Configuring the integration with a custom agent in IBM watsonx Orchestrate to support agentic chat

To use your own watsonx Orchestrate agent, you must have a custom watsonx Orchestrate instance set up and connected to Planning Analytics Agent. For more information, see Connecting the Planning Analytics Agent to a custom IBM watsonx Orchestrate instance.

The agent configuration requires the following fields from the agent's Embedded agent section:

• purchaseID: The unique ID for your purchase or subscription.
• wxo_agent.orchestrationID: The unique ID for your watsonx Orchestrate instance.
• wxo_agent.hostURL: The watsonx Orchestrate host URL.
• wxo_agent.agentID: The unique agent ID.
• wxo_agent.agentEnvironmentId: The unique agent environment ID.
• wxo_agent.perspectives: Specifies the perspectives where the custom watsonx Orchestrate agent is available. Perspectives that are not included continue to use the existing Planning Analytics Agent.

  The perspectives array accepts the following values:

  • pa-home
  • pa-administration
  • dashboard
  • modeling
  • modeling-home
  • pa-plan-contribute
  • pa-report

  Plans and Apps perspectives retain their current chat assistant for now.

  The agent evaluates requests based on the active perspective. If you trigger an intent in the wrong perspective, the agent provides feedback to you. For example, if you request chart insights while in the Administration perspective, the agent informs you that the action cannot be completed in that context.

  Note: If the perspectives property is not specified, the custom agent does not appear in any perspectives.
• wxo_agent.authKey: If security is enabled, this field is the private RSA that corresponds to the public key that you configured in your custom watsonx Orchestrate environment. Replace line breaks with \n. This key is used to secure your chat integration.

Your watsonx Orchestrate instance must have an agent that is defined with an orchestration ID, host URL, agent ID, agent environment ID, and (if security is enabled) a private authorization key.

The following example JSON configuration string contains the required fields:

{
  "purchaseID": "<purchase_id>",
  "wxo_agent": {
    "orchestrationID": "<orchestration_id_string>",
    "hostURL": "https://<orchestration_url>",
    "agentId": "<agent_id_string>",
    "agentEnvironmentId": "<agent_env_id_string>", 
    "perspectives": [
      "pa-home",
      "pa-administration",
      "dashboard",
      "modeling",
      "modeling-home"
    ]
    "authKey": "-----BEGIN PRIVATE KEY-----\\n<private_key>\\n-----END PRIVATE KEY-----"
  }
}

To keep your JSON configuration string short, you can also specify the authKey authorization key in the separate Embedded chat authorization key field.

The watsonx Orchestrate agent supports the following commands in perspectives other than Dashboard:

• Open books, workbenches, or plans by name (for example, "Open book Sales Report")
• List users
• List groups
• List groups for a specific user
• List users under a specific group
• Switch between perspectives (for example, "Switch to modeling" or "Switch to administration")

The agent also provides how-to guidance for common tasks, such as:

• How to do modeling
• How to write a TurboIntegrator script