将深度智能体投入生产的最快方式是 [`deepagents deploy`](/oss/python/deepagents/deploy)，它打包你的智能体配置并通过一条命令将其部署为 LangSmith Deployment。或者，你也可以直接配置 [LangSmith Deployment](/langsmith/deployment)。任何一种方式都会为你的智能体预置所需的基础设施：[助手](/langsmith/assistants)、[线程](/langsmith/use-threads)、[运行](/langsmith/runs)、存储和检查点器，因此你无需自己设置。它还开箱即用地提供[认证](/langsmith/auth)、[webhook](/langsmith/use-webhooks)、[定时任务](/langsmith/cron-jobs)和[可观测性](/langsmith/observability)，并可通过 [MCP](/langsmith/server-mcp) 或 [A2A](/langsmith/server-a2a) 暴露你的智能体。
有关基于 CLI 的方法，请参阅[使用 CLI 部署](/oss/python/deepagents/deploy)。有关手动设置，请参阅 [LangSmith Deployments 快速入门](/langsmith/deployment-quickstart)。
除非另有说明，本页面上的所有代码片段都使用以下 `langgraph.json`：
```json langgraph.json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"dependencies": ["."],
"graphs": {
"agent": "./agent.py:agent"
},
"env": ".env"
}
```
`langgraph.json` 是告诉 LangGraph 平台如何构建和运行你的应用程序的配置文件。它位于项目根目录，本地开发（使用 `langgraph dev`）和生产部署都需要它。关键字段包括：
| 字段 | 描述 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `dependencies` | 要安装的包。`["."]` 将当前目录作为包安装（从 `requirements.txt`、`pyproject.toml` 或 `package.json` 读取）。 |
| `graphs` | 将图 ID 映射到其代码位置。每个条目是 `"
#### 用户身份和访问控制
[LangSmith Deployments](/langsmith/deployment) 支持[自定义认证](/langsmith/custom-auth)来建立用户身份，以及[授权处理器](/langsmith/auth)来控制对线程、助手和存储命名空间等资源的访问。授权处理器在认证成功后运行，可以：
* 用所有权元数据标记资源（例如 `owner: user_id`）
* 返回过滤器，使用户只能看到自己的资源
* 对未授权操作返回 HTTP 403 拒绝访问
有关分步教程，请参阅[使对话私有化](/langsmith/resource-auth)。有关演练，观看[自定义认证视频](https://www.youtube.com/watch?v=DkNqgCz8cjE)。
你如何划定[记忆范围](#scoping)和[执行环境](#execution-environment)决定了用户之间共享哪些数据。详情请参阅以下章节。
#### 团队访问控制 (RBAC)
LangSmith 的[基于角色的访问控制](/langsmith/rbac)管理你团队中谁可以部署、配置和监控智能体。这与上述的终端用户授权是分开的。
| 角色 | 访问权限 |
| ------ | -------------------- |
| 工作区管理员 | 完整权限，包括设置和成员管理 |
| 工作区编辑者 | 创建和修改资源，但无法删除运行或管理成员 |
| 工作区查看者 | 只读访问 |
企业版提供具有细粒度权限的自定义角色。有关完整的权限模型，请参阅 [RBAC 参考](/langsmith/rbac)。
#### 终端用户凭证
当你的智能体需要代表用户调用外部 API（例如读取他们的 GitHub 仓库、发送 Slack 消息、查询他们的数据仓库）时，你需要一种将用户凭证传递给智能体的方式，而不是硬编码它们。
**通过 Agent Auth 的 OAuth。** [Agent Auth](/langsmith/agent-auth) 提供托管的 OAuth 2.0 流程。配置 OAuth 提供商，智能体即可请求限定到每个用户的 Token。首次使用时，智能体会[中断](/oss/python/langgraph/interrupts)执行并呈现 OAuth 同意 URL。用户认证后，智能体以有效 Token 恢复执行。Token 会自动存储和刷新。
```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_auth import Client
from langchain.tools import tool, ToolRuntime
auth_client = Client()
# 在你的智能体的工具中：
@tool
async def github_action(runtime: ToolRuntime):
"""代表用户在 GitHub 上执行操作。"""
auth_result = await auth_client.authenticate(
provider="github",
scopes=["repo", "read:org"],
user_id=runtime.server_info.user.identity, # [!code highlight]
)
# 使用 auth_result.token 代表用户调用 GitHub API
```
**沙箱的凭证注入。** 如果你的智能体在调用外部 API 的[沙箱](#sandboxes)中运行代码，[沙箱认证代理](/langsmith/sandbox-auth-proxy)可以自动将凭证注入到出站请求中，使沙箱代码永远不会接触到原始 API 密钥。详情请参阅[管理秘密](#managing-secrets)。
**工作区秘密。** 对于跨所有用户共享的 API 密钥（例如你组织的大语言模型（LLM）提供商密钥、搜索 API 密钥），将它们存储为 LangSmith 中的[工作区秘密](/langsmith/set-up-hierarchy#configure-workspace-settings)。详情请参阅[管理秘密](#managing-secrets)。
### 异步
基于大语言模型（LLM）的应用是高度 I/O 密集型的：调用语言模型、数据库和外部服务。异步编程让这些操作可以并发运行而非阻塞，提高吞吐量和响应能力。
检查点还支持：
* **无限期[中断](/oss/python/langgraph/interrupts)。** 人机协作工作流可以暂停几分钟或几天，然后从中断的位置精确恢复。
* **[时间旅行](/oss/python/langgraph/use-time-travel)。** 每个检查点步骤都是一个快照，你可以回退到该状态，如果出现问题可以从早期状态重放。
* **安全处理敏感操作。** 对于涉及支付或其他不可逆操作的工作流，检查点提供了审计追踪和恢复点，可以检查导致操作的确切状态。
### 范围划定
记忆始终跨对话持久化。主要问题是它如何在用户和助手边界之间划定范围。正确的范围取决于谁应该查看和修改数据：
| 范围 | 命名空间 | 用例 | 示例 |
| ------------ | ---------------- | ------------ | --------------- |
| **用户**（推荐默认） | `(user_id)` | 每个用户的偏好和上下文 | "我喜欢简洁的回复" |
| **助手** | `(assistant_id)` | 一个助手的共享指令 | "帖子限制在 280 个字符" |
| **全局** | `(org_id)` | 所有用户和助手的只读策略 | "不要公开内部定价" |
```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
"proxy_config": {
"rules": [
{
"name": "openai-api",
"match_hosts": ["api.openai.com"],
"inject_headers": {
"Authorization": "Bearer ${OPENAI_API_KEY}"
}
},
{
"name": "anthropic-api",
"match_hosts": ["api.anthropic.com"],
"inject_headers": {
"x-api-key": "${ANTHROPIC_API_KEY}"
}
}
]
}
}
```
`${SECRET_KEY}` 引用在 LangSmith [工作区设置](/langsmith/set-up-hierarchy#configure-workspace-settings)中存储的秘密进行解析。在创建引用它们的模板之前，请先在那里配置秘密。
**工作区秘密。** 对于不需要基于代理注入的 API 密钥（例如智能体服务器本身使用的密钥，而非沙箱代码），将它们存储为 LangSmith 中的[工作区秘密](/langsmith/set-up-hierarchy#configure-workspace-settings)。这些作为环境变量在工作区中所有智能体的运行时可用。
### 速率限制
这里的速率限制指的是限制智能体在运行中自身的大语言模型（LLM）和工具使用量，而非入站请求的 API 网关速率限制。
没有限制，困惑的智能体可能在几分钟内通过循环相同的工具调用或进行数百次模型调用耗尽你的大语言模型（LLM）API 预算。对每次运行中的模型调用和工具执行都设置上限：
```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from deepagents import create_deep_agent
from langchain.agents.middleware import ModelCallLimitMiddleware, ToolCallLimitMiddleware
agent = create_deep_agent(
model="google_genai:gemini-3.1-pro-preview",
middleware=[
ModelCallLimitMiddleware(run_limit=50),
ToolCallLimitMiddleware(run_limit=200),
],
)
```
使用 `run_limit` 限制单次调用中的调用数（每轮重置）。使用 `thread_limit` 限制整个对话中的调用数（需要检查点器）。参阅 [ModelCallLimitMiddleware](https://reference.langchain.com/python/langchain/agents/middleware/model_call_limit/ModelCallLimitMiddleware) 和 [ToolCallLimitMiddleware](https://reference.langchain.com/python/langchain/agents/middleware/tool_call_limit/ToolCallLimitMiddleware) 了解完整配置。
### 处理错误
不是所有错误都应该以相同方式处理。瞬时故障（网络超时、速率限制）应自动重试。大语言模型（LLM）可以恢复的错误（错误的工具输出、解析失败）应反馈给模型。需要人工输入的错误应暂停智能体。有关完整分类和代码示例，请参阅[适当处理错误](/oss/python/langgraph/thinking-in-langgraph#handle-errors-appropriately)。
中间件处理瞬时情况。模型调用和工具调用各自有带有指数退避的重试中间件。如果你的主要模型提供商完全宕机，回退中间件会切换到替代方案：
```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from deepagents import create_deep_agent
from langchain.agents.middleware import (
ModelFallbackMiddleware,
ModelRetryMiddleware,
ToolRetryMiddleware,
)
agent = create_deep_agent(
model="google_genai:gemini-3.1-pro-preview",
middleware=[
# 在速率限制、超时和 5xx 错误时重试模型调用
ModelRetryMiddleware(max_retries=3, backoff_factor=2.0, initial_delay=1.0),
# 如果主模型完全宕机，回退到替代方案
ModelFallbackMiddleware("gpt-5.4"),
# 重试调用外部 API 的特定工具（不是所有工具）
ToolRetryMiddleware(
max_retries=2,
tools=["search", "fetch_url"],
retry_on=(TimeoutError, ConnectionError),
),
],
)
```
将 [ToolRetryMiddleware](https://reference.langchain.com/python/langchain/agents/middleware/tool_retry/ToolRetryMiddleware) 限定到特定工具，而非重试所有工具。文件系统的 `read_file` 失败不会因重试而受益，但超时的网络搜索可能会。参阅 [ModelRetryMiddleware](https://reference.langchain.com/python/langchain/agents/middleware/model_retry/ModelRetryMiddleware) 和 [ModelFallbackMiddleware](https://reference.langchain.com/python/langchain/agents/middleware/model_fallback/ModelFallbackMiddleware) 了解完整配置。
### 数据隐私
如果你的智能体处理可能包含邮箱、信用卡号或其他 PII 的用户输入，你可以在它到达模型或存入日志之前检测和处理它：
```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from deepagents import create_deep_agent
from langchain.agents.middleware import PIIMiddleware
agent = create_deep_agent(
model="google_genai:gemini-3.1-pro-preview",
middleware=[
PIIMiddleware("email", strategy="redact", apply_to_input=True),
PIIMiddleware("credit_card", strategy="mask", apply_to_input=True),
],
)
```
策略包括 `redact`（替换为 `[REDACTED_EMAIL]`）、`mask`（部分遮盖如 `****-****-****-1234`）、`hash`（确定性哈希）和 `block`（抛出错误）。你也可以为领域特定的模式编写自定义检测器。
参阅 [PIIMiddleware](https://reference.langchain.com/python/langchain/agents/middleware/pii/PIIMiddleware) 了解完整配置。
有关可用中间件的完整列表，请参阅[预置中间件](/oss/python/langchain/middleware/built-in)。
## 前端
深度智能体使用 [`useStream`](/oss/python/langchain/frontend/overview) 将 UI 连接到智能体后端。`useStream` 是一个前端钩子（适用于 React、Vue、Svelte 和 Angular），可从智能体实时流式传输消息、子智能体进度和自定义状态。
在本地，`useStream` 指向 `http://localhost:2024`。在生产环境中，将其指向你的 [LangSmith Deployment](/langsmith/deployment) 并配置重连，使用户在连接断开时不会丢失进度。
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { useStream } from "@langchain/react";
function App() {
const stream = useStream