Bin✳

学习笔记 · Obsidian

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

LangChainLangSmithPython
来源更新 2026-08-11下载 Markdown ↓

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

路线对比

维度Call from codeExport to code
运行位置Fleet 的 Agent Server自有本地/服务器
接入LangGraph SDK 或 RESTfleet-deepagents-export + Python 项目
状态stateless 或 thread-stateful取决于自建 graph/checkpointer
定制调用参数与已发布配置custom tools、middleware、skills、model、graph wiring
凭据LangSmith PAT 调 Fleet endpointprovider 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，同时必须设置：

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 infoGET/assistants/{AGENT_ID}
Create threadPOST/threads
Stateless waitPOST/runs/wait
Stateless streamPOST/runs/stream
Thread waitPOST/threads/{THREAD_ID}/runs/wait
Thread streamPOST/threads/{THREAD_ID}/runs/stream

所有请求至少带 JSON content type、PAT 和 auth scheme。完整参数、错误模型和兼容性以 01-Assistants配置版本与Schema、02-Threads状态Checkpoint与生命周期、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 版本。
← 继续探索AI 与智能体回到顶部 ↑