Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

IBM watsonx Orchestrate

Monitor IBM watsonx Orchestrate agents in Akto — discovery and conversation traffic, with no changes to your agents

Overview

IBM watsonx Orchestrate is IBM's platform for building, running and governing AI agents. It acts as an agent control plane: it manages agents built in Orchestrate and external agents, an AI gateway for models and MCP servers, guardrail controls, connections to business systems, and agent permissions.

Akto connects to your Orchestrate instance with an API key and, every few minutes:

  • Discovers everything Orchestrate manages: your agents (built in Orchestrate and external agents), their tools, collaborators, models, MCP servers, guardrail controls, connections, identity and permissions.

  • Reads the conversations your agents have had, as recorded by Orchestrate's observability, and sends them to Akto for security analysis.

Nothing is installed in your IBM account and your agents are not changed. Akto only reads. Conversations reach Akto a few minutes after they happen.

How it works

What Akto Covers

Agents

Covered
Details

Agents built in Orchestrate

All agents, both draft and live (deployed). For live agents, Akto reads the deployed version, so you see what is actually running.

External agents

Agents registered in Orchestrate's Agent directory (external chat and A2A agents built on other frameworks).

Multi-agent setups

Supervisor agents and their collaborators, including external collaborators. Each conversation shows which agent called which.

IBM built-in agents

Agents such as AskOrchestrate and the Document Processing agent, if used in your instance.

Each agent appears in Akto under its display name as shown in Orchestrate (for external agents, their title).

What Akto discovers about each agent

Area
What you see in Akto

Configuration

Description, instructions, model, tools, collaborators, MCP servers, knowledge bases, plug-ins, and whether the agent is in draft, live or both

AI gateway

The models available in your instance, and MCP servers registered on the gateway with their tools

Controls (guardrails)

Which Orchestrate controls (PII filter, content guardrails, rate limiters, code plug-ins and others) are applied to the agent, its tools and its model. Agents with no controls are flagged

Connections

The business systems the agent connects to (for example SAP SuccessFactors), with their authentication type and whether they are shared by the team or set per user. Only names and types are read

Identity and permissions

Who created the agent and when, who last updated it and when, whether agent identity is enabled, the permissions granted through its connections, and the number of tools it can access (including through collaborators)

Conversation traffic

Covered
Details

User messages and agent answers

Every conversation turn, in draft (preview) and live

System prompt

The instructions the agent runs with

Tool calls

Each tool the agent called, with its input and result

Collaborator handoffs

When a supervisor delegates to a collaborator (including external agents), both sides of the handoff, linked together

Flow inputs

Messages and form choices a user sends to a running flow (for example a document processing flow), labelled as flow input

Model and token usage

The model used and input/output tokens per turn

User and session

Who sent the message, and the conversation session it belongs to

Conversation content is sent to Akto as Orchestrate records it, including the user who sent each message.

Prerequisites

  • An IBM watsonx Orchestrate SaaS instance (IBM Cloud or AWS hosted).

  • An Orchestrate API key for a user who can see all agents. We recommend a dedicated user with the Admin role, so that controls, connections and permissions are fully visible.

  • Your Akto data ingestion service URL (contact Akto support if you don't have it).

Steps to Connect

1

Get your Orchestrate instance URL and API key

  1. Sign in to watsonx Orchestrate.

  2. Open your profile menu (top right) → Settings → API details.

  3. Copy the Service instance URL. For example: https://api.dl.watson-orchestrate.ibm.com/instances/<instance-id>

  4. Click Generate API key, give it a name (for example akto-monitoring) and copy the key. It is shown only once.

2

Add the connector in Akto

  1. In the Akto dashboard, go to Connectors → AI Agent Security → IBM watsonx Orchestrate.

  2. Fill in the form:

Field
Required
Value

Instance URL

Yes

The Service instance URL from the previous step

API Key

Yes

The Orchestrate API key from the previous step

URL for Data Ingestion Service

Yes

Your Akto data ingestion service URL

  1. Click Import.

3

Wait for the first sync

Akto starts right away and then repeats every 5 minutes:

  • Your agents, models, MCP servers, controls and connections appear within a few minutes.

  • The conversations of the last 3 days are imported. For a busy instance this can take a few cycles.

  • After that, new conversations appear in Akto 5 to 10 minutes after they happen.

4

See your agents in Akto

  1. Go to Agentic AI Discovery → Collections. You will find:

    • one collection per agent, named after the agent (for example Customer Support Agent);

    • one collection per MCP server registered on the AI gateway;

    • a watsonx Orchestrate AI Gateway collection listing models, MCP servers, controls and connections.

  2. Open a collection to see its tags, for example:

Tag
Example

bot-name

Customer Support Agent

tools

get_order_status

collaborators

Billing Agent, Currency Agent

mcp-servers

wxo_ootb_docproc

controls

PII Filter, or none when no control is applied

connections

SAP SuccessFactors (team)

created-by / updated-by

the creator and the last editor

agent-identity

enabled or disabled

environments

draft, live

  1. Go to Agentic AI Discovery → Traces to read the conversations: user prompt, agent response, tool calls, tokens and session.

Data Handling

  • Read only. Akto only reads from Orchestrate. It does not create, change or delete agents, tools, controls or connections.

  • Dedicated access. Create the Orchestrate access for Akto under a dedicated user, so it can be reviewed and revoked on its own.

  • Connections. Akto reads only the names and types of the connections configured in Orchestrate.

Troubleshooting

Symptom
What to check

No agents appear

The instance URL is the Service instance URL (it contains /instances/)

Agents appear but no conversations

Conversations exist on Orchestrate's Observability page for that period. Only the last 3 days are imported on the first run

Controls or connections are missing

Use a user with the Admin role in Orchestrate

New conversations appear late

Conversations are read every 5 minutes. Allow up to 10 minutes

Real-time Blocking

Real-time blocking adds the AKTO plug-in to your Orchestrate agents. On every conversation turn:

  • the user's message is checked by your AKTO guardrail policies before the agent processes it;

  • the agent's answer is checked before the user sees it.

A message or answer that violates a policy is blocked. If a policy masks content (for example personal data), the agent or the user receives the masked version. Every checked exchange is also recorded in Akto.

How it behaves

Blocked message

The agent does not process it, and Orchestrate reports the block in the chat

Blocked answer

The answer is not shown to the user

Masked content

The masked version is passed on instead of the original

Monitor-only policies

Policies set to warn or alert are recorded in Akto but do not block

Added wait

Each message and answer waits for Akto's verdict, at most 5 seconds

Prerequisites

  • Your AKTO guardrail policies set up in the Akto dashboard.

  • Your AKTO guardrails host and AKTO API key (AKTO Argus → Connectors → Setup Guardrails).

  • An Orchestrate API key of a user with the Admin role (Orchestrate → profile menu → Settings → API details), and the Service instance URL shown on the same page.

  • For the installer: Python 3.11 to 3.14 on the computer you run it from (python.org/downloads).

Installer (all Orchestrate plans)

The installer adds the AKTO plug-in to the agents you choose. You do not need to install anything else: it prepares IBM's tools by itself, in a folder of its own.

1

Download the AKTO plug-in package

Download the package akto-watsonx-1.0.0.zip and unzip it. Its checksum is published next to it as akto-watsonx-1.0.0.zip.sha256. The folder contains the installer, the plug-in and a checksum file; the installer checks the files before using them.

2

Run the installer

Unzipping creates a folder named akto-watsonx-1.0.0. For example, if you downloaded it to your Downloads folder:

Open a terminal and go to that folder. Use the path where you unzipped it:

On macOS, you can also type cd (with a space) in the terminal and drag the akto-watsonx-1.0.0 folder from Finder into the terminal window, then press Enter.

Then run the installer from that folder:

Choose which agents to protect with --agents:

To protect
Use

One agent

--agents "Customer Support Agent"

Several agents

--agents "Customer Support Agent, Billing Agent"

All agents

--agents all

  • Use the agent's name as shown in Orchestrate (its display name or its internal name; upper and lower case do not matter).

  • --agents all covers every agent that exists when you run the installer. Agents created later are not added automatically: run the installer again with the new agent's name (or with all). Agents that already have the plug-in are left as they are.

  • External agents cannot have plug-ins in Orchestrate; they are protected through the Orchestrate agent that calls them.

--deploy also updates your live agents. Without it, only the draft agents are protected, so you can test in the agent's preview first. Agents that are not live (draft only) are never deployed by the installer.

When asked, paste your Orchestrate API key and your AKTO API key. Nothing is shown while you paste.

3

Check the summary

The installer ends with the list of your agents and whether each one is protected in draft and live:

If an agent's draft has other changes that were never deployed, the installer asks before deploying it, because deploying would publish those changes too.

Check that it works

  1. Open one of the protected agents in Orchestrate and send an ordinary message: the agent answers as usual.

  2. Send a message that one of your AKTO guardrail policies blocks: the agent does not answer it.

  3. In Akto, the blocked message appears under the agent, in Agentic AI Discovery → Traces.

Update or remove the plug-in

Go to the unzipped folder first (for example cd ~/Downloads/akto-watsonx-1.0.0), then run:

To
Run

See which agents are protected

python3 akto_watsonx_setup.py status --instance-url "<URL>"

Install a newer version (from a newer package)

python3 akto_watsonx_setup.py upgrade --instance-url "<URL>" --deploy

Remove the plug-in

python3 akto_watsonx_setup.py uninstall --instance-url "<URL>" --agents all --deploy

Removing it from all agents also removes the AKTO plug-in and its settings from your Orchestrate instance.

Get Support for your Akto setup

There are multiple ways to request support from Akto. We are 24X7 available on the following:

  1. In-app intercom support. Message us with your query on intercom in Akto dashboard and someone will reply.

  2. Join our discord channel for community support.

  3. Contact help@akto.io for email support.

  4. Contact us here.

Last updated