How ibm/ibm-watsonx-orchestrate-adk works
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)