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

Note: IBM Cloud and watsonx on-premises are supported starting from 26.0.0.0-IF001.
Before you can use this feature, you need to configure the AI agents integration. watsonx Orchestrate on Amazon Web Services (AWS), IBM Cloud, and on-premises are supported.
  1. Apply the following watsonx Orchestrate endpoint configurations:
  2. Add the following configuration to your 100Custom.xml file.
    • AWS
      <server> 
     <wxo merge="mergeChildren"> 
          <environment-type>AWS</environment-type> 
          <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>
    •  From 26.0.0.0-IF001  IBM Cloud
      <server> 
     <wxo merge="mergeChildren"> 
          <environment-type>IBMCloud</environment-type> 
          <token-url>https://iam.cloud.ibm.com/identity/token</token-url> 
          <discovery> 
              <service-instance-url>https://api.<hostname>/instances/<tenant_id></service-instance-url> 
          </discovery>
     </wxo> 
</server>
    •  From 26.0.0.0-IF001  On-premises
      <server> 
     <wxo merge="mergeChildren"> 
          <discovery> 
              <service-instance-url>https://<hostname>/orchestrate/<namespace>/instances/<instance_id></service-instance-url> 
          </discovery> 
     </wxo> 
</server>

    Replace <hostname>, <tenant_id>, and <instance-id> with your specific environment values.

  3. Depending on your environment, use one of the following custom resource parameters to enable the 100Custom.xml snippet.
    • For Workflow Authoring, use lombardi_custom_xml_secret_name.
    • For Workflow Process Service Authoring, use lombardi_custom_xml_secret_name.
    • For Workflow Runtime, use lombardi_custom_xml_secret_name.
    • For Workflow Process Service Runtime, use lombardiXML.
  4. (On-premises) Trust the certificate of your watsonx Orchestrate on-premises environment.
    • Create a secret with the certificate of your watsonx Orchestrate on-premises environment: 
      kubectl create secret generic <secret name> --from-file=tls.crt=<certificate file path> -n <namespace>
    • Add the secret to the component’s trust store. If you want watsonx Orchestrate on-premises to be trusted by all components installed by the operator, add the secret to the custom resource in the shared_configuration.trusted_certificate_list parameter. For example:
      shared_configuration:
  trusted_certificate_list:
    - <secret name>
  5. Make sure your Cloud Pak for Business Automation instance can access the watsonx Orchestrate instance.
  6. 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

  1. 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.
  2. Browse the list of available AI agents and select the AI agent that you want to use in your workflow.
  3. 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

  1. If not opened already, open the discovered AI agent by selecting the AI agent from the library under Services.
  2. 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.
  3. Add notes to the Documentation section as needed.

Using the AI agent in a service flow

  1. Create or open a service flow where you want to use the AI agent. For more information, see Creating a service flow.
  2. Drag an AI agent activity from the palette to your service flow.
  3. In the implementation tab of the AI agent activity, click Edit AI Agent to open the AI Agent activity page.
  4. Select the AI agent artifact that you want to use.
  5. 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.
  6. 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.
  7. In the Data Mapping section, view and map the output of the AI agent to one of the workflow variables.
  8. 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

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