Managing agents in the AI chat

Add agents with specialized tools, edit existing ones, or remove those agents that are no longer needed to customize the AI chat capabilities according to specific needs.

When you add agents, consider adding descriptions that are specialized for each one. This way, the system can better determine which agent is best suited to help a particular user.

Before you begin

The AI agent from the third-party platform must comply with the API contract provided by IBM watsonx Orchestrate. For the details of the API, see the operations of the External AI Agents method in the API documentation.

Adding external agents to the AI chat

Add agents from third-party platforms to the AI chat:

From the menu , go to AI agent configuration.
Click Agents > Add agent.
In the Display name, enter the display name of the agent.
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 Guidelines to describe your agent's capabilities section.
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.
In the Service instance URL, enter the URL to connect to the server where the external AI agent is hosted.
Click Add agent.

Registering agents from watsonx.ai

Register the AI agents that you build and deploy on the Agent Lab in IBM watsonx.ai to watsonx Orchestrate. You can configure the agent to decide and perform tasks on behalf of a user by using the parameters and tools you specify in the agent's settings.

Note:Registering the AI agent from Agent Lab in watsonx.ai with watsonx Orchestrate is possible only through the Register External Agent operation in the watsonx Orchestrate External Agent API .

Pre-requisites to register 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 by using Agent Lab guide.

To register the deployed agent through the External Agent endpoint, do the following steps:

Get the Public endpoint:
- Go to watsonx.ai home screen Navigation menu > Deployments.
- Click the deployed agent.
- Go to the API reference tab.
- Under the Public endpoint, select the endpoint that has ai_service_stream as part of the URL path. For reference, the endpoint looks like -
  https://us-south.ml.cloud.ibm.com/ml/v4/deployments/{deploymment_id}/ai_service_stream?version=2021-05-01.
- Save this Public endpoint.
Create an API key for your deployed agent as an AI service:
- You can create and manage your API key using this guide.
- Save the API key.
Register the agent from Agent Lab by using the API:

To register the AI agent with watsonx Orchestrate by using External Agent endpoint, ensure to set the following in the Request body:
- Set the api_url field to the Public endpoint that you copied from the API reference tab.
- Set the auth_scheme field to API_KEY.
- In auth_config, set the token field to the API key that you saved from Create an API key for your deployed agent as an AI service step.
- Set the provider field to wx.ai.

Users can view and mention agents in the AI chat as they do with AI assistants and skills. For more information, see Using the AI chat.

Editing an agent

After you add agents to the AI chat, you can edit them:

From the Agents page, expand the accordion of the wanted agent.
Click Edit to change the description of the agent.
Click Apply changes to save changes.

Guidelines to describe an agent's capabilities

When you create a description for your specialized agent, consider the following factors to ensure that the AI model can better evaluate which agent would help your users:

Domain expertise
Clearly outline the domain or topic that the agent specializes in. Use keywords that are related to the domain.
Features and strengths
Highlight unique features and strengths that the agent possesses, and consider the user intentions when they prompt for the agent.
Limitations and scope
Define the limits that the agent has and its scope of knowledge. Defining limitations and scope might help avoid misunderstandings.
Clear and simple language
Opt for simple, straightforward language to convey the agent's purpose and capabilities.

Example:

HRAgent is an agent that simplifies Human Resources (HR) tasks, from onboarding to offboarding. It understands and responds to a wide range of HR inquiries, which include: populating HR software systems, running workflows, validating local holidays, generating vacation reports. This tool has the following limitations: not a substitute for legal advice, not specialized on candidate sourcing and screening.

Showing or hiding agents from the AI chat

Control the visibility of different agents to manage the user interface, making it less cluttered or more intuitive, depending on the user's preference or the task at hand.

From the Agents page, expand the accordion of the wanted agent.
Set Show agent in chat to On to show the agent in the chat, or set it to Off to hide it from the chat.

Hiding agents from the AI chat make them unusable by the users. No routing or mention is possible for the specific agent.

Showing or hiding chain of thought (COT) from the AI chat

The chain of thought provides insight into the AI's decision-making process. Users might want to show the COT to understand how the AI concluded at a topic, which can be useful for learning, debugging, or ensuring transparency. Conversely, hiding it might be preferred for a cleaner interface or when the user trusts the AI's decisions without needing to see the reasoning.

The output formats from a chain of thought process can vary based on the complexity of the question and the depth of reasoning required. Agents within watsonx Orchestrate generate the trace of tool calls and their responses as a form of a chain of thought.

From the Agents page, expand the accordion of the wanted agent.
Set Show thinking in chat to On to see the agent reasoning in the chat, or set it to Off to hide it from the chat.

Disconnecting an agent

Disconnecting an agent means that this agent is no longer available for all users in the AI chat.

Even though the agent is disconnected, the chat history with this agent remains. However, any in-progress chats end immediately:

From the Agents page, expand the accordion of the wanted agent.
Click Edit > Disconnect from the agent page.
Enter the name of the agent in the Confirmation field. Click Remove to disconnect the agent from the chat.

What to do next

Users can view and mention agents in the AI chat as they do with AI assistants and skills. For more information, see Using the AI chat.