Connect to external agents

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

{
  "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.\n",
  "tags": [
    "test"
  ],
  "api_url": "https://someurl.com",
  "auth_scheme": "BEARER_TOKEN",
  "auth_config": {
    "token": "123"
  },
  "chat_params": {
    "stream": true
  },
  "config": {
    "hidden": false,
    "enable_cot": true
  }
}

from ibm_watsonx_orchestrate.agent_builder.agents import Agent, ExternalAgent, AgentKind, AgentProvider, ExternalAgentAuthScheme

my_agent = ExternalAgent(
    kind=AgentKind.EXTERNAL,
    name="news_agent",
    title="News Agent",
    nickname="news_agent",
    provider=AgentProvider.EXT_CHAT,
    description="An agent built in langchain which searches the news.\n",
    tags=['test'],
    api_url="https://someurl.com",
    auth_scheme=ExternalAgentAuthScheme.BEARER_TOKEN,
    auth_config={
        "token": "123"
    },
    chat_params={
        "stream": True
    },
    config={
        "hidden": False,
        "enable_cot": True
    }
)

# External Agents can only be used as a collaborator of a native agent as shown below
native_agent = Agent(
    # omitted for brevity
    collaborators=[my_agent]
)

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. The currently supported version is 0.3.0. Earlier versions, such as 0.2.1, are deprecated and will be removed in a future release. To ensure continued support, use version 0.3.0 or later when registering A2A-compatible 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.3.0, like the following example:

spec_version: v1
kind: external 
name: news_agent
title: News Agent
nickname: news_agent 
provider: external_chat/A2A/0.3.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

{
  "spec_version": "v1",
  "kind": "external",
  "name": "news_agent",
  "title": "News Agent",
  "nickname": "news_agent",
  "provider": "external_chat/A2A/0.2.0",
  "description": "An agent built in langchain which searches the news.",
  "tags": ["test"],
  "api_url": "https://someurl.com",
  "auth_scheme": "BEARER_TOKEN",
  "auth_config": {
    "token": "123"
  },
  "chat_params": {
    "stream": true,
    "pushNotifications": true
  },
  "config": {
    "hidden": false
  }
}

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:

Use a valid API key to generate a Bearer token for authentication.
Provide complete task update details in the notification payload, following the A2A protocol’s task object specification. Partial status updates are not sufficient.

watsonx AI Agent Builder

You can also integrate with agents built using watsonx.ai’s agent builder platform. For more information, see Registering agents from watsonx.ai. 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

{
  "spec_version": "v1",
  "kind": "external",
  "name": "news_agent",
  "title": "News Agent",
  "provider": "wx.ai",
  "description": "An agent built in langchain which searches the news.\n",
  "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",
  "auth_config": {
    "token": "my-api-key"
  },
  "chat_params": {
    "stream": true
  },
  "config": {
    "hidden": false,
    "enable_cot": true
  }
}

from ibm_watsonx_orchestrate.agent_builder.agents import Agent, ExternalAgent, AgentKind, AgentProvider, ExternalAgentAuthScheme

my_agent = ExternalAgent(
    kind=AgentKind.EXTERNAL,
    name="news_agent",
    title="News Agent",
    nickname="news_agent",
    provider=AgentProvider.WATSONX,                         # the provider will always be AgentProvider.WATSONX 
    description="An agent built in langchain which searches the news.\n",
    tags=['test'],
    api_url="https://us-south.ml.cloud.ibm.com/ml/v4/deployments/<id>/ai_service_stream?version=2021-05-01",
    auth_scheme=ExternalAgentAuthScheme.API_KEY,            # the auth_schema will always be ExternalAgentAuthScheme.API_KEY
    auth_config={
        "token": "my-api-key"
    },
    chat_params={
        "stream": True                                      # should the external agent be invoked using using SSE streaming or as a rest call
    },
    config={
        "hidden": False,
        "enable_cot": True
    }
)

# External Agents can only be used as a collaborator of a native agent as shown below
native_agent = Agent(
    # omitted for brevity
    collaborators=[my_agent]
)

Salesforce AgentForce

To register an agent that is built within Salesforce Agent Force as an external agent:

Follow the Getting Started Guide for the Agent API. For more information, see the Getting Started Guide.

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

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

{
  "name": "salesforce_ext_agent",
  "kind": "external",
  "provider": "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"
  },
  "config": {
    "hidden": false,
    "enable_cot": false
  }
}

from ibm_watsonx_orchestrate.agent_builder.agents import Agent, ExternalAgent, AgentKind, AgentProvider, ExternalAgentAuthScheme

my_agent = ExternalAgent(
    name="salesforce_ext_agent",
    kind=AgentKind.EXTERNAL,
    provider=AgentProvider.SALESFORCE,                         # the provider will always be AgentProvider.SALESFORCE 
    title="Customer Service Agent by Salesforce",
    description="An AI customer service agent whose job is to help customers with support questions or other issues.",
    tags=['salesforce'],
    api_url="https://api.salesforce.com/einstein/ai-agent/v1",
    auth_scheme=ExternalAgentAuthScheme.API_KEY,            # the auth_schema will always be ExternalAgentAuthScheme.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"
    },
    config={
        "hidden": False,
        "enable_cot": True
    }
)

# External Agents can only be used as a collaborator of a native agent as shown below
native_agent = Agent(
    # omitted for brevity
    collaborators=[my_agent]
)

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:

Navigate to the settings on the actions page and open the settings.

On the farthest right tab, select Upload/Download, and click the Download button.

Locate your environment_id and assistant_id in the output JSON.

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.

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

{
  "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.\n",
  "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"
  }
}

from ibm_watsonx_orchestrate.agent_builder.agents import Agent, AssistantAgent, AssistantAgentConfig, AgentKind
from ibm_watsonx_orchestrate.agent_builder.agents.types import AssistantAgentAuthType

my_agent = AssistantAgent(
    name="hr_assistant",
    kind=AgentKind.ASSISTANT,
    title="HR Agent",
    description="This assistant is capable of acting as a first point of contact for all support requests.\n",
    tags=['wxa'],
    config=AssistantAgentConfig(
        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=AssistantAgentAuthType.IBM_CLOUD_IAM,
        authorization_url="https://iam.cloud.ibm.com"
    )
)

# External Agents can only be used as a collaborator of a native agent as shown below
native_agent = Agent(
    # omitted for brevity
    collaborators=[my_agent]
)

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

{
  "spec_version": "v1",
  "name": "my_assistant",
  "title": "my_assistant",
  "description": "This assistant is capable of handling call center operations.\n",
  "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"
  }
}

from ibm_watsonx_orchestrate.agent_builder.agents import Agent, AssistantAgent, AssistantAgentConfig, AgentKind
from ibm_watsonx_orchestrate.agent_builder.agents.types import AssistantAgentAuthType

my_agent = AssistantAgent(
    name="hr_assistant",
    kind=AgentKind.ASSISTANT,
    title="HR Agent",
    description="This assistant is capable of acting as a first point of contact for all support requests.\n",
    tags=['wxa'],
    config=AssistantAgentConfig(
        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-15T00:00:00.000Z",
        auth_type=AssistantAgentAuthType.MCSP,
        authorization_url="https://iam.platform.saas.ibm.com"
    )
)

# External Agents can only be used as a collaborator of a native agent as shown below
native_agent = Agent(
    # omitted for brevity
    collaborators=[my_agent]
)

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.3.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

{
    "spec_version": "v1",
    "kind": "external",
    "name": "news_agent",
    "title": "News Agent",
    "nickname": "news_agent",
    "provider": "external_chat/A2A/0.3.0",
    "description": "An agent built in langchain which searches the news.\n",
    "tags": [
        "test"
    ],
    "api_url": "https://someurl.com",
    "auth_scheme": "BEARER_TOKEN",
    "auth_config": {
        "token": "123"
    },
    "chat_params": {
        "stream": true
    },
    "config": {
        "hidden": false
    },
    "context_access_enabled": true,
    "context_variables": [
        "clientID"
    ]
}

Show detailed parameter descriptions

context_access_enabled

object

default:"false"

Indicates whether this agent can access context variables set by the Runs API.

context_variables

list<string>

default:"[]"

Specifies the list of context variables the agent can access.

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

{
    "spec_version": "v1",
    "kind": "external",
    "name": "news_agent",
    "title": "News Agent",
    "nickname": "news_agent",
    "provider": "external_chat/A2A/0.3.0",
    "description": "An agent built in langchain which searches the news.\n",
    "tags": [
        "test"
    ],
    "api_url": "https://someurl.com",
    "auth_scheme": "BEARER_TOKEN",
    "auth_config": {
        "token": "123"
    },
    "chat_params": {
        "stream": true
    },
    "config": {
        "hidden": false
    },
    "restrictions": "editable"
}

Show detailed parameter descriptions

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.

Release Notes

Get Started

Build

Analyze

watsonx Orchestrate Developer Edition

watsonx Orchestrate ADK MCP Server

Reference

Legal notices

External Agents

Providers

External Chat (Chat Completions API)

Agent to Agent (A2A) Protocol

watsonx AI Agent Builder

Salesforce AgentForce

External watsonx Assistants

IBM Cloud

AWS

Additional features of external agents

Providing access to context variables

Restricting Agents

​External Agents

​Providers

​External Chat (Chat Completions API)

​Agent to Agent (A2A) Protocol

​watsonx AI Agent Builder

​Salesforce AgentForce

​External watsonx Assistants

​IBM Cloud

​AWS

​Additional features of external agents

​Providing access to context variables

​Restricting Agents

External Agents

Providers

External Chat (Chat Completions API)

Agent to Agent (A2A) Protocol

watsonx AI Agent Builder

Salesforce AgentForce

External watsonx Assistants

IBM Cloud

AWS

Additional features of external agents

Providing access to context variables

Restricting Agents