# ibm/ibm-watsonx-orchestrate-adk architecture

> Architecture diagram of the GitHub repository ibm/ibm-watsonx-orchestrate-adk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ibm/ibm-watsonx-orchestrate-adk
- Repository: https://github.com/ibm/ibm-watsonx-orchestrate-adk

## Overview

##### Project type and purpose
- This is a Python-based SDK and CLI tool (“Agent Development Kit” or ADK) for building, testing, and deploying conversational agents on IBM watsonx Orchestrate.
- Key deliverables:
- A command-line interface (`orchestrate` CLI)
- A Python library (`src/ibm_watsonx_orchestrate`) that exposes modules for agent construction, flow building, runtime execution, and a REST API client.
- Local developer environment artifacts (Docker Compose files, shell scripts) for running a “Developer Edition” of the Orchestrate server.

##### File structure
- Top-level directories:
- `.sps` – CI/CD, containerization, testing scripts
- `docs` / `_docs` – documentation & Docker recommendations
- `examples` – dozens of sample agents and flows, organized by capability (agent_builder, flow_builder, evaluations)
- `src/ibm_watsonx_orchestrate` – core library subdivided into:
– `agent_builder` (builds YAML/JSON agent definitions from tools, connections, knowledge bases, model policies)
– `flow_builder` (constructs executable flows)
– `cli` (Typer-based commands, each with a controller)
– `client` (HTTP wrappers for Orchestrate services: agents, connections, models, knowledge bases, copilot, toolkit, analytics)
– `run` (entrypoints for executing flows locally)
– `docker` (compose files, env templates, startup scripts)
– `utils` (logging, exception types, generic helpers)
- `tests` – unit and integration tests aligned with each subpackage

##### Cross-reference the README
- Confirms:
- Purpose (agent & tool integration, local development vs. production)
- CLI surface area (environment, agents, tools, knowledge bases, channels, chat UI, server management)
- Developer Edition prerequisites (Docker, resources, recommended settings)

##### Components
a. Main components
– User / Developer (CLI user)
– `orchestrate` CLI front-end (Typer commands)
– CLI Controllers & Commands layer
– Python SDK modules:
- Agent Builder (connections, KBs, toolkits, models → agent definitions)
- Flow Builder (nodes, events, decorators → flow graphs)
- Runtime (`run` module)
- Client (REST API adapters)
- Utils & Logging
– Local Developer Edition cluster (Docker Compose services):
- Orchestrate Server API
- PostgreSQL / Redis
- Builder service
– Remote Orchestrate cloud service (production endpoint)
– External services: LLM providers, Langfuse telemetry, Document Processing

b. Relationships & interactions
1. Developer invokes `orchestrate` CLI →
2. CLI parses command → routes to specific controller →
3. Controller uses:
- SDK Client to call Orchestrate Server REST endpoints (local or remote)
- Agent Builder / Flow Builder modules to generate payloads for import
- Runtime (`run`) to execute flows locally against Developer Edition
4. SDK Client issues HTTP calls to:
- Local Developer Edition (Docker Compose services)
- Orchestrate Cloud API (if env activated for prod)
5. Developer Edition services coordinate: DB, Redis, builder, service bus to persist agents, flows, telemetry

c. Architectural patterns & principles
– Modular layering (CLI → controllers → domain modules → client adapters)
– Adapter pattern for `client` (uniform interface over HTTP)
– Builder pattern in agent_builder & flow_builder packages
– Separation of concerns: building vs. executing vs. deploying
– Configuration-as-code (YAML agent definitions, JSON flow files)

d. Key technologies & libraries
– Python 3.11–3.13, Typer (CLI), HTTP client (httpx)
– Docker Compose for local Developer Edition
– RESTful API calls to Watsonx Orchestrate services
– Optional external telemetry (Langfuse) and IBM Document Understanding

##### Diagramming conventions
- CLI → Controllers → Modules → Client → Orchestrate Server
- Modules → File system (YAML/JSON definitions)
- Green for user-facing (CLI)
- Blue for internal modules (agent_builder, flow_builder, run)
- Orange for client & HTTP layer
- Purple for runtime environment (Docker Compose cluster & cloud API)
- Rectangles for processes/modules
- Clouds for remote services (Watsonx Orchestrate Cloud, LLM providers)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-Facing Layer
    Developer["Developer / User"]:::user -->|invokes| CLI["orchestrate CLI"]:::cli
    click CLI "https://github.com/ibm/ibm-watsonx-orchestrate-adk/blob/main/src/ibm_watsonx_orchestrate/cli/main.py"

    subgraph "CLI Frontend"
        direction TB
        Config["CLI Configuration"]:::cli --> InitHelper["CLI Init Helper"]:::cli
        Controllers["CLI Controllers & Commands"]:::cli
        CLI --> Config
        CLI --> Controllers
        click Config "https://github.com/ibm/ibm-watsonx-orchestrate-adk/blob/main/src/ibm_watsonx_orchestrate/cli/config.py"
        click InitHelper "https://github.com/ibm/ibm-watsonx-orchestrate-adk/blob/main/src/ibm_watsonx_orchestrate/cli/init_helper.py"
        click Controllers "https://github.com/ibm/ibm-watsonx-orchestrate-adk/tree/main/src/ibm_watsonx_orchestrate/cli/commands/"
    end

    subgraph "Domain Modules"
        direction TB
        AgentBuilder["Agent Builder"]:::module
        FlowBuilder["Flow Builder"]:::module
        Runtime["Runtime Execution"]:::module
        Utils["Utils & Logging"]:::module
        Controllers --> AgentBuilder
        Controllers --> FlowBuilder
        Controllers --> Runtime
        Controllers --> Utils
        click AgentBuilder "https://github.com/ibm/ibm-watsonx-orchestrate-adk/tree/main/src/ibm_watsonx_orchestrate/agent_builder/"
        click FlowBuilder "https://github.com/ibm/ibm-watsonx-orchestrate-adk/tree/main/src/ibm_watsonx_orchestrate/flow_builder/"
        click Runtime "https://github.com/ibm/ibm-watsonx-orchestrate-adk/tree/main/src/ibm_watsonx_orchestrate/run/"
        click Utils "https://github.com/ibm/ibm-watsonx-orchestrate-adk/tree/main/src/ibm_watsonx_orchestrate/utils/"
    end

    Filesystem["YAML/JSON Definitions"]:::datastore
    AgentBuilder -->|writes definitions| Filesystem
    FlowBuilder -->|writes definitions| Filesystem

    subgraph "Client Layer"
        direction TB
        Client["REST API Client"]:::client
        Controllers --> Client
        click Client "https://github.com/ibm/ibm-watsonx-orchestrate-adk/tree/main/src/ibm_watsonx_orchestrate/client/"
    end

    subgraph "Deployment Targets"
        direction TB

        subgraph "Local Developer Edition (Docker Compose)" 
            direction TB
            Server["Orchestrate Server API"]:::env
            BuilderSvc["Builder Service"]:::env
            Postgres["PostgreSQL"]:::datastore
            Redis["Redis"]:::datastore
            DockerFiles["Docker Artifacts"]:::env
            Client --> Server
            Server --> Postgres
            Server --> Redis
            Server --> BuilderSvc
            click DockerFiles "https://github.com/ibm/ibm-watsonx-orchestrate-adk/tree/main/src/ibm_watsonx_orchestrate/docker/"
        end

        subgraph "Remote Cloud Service"
            direction TB
            CloudAPI["Watsonx Orchestrate Cloud API"]:::env
            LLM["LLM Providers"]:::external
            Telemetry["Langfuse Telemetry"]:::external
            DocProc["Document Processing"]:::external
            Client --> CloudAPI
            CloudAPI --> LLM
            CloudAPI --> Telemetry
            CloudAPI --> DocProc
        end
    end

    %% Additional artifacts
    Developer -->|views examples| Examples["Sample Agents & Flows"]:::external
    Examples -->|uses| AgentBuilder
    click Examples "https://github.com/ibm/ibm-watsonx-orchestrate-adk/tree/main/examples/"

    Developer -->|CI/CD actions| SPS["CI/CD & Testing Scripts"]:::external
    click SPS "https://github.com/ibm/ibm-watsonx-orchestrate-adk/tree/main/.sps/"

    %% Styles
    classDef user fill:#8FBC8F,stroke:#333,stroke-width:1px;
    classDef cli fill:#98FB98,stroke:#333,stroke-width:1px;
    classDef module fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef env fill:#D8BFD8,stroke:#333,stroke-width:1px;
    classDef datastore fill:#9370DB,stroke:#333,stroke-width:1px;
    classDef external fill:#F0E68C,stroke:#333,stroke-width:1px;
```
