Exporting a watsonx Orchestrate agent trace

Answer

There are two options to collect an agent trace:

• use the /v1/agentops-v3/traces/ API 
  Documentation: Get traces
• use the orchestrate observability traces export command in the ADK
  Documentation: Using traces with ADK CLI

There are sample steps to collect an agent trace with both options below.

PREPARATION

Before collecting the agent trace with the /v1/agentops-v3/traces/ API, you must prepare by collecting four parameters:

• Your environment's service instance URL.
  • To get the service instance URL, log into watsonx Orchestrate, click your Profile icon > Settings > API details tab.
• A valid API key.
  • To get an API key, click your Profile icon > Settings > API details tab, and click the Generate API key button.

• An access token generated with the API key.

  • IBM Cloud instructions.
    Sample commands:

  • # assign the API key value to the MY_APIKEY variable
    MY_APIKEY=o-HkNvDAAZgc...
    
    #generate the token and assign it to the MY_TOKEN variable
    MY_TOKEN=$(curl -X POST "https://iam.cloud.ibm.com/identity/token" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$MY_APIKEY" \
    | jq -r '.access_token')

   

  • AWS instructions.
    Sample commands:

  • # assign the API key value to the MY_APIKEY variable
    MY_APIKEY=azE6dXNy...
    
    # MCSP V1 endpoint example
    # generate the token and assign it to the MY_TOKEN variable
    MY_TOKEN=$(curl --request POST \
    --url https://iam.platform.saas.ibm.com/siusermgr/api/1.0/apikeys/token \
    --header "accept: application/json" \
    --header "content-type: application/json" \
    --data "{ \"apikey\": \"$MY_APIKEY\" }" \
    | jq -r '.token')
    
    # MCSP V2 endpoint example
    # generate the token and assign it to the MY_TOKEN variable
    MY_TOKEN=$(curl --request POST \
    --url https://account-iam.platform.saas.ibm.com/api/2.0/apikeys/token \
    --header "accept: application/json" \
    --header "content-type: application/json" \
    --data "{ \"apikey\": \"$MY_APIKEY\" }" \
    | jq -r '.token')

• A trace_id value associated with the problem.
  • You can get the trace_id value from the browser developer tool Network tab, testing the agent in debug mode, or from watsonx Orchestrate server traces.
  • Browser developer tool Network tab example: 
    Find a runs call and click the Response tab. 
    
  • Agent in debug mode example:
    

Sample /v1/agentops-v3/traces/ API commands

AWS EXAMPLE:

curl -X GET "https://api.dl.watson-orchestrate.ibm.com/instances/20250501-1835-xxx \
/v1/agentops-v3/traces/a5f8875b1d9e4de96311a3718c6751c6" \
-H "Authorization: Bearer ${MY_TOKEN}" > trace.json

IBM Cloud EXAMPLE:

curl -X GET "https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/3531942d-5da5-xxx \ 
/v1/agentops-v3/traces/a5f8875b1d9e4de96311a3718c6751c6" \
-H "Authorization: Bearer ${MY_TOKEN}" > trace.json

where:

• https://api.dl.watson-orchestrate.ibm.com/instances/20250501-1835-xxx is the service instance URL on AWS;
• https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/3531942d-5da5-xxx is the service instance URL on IBM Cloud;
• a5f8875b1d9e4de96311a3718c6751c6 is the trace_id value
• MY_TOKEN is the authorization token you generated in the preparation steps.
• trace.json is the output file, which has the agent trace.

Sample ADK command

NOTE: the minimum ADK version requirement is ADK 2.13.

orchestrate observability traces export --trace-id a5f8875b1d9e4de96311a3718c6751c6 -o trace.json

where:

• a5f8875b1d9e4de96311a3718c6751c6 is the trace_id value
• trace.json is the output file, which has the agent trace.