Skip to main content

​
External Agents

External agents are built outside watsonx Orchestrate and can be used as collaborators for native agents. watsonx Orchestrate supports multiple provider protocols, including external_chat, the Agent-to-Agent Protocol (A2A), and specialized communication protocols for integrating with watsonx AI Agent Builder agents, watsonx Assistants, and Salesforce Agent Force agents. external_chat and A2A agents can be built on any underlying agent platform such as BeeAI, Langgraph, and CrewAI, where the user hosts the agent themselves, on Code Engine.

​
Providers

​
External Chat (Chat Completions API)

The external_chat provider can be used to integrate with any agent that is capable of providing an OpenAI style chat completions endpoint and is the most common form of integration. The documentation for this API spec can be found on the watsonx-orchestrate-developer-toolkit. A reference Langgraph external agent can be found here. 
spec_version: v1
kind: external 
name: news_agent
title: News Agent
nickname: news_agent 
provider: external_chat
description: |
  An agent built in langchain which searches the news.
tags:
  - test
api_url: "https://someurl.com"   # the url of the external agent
auth_scheme: BEARER_TOKEN        # one of BEARER_TOKEN | API_KEY | NONE 
auth_config:
  token: "123"                   # this is token for both BEARER_TOKEN and API_KEY 
chat_params:                     # chat_parms are parameters sent to an agent on each request
  stream: true                  # should the external agent be invoked using using SSE streaming or as a rest call 
config:                          # config represents the internal configuration of this agent used by wxo
  hidden: false                  # Hide this collaborator agent from the ui
  enable_cot: true               # Does the external agent return all internal steps and tool calls

​
Agent to Agent (A2A) Protocol

The Agent to Agent Protocol (A2A) is an open standard designed to enable communication and interoperability between multiple agentic systems. Because the standard evolves rapidly, watsonx Orchestrate specifies the A2A version in the provider field to ensure compatibility when communicating with agents. For a sample LangGraph agent compatible with the A2A protocol, see the a2a-samples repository. To register an agent that is compatible with the A2A protocol, set provider to external_chat/A2A/0.2.0, like the following example: 
spec_version: v1
kind: external 
name: news_agent
title: News Agent
nickname: news_agent 
provider: external_chat/A2A/0.2.0 # this is the identifier for A2A agents, provider/protocol/version of A2A supported
description: |
  An agent built in langchain which searches the news.
tags:
  - test
api_url: "https://someurl.com"   # the url of the external agent
auth_scheme: BEARER_TOKEN        # one of BEARER_TOKEN | API_KEY | NONE 
auth_config:
  token: "123"                   # this is token for both BEARER_TOKEN and API_KEY 
chat_params:                     # chat_parms are parameters sent to an agent on each request
  sendHistory:                   # indicates whether conversation history should be sent to the external A2A agent
  stream: false                  # should the external agent be invoked using using SSE streaming or as a rest call
  pushNotifications: true        # set to true if the external agent can send push notifications to provide updates on async tasks
config:                          # config represents the internal configuration of this agent used by wxo
  hidden: false                  # Hide this collaborator agent from the ui
Asynchronous updates with push notifications (technical preview) For tasks that run for extended periods (e.g., minutes, hours, or days) or in scenarios where clients cannot maintain persistent connections—such as mobile applications or serverless functions — A2A supports asynchronous updates via push notifications. This mechanism enables the A2A Server to actively notify a client-provided webhook whenever a significant task update occurs. If your agent supports asynchronous push notifications for long-running tasks, register this capability by setting the property: 
pushNotifications: true
The push notification configuration is provided to the external A2A agent in the initial message/send or message/stream request. The A2A agent must include the complete update — such as message, task, and artifact details (as applicable) — in the notification payload, along with the corr_id value received in the metadata of the initial request. Push notifications use Bearer token authentication, where the token is generated from API keys as described in the Getting Started guide. Callback URL and authentication The callback URL is included in the request sent to the A2A agent. To send push notifications, you must:

​
watsonx AI Agent Builder

You can also integrate with agents built using watsonx.ai’s agent builder platform. For more information, please see Registering agents from watsonx.ai here. Instead of using the API, complete the following YAML file and import your agent. Provide well-crafted descriptions for your agents. These descriptions are used by supervisor agents to determine how to route user requests. For more information, see Writing descriptions for agents. 
spec_version: v1
kind: external 
name: news_agent
title: News Agent
    provider: wx.ai                  # the provider will always be wx.ai
description: | 
  An agent built in langchain which searches the news.
tags:
  - test
api_url: "https://us-south.ml.cloud.ibm.com/ml/v4/deployments/<id>/ai_service_stream?version=2021-05-01"
auth_scheme: API_KEY             # this will always be API_KEY         
auth_config:
  token: "<my_api_key>"          # this is the API key for wx.ai  
chat_params:
  stream: true                   # should the external agent be invoked using using SSE streaming or as a rest call 
config:
  hidden: false                  # Hide this collaborator agent from the ui
  enable_cot: true               # Does the external agent return all internal steps and tool calls

​
Salesforce AgentForce

To register an agent that is built within Salesforce Agent Force as an external agent:
  1. Follow the Getting Started Guide for the Agent API. For more information, see the Getting Started Guide.
getting-started-salesforce.png
  1. On the Create a token page, the following information applies to all Salesforce agents within the instance:
    • api_url: Always set to https://api.salesforce.com/einstein/ai-agent/v1.
    • auth_config.token: Use the CONSUMER_SECRET provided in the guide.
    • chat_params:
      • client_id: Use the CONSUMER_KEY.
      • domain_url: Use the DOMAIN_URL.
      • Optionally, specify a list of display types to pass to Orchestrate as a comma-separated string.
  2. Provide well-crafted descriptions for your agents. These descriptions are used by supervisor agents to determine how to route user requests. For more information, see Writing descriptions for agents.
  3. Lastly, under chat_params you need to specify your agent_id. This can be found by hovering over one of your agents and either right-clicking and copying the URL, or by manually writing it based on hover text. In the following example, the agent_id is 0XxfJ0000001d8zSAA.
agent-selection-salesforce.png 
name: salesforce_ext_agent 
kind: external 
provider: salesforce                            # the provider will always be salesforce
title: Customer Service Agent by Salesforce
tags:
- "salesforce" 
description: An AI customer service agent whose job is to help customers with support questions or other issues. 
api_url: "https://api.salesforce.com/einstein/ai-agent/v1"
auth_scheme: API_KEY
auth_config:
  token: "my-api-key"
chat_params:
  agent_id: "my-agent-id"
  client_id: "my-client-id"
  domain_url: "https://agentforceXXX-dev-ed.develop.my.salesforce.com"
  # display_types: TextChunk,Confirm,Error,Failure,Inquire,Inform
config:
  hidden: false
  enable_cot: false

​
External watsonx Assistants

To register assistants from watsonx Assistant, you must obtain the following information:
  • service_instance_url
  • api_key
  • assistant_id
  • environment_id
Note: The location of the service_instance_url and api_key varies depending on whether the assistant is imported to IBM Cloud or AWS.
To retrieve your assistant ID:
  1. Navigate to the settings on the actions page and open the settings.
actions_page.png
  1. On the farthest right tab, select Upload/Download, and click the Download button.
actions-page.png
  1. Locate your environment_id and assistant_id in the output JSON.
environment-id.png

​
IBM Cloud

On IBM Cloud, your service_instance_url and api_key can be found on the page where you launch your assistant’s tooling UI. ibmcloud-service-keys.png Provide well-crafted descriptions for your agents. These descriptions are used by supervisor agents to determine how to route user requests. For more information, see Writing descriptions for agents. 
spec_version: v1
kind: assistant
name: hr_assistant
title: HR Agent
description: |
  This assistant is capable of acting as a first point of contact for all support requests.
tags:
- wxa
config:
  assistant_id: assistantid
  environment_id: environmentid
  hidden: false
  api_key: my-api-key
  service_instance_url: https://api.eu-de.assistant.watson.cloud.ibm.com/instances/<my-instance-id>
  api_version: '2023-06-15T00:00:00.000Z'
  auth_type: IBM_CLOUD_IAM
  authorization_url: https://iam.cloud.ibm.com

​
AWS

Provide well-crafted descriptions for your agents. These descriptions are used by supervisor agents to determine how to route user requests. For more information, see Writing descriptions for agents. 
spec_version: v1
name: my_assistant
title: my_assistant
description: |
  This assistant is capable of handling call center operations.
kind: assistant
tags:
- wxa
config:
  assistant_id: assistantid
  environment_id: environmentid
  hidden: false
  api_key: my-api-key
  service_instance_url: https://api.us-east-1.preprod.aws.watsonassistant.ibm.com/instances/<my-instance-id>
  api_version: '2023-06-15'
  auth_type: MCSP
  authorization_url: https://iam.platform.saas.ibm.com

​
Additional features of external agents

​
Providing access to context variables

Context variables enable builders to incorporate user-specific identifiers—such as username, user ID, or tenant ID—from upstream systems into an agent. These variables can currently be set through API-level integration by using the Runs API, the Chat Completions API, or its streaming variant. By default, agents invoked during a run do not have access to context. To enable access, set the context_access_enabled field to true and provide a list of context_variables to expose to the agent. Context variables are passed to the agent in the following ways:
  • Runs API: Use the context field at the root of the request.
  • Chat Completions API: Use the context field at the root of the request.
  • Streaming variant: Each SSE event sent to the agent includes the context object.
  • The context variables defined will be accessible to external A2A agents in the metadata of the message object.
spec_version: v1
kind: external
name: news_agent
title: News Agent
nickname: news_agent
provider: external_chat/A2A/0.2.0 # this is the identifier for A2A agents, provider/protocol/version of A2A supported
description: |
  An agent built in langchain which searches the news.
tags:
- test
api_url: "https://someurl.com" # the url of the external agent
auth_scheme: BEARER_TOKEN # one of BEARER_TOKEN | API_KEY | NONE
auth_config:
  token: "123" # this is token for both BEARER_TOKEN and API_KEY
chat_params:                     # chat_parms are parameters sent to an agent on each request
  sendHistory:                   # indicates whether conversation history should be sent to the external A2A agent
  stream: false                  # should the external agent be invoked using using SSE streaming or as a rest call 
config:
  hidden: false # Hide this collaborator agent from the ui
context_access_enabled: true
context_variables:
  - clientID

​
Restricting Agents

You can restrict external agents in watsonx Orchestrate by using the restrictions parameter in your external agent configuration. 
spec_version: v1
kind: external
name: news_agent
title: News Agent
nickname: news_agent
provider: external_chat/A2A/0.2.0 # this is the identifier for A2A agents, provider/protocol/version of A2A supported
description: |
  An agent built in langchain which searches the news.
tags:
- test
api_url: "https://someurl.com" # the url of the external agent
auth_scheme: BEARER_TOKEN # one of BEARER_TOKEN | API_KEY | NONE
auth_config:
  token: "123" # this is token for both BEARER_TOKEN and API_KEY
chat_params:                     # chat_parms are parameters sent to an agent on each request
  sendHistory:                   # indicates whether conversation history should be sent to the external A2A agent
  stream: false                  # should the external agent be invoked using using SSE streaming or as a rest call 
config:
  hidden: false # Hide this collaborator agent from the ui
restrictions: editable