> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Watson Orchestrate ADK (tracing)

> Trace IBM watsonx Orchestrate ADK tools, run clients, and chat clients with Respan.

[IBM watsonx Orchestrate ADK](https://developer.watson-orchestrate.ibm.com/) lets teams build and operate enterprise agents, tools, and orchestrated runs. Respan traces local ADK Python tools, run-client operations, and watsonx.ai autodiscover chat calls when those optional client modules are installed.

Use this page when your application calls Watson Orchestrate ADK directly with IBM credentials.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Example projects

* [Python examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/watson-orchestrate-adk)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-watson-orchestrate-adk ibm-watsonx-orchestrate
```

#### Set environment variables

```bash
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export WATSON_ORCHESTRATE_BASE_URL="YOUR_WATSON_ORCHESTRATE_BASE_URL"
export WATSON_ORCHESTRATE_API_KEY="YOUR_WATSON_ORCHESTRATE_API_KEY"
```

`RESPAN_API_KEY` exports traces to Respan. The `WATSON_ORCHESTRATE_*` variables are used by the Watson Orchestrate ADK clients.

#### Initialize and run

```python
from respan import Respan
from respan_instrumentation_watson_orchestrate_adk import (
    WatsonOrchestrateADKInstrumentor,
)

respan = Respan(
    app_name="watson-orchestrate-adk-demo",
    instrumentations=[WatsonOrchestrateADKInstrumentor()],
)

# Build and invoke Watson Orchestrate ADK tools, run clients, or chat clients
# after Respan has initialized.

respan.flush()
respan.shutdown()
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see Watson Orchestrate ADK tool, run, and chat spans.

## Configuration

| Parameter             | Type           | Default           | Description                                                                   |
| --------------------- | -------------- | ----------------- | ----------------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `RESPAN_API_KEY`  | Respan API key used to export traces.                                         |
| `base_url`            | `str \| None`  | `RESPAN_BASE_URL` | Optional Respan trace export API URL.                                         |
| `instrumentations`    | `list`         | `[]`              | Include `WatsonOrchestrateADKInstrumentor()` to patch installed ADK surfaces. |
| `customer_identifier` | `str \| None`  | `None`            | Default customer identifier for all spans.                                    |
| `metadata`            | `dict \| None` | `None`            | Default metadata attached to all spans.                                       |
| `environment`         | `str \| None`  | `None`            | Environment tag, for example `"production"`.                                  |

## What gets traced

| Watson Orchestrate ADK operation                  | Respan span | Notes                                                                                                    |
| ------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| Local `PythonTool` execution                      | `tool`      | Captures tool name, arguments, result, and failures.                                                     |
| `RunClient` run methods                           | `agent`     | Captures run input, thread/run identifiers, response payloads, and errors.                               |
| ADK chat and watsonx.ai autodiscover client calls | `chat`      | Captures prompt, completion, model, token usage, and failures when those optional modules are installed. |

The instrumentor does not require Watson Orchestrate ADK at import time. Missing optional client surfaces are skipped during activation.