Production Deep Agents 运行时指南：弹性执行、内存与多租户

✍ LangChain🕐 2026-05-06📦 38.1 KB 🟢 已读 𝕏 文章列表

本文探讨了将长运行周期的 Deep Agents 部署到生产环境所需的运行时基础设施。文章指出，除了 Agent 的 Harness（提示词、工具）外，更关键的是底层的 Runtime，它提供了弹性执行、持久化内存、多租户隔离、人在回路（HITL）和可观测性。文章详细介绍了如何通过检查点机制实现故障恢复与状态恢复，区分了短期与长期内存的存储策略，并阐述了在 Agent Server 中实现数据隔离与鉴权的多租户方案。

LangChain Agent Runtime 多租户系统架构持久化 HITL 生产环境 Deep Agents

# The runtime behind production deep agents **作者**: LangChain **日期**: 2026-05-05T16:06:21.000Z **来源**: [https://x.com/LangChain/status/2051694998932877338](https://x.com/LangChain/status/2051694998932877338) --- ![Image](/doc/1637/image/img_94b7a3e25c5e.jpg) This article by @sydneyrunkle and @Vtrivedy10 was originally featured on the LangChain blog. ## Key Takeaways - A good harness gives your agent the right prompts, tools, and skills. But deploying long-running agents in production requires durable execution, memory, multi-tenancy, human-in-the-loop, and observability. This infrastructure lives underneath the harness and keeps the agent running reliably across crashes, deploys, and long-running tasks. - Durable execution is the foundation everything else depends on. Agents that run for minutes or hours, pause for human approval, or survive mid-run deploys all need checkpointed execution that can stop, resume, and retry across process boundaries. Streaming, human-in-the-loop, cron jobs, and concurrent message handling all build on top of it. - Production agents need open and model-agnostic infrastructure. Deep Agents is MIT licensed, agents are exposed via open protocols (MCP, A2A), and memory lives in your own PostgreSQL. Teams keep full visibility into how their agent works and the ability to change it without a rewrite. Deploying long horizon agents in production requires purpose-built infrastructure. This guide covers durable execution, memory, HITL, observability, and how deepagents deploy ships it all to production. To build a good agent, you need a good harness. To deploy that agent, you need a good runtime. The harness is the system you build around the model to help your agent be successful in its domain. That includes prompts, tools, skills, and anything else supporting the model and tool calling loop that defines an agent. The runtime is everything underneath: durable execution, memory, multi-tenancy, observability, the machinery that keeps an agent running in production without your team reinventing it. This guide walks through the production requirements that surface once you deploy agents, the runtime capabilities that meet them, and how deepagents deploy packages those capabilities into something you can ship. ## Runtime capabilities for production agents Throughout this section, "the runtime" refers to LangSmith Deployment (LSD) and its Agent Server: LSD runs agents in production, and Agent Server is the interface for assistants, threads, runs, memory, and scheduled jobs. The table below maps each production requirement to the runtime primitive that meets it. ![Image](/doc/1637/image/img_b3b74a382506.jpg) # Durable execution Agents work by running a loop: Given a prompt, the model reasons, calls tools, observes the results, and repeats until it decides the task is complete. 📷 Unlike a typical web request that returns in milliseconds, this loop can span minutes or hours. A single run might make dozens of model calls, spawn subagents, or wait indefinitely for a human to approve a draft. A crash, deploy, or transient failure anywhere in that loop shouldn't erase the work leading up to it. In practice, you feel it in two places: Long runs need to survive infrastructure failures. A research agent spending twenty minutes gathering sources and synthesizing findings can't afford to restart from scratch if the worker process dies: the agent already paid for the tokens and executed the tool calls. What you want is resumption from the last completed step, with all prior state intact. Agents need to be able to stop and wait. An agent that pauses for a human to approve a transaction doesn't know if the human will respond in thirty seconds or three days. Tying up a worker process or a client connection for that entire window isn't viable. The agent needs to truly stop: free resources, release workers, then pick up later exactly where it left off. Both requirements are solved by the same thing: durable execution. - Agents run on a managed task queue with automatic checkpointing, so any run can be retried, replayed, or resumed from the exact point of interruption. - Each super-step of graph execution writes a checkpoint to the persistence layer (PostgreSQL by default), keyed by a thread_id that acts as a persistent cursor into the run. - When a worker crashes, the run's lease is released and another worker picks it up from the latest checkpoint. - When an agent waits for human input, the process hands off its slot and the run sleeps indefinitely until resumed. - Configurable retry policies control backoff, max attempts, and which exceptions trigger retries on a per-node basis. ![Image](/doc/1637/image/img_3164deb16199.jpg) Durability is the foundation the rest of this list depends on. Because execution can pause and resume across process boundaries, agents can wait indefinitely for human input, run in the background, survive deploys mid-run, and handle concurrent inputs without corrupting state. # Memory Agents need two different kinds of memory, and the distinction matters. Short-term memory is what the agent accumulates within a single conversation. The messages exchanged, the tool calls made, the intermediate state built up across a run. This lives in the checkpoint for the thread, scoped to a thread_id, and disappears (conceptually) when the conversation ends. A follow-up message on the same thread sees everything that came before on that thread. Long-term memory is what the agent carries across conversations. This can include user preferences learned across conversations, project conventions and best practices, or a knowledge base enhanced with each new query. None of this belongs to any single thread. It's user-level or organization-level context that should persist across every conversation the agent has. Checkpoints alone can't do this, because checkpoint state is scoped to a single thread. ![Image](/doc/1637/image/img_047b014e9f41.jpg) Long-term memory is what the Agent Server's built-in store is for. It's a key-value interface where memories are organized by namespace tuples (for example, (user_id, "memories")) and persisted across threads. Your agent writes to the store in one conversation and reads from it in the next. Backed by PostgreSQL by default, it supports semantic search via embedding configuration so agents can retrieve memories by meaning rather than exact match, and you can swap in a custom backend if you need different storage characteristics. The namespace structure is flexible: scope by user, assistant, organization, or any combination that fits your data model. Because memory that accumulates over months is some of the most valuable data the system produces, it matters where it lives. The store is queryable directly via API, and if you self-host, it lives in your own PostgreSQL instance. Keeping this data in a standard format you control is what lets you migrate between models, analyze it, or build on top of it outside the agent itself. # Multi-tenancy The moment your agent serves more than one user, a set of problems appears that didn't exist in single-player mode. These break down into three distinct concerns, and the Agent Server handles each with its own primitive. Isolating one user's data from another. User A's run should only touch User A's threads, and only read User A's memories. Custom authentication runs as middleware on every request: your @auth.authenticate handler validates the incoming credential and returns the user's identity and permissions, which get attached to the run context. Authorization handlers registered with @auth.on.threads, @auth.on.assistants.create, and so on then enforce who can see or modify what by tagging resources with ownership metadata on creation and returning filter dictionaries on reads. Handlers are matched from most specific to least, so you can start with a single global handler and add resource-specific ones as your model grows. Letting the agent act on behalf of a user. Agents often need to call third-party services using the user's credentials—reading their calendar, posting to their Slack, opening a PR in their repo. Agent Auth handles the OAuth dance and token storage for this pattern, so the agent gets user-scoped credentials at runtime without you managing the refresh flow yourself. The user authenticates once; the agent can act on their behalf across subsequent runs. Controlling who can operate the system itself. Separate from end-user access, there's the question of which members of your team can deploy agents, configure them, view traces, or change auth policies. RBAC handles this operator-level access control. The three layers compose: end users authenticate via your auth handler, the agent calls third-party services via Agent Auth, and your team operates the deployment under RBAC policies. ![Image](/doc/1637/image/img_94ed220df423.jpg) # Human-in-the-loop (HITL) Agents work by running a loop: given a prompt, a model reasons and decides to call tools, observes the results, and repeats until it decides it has completed the task at hand. Most of the time you want that loop to run uninterrupted. That’s where the value comes from. But sometimes you need a human in the middle of the loop at key decision points. There are two common situations where this comes up: 1. ‍Reviewing a proposed tool call. Before the agent executes a consequential action (sending an email, executing a financial transaction, deleting files), you want a human to see exactly what it's about to do and decide how to respond. Take the email case: the agent drafts a message and pauses before sending. You can approve it as-is, edit the subject or body before it goes out, or reject it with a reason and specific edit requests so the agent can revise and try again.‍ 2. An agent asking a clarifying question. Sometimes an agent reaches a decision point it can't resolve on its own, not because it lacks a tool but because the right answer depends on human judgment or preference. Rather than guessing, the agent can surface the question directly: "I found three config files matching that pattern. Which one should I modify?" or "Should this deploy to staging or production?" Your answer becomes the return value of the interrupt, and the agent continues from exactly where it stopped. The Agent Server handles this with two primitives: interrupt() pauses execution and surfaces a payload to the caller; Command(resume=...) continues it with the human's response. Together they let you build approval gates, draft review loops, input validation, and any workflow where a human needs to weigh in mid-execution. ![Image](/doc/1637/image/img_f17d836c18f3.jpg) Under the hood, interrupt() triggers the runtime's checkpointer to write the full graph state to durable storage, keyed by a thread_id that acts as a persistent cursor. The process then frees resources and waits indefinitely. Unlike static breakpoints that pause before or after specific nodes, interrupt() is dynamic: place it anywhere in your code, wrap it in conditionals, or embed it inside a tool function so approval logic travels with the tool. When Command(resume=...) arrives—minutes, hours, or days later—the resume value becomes the return value of the interrupt() call, and execution picks up exactly where it stopped. Because resume accepts any JSON-serializable value, the response isn't limited to approve/reject: a reviewer can return an edited draft, a human can supply missing context, a downstream system can inject computed results. When parallel branches each call interrupt(), all pending interrupts are surfaced together and can be resumed in a single invocation, or one at a time as responses come back. # Real-time interaction Human-in-the-loop is an interaction mode where execution can pause for a person to review or provide input—sometimes immediately, sometimes much later. Separately, there are “live session” problems that show up when the agent is actively working while the user is present: making progress visible (streaming) and coordinating concurrent messages (double-texting). ## Streaming An agent that takes thirty seconds to produce a response leaves the user staring at a spinner with no signal about whether it's making progress, stuck, or about to fail. They also can't start reading the answer until the whole thing is done. Streaming solves both: partial output flows to the client as the agent produces it, so the user sees the response materialize in real time. The Streaming API supports several modes depending on what granularity you want: full state snapshots after each graph step, state updates only, token-by-token LLM output, or custom application events. You can also combine them. Run streaming (client.runs.stream()) is scoped to a single run; thread streaming (client.threads.joinStream()) opens a long-lived connection that delivers events from every run on a thread, useful when follow-up messages, background runs, or HITL resumptions all trigger activity on the same thread. Thread streaming supports resumption via the Last-Event-ID header: the client reconnects with the ID of the last event it received, and the server replays from there with no gaps. Without this, every dropped connection means the client either misses output or has to start over. ## Double-texting The second real-time problem: a user sends a new message while the agent is still working on the previous one. This happens constantly in chat UIs. Someone types a question, realizes they meant something slightly different, and fires off a correction before the first run finishes. We call this double-texting, and the runtime has to take a position on how to handle it. There are four strategies, and the right one depends on your application: - enqueue (the default): The new input waits for the current run to finish, then processes sequentially. - reject: Refuse any new input until the current run finishes. - interrupt: Halt the current run, preserve progress, and process the new input from that state. Useful when the second message builds on the first. - rollback: Halt the current run, revert all progress including the original input, and process the new message as a fresh run. Useful when the second message replaces the first. ![Image](/doc/1637/image/img_f5f3f73d21e7.jpg) interrupt gives the snappiest chat feel but requires your graph to handle partial tool calls cleanly (a tool call initiated but not completed when the interrupt hits may need cleanup on resume). enqueue is the safest default—no state corruption, at the cost of making the user wait. Guardrails Not every production concern can be expressed as "run the loop durably." Some have to shape the loop itself: intercepting model inputs, filtering tool outputs, enforcing limits on expensive operations. These policies belong in code, not in a prompt. They need to run every time, not whenever the model happens to remember them. Two cases make this concrete: 1. ‍Redacting sensitive data before the model sees it. A customer support agent processes user messages containing PII (names, emails, account numbers). You don't want the model to see them, you don't want them in traces, and compliance likely requires redaction before logging. This has to happen before every model call, deterministically.‍ 2. Capping expensive operations. An agent that can call a paid external API needs a hard ceiling on how many calls it makes per run, because a confused model will otherwise happily call it fifty times and burn through your budget before lunch. Both are handled by middleware, which wraps the agent loop at defined hooks—before_model, wrap_model_call, wrap_tool_call, after_model—so policies execute deterministically around every relevant step. ![Image](/doc/1637/image/img_6aaabc220d54.jpg) LangChain ships built-in middleware covering the common cases: PIIRedactionMiddleware, ModelRetryMiddleware, ModelFallbackMiddleware, ToolCallLimitMiddleware, SummarizationMiddleware, HumanInTheLoopMiddleware, OpenAIModerationMiddleware, and you can write custom middleware for application-specific policies. Middleware is open source, but it only really pays off when it runs inside the agent runtime. When it does, those same policies become part of every interaction mode the runtime supports—streaming, human-in-the-loop pauses/resumes, retries, background runs, and long-lived threads. In practice, that means your guardrails and instrumentation aren’t “best effort”: they consistently wrap every model call and every tool call, at the exact points you expect, no matter what the agent is doing. # Observability You don't know what an agent will do in production until you run it. Unlike a traditional application where you can reason about behavior from the code, an agent's execution path depends on the model's choices at runtime: which tools to call, what to pass them, how to interpret the results, and when to give up and try something else. When something goes wrong, you can't just re-read the function. You need to see what actually happened. A support ticket says "the agent kept asking the same question over and over." Without traces, you're guessing from the user's description. With traces, you see the full execution tree: the user's message, the model's planned response, the tool it called, the result it got back, the next message it generated, the loop it fell into. You can filter by cost to find runs that burned through tokens, by error to find runs that failed, by user to see what a specific customer experienced. You can spot patterns across thousands of runs that no individual trace would reveal. Every LangSmith Deployment is automatically wired to a tracing project. You get the full execution tree out of the box—model calls, tool calls, subagent runs, middleware hooks—with structured metadata you can query by user, time window, cost, latency, error state, feedback, or custom tags. Traces are the foundation of the improvement loop: ![Image](/doc/1637/image/img_496480b9f560.jpg) Polly, the LangSmith AI assistant, analyzes traces and surfaces insights—common failure modes, slow tool calls, repeated patterns—so you're not reading thousands by hand. Online Evals run LLM-as-judge or custom scorers against production traces automatically, so regressions get caught as they happen. We used this loop to improve Deep Agents by 13.7 points on Terminal Bench 2.0 by only changing the harness—the whole argument for why the agent improvement loop starts with a trace is worth reading in full. # Time travel Observability tells you what happened. Time travel lets you ask what would have happened if something had gone differently. The motivating case is debugging a run that went off the rails. Your agent made a bad decision at step 5 of a 20-step run: it called the wrong tool, misread a tool result, or asked a clarifying question when it should have kept going. You want to understand why, and you want to try alternatives without re-running the whole thing from scratch. More generally, any time an agent's path depends on state at a particular checkpoint, you want the ability to rewind to that checkpoint, change the state, and let the rest of the run unfold differently. Because every super-step writes a checkpoint, every point in a run's history is already a snapshot you can return to. Time travel makes this explicit: pick a checkpoint from a thread's history, optionally modify its state, and resume from there. The modified checkpoint forks the thread's history. The original stays intact, and the new path runs forward as its own branch. LLM calls, tool calls, and interrupts all re-trigger on replay, so forks exercise the real agent loop rather than a stub of it. ![Image](/doc/1637/image/img_6006f961ff37.jpg) This unlocks patterns that are hard to build otherwise: debugging why the agent chose tool A when it should have chosen tool B, comparing two prompts against the same upstream context, recovering from a run that went sideways by rewinding to the last good state, or exploring counterfactuals across many forks to understand model behavior. The LangSmith Studio UI gives you a visual interface for all of this; the API is what most production debugging workflows end up using. # Code execution An agent that can only call the tools you pre-wired is limited to what you anticipated. An agent that can run arbitrary code is general-purpose: it can install dependencies, clone repos, execute tests, run data analysis, generate documents, and render plots. This is the gap between "chatbot with function calling" and "agent that can actually do things." Arbitrary code execution requires isolation. If the agent runs rm -rf / on your host, you have a bad day. If it reads your environment variables, it exfiltrates your API keys. You need a boundary between the agent's execution environment and everything you care about, and you need it before the agent writes its first command. In Deep Agents, isolation happens through sandbox backends. When you configure a backend that implements SandboxBackendProtocol, the agent automatically gets an execute tool for running shell commands in the sandbox alongside the standard filesystem tools. Without a sandbox backend, the execute tool isn't even visible to the agent. Supported providers include Daytona, Modal, Runloop, and LangSmith Sandboxes, and you can swap between them with a single configuration change. LangSmith Sandboxes (currently in private preview) are worth a specific callout because they're built to integrate with the rest of the runtime. Templates define container images, resource limits, and volumes declaratively. Warm pools pre-provision sandboxes with automatic replenishment, eliminating cold start latency for interactive agents. And the auth proxy solves a problem every team hits eventually: the agent needs to call authenticated APIs, but putting credentials inside the sandbox is a security risk. The proxy runs as a sidecar, intercepts outbound requests, and injects credentials from workspace secrets automatically—the sandbox code calls api.openai.com with no headers, and the proxy adds the right Authorization header on the way out. Secrets never enter the sandbox, and the agent can't exfiltrate what it can't see. ![Image](/doc/1637/image/img_b3d926c76f74.jpg) One piece of security guidance worth repeating: sandboxes protect your host, not the sandbox itself. An attacker who controls the agent's input (via prompt injection in a scraped webpage, a malicious email, a poisoned tool result) can instruct the agent to run commands inside the sandbox. The sandbox keeps the attacker off your machine, but anything inside the sandbox—including credentials placed there directly—is compromised. The auth proxy pattern exists for exactly this reason. # Integrations Agents are most useful when they plug into the systems people and organizations already use. A coding agent becomes more powerful when it can reach into GitHub, Linear, and your CI system. A research agent becomes more useful when its output feeds into your publishing pipeline. An internal agent becomes a platform when other agents can call it as a building block. If every one of those integrations is a hand-rolled adapter, your agents stay isolated. The boundary between "agent" and "everything else" becomes a wall. Open protocols solve this by letting agents and external systems discover and talk to each other without either side knowing the other's implementation. The Agent Server provisions three integration surfaces automatically. # MCP MCP (Model Context Protocol) is the open standard for connecting agents to tools and data sources. Every LangSmith Deployment automatically exposes an MCP endpoint, making your agent discoverable by any MCP-compliant client—Claude Desktop, IDEs, other agents, custom applications—without you writing adapter code. In the other direction, your agent can call out to any MCP server (Linear, GitHub, Notion, and hundreds of others) to reach tools and data your users already have. # A2A A2A (Agent-to-Agent) is the analogous standard for agent-to-agent communication, and every deployment exposes an A2A endpoint automatically as well. This is what makes multi-agent architectures across deployments tractable: an orchestrator agent in one deployment can discover and call worker agents in another using a protocol both sides understand, with no hand-rolled HTTP contracts. # Webhooks Webhooks handle the outbound case: your agent finishes a run, and you want to kick off something downstream without polling. Pass a webhook URL when creating a run, and the server POSTs the run payload to that URL on completion. This is how you chain agent runs into existing workflows—a research run completes and triggers a publishing pipeline, a daily summary finishes and notifies Slack, a compliance check completes and writes to your audit log. Headers, domain allowlists, and HTTPS enforcement are all configurable for production environments. # Cron The agents we've been talking about so far are reactive: a user sends a message, the agent responds. But a lot of valuable agent work is proactive—it happens on a schedule, with no human triggering it. Two patterns in particular: 1. Sleep-time compute. Agents that do useful work during idle periods, so users benefit from accumulated thinking rather than on-demand latency. A research agent that runs nightly to catch up on new papers in your field. A prep agent that reviews tomorrow's calendar and drafts briefing notes before you start your day. A triage agent that classifies overnight support tickets so your team walks into a prioritized queue. The work happens while nobody's waiting, and the output is ready when the user shows up. 2. Health and monitoring loops. Agents that periodically check on something and act (or escalate) if they find an issue. An on-call agent that reviews alerts every fifteen minutes, an agent that monitors your staging environment for regressions, a compliance agent that sweeps for policy violations on a cadence. These need the same durability, tracing, and auth as user-facing runs, but no user is waiting on them. The Agent Server has cron jobs built in, so scheduled runs get the same durability, tracing, and auth guarantees as any other run—no separate scheduler to maintain, no second observability story to wire up. You pass a standard cron expression (UTC) and an input, and the server triggers runs on schedule. Two flavors fit different patterns: 1. Stateful cron (client.crons.create_for_thread) ties the schedule to a specific thread_id, so every triggered run appends to the same conversation. This fits agents that should see their own history—a daily research agent that builds on yesterday's findings, or a monitoring agent that remembers what it already flagged. 2. .Stateless cron (client.crons.create) spins up a fresh thread for each execution, which fits batch-style work that doesn't need continuity between runs. Control thread cleanup via on_run_completed: "delete" (the default) removes the thread when the run finishes, "keep" preserves it for later retrieval viaclient.runs.search(metadata={"cron_id": cron_id}) ``` client.runs.search(metadata={"cron_id": cron_id}) ``` ![Image](/doc/1637/image/img_506e2f35a41f.jpg) Every cron run shows up in tracing, respects auth handlers and middleware, and supports resumption on failure—a cron that hits a transient model outage at 3am doesn't silently fail, it gets retried like any other run. One operational note: delete crons when you're done with them. They keep running (and billing) until you do. We see enterprise teams with varying deployment requirements, so the runtime supports cloud, hybrid, and self-hosted deployments. The capabilities are the same regardless of where you run it. # deepagents deploy deepagents deploy is the packaging step that deploys your agent on the runtime described above. You define your agent in deepagents.toml, and the CLI bundles your configuration and deploys it as a LangSmith Deployment with all of the aforementioned features. ![Image](/doc/1637/image/img_3b055621c21f.jpg) Memory uses a virtual filesystem with pluggable backends that gives agents both ephemeral scratch space and persistent cross-conversation storage. Deep Agents support memory scoped to users or assistants (or both)! Sandbox providers (LangSmith Sandboxes, Daytona, Modal, Runloop, or custom) are a single config value. When a sandbox is present, the harness automatically adds an execute tool. Sandbox lifecycle (thread-scoped vs assistant-scoped) is handled through graph factories. Credentials inside sandboxes are managed through the sandbox auth proxy so API keys never appear in sandbox code or logs. Skills and instructions are auto-detected from your skills/ directory and AGENTS.md. MCP servers are picked up from mcp.json. The name field is the only required config value; everything else has sensible defaults. The result is a deployment that can evolve over time, with new skills, tools, and memory policies, without a full rewrite. For the complete set of production considerations (credential management, async patterns, frontend integration, and more), see the going-to-production guide. # Open Harness There's a growing trend in agent infrastructure where moving to a managed solution comes with reduced builder choice—lock-in to a single model provider, a closed harness, or harness functionality hidden behind APIs (like server-side compaction that generates encrypted summaries you can't use outside one ecosystem). The practical consequence is that teams lose visibility into how their agent actually works, and lose the ability to change it when it doesn't. One note on vendor lock-in: deepagents deploy is built to avoid it. The harness is MIT licensed and fully open source, agent instructions use AGENTS.md (an open standard), and agents are exposed via open protocols—MCP, A2A, Agent Protocol. There's no model or sandbox lock-in, and nothing about the harness is a black box. The default harness offers the following capabilities: ![Image](/doc/1637/image/img_2664f91c305d.jpg) Additionally, Deep Agents allows you to inspect, customize, and extend every layer of agent behavior, including rate limits, retry logic, model fallback, PII detection, and file permissions via LangChain's middleware. ## Take your agents to production The capabilities this guide outlines—durable execution, memory, multi-tenancy, guardrails, human-in-the-loop, observability, sandboxed code execution, scheduled runs, and more—are the infrastructure requirements production agents can't function without. deepagents deploy packages all of it so teams don't have to assemble it from scratch, and keeps the stack open, configurable, and yours throughout. Building agents is a deeply iterative cycle: traces surface what's actually happening in production, online evals catch regressions before they compound, and memory means the agent gets more useful over time. The infrastructure isn't just supporting the live agent, it's the foundation for making it better. If you want to try it out, the quickstart will get you from deepagents.toml to a running deployment in minutes. For the full production playbook including memory scoping, sandbox lifecycle, credential management, guardrails, and frontend integration, see the going-to-production guide. For a deeper look at the runtime itself, see the LangSmith Deployment and Agent Server docs. ## 相关链接 - [LangChain](https://x.com/LangChain) - [@LangChain](https://x.com/LangChain) - [3.6K](https://x.com/LangChain/status/2051694998932877338/analytics) - [@sydneyrunkle](https://x.com/@sydneyrunkle) - [@Vtrivedy10](https://x.com/@Vtrivedy10) - [originally featured on the LangChain blog](https://www.langchain.com/blog/runtime-behind-production-deep-agents?utm_source=x&utm_medium=social) - [deepagents deploy](https://docs.langchain.com/oss/python/deepagents/deploy?_gl=1*13mofyu*_gcl_aw*R0NMLjE3NzcyOTY1ODcuQ2owS0NRandrcnpQQmhDcUFSSXNBSk40NjBsN3RfT0xOY1dYNmtlR2lrZTRrOXZpaHhMb0sxR2lvNzlOS3dHaElIRWdsYmVydWVDTXVoNGFBdEFFRUFMd193Y0I.*_gcl_au*OTc1MDI1MDQxLjE3NzYxMTY1MTg.*_ga*NjAyMTIyNDY4LjE3NzYxMTY1MTk.*_ga_47WX3HKKY2*czE3Nzc2Mzg3NzYkbzY4JGcxJHQxNzc3NjM4ODc5JGoyNiRsMCRoMA..) - [LangSmith Deployment (LSD)](https://docs.langchain.com/langsmith/deployment) - [Agent Server](https://docs.langchain.com/langsmith/agent-server) - [checkpointing](https://docs.langchain.com/oss/python/langgraph/persistence#checkpoints) - [super-step](https://docs.langchain.com/oss/python/langgraph/persistence#super-steps) - [retry policies](https://docs.langchain.com/oss/python/langgraph/use-graph-api#add-retry-policies) - [store](https://docs.langchain.com/oss/python/langgraph/persistence#memory-store) - [semantic search](https://docs.langchain.com/langsmith/semantic-search) - [swap in a custom backend](https://docs.langchain.com/langsmith/custom-store) - [API](https://docs.langchain.com/langsmith/server-api-ref) - [Custom authentication](https://docs.langchain.com/langsmith/custom-auth) - [@auth](https://x.com/@auth) - [Authorization handlers](https://docs.langchain.com/langsmith/auth#authorization) - [@auth](https://x.com/@auth) - [@auth](https://x.com/@auth) - [Agent Auth](https://docs.langchain.com/langsmith/agent-auth) - [RBAC](https://docs.langchain.com/langsmith/rbac) - [interrupt()](https://docs.langchain.com/oss/python/langgraph/interrupts) - [Command(resume=...)](https://docs.langchain.com/oss/python/langgraph/interrupts#resuming-interrupts) - [checkpointer](https://docs.langchain.com/oss/python/langgraph/persistence) - [Streaming API](https://docs.langchain.com/langsmith/streaming) - [client.runs.stream](https://client.runs.stream/) - [thread streaming](https://docs.langchain.com/langsmith/streaming#stream-a-thread) - [Last-Event-ID header](https://docs.langchain.com/langsmith/streaming#resume-from-last-event) - [double-texting](https://docs.langchain.com/langsmith/double-texting) - [enqueue](https://docs.langchain.com/langsmith/enqueue-concurrent) - [reject](https://docs.langchain.com/langsmith/reject-concurrent) - [interrupt](https://docs.langchain.com/langsmith/interrupt-concurrent) - [rollback](https://docs.langchain.com/langsmith/rollback-concurrent) - [middleware](https://docs.langchain.com/oss/python/langchain/middleware) - [built-in middleware](https://docs.langchain.com/oss/python/langchain/middleware/built-in) - [custom middleware](https://docs.langchain.com/oss/python/langchain/middleware/custom) - [You don't know what an agent will do in production until you run it.](https://blog.langchain.com/you-dont-know-what-your-agent-will-do-until-its-in-production/) - [automatically wired to a tracing project](https://docs.langchain.com/langsmith/observability) - [Polly](https://docs.langchain.com/langsmith/polly) - [Online Evals](https://docs.langchain.com/langsmith/online-evaluations-llm-as-judge) - [improve Deep Agents by 13.7 points on Terminal Bench 2.0](https://blog.langchain.com/improving-deep-agents-with-harness-engineering/) - [the agent improvement loop starts with a trace](https://www.langchain.com/conceptual-guides/traces-start-agent-improvement-loop) - [checkpoint](https://docs.langchain.com/oss/python/langgraph/persistence) - [Time travel](https://docs.langchain.com/langsmith/human-in-the-loop-time-travel) - [Studio UI](https://docs.langchain.com/langsmith/studio) - [API](https://docs.langchain.com/langsmith/human-in-the-loop-time-travel) - [sandbox backends](https://docs.langchain.com/oss/python/deepagents/sandboxes) - [SandboxBackendProtocol](https://docs.langchain.com/oss/python/deepagents/sandboxes#the-execute-method) - [Supported providers](https://docs.langchain.com/oss/python/deepagents/sandboxes#available-providers) - [LangSmith Sandboxes](https://docs.langchain.com/langsmith/sandboxes) - [LangSmith Sandboxes](https://www.langchain.com/blog/introducing-langsmith-sandboxes-secure-code-execution-for-agents) - [Templates](https://docs.langchain.com/langsmith/sandbox-templates) - [Warm pools](https://docs.langchain.com/langsmith/sandbox-warm-pools) - [auth proxy](https://docs.langchain.com/langsmith/sandbox-auth-proxy) - [api.openai.com](https://api.openai.com/) - [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) - [automatically exposes an MCP endpoint](https://docs.langchain.com/langsmith/server-mcp) - [A2A (Agent-to-Agent)](https://a2a-protocol.org/) - [exposes an A2A endpoint automatically as well](https://docs.langchain.com/langsmith/server-a2a) - [Webhooks](https://docs.langchain.com/langsmith/use-webhooks) - [cron jobs](https://docs.langchain.com/langsmith/cron-jobs) - [viaclient.runs.search](https://viaclient.runs.search/) - [cloud](https://docs.langchain.com/langsmith/deploy-to-cloud) - [hybrid](https://docs.langchain.com/langsmith/deploy-with-control-plane) - [self-hosted](https://docs.langchain.com/langsmith/deploy-standalone-server) - [deepagents deploy](https://docs.langchain.com/oss/python/deepagents/deploy) - [virtual filesystem with pluggable backends](https://docs.langchain.com/oss/python/deepagents/harness) - [LangSmith Sandboxes, Daytona, Modal, Runloop](https://docs.langchain.com/oss/python/deepagents/sandboxes) - [Sandbox lifecycle](https://docs.langchain.com/oss/python/deepagents/going-to-production) - [sandbox auth proxy](https://docs.langchain.com/langsmith/sandbox-auth-proxy) - [AGENTS.md](https://agentskills.io/specification) - [going-to-production guide](https://docs.langchain.com/oss/python/deepagents/going-to-production) - [MIT licensed and fully open source](https://github.com/langchain-ai/deepagents) - [AGENTS.md](https://agentskills.io/specification) - [middleware](https://docs.langchain.com/oss/python/langchain/middleware/built-in) - [quickstart](https://docs.langchain.com/oss/python/deepagents/deploy) - [going-to-production guide](https://docs.langchain.com/oss/python/deepagents/going-to-production) - [LangSmith Deployment](https://docs.langchain.com/langsmith/deployment) - [Agent Server](https://docs.langchain.com/langsmith/agent-server) - [Upgrade to Premium](https://x.com/i/premium_sign_up) - [12:06 AM · May 6, 2026](https://x.com/LangChain/status/2051694998932877338) - [3,687 Views](https://x.com/LangChain/status/2051694998932877338/analytics) - [View quotes](https://x.com/LangChain/status/2051694998932877338/quotes) --- *导出时间: 2026/5/6 09:37:41* --- ## 中文翻译 # 生产级深度代理背后的运行时 **作者**: LangChain **日期**: 2026-05-05T16:06:21.000Z **来源**: [https://x.com/LangChain/status/2051694998932877338](https://x.com/LangChain/status/2051694998932877338) --- ![Image](/doc/1637/image/img_94b7a3e25c5e.jpg) 本文由 @sydneyrunkle 和 @Vtrivedy10 撰写，最初发布于 LangChain 博客。 ## 核心要点 - 一个好的“挽具”能为你的代理提供正确的提示词、工具和技能。但在生产环境中部署长期运行的代理需要持久化执行、记忆、多租户、人机协作和可观测性。这些基础设施位于挽具之下，确保代理在崩溃、部署和长期运行的任务中依然可靠运行。 - 持久化执行是其他一切依赖的基础。运行数分钟或数小时的代理、等待人工批准的代理，或能在运行中途通过部署存活的代理，都需要通过检查点机制来实现跨进程的停止、恢复和重试。流式传输、人机协作、定时任务和并发消息处理都构建在此基础之上。 - 生产级代理需要开放且与模型无关的基础设施。Deep Agents 采用 MIT 许可证，代理通过开放协议（MCP, A2A）暴露，且数据存储在你自己的 PostgreSQL 中。团队可以完全了解其代理的工作原理，并能在不重写代码的情况下进行修改。在生产环境中部署长周期的代理需要专门构建的基础设施。本指南涵盖了持久化执行、记忆、人机协作（HITL）、可观测性，以及 deepagents deploy 如何将所有这些功能交付到生产环境。要构建一个好的代理，你需要一个好的挽具。要部署该代理，你需要一个好的运行时。挽具是你围绕模型构建的系统，用于帮助代理在其领域内取得成功。这包括提示词、工具、技能，以及任何其他支持模型和工具调用循环（定义了代理的要素）的东西。运行时则是其下的所有内容：持久化执行、记忆、多租户、可观测性，以及那些让代理在生产环境中运行而无需你的团队重新发明的机制。本指南将介绍部署代理后浮现的生产需求、满足这些需求的运行时能力，以及 deepagents deploy 如何将这些能力打包成你可以交付的产品。 ## 生产级代理的运行时能力在本节中，“运行时”指的是 LangSmith Deployment (LSD) 及其 Agent Server（代理服务器）：LSD 在生产环境中运行代理，而 Agent Server 是助手、线程、运行、记忆和定时任务的接口。下表将每个生产需求映射到满足它的运行时原语。 ![Image](/doc/1637/image/img_b3b74a382506.jpg) # 持久化执行代理通过运行一个循环来工作：给定一个提示词，模型进行推理，调用工具，观察结果，并重复此过程直到它判定任务完成。 📷 与毫秒级返回的典型 Web 请求不同，这个循环可能持续数分钟甚至数小时。单次运行可能会进行数十次模型调用，生成子代理，或无限期等待人工批准草稿。该循环中任何位置的崩溃、部署或瞬态故障都不应抹除在此之前完成的工作。在实践中，你会在两个地方感受到这一点： **长运行任务需要从基础设施故障中幸存。** 一个花费二十分钟收集资料并综合发现的研究代理，如果工作进程死机，无法承担从头重来的代价：代理已经为 Token 付了费，并执行了工具调用。你需要的是从最后完成的步骤恢复，并保持所有先前的状态完好无损。 **代理需要能够停止并等待。** 一个暂停以等待人工批准交易的代理不知道人类会在三十秒内还是三天后回应。在整个窗口期内占用一个工作进程或客户端连接是不可行的。代理需要真正停止：释放资源，释放工作进程，然后稍后从其确切停止的地方继续。这两个需求通过同一个东西解决：持久化执行。 - 代理运行在具有自动检查点功能的托管任务队列上，因此任何运行都可以从确切的干扰点进行重试、重放或恢复。 - 图执行的每个超步骤都会向持久层（默认为 PostgreSQL）写入一个检查点，以 thread_id 为键，作为运行中的持久游标。 - 当工作进程崩溃时，运行的租约会被释放，另一个工作进程会从最新的检查点接管。 - 当代理等待人工输入时，该进程会移交其位置，运行会无限期休眠，直到被恢复。 - 可配置的重试策略控制退避、最大尝试次数，以及哪些异常会在每个节点的基础上触发重试。 ![Image](/doc/1637/image/img_3164deb16199.jpg) 持久性是本列表其余部分依赖的基础。因为执行可以跨进程边界暂停和恢复，代理可以无限期等待人工输入、在后台运行、在运行中途通过部署存活，并处理并发输入而不会导致状态损坏。 # 记忆代理需要两种不同类型的记忆，这种区别很重要。 **短期记忆**是代理在单次对话中积累的内容。交换的消息、进行的工具调用、在运行中建立的中间状态。它存在于线程的检查点中，作用域限定为 thread_id，并在对话结束时（概念上）消失。同一线程上的后续消息能看到该线程上发生的所有先前内容。 **长期记忆**是代理跨对话携带的内容。这可以包括跨对话学习到的用户偏好、项目约定和最佳实践，或随着每次新查询而增强的知识库。这些都不属于任何单个线程。它是用户级或组织级的上下文，应该在代理的每次对话中持久存在。仅靠检查点无法做到这一点，因为检查点状态仅限于单个线程。 ![Image](/doc/1637/image/img_047b014e9f41.jpg) 长期记忆正是 Agent Server 内置存储的用途。它是一个键值接口，其中记忆按命名空间元组（例如 `(user_id, "memories")`）组织，并跨线程持久化。你的代理在一个对话中写入存储，并在下一个对话中读取。默认由 PostgreSQL 支持，它通过嵌入配置支持语义搜索，以便代理可以通过含义而非精确匹配来检索记忆，如果你需要不同的存储特性，可以换成自定义后端。命名空间结构很灵活：按用户、助手、组织或任何适合你的数据模型的组合进行限定。因为数月内积累的记忆是系统产生的最有价值的数据之一，所以它的存储位置很重要。该存储可通过 API 直接查询，如果你是自托管，它位于你自己的 PostgreSQL 实例中。将这些数据保持在你控制的标准格式中，使你能够迁移模型、分析数据或在代理本身之外基于数据进行构建。 # 多租户当你的代理服务于不止一个用户时，会出现单机模式下不存在的一组问题。这些问题分为三个不同的关注点，Agent Server 使用各自的原语来处理每一个。 **隔离一个用户与另一个用户的数据。** 用户 A 的运行应该只接触用户 A 的线程，并且只读取用户 A 的记忆。自定义身份验证作为中间件在每个请求上运行：你的 `@auth.authenticate` 处理程序验证传入的凭证并返回用户的身份和权限，这些信息会被附加到运行上下文。注册了 `@auth.on.threads`、`@auth.on.assistants.create` 等的授权处理程序，通过在创建时用所有权元组标记资源并在读取时返回过滤字典，来强制执行谁可以查看或修改什么。处理程序从最具体到最不具体进行匹配，因此你可以从单个全局处理程序开始，并随着模型的发展添加特定于资源的处理程序。 **让代理代表用户行事。** 代理通常需要使用用户的凭证调用第三方服务——阅读他们的日历、发布到他们的 Slack、打开他们仓库中的 PR。Agent Auth 处理这种模式的 OAuth 流程和令牌存储，因此代理在运行时获得用户范围的凭证，而无需你自己管理刷新流程。用户进行一次身份验证；代理可以在后续运行中代表他们行事。 **控制谁可以操作系统本身。** 与终端用户访问分开，还有一个问题，即你团队的哪些成员可以部署代理、配置代理、查看跟踪或更改身份验证策略。RBAC 处理此操作员级别的访问控制。这三层组合在一起：终端用户通过你的身份验证处理程序进行身份验证，代理通过 Agent Auth 调用第三方服务，而你的团队在 RBAC 策略下操作部署。 ![Image](/doc/1637/image/img_94ed220df423.jpg) # 人机协作 (HITL) 代理通过运行循环来工作：给定一个提示词，模型进行推理并决定调用工具，观察结果，并重复此过程直到它决定它已完成的任务。大多数情况下，你希望该循环不间断地运行。这就是价值所在。但有时你需要在关键决策点让人类介入循环。在两种常见情况下会出现这个问题： 1. ‍审查提议的工具调用。在代理执行重大操作（发送电子邮件、执行金融交易、删除文件）之前，你希望人类准确看到它即将执行的内容并决定如何响应。以电子邮件为例：代理起草一条消息并在发送前暂停。你可以按原样批准，在发送前编辑主题或正文，或以拒绝原因和具体的编辑请求拒绝它，以便代理修改并重试。‍ 2. 代理提出一个澄清问题。有时代理会遇到一个无法自行解决的决策点，不是因为它缺少工具，而是因为正确的答案取决于人类的判断或偏好。代理可以直接提出问题：“我找到了三个符合该模式的配置文件。我应该修改哪一个？”或“这是应该部署到暂存环境还是生产环境？”你的答案成为中断的返回值，代理从其确切停止的地方继续。 Agent Server 使用两个原语来处理这个问题：`interrupt()` 暂停执行并向调用者显示有效负载；`Command(resume=...)` 使用人类的响应继续执行。它们共同让你能够构建批准网关、草稿审查循环、输入验证，以及任何需要在执行中途进行人工投入的工作流。 ![Image](/doc/1637/image/img_f17d836c18f3.jpg) 在底层，`interrupt()` 触发运行时的检查点程序将完整的图状态写入持久存储，以 thread_id 为键，作为持久游标。然后该进程释放资源并无限期等待。与在特定节点之前或之后暂停的静态断点不同，`interrupt()` 是动态的：你可以将其放在代码中的任何位置，用条件将其包装，或将其嵌入到工具函数内部，以便批准逻辑随工具一起移动。当 `Command(resume=...)` 到达时——几分钟后、几小时后或几天后——恢复值将成为 `interrupt()` 调用的返回值，执行从其确切停止的地方继续。因为恢复接受任何可 JSON 序列化的值，所以响应不仅限于批准/拒绝：审查者可以返回编辑后的草稿，人类可以提供缺失的上下文，下游系统可以注入计算结果。当并行分支各自调用 `interrupt()` 时，所有待处理的中断会一起显示，并可以在单次调用中恢复，或者随着响应的到达逐个恢复。 # 实时交互人机协作是一种交互模式，执行可以暂停以供人员审查或提供输入——有时立即，有时很久以后。另外，当用户在场时代理正在积极工作时，会出现“实时会话”问题：使进度可见（流式传输）和协调并发消息（连发消息）。 ## 流式传输一个需要三十秒才能产生响应的代理会让用户盯着旋转指示器，而没有任何关于它是在取得进展、卡住还是即将失败的信号。他们也必须等到整个过程完成后才能开始阅读答案。流式传输同时解决了这两个问题：部分输出随着代理的产生流向客户端，因此用户可以看到响应实时显现。流式 API 根据你需要的粒度支持多种模式：每个图步骤后的完整状态快照、仅状态更新、逐个 Token 的 LLM 输出或自定义应用程序事件。你也可以组合它们。运行流式传输（`client.runs.stream()`）仅限于单次运行；线程流式传输（`client.threads.joinStream()`）打开一个长连接，传递线程上每次运行的事件，当后续消息、后台运行或 HITL 恢复都在同一线程上触发活动时，这非常有用。线程流式传输通过 `Last-Event-ID` 头支持恢复：客户端使用它收到的最后一个事件的 ID 重新连接，服务器从那里开始重放，没有间隙。没有这个，每次掉线都意味着客户端要么错过输出，要么必须重新开始。 ## 连发消息第二个实时问题：用户在代理仍在处理上一个消息时发送了一个新消息。这在聊天 UI 中经常发生。有人输入了一个问题，意识到他们的意思略有不同，并在第一次运行完成前发出更正。我们称之为连发消息，运行时必须采取关于如何处理它的立场。有四种策略，正确的一种取决于你的应用程序： - enqueue（默认）：新输入等待当前运行完成，然后按顺序处理。 - reject：拒绝任何新输入，直到当前运行完成。 - interrupt：停止当前运行，保留进度，并从该状态处理新输入。当第二条消息基于第一条消息时很有用。 - rollback：停止当前运行，恢复包括原始输入在内的所有进度，并将新消息作为新运行处理。当第二条消息替换第一条时很有用。 ![Image](/doc/1637/image/img_f5f3f73d21e7.jpg) interrupt 提供了最快捷的聊天感觉，但需要你的图干净地处理部分工具调用（在中断到达时启动但未完成的工具调用可能需要在恢复时进行清理）。enqueue 是最安全的默认设置——不会导致状态损坏，但代价是让用户等待。护栏并非每个生产问题都可以表达为“持久地运行循环”。有些必须塑造循环本身：拦截模型输入、过滤工具输出、对昂贵的操作强制执行限制。这些策略属于代码，而不属于提示词。它们需要每次都运行，而不是每当模型恰好记住它们时才运行。两个案例使这变得具体： 1. ‍在模型看到之前编辑敏感数据。客户支持代理处理包含 PII（姓名、电子邮件、账号）的用户消息。你不希望模型看到它们，你不希望它们出现在跟踪中，并且合规性可能要求在记录之前进行编辑。这必须在每次模型调用之前确定性地发生。‍ 2. 限制昂贵的操作。一个可以调用付费外部 API 的代理需要限制每次运行进行多少次调用的硬上限，否则一个困惑的模型会在午餐前愉快地调用它五十次并烧光你的预算。两者都由中间件处理，中间件在定义的钩子处包裹代理循环——`before_model`、`wrap_model_call`、`wrap_tool_call`、`after_model`——以便策略确定性地执行...

🔗 相关文档