从代码调用代理 - Docs by LangChain

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

前提条件

一个拥有 Fleet 代理的 LangSmith 账户
用于身份验证的个人访问令牌 (PAT)
（仅限 SDK）已安装 LangGraph SDK：

pip install langgraph-sdk python-dotenv

身份验证

要向您的代理 Fleet 部署进行身份验证，请在实例化 LangGraph SDK 客户端时，将 LangSmith 个人访问令牌 (PAT) 提供给 api_key 参数，或通过 X-API-Key 请求头提供。如果使用 X-API-Key，您还必须将 X-Auth-Scheme 请求头设置为 langsmith-api-key。如果您传递的 PAT 未与代理所有者关联，您的请求将被拒绝并返回 404 Not Found 错误。如果您尝试调用的代理是一个，而您不是所有者，您可以执行与在 UI 中相同的所有操作（只读）。

1. 获取代理 ID 和 URL

要获取您的代理的 agent_id 和 api_url：

在 LangSmith UI 中，导航到您的代理收件箱。
在代理名称旁边，点击 编辑代理 图标。
点击右上角的设置图标。
点击 查看代码片段 以查看为您代理预填充的值。

复制下面的代码，并将 agent_id 和 api_url 替换为您的代理代码片段中的值。在项目根目录创建一个 .env 文件，其中包含您的个人访问令牌：

.env

LANGGRAPH_API_KEY=your-personal-access-token

2. 获取代理配置

通过获取代理配置来验证您的连接：

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 账户关联的个人访问令牌 (PAT)。将 X-Auth-Scheme 请求头设置为 langsmith-api-key 进行身份验证。如果您实现了自定义身份验证，请在请求头中传递用户的令牌，以便代理可以使用用户范围的工具。请参阅添加自定义身份验证。

3. 调用代理

以下示例展示了如何向您的代理发送消息并接收响应。您可以使用 无状态 运行（无线程，无对话历史记录）或 有状态 运行（使用线程在多个轮次间维护对话历史记录）。

无状态运行

无状态运行发送单个请求并返回完整响应。不保留对话历史记录。这是调用代理最简单的方式：

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": "What can you help me with?"}
        ]
    },
)
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 = "<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: "What can you help me with?" }
      ]
    }
  }
);
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": "What can you help me with?"}
        ]
    },
    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: "What can you help me with?" }
      ]
    },
    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"
        ]
    }'

使用线程的有状态运行

要在多次交互间维护对话历史记录，请先创建一个线程，然后在该线程上运行您的代理。在同一线程上的每次后续运行都可以访问完整的消息历史记录：

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

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: "Hi, my name is 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: "What is my name?" }
      ]
    },
    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> 替换为您的代理部署 URL。

操作	方法	端点
获取代理信息	`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 参考。

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​前提条件

​身份验证

​1. 获取代理 ID 和 URL

​2. 获取代理配置

​3. 调用代理

​无状态运行

​无状态流式运行

​使用线程的有状态运行

​REST API 参考

前提条件

身份验证

1. 获取代理 ID 和 URL

2. 获取代理配置

3. 调用代理

无状态运行

无状态流式运行

使用线程的有状态运行

REST API 参考