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

Running A2A agents on behalf of a user By default, watsonx Orchestrate calls an external A2A agent using its own service identity. When the A2A agent needs to act on behalf of the end user — for example, to call downstream enterprise systems (such as Concur or ServiceNow) using the user’s identity — you can forward a user-scoped token to the A2A agent by setting app_id in the agent YAML definition to the name of a connection that issues a user-scoped token. This mechanism works with any connection type that produces a user-scoped token, including:

RFC 8693 OAuth 2.0 Token Exchange (oauth_auth_token_exchange_flow) — watsonx Orchestrate presents the user’s sso_token to the IdP and receives a new JWT preserving the user’s identity.
On-Behalf-Of (OBO) — the user’s token is forwarded directly or exchanged via an OBO flow, depending on the IdP configuration.

The connection named in app_id must already be registered in watsonx Orchestrate before the agent is imported. How it works When app_id is set to a connection name, watsonx Orchestrate obtains a user-scoped token from that connection before invoking the A2A agent. The token is forwarded in the Authorization: Bearer <token> header of every request to the A2A agent, allowing it to call downstream services with the original user’s identity rather than the platform service identity. The full flow (shown here using RFC 8693 token exchange as an example) involves the following steps:

User login — the custom web app runs an OIDC Authorization Code + PKCE flow against the IdP. The resulting user access token is stored server-side in the session.
wxO JWT minting — the web app builds a signed RS256 JWT for watsonx Orchestrate. The user’s access token is encrypted with watsonx Orchestrate’s RSA public key and placed in the user_payload.sso_token field. This JWT is passed to the embedded chat widget as wxOConfiguration.token.
Token exchange — when the user sends a message that triggers the A2A agent, watsonx Orchestrate uses the configured connection to obtain a user-scoped token (for example, by presenting the sso_token to the IdP as the subject_token in an RFC 8693 request). The IdP validates the token and issues a new JWT preserving the user’s identity (sub, email, group membership).
A2A agent invocation — watsonx Orchestrate places the user-scoped JWT in the Authorization: Bearer header and calls the A2A agent. The agent can then use this token to call downstream enterprise APIs on the user’s behalf.

Registering the A2A agent Set app_id in the agent definition to the name of the connection that should provide the user-scoped token. The example below uses a connection named verify_token_exchange of kind oauth_auth_token_exchange_flow:

YAML

spec_version: v1
kind: external
name: flights_agent
title: Flights Agent
style: react_core
nickname: flights_agent
provider: external_chat/A2A/0.3.0
description: |
  A2A Flights Agent — searches for available flights and returns user profile
  using IBM Verify token-exchange (oauth_auth_token_exchange_flow).
tags:
  - flights
  - travel
api_url: "${A2A_SERVER_URL}"
app_id: verify_token_exchange      # name of the connection that provides the user-scoped token (oauth_auth_token_exchange_flow or OBO)
chat_params:
  sendHistory: false
  stream: true
  pushNotifications: false
config:
  hidden: false

Receiving and validating the token in the A2A agent The A2A agent receives the exchanged JWT in the Authorization: Bearer header. The agent should:

Extract the bearer token from the Authorization header.
Fetch the IdP’s JWKS endpoint and verify the JWT signature (RS256).
Validate the exp, iss, and aud claims as appropriate for your environment.
Extract user identity and group/role membership from the JWT claims.

IBM Verify token-exchange tokens may omit the kid header field. If your JWT library requires a kid to look up the signing key, fall back to iterating all keys in the JWKS set. Claim shapes for group membership vary across IdP configurations. Check all three locations: groupIds[].displayName (Verify SCIM groups), groups[] (flat string array), and roles[] (flat string array). Environment variables required in the A2A agent

Variable	Purpose
`JWKS_URI`	IdP JWKS endpoint used to verify the exchanged JWT signature (e.g. `https://<tenant>.verify.ibm.com/v1.0/endpoint/default/jwks`)
`JWT_ISSUER`	Expected `iss` claim in the exchanged JWT (optional; if unset, issuer check is skipped)
`JWT_AUDIENCE`	Expected `aud` claim (optional; if unset, audience check is skipped)

app_id is supported for A2A agents only (provider: external_chat/A2A/<version>). It works with any connection type that produces a user-scoped token, including oauth_auth_token_exchange_flow (RFC 8693 token exchange) and OBO connections. The connection must be registered in your watsonx Orchestrate environment before the agent is imported.

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:

YAML

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.

WXO supports the A2A protocol only over JSON-RPC 2.0 on HTTP. Although A2A can use multiple transport protocols, this implementation is limited to JSON-RPC 2.0.

Import external agents from a URL

Use the orchestrate agents discover command to retrieve and import external agents without manually defining the full agent configuration. You can discover agents in two ways:

By using a URL that hosts an A2A agent card (--url). This is described in this section.
By using a cloud provider connection (--provider). Supported providers are bedrock_agent, azure_ai_foundry, and vertex_agent. For more information, see Discover agents from cloud providers.

Use a URL that hosts an agent card to retrieve and import an external agent. This approach removes the need to manually define the full agent configuration when the external agent already exposes its metadata. External agents that follow the A2A protocol typically publish an agent card at a well-known endpoint. The default location is .well-known/agent-card.json. The discovery command uses this endpoint unless a custom endpoint is provided. After the agent is discovered, the configuration is retrieved and the agent can be exported and saved locally. The exported agent can then be imported and used like other external agents.

Discover an agent by using the default endpoint

BASH

orchestrate agents discover -u https://example.com

Discover an agent by using a custom endpoint

Use a custom endpoint when the agent card is not located at the default path.

BASH

orchestrate agents discover -u https://example.com -e .well-known/agent-card-2.json

Discover an agent by using a connection for authentication

Some external agents require authentication. Provide a connection to retrieve the agent configuration.

BASH

orchestrate agents discover -u https://example.com -a my-a2a-connection

Discover an agent by using a custom name

Override the agent name defined in the agent card.

BASH

orchestrate agents discover -u https://example.com -n my_custom_agent -a my-a2a-connection

Command behavior

Retrieves agent configuration from a URL that hosts an agent card.
Uses .well-known/agent-card.json as the default endpoint.
Supports custom endpoints for environments that expose multiple agents or non-standard paths.
Supports authenticated access through a configured connection.
Allows overriding the agent name during discovery.
Enables exporting the discovered agent for local use and later import into an environment.

Discover agents from cloud providers

Use the --provider flag to discover agents that are hosted on a cloud provider and register them in watsonx Orchestrate. The command uses the credentials stored in a connection to list the agents available to you, and then registers the agents that you select as external agents.

BASH

orchestrate agents discover \
  --provider <bedrock_agent | azure_ai_foundry | vertex_agent> \
  --app-id <connection-name> \
  [--name <agent-name>] \
  [--yes]

Flag	Description
`--provider`	The cloud provider to discover agents from. Supported values: `bedrock_agent`, `azure_ai_foundry`, `vertex_agent`.
`--app-id`, `-a`	The `app_id` of the connection that holds the provider credentials.
`--name`, `-n`	Only register discovered agents whose display name matches this value. Repeat the flag to select multiple agents. For more information, see Filter discovered agents by name.
`--yes`, `-y`	Skip the confirmation prompt and register all discovered agents. Use this flag for non-interactive and CI/CD usage. Supported for the `bedrock_agent` and `vertex_agent` providers.

Create and configure the connection before you run the discovery command. For more information, see Build connections.

Filter discovered agents by name

The --name flag is repeatable. Matching is case-insensitive and is performed against the display name of the agent in the provider. If a --name value does not match any discovered agent, the CLI displays a warning for that value.

BASH

orchestrate agents discover \
  --provider bedrock_agent \
  --app-id my-bedrock-conn \
  --name "Customer Support" \
  --name "Sales Assistant"

Agent names in watsonx Orchestrate

Discovered agent names are converted to watsonx Orchestrate-compatible names by applying the following rules:

The name is converted to lowercase.
Spaces and hyphens are replaced with underscores.
Any character that is not a-z, 0-9, or _ is replaced with an underscore.
The name is truncated to 64 characters.
If the result is empty, a fallback name is used: bedrock_agent_<id> for AWS Bedrock, azure_agent_<id> for Microsoft Azure AI Foundry, and vertex_agent_<last-segment-of-resource-path> for Google Vertex.

For example, the agent Customer Support-Bot is registered as customer_support_bot.

Discover AWS Bedrock agents

Discover agents from Amazon Bedrock and register them in your watsonx Orchestrate workspace. Prerequisites Install the ADK with the aws extra. Discovery uses AWS Signature Version 4 (SigV4) signing, which requires the botocore package. If the package is missing, the command fails with ImportError: The 'botocore' package is required for AWS Bedrock agent discovery.

BASH

pip install 'ibm-watsonx-orchestrate[aws]'

You also need valid AWS IAM credentials that are allowed to list Bedrock agents (bedrock:ListAgents). The CLI signs all requests to AWS for you.

Availability: SaaS environments only. AWS Bedrock agent discovery is not available in Developer Edition or on-premises (CPD) environments.

Step 1: Configure AWS Bedrock connection credentials Store your AWS credentials in a key_value connection. The connection supports the following entries:

Entry key	Required	Description
`region`	Yes	The AWS region, for example `us-east-1`.
`access_key_id`	Yes	The AWS access key ID.
`secret_access_key`	Yes	The AWS secret access key.
`session_token`	No	The AWS STS session token. Required only when you use temporary credentials, such as an assumed role.

BASH

# 1. Create the connection
orchestrate connections add --app-id my-bedrock-conn

# 2. Configure it as a team key_value connection in draft
orchestrate connections configure \
  --app-id my-bedrock-conn \
  --kind key_value \
  --type team \
  --environment draft

# 3. Store the credentials
orchestrate connections set-credentials \
  --app-id my-bedrock-conn \
  --environment draft \
  --entries region=us-east-1 \
  --entries access_key_id=<your-access-key-id> \
  --entries secret_access_key=<your-secret-access-key>

To use temporary credentials, add --entries session_token=<your-session-token> to the set-credentials command. Step 2: Discover and register agents Discover and register all agents:

BASH

orchestrate agents discover \
  --provider bedrock_agent \
  --app-id my-bedrock-conn

The CLI displays a table of discovered agents and prompts for confirmation before registration. To skip the prompt in scripts and CI/CD pipelines, add the --yes flag:

BASH

orchestrate agents discover \
  --provider bedrock_agent \
  --app-id my-bedrock-conn \
  --yes

Discover specific agents by name:

BASH

orchestrate agents discover \
  --provider bedrock_agent \
  --app-id my-bedrock-conn \
  --name "Customer Support"

Step 3: Verify registered agents

BASH

orchestrate agents list

Discovered agents appear with provider: bedrock_agent and can be configured as collaborators for your native agents.

Discover Microsoft Azure AI Foundry agents

Discover agents deployed in Microsoft Azure AI Foundry and register them in your watsonx Orchestrate workspace. Authentication uses a Microsoft Entra ID service principal with the OAuth 2.0 client credentials flow.

Availability: SaaS environments only. Azure AI Foundry discovery is not available in Developer Edition or on-premises (CPD) environments.

Step 1: Configure Azure AI Foundry connection credentials Store your Microsoft Azure credentials in a key_value connection. The connection requires five entries:

Entry key	Description
`tenant_id`	Microsoft Entra ID (Azure AD) tenant ID.
`client_id`	Service principal (app registration) client ID.
`client_secret`	Service principal client secret.
`endpoint`	Azure AI Foundry resource endpoint, for example `https://<resource-name>.services.ai.azure.com`.
`project_name`	Azure AI Foundry project name.

BASH

# 1. Create the connection
orchestrate connections add --app-id azure-conn

# 2. Configure it as a team key_value connection in draft
orchestrate connections configure \
  --app-id azure-conn \
  --kind key_value \
  --type team \
  --environment draft

# 3. Store the credentials
orchestrate connections set-credentials \
  --app-id azure-conn \
  --environment draft \
  --entries tenant_id=00000000-0000-0000-0000-000000000000 \
  --entries client_id=11111111-1111-1111-1111-111111111111 \
  --entries client_secret=<your-client-secret> \
  --entries endpoint=https://my-resource.services.ai.azure.com \
  --entries project_name=my-project

Step 2: Discover and register agents Discover and register all agents in the project:

BASH

orchestrate agents discover \
  --provider azure_ai_foundry \
  --app-id azure-conn

The CLI displays a table of discovered agents and prompts for confirmation before registration. Discover specific agents by name:

BASH

orchestrate agents discover \
  --provider azure_ai_foundry \
  --app-id azure-conn \
  --name "Customer Support" \
  --name "Sales Assistant"

Step 3: Verify registered agents

BASH

orchestrate agents list

Discovered agents appear with provider: azure_ai_foundry and can be configured as collaborators for your native agents.

Discover Google Vertex agents

Discover agents hosted on Google Vertex and register them in your watsonx Orchestrate workspace by using the vertex_agent provider.

Availability: SaaS environments only. Google Vertex agent discovery is not available in Developer Edition or on-premises (CPD) environments.

Step 1: Configure Google Vertex connection credentials Store your Google Cloud credentials in a key_value connection. The connection requires three entries:

Entry key	Description
`service_account_json`	The full Google service account JSON, as a string.
`project_id`	The GCP project ID.
`location`	The GCP region, for example `us-central1`.

BASH

# 1. Create the connection
orchestrate connections add --app-id my-vertex-conn

# 2. Configure it as a team key_value connection in draft
orchestrate connections configure \
  --app-id my-vertex-conn \
  --kind key_value \
  --type team \
  --environment draft

# 3. Store the credentials
orchestrate connections set-credentials \
  --app-id my-vertex-conn \
  --environment draft \
  --entries service_account_json='<service-account-json>' \
  --entries project_id=<your-project-id> \
  --entries location=us-central1

Step 2: Discover and register agents

BASH

orchestrate agents discover \
  --provider vertex_agent \
  --app-id my-vertex-conn

The CLI displays a table of discovered agents and prompts for confirmation before registration. Use the --name flag to select specific agents, or the --yes flag to skip the confirmation prompt:

BASH

orchestrate agents discover \
  --provider vertex_agent \
  --app-id my-vertex-conn \
  --name "Customer Support" \
  --yes

Step 3: Verify registered agents

BASH

orchestrate agents list

Discovered agents appear with provider: vertex_agent and can be configured as collaborators for your native agents.

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]
)

In Microsoft Copilot Studio, navigate to your agent settings and select No authentication under agent settings. No authentication setting

Obtain your bot secret from Security → Web channel security in the Copilot Studio interface.

Configure your external agent YAML file with the following parameters:

provider: Always set to microsoft_copilot_studio.
api_url: The Direct Line API endpoint. For most users, this is https://directline.botframework.com/v3/directline. This may vary slightly based on your region.
auth_scheme: Set to NONE since authentication is handled through the bot secret.
auth_config.bot_secret: The bot secret obtained from Web channel security settings.
chat_params.token_endpoint: The token generation endpoint. For most users, this is https://directline.botframework.com/v3/directline/tokens/generate. This may vary slightly based on your region.

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.

YAML

spec_version: v1
kind: external
name: copilot_studio_agent
title: Copilot Studio Agent
provider: microsoft_copilot_studio
description: |
  A Microsoft Copilot Studio agent exposed through Direct Line.

api_url: https://directline.botframework.com/v3/directline
auth_scheme: NONE

auth_config:
  bot_secret: <your-bot-secret>

chat_params:
  token_endpoint: https://directline.botframework.com/v3/directline/tokens/generate
  # timeout_seconds: 180
  # poll_interval: 0.5
  # stream_chunk_size: 40
  can_collaborate: false

config:
  hidden: false
  enable_cot: false

JSON

{
  "spec_version": "v1",
  "kind": "external",
  "name": "copilot_studio_agent",
  "title": "Copilot Studio Agent",
  "provider": "microsoft_copilot_studio",
  "description": "A Microsoft Copilot Studio agent exposed through Direct Line.\n",
  "api_url": "https://directline.botframework.com/v3/directline",
  "auth_scheme": "NONE",
  "auth_config": {
    "bot_secret": "<your-bot-secret>"
  },
  "chat_params": {
    "token_endpoint": "https://directline.botframework.com/v3/directline/tokens/generate",
    "can_collaborate": false
  },
  "config": {
    "hidden": false,
    "enable_cot": false
  }
}

Python

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

my_agent = ExternalAgent(
    name="copilot_studio_agent",
    kind=AgentKind.EXTERNAL,
    provider=AgentProvider.MICROSOFT_COPILOT_STUDIO,
    title="Copilot Studio Agent",
    description="A Microsoft Copilot Studio agent exposed through Direct Line.",
    api_url="https://directline.botframework.com/v3/directline",
    auth_scheme=ExternalAgentAuthScheme.NONE,
    auth_config={
        "bot_secret": "<your-bot-secret>"
    },
    chat_params={
        "token_endpoint": "https://directline.botframework.com/v3/directline/tokens/generate",
        "can_collaborate": False
    },
    config={
        "hidden": False,
        "enable_cot": False
    }
)

# 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]
)

LangGraph agent

You can import LangGraph agents directly into watsonx Orchestrate. During the upload process, Orchestrate applies the Agent to Agent protocol behind the scenes to make the agent compatible with the platform. You use the same streamlined experience that you use for Python agents or MCP agents. A2A‑enabled LangGraph agents support lifecycle tasks such as update, delete, and export. For a detailed description of how to import LangGraph agents, see Importing LangGraph agents. Limitations:

Supported for Python implementations only.
Agents that are run inside the watsonx Orchestrate environment with the required isolation.
Supports only messages in the agent graph between turns, so complex custom state objects get lost between turns.

Example:

PYTHON

"""
Simple Agent: No LLM - Hello World
A simple agent that returns a static "Hello World" message without using any LLM.
"""
from typing import Annotated, List, TypedDict
from langchain_core.messages import AIMessage, BaseMessage
from langchain_core.runnables.config import RunnableConfig
from langgraph.graph import StateGraph, START, END


class AgentState(TypedDict):
    """Simple state with just messages."""
    messages: Annotated[List[BaseMessage], "conversation history"]


def hello_world_node(state: AgentState) -> AgentState:
    """
    Node that returns a static Hello World message.
    No LLM involved - just returns a hardcoded response.
    """
    # Get the last user message if available
    user_message = ""
    if state["messages"]:
        user_message = state["messages"][-1].content
    
    # Create a simple response
    response = AIMessage(
        content=f"Hello World! I received your message: '{user_message}'. "
                f"I'm a simple test agent with no LLM - I just return this static message."
    )
    
    return {"messages": state["messages"] + [response]}


def create_agent(config: RunnableConfig) -> StateGraph:
    """
    Factory function that creates and returns a LangGraph StateGraph.
    This agent has no LLM and just returns a static message.
    
    Args:
        config: Runtime configuration (not used in this simple agent)
    
    Returns:
        StateGraph: The compiled agent graph
    """
    # Build a simple linear graph: START -> hello_world -> END
    workflow = StateGraph(AgentState)
    workflow.add_node("hello_world", hello_world_node)
    workflow.add_edge(START, "hello_world")
    workflow.add_edge("hello_world", END)
    
    return workflow


if __name__ == "__main__":
    # Test the agent locally
    from langchain_core.messages import HumanMessage
    
    app = create_agent({}).compile()
    
    # Test 1: Simple message
    result = app.invoke({"messages": [HumanMessage(content="Hi there!")]})
    print("Test 1 - Simple message:")
    print(result["messages"][-1].content)
    print()
    
    # Test 2: Different message
    result = app.invoke({"messages": [HumanMessage(content="What can you do?")]})
    print("Test 2 - Different message:")
    print(result["messages"][-1].content)

This capability is supported through the A2A protocol.

Configuring checkpointers

Checkpointers persist agent state so you can resume execution and maintain context. Choose the checkpointer that fits your environment and persistence needs, then add its configuration to the checkpointer section of the agent YAML file.

Memory (development or testing)
SQLite
PostgreSQL (production)
No checkpointer (stateless)

Use in-memory storage to persist state during execution. State resets when the process restarts.

YAML

checkpointer:
  type: memory

Example:

spec_version: v1
kind: agent
name: my-agent
title: My LangGraph Agent
description: Agent with PostgreSQL state persistence
framework: langgraph

deployment:
  code_bundle:
    entrypoint: "main:create_graph"

checkpointer:
  type: memory

Use a local SQLite file to persist state. State resets when the agent pod restarts.

YAML

checkpointer:
  type: sqlite

Requirements:

Add langgraph-checkpoint-sqlite to the agent requirements.txt file.

Example:

spec_version: v1
kind: agent
name: my-agent
title: My LangGraph Agent
description: Agent with PostgreSQL state persistence
framework: langgraph

deployment:
  code_bundle:
    entrypoint: "main:create_graph"

checkpointer:
  type: sqlite

Use PostgreSQL to persist state across restarts and deployments.

YAML

checkpointer:
  type: postgres
  connection_string_key: db_connection_string

Requirements:

Add langgraph-checkpoint-postgres to the agent requirements.txt file.
Add the PostgreSQL connection to the file.

Example:

spec_version: v1
kind: agent
name: my-agent
title: My LangGraph Agent
description: Agent with PostgreSQL state persistence
framework: langgraph

deployment:
  code_bundle:
    entrypoint: "main:create_graph"

checkpointer:
  type: postgres
  connection_string_key: db_connection_string

Exclude the checkpointer section to run the agent without state persistence.

Notes:

The connection_string_key maps to a credential entry that stores the database connection string. Choose API key as the connection type and enter the connection string as the value.
For SQLite and PostgreSQL, the system manages database connections and schema setup automatically.
The memory checkpointer requires no credentials or additional configuration.

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. For a full explanation of how context variables work, including delivery methods, precedence, scope, persistence strategies, and channel limitations, see Context variables. 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.
For external A2A agents, the context variables defined are accessible in the metadata of the message object.

System and custom variables

Context variables are either system variables or custom variables. System variables use the reserved wxo_ prefix and are populated automatically by the platform on every run. Custom variables are defined and supplied by your application. For details, see Types of context variables.

Naming convention for context variables

Follow the standard naming rules for custom context variables. For details, see Naming rules.

Scope and persistence

Context is scoped to a single run and is not persisted across turns in a thread. For details and persistence strategies, see Persisting context across turns.

Channel support

Channels might not support context-variable propagation. For details, see Channel support.

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

object

default:"false"

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

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

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

Deploy

Analyze

Developer experience

Legal notices

External Agents

Providers

External Chat (Chat Completions API)

Agent to Agent (A2A) Protocol

Import external agents from a URL

Discover an agent by using the default endpoint

Discover an agent by using a custom endpoint

Discover an agent by using a connection for authentication

Discover an agent by using a custom name

Command behavior

Discover agents from cloud providers

Filter discovered agents by name

Agent names in watsonx Orchestrate

Discover AWS Bedrock agents

Discover Microsoft Azure AI Foundry agents

Discover Google Vertex agents

watsonx AI Agent Builder

Salesforce AgentForce

LangGraph agent

Configuring checkpointers

External watsonx Assistants

IBM Cloud

AWS

Additional features of external agents

Providing access to context variables

System and custom variables

Naming convention for context variables

Scope and persistence

Channel support

Restricting Agents

​External Agents

​Providers

​External Chat (Chat Completions API)

​Agent to Agent (A2A) Protocol

​Import external agents from a URL

Discover an agent by using the default endpoint

Discover an agent by using a custom endpoint

Discover an agent by using a connection for authentication

Discover an agent by using a custom name

​Command behavior

​Discover agents from cloud providers

Filter discovered agents by name

Agent names in watsonx Orchestrate

Discover AWS Bedrock agents

Discover Microsoft Azure AI Foundry agents

Discover Google Vertex agents

​watsonx AI Agent Builder

​Salesforce AgentForce

​LangGraph agent

Configuring checkpointers

​External watsonx Assistants

​IBM Cloud

​AWS

​Additional features of external agents

​Providing access to context variables

System and custom variables

Naming convention for context variables

Scope and persistence

Channel support

​Restricting Agents

External Agents

Providers

External Chat (Chat Completions API)

Agent to Agent (A2A) Protocol

Import external agents from a URL

Command behavior

Discover agents from cloud providers

watsonx AI Agent Builder

Salesforce AgentForce

LangGraph agent

External watsonx Assistants

IBM Cloud

AWS

Additional features of external agents

Providing access to context variables

Restricting Agents