Coordination | Giulia Solinas

Bringing all together: The key building blocks of watsonx Orchestrate

Sat, 16 May 2026 00:00:00 +0000

From Code to Collaboration: Mastering the watsonx Orchestrate Agent Development Kit (ADK)

This blog post summarizes the key concepts and hands-on learning from the watsonx Orchestrate Agent Development Kit (ADK) curriculum—covering the development lifecycle from tool creation to advanced agent collaboration, knowledge integration, and prompt optimization.

Throughout the past three blogs, we’ve explored the architectural foundations, best practices, and tooling that make watsonx Orchestrate a powerful platform for enterprise AI agents. Now, let’s add few more concepts and bring it all together.

The IBM watsonx Orchestrate Agent Development Kit (ADK) is a powerful toolset for building, testing, and deploying robust AI agents tailored for enterprise workflows. This learning path moves beyond basic development to cover critical topics like agent collaboration, knowledge grounding, and optimization with Copilot.

Building Blocks: Agents and Tools

The foundation of the watsonx Orchestrate ecosystem lies in two core concepts: Agents and Tools.

Agents

The primary intelligent entity, defined using YAML or JSON files. An agent’s configuration dictates its behavior, the LLM it uses, and the tools it can access. The YAML file has the following structure.

Tools

The reusable functions that expose specific business capabilities to the agent, allowing it to take action. Tools can be created from two main formats:

Python Functions: Directly written in Python, they are imported using a command like orchestrate tools import -k python -f my-tool.py -r requirements.txt -a app1 -a app2. Note that the wx orchestrate framework is moving towards importing tools’ packages instead of single tools to improve the utilization of runtime capacity while calling the deployed tool.
OpenAPI Specification: A standard way to define REST APIs. The agent uses the structure of the OpenAPI document, specifically the paths element to identify endpoints and the servers element to find the API’s base URLs. The import command is orchestrate tools import -k openapi.

Agents can access tools also through local MCP server packages hosted on the local machine and connections to external MCP server. Here the changes in the documentation are very dynamic and it is better to refer to the official wx orchestrate ADK developer webpage for references.

Tools are secured using Connections, which handle authentication details like API keys or user credentials.

Grounding Agents with Knowledge

For agents to answer informational or history-based questions accurately, they need access to a Knowledge Base, leveraging the Retrieval-Augmented Generation (RAG) pattern.

A Knowledge Base is defined using YAML or JSON and populated with relevant documents. Two key parameters govern the accuracy of the responses:

retrieval_confidence_threshold: This controls the minimum confidence required for retrieved documents to be considered relevant to the user’s query. Documents below this threshold are ignored.
Response Confidence: If the Large Language Model’s (LLM) final generated answer falls below this set threshold, the agent will refuse to answer and returns a default ‘I don’t know’ response to prevent hallucinations and maintain factual integrity.

Advanced Architectures: Collaboration and Workflow

For complex business processes, single agents are replaced by a system of collaborating agents:

Collaborating Agents: Specialized agents (e.g., a Quoter Agent and a Monthly Payment Agent) work together to achieve a multi-step goal.
Manager Agent: The manager agent sits at the top, and its primary role is to coordinate the collaborating agents. It uses its own LLM reasoning to decide which agent to call, in what sequence, and how to combine their outputs.

This collaborative architecture is the practical implementation of the Supervisor/Manager pattern we discussed in earlier posts—a testament to how architectural concepts translate into working code.

Development, Debugging, and Optimization

The ADK streamlines the development lifecycle with powerful tooling:

Area	Tool/Concept	Key Function	CLI Command
Local Testing	Developer Edition Chat UI	Interactive environment to test agents locally.	`orchestrate chat start`
Optimization	Agent Builder	AI agent builder for prompt-tuning to improve prompt clarity and agent behavior. It requests invocation examples to understand and refine the agent’s logic.	`orchestrate agents ai-builder create`
Observability	Langfuse	Integrated stack that captures and visualizes agent reasoning traces (tool calls, inputs, outputs). Essential for debugging the agent’s decision-making process.	(Integrated with server trace)

Conclusion: Bringing It All Together

By combining the structural power of tool definition, the informational grounding of knowledge bases, the architectural flexibility of collaboration, and the optimization capabilities of Copilot and Langfuse, developers can build reliable, enterprise-grade AI agents with the watsonx Orchestrate ADK.

Series Summary: Key Takeaways

Over this four-part series, we’ve covered the essential elements of building production-ready agents with watsonx Orchestrate:

Architectural Foundation (Part 1): The hybrid pro-code/low-code approach—using the ADK for complex logic and the Agent Builder for orchestration and speed.
Best Practices (Part 2): Multi-Agent Orchestration with the Supervisor/Manager pattern, writing clear agent descriptions, and choosing the right tool type (Python vs. MCP).
Tooling and APIs (Part 3): Mastering the ADK CLI commands, understanding MCP security considerations, and working with the core API parameters (agent_id and thread_id).
Implementation (Part 4): The ADK development lifecycle—defining agents and tools, grounding with knowledge bases, implementing collaborative architectures, and optimizing with AI Agent Builder and Langfuse.

These concepts form a cohesive framework for building enterprise-grade AI agents that scale. The difference between a proof-of-concept and a production-ready agent lies not in any single technique, but in how these elements work together as a system.

Start building. Start iterating. And most importantly—start orchestrating.

My notes about the watsonx Orchestrate Agent Development Kit (ADK) and Model Context Protocol

Fri, 15 May 2026 00:00:00 +0000

Elevate Your AI Engineering: Mastering watsonx Orchestrate Tooling and APIs

In Parts 1 and 2, I covered the architectural foundations and best practices for building production-ready agents. Now it’s time to get hands-on with the tooling and APIs that power your watsonx Orchestrate implementations.

For AI engineers looking to extend the capabilities of their agents, this installment provides the foundational knowledge necessary to integrate custom tools and manage the environment using powerful command-line tools and direct API calls. It is also

The Agent Developer Kit (ADK): The Command Center

The ADK is the essential CLI for managing your watsonx Orchestrate environments and assets. Mastering a few key commands allows you to seamlessly switch between environments (for example, ), as well as manage the tools your agents use.

Essential Commands

orchestrate env list & orchestrate env activate: Essential for listing all configured environments and activating a specific one (e.g., a local development instance or a SaaS tenant).
orchestrate agents import -f [agent_name].yaml to import the agent into the environment.
orchestrate tools import & orchestrate tools list: The standardized way to register new tools into your environment and verify their successful import.
orchestrate connections remove: Used to safely unregister external service connections from your active tenant.
orchestrate knowledge-bases status: Provides vital diagnostic information on the content and state of your retrieval-augmented generation (RAG) knowledge bases.

These commands form the backbone of your day-to-day workflow. Whether you’re deploying to production or debugging in development, the ADK is your interface to the platform.

Standardizing Tools with the Model Context Protocol (MCP)

To enable agents to use external applications, watsonx Orchestrate utilizes the Model Context Protocol (MCP), which relies on an MCP server as a standardized intermediary.

Why MCP Matters

The core benefit of MCP is providing a standardized interface for watsonx Orchestrate, allowing various external services to be integrated with consistent simplicity. Instead of building custom integrations for every service, MCP gives you a uniform approach.

Here you can find an insightful reading if you want to compare this approach with Anthropics’s guidelines to build . I believe learnings from one platform can be applied to other contexts, too.

Security Considerations

MCP servers typically require environment variables at startup to initialize correctly with necessary authentication keys (API keys) and endpoints. However, there’s a critical security consideration: without proper sandboxing, running an MCP server poses a severe security risk of arbitrary code execution. This risk must be mitigated before deploying to production.

API Essentials for Conversational Flows

When building custom user interfaces or services, direct interaction with the watsonx Orchestrate API is required. Two identifiers are paramount for managing conversation state:

The Critical API Parameters

agent_id: Must be included in the API request to direct the conversation to the specific agent instance that is configured with the right skills and tools.
thread_id: Used to maintain and reference the context of a specific conversation. Including this ID in subsequent calls ensures the agent has access to the full conversation history for coherent, multi-turn dialogue.

These two identifiers are the keys to building seamless, context-aware conversational experiences in your custom applications.

Key Takeaways

Master the ADK—it’s your command center for environment management, tool registration, and diagnostics.
Embrace MCP for standardized integrations, but never neglect security—sandbox your MCP servers.
Understand the API fundamentals—agent_id and thread_id are essential for building custom conversational interfaces.

With these tooling and API skills in your toolkit, we’re equipped to move beyond conceptual design into full implementation. The foundation is set; the execution begins.

Mastering Multi-Agent Orchestration and Tool Selection in watsonx Orchestrate

Thu, 14 May 2026 00:00:00 +0000

Mastering Multi-Agent Orchestration and Tool Selection in watsonx Orchestrate

In the first blog, we explored the foundational architectural choices: when to use the Agent Development Kit (ADK) for pro-code development and when to leverage the Agent Builder for speed. Now, let’s dive deeper into two critical best practices that separate agentic design from AI assistants and more traditional chatbot solution: Multi-Agent Orchestration and Agent Descriptions.

Multi-Agent Orchestration: The Supervisor/Manager Pattern

If there’s one architectural pattern I had to internalize for watsonx Orchestrate, it’s the Supervisor/Manager agent topology. This approach leverages the concept of Multi-Agent Systems—a core capability that transforms how complex workflows are handled.

Why Single Agents Fail at Scale

Do not get me wrong, single agents have been there for a while and can still be deployed with success. Furthermore, single agents that handle a sequence of tasks in parallel can be more performing that a crew of agents accomplishing the same tasks in parallel but without real coordination –see for example, from Google.

However a single agent hits a wall when performing a very complex job that would require parallel tasks and multiple tools, even if they are supported by very powerful, state-of-the-art models. When multiple tools have similar names or work with the same data, the LLM inside a single, large agent can struggle with tool routing—the process of selecting the correct tool for a given step. The more tools you pile into one agent, the more overwhelmed the model’s reasoning becomes. The result? Incorrect routing, failed tasks, and frustrated users.

There is now quite a lot of evidence on this topic, suggesting that the maximum number of tools an agent should handle should be larger than eight. Allen Chen, distinguished engineer at IBM, has written a great article about it on .

The solution to this problem is thinking modular and designing a multi-agent framework, in which each agent covers a specialized task with its associated tools and connects loosely with the other agents. The idea is to turn our implementations from monolith agents to lightweight, decentralized yet connected agents. I find multi-agent coordination a very fascinating topic and I recommend reading this by Grötschla and co-authors to know more about forms of coordination design.

One of those modes is indeed the “Supervisor/Manager” patter that is at the core of watsonx Orchestrate. Its foundational idea is to have an orchestrating agent taking a overview of the tasks and coordination among its collaborators. Collaborators can pass information among each other and run tasks in parallel or in sequence. Yet, the ultimate check resides to the orchestrator.

The Modular Solution

By decomposing a complex task into smaller, specialized agents (e.g., a “Leave Balance Agent” and a “Submission Agent”), you dramatically simplify the decision space. Each sub-agent is given a small, specific set of tools, making its reasoning and selection process highly accurate.

This architecture assigns specialized roles to agents, allowing them to excel at their dedicated tasks. A supervising agent (the manager) then handles the overall complexity by delegating the user’s request to the correct sequence of specialized agents—the orchestration step.

This modular, collaborative approach is the best practice for complex workflows in watsonx Orchestrate.

Agent Descriptions: Writing for the Model

Here’s a truth that surprises many developers: the agent description isn’t for humans—it’s primarily for the AI.

The description is critically important because it is used by the underlying Large Language Model (LLM) within watsonx Orchestrate to perform reasoning and routing. The LLM reads the description in a YAML file to determine the agent’s capabilities and decide if it should be invoked to handle a user’s request.

What Makes a Great Description

A well-crafted description should clearly state:

Purpose: What the agent does
Inputs: The type of information it needs
Outputs: What it returns
Constraints: Any key limitations or special instructions

This information is packed in the YAML file with this structure,for a customer service agent running on ServiceNow.

spec_version: v1
style: default
name: service_now_agent
llm: groq/openai/gpt-oss-120b
description: |
 You are an agent who specializes in customer care for a large healthcare institution. You should be compassionate
 to the user.

 You are able to help help a user create tickets in service now for processing by a human later. Examples of when to do
 do this include for adding members to plans or helping users with documentation.
instructions: |
 If a user is having difficulty either generating benefits documents or adding additional members to their plan,
 create a new incident for our support team using service_now_create_incident tool. Be compassionate about the user
 facing difficulty.

 The output of get_service_now_incidents should be formatted as a github style formatted markdown table.
collaborators: []
tools:
 - create_service_now_incident
 - get_my_service_now_incidents
 - get_service_now_incident_by_number

Here some notes about this example:

The agent’s style is set as default, which is the baseline agentic reasoning mode for native agents in wx orchestrate. It can be changed into the ReAct style.
The agent is a stand alone one and does not have collaborators. They can be added with additional YAML files stored in the project’s workspace and loaded in the environment. You do not need to setup an A2A protocol to let them sync and collaborate, unless we have imported third-party agents that need to coordinate with native ones.
There is a list of tools, typically Python files or MCP integration.

Clarity Over Complexity

Using clear, non-technical language ensures the LLM interprets the agent’s role correctly, which in turn leads to a better user experience. While developers also read the description, think of it primarily as a prompt for the AI’s logic—and AI needs unambiguous instructions.

Avoid:

Technical jargon that the LLM won’t recognize
Internal acronyms without context
Vague or overly brief descriptions

These introduce ambiguity and increase the risk of incorrect routing decisions. When in doubt, err on the side of clarity. Ambiguity is poison.

Choosing the Right Tool: Python vs. MCP

We’ve touched on the role of tools before before, but this topic deserves a deeper explanation. In watsonx Orchestrate, as in the other agentic design frameworks, tools can be developed through Python code or MCP integrations. The question is when do you use Python tools versus MCP tools?

Python Tools (via ADK)

The Agent Development Kit (ADK) allows developers to create custom Python tools. Python is the ideal choice when you need:

Complex conditional logic (business rules)
Data manipulation and calculations
Handling accrual rates, rollovers, and time-based calculations
Any custom computational logic unique to your business

For example, calculating remaining vacation days based on custom seniority rules? That requires Python.

MCP Tools (Model Context Protocol)

MCP tools are excellent for integrating with existing systems—typically via OpenAPI specifications. They’re best suited for:

Calling standard REST APIs
Simple, form-based workflows
Connecting to external services

What they lack is the ability to embed complex, custom computational logic. If you need to transform data in unique ways or implement business rules that don’t exist in an external service, reach for Python.

Key Takeaways

Decompose complex workflows into specialized agents to reduce the LLM’s cognitive load and improve routing accuracy.
Write descriptions for the AI first—clear, unambiguous descriptions are the difference between reliable routing and failed execution.
Choose Python for logic, MCP for integration—understand the strength of each tool type and use them appropriately.

These are my learning in trying to discover and put in practice the best practices to build multi-agents. The offers several tips on how to write good agent’s descriptions, and offers an extensive list of dos and don’ts. Check it and have fun.

How Do Design-Thinking and Agents' Roles Matter to Generate Predictive Knowledge in Organizations?

Mon, 02 Oct 2023 00:00:00 +0000

Competition, formal governance and trust in alliances An experimental study

Sat, 01 Oct 2022 00:00:00 +0000

Cui Bono Cui Malo? Contractual Complementarity for Rent Appropriation in Strategic Outsourcing

Wed, 01 Apr 2020 00:00:00 +0000

Framing Technology Licensing

Wed, 15 Feb 2017 00:00:00 +0000