Blog | Giulia Solinas

Building Agents in Bob with a Software Spec Driven Approach

Fri, 03 Jul 2026 00:00:00 +0000

Building Agents in Bob with a Software Spec Driven Approach

Agentic systems become easier to build, review, and evolve when they are treated like software products instead of clever prompts. Bob’s dedicated skills support exactly that style of work: start with business intent, turn it into explicit specifications, generate implementation artifacts, and then analyze the result against the design.

In this post, I describe how to use Bob and four dedicated skills as an end-to-end, spec driven workflow for creating watsonx Orchestrate (wxO) agentic solutions.

Why Spec Driven Agent Development Matters

Traditional agent building often starts with a prompt and quickly jumps into tools, flows, and integrations. That can work for experiments, but it becomes fragile when the solution has real business logic, compliance expectations, system integrations, or multiple collaborators.

A software spec driven approach flips the sequence:

Define the business problem before choosing the implementation.
Produce architecture and process specifications before generating code.
Keep business rules legible in Standard Operating Procedures (SOPs).
Generate wxO artifacts from the agreed specification.
Analyze the implementation and feed findings back into the next iteration.

In this framework, the specification is not a bulk of documentation that none reads and gets under the deck of work to be done for a client. It is the contract that the developer signs with the agent.

The Bob Skill Pipeline

We can bring into the Bob’s workspace (global or at the project level) four specialized skills that form a complete pipeline for designing, building, and auditing wxO agentic solutions:

Skill	Primary Question	Output
`solution-architect`	What should we build, and why?	Solution overview, architecture, and implementation plan
`sop-builder`	How should the business process work?	Structured SOP with process flow, data needs, rules, and decisions
`wxo-builder`	How do we turn the spec into wxO artifacts?	Importable wxO project with agents, tools, flows, connections, and scripts
`wxo-analyzer`	Does the implementation match expectations?	Documentation and audit reports for an existing wxO project

The skills are avaialble in the GitHub repository for . We can clone the repo and import the folders into our project.

The important pattern is that each skill produces the input for the next one. That makes the workflow traceable from business problem to deployed solution.

Step 1: Start with `solution-architect`

Use solution-architect when you have a business problem or use case, but no technical design yet.

Example prompt:

I need an AI agent that processes invoices from a shared mailbox, extracts invoice data, validates it against vendor records, and prepares a SalesForce update.

The goal at this stage is not to write code. The goal is to create a shared understanding of the solution.

The agent using the solution-architect skills should produce three key documents:

Document	Purpose
Solution Overview	Captures the executive summary, business context, problem statement, and agent requirements
Solution Architecture	Describes components, integrations, data flow, security, and architecture diagrams
Implementation Plan	Breaks the work into phases, assumptions, constraints, and SOP candidates

The implementation plan is especially important because it decomposes the solution into business processes that can be specified independently.

Step 2: Convert Architecture into SOPs with `sop-builder` skills

Use sop-builder skills when you have an architecture document, workflow description, BPMN model, Langflow export, n8n export, or any other process-oriented input.

This skill turns design intent into a plain-language Standard Operating Procedure. That SOP becomes the specification for implementation.

A good SOP includes:

Business process flow diagrams
Business context and problem statement
Input, processing, and output data requirements
Business rules and decision points
Integration expectations
Error handling and escalation behavior

This is where the spec driven approach becomes practical. Instead of embedding business logic directly in generated tools or agent instructions, you first make that logic visible and reviewable.

Example prompt:

Build the SOP for the invoice extraction and validation flow from the implementation plan.

For larger solutions, a good option can be creating one SOP per major flow. A single monolithic SOP usually hides important decisions and makes generation harder to review.

Step 3: Generate the wxO Solution with `wxo-builder` skills

Use Bob with wxo-builder skills when you have an SOP or a very clear build prompt and want actual watsonx Orchestrate artifacts.

This is the point where Bob moves from specification into implementation. Given a strong SOP, wxo-builder can generate an importable wxO project structure such as:

my_solution/
 agents/
 my_agent.yaml
 tools/
 my_tool.py
 my_flow.py
 connections/
 my_connection.yaml
 main_flow.py
 import-all.sh

The agent with the builder skills can create:

Native wxO agents
Python tools with correct decorator and docstring conventions
Flow Builder patterns for document processing, user activity, conditional logic, and multi-agent workflows
Knowledge base configurations
Connection YAML files for credential management
Import scripts for repeatable setup

The quality of the generated solution depends heavily on the quality of the SOP. If the SOP defines the business rules, data contracts, exception paths, and integration behavior, the builder has fewer assumptions to invent.

Example prompt:

Generate the wxO solution from this SOP. Create the agent configuration, required Python tools, connection specs, and import script.

This step should usually happen in Agent mode because it writes project files. Note that you can further empower the agent mode by giving MCP connections to the Orchestrate documentation through the wx orchestrate ADK. However, a downside of MCP connections is larger token consumptions. An alternative method would be using the CLI skills approach by Floring Manila and Niklas Heidoff as explained in this .

Step 4: Audit and Document with `wxo-analyzer` skills

Use wxo-analyzerskills when you have an existing wxO project and want to understand, document, or audit it.

The Agent with the analyzer skills should produce a three-report documentation set:

Report	Purpose
Solution Overview	Summarizes architecture, components, and file structure
Agent Analysis	Breaks down each agent, its tools, collaborators, instructions, and LLM settings
Tools and Components	Reviews flows, Python tools, connections, knowledge bases, and implementation patterns

This closes the loop. After generating or modifying a solution, analyze it and compare the reports against the original architecture and SOPs.

Useful review questions include:

Does the generated agent follow the intended process?
Are business rules represented explicitly?
Are credentials handled through connections instead of hardcoded values?
Are error paths and escalation paths implemented?
Are tools too large, too ambiguous, or missing validation?
Does the implementation introduce behavior that was not in the SOP?

The output of the step obtained with wxo-analyzer skills can feed back into the tasks for the sop-builder or wxo-builder for refinement.

A Practical End-to-End Flow

Here is the full workflow in one sequence:

Business problem
 -> solution-architect
 -> Solution overview, architecture, implementation plan
 -> sop-builder
 -> Standard Operating Procedure
 -> wxo-builder
 -> Importable wxO project
 -> wxo-analyzer
 -> Audit reports and improvement backlog

Best Practices for Spec Driven Agent Work

Start with architecture for non-trivial use cases. If the solution touches multiple systems, users, approval steps, or data sources, begin with solution-architect skills.

Keep SOPs focused. One SOP per flow makes the specification easier to review and easier for wxo-builder skills to implement cleanly.

Treat the SOP as the contract. The SOP should define data inputs, outputs, business rules, decisions, and exceptions clearly enough that implementation choices can be checked against it.

Build from reviewed specs. Do not rush from a vague idea to generated code. The fastest path is usually to clarify the spec first.

Analyze after building. Call the agent with the wxo-analyzer skills after generation or major changes so the project can be reviewed for missing error handling, hardcoded credentials, oversized flows, or behavior that drifted from the SOP.

Iterate deliberately. When the agent finds gaps, update the SOP or architecture first when the gap is conceptual. Update the wxO implementation when the spec is right but the build needs refinement.

What This Changes

Bob’s dedicated skills make agent development like professional software delivery.

The workflow creates a chain of accountability:

Business requirements explain why the agent exists.
Architecture explains how the solution should fit together.
SOPs explain how the work should happen.
wxO artifacts implement the agreed process.
Analyzer reports show what was actually built.

That chain is what makes agentic systems deliverable and maintainable. It gives teams a way to discuss requirements, review logic, generate implementation, and audit the result without losing the thread between business intent and technical behavior.

When used together, solution-architect, sop-builder, wxo-builder, and wxo-analyzer skills turn Bob into a spec driven agent factory: one that can move from idea to implementation while keeping the reasoning visible at every step.

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.

AI for Science

Tue, 21 Jan 2025 00:00:00 +0000

AI‑Enhanced Science: How Generative Models Are Accelerating Discovery, Literature Mining, and Idea Generation
Originally featured on the 

1. AI as a “Hilbert” for Equation Discovery

The most eye‑catching advance comes from the AI‑Hilbert algorithm, whose recent Nature Communications paper demonstrates that multivariate polynomial generators can invent new scientific laws from existing theory and data.

Why it matters

Data‑scarce domains (e.g., high‑energy physics, climate modeling) often lack clean, labeled datasets. Traditional symbolic regression struggles when the search space is huge and the underlying dynamics are noisy.
AI‑Hilbert expands the search space by coupling continuous polynomial families with a Bayesian‑style pruning of implausible terms, delivering equations that are both interpretable and generalizable.

Bottom line – AI can now act as a “virtual mathematician,” surfacing equations that push the frontier of scientific theory while keeping the output human‑readable and testable.

2. Smarter Literature Mining with SciLitLLM

Reading the literature is the backbone of any research program, yet the semantic gap between disciplines hampers existing LLMs. SciLitLLM, a family of models built on a continual‑pre‑training + supervised fine‑tuning pipeline, directly addresses this problem.

Key capabilities

Domain‑aware embeddings that capture jargon from chemistry, biology, nanomaterials, etc., without catastrophic forgetting.
Ability to extract targeted facts (e.g., “list all catalysts reported with >95 % yield under 25 °C”) and produce concise, citation‑ready summaries.
Human‑in‑the‑loop validation layer: researchers verify that hallucinations are filtered before conclusions are drawn.

Limitations – The model is powerful but not a substitute for critical appraisal; it still requires domain experts to curate outputs and guard against subtle misinterpretations.

3. LLM‑Generated Research Ideas (and Their Unexpected Novelty)

A Stanford‑led pre‑print experiment pitted human‑only idea generation against LLM‑generated proposals that were subsequently re‑ranked by expert reviewers.

Result: The top‑ranked LLM ideas were judged significantly more novel than those produced solely by the human panel, even though feasibility scores were comparable.
Implication: Large language models can break cognitive lock‑in, surfacing unconventional connections that traditional pipelines often overlook.
Caveats: Novelty does not guarantee practicality; further validation and feasibility modeling are required before moving to grant proposals or experimental testing.

4. The Common Thread & What Still Needs to Happen

All three examples share a common prerequisite: they are research‑grade tools, not off‑the‑shelf plug‑ins. Realising their full potential demands:

Customization – fine‑tuning on discipline‑specific corpora or data pipelines.
Trust & Transparency – rigorous validation, explainability layers, and community benchmarks.
Institutional Investment – compute resources, training programs, and integration into research workflows.

In short, AI is moving from a supporting calculator to a co‑investigator, but the transition hinges on sustained collaboration between technologists, domain scientists, and research administrators.

Looking Ahead

The convergence of symbolic equation generators, domain‑aware literature models, and ideation‑focused LLMs suggests a new research ecosystem where AI amplifies every stage of the scientific method—from hypothesis birth to experimental validation. When these tools become as routine as a statistical package, we can expect a acceleration of discovery across fields that have traditionally stagnated under data scarcity and human cognitive limits.

Stay tuned to Diagonalising for deeper dives into each tool, practical implementation guides, and interviews with the scientists who are already piloting them.

Organizing for Good

Thu, 29 Jun 2023 00:00:00 +0000

In today’s business world, organizational structure is more important than ever. ⁣⁣And when it comes to organizations serving needs in environments afflicted by natural disasters or wars, the stakes are even higher.

⁣⁣That’s why we’re interested in exploring how has contributed to its success by blending elements of platform design, flat structure, hierarchy, entrepreneurial spirit, and strong engagement with its community.⁣⁣ And that’s something worth pinning! ⁣⁣

So, what can we learn from this innovative company? Read this and share your thoughts on organizational structure to create impact! Let’s spark a discussion and see what insights we can gain together.

Innovation capital: Is the tide low?

Wed, 29 Jun 2022 00:00:00 +0000

Half a year into 2022 central banks are poised to keep raising interest rates, supply chains are hobbled, and a war is raging in Europe. As this harrowing mix turned markets tumultuous and zapped investors’ confidence, what does it mean for VC-backed investment?

In this , Christoph Feest and I argue that trends in policy and digitalization feed an undiminished appetite and need for venture backing, leading to increased, more-broadly sourced and more widely-distributed investments.

Blog | Giulia Solinas

Building Agents in Bob with a Software Spec Driven Approach

Building Agents in Bob with a Software Spec Driven Approach

Why Spec Driven Agent Development Matters

The Bob Skill Pipeline

Step 1: Start with solution-architect

Step 2: Convert Architecture into SOPs with sop-builder skills

Step 3: Generate the wxO Solution with wxo-builder skills

Step 4: Audit and Document with wxo-analyzer skills

A Practical End-to-End Flow

Best Practices for Spec Driven Agent Work

What This Changes

Bringing all together: The key building blocks of watsonx Orchestrate

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

Building Blocks: Agents and Tools

Agents

Tools

Grounding Agents with Knowledge

Advanced Architectures: Collaboration and Workflow

Development, Debugging, and Optimization

Conclusion: Bringing It All Together

Series Summary: Key Takeaways

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

Elevate Your AI Engineering: Mastering watsonx Orchestrate Tooling and APIs

The Agent Developer Kit (ADK): The Command Center

Essential Commands

Standardizing Tools with the Model Context Protocol (MCP)

Why MCP Matters

Security Considerations

API Essentials for Conversational Flows

The Critical API Parameters

Key Takeaways

Mastering Multi-Agent Orchestration and Tool Selection in watsonx Orchestrate

Mastering Multi-Agent Orchestration and Tool Selection in watsonx Orchestrate

Multi-Agent Orchestration: The Supervisor/Manager Pattern

Why Single Agents Fail at Scale

The Modular Solution

Agent Descriptions: Writing for the Model

What Makes a Great Description

Clarity Over Complexity

Choosing the Right Tool: Python vs. MCP

Python Tools (via ADK)

MCP Tools (Model Context Protocol)

Key Takeaways

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

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

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

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

2. The Low-Code Accelerator: The Agent Builder

3. Modularity is Precision: Process Decomposition

4. The LLM’s Instruction Manual: Routing Clarity

Key Takeaways

AI for Science

1. AI as a “Hilbert” for Equation Discovery

2. Smarter Literature Mining with SciLitLLM

3. LLM‑Generated Research Ideas (and Their Unexpected Novelty)

4. The Common Thread & What Still Needs to Happen

Looking Ahead

Organizing for Good

Innovation capital: Is the tide low?

Step 1: Start with `solution-architect`

Step 2: Convert Architecture into SOPs with `sop-builder` skills

Step 3: Generate the wxO Solution with `wxo-builder` skills

Step 4: Audit and Document with `wxo-analyzer` skills

1. AI as a “Hilbert” for Equation Discovery

2. Smarter Literature Mining with SciLitLLM

3. LLM‑Generated Research Ideas (and Their Unexpected Novelty)

4. The Common Thread & What Still Needs to Happen