Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Runs-on mode is used when an agent runs inside the watsonx Orchestrate runtime. The runtime provides the execution context required by the SDK, including authentication and request routing details. This mode enables the agent to operate with runtime-managed access and thread-level context.

​
Runtime context

The runtime provides an execution context that includes required fields such as access token, thread ID, and API proxy URL. The SDK uses this context directly to send requests.

​
Initialize the client

Use RunnableConfig to initialize the client. This is the preferred pattern for runs-on agents.
PYTHON
from ibm_watsonx_orchestrate_sdk import Client
from langgraph.graph.state import RunnableConfig

def create_agent(config: RunnableConfig):
    client = Client.from_runnable_config(config)
    return client

​
From execution_context

Use this pattern only when manual control is required.
PYTHON
from ibm_watsonx_orchestrate_sdk import Client
from langgraph.graph.state import RunnableConfig

def create_agent(config: RunnableConfig):
    execution_context = config.get("configurable", {}).get("execution_context")
    client = Client(execution_context=execution_context)
    return client

​
Required runtime context

A runs-on agent must receive execution_context from the runtime. The following fields are required:
  • access_token
  • thread_id
  • api_proxy_url

​
api_proxy_url behavior

The SDK uses api_proxy_url as provided:
  • The SDK does not append /v1/orchestrate
  • The SDK does not append an instance path
The value must already be the full API base URL that the SDK should call.
  • The execution context must include all required fields.
  • The API proxy URL is used as provided without modification.
  • Runtime values take precedence over environment configuration.

​
References