Agent 协议

Agent Protocol 是我们尝试将用于在生产环境中服务 LLM 智能体的框架无关 API 进行规范化的努力。本文档解释了该协议的目的，并阐述了规范中每个端点的理由。最后，我们列出了一些未来的路线图项目。

查看完整的 OpenAPI 文档 此处，查看 JSON 规范 此处。

LangGraph 平台 实现了该协议的超集，但我们非常欢迎社区的其他实现。

资源

• Agent 协议 OpenAPI 文档
• Agent 协议 JSON 规范
• Agent 协议 Python 服务器存根 - 一个使用 Pydantic V2 和 FastAPI 的 Python 服务器，由 OpenAPI 规范自动生成
• LangGraph.js API - 此协议的一个开源实现，用于 LangGraph.js 智能体，使用内存存储
• LangGraph 平台 - 一个商业平台，实现了该协议的超集，用于在生产环境中部署任何 LLM 智能体

为什么需要 Agent 协议

什么是适合在生产环境中服务 LLM 应用程序的正确 API？我们相信它围绕 3 个重要概念构建：

• Runs（运行）：执行智能体的 API
• Threads（线程）：组织智能体多轮执行的 API
• Store（存储）：处理长期记忆的 API

让我们深入探讨每一个，首先从需求开始，然后展示满足这些需求的协议端点。

无状态运行：一次性交互

在某些情况下，您可能希望在单个请求中创建线程并运行，并在运行结束后删除该线程。这对于短暂或无状态的交互很有用，在这些交互中您不需要跟踪线程的状态。

• POST /runs/wait - 创建一个临时运行，并等待其最终输出，输出将在响应中返回。
• POST /runs/stream - 创建一个临时运行，并按生产情况流式传输输出。

线程：多轮交互

您需要哪些 API 来启用多轮交互？

• 持久化状态
  • 获取和更新状态
  • 跟踪线程过去状态的历史，建模为状态的追加日志
  • 通过仅存储状态之间的差异来优化存储
• 并发控制
  • 确保同一时间每个线程只有一个运行处于活动状态
  • 可自定义处理并发运行（中断、入队、中断或回滚）
• 线程的 CRUD 端点
  • 按用户或其他元数据列出线程
  • 按状态列出线程（空闲、已中断、出错、完成）
  • 复制或删除线程

端点：

• POST /threads - 创建线程。
• POST /threads/search - 搜索线程。
• GET /threads/{thread_id} - 获取线程。
• GET /threads/{thread_id}/history - 浏览线程状态的历史修订版。修订版由运行创建，或通过下面的 PATCH 端点创建。
• POST /threads/{thread_id}/copy - 创建线程的独立副本。
• DELETE /threads/{thread_id} - 删除线程。
• PATCH /threads/{thread_id} - 更新线程的值或元数据。更新值会在线程历史中创建新的修订版。

智能体：内省

在使用智能体之前，了解它能做什么、接受什么输入、返回什么等有时很有用。这就是内省端点发挥作用的地方。

端点：

• POST /agents/search - 列出所有智能体，可选择性地按元数据或名称过滤。
• GET /agents/{agent_id} - 获取智能体的基本信息，包括其名称、描述、元数据。
• GET /agents/{agent_id}/schemas - 获取智能体的输入、输出、状态和配置模式。所有模式均以 JSON Schema 格式表示。

后台运行：原子化智能体执行

要执行一个智能体，我们需要 API 提供什么功能？

• 支持两种启动运行的范式
  • “发射即忘”（Fire and Forget），即在后台启动运行，但不等待其完成
  • 等待回复（阻塞或轮询），即启动运行并等待/流式传输其输出
• 支持智能体执行的 CRUD (增删改查) 操作
  • 列出和获取运行
  • 取消和删除运行
• 灵活的消费输出方式
  • 获取最终状态
  • 多种类型的流式输出，例如逐 token、中间步骤等
  • 如果断开连接，能够重新连接到输出流
• 处理边界情况
  • 故障应被优雅地处理，如果需要可以重试
  • 突发流量应该被排队

基础端点：

• GET /threads/{thread_id}/runs - 列出线程的运行。
• POST /runs - 创建一个后台运行。
• GET /runs/{run_id} - 获取运行及其状态。
• POST /runs/{run_id}/cancel - 取消运行。如果运行尚未开始，立即取消；如果正在运行，则尽快取消。
• DELETE /runs/{run_id} - 删除已完成的运行。待处理的运行需要先取消，参见上一个端点。
• GET /runs/{run_id}/wait - 等待运行完成，返回最终输出。如果运行已完成，立即返回其最终输出。
• GET /runs/{run_id}/stream - 加入现有运行的输出流。仅调用此端点后产生的输出才会被流式传输。

存储：长期记忆

对于智能体的记忆 API，你需要什么功能？

• 可自定义的记忆范围
  • 针对用户、线程、助手、公司等存储记忆
  • 在同一运行中访问不同范围的记忆
• 灵活的存储
  • 支持简单的文本记忆以及结构化数据
  • 记忆的 CRUD (增删改查) 操作（创建、读取、更新、删除）
• 搜索和检索
  • 通过命名空间和键获取单个记忆
  • 按命名空间、内容过滤，按时间排序等列出记忆

端点：

• PUT /store/items - 在指定的命名空间和键处创建或更新记忆项。
• DELETE /store/items - 在指定的命名空间和键处删除记忆项。
• GET /store/items - 在指定的命名空间和键处获取记忆项。
• POST /store/items/search - 搜索记忆项。
• POST /store/namespaces - 列出命名空间。

消息

消息已成为处理大语言模型 (LLMs) 的核心原语，因此我们在 Agent Protocol 中对消息提供了第一类支持。此外，我们还完全支持为智能体定制输入/输出模式 (schemas)。我们定义了一个消息规范 (Message spec)，它是主要 LLM 提供商（如 OpenAI 和 Anthropic）支持的格式的子集。在所有暴露线程值的端点中，还有一个单独的 messages 字段，智能体可以选择实现。

Agent Protocol 实战

以下是几个使用 Hurl 格式的示例“用户旅程”，每个都展示了针对您的 Agent Protocol 服务（监听在 localhost:8000，无需认证）的常见 API 调用序列。

它们经过组织，以便您可以将每个旅程粘贴到独立的 .hurl 文件中（或合并它们），然后使用"hurl"命令运行。这应该能让您很好地了解该协议在实际中如何使用。

旅程 1：创建线程 → 获取线程 → 创建运行 → 等待输出

此旅程演示了创建线程、启动运行并等待最终输出的典型序列。然后您可以重复最后两步以在同一线程中启动更多运行。这是多轮交互（如聊天机器人对话）最常见的模式。

# 1. Create a brand new thread
POST http://localhost:8000/threads
Content-Type: application/json

{
  "thread_id": "229c1834-bc04-4d90-8fd6-77f6b9ef1462",
  "metadata": {
    "purpose": "support-chat"
  }
}

HTTP/1.1 200
[Asserts]
jsonpath "$.thread_id" == "229c1834-bc04-4d90-8fd6-77f6b9ef1462"


# 2. Retrieve the thread we just created
GET http://localhost:8000/threads/229c1834-bc04-4d90-8fd6-77f6b9ef1462

HTTP/1.1 200
[Asserts]
jsonpath "$.status" == "idle"


# 3. Create a run in the existing thread (background run).
# Capture the run_id for the next step.
POST http://localhost:8000/threads/229c1834-bc04-4d90-8fd6-77f6b9ef1462/runs
Content-Type: application/json

{
  "input": {
    "message": "Hi there, what's the weather?"
  },
  "metadata": {
    "requestType": "weatherQuery"
  }
}

HTTP/1.1 200
[Captures]
run_id: jsonpath "$.run_id"
[Asserts]
jsonpath "$.status" == "pending"


# 4. Wait for final run output
GET http://localhost:8000/threads/229c1834-bc04-4d90-8fd6-77f6b9ef1462/runs/{{run_id}}/wait

HTTP/1.1 200
[Asserts]
# For example, check that the run status is success or error,
# depending on your actual system's response:
jsonpath "$.status" == "success"

您可以将最后一步替换为 GET /threads/{thread_id}/runs/{run_id}/stream 以流式传输产生的输出，或者使用 GET /threads/{thread_id} 进行轮询状态/输出而无需等待。

旅程 2：临时“无状态”运行（创建 + 等待）

此旅程演示了一次性运行，其中您在一次请求中创建线程并运行，并等待最终输出。这对于无状态交互很有用，您希望每次从头开始。良好的用例包括提取或研究智能体。

# Launch a one-shot run with a brand new ephemeral thread,
# and wait for the final output right away.
POST http://localhost:8000/runs/wait
Content-Type: application/json

{
  "input": {
    "prompt": "What's the fastest route to the airport?"
  },
  "metadata": {
    "useCase": "travelPlan"
  },
  "config": {
    "tags": ["ephemeral", "demo"]
  }
}

HTTP/1.1 200

旅程 3：使用存储（添加、检索和删除项）

本旅程演示了如何使用 Store API（存储 API）来添加、检索和删除一项内容。这对于存储长期记忆非常有用，例如用户档案、偏好设置或其他结构化数据，这些数据既可以在智能体内部访问，也可以在智能体外部访问。

# 1. Put (store or update) an item in the store
PUT http://localhost:8000/store/items
Content-Type: application/json

{
  "namespace": ["user_profiles"],
  "key": "profile_jane_doe",
  "value": {
    "displayName": "Jane Doe",
    "role": "customer"
  }
}

HTTP/1.1 204


# 2. Retrieve it by namespace/key
GET http://localhost:8000/store/items?key=profile_jane_doe&namespace=user_profiles

HTTP/1.1 200
[Asserts]
jsonpath "$.value.displayName" == "Jane Doe"
jsonpath "$.value.role" == "customer"


# 3. Delete the item
DELETE http://localhost:8000/store/items
Content-Type: application/json

{
  "namespace": ["user_profiles"],
  "key": "profile_jane_doe"
}

HTTP/1.1 204

路线图

• 为每种流模式添加详细规范（目前这部分留给实现者决定）
• 添加 Store 端点以在内存条目上执行向量搜索
• 为 POST /threads/{thread_id}/runs/{run_id}/stream 添加参数，以便在流式传输新事件之前重放自 event-id 以来的事件
• 向 `POST /threads/{thread_id}/runs `` 添加参数，以选择性地允许在同一线程上进行并发运行（当前规范禁止此操作）
• （提交一个 Issue（问题）并告诉我们这里还应该包含什么！）

Agent Protocol 快速上手指南

Agent Protocol 是一套旨在为生产环境中的 LLM 代理（Agents）提供框架无关 API 的规范。它定义了用于执行代理、管理多轮对话线程以及长期记忆存储的核心接口。本指南将指导您如何部署参考服务器并测试基础 API。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux / macOS / Windows
• Python 版本: 3.10 或更高版本
• 依赖工具: Git, Pip
• 网络建议: 由于涉及 GitHub 仓库克隆及 PyPI 包下载，建议使用国内镜像源加速（如清华源）。

安装步骤

1. 克隆项目仓库

从 GitHub 获取官方代码库。如果连接缓慢，可使用国内镜像地址。

git clone https://github.com/langchain-ai/agent-protocol.git
cd agent-protocol

2. 安装服务端依赖

进入 server/ 目录，该目录包含基于 Pydantic V2 和 FastAPI 自动生成的 Python 服务器存根。

cd server
# 推荐使用国内 PyPI 镜像源安装依赖
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple fastapi uvicorn pydantic

(注：如果目录下存在 requirements.txt，请优先使用 pip install -r requirements.txt)

3. 启动服务

使用 Uvicorn 启动 FastAPI 应用，默认监听端口为 8000。

uvicorn main:app --host 0.0.0.0 --port 8000

(注：具体入口文件名为 main.py，若不同请根据实际目录结构调整)

基本使用

启动服务后，您可以使用支持 HTTP 请求的工具（如 Hurl 或 cURL）来调用协议接口。以下示例展示了创建线程、启动运行并等待输出的标准流程。

示例场景：创建线程 → 获取线程 → 创建运行 → 等待输出

将以下代码保存为 journey1.hurl 文件，并在终端运行 hurl journey1.hurl 进行测试。

# 1. Create a brand new thread
POST http://localhost:8000/threads
Content-Type: application/json

{
  "thread_id": "229c1834-bc04-4d90-8fd6-77f6b9ef1462",
  "metadata": {
    "purpose": "support-chat"
  }
}

HTTP/1.1 200
[Asserts]
jsonpath "$.thread_id" == "229c1834-bc04-4d90-8fd6-77f6b9ef1462"


# 2. Retrieve the thread we just created
GET http://localhost:8000/threads/229c1834-bc04-4d90-8fd6-77f6b9ef1462

HTTP/1.1 200
[Asserts]
jsonpath "$.status" == "idle"


# 3. Create a run in the existing thread (background run).
# Capture the run_id for the next step.
POST http://localhost:8000/threads/229c1834-bc04-4d90-8fd6-77f6b9ef1462/runs
Content-Type: application/json

{
  "input": {
    "message": "Hi there, what's the weather?"
  },
  "metadata": {
    "requestType": "weatherQuery"
  }
}

HTTP/1.1 200
[Captures]
run_id: jsonpath "$.run_id"
[Asserts]
jsonpath "$.status" == "pending"


# 4. Wait for final run output
GET http://localhost:8000/threads/229c1834-bc04-4d90-8fd6-77f6b9ef1462/runs/{{run_id}}/wait

HTTP/1.1 200
[Asserts]
# For example, check that the run status is success or error,
# depending on your actual system's response:
jsonpath "$.status" == "success"

其他常用模式

• 无状态运行 (Stateless): 使用 POST /runs/wait 直接创建临时线程并获取结果。
• 流式输出 (Streaming): 将最后一步替换为 GET /threads/{thread_id}/runs/{run_id}/stream 以实时接收输出。

更多完整的 API 文档与规范，请访问 Agent Protocol OpenAPI Docs。