运行时

概述

LangChain 的 createAgent 底层运行于 LangGraph 的运行时之上。 LangGraph 暴露了一个 Runtime 对象，包含以下信息：

上下文：静态信息，如用户ID、数据库连接或其他依赖项，用于智能体调用。
存储：一个 BaseStore 实例，用于长期记忆。
流写入器：一个对象，用于通过 "custom" 流模式传输信息。
执行信息：当前执行的标识和重试信息（线程ID、运行ID、尝试次数）。
服务器信息：当运行于 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.5",
  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: "获取用户的邮件偏好。",
    schema: z.object({}),
  }
);

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

访问执行标识（线程ID、运行ID）使用 runtime.executionInfo，访问服务器特定元数据（助手ID、已认证用户）使用 runtime.serverInfo（当运行于 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: "一个使用执行和服务器信息的工具。",
    schema: z.object({}),
  }
);

当不运行于 LangGraph Server 时（例如，在本地开发期间），serverInfo 为 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.5",
  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）。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

概述

访问

工具内部

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

中间件内部

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

​概述

​访问

​工具内部

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

​中间件内部

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

概述

访问

工具内部

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

中间件内部

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