Skip to main content

​
概述

LangChain 的 createAgent 在底层运行于 LangGraph 的运行时之上。 LangGraph 公开了一个 Runtime 对象，包含以下信息：
  1. 上下文：静态信息，如用户 ID、数据库连接或其他用于代理调用的依赖项
  2. 存储：一个 BaseStore 实例，用于长期记忆
  3. 流写入器：一个用于通过 "custom" 流模式流式传输信息的对象
  4. 执行信息：当前执行的身份和重试信息（线程 ID、运行 ID、尝试次数）
  5. 服务器信息：在 LangGraph Server 上运行时的服务器特定元数据（助手 ID、图 ID、认证用户）
运行时上下文是您在代理中传递数据的方式。您可以将值（如数据库连接、用户会话或配置）附加到上下文中，并在工具和中间件中访问它们，而不是将内容存储在全局状态中。这保持了无状态、可测试和可重用性。
您可以在工具和中间件中访问运行时信息。

​
访问

使用 createAgent 创建代理时，可以指定 contextSchema 来定义存储在代理 Runtime 中的 context 结构。 调用代理时，传递包含相关运行配置的 context 参数： 
import * as z from "zod";
import { createAgent } from "langchain";

const contextSchema = z.object({
  userName: z.string(),
});

const agent = createAgent({
  model: "gpt-4.1",
  tools: [
    /* ... */
  ],
  contextSchema,
});

const result = await agent.invoke(
  { messages: [{ role: "user", content: "What's my name?" }] },
  { context: { userName: "John Smith" } }
);

​
在工具内部

您可以在工具内部访问运行时信息，以：
  • 访问上下文
  • 读取或写入长期记忆
  • 写入自定义流（例如，工具进度/更新）
使用 runtime 参数在工具内部访问 Runtime 对象。 
import * as z from "zod";
import { tool } from "langchain";
import { type ToolRuntime } from "@langchain/core/tools";

const contextSchema = z.object({
  userName: z.string(),
});

const fetchUserEmailPreferences = tool(
  async (_, runtime: ToolRuntime<any, typeof contextSchema>) => {
    const userName = runtime.context?.userName;
    if (!userName) {
      throw new Error("userName is required");
    }

    let preferences = "The user prefers you to write a brief and polite email.";
    if (runtime.store) {
      const memory = await runtime.store?.get(["users"], userName);
      if (memory) {
        preferences = memory.value.preferences;
      }
    }
    return preferences;
  },
  {
    name: "fetch_user_email_preferences",
    description: "Fetch the user's email preferences.",
    schema: z.object({}),
  }
);

​
工具内部的执行信息和服务器信息

通过 runtime.executionInfo 访问执行身份（线程 ID、运行 ID），并通过 runtime.serverInfo 访问服务器特定元数据（助手 ID、认证用户），当在 LangGraph Server 上运行时： 
import { tool } from "langchain";
import * as z from "zod";

const contextAwareTool = tool(
  async (_input, runtime) => {
    // 访问线程和运行 ID
    const info = runtime.executionInfo;
    console.log(`Thread: ${info.threadId}, Run: ${info.runId}`);

    // 访问服务器信息（仅在 LangGraph Server 上可用）
    const server = runtime.serverInfo;
    if (server != null) {
      console.log(`Assistant: ${server.assistantId}`);
      if (server.user != null) {
        console.log(`User: ${server.user.identity}`);
      }
    }

    return "done";
  },
  {
    name: "context_aware_tool",
    description: "A tool that uses execution and server info.",
    schema: z.object({}),
  }
);
serverInfo 在未在 LangGraph Server 上运行时为 null（例如，在本地开发期间）。
需要 deepagents>=1.9.0（或 @langchain/langgraph>=1.2.8）以支持 runtime.executionInfo 和 runtime.serverInfo。

​
在中间件内部

您可以在中间件中访问运行时信息，以创建动态提示、修改消息或基于用户上下文控制代理行为。 使用 runtime 参数在中间件内部访问 Runtime 对象。 
import * as z from "zod";
import { createAgent, createMiddleware, SystemMessage } from "langchain";

const contextSchema = z.object({
  userName: z.string(),
});

// 动态提示中间件
const dynamicPromptMiddleware = createMiddleware({
  name: "DynamicPrompt",
  contextSchema,
  beforeModel: (state, runtime) => {
    const userName = runtime.context?.userName;
    if (!userName) {
      throw new Error("userName is required");
    }

    const systemMsg = `You are a helpful assistant. Address the user as ${userName}.`;
    return {
      messages: [new SystemMessage(systemMsg), ...state.messages],
    };
  },
});

// 日志记录中间件
const loggingMiddleware = createMiddleware({
  name: "Logging",
  contextSchema,
  beforeModel: (state, runtime) => {
    console.log(`Processing request for user: ${runtime.context?.userName}`);
    return;
  },
  afterModel: (state, runtime) => {
    console.log(`Completed request for user: ${runtime.context?.userName}`);
    return;
  },
});

const agent = createAgent({
  model: "gpt-4.1",
  tools: [
    /* ... */
  ],
  middleware: [dynamicPromptMiddleware, loggingMiddleware],
  contextSchema,
});

const result = await agent.invoke(
  { messages: [{ role: "user", content: "What's my name?" }] },
  { context: { userName: "John Smith" } }
);

​
中间件内部的执行信息和服务器信息

中间件钩子也可以访问 runtime.executionInfo 和 runtime.serverInfo： 
import { createMiddleware } from "langchain";

const authGate = createMiddleware({
  name: "AuthGate",
  beforeModel: (state, runtime) => {
    const server = runtime.serverInfo;
    if (server != null && server.user == null) {
      throw new Error("Authentication required");
    }
    console.log(`Thread: ${runtime.executionInfo.threadId}`);
    return;
  },
});
需要 deepagents>=1.9.0（或 @langchain/langgraph>=1.2.8）。
在 GitHub 上编辑此页面 或提交问题。
通过 MCP 将这些文档连接到 Claude、VSCode 等 以获取实时答案。