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 built with and imported to the watsonx Orchestrate platform. They have the capability of following a set of instructions that tell the agent how it should respond to a user request.

The overall integrated prompting structure of the agent can be modified by using the style attribute. Currently, two styles are available: default and react. A native style agent relies on the intrinsic tool call abilities of the LLM, whereas a react style agent relies on the prompting strategy outlined by the ReAct paper.

Native agents have collaborators which are other agents, whether they be native agents, external agents, or external assistants, that this agent can communicate with to solve a users request.

The native agent’s description provides a user-facing description of the agent for the agent management UI and helps the agent decide when to consume this agent as a collaborator when it is added to the agent’s collaborator list.

spec_version: v1
kind: native
name: agent_name
llm: watsonx/ibm/granite-3-8b-instruct
style: default     
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 it's 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

​
External Agents

External agents are built outside watsonx Orchestrate and can be used as collaborators for native agents.

​
provider: external_chat

The external chat provider can be used to integrate agents from an external provider such as BeeAI, Langgraph, or CrewAI that a user hosts themselves, for example in Code Engine.

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

​
provider: wx.ai

It is also possible to integrate with agents built using watsonx.ai’s agent builder platform.

For more information, please see Registering agents from watsonx.ai here. However, rather than using the api, simply fill out the following yaml file and import your agent.

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"           
auth_config:
  token: "123"                   # this is 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

​
provider: salesforce

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

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

getting-started-salesforce.png

  1. On the create a token page, you find the following information, which will be the same across all your SalesForce agents in the instance:
  • Your api_url, it always be https://api.salesforce.com/einstein/ai-agent/v1.
  • Under auth_config, your token will be the CONSUMER_SECRET referenced in the guide.
  • Under chat_params.
    • Your client_id will be the CONSUMER_KEY.
    • Your domain_url will be the DOMAIN_URL.
    • Optionally, you can specify a list of display types to pass to orchestrate as a comma-separated string.
  1. 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 agents

To register assistants from watsonx Assistant, you need to 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

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

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