A small Python 3.11 app that connects to the IBM watsonx Orchestrate API (Custom Assistants / Getting Started) using an API key from apikey.json and Authorization: Bearer <api_key> so you can chat remotely with the system.

• Python 3.11+
• requests (see requirements.txt)

1. API key
   Put your Watson Orchestrate API key in apikey.json in the project root:

   {
     "name": "Your Name (Your Org)",
     "description": "",
     "createdAt": "...",
     "apikey": "YOUR_API_KEY_HERE"
   }

2. Base URL (must be Watson Orchestrate, not watsonx ML)
   Use the Service instance URL from Watson Orchestrate → Profile → Settings → API details. Do not use us-south.ml.cloud.ibm.com (that is watsonx.ai / ML); the Orchestrate API lives on a different host.

   • IBM Cloud:
     https://api.<region>.watson.cloud.ibm.com/instances/<tenant_id>
   • AWS:
     https://api.<region>.watson-orchestrate.ibm.com/instances/<tenant_id>

   Example (replace with your tenant ID):
   https://api.us-south.watson.cloud.ibm.com/instances/YOUR_TENANT_ID

   Either set WATSON_ORCHESTRATE_BASE_URL or pass --base-url "https://...".

3. Install dependencies

   pip install -r requirements.txt

Interactive chat (CLI):

python chat.py

With options:

python chat.py --base-url "https://api.us-south.watson.cloud.ibm.com/instances/YOUR_TENANT_ID" --assistant-id "optional-assistant-uuid"

• Base URL: Required if not set via WATSON_ORCHESTRATE_BASE_URL. Must be the Watson Orchestrate instance URL (see above), not ml.cloud.ibm.com.
• Assistant ID: Optional. It is the UUID of a custom assistant in Watson Orchestrate. To see your IDs, run:
  python list_assistants.py --base-url "https://..."

In chat:

• Type your message and press Enter to send.
• /quit or /exit to exit.
• /thread to print the current thread ID.

For IBM Cloud (e.g. api.*.watson-orchestrate.cloud.ibm.com), the app exchanges your API key for an IAM access token and sends Authorization: Bearer <token>. The token is refreshed automatically (and on 401).

• API key is read from apikey.json (field apikey).
• The client calls https://iam.cloud.ibm.com/identity/token with grant_type=urn:ibm:params:oauth:grant-type:apikey and your API key, then uses the returned access_token for Watson Orchestrate requests.

• apikey.json – API key (do not commit; in .gitignore).
• config.py – Loads API key and base URL.
• watson_client.py – HTTP client: Bearer API key, list assistants, send message, poll run events.
• chat.py – CLI chat loop.
• list_assistants.py – List custom assistants and their IDs (for --assistant-id).
• diagnose.py – Run connection and API checks; use when something isn’t working.
• requirements.txt – Python dependencies.

Run the diagnostic script with your base URL and API key file. It will show which step fails and the API response body:

python diagnose.py --base-url "https://api.au-syd.watson-orchestrate.cloud.ibm.com/instances/YOUR_INSTANCE_ID" --apikey-file apikey.json

• IAM token FAILED – API key is wrong or not an IBM Cloud API key. Regenerate the key in Watson Orchestrate (Settings → API details) or in IBM Cloud.
• GET /v1/orchestrate/agents FAILED (404) – Base URL or path is wrong. Use the Service instance URL from Watson Orchestrate → Settings → API details (no extra path). The app uses the same paths as the IBM watsonx Orchestrate ADK (/v1/orchestrate/agents, /v1/orchestrate/runs).
• GET /v1/orchestrate/agents FAILED (401) – Token not accepted. Ensure the API key belongs to the same IBM Cloud account as the Watson Orchestrate instance.
• No agents / SKIP run – Create at least one agent in Watson Orchestrate (build and save an agent in the UI), then run diagnose.py again.
• POST /v1/orchestrate/runs FAILED (4xx) – The response body will show the reason. Copy it and check the ADK RunClient payload (message, agent_id, thread_id).

When you run chat.py or list_assistants.py, HTTP errors now print the response body (first 800 chars) so you can see exactly what the API returned.

• 404 on list or runs
  The app uses the same API paths as the IBM watsonx Orchestrate ADK: GET /v1/orchestrate/agents, POST /v1/orchestrate/runs, GET /v1/orchestrate/threads/{thread_id}/messages. You need at least one agent; the app uses the first one if you omit --assistant-id.

• What is assistant_id?
  The agent ID (UUID). Run python list_assistants.py --base-url "..." to see IDs, then python chat.py --base-url "..." [--assistant-id "<uuid>"]. You can also use the official ADK: pip install ibm-watsonx-orchestrate then orchestrate env add / orchestrate agents list / orchestrate agents experimental-run --message "hello" --agent-name <name>.

This app uses the same API paths as the IBM watsonx Orchestrate ADK:

• GET /v1/orchestrate/agents – list agents
• POST /v1/orchestrate/runs – send message (payload: message, agent_id, thread_id)
• GET /v1/orchestrate/runs/{run_id} – run status
• GET /v1/orchestrate/threads/{thread_id}/messages – thread messages

You can use the official ADK instead: pip install ibm-watsonx-orchestrate, then orchestrate env add, orchestrate login, orchestrate agents list, and orchestrate agents experimental-run --message "hello" --agent-name <name>.

• IBM watsonx Orchestrate ADK (GitHub)
• Watson Orchestrate Custom Assistants – Getting Started
• Getting the API endpoint
• Generating an API key (on-prem; similar for Cloud/AWS)