---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - fleet
  - api
  - deep-agents
topic: LangSmith Fleet 代码调用、导出与生产边界
sources:
  - https://docs.langchain.com/langsmith/fleet/code
last_verified: 2026-08-11
---

# Fleet：代码调用、导出与生产边界

Fleet Agent 有两条代码路线：远程调用保留 Fleet/Agent Server 托管运行；Export to code 则下载配置，在自己的 Python/Deep Agents 项目运行。前者运维轻、能力与 UI 同步；后者可深度定制、版本控制和自管基础设施，但认证、依赖、部署与升级责任也随之转移。

## 路线对比

| 维度 | Call from code | Export to code |
|---|---|---|
| 运行位置 | Fleet 的 Agent Server | 自有本地/服务器 |
| 接入 | LangGraph SDK 或 REST | `fleet-deepagents-export` + Python 项目 |
| 状态 | stateless 或 thread-stateful | 取决于自建 graph/checkpointer |
| 定制 | 调用参数与已发布配置 | custom tools、middleware、skills、model、graph wiring |
| 凭据 | LangSmith PAT 调 Fleet endpoint | provider key、LangSmith IDs、MCP registry/OAuth |
| 运维 | 主要由 Fleet 承担 | 构建、部署、升级、监控、安全自行承担 |

## 远程调用认证

需要 Fleet Agent、LangSmith Personal Access Token（PAT），SDK 路线安装 LangGraph SDK。Client 的 `api_key` 或 HTTP `X-Api-Key` 放 PAT，同时必须设置：

```text
X-Auth-Scheme: langsmith-api-key
```

PAT 若不属于 Agent owner，private Agent 会以 `404 Not Found` 拒绝，以避免泄露资源存在性。Workspace Agent 的非 owner 可以执行与 UI 相同的只读操作；不要把 404 一概当 URL 错误，也不要以为共享 Run 权限等于可修改 Assistant 配置。

从 Agent sidebar > Advanced settings > Developer > View code snippets 取得准确 `agent_id` 与 `api_url`。PAT 放 `.env`/secret manager，禁止硬编码、提交或输出到日志。

## Assistant 配置探测

首次集成先 `GET /assistants/{agent_id}`（或 `client.assistants.get`）验证 URL、认证和 Agent 可见性，再开始 Run。调用方应检查返回的 graph/config/schema/version，而不是只看 200；发布后 Agent 配置变化可能改变工具、输入和输出语义。

## Stateless 与 stateful

### Stateless

`POST /runs/wait` 等待完整结果；`POST /runs/stream` 流式返回。SDK 对应 `client.runs.wait(None, agent_id, ...)` 和 `client.runs.stream(None, ...)`。没有 thread，不持久化对话历史，适合独立任务、后台作业和可重放请求。

### Stateful

先 `POST /threads` 创建 thread，再使用 `/threads/{thread_id}/runs/wait|stream`。同一 thread 的后续 run 能读取完整历史，适合会话和需要跨轮状态的工作流。

客户端必须把 thread ID 绑定到可信用户/业务会话，不能接受任意客户端传入后直接访问，否则会造成跨用户历史泄漏。长期对话还要控制 state 大小、保留期、并发 run 与删除策略。

### Streaming

示例使用 `stream_mode: updates`，并忽略只带 `run_id` 的控制 chunk。生产消费者还要处理：断线重连、重复 chunk、顺序、心跳、错误 frame、取消、服务端已完成但客户端超时，以及 UI backpressure。不能把收到 TCP 断开等同为 run 失败。

## REST 端点地图

| 能力 | 方法 | 路径 |
|---|---|---|
| Agent info | GET | `/assistants/{AGENT_ID}` |
| Create thread | POST | `/threads` |
| Stateless wait | POST | `/runs/wait` |
| Stateless stream | POST | `/runs/stream` |
| Thread wait | POST | `/threads/{THREAD_ID}/runs/wait` |
| Thread stream | POST | `/threads/{THREAD_ID}/runs/stream` |

所有请求至少带 JSON content type、PAT 和 auth scheme。完整参数、错误模型和兼容性以 [[../Agent-Server-API/01-Assistants配置版本与Schema]]、[[../Agent-Server-API/02-Threads状态Checkpoint与生命周期]]、[[../Agent-Server-API/03-Stateful与Stateless-Runs]] 为准。

## Export to code

导出要求 Python 3.11+，推荐 `uv`。官方 starter 位于 `fleet-deepagents-export/examples/template-agent`：

1. 克隆 repo 并复制 starter；
2. Fleet 导出 `.zip`，解到项目的 `fleet/`；
3. 从 `fleet/config.json -> metadata` 取 tenant、organization、user IDs；
4. `.env` 配置 provider key、LangSmith PAT/IDs 与 `BUILTIN_MCP_URL`；
5. `make setup` 安装，`make dev` 启 Studio，`make run` 启 terminal REPL。

导出目录包含：

- `AGENTS.md`：system prompt；
- `config.json`：model 与 workspace metadata；
- `tools.json`：MCP connections；
- 可选 `subagents/` 与 `skills/`。

## Fleet-owned 与 user-owned 分层

Starter 用目录边界避免 re-export 覆盖定制：

| 路径 | 所有者 | 用法 |
|---|---|---|
| `fleet/` | Fleet 导出物 | 新版本整体替换，不在里面手改 |
| `agent.py` | 用户 | graph wiring、model override |
| `custom_tools.py` | 用户 | code-defined tools，与 Fleet MCP tools 合并 |
| `custom_middleware.py` | 用户 | logging、filter、pre/post hooks |
| `custom_skills/` | 用户 | 覆盖之外的本地 skills |
| `cli.py` | 用户 | 本地交互入口 |

`StaticSkillsLoader` 将 `fleet/skills` 与 `custom_skills` 映射到不同虚拟路径；`load_agent_components` 解析导出配置；自定义 tools 追加到导出 tools；最终 `create_deep_agent` 组合 model、middleware 和 components。示例把 recursion limit 设为 1000，这只是示例值，生产要根据任务和预算收紧，不要照抄为默认。

Re-export 可以整体清空 `fleet/` 后重新解压，因为用户定制在目录外。但这是破坏性本地命令，自动化前要验证目标确实是项目内的 Fleet-owned 目录，并对导出包做校验、备份和差异审查。

## 模型与 MCP 认证

Starter 默认带 Anthropic、OpenAI、Google GenAI provider 包；Bedrock、Fireworks 等需添加对应 `langchain-<provider>` 依赖。Provider 切换不仅是装包，还要核对 model 名、结构化输出、tool call、stream、token、区域与数据策略。

启动时工具的 `mcp_server_url` 会在 LangSmith MCP registry 解析：

- built-in LangSmith tools：使用 `LANGSMITH_API_KEY`；
- `headers` static credential server：从 registry 取凭据，调用者需要 `mcp-servers:invoke`；
- OAuth server：从 LangSmith OAuth broker 取 bearer；未授权的 per-user server 首次运行会打开浏览器。

`LANGSMITH_USER_ID` 在使用 OAuth tools 时必需。Headless/container 环境无法交互打开浏览器时，必须提前完成授权或设计服务身份，不能让生产 job 卡在 OAuth 页面。

## 生产化建议

- Remote 调用先探测 Assistant schema/version；为 PAT 设短期、最小权限与轮换。
- Stateless 请求自带业务 idempotency key；stateful thread 绑定 tenant/user，限制并发写。
- Stream 消费器支持断点、去重、取消与最终状态查询。
- 导出 ZIP 进入供应链扫描：路径穿越、恶意 prompt/tool config、依赖、secret、内容 hash。
- `fleet/` 与自定义代码分别 version control；每次 re-export 审核 instructions、tools、approval、skills、subagents 和 model diff。
- 自定义 middleware 做输入/输出过滤、tool allowlist、审计、超时和异常归一化，但不要吞掉中断/审批语义。
- 在 CI 用最小 mock tools 做契约测试；在 staging 用真实 OAuth/MCP 验证，不把本地 Studio 通过等同生产可用。
- 记录 trace、token/LCU、工具延迟、重试、人工拒绝与业务结果；准备回滚到上一导出包/Assistant 版本。