Adding AI assistants to the AI chat
Use purpose-built AI assistants from various sources to complete specific tasks and run skills. You can add various AI assistants to the AI chat to help your users to resolve specific use-cases.
When you add AI assistants, consider adding descriptions that are specialized for each one. This way, the system can better determine which AI assistant is best suited to help a particular user.
Before you begin
Comply with the following steps and their requirements before you add and use AI assistants from the following sources:
- AI assistant builder
- IBM watsonx Assistant instance
- AI agent from third-party platform
AI assistants
1. Create an AI assistant
Create an AI assistant in the AI assistant builder or in the IBM watsonx Assistant product.
2. Create actions in the AI assistant
Create the actions that are needed to handle conversations in the AI assistant. If you want to use skill-based actions, you must connect to the apps that hold the skills that you want to use.
3. Publish the contents of the AI assistant
Publish the contents of the AI assistant to the draft and live environments.
4. Add the AI assistant to the chat
Add the AI assistant from the AI assistant builder or from the IBM watsonx Assistant to the AI chat by following the procedures in the next sections.
The AI assistants that you add to the chat are available to all users in the tenant. The AI assistants from the AI assistant builder are tenant-specific. If you want to add the AI assistants from another tenant, consider creating a new AI assistant with the same capabilities in the wanted tenant.
AI assistants from external AI agents
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 AI assistants from the AI assistant builder
Add the AI assistants that you publish from the AI assistant builder to the AI chat:
-
From the menu
, go to Agent configuration.
-
Click the Add assistant button, and go to the Published Assistants tab.
-
Select an assistant by clicking the drop-down list in Choose assistant.
Important: Only published and live AI assistants appear on the drop-down list. Confirm that the AI assistant you want to add was published and is live.
-
In the Display name, enter the display name of the AI assistant.
-
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 Guidelines to describe your AI assistant's capabilities section.
-
Click the Connect button.

Adding AI assistants from IBM watsonx Assistant
Add the AI assistants that you publish from an IBM watsonx Assistant instance to the AI chat:
- From the menu
, go to Agent configuration.
- Click the Add assistant button, and go to the External Assistant tab.
- In the Choose assistant type, click watsonx Assistant.
- In the Display name, enter the display name of the AI assistant.
- 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 Guidelines to describe your AI assistant's capabilities section.
- 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.
- 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.
- 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. - 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.
- 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.
- Click the Connect button.

Adding AI assistants from external AI agents
Add the AI assistants from the AI agents that you have in third-party platforms to the AI chat:
- From the menu
, go to Agent configuration.
- Click the Add assistant button, and go to the External Assistant tab.
- In the Choose assistant type, click External-agent Assistant.
- In the Display name, enter the display name of the AI assistant.
- 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 AI assistant that helps the users. For guidance on writing descriptions, see the Guidelines to describe your AI assistant's capabilities section.
- In the Authentication type, select
Bearer token
orAPI key
. - In the API key, enter the API key that is generated in 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 the Connect button.
Guidelines to describe your AI assistant's capabilities
When you create a description for your specialized AI assistant, consider the following factors to ensure that the AI model can best evaluate which AI assistant would help your users:
-
Domain expertise
Clearly outline the domain or topic that the AI assistant specializes in. Use keywords that are related to the domain. -
Features and strengths
Highlight unique features and strengths that the AI assistant possesses, and consider the user intentions when they prompt for the AI assistant. -
Limitations and scope
Define the limits that the AI assistant 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 AI assistant's purpose and capabilities.
Example:
HRAssistant is a tool 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.
Editing an AI assistant
After you add the AI assistants to the AI chat, you can edit them:
- Expand a row in the accordion to show details about the current AI assistant and to reveal the Edit button.
- Click Edit to change the description of the AI assistant.
- Click Apply changes to save changes to the AI assistant.
Hiding the AI assistants from the chat
Control the AI assistant’s visibility in the AI chat. By default, assistants remain visible. Disabling the Show in chat toggle hides the AI assistant from users when they type @.
However, the AI assistant can still route responses if a user’s question matches its description. In this case, the response appears to come from the default assistant, such as watsonx, instead of the hidden assistant. Routing to hidden AI assistants happens seamlessly without confirmation prompts.
Disconnecting an AI assistant
Disconnecting an AI assistant means that this AI assistant is no longer available for all users in the watsonx Orchestrate chat.
Even though the AI assistant is disconnected, the chat history with this AI assistant remains. However, any in-progress chats end immediately. To disconnect the AI assistant from the chat environment, you must do the following:
- Expand a row in the accordion to show details about the current AI assistant and to reveal.
- Click the Edit button.
- Click the Disconnect button from the Assistants page.

Enter the name of the AI assistant in the Confirmation field. Click Remove to disconnect the AI assistant from the chat.

Viewing the AI assistants added to the chat
View the AI assistants that are added to the watsonx Orchestrate chat and their details:
-
From the chat page, click Assistants.
Figure 5. Viewing the AI assistants added to the chat. -
From the list of AI assistants, choose the AI assistant that you want to open. The selected row in the accordion shows the description of the AI assistant.
-
Type on the chat bar to start the conversation. Use a specific AI assistant by mentioning its name, or expect the system to route the conversation to an AI assistant based on the conversation context. For more information, see Using purpose-built AI assistants.
Parent topic: