Adding agents from catalog

Edit online

You can add agents as collaborators from the catalog. The catalog includes prebuilt agents, external partner agents, and partner native agents. Use the interface to browse, search, and select agents that best fit your workflow.

Prebuilt agents: They are ready-to-use agents that are designed for common scenarios and tasks. They come with predefined configurations and capabilities, making it easy to integrate them into your workflows without extensive setup. See List of prebuilt agents for more details.

External agents from partners: These agents are developed outside watsonx Orchestrate and made available in the catalog by the providers. They offer flexibility and customization for specialized use cases. For more information, see External agents.

Partner native agents: These agents are developed by an external partner, such as Symplistic through watsonx Orchestrate’s Agent Development Kit (ADK). These agents are built directly within the watsonx Orchestrate platform. For more information, see Partner native agents.

Partner A2A agents: These agents are hosted and managed by an external partner. They allow watsonx Orchestrate to send tasks to an external agent and receive results back without user involvement. For more information, see Partner A2A (Agent2Agent) agents.

Before you begin

  • Make sure that you are editing an existing agent or creating a new agent.

  • Confirm that you have the required access role Admin or Builder.

  • If you plan to add an external partner or partner native agent, make sure that you have:

    • The External agent's URL

    • A bearer token or an API key from the partner service (depending on the authentication type you plan to select)

  • Some partner agents require a purchase before they can be added. These agents display a lock icon in the catalog. If you need to purchase and unlock a partner agent, see Purchasing partner agents.

Steps to add a collaborator agent from the catalog

To add an agent (prebuilt, external partner, or partner native) as a collaborator agent:

  1. In the agent configuration page, go to Toolset > Add agent > Add from catalog.

  2. Select the agent from the catalog view. View and analyze the agent overview and configuration details.

  3. Click Add as collaborator. The selected prebuilt agent is added as a collaborator.

  4. If the selected agent is an external partner, partner native agent, or partner A2A agent, register the agent:

i. Select Authentication type: Choose Bearer token or API key.

ii. Provide the following details:

  • External agent's URL: Enter the endpoint provided by the partner to connect to the external agent.

  • Display name: Provide a name for the agent.

  • Description of agent capabilities: Describe what the agent does and include relevant keywords to improve routing. See Recommendations for agent descriptions.

iii. View Advanced settings.

  • The UI displays advanced settings such as Support streaming, Support push notifications, and Send conversation history as disabled. You cannot edit these settings. Each setting includes a status label that shows whether the feature is on or off, based on the partner’s configuration.

iv. Click Register and add. The selected partner agent is added as a collaborator.

Retrieving the bearer token

To retrieve the bearer token:

  1. Register your application

Go to the API provider’s developer portal. Register your app to get a Client ID and Client Secret.

  1. Request an access token

Make a POST request to the token endpoint.

  1. Use the following sample cURL command:

   curl -location POST https://api.example.com/oauth/token  \

   --header 'Content-Type: application/x-www-form-urlencoded' \

   --header 'Authorization: Basic <ClientKey:ClientSecret>' \

   --header 'Accept: application/json' \

   --data-urlencode 'grant_type=client_credentials'

Copy the JWT(JSON Web Token) from the API response and use it as the bearer token to connect to watsonx Orchestrate.

Retrieving the API key

To retrieve the API key for a purchased agent service instance:

  1. After you purchase the agent service instance, it appears in the Resource list of your IBM Cloud account.

  2. From the Resource list, and select the service instance.

  3. In the service details page, locate the API key.

  4. Unmask to view the key, and then copy to use it when you register the agent in watsonx Orchestrate.

What to do next

After you add a collaborator agent: