运行时

概述

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-5.4",
  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 在 LangGraph Server 上运行时访问服务器特定元数据（助手 ID、已认证用户）：

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-5.4",
  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）。

---

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交问题。