> ## 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.

# Runs-on

## 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

### From RunnableConfig (recommended)

Use `RunnableConfig` to initialize the client. This is the preferred pattern for runs-on agents.

```python PYTHON [expandable] theme={null}
from ibm_watsonx_orchestrate_sdk import Client
from langgraph.graph.state import RunnableConfig

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

    # Build the graph
    builder = StateGraph(AgentState)
    builder.add_node("agent", agent_node)
    builder.set_entry_point("agent")
    builder.add_edge("agent", END)
    
    return builder
```

### From execution\_context

Use this pattern only when manual control is required.

```python PYTHON [expandable] theme={null}
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)

    # Build the graph
    builder = StateGraph(AgentState)
    builder.add_node("agent", agent_node)
    builder.set_entry_point("agent")
    builder.add_edge("agent", END)
    
    return builder
```

### 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.

<Note>
  * 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.
</Note>

### References

* [Client](/sdk/client)
* [Chat models](/sdk/chat_wxo)
* [Memory](./memory)
* [Context](./context)