将深度智能体投入生产的最快方式是使用 [`deepagents deploy`](/oss/python/deepagents/deploy)，它打包您的智能体配置，并通过一条命令将其部署为 LangSmith 部署。或者，您可以直接配置 [LangSmith 部署](/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 部署快速入门](/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 部署](/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 消息、查询他们的数据仓库）时，您需要一种方式将用户的凭据传递给智能体，而无需硬编码它们。
**通过智能体认证的 OAuth。** [智能体认证](/langsmith/agent-auth)提供了一个托管的 OAuth 2.0 流程。配置一个 OAuth 提供程序，智能体就可以请求限定每个用户范围的令牌。首次使用时，智能体会[中断](/oss/python/langgraph/interrupts)执行并呈现一个 OAuth 同意 URL。用户认证后，智能体使用有效的令牌恢复执行。令牌会自动存储和刷新。
```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 调用
```
**沙箱的凭据注入。** 如果您的智能体在[沙箱](#sandboxes)内运行调用外部 API 的代码，[沙箱认证代理](/langsmith/sandbox-auth-proxy)可以自动将凭据注入出站请求，因此沙箱代码永远不会收到原始 API 密钥。有关设置详情，请参阅[管理密钥](#managing-secrets)。
**工作区密钥。** 对于所有用户共享的 API 密钥（例如，您组织的 LLM 提供商密钥、搜索 API 密钥），请将它们作为[工作区密钥](/langsmith/set-up-hierarchy#configure-workspace-settings)存储在 LangSmith 中。详情请参阅[管理密钥](#managing-secrets)。
### 异步
基于 LLM 的应用程序是 I/O 密集型的：调用语言模型、数据库和外部服务。异步编程允许这些操作并发运行而不是阻塞，从而提高吞吐量和响应能力。
检查点还支持：
* **无限期[中断](/oss/python/langgraph/interrupts)。** Human in the Loop的工作流可以暂停数分钟或数天，并准确地从上次中断的地方恢复。
* **[时间旅行](/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/set-up-hierarchy#configure-workspace-settings)存储在 LangSmith 中。这些在运行时作为环境变量对工作区中的所有智能体可用。
### 速率限制
这里的速率限制是指在单次运行内限制智能体自身的 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 部署](/langsmith/deployment)并配置重连，以便用户在连接中断时不会丢失进度。
```tsx theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { useStream } from "@langchain/react";
function App() {
const stream = useStream