DOCSEARCHbyAlgolia
Submit Docs

watsonx Orchestrate Agent Development Kit (ADK)

repository·main·Indexed 41 days ago

https://github.com/ibm/ibm-watsonx-orchestrate-adk

A Python-based toolkit and CLI for building, testing, and deploying AI agents. It includes a 'Developer Edition' for local development and tools for packaging agents for the watsonx Orchestrate Agent Catalog. The ADK supports creating agents with PDF knowledge bases, integrating with external APIs like ServiceNow, and implementing re-entrant patterns for stateful operations using external databases such as AstraDB.

Tokens
232.5K
Snippets
610
Records
873
Agent score
51%

What's inside watsonx Orchestrate ADK

  1. Overview of watsonx Orchestrate Skills

    main

    The ADK contains a suite of skills designed to support the end-to-end lifecycle of enterprise automation and agent solutions. These skills form a closed-loop system for:

    1. Designing: solution-architect (business to technical design) and agentic-workflow-advisor (workflow validation).
    2. Building: sop-builder (technical workflows to SOPs) and wxo-builder (SOPs to implemented solutions).
    3. Documenting: wxo-analyzer (reverse-engineering existing projects).
    4. Evaluating & Debugging: agent-instructions-evaluator (instruction reliability), telemetry-analyzer (trace-based debugging), and customercare-mcp-builder (MCP server development).

  2. Overview of the wxo-analyzer skill

    main

    The wxo-analyzer is a skill designed to analyze watsonx Orchestrate (wxO) projects and automatically generate a comprehensive 3-file documentation set. This documentation set includes Mermaid diagrams to visualize relationships between components.

    The 3-File Report Structure:

    1. Solution Overview Report: High-level architecture, business purpose, project structure, and deployment notes. Intended for stakeholders and architects.
    2. Agent Analysis Report: Detailed breakdown of each agent's purpose, configuration, instructions, capabilities, collaborators, and tools. Intended for prompt authors and AI engineers.
    3. Tools and Components Report: Technical details on Python tools, flows (Python or JSON), Langflow assets, connections, and knowledge bases. Intended for developers and platform engineers.

  3. Overview of the Customer Care Agent (CCA) Architecture

    main

    The Customer Care Agent (CCA) style for Watsonx Orchestrate is designed for high-performance, low-latency interactions across channels like CCaaS, Web Chat, Slack, and Voice.

    Core Components

    • Channels: Interfaces where users interact (e.g., Web Client, Slack, FB Messenger).
    • Runtime: The Customer Care Agent (CCA) that manages the conversation.
    • Knowledge: A store for uploaded business content used by the agent.
    • MCP Servers: Custom Model Context Protocol (MCP) servers that allow the agent to access business systems (e.g., Claims, Benefits, ID) on behalf of customers.

    Key Capabilities

    • Fast Response Times: Optimized for low latency.
    • Risk Mitigation: Strategies to prevent LLM hallucinations in sensitive domains.
    • Personalized Experience: Tailoring tools and interactions based on user context (e.g., specific banking products held).
    • Rich Interaction: Support for out-of-the-box and custom widgets (e.g., Date Pickers).
    • Multi-Language Support: Business logic is provided once and handled by the platform in multiple languages.

  4. Overview of the Agent Instructions Evaluator

    main

    The Agent Instructions Evaluator is a skill designed to evaluate agent instructions or definitions for operational achievability in production environments. Unlike standard writing quality checks, this skill focuses on runtime reliability and efficiency. It identifies risks such as hidden state requirements, conflicting rules, vague scope, brittle phrasing, underspecified tool behavior, and instruction overload.

    Evaluation Output

    The skill produces a structured, evidence-backed report containing:

    • Per-dimension scores (0-5 scale) across five core dimensions.
    • Deterministic signal counts (e.g., exact phrases, nested branches, implicit state).
    • Detailed findings including evidence, impact analysis, and specific recommendations.
    • Risk prioritization based on high-impact changes.
    • Runtime performance risk assessment (token overhead, reasoning overhead, tool-call overhead, retry-loop risk, and latency variance).
    • Structured JSON for integration with evaluation harnesses.

  5. Use the Agent Telemetry Analyzer skill

    main

    The telemetry-analyzer skill is used to debug watsonx Orchestrate agents by exporting and analyzing telemetry traces. It supports two trace formats:

    1. OTel JSON: Produced by the classic TracesController.export_trace_to_json() ADK path or local IBM telemetry servers. The top-level key is traceData.resourceSpans.
    2. Langfuse JSON: Produced by the agentops-v3 REST API (GET /v1/agentops-v3/traces/<id>) or the export_traces_agentops_v3.py script. The top-level key is observations (an array of GENERATION / CHAIN / SPAN objects).

    Key Capabilities:

    • Trace Discovery: Finds traces by agent name or ID across remote (wxO Traces API or agentops-v3) or local environments.
    • Bug Detection: Automatically scans for hard errors, LLM failures (e.g., finish_reason == "length"), tool call failures, agent logic loops, token anomalies, and cache efficiency issues.
    • Reporting: Generates structured HTML bug reports with root-cause analysis and fix recommendations, or thread-scoped conversational flow reports that reconstruct multi-turn interactions.

  6. CustomerCare Tutorials Overview

    main

    The CustomerCare tutorials provide a structured learning path for building customer care agents using the Model Context Protocol (MCP). The tutorials are designed to take you from initial installation to building custom MCP servers from scratch, with a focus on the 'Customer Care Agent' (CCA) style.

    Learning Paths

    • Beginners: Start with Installation Guide and Getting Started to understand the basics and run the banking agent demo.
    • Extending Existing Examples: If you want to add features to the provided banking example, follow the Extending the Server tutorial.
    • Building New Servers: To build your own domain-specific agent (e.g., insurance), follow the full path, specifically focusing on the Creating New Servers tutorial.
    • Architects: Review the Getting Started tutorial to understand the architecture, context layers, and how this approach differs from traditional chatbots.

  7. Build MCP servers for customer care agents

    main

    The customercare-mcp-builder skill is designed to guide the creation of production-ready Model Context Protocol (MCP) servers specifically for customer care agents. It enforces strict adherence to Watson Orchestrate specifications regarding tool patterns, authentication, widgets, and context management.

    When using this builder, you must follow a specific workflow to ensure the resulting server is compatible with the Orchestrate environment.

  8. Manage bundled skills with IBM watsonx Orchestrate MCP Server tools

    main
    The ibm-watsonx-orchestrate-mcp-server package includes tools to access and manage pre-bundled skills. These skills are included at build time, so no network or git access is required at runtime. You can discover available skills, fetch individual skills, or fetch all skills to your local project directory.

  9. Memory Coach SDK Agent Overview

    main

    The Memory Coach SDK Agent is a LangGraph-based custom agent example that demonstrates how to build memory-driven agents using the ibm-watsonx-orchestrate-sdk. It uses an external LLM (via OpenRouter) to manage a personalization loop: planning when to search or store memory, retrieving relevant context, and generating personalized responses.

    Key capabilities include:

    • Memory Planning: The LLM decides whether to recall information or store new facts.
    • Personalization Loop: Uses client.memory.add_messages() to store facts and client.memory.search() to retrieve them in later turns.
    • Structured Memory: Categorizes information into specific types to ensure backend compatibility.

  10. Overview of creating new MCP servers

    main

    To create a new Model Context Protocol (MCP) server for a custom domain, you must follow these six steps:

    1. Set up the project structure: Initialize your environment (Node.js or Python).
    2. Implement the MCP protocol: Use an MCP SDK to handle communication.
    3. Define tools: Implement the specific domain logic as tools.
    4. Manage context and state: Handle how the agent interacts with data.
    5. Configure the agent runtime: Set up how the server connects to the orchestrator.
    6. Test and iterate: Verify tool execution and protocol compliance.

  11. Compare wxO Agentic Workflow vs LangGraph for Swarms

    main

    When building an Agentic Swarm, the wxO Agentic Workflow offers several advantages over LangGraph:

    1. Human-in-the-loop: Built-in support for user activities and forms makes it easier to incorporate human oversight.
    2. Agent Composition Flexibility: You can compose swarms using agents built on different frameworks or technologies. LangGraph typically requires all agents to be defined within the same graph.
    3. Control and Predictability: You can implement a custom Agent Router as a control point to manage delegation and prevent issues like infinite loops.

  12. Understand the Skill file structure

    main

    Each skill in the ADK follows a standardized format for metadata and content:

    • SKILL.md: The primary file containing the skill's definition. It must include Frontmatter (metadata like name and description) and the main Content (expert guidance, specifications, and best practices).
    • examples.md: Contains complete reference implementations and code examples where applicable.