Integrating AI agents

An AI agent in the designer is used to call an AI agent built in IBM® watsonx™ Orchestrate®. watsonx Orchestrate AI agents provide powerful AI capabilities that you can integrate directly into your workflow automations. The designer provides a discovery mechanism to find the AI agent in watsonx Orchestrate that you want, and to generate an AI agent artifact in the designer.

In the designer, you can discover AI agents from watsonx Orchestrate. As the result of the discovery, an AI agent artifact is created in the designer.

The AI agent editor shows you relevant information about the AI agent and allows you to specify an API key that is used for invocation at runtime. In the runtime, this API key can be overwritten by an administrator by using the Operations REST API.

To call an AI agent, you use an AI agent activity in a service flow.

To discover an AI agent from watsonx Orchestrate and generate an AI agent artifact in the designer that you can use in a service flow, complete the following steps.

Before you begin

Before you can use this feature, you need to configure the AI agents integration. You need watsonx Orchestrate on Amazon Web Services (AWS).

Apply the following watsonx Orchestrate endpoint configurations:
- token-url: Used for authentication. For more information on how to obtain the token-url, see IBM watsonx Orchestrate API .
- service-instance-url: Used to access the watsonx Orchestrate instance during discovery. For more information on how to obtain the service-instance-url, see Getting the API endpoint.
Add the following configuration to your 100Custom.xml file.
```
<server> 
     <wxo merge="mergeChildren"> 
          <token-url>https://iam.platform.saas.ibm.com/siusermgr/api/1.0/apikeys/token</token-url> 
          <discovery> 
              <service-instance-url>https://api.<hostname>/instances/<tenant_id></service-instance-url> 
          </discovery> 
     </wxo> 
</server> 
```
Replace <hostname> and <tenant_id> with your specific environment values.
(Cloud Pak for Business Automation) Depending on your environment, use one of the following custom resource parameters to enable the 100Custom.xml snippet.
- For Workflow Authoring, use bastudio_custom_xml. For more information, see IBM Business Automation Workflow Authoring parameters.
- For Workflow Process Service Authoring, use lombardi_custom_xml_secret_name. For more information, see IBM Workflow Process Service Authoring parameters.
- For Workflow Runtime, use lombardi_custom_xml_secret_name. For more information, see IBM Business Automation Workflow Runtime and Workstream Services parameters.
- For Workflow Process Service Runtime, use lombardiXML. For more information, see CP4BA Workflow Process Service Runtime parameters.
(Business Automation Workflow on containers) Use the lombardi_custom_xml_secret_name custom resource parameter to enable the 100Custom.xml snippet. For more information, see Business Automation Workflow on containers authoring parameters and Business Automation Workflow on containers runtime parameters .
Make sure your Cloud Pak for Business Automation instance can access the watsonx Orchestrate instance.
Build or identify the AI agents in watsonx Orchestrate that you want to use in your workflows. For more information on creating AI agents, see Building agents.

Procedure

Discovering an AI agent

In the library navigation, go to Services > (+) > AI agent. If you are discovering AI agents for the first time, you are prompted to enter an API key. The key is used to retrieve available AI agents. To generate an API key, see Generating an API key.
You then see the list of AI agents that are available to the user of the API key.
Browse the list of available AI agents and select the AI agent that you want to use in your workflow.
Click Add to create an AI agent artifact in the designer. The created AI agent is automatically opened in the designer.

Viewing and configuring the discovered AI agent

If not opened already, open the discovered AI agent by selecting the AI agent from the library under Services.
In the AI agent editor, set the API key for runtime invocation.

Note: An administrator can override the API key by using the Operations REST API. For more information, see Operations REST APIs.
Add notes to the Documentation section as needed.

Using the AI agent in a service flow

Create or open a service flow where you want to use the AI agent. For more information, see Creating a service flow.
Drag an AI agent activity from the palette to your service flow.
In the implementation tab of the AI agent activity, click Edit AI Agent to open the AI Agent activity page.
Select the AI agent artifact that you want to use.
Specify a message to send to the AI Agent at run time. {{variable_name}}. You can include values from String variables of the service flow in your message by using the format variable_name.
Test your AI Agent invocation to make sure that all the required information is provided, otherwise the AI Agent asks for the information.
1. Add variables to the test data.
2. Specify values for the variables used in the message.
3. Click Test to test the AI agent invocation.
4. Verify that the result is as expected and refine your message as needed.
In the Data Mapping section, view and map the output of the AI agent to one of the workflow variables.
To catch errors raised during AI Agent invocations, attach a catch all boundary error event to the AI agent activity. For more information, see Catching errors by using error boundary events.

Note: AI agent invocations that involve asynchronous tools are not supported. The behavior of an AI agent activity that involves an asynchronous tool is undefined.

What to do next

Install your workflow automation to a workflow server for production use. For more information, see Installing workflow automations and automation services.
Manage the API as needed. Administrators can override API keys by using the Operations REST API. For more information, see Operations REST APIs.