代理是一个模型在循环中调用工具，直到给定任务完成。 核心代理循环图
Agent = Model + HarnessHarness 的职责：在给定任务中，在正确的时间向模型提供正确上下文。
Harness 是该循环周围的一切：模型、prompt、工具，以及任何塑造其行为的 middleware。 create_agent 是高度可配置的 harness。最简单的形式如下： 
import { createAgent } from "langchain";

const agent = createAgent({ model: "openai:gpt-5.4", tools });
直接配置基础项：model=、tools=、system_prompt=。如需更高级能力，请使用 middleware 扩展 harness。

​
核心组件

​
Model

传入模型标识符字符串（"provider:model"）或已初始化的模型实例。参数、provider 设置和动态模型选择请参阅 Models。 
import { createAgent } from "langchain";

const agent = createAgent({ model: "openai:gpt-5.4", tools });

​
Tools

传入任意 Python callable、LangChain tool 或 tool dict。工具定义、context 访问和动态工具选择请参阅 Tools。 
import { createAgent, tool } from "langchain";
import * as z from "zod";

const search = tool(({ query }) => `Results for: ${query}`, {
  name: "search",
  description: "Search for information",
  schema: z.object({ query: z.string() }),
});

const agent = createAgent({ model: "openai:gpt-5.4", tools: [search] });

​
System prompt

塑造代理处理任务的方式。接受字符串或 SystemMessage。如需运行时动态 prompts，请使用 middleware。 
const agent = createAgent({
  model: "openai:gpt-5.4",
  tools,
  systemPrompt: "You are a helpful assistant. Be concise and accurate.",
});

​
结构化输出

使用 response_format= 从代理返回经过验证的 schema。策略和示例请参阅 Structured output。 
import * as z from "zod";

const Answer = z.object({ summary: z.string(), confidence: z.number() });

const agent = createAgent({ model: "openai:gpt-5.4", tools, responseFormat: Answer });
const result = await agent.invoke({ messages: [{ role: "user", content: "Summarize AI trends" }] });
result.structuredResponse; // { summary: ..., confidence: ... }

​
Name

可选标识符。在 multi-agent 系统中将此代理作为 subgraph 嵌入时，它会用作节点名称。 
const agent = createAgent({ model: "openai:gpt-5.4", tools, name: "research_assistant" });
要用自定义字段扩展代理的状态 schema，请在 create_agent 上使用 state_schema，或通过 middleware 定义它。详情请参阅 Memory。

​
调用

使用 LangSmith 跟踪该循环的每一步、调试工具调用并评估代理输出。按照 tracing quickstart 完成设置。也建议设置 LangSmith Engine，它会监控 traces、检测问题并提出修复建议。
可以通过向代理的 State 传入更新来调用代理。所有代理的状态中都包含一个消息序列；要调用代理，请传入一条新消息以及 thread_id，让代理可以持久化并恢复对话历史： 
import { AIMessage } from "@langchain/core/messages";
import { createAgent } from "langchain";
import { MemorySaver } from "@langchain/langgraph";

const agent = createAgent({
  model: "google-genai:gemini-3.5-flash",
  tools: [],
  checkpointer: new MemorySaver(),
});

const config = { configurable: { thread_id: crypto.randomUUID() } };

let result = await agent.invoke(
  {
    messages: [
      { role: "user", content: "What's the weather in San Francisco?" },
    ],
  },
  config,
);

// A follow-up turn on the same conversation: reuse the same thread_id to keep history
result = await agent.invoke(
  { messages: [{ role: "user", content: "What about tomorrow?" }] },
  config,
);
使用 thread_id 持久化对话历史要求代理配置 checkpointer。部署到 LangSmith 时，会自动配置 checkpointer。在本地，请显式传入一个，例如 create_agent(..., checkpointer=InMemorySaver())。
如果还需要向工具和 middleware 传入每次运行的配置（例如用户 ID、API keys 或 feature flags），请将其作为 context 与 config 一起传入。使用 contextSchema 定义这些数据的形状，并通过 runtime.context 访问： 
import * as z from "zod";
import { AIMessage } from "@langchain/core/messages";
import { createAgent } from "langchain";
import { MemorySaver } from "@langchain/langgraph";

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

const agent = createAgent({
  model: "google-genai:gemini-3.5-flash",
  tools: [],
  contextSchema,
  checkpointer: new MemorySaver(),
});

const result = await agent.invoke(
  {
    messages: [
      { role: "user", content: "What's the weather in San Francisco?" },
    ],
  },
  {
    configurable: { thread_id: crypto.randomUUID() },
    context: { user_id: "user-123" },
  },
);
thread_id 限定对话范围（消息历史、checkpoints），而 context 携带工具和 middleware 在调用时读取的每次运行数据。二者通常一起传入。更多信息请参阅 tool context 和 Runtime。

​
流式传输

前面展示了如何使用 invoke 调用代理以获取最终响应。如果代理执行多个步骤，可能需要一段时间。要显示中间进度，可以在消息产生时将其流式传回。 
const stream = await agent.stream(
  {
    messages: [{
      role: "user",
      content: "Search for AI news and summarize the findings"
    }],
  },
  { streamMode: "values" }
);

for await (const chunk of stream) {
  // Each chunk contains the full state at that point
  const latestMessage = chunk.messages.at(-1);
  if (latestMessage?.content) {
    console.log(`Agent: ${latestMessage.content}`);
  } else if (latestMessage?.tool_calls) {
    const toolCallNames = latestMessage.tool_calls.map((tc) => tc.name);
    console.log(`Calling tools: ${toolCallNames.join(", ")}`);
  }
}
更多流式传输详情请参阅 Streaming。

​
配置 harness

create_agent 具有很强的扩展性。Middleware 是自定义的原语：每个部分处理一个关注点，在正确时刻接入代理循环，并可与其他部分自由组合。只选择用例需要的能力，跳过其余部分。 常见模式已作为一等 middleware 预构建。任何自定义能力都可以通过编写一个 middleware 实现。 Middleware 生命周期图 当代理承担复杂工作时，需要在几个关键领域获得支持。Middleware 生态系统覆盖了这些领域：

执行环境

工具、文件系统、sandboxes 和代码执行

上下文管理

Summarization、memory、skills 和 prompt caching

规划与委派

用于并行、隔离工作的 todo lists 和 subagents

容错

重试、fallbacks 和调用限制

Guardrails

PII detection 和内容控制

引导

高影响动作前的 human-in-the-loop 审批

​
执行环境

当代理可以采取动作，而不仅仅是生成文本时，它们才真正有用。执行环境为代理提供工作区：可调用的工具、可跨轮次读写文件的文件系统，以及用于运行脚本或 shell 命令的代码执行能力。 
import { createAgent } from "langchain";
import { FilesystemMiddleware, StateBackend } from "deepagents";

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [search],
  middleware: [new FilesystemMiddleware({ backend: new StateBackend() })],
});
请参阅 FilesystemMiddleware、Sandboxes、Interpreters。

​
上下文管理

每次模型调用都有固定上下文窗口。随着代理运行并累积历史、工具结果和中间步骤，该窗口会逐渐填满。Summarization 会在溢出前压缩历史；memory 会在启动时加载持久指令，让知识跨会话保留；skills 会按需浮现领域知识，而不是预先加载所有内容。 
import { FilesystemMiddleware, MemoryMiddleware, SkillsMiddleware, SummarizationMiddleware, StateBackend } from "deepagents";

const backend = new StateBackend();
const model = "anthropic:claude-sonnet-4-6";

const agent = createAgent({
  model,
  tools: [search],
  middleware: [
    new FilesystemMiddleware({ backend }),
    new SummarizationMiddleware({ model, backend }),
    new MemoryMiddleware({ backend, sources: ["./AGENTS.md"] }),
    new SkillsMiddleware({ backend, sources: ["./skills/"] }),
  ],
});
请参阅 SummarizationMiddleware、MemoryMiddleware、SkillsMiddleware、Context engineering。

​
规划与委派

复杂任务通常会超出单个上下文窗口可处理的范围。委派让主代理可以将工作拆分成多个部分，交给各自在隔离上下文中运行的 subagents，并专注于协调而不是执行。工作可以并行运行，主代理的上下文保持干净。 
import { createAgent, todoListMiddleware, tool } from "langchain";
import {
  createFilesystemMiddleware,
  createSubAgentMiddleware,
  StateBackend,
} from "deepagents";
import * as z from "zod";

const search = tool(({ query }) => `Search results for: ${query}`, {
  name: "search",
  description: "Search for a query and return a short summary.",
  schema: z.object({ query: z.string() }),
});

const backend = new StateBackend();

const agent = createAgent({
  model: "google-genai:gemini-3.5-flash",
  tools: [search],
  middleware: [
    createFilesystemMiddleware({ backend }),
    todoListMiddleware(),
    createSubAgentMiddleware({
      defaultModel: "anthropic:claude-sonnet-4-6",
      defaultTools: [],
      subagents: [
        {
          name: "researcher",
          description: "Searches and returns a structured summary.",
          systemPrompt:
            "Use the search tool to research the question and summarize key points.",
          tools: [search],
          model: "anthropic:claude-sonnet-4-6",
          middleware: [],
        },
      ],
    }),
  ],
});
请参阅 SubAgentMiddleware、Subagents。

​
容错

生产环境中的代理会遇到开发中很少出现的故障：rate limits、模型超时、瞬时 API 错误。容错 middleware 会在基础设施层处理这些问题，因此你的工具和业务逻辑不需要为每次调用包裹 try/catch。 
import {
  createAgent,
  modelRetryMiddleware,
  tool,
  toolRetryMiddleware,
} from "langchain";
import * as z from "zod";

const search = tool(({ query }) => `Search results for: ${query}`, {
  name: "search",
  description: "Search for a query and return a short summary.",
  schema: z.object({ query: z.string() }),
});

const agent = createAgent({
  model: "google-genai:gemini-3.5-flash",
  tools: [search],
  middleware: [
    modelRetryMiddleware({ maxRetries: 3 }),
    toolRetryMiddleware({ maxRetries: 2 }),
  ],
});
请参阅 modelRetryMiddleware、toolRetryMiddleware、Prebuilt middleware。

​
Guardrails

有些策略不能只写在 prompt 中，它们需要无论模型怎么做都能确定性执行。Guardrails 会在数据流经代理循环时拦截它，在工具结果进入模型上下文之前应用合规规则或内容策略。 
import { createAgent, piiMiddleware, tool } from "langchain";
import * as z from "zod";

const search = tool(({ query }) => `Search results for: ${query}`, {
  name: "search",
  description: "Search for a query and return a short summary.",
  schema: z.object({ query: z.string() }),
});

const agent = createAgent({
  model: "google-genai:gemini-3.5-flash",
  tools: [search],
  middleware: [piiMiddleware("email")],
});
请参阅 piiMiddleware、Prebuilt middleware。

​
引导

完全自主并不总是合适。Steering 让你无需重构代理，就能将人工放在特定决策点上，例如破坏性写入、昂贵 API 调用或任何需要判断的操作之前。代理会暂停并等待；人工批准、编辑或拒绝；执行继续。 
import { createAgent, humanInTheLoopMiddleware, tool } from "langchain";
import * as z from "zod";

const search = tool(({ query }) => `Search results for: ${query}`, {
  name: "search",
  description: "Search for a query and return a short summary.",
  schema: z.object({ query: z.string() }),
});

const agent = createAgent({
  model: "google-genai:gemini-3.5-flash",
  tools: [search],
  middleware: [humanInTheLoopMiddleware({ interruptOn: { writeFile: true } })],
});
请参阅 humanInTheLoopMiddleware、Human-in-the-loop。
create_deep_agent 会为长时间运行的编码和研究任务预组装这套栈（默认包含 filesystem、summarization、subagents 和 prompt caching）。完整预构建 harness 请参阅 Deep Agents。
Middleware 资源：
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.