Inject request-scoped dependencies
A tool needs to query a database selected for the current request.
AI Agents · Const
Context object
Context is static, per-run information made available to an agent through its Runtime. Define its shape with contextSchema, pass values via the invocation context option, and access them in tools or middleware.
How it works
A Context object is per-run information supplied separately from conversation state, such as a user identifier, database connection, or feature flag. Define its shape with contextSchema, pass values through the context invocation option, and read them from runtime.context in tools or middleware.
Syntax
const agent = createAgent({ contextSchema });
await agent.invoke(input, { context });Parameters
| Name | Type | Description |
|---|---|---|
contextSchema | Zod schema | Zod schema describing the runtime context shape. |
context | ContextType | Per-run values supplied in the invocation options. |
Returns
An agent result containing the invocation output; the documentation does not specify a distinct return type for the context object.
Key points
- Context is suited to static per-invocation dependencies, including user identifiers and database connections.
- Attaching dependencies to runtime context keeps application code independent of mutable global variables.
- Per-run context improves isolation, making agents easier to test and reuse.
- Use contextSchema to declare the expected shape of the context object.
- Provide concrete runtime values through the context option when invoking the agent.
- A tool can receive runtime and use its context to access invocation-specific data.
Example: Pass per-run context to an agent
import { createAgent } from "langchain";
import * as z from "zod";
const ContextSchema = z.object({
userId: z.string(),
});
const agent = createAgent({
model: "openai:gpt-4.1-mini",
tools: [],
contextSchema: ContextSchema,
});
const result = await agent.invoke(
{ messages: [{ role: "user", content: "Hello" }] },
{ context: { userId: "user-123" } },
);
console.log(result);
Defines per-run context and supplies it when invoking the agent; tools or middleware can read it through the runtime.
When to use it
Carry user metadata
Middleware personalizes behavior using the authenticated account.
Pass feature flags
A deployment enables or disables behavior per invocation.
Interview questions
QHow is runtime context configured and accessed?
Define a schema with contextSchema when creating the agent, then provide matching values in the context field of the invocation options. Tools and middleware access those values through the runtime context.
Follow-up: How should conversation identity differ from runtime configuration? Use thread_id for message history and checkpoints, and context for data needed only during that run.
QWhat is runtime context useful for?
Context carries static information such as user metadata, database connections, or other dependencies for one agent invocation. It avoids putting those dependencies in global state, which supports stateless and reusable code.
Follow-up: What should happen when a value must evolve during execution? Put mutable run data in graph state rather than static runtime context.
QWhat is the role of contextSchema?
The context schema describes the structure of the context stored in the agent runtime. The invocation supplies the actual context object, and application code can consume it through runtime.context.
Follow-up: Is context automatically visible to the model? No; a tool, middleware, or other logic must read it and add relevant information to the prompt or messages.
Related
Runtimeruntime.contextcontextSchemathread_idStateGraph