Adding agents for orchestration

Agents in IBM watsonx Orchestrate can collaborate using multi-agent orchestration to complete tasks across various channels. You can add multiple collaborator agents from various sources, such as prebuilt and custom agents built by IBM and your team, agents from third-party platforms and watsonx.ai, and AI assistants from IBM watsonx Assistant instances.

Collaborator agents are computational systems where multiple autonomous agents interact or work together to complete specific tasks or achieve common goals. These agents can learn reasoning and decision-making.

Adding collaborator agents helps you to have domain-focused agents that are designed to operate within a specific field or industry. These agents possess deep knowledge and expertise in their respective domains, which allows them to complete tasks more efficiently and accurately.

With collaborator agents, you can:

  • Divide tasks among multiple agents to complete complex tasks more efficiently than a single large system.
  • Scale by adding agents to handle more tasks or larger workloads.
  • Enable the system to handle a broader range of tasks and adapt to changing conditions by leaving agents to carry out tasks independently.
  • Gather insights from employee or customer communication, so agents can build upon key ideas for better performance.

Planning agents for collaboration and orchestration

Agents with collaborator agents operate independently and decide based on local information and interactions without a central authority.

An agent can have collaborators, and those collaborators can also have their own collaborators. This collaboration creates a network of interconnected agents. The initial agent can call upon all these collaborator agents to delegate the task execution to one another.

Using collaborator agents effectively requires careful planning and implementation:

Define clear objectives: Clearly define what you want to achieve with collaborator agents. Whether it's improving customer service, optimizing supply chains or enhancing data analysis, having specific goals to guide the implementation process.

Design the system: Plan the multi-agent system, including the roles and capabilities of each agent.

Choose the right agents: Choose agents that are suited to the tasks at hand. Consider their capabilities, compatibility with existing systems, and how they can be integrated into your workflows.

Foster human-agent collaboration: Promote a culture where human employees and agents work together seamlessly.

Plan for scalability: Ensure that your multi-agent system can scale as your business grows, which include you to be able to add more agents or expand their capabilities without significant overhauls.

Adding a collaborator agent

  1. On the agent edit page, click Toolset > Add agent.
  2. Choose from where you want to add the agent:
    1. Add from the catalog.
    2. Add from local instance.
    3. Import from external sources.

Adding an agent from the catalog

Adding an agent from the catalog opens the Catalog view. In the Catalog, you can search and use the prebuilt agents available.

For a complete list of the prebuilt agents available, see List of prebuilt agents.

Upcoming availability of agents and tools within the Catalog

Complete the following form to request access to prebuilt agents and tools: Preview access request form

After approval, the agents and tools for productivity, HR, procurement and sales will be available in a few days. In the meantime, you can explore the following options within the product to continue your activities smoothly:

  • Explore the list of agents and tools: Get more information on the use cases that the agents for productivity, HR, procurement and sales can cover. For more information, see List of prebuilt agents.
  • Create your own tools: Use the IBM watsonx Orchestrate Agent Development Kit to easily create tools programmatically. For more information, see Creating your first agent on agent builder.
  • Build your own agents: Use the agent builder to build custom agents based on your business knowledge, tools, or other agents that you add for multi-agent orchestration. For more information, see Creating agents.

Adding an agent from local instance

Adding an agent from local instance opens a view of the agents that the members of your watsonx Orchestrate instance created. Search and select one or more agents, and click Add to agent to finish.

The external agents that the members of the instance connect are shared across all users within the same instance.

Adding an agent from external platforms

Important: External agents can be used as collaborator agents only. The connections established to external agents are available within the local instance, so you can reuse them in other agents.

Add an agent by importing it from external platforms:

  1. From the agent edit page, click Toolset > Add agent > Import, then select the type of agent that you want to register, and click Next:

Add an external agent using the Agent development kit (ADK):

  1. You can use the ADK to designate an external A2A agent as a collaborator for native agents.

Adding agents from third-party platforms

Add agents from third-party platforms as a collaborator agent:

  1. From Provider, select External agent.

  2. In the Authentication type, select Bearer token or API key:

    • In the Bearer token, enter the Bearer token.
    • In the API key, enter the API key.

    You get the authentication data from the platform where the external AI agent is hosted.

  3. In the Service instance URL, enter the URL to connect to the server where the external AI agent is hosted.

  4. In the Display name, enter the display name of the agent.

  5. In the Description of agent capabilities, enter a description of what it can do to help your users. The description must contain the most used keywords that enable the system to determine the better agent that helps the users. For guidance on writing descriptions, see the Recommendations for agent descriptions section.

  6. Click Import agent.

Adding agents from watsonx.ai

Add agents from Agent Lab in watsonx.ai as collaborator agents.

Requirements

Comply with the following requirements to add agents from watsonx.ai:

  • You must have access to IBM Cloud and IBM watsonx.ai.
  • Create an agent through the Agent Lab in watsonx.ai and deploy the agent as an AI service. For more information about how to create agents, see Getting started with Agent Lab in the IBM watsonx as a Service documentation.

Getting the public endpoint from watsonx.ai

Get the public endpoint to connect to a deployed agent:

  1. In the watsonx.ai home screen, click the menu > Deployments.
  2. Click the deployed agent, and go to the API reference tab.
  3. In the Public endpoint, select the endpoint that has "ai_service_stream" as part of the URL path. For instance, the endpoint looks like "https://us-south.ml.cloud.ibm.com/ml/v4/deployments/{deploymment_id}/ai_service_stream?version=2021-05-01".
  4. Save this public endpoint.

Creating the API key

Create an API key for your deployed agent as an AI service. For more information about how to create and manage your API key, see Creating an API key in the console in Managing your account, resources, and access for IBM Cloud.

Save the API key.

Adding the agent as a collaborator

Add agents from watsonx.ai as a collaborator agent in the agent builder:

  1. From Provider, select watsonx.ai.
  2. In the Authentication type, select API key.
  3. In the API key, enter the API key that you saved.
  4. In the Service instance URL, enter the public endpoint that you copied from deployed agent within watsonx.ai.
  5. In the Display name, enter the display name of the agent.
  6. In the Description of agent capabilities, enter a description of what it can do to help your users. The description must contain the most used keywords that enable the system to determine the better agent that helps the users. For guidance on writing descriptions, see the Recommendations for agent descriptions section.
  7. Click Import agent.

Adding IBM watsonx Orchestrate assistants as collaborator agents

Add assistants from IBM watsonx Orchestrate as collaborator agents:

  1. From Available assistants, select the assistant you want to use as a collaborator.

  2. Type a new Display name for your collaborator agent.

    Agent collaborator names must be unique and meet the following criteria:

    • The name must be at least 3 characters long and no more than 128 characters.
    • The name can include letters, digits, hyphens (-), and underscores (_), but it cannot start with a digit.
    • The same name cannot be reused on another collaborator agent.

  3. In Description, enter a description of what the assistant can do to help your users. The description must contain the most used keywords that enable the system to determine the better agent that helps the users. For guidance on writing descriptions, see the Recommendations for agent descriptions section.

  4. Click Import agent.

Adding AI assistants as agents

The option to add AI assistants as collaborator agents is limited to:

  • AI assistants that you publish from an instance of the IBM watsonx Assistant product.

  • AI assistants that you publish from the AI assistant builder.

    Important: If you want to add AI assistants from the AI assistant builder, the AI assistant must meet the following prerequisites:
    • It must be hosted on IBM watsonx Orchestrate on IBM Cloud. Adding AI assistants from IBM watsonx Orchestrate on AWS is not supported.
    • It must be sourced from instances other than the instance that you use to build the agent.

Add an AI assistant as a collaborator agent in the agent builder:

  1. In the API key, enter the API key to connect to your instance. From the IBM Cloud console, search for your IBM watsonx Assistant service, and click it. In the Credentials section, copy the value from the API key field.
  2. In the Environment ID, enter the environment ID of the AI assistant. You can use the draft or the live environment of the AI assistant that you want to call through the AI agent.
  3. In the Version, enter the minor API version that you want to use when calling the AI assistant. The latest minor API version is 2024-08-25. You can find the list of API versions in the IBM watsonx Assistant release notes.
  4. In the Assistant ID, enter the assistant ID. From your IBM watsonx Assistant instance, go to the Assistant settings page. In the Assistant IDs and API details section, click View details, and copy the value from the Assistant ID field.
  5. In the Service instance URL, enter the service instance URL. From your IBM watsonx Assistant instance, go to the Assistant settings page. In the Assistant IDs and API details section, click View details, and copy the value from the Service instance URL field.
  6. In the Display name, enter the display name of the agent.
  7. In the Description of assistant capabilities, enter a description of what it can do to help your users. The description must contain the most used keywords that enable the system to determine the best AI assistant that helps the users. For guidance on writing descriptions, see the Recommendations for agent descriptions section.
  8. Click Import agent.

Adding external A2A agents using ADK

External agents that communicate using the Agent-to-Agent (A2A) protocol can be added as collaborators through the ADK. These A2A agents operate alongside native agents.

watsonx Orchestrate supports bearer token and API Key authentication types, processes only plain text input (excluding rich UI elements), and does not provide native task management integration for A2A agents.

Note: A2A agents can be added as collaborators only through ADK configuration.

Removing a collaborator agent

  1. In the Toolset section, go to the agent that you want to remove.
  2. Click the vertical ellipsis button overflow_menu > Remove.