在代码中使用 Fleet agents

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

从代码调用：通过 LangGraph SDK 或 REST API 远程调用 agent，无需下载任何内容。
导出到代码：下载 agent 的配置，并使用 fleet-deepagents-export 包，将其作为独立的 Python 项目在本地运行。

从代码调用

你可以在应用程序中使用 LangGraph SDK 或 REST API 调用 LangSmith Fleet agents。Fleet agents 运行在 Agent Server 上，因此你可以使用与其他 LangSmith 部署相同的 API 方法。 REST API 支持从任何支持 HTTP 请求的语言或平台调用 agent。

前置条件

拥有 LangSmith 账号和一个 Fleet agent
用于身份验证的 Personal Access Token (PAT)
（仅 SDK）已安装 LangGraph SDK：

pip install langgraph-sdk python-dotenv

yarn add @langchain/langgraph-sdk

身份验证

要验证 Fleet 部署中 agent 的身份，请在实例化 LangGraph SDK 客户端时，将 LangSmith Personal Access Token (PAT) 传递给 api_key 参数，或通过 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_id 和 api_url 替换为 agent 代码片段中的值。在项目根目录中创建 .env 文件，并填入你的 Personal Access Token：

.env

LANGGRAPH_API_KEY=your-personal-access-token

2. 获取 agent 配置

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

Python
TypeScript
cURL

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))

import "dotenv/config";
import { Client } from "@langchain/langgraph-sdk";

const agentId = "your-agent-id";

const apiKey = process.env.LANGGRAPH_API_KEY;
const apiUrl = "<AGENT-BUILDER-URL>.us.langgraph.app";

const client = new Client({
  apiUrl,
  apiKey,
  defaultHeaders: {
    "X-Auth-Scheme": "langsmith-api-key",
  },
});

async function main(agentId: string) {
  const agent = await client.assistants.get(agentId);
  console.log(agent);
}

main(agentId).catch(console.error);

curl --request GET \
    --url "<AGENT-BUILDER-URL>.us.langgraph.app/assistants/your-agent-id" \
    --header 'Content-Type: application/json' \
    --header 'X-Api-Key: your-personal-access-token' \
    --header 'X-Auth-Scheme: langsmith-api-key'

使用与你的 LangSmith 账号关联的 Personal Access Token (PAT)。将 X-Auth-Scheme 标头设置为 langsmith-api-key 以进行身份验证。

3. 调用 agent

下面的示例展示了如何向 agent 发送消息并接收响应。你可以使用无状态运行（无线程、无对话历史），也可以使用有状态运行（通过线程在多轮交互中保留对话历史）。

无状态运行

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

Python
TypeScript
cURL

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": "你能帮我做什么？"}
        ]
    },
)
print(result)

import "dotenv/config";
import { Client } from "@langchain/langgraph-sdk";

const agentId = "your-agent-id";

const apiKey = process.env.LANGGRAPH_API_KEY;
const apiUrl = "https://<AGENT-BUILDER-URL>.us.langgraph.app";

const client = new Client({
  apiUrl,
  apiKey,
  defaultHeaders: {
    "X-Auth-Scheme": "langsmith-api-key",
  },
});

const result = await client.runs.wait(
  null,
  agentId,
  {
    input: {
      messages: [
        { role: "user", content: "你能帮我做什么？" }
      ]
    }
  }
);
console.log(result);

curl --request POST \
    --url "<AGENT-BUILDER-URL>.us.langgraph.app/runs/wait" \
    --header 'Content-Type: application/json' \
    --header 'X-Api-Key: your-personal-access-token' \
    --header 'X-Auth-Scheme: langsmith-api-key' \
    --data '{
        "assistant_id": "your-agent-id",
        "input": {
            "messages": [
                {
                    "role": "user",
                    "content": "What can you help me with?"
                }
            ]
        }
    }'

无状态流式运行

如果希望在响应生成时就将其流式传输，而不是等待完整结果，请使用流式端点：

Python
TypeScript
cURL

async for chunk in client.runs.stream(
    None,
    agent_id,
    input={
        "messages": [
            {"role": "user", "content": "你能帮我做什么？"}
        ]
    },
    stream_mode="updates",
):
    if chunk.data and "run_id" not in chunk.data:
        print(chunk.data)

const streamResponse = client.runs.stream(
  null,
  agentId,
  {
    input: {
      messages: [
        { role: "user", content: "你能帮我做什么？" }
      ]
    },
    streamMode: "updates"
  }
);
for await (const chunk of streamResponse) {
  if (chunk.data && !("run_id" in chunk.data)) {
    console.log(chunk.data);
  }
}

curl --request POST \
    --url "<AGENT-BUILDER-URL>.us.langgraph.app/runs/stream" \
    --header 'Content-Type: application/json' \
    --header 'X-Api-Key: your-personal-access-token' \
    --header 'X-Auth-Scheme: langsmith-api-key' \
    --data '{
        "assistant_id": "your-agent-id",
        "input": {
            "messages": [
                {
                    "role": "user",
                    "content": "What can you help me with?"
                }
            ]
        },
        "stream_mode": [
            "updates"
        ]
    }'

使用线程进行有状态运行

要在多次交互中保留对话历史，请先创建线程，然后在该线程上运行 agent。同一线程上的后续运行都可以访问完整的消息历史：

Python
TypeScript
cURL

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": "你好，我叫 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": "我叫什么名字？"}
        ]
    },
    stream_mode="updates",
):
    if chunk.data and "run_id" not in chunk.data:
        print(chunk.data)

import "dotenv/config";
import { Client } from "@langchain/langgraph-sdk";

const agentId = "your-agent-id";

const apiKey = process.env.LANGGRAPH_API_KEY;
const apiUrl = "<AGENT-BUILDER-URL>.us.langgraph.app";

const client = new Client({
  apiUrl,
  apiKey,
  defaultHeaders: {
    "X-Auth-Scheme": "langsmith-api-key",
  },
});

const thread = await client.threads.create();

let streamResponse = client.runs.stream(
  thread["thread_id"],
  agentId,
  {
    input: {
      messages: [
        { role: "user", content: "你好，我叫 Alice。" }
      ]
    },
    streamMode: "updates"
  }
);
for await (const chunk of streamResponse) {
  if (chunk.data && !("run_id" in chunk.data)) {
    console.log(chunk.data);
  }
}

streamResponse = client.runs.stream(
  thread["thread_id"],
  agentId,
  {
    input: {
      messages: [
        { role: "user", content: "我叫什么名字？" }
      ]
    },
    streamMode: "updates"
  }
);
for await (const chunk of streamResponse) {
  if (chunk.data && !("run_id" in chunk.data)) {
    console.log(chunk.data);
  }
}

首先，创建一个线程：

curl --request POST \
    --url "<AGENT-BUILDER-URL>.us.langgraph.app/threads" \
    --header 'Content-Type: application/json' \
    --header 'X-Api-Key: your-personal-access-token' \
    --header 'X-Auth-Scheme: langsmith-api-key' \
    --data '{}'

使用响应中的 thread_id 在线程上发送消息：

curl --request POST \
    --url "<AGENT-BUILDER-URL>.us.langgraph.app/threads/<THREAD_ID>/runs/stream" \
    --header 'Content-Type: application/json' \
    --header 'X-Api-Key: your-personal-access-token' \
    --header 'X-Auth-Scheme: langsmith-api-key' \
    --data '{
        "assistant_id": "your-agent-id",
        "input": {
            "messages": [
                {
                    "role": "user",
                    "content": "Hi, my name is Alice."
                }
            ]
        },
        "stream_mode": [
            "updates"
        ]
    }'

在同一线程上发送后续消息：

curl --request POST \
    --url "<AGENT-BUILDER-URL>.us.langgraph.app/threads/<THREAD_ID>/runs/stream" \
    --header 'Content-Type: application/json' \
    --header 'X-Api-Key: your-personal-access-token' \
    --header 'X-Auth-Scheme: langsmith-api-key' \
    --data '{
        "assistant_id": "your-agent-id",
        "input": {
            "messages": [
                {
                    "role": "user",
                    "content": "What is my name?"
                }
            ]
        },
        "stream_mode": [
            "updates"
        ]
    }'

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: 你的 Personal Access Token
X-Auth-Scheme: langsmith-api-key

如需查看完整的 API 规范，请参阅 Agent Server API 参考。

导出到代码

导出到代码功能可以将 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/ 中的入门项目开始。克隆代码仓库并复制入门项目：

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-export-code

然后将内容放入入门项目的 fleet/ 目录中：

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

fleet/ 目录包含 agent 所需的全部内容：

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

3. 配置环境

复制示例环境文件，并填入必需的值：

cp .env.example .env

这三个 LANGSMITH_*_ID 值位于 fleet/config.json 的 metadata 下。打开该文件，将 tenant_id、organization_id 和 ls_user_id 复制到 .env 中：

.env

# 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. 安装依赖并运行

make setup    # installs dependencies via uv sync

然后选择与 agent 交互的方式：

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：

"""从 LangSmith Fleet 导出的独立 deepagent。

LangGraph Studio / 开发服务器：  make dev
终端：                        make run  （参见 cli.py）

扩展点（编辑这些文件，而不是本文件）：
- ``custom_tools.py``      — 添加代码定义的工具
- ``custom_middleware.py`` — 使用日志记录、过滤器等功能包装 agent 循环
- ``custom_skills/``       — 放入 ``<skill-name>/SKILL.md`` 文件
"""

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"

# 从磁盘读取一次 SKILL.md；中间件会在第一轮交互时将其注入状态。
_SKILL_LOADER = StaticSkillsLoader(
    [
        (FLEET_DIR / "skills", "/skills/fleet"),
        (CUSTOM_SKILLS_DIR, "/skills/custom"),
    ]
)


async def graph(runtime: Any):
    """构建并返回 agent 图。"""
    components = await load_agent_components(FLEET_DIR)
    model = components.pop("model")  # ��自 fleet/config.json；替换此处即可覆盖模型
    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 的新版本时，只需清空目录并重新解压即可——你的自定义内容不会受到影响：

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 broker 获取 bearer token。对于尚未完成授权的按用户服务器，首次运行时会打开浏览器窗口。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Get started

Configure

Tools and automation

Advanced

Additional resources

从代码调用

前置条件

身份验证

1. 获取 agent ID 和 URL

2. 获取 agent 配置

3. 调用 agent

无状态运行

无状态流式运行

使用线程进行有状态运行

REST API 参考

导出到代码

前置条件

1. 复制入门项目

2. 从 Fleet 导出 agent

3. 配置环境

4. 安装依赖并运行

5. 自定义 agent

重新导出

支持的模型提供商

MCP 身份验证

​从代码调用

​前置条件

​身份验证

​1. 获取 agent ID 和 URL

​2. 获取 agent 配置

​3. 调用 agent

​无状态运行

​无状态流式运行

​使用线程进行有状态运行

​REST API 参考

​导出到代码

​前置条件

​1. 复制入门项目

​2. 从 Fleet 导出 agent

​3. 配置环境

​4. 安装依赖并运行

​5. 自定义 agent

​重新导出

​支持的模型提供商

​MCP 身份验证

从代码调用

前置条件

身份验证

1. 获取 agent ID 和 URL

2. 获取 agent 配置

3. 调用 agent

无状态运行

无状态流式运行

使用线程进行有状态运行

REST API 参考

导出到代码

前置条件

1. 复制入门项目

2. 从 Fleet 导出 agent

3. 配置环境

4. 安装依赖并运行

5. 自定义 agent

重新导出

支持的模型提供商

MCP 身份验证