Agentic AI | 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.

Building Production-Ready Agents with watsonx Orchestrate: A Pro-Code/Low-Code Architectural Guide

Wed, 13 May 2026 00:00:00 +0000

Building Production-Ready Agents with IBM watsonx Orchestrate: A Pro-Code/Low-Code Architectural Guide

My journey with watsonx Orchestrate began at the Agentic AI Academy in Paris in March 2025 —a pivotal event that shaped my understanding of the product’s development direction. Since then, I tested it in demos and in sandbox projects. I decided to write up this series of blog to document (for myself) my journey and understanding of the framework. I want to start with a first clear lesson: the true power of this platform comes from knowing when to leverage code and when to embrace the low-code interface.

It’s not an “either/or” decision—it’s a calculated architectural synthesis that, when done right, delivers both the flexibility of custom development and the speed of visual assembly.

The Architectural Synthesis: Pro-Code Agility Meets Low-Code Speed

As an AI engineer, I’ve learned that the most effective watsonx Orchestrate implementations blend two distinct approaches. Here’s how to think about each and when to use them.

1. The Pro-Code Anchor: The Agent Development Kit (ADK)

When you encounter complex, stateful, or computationally intensive tasks—the core business logic—you must reach for the Agent Development Kit (ADK). This is your Pro-Code First zone.

Why? Because calculating something like prorated vacation days based on custom seniority rules requires the flexibility and computational power of a Python tool. Simple, low-code API connectors (like MCP) are excellent for making a standard REST call, but they fall short when you need deep, custom programmatic logic and complex data manipulation. The ADK ensures your high-value agents are built on a solid foundation of reliable code.

2. The Low-Code Accelerator: The Agent Builder

Once your custom logic is secured in a Python tool via the ADK, you pivot to the Agent Builder for orchestration and speed. This is the Low-Code/Quick Setup environment.

The Builder excels at two things: assembly and observability. It’s the fastest way to integrate knowledge bases, assemble a workflow from various skills, and, crucially, to monitor your agents. Features like Knowledge analytics and trace details provide a vital “glass cockpit” for RAG performance, allowing you to debug and refine your agent’s knowledge retrieval without diving back into custom code. It acts as the high-speed glue and the maintenance dashboard.

3. Modularity is Precision: Process Decomposition

The most critical architectural decision for scalability is Process Decomposition, and it’s all about managing the Large Language Model’s (LLM’s) cognitive load.

A single, monolithic agent attempting to handle an entire complex workflow (e.g., “submit days off”) may succumb to tool-routing failure. The LLM gets overwhelmed trying to decide between five different tools at any given step.

The solution is the Supervisor/Manager agent topology. We break that complex workflow into smaller, single-purpose, modular agents (“Check Balance,” “Submit Request,” “Confirm Leave”). The main Manager agent now only has one job: delegate to the correct, highly specialized sub-agent. This approach drastically simplifies the LLM’s reasoning and tool-routing decision, leading to a measurable boost in overall execution accuracy and scalability.

4. The LLM’s Instruction Manual: Routing Clarity

Finally, all this architectural precision hinges on one seemingly simple detail: Agent descriptions.

The LLM doesn’t “read your code”; it reads the description of your tool or agent to decide if it’s the right fit for the user’s intent. Therefore, this description must serve as a crystal-clear contract: non-technical, precise about the agent’s purpose, and explicit about its required inputs and expected outputs. Ambiguity here is poison. If the documentation is vague, the LLM’s planning function falters, resulting in unreliable autonomous execution—the agent picks the wrong tool, and the user gets a bad experience. Clarity in documentation is paramount to operational reliability.

Key Takeaways

Building production-ready agents with watsonx Orchestrate requires a deliberate architectural approach:

Embrace the hybrid model: Use the ADK for complex, custom logic and the Agent Builder for orchestration and monitoring.
Decompose for scale: Break monolithic workflows into specialized, modular agents to reduce cognitive load on the LLM.
Write for the model: Treat agent descriptions as contracts—clear, precise, and unambiguous.

The difference between a working agent and a reliable agent often comes down to these architectural choices. My goal is to master them to build agents that scale.

Note

This is the first of four blogs I wrote to crystallize my understanding of a framework—watsonx Orchestrate—that I use daily. There are many other frameworks for building agents, and IBM watsonx Orchestrate shares some commonalities with them, including Python-based tooling, MCP integrations, and agentic design, among others. Still, each framework has its own peculiarities. If you find this useful, I hope you’ll continue reading the rest of the series.

Agentic AI

Fri, 27 Mar 2026 00:00:00 +0000

Agentic AI

Building Smarter Teams, One Agent at a Time

I specialize in designing and deploying autonomous agent ecosystems that turn complex workflows into seamless, self‑organizing teams. Using IBM watsonx Orchestrate, I assembled a sandbox crew of business analysts who collaborate in real‑time to surface users stories, automate the identification of process requirements, and accelerate decision-making.

What makes me excited about this project: high degree of specialization, modularity, possibility to scale in tasks, smaller models for each specialized agents, ReAcT capabiliites, orchestration by design.

At the same time, I explored the Google SDK for Agent Building and crafted a sandbox project—a virtual podcast crew that researches, scripts, and narrates fintech news on‑the‑fly. The agents coordinate research, fact‑checking, and voice synthesis, delivering a polished, up‑to‑date podcast episode without human intervention.

What I learned from this project: each agent is supported by a different foundation model like LLM for text creation, multi-modal models for information parsing (including imaging and IDP capabilities), and text-to-speech, each packed in diffrent agents as modular components.

Together, these experiences showcase my ability to:

Design modular agent architectures that integrate with existing data and NLP pipelines.
Orchestrate multi‑agent collaboration through clear role‑based interactions.

[NOTE!] My next chapter here in this area is AgentOps.

Do you want to co-develop with me? Just reach out.