REST API Usage with the watsonx Orchestrate Developer Edition locally: An Example

This blog post is about the local usage of the REST API in the local watsonx Orchestrate server. The details are documented in the REST API of the watsonx Orchestrate ADK.

The post guides step-by-step from configure local watsonx Orchestrate server to invoking a simple agent via REST API using a Python application. We’ll see how to set environment variables, retrieve the needed Bearer token, fetch the agent ID, and invoke the agent using a short code example. Pair this with my previous work on local AI agents and flow building for a full-stack local orchestration experience.

You can follow this alongside my previous blog post related to watsonx Orchestrate Developer Edition:

• Getting Started with Local AI Agents in the watsonx Orchestrate Developer Edition (Jun 25, 2025)
• Supercharge Your Support: Example Build & Orchestrate AI Agents with watsonx.ai and watsonx Orchestrate (May 15, 2025)
• Watch the Unlock the New Flow Builder in IBM watsonx Orchestrate – Visualize, Debug & Deploy Tool Flows video on YouTube. 🚀 (July 02, 2025)
• Build, Export & Import a watsonx Orchestrate Agent with the Agent Developer Kit (ADK) (July 08, 2025)

1. What’s Covered in the Example

This post is an example of a flow from starting the server to writing and executing the code.

We walk through:

1. Preparing your local environment
2. Launching the watsonx Orchestrate server
3. Activating the ADK shell
4. Determining the local port and swagger UI
5. Extracting your Bearer token
6. Listing your agent and getting the agent ID
7. Coding a Python script to invoke the agent
8. Running the script and inspecting the response

Step 1: Ensure you set you local environment variables

Ensure .env file. The variable WO_DEVELOPER_EDITION_SOURCE=myibm displays that you are going to use an entitlement key from MyIBM and access watsonx.ai as model sources.

WO_DEVELOPER_EDITION_SOURCE=myibm
WO_ENTITLEMENT_KEY=<YOUR_ENTITLEMENT_KEY>
WATSONX_APIKEY=<YOUR_WATSONX_API_KEY>
WATSONX_SPACE_ID=<YOUR_SPACE_ID>

Step 2: Start the local watsonx Orchestrate server

The server boots up, connecting local credentials, containers, and runtimes.

source ./.venv/bin/activate
orchestrate server start --env-file .env

Step 3: Ensure the local ADK environment is activated

This ensures that your client targets the local server configuration.

orchestrate env activate local

Step 4: Get the local port for your local watsonx Orchestrate server

When you inspect docker compose on your local machine you will find that the watsonx Orchestrate server is running on the port 4321, and you can access the swagger UI with http://localhost:4321/docs.

The image below displays the Rancher Desktop on the local machine.

This shows that by default, the server runs on port 4321, and the Swagger API explorer is at:

Step 5: Get the needed Bearer token for the authentication to the local watsonx Orchestrate server

We will need a Bearer token later to access the local server using the REST API; we can use the content of wxo_mcsp_token for local usage at the moment.

In the watsonx Orchestrate ADK documentation you find that there are two important configuration files.

• ~/.config/orchestrate/config.yaml
• ~/.cache/orchestrate/credentials.yaml

To authenticate REST API calls, we pull the Bearer token from the orchestrate cache:

The file ~/.cache/orchestrate/credentials.yaml contains, for example, the following information.

Invoke following command to get the details:

nano ~/.cache/orchestrate/credentials.yaml

• Example output:

auth:
  local:
    wxo_mcsp_token: XXXX

We can get the token value also with this command.

grep -R "wxo_mcsp_token" ~/.cache/orchestrate/credentials.yaml

Copy the token value.

Step 6: Get the agent ID

List your agents and get the ID for the agent you want to invoke. Note your agent ID for the next step.

orchestrate agents list

• Example output:

In this situation, the ID is 42db7f18-4880-4bbb-83f4-262a3532f3af.

┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                    ┃ Description             ┃ LLM                     ┃ Style   ┃ Collaborators ┃ Tools                  ┃ Knowledge Base ┃ ID                      ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ MyLocalAgent_3448nD     │ MyLocalAgent            │ watsonx/meta-llama/llam │ default │               │                        │                │ 42db7f18-4880-4bbb-83f4 │
│                         │                         │ a-3-2-90b-vision-instru │         │               │                        │                │ -262a3532f3af           │
│                         │                         │ ct                      │         │               │                        │                │                         │
└─────────────────────────┴─────────────────────────┴─────────────────────────┴─────────┴───────────────┴────────────────────────┴────────────────┴─────────────────────────┘

Step 7: Write a simple invocation for an agent using the REST API for watsonx Orchestrate

Create a Python file, for example, called invoke_agent.py with the following code. Most of the code is reused from the offical examples in the documentation: Chat with Agents in the REST API documentation. Insert the agent ID and the token into the example code.

import requests
from modules import token

agent_id = "your_agent_id"
url = f"http://localhost:4321/api/v1/orchestrate/{agent_id}/chat/completions"

token = "your_wxo_mcsp_token_wxo_mcsp_token"

payload = {
    "messages": [
 {
            "role": "human",
            "content": "What can you do for me?"
 }
 ],
    "additional_parameters": {},
    "context": {},
    "stream": False
}

headers = {
    "Authorization": f "Bearer {token}",
    "Content-Type": "application/json"
}

# Invoke the agent
response = requests.request("POST", url, json=payload, headers=headers)
print(f"Agent response:\n{response.text}\n")

Step 8: Execute your code to invoke the REST API

python3 ./invoke_agent.py

• Example output:

{
  "id": "...",
  "object": "chat.completion",
  "created": 1752134664,
  "model": "watsonx/meta-llama/llama-3-2-90b-vision-instruct",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Hello! I am watsonx Orchestrate, an AI assistant…"
 }
 }]
}

Now, we’ve successfully communicated with our local agent via REST.

2. Summary

This local REST API flow gives us complete control—no cloud dependencies, interactively testable. Keep an eye on the official documentation, as local specifics, such as token retrieval and port assignments, can evolve.

For the testing of the agents, we should also take a close look into the evaluation framework out-of-the-box provided in the watsonx Orchestrate ADK. Following the steps:

• Develop
• Evaluate
• Analyze
• Improve

This can be a topic for a future post.

I hope this was useful to you and let’s see what’s next?

Greetings,

Thomas

#watsonxOrchestrate, #AIAgents, #GenAI, #Automation, #Python, #Automation