在代码中使用 Fleet agent

通过 LangGraph SDK 或 REST API 调用 Fleet agent，或用 fleet-deepagents-export 包把它们下载并在本地运行。

以编程方式使用 Fleet agent 有两种主要方式：

从代码调用：通过 LangGraph SDK 或 REST API 远程调用你的 agent，不下载任何东西。
导出到代码：下载你的 agent 配置，并用 fleet-deepagents-export 包把它作为一个自包含的 Python 项目在本地运行。

从代码调用

你可以用 LangGraph SDK 或 REST API 从你的应用调用 LangSmith Fleet agent。Fleet agent 运行在 Agent Server 上，因此你可以使用与任何其他 LangSmith 部署相同的 API 方法。

REST API 让你能从任何支持 HTTP 请求的语言或平台调用你的 agent。

前提条件

一个带 Fleet agent 的 LangSmith 账户
一个用于身份验证的个人访问令牌（PAT）
（仅 SDK）已安装的 LangGraph SDK：

PythonTypeScript

bash

pip install langgraph-sdk python-dotenv

bash

yarn add @langchain/langgraph-sdk

认证

要与你 agent 的 Fleet 部署进行身份验证，在实例化 LangGraph SDK 客户端时向 api_key 参数提供一个 LangSmith个人访问令牌（PAT），或通过 X-API-Key 标头。如果使用 X-API-Key，你还必须把 X-Auth-Scheme 标头设为 langsmith-api-key。

如果你传入的 PAT 没有绑定到 agent 的所有者，你的请求会被拒绝并返回一个 404 Not Found 错误。

如果你正尝试调用的 agent 是一个

而你不是所有者，你可以执行与你在 UI 中所做的所有相同操作（只读）。

1. 获取 agent ID 和 URL

要获取你 agent 的 agent_id 和 api_url：

在 LangSmith UI中，打开你的 agent。
在侧边栏中，展开 Advanced settings 抽屉。
在 Developer 下，点击 View code snippets 以查看为你 agent 预填的值。

复制下面的代码，并用你 agent 代码片段中的值替换 agent_id 和 api_url。

在你的项目根目录创建一个带你的个人访问令牌的 .env 文件：

bash

LANGGRAPH_API_KEY=your-personal-access-token

2. 获取 agent 配置

通过获取你 agent 的配置来验证你的连接：

python

import os
from dotenv import load_dotenv
from langgraph_sdk.client import get_client

load_dotenv()

agent_id = "your-agent-id"

api_key = os.getenv("LANGGRAPH_API_KEY")
api_url = "<AGENT-BUILDER-URL>.us.langgraph.app"

client = get_client(
    url=api_url,
    api_key=api_key,
    headers={
        "X-Auth-Scheme": "langsmith-api-key",
    },
)

async def get_assistant(agent_id: str):
    agent = await client.assistants.get(agent_id)
    print(agent)

if __name__ == "__main__":
    import asyncio
    asyncio.run(get_assistant(agent_id))

INFO

使用一个绑定到你 LangSmith 账户的个人访问令牌（PAT）。把 X-Auth-Scheme 标头设为 langsmith-api-key 以进行身份验证。

3. 调用 agent

下面的示例展示如何向你的 agent 发送一条消息并接收响应。你可以使用一个无状态运行（无线程、无对话历史），或一个有状态运行（带一个线程以跨多轮维护对话历史）。

无状态运行

一个无状态运行发送单个请求并返回完整响应。不持久化任何对话历史。这是调用你 agent 最简单的方式：

python

import os
from dotenv import load_dotenv
from langgraph_sdk.client import get_client

load_dotenv()

agent_id = "your-agent-id"

api_key = os.getenv("LANGGRAPH_API_KEY")
api_url = "https://<AGENT-BUILDER-URL>.us.langgraph.app"

client = get_client(
    url=api_url,
    api_key=api_key,
    headers={
        "X-Auth-Scheme": "langsmith-api-key",
    },
)

result = await client.runs.wait(
    None,
    agent_id,
    input={
        "messages": [
            {"role": "user", "content": "What can you help me with?"}
        ]
    },
)
print(result)

无状态流式运行

要在响应生成时流式接收它而非等待完整结果，使用流式端点：

python

async for chunk in client.runs.stream(
    None,
    agent_id,
    input={
        "messages": [
            {"role": "user", "content": "What can you help me with?"}
        ]
    },
    stream_mode="updates",
):
    if chunk.data and "run_id" not in chunk.data:
        print(chunk.data)

带线程的有状态运行

要跨多次交互维护对话历史，先创建一个线程，然后在其上运行你的 agent。同一线程上的后续每次运行都能访问完整的消息历史：

python

import os
from dotenv import load_dotenv
from langgraph_sdk.client import get_client

load_dotenv()

agent_id = "your-agent-id"

api_key = os.getenv("LANGGRAPH_API_KEY")
api_url = "<AGENT-BUILDER-URL>.us.langgraph.app"

client = get_client(
    url=api_url,
    api_key=api_key,
    headers={
        "X-Auth-Scheme": "langsmith-api-key",
    },
)

thread = await client.threads.create()

async for chunk in client.runs.stream(
    thread["thread_id"],
    agent_id,
    input={
        "messages": [
            {"role": "user", "content": "Hi, my name is Alice."}
        ]
    },
    stream_mode="updates",
):
    if chunk.data and "run_id" not in chunk.data:
        print(chunk.data)

async for chunk in client.runs.stream(
    thread["thread_id"],
    agent_id,
    input={
        "messages": [
            {"role": "user", "content": "What is my name?"}
        ]
    },
    stream_mode="updates",
):
    if chunk.data and "run_id" not in chunk.data:
        print(chunk.data)

REST API 参考

下表概述了关键端点。把 <API_URL> 替换为你 agent 的部署 URL。

操作	方法	端点
获取 agent 信息	`GET`	`<API_URL>/assistants/<AGENT_ID>`
创建一个线程	`POST`	`<API_URL>/threads`
运行（等待结果）	`POST`	`<API_URL>/runs/wait`
运行（流式）	`POST`	`<API_URL>/runs/stream`
在线程上运行（等待）	`POST`	`<API_URL>/threads/<THREAD_ID>/runs/wait`
/langsmith/agent-server-api/thread-runs/create-run-stream-output	`POST`	`<API_URL>/threads/<THREAD_ID>/runs/stream`

所有端点都需要以下标头：

Content-Type: application/json
X-Api-Key: 你的个人访问令牌
X-Auth-Scheme: langsmith-api-key

完整的 API 规范参阅 Agent Server API 参考。

导出到代码

Export to code 功能让你把 Fleet agent 下载为一个自包含的 Python 项目并在本地运行。当你想以下情形时很有用：

在你自己的基础设施上运行你的 agent，而不调用 Fleet API
超出 Fleet UI 所支持的边界来扩展或定制 agent（添加自定义工具、中间件或技能）
检查或版本管理完整的 agent 实现
把 LangGraph Studio 用于本地开发和图检视

fleet-deepagents-export 包（GitHub）负责读取导出的配置，并把你的 agent 与 MCP 工具、子 agent 和技能接线。

前提条件

Python 3.11+
uv（推荐）用于依赖管理
一个要导出的 LangSmith Fleet agent

1. 复制脚手架项目

examples/template-agent/ 处的脚手架项目是推荐的起点。克隆仓库并复制脚手架：

bash

git clone https://github.com/langchain-ai/fleet-deepagents-export.git
cp -R fleet-deepagents-export/examples/template-agent my-agent
cd my-agent

2. 从 Fleet 导出你的 agent

在 LangSmith UI 中，打开你的 agent 并把它导出为一个 .zip 文件。

然后把你脚手架项目 fleet/ 目录的内容拖进去：

bash

unzip path/to/my-export.zip -d fleet/

fleet/ 目录包含你 agent 所需的一切：

AGENTS.md — 系统提示
config.json — 模型配置和工作区元数据
tools.json — MCP 服务器连接
subagents/（可选）— 子 agent 定义
skills/（可选）— 技能指令

3. 配置你的环境

复制示例 env 文件并填入所需的值：

bash

cp .env.example .env

三个 LANGSMITH_*_ID 值在 fleet/config.json 的 metadata 下。打开那个文件并把 tenant_id、organization_id 和 ls_user_id 复制到你的 .env：

bash

# Model provider — set the key for whichever provider your agent uses
ANTHROPIC_API_KEY=your-anthropic-api-key

# LangSmith credentials — copy IDs from fleet/config.json → metadata
LANGSMITH_API_KEY=your-langsmith-pat
LANGSMITH_TENANT_ID=your-tenant-id
LANGSMITH_ORGANIZATION_ID=your-organization-id
LANGSMITH_USER_ID=your-user-id       # required if your agent uses OAuth tools

# Built-in MCP tools (Gmail, Calendar, GitHub)
BUILTIN_MCP_URL=https://tools.langchain.com/mcp

4. 安装依赖并运行

bash

make setup    # installs dependencies via uv sync

然后选择如何与你 agent 交互：

bash

make dev    # LangGraph Studio — browser UI for chat and graph inspection
make run    # terminal REPL via cli.py — text-only chat

5. 定制 agent

脚手架把 Fleet 自有的文件与你自有、可自由编辑的文件分开：

文件 / 目录	所有者	目的
`fleet/`	Fleet	把导出内容放这里。重新解压以更新；其他什么都不碰。
`agent.py`	你	图接线。通过替换 `model = components.pop("model")` 那一行来覆盖模型。
`custom_tools.py`	你	添加代码定义的工具；在运行时与 Fleet MCP 工具合并。
`custom_middleware.py`	你	为日志、过滤器、前/后钩子等添加 `AgentMiddleware` 实例。
`custom_skills/`	你	拖入 `<skill-name>/SKILL.md` 文件；叠加在 `fleet/skills/` 之上。
`cli.py`	你	终端 REPL；自由编辑。

这是脚手架中完整的 agent.py：

python

"""Standalone deepagent exported from LangSmith Fleet.

LangGraph Studio / dev server:  make dev
Terminal:                        make run  (see cli.py)

Extension points (edit these, not this file):
- ``custom_tools.py``      — add code-defined tools
- ``custom_middleware.py`` — wrap the agent loop with logging, filters, etc.
- ``custom_skills/``       — drop ``<skill-name>/SKILL.md`` files
"""

from __future__ import annotations

from pathlib import Path
from typing import Any

from dotenv import load_dotenv

load_dotenv()

from custom_middleware import custom_middleware
from custom_tools import custom_tools
from deepagents import create_deep_agent
from fleet_deepagents_export import StaticSkillsLoader, load_agent_components

PROJECT_DIR = Path(__file__).parent
FLEET_DIR = PROJECT_DIR / "fleet"
CUSTOM_SKILLS_DIR = PROJECT_DIR / "custom_skills"

# Read SKILL.md from disk once; middleware injects into state on first turn.
_SKILL_LOADER = StaticSkillsLoader(
    [
        (FLEET_DIR / "skills", "/skills/fleet"),
        (CUSTOM_SKILLS_DIR, "/skills/custom"),
    ]
)

async def graph(runtime: Any):
    """Build and return the agent graph."""
    components = await load_agent_components(FLEET_DIR)
    model = components.pop("model")  # from fleet/config.json; replace to override
    components["tools"] = list(components["tools"]) + list(custom_tools)

    if _SKILL_LOADER.files:
        components["skills"] = _SKILL_LOADER.skill_paths

    return create_deep_agent(
        model=model,
        middleware=[_SKILL_LOADER, *custom_middleware],
        **components,
    ).with_config({"recursion_limit": 1000})

重新导出

当你从 Fleet 导出你 agent 的新版本时，只需清空并重新解压——你的定制不受影响：

bash

rm -rf fleet && unzip path/to/my-new-export.zip -d fleet/

受支持的模型提供商

脚手架随附 langchain-anthropic、langchain-openai 和 langchain-google-genai。对于任何其他提供商（例如 bedrock、fireworks），把匹配的 langchain-<provider> 包添加到 pyproject.toml。

MCP 身份验证

启动时，每个工具的 mcp_server_url 会针对 LangSmith 的 MCP 服务器注册表解析：

内置 LangSmith 工具（Gmail、Calendar、GitHub）— 通过你的 LANGSMITH_API_KEY 身份验证。
静态凭据服务器（auth_type: "headers"）— 凭据来自注册表记录。需要 mcp-servers:invoke 权限。
OAuth 服务器（auth_type: "oauth"）— 从 LangSmith 的 OAuth 代理获取 bearer 令牌。首次运行时，会为尚未授权的任何按用户服务器弹出一个浏览器窗口。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织