Skip to main content
With the ADK, you can create native agents, external agents, and external watsonx Assistants agents. Each of these agent types requires its own set of configurations. Use YAML, JSON, or Python files to create your agents for watsonx Orchestrate.

​
Native Agents

Native agents are developed and imported into the watsonx Orchestrate platform. Each agent is composed of several key components:
​
llm
string
The large language model (LLM) that powers the agent’s ability to understand and respond to user queries.
​
style
string
Defines the prompting structure that the agent uses. This determines how the LLM interprets and responds to instructions. For more information, see Agent styles.
​
hide_reasoning
boolean
Defines whether the agent’s reasoning appears to the end user. When set to True, the agent hides its reasoning from the user. When set to False, the agent displays its reasoning. The default value is False.
​
instructions
string
Natural language guidance that is provided to the LLM. These instructions shape the agent’s behavior, such as adopting a specific persona (for example, a customer service representative) and explaining how to use tools and collaborators to solve tasks. For more information, see Writing instructions for agents.
​
tools
list<string>
Extend the LLM’s capabilities by enabling access to external functions and services. Examples include:
  • OpenAPI definitions for external APIs
  • Python functions for scripting more complex interactions with external systems
  • Agentic workflows that orchestrate complex operations across multiple tools and agents
  • Toolkit-exposed tools such as an MCP server
​
collaborators
list<string>
Other agents that this agent can interact with to solve more complex problems. Collaborators might be native watsonx Orchestrate agents, external agents, or watsonx Assistants. To learn how to connect external agents, see Connect to external agents.
​
description
string
A human-readable summary of the agent’s purpose, visible in the Manage Agents UI. It also helps other agents understand its role when used as a collaborator. Note: The description does not influence how the agent responds unless it is invoked as a collaborator. For guidance, see Writing descriptions for agents.
​
knowledge_base
list<string>
Represents domain-specific knowledge that is acquired by the LLM from uploaded files or connected vector data stores.
​
restrictions
string
Specifies whether the Agent remains editable after import. This field accepts one of the following options:
  • editable Sets the Agent as editable. This is the default value.
  • non_editable Sets the Agent as non-editable and prevents it from being exported.
spec_version: v1
kind: native
name: agent_name
llm: watsonx/ibm/granite-3-8b-instruct  # watsonx Orchestrate (watsonx) model provider followed by the model id: ibm/granite-3-8b-instruct
style: default     
hide_reasoning: False
description: |
    A description of what the agent should be used for when used as a collaborator.
instructions: |
    These instructions control the behavior of the agent and provide 
    context for how to use its tools and agents.
collaborators:
  - name_of_collaborator_agent_1
  - name_of_collaborator_agent_2
tools:
  - name_of_tool_1
  - name_of_tool_2
knowledge_base:
  - name_of_knowledge_base
restrictions: editable

​
Additional features of native agents

Customize your agent by configuring additional features to better match your specific needs.

​
Web chat configuration

Use web chat configurations to customize how your agent behaves in the web chat UI. Set up a welcome message and starter prompts to guide users from the start.

​
Welcome message

Welcome message example

Welcome message example

The welcome message is the first message users see when they start interacting with your agent. You can personalize this message to match your agent’s purpose. To configure it, define the welcome_content schema in your agent file by using the following: Example: 
spec_version: v1
style: react
name: service_now_agent
llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
description:  'Agent description'
instructions: ''
collaborators: []
tools: []
hidden: false
welcome_content:
  welcome_message: "Hello, I'm Agent. Welcome to watsonx Orchestrate!"
  description: "How can I help you today?"

​
Starter prompts

Start prompts example

Starter prompts example

Starter prompts are predefined messages that help users begin a conversation with your agent. You can configure these prompts in the starter_prompts section of your agent file. Start by defining whether these prompts are the default set. Then, for each prompt, configure the following: Example: 
spec_version: v1
style: react
name: service_now_agent
llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
description:  'Agent description'
instructions: ''
collaborators: []
tools: []
hidden: false
starter_prompts:
    prompts:
        - id: "hello1"
          title: "Hello1"
          subtitle: ""
          prompt: "This is the messages for Hello prompt"

​
Agent styles

Agent styles dictate how the agents follow instructions and the way that the agents behave. Currently, you can choose from three available styles:

​
Default style

The Default (default) style is a streamlined, tool-centric reasoning mode ideal for straightforward tasks. It relies on the LLM’s prompt-driven decision-making to decide which tool to use, how to use it, and when to respond. This style is excellent when the logic is mostly linear, like retrieving a report or checking a ticket, because the agent uses the LLM’s intrinsic capabilities to orchestrate tool calls on the fly. It is ideal for:
  • Single-step or lightly sequential tasks
  • Scenarios where flexibility and adaptability are needed
  • Tasks that might require multiple tools but don’t need strict sequencing
Behavior
  • Iteratively prompts the LLM to:
    • Identify which tool or collaborator agent to invoke
    • Determine what inputs to use
    • Decide whether to call more tools or finalize a response
  • Continues the prompting loop as needed until it gathers sufficient context for a final answer.
Tool Compatibility
  • Python tools
  • OpenAPI tools
  • MCP tools
Example use cases:
  • Extract information from the web or from a system
  • Check the status of a task or ticket
  • Perform tasks that require well-defined steps

​
ReAct style

The ReAct (react) style (Reasoning and Acting) is an iterative loop where the agent thinks, acts, and observes continuously. It is designed for complex or ambiguous problems where each outcome influences the next action. Inspired by the ReAct methodology, this pattern surfaces the agent’s chain of thought, supporting validation, step-by-step reasoning, and interactive confirmation. A ReAct agent breaks the task into smaller parts, and starts reasoning through each step before taking an action and deciding on which tools to use. The agent then adjusts its actions based on what it learns along the way, and it might ask the user for confirmation to continue working on the given task. It is ideal for:
  • Exploratory or research-intensive tasks
  • Scenarios requiring iterative validation or hypothesis testing
  • Tasks with unclear or evolving requirements
  • Situations where transparent reasoning and reflection are valuable
Behavior
  • Think: Assess the user’s request and decide on a tool, collaborator, or reasoning step.
  • Act: Execute the tool or collaborator.
  • Observe: Evaluate the outcome and adjust reasoning.
  • Repeat until the goal is achieved.
Tool Compatibility
  • Knowledge-intensive tools
  • Data-intensive tools
  • Collaborator agents
Example use cases
  • Coding an application or tool by generating code snippets or refactoring existing code
  • Answering complex questions by searching the web, synthesizing information, and citing sources
  • Handling support tickets that require complex interactions with users

​
Plan-Act style

The Plan-Act (planner) style agent emphasizes upfront planning followed by stepwise execution. Initially, the agent uses the LLM to create a structured action plan, a sequence of tasks to execute, with all the tools and collaborator agents to invoke. Once the plan is in place, it carries out each step in order. This approach supports dynamic replanning if unexpected changes occur, leveraging the agent’s oversight over multi-step workflows. A planner style agent is capable of customizing the response output. By default, the planner style generates a summary of the tasks planned and executed by the planner agent if you don’t provide a custom response output. It is ideal for:
  • Multi-step, structured workflows
  • Business processes needing transparency and traceability
  • Automations involving multiple domains or collaborator agents
Tool Compatibility
  • Python tools
  • OpenAPI tools
  • MCP tools
  • Collaborator agents
Example use cases:
  • Creating structured reports
  • Agents that use multiple tools (for example, search, calculator, code execution) and need to combine results
  • Drafting contracts, policies, or compliance checklists
Customizing the response output with the Plan-Act agent
To customize the output, you can define either a structured_output field or a custom_join_tool field, as follows:
structured_output and custom_join_tool are mutually exclusive. If you provide one of them, do not provide the other.
spec_version: v1
style: planner
structured_output: {type: "object",   additionalProperties: false, properties: {}}  # if no custom_join_tool is provided, provide a structured output
name: customer_care_agent
llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
description: |
  You are an agent who specializes in customer care for a large healthcare institution. You should be compassionate
  to the user. ...
collaborators:
  - service_now_agent
tools:
  - search_healthcare_providers
  - get_healthcare_benefits
  - get_my_claims
The structured_output defines the schema of how the data should be returned from the agent. The custom_join_tool is a normal Python tool that dictates how the output of the agent should look like, giving you total control of how the output looks instead of being generated by the LLM. You can see the following example of a custom_join_tool:
custom_join_tool.py
from typing import Dict, List, Any
from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
from ibm_watsonx_orchestrate.agent_builder.tools.types import PythonToolKind

@tool(permission=ToolPermission.READ_ONLY, kind=PythonToolKind.JOIN_TOOL)
def format_task_results(original_query: str, task_results: Dict[str, Any], messages: List[Dict[str, Any]]) -> str:
    """
    Format the results from various tasks executed by a planner agent into a cohesive response.

    Args:
        original_query (str): The initial query submitted by the user.
        task_results (Dict[str, Any]): A dictionary containing the outcomes of each task executed within the agent's plan.
        messages (List[Dict[str, Any]]): The history of messages in the current conversation.

    Returns:
        str: A formatted string containing the consolidated results.
    """
    # Create a summary header
    output = f"## Results for: {original_query}\n\n"

    # Add each task result in a structured format
    for task_name, result in task_results.items():
        output += f"### {task_name}\n"

        # Handle different result types appropriately
        if isinstance(result, dict):
            # Pretty format dictionaries
            output += "```json\n"
            output += json.dumps(result, indent=2)
            output += "\n```\n\n"
        elif isinstance(result, list):
            # Format lists as bullet points
            output += "\n".join([f"- {item}" for item in result])
            output += "\n\n"
        else:
            # Plain text for other types
            output += f"{result}\n\n"

    # Add a summary section
    output += "## Summary\n"
    output += f"Completed {len(task_results)} tasks related to your query about {original_query.lower()}.\n"

    return output

​
Guidelines

You can configure guidelines to control agent behavior. Guidelines are similar to instructions but more structured, providing stronger guarantees about how the agent responds. Use guidelines when you need predictable, rule-based behavior.
  1. Each guideline follows the format: When condition then perform an action and/or invoke a tool.
  2. Only guidelines relevant to the current user utterance are included in the agent prompt. This reduces complexity for the LLM.
  3. Guidelines execute in priority order, based on their position in the list.
  4. Only guidelines whose condition is relevant to the current user utterance will be injected into the agent prompt, reducing the complexity of the task posed to the LLM.
  5. Guidelines are invoked in priority order (the order they are listed).
To set up guidelines, add a guidelines section and define each guideline with the following fields: 
spec_version: v1
kind: native # Optional, Default=native, Valid options ['native', 'external', 'assistant']
name: finance_agent
style: default # Optional, Valid options ['default', 'react', 'planner']
llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
description: |
  You are a helpful calculation agent that assists the user in performing math.
  This includes performing mathematical operations and providing practical use cases for math in everyday life.
instructions: |
  Always solve the mathematical equations using the correct order of operations (PEMDAS):
    Parentheses
    Exponents (including roots, powers, and so on)
    Multiplication and Division (from left to right)
    Addition and Subtraction (from left to right)

  Make sure to include decimal points when the user's input includes a float.
guidelines:
  - display_name: "User Dissatisfaction"
    condition: "The Customer expresses dissatisfaction with the agents response."
    action: "Acknowledge their frustration and ask for details about their experience so it can be addressed properly."
  - display_name: "Joy check"
    condition: "If the customer expresses joy or happiness about the response"
    action: "Respond by making chicken noises like 'bock bock' and then take no further action"
  - display_name: "Check user"
    condition: "If the customer expresses the need to check a user in the system."
    action: "Use the 'get_user' tool to check the user in the system"
    tool: "get_user"

tools:
  - get_user
collaborators: []

​
Knowledge

Agent Knowledge allows you to provide information that the agent should inherently know and use to answer questions. This knowledge can come from documents you upload or from various data sources integrated with watsonx Orchestrate, such as Milvus, Elasticsearch, AstraDB, and others. 
spec_version: v1
style: react
name: service_now_agent
llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
description:  'Agent description'
instructions: ''
collaborators: []
tools: []
knowledge_base:
- my_knowledge_base
To learn more about setting up a knowledge base see the section on Knowledge bases.

​
Chat with documents

In addition to Knowledge, builders can enable the Chat with Documents feature. This allows users to upload a document during a conversation and ask questions about its content—without permanently storing the document in watsonx Orchestrate. Unlike Knowledge, which persists documents, Chat with Documents handles them only for the duration of the session. 
spec_version: v1
style: react
name: service_now_agent
llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
description:  'Agent description'
instructions: ''
collaborators: []
tools: []
chat_with_docs:
  enabled: true
  citations:
    citations_shown: -1
  generation:
    idk_message: 'Your I don’t know message'
  supports_full_document: true
Note: When this feature is enabled, users can upload documents during chat interactions. The agent uses the file name to route prompts to the correct document, so ensure that uploaded file names are unique and meaningful to avoid confusion.

​
Providing access to context variables

Context variables let builders inject user-specific identifiers, such as username, user ID, or tenant ID, from upstream systems into their agents. This enables personalized, context-aware interactions throughout the agent’s execution. Out of the box, the following variables are available to your agents:
  • wxo_email_id - The email address used by the user that invoked the agent/tool
  • wxo_user_name - The username of the user that invoked the agent/tool
  • wxo_tenant_id - The wxo tenant id (unique wxo instance identifier) of the request
kind: native
name: context_variables_sample
display_name: Context Variables Agent
description: I'm able to deal with context variables
llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
style: react
instructions: |
  You have access to additional information :
    - wxo_email_id - {wxo_email_id}  
    - wxo_user_name - {wxo_user_name}  
    - wxo_tenant_id - {wxo_tenant_id}  
  Help users by returning the values to you so you can respond back to user with these values.
guidelines: []
collaborators: []
tools: []
knowledge_base: []
spec_version: v1
context_access_enabled: true
context_variables:
  - wxo_email_id
  - wxo_tenant_id
  - wxo_user_name
For scheduled workflows, the email address and username will be that of the user who originally scheduled the workflow.
To set context variables, pass a dictionary as the context within the request body (not context_variables) when using any of the following endpoints: By default, agents invoked during a run cannot access context variables. To enable this, set the context_access_enabled field to true. After enabling context access, you must specify the context_variables the agent will use. These variables define which contextual details, such as user identifiers or session data, are available during execution. You can reference these variables in descriptions, guidelines, or instructions using curly braces (for example, {my_context_variable}), or pass them as arguments to a Python function. In the latter case, the agent runtime automatically fills the values without prompting the user. 
spec_version: v1
style: react
name: service_now_agent
llm: watsonx/meta-llama/llama-3-1-70b-instruct
description:  'Agent description'
instructions: |
  You have access to clientID: {clientID}
collaborators: []
tools: []
context_access_enabled: true
context_variables:
  - clientID
  - channel     # Use it to get access to channel integration (embedded chat)