Runtime context: who is asking

Runtime context is a way to pass a tool the facts your code knows about a run, such as who the customer is, with each call and out of the model's sight.

Last updated: 27 Sep, 2026 · LangChain 1.4

Lesson 7's agent tells anyone the status of any order. A customer called Ravi should see his own orders and no one else's. That name cannot be a tool argument, because the model fills arguments in and a message can talk a model into sending any name.

The ToolRuntime parameter

@tool
def lookup_order(order_id: str, runtime: ToolRuntime[Customer]) -> str:
    ...
    runtime.context.name   # the Customer object you passed for this run

agent = create_agent(model, tools=[lookup_order], context_schema=Customer)
agent.invoke(inputs, context=Customer("ravi"))   # supply it per call

Describing the context

The context is whatever your code knows about this run: the signed-in customer, a database connection, a setting. A dataclass describes its shape.

from dataclasses import dataclass


@dataclass
class Customer:
    name: str

Reading context in the tool

A parameter typed ToolRuntime is filled in by LangChain when the tool runs, so the tool can compare the order's owner with the customer asking.

from langchain.tools import ToolRuntime, tool

ORDERS = {"A17": ("ravi", "shipped on 3 March"), "C40": ("mei", "waiting for stock")}


@tool
def lookup_order(order_id: str, runtime: ToolRuntime[Customer]) -> str:
    """Look up one of the customer's orders by its id, such as A17."""
    owner, status = ORDERS.get(order_id, (None, None))
    if owner != runtime.context.name:
        return f"{order_id} is not one of your orders."
    return f"{order_id} {status}."

Wiring the context into the agent

Wire the tool into the agent and tell the agent what context to expect.

from langchain.agents import create_agent
from shop_model import ShopModel
from tools import Customer, lookup_order

agent = create_agent(ShopModel(), tools=[lookup_order], context_schema=Customer)

The same question as two customers

First check the schema the model sees for the tool.

from tools import lookup_order

print(lookup_order.args)

The schema has only order_id: the runtime parameter is left out, so the model cannot supply or change the customer. Now run the same question as two different customers.

result = agent.invoke({"messages": [{"role": "user", "content": "Where is my order A17?"}]}, context=Customer("ravi"))
print(result["messages"][-1].text)

result = agent.invoke({"messages": [{"role": "user", "content": "Where is my order A17?"}]}, context=Customer("mei"))
print(result["messages"][-1].text)

What the runtime gave the tool

• A parameter typed ToolRuntime is filled in by LangChain when the tool runs; runtime.context is the object you passed for this run.
• The schema the model sees has only order_id; the runtime parameter is left out, so the model cannot supply or change the customer.
• context_schema=Customer tells the agent what to expect, and context= supplies it for one call.
• The same question gets two answers: A17 is Ravi's order, so Mei is told it is not hers.

Tool argument vs runtime context

When to use runtime context

• Passing the signed-in user so a tool returns only their data.
• Handing a tool a database connection or a per-request setting the model should never see.

Related

• Previous: Streaming steps with stream_mode
• Next: Structured output with response_format
• Reference: Runtime context