LLM Agent标准化互操作协议：Agent Protocol

代理协议是我们尝试规范化用于在生产环境中服务 LLM 代理的框架无关 API。本文档解释了该协议的目的，并阐述了每个端点的必要性。最后，我们列出了未来的一些发展路线。

请参阅完整的 OpenAPI 文档这里[1]，以及 JSON 规范这里[2]。

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

为什么选择代理协议

如何为 LLM 应用程序在生产环境中提供正确的 API？我们认为，这个 API 围绕三个重要概念展开：

• 运行：用于执行代理的 API
• 线程：用于组织代理的多轮执行的 API
• 存储：用于处理长期记忆的 API

让我们深入探讨每个概念，首先是需求，然后展示符合这些需求的协议端点。

运行：原子代理执行

我们需要什么样的 API 来执行一个代理？

• 支持两种启动运行的范式：
  • Fire and forget：即在后台启动一个运行，但不等待其完成
  • 等待回复（阻塞或轮询）：即启动一个运行并等待/流式输出
• 支持代理执行的 CRUD 操作：
  • 列出并获取运行
  • 取消和删除运行
• 灵活的输出消费方式：
  • 获取最终状态
  • 多种流式输出类型，例如逐个令牌、过程步骤等
  • 如果断开连接，能够重新连接到输出流
• 处理边缘情况：
  • 错误应平滑处理，且可根据需要重试
  • 突发流量应排队处理

基础端点：

• `GET /threads/{thread_id}/runs`[4] - 列出运行。
• `POST /threads/{thread_id}/runs`[5] - 创建一个运行。
• `GET /threads/{thread_id}/runs/{run_id}`[6] - 获取一个运行及其状态。
• `POST /threads/{thread_id}/runs/{run_id}/cancel`[7] - 取消运行。如果运行尚未开始，立即取消；如果正在运行，则尽可能尽快取消。
• `DELETE /threads/{thread_id}/runs/{run_id}`[8] - 删除已完成的运行。待处理的运行需要先取消，参见前一个端点。
• `GET /threads/{thread_id}/runs/{run_id}/wait`[9] - 等待运行完成，返回最终输出。如果运行已完成，立即返回其最终输出。
• `GET /threads/{thread_id}/runs/{run_id}/stream`[10] - 加入现有运行的输出流。只有在调用该端点后产生的输出才会被流式传输。

便捷端点：

• `POST /threads/{thread_id}/runs/wait`[11] - 创建运行，并等待最终输出。
• `POST /threads/{thread_id}/runs/stream`[12] - 创建运行，并在产生时流式传输输出。

线程：多轮交互

支持多轮交互需要哪些 API？

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

端点：

• `POST /threads`[13] - 创建线程。
• `POST /threads/search`[14] - 搜索线程。
• `GET /threads/{thread_id}`[15] - 获取线程。
• `GET /threads/{thread_id}/state`[16] - 获取线程的最新状态。
• `POST /threads/{thread_id}/state`[17] - 创建线程状态的新修订版。
• `GET /threads/{thread_id}/history`[18] - 浏览线程状态的历史修订版。修订版由运行创建，或通过上面的端点创建。
• `POST /threads/{thread_id}/copy`[19] - 创建线程的独立副本。
• `DELETE /threads/{thread_id}`[20] - 删除线程。
• `PATCH /threads/{thread_id}`[21] - 更新线程的元数据。

存储：长期记忆

代理的记忆 API 需要提供哪些功能？

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

端点：

• `PUT /store/items`[22] - 创建或更新指定命名空间和键的记忆项。
• `DELETE /store/items`[23] - 删除指定命名空间和键的记忆项。
• `GET /store/items`[24] - 获取指定命名空间和键的记忆项。
• `POST /store/items/search`[25] - 搜索记忆项。
• `POST /store/namespaces`[26] - 列出命名空间。

路线图

• 添加存储端点以对记忆条目进行向量搜索
• 为POST /threads/{thread_id}/runs/{run_id}/stream 添加一个参数，以便在流式传输新事件之前重放自event-id 以来的事件
• 为POST /threads/{thread_id}/runs 添加一个参数，以可选地允许在同一线程上并发运行（当前规格禁止此操作）
• （请提出问题并告知我们还应该添加什么内容！）

关注我，与你一起探索 AI 最前沿的技术洞见！您的评论与分享是我创作的动力。

参考资料

[1]

这里:https://langchain-ai.github.io/agent-protocol/api.html

[2]

这里:https://langchain-ai.github.io/agent-protocol/openapi.json

[3]

LangGraph平台:https://www.langchain.com/pricing-langgraph-platform

[4]

GET /threads/{thread_id}/runs:https://langchain-ai.github.io/agent-protocol/api.html#tag/runs/GET/threads/{thread_id}/runs

[5]

POST /threads/{thread_id}/runs:https://langchain-ai.github.io/agent-protocol/api.html#tag/runs/POST/threads/{thread_id}/runs

[6]

GET /threads/{thread_id}/runs/{run_id}:https://langchain-ai.github.io/agent-protocol/api.html#tag/runs/GET/threads/{thread_id}/runs/{run_id}

[7]

POST /threads/{thread_id}/runs/{run_id}/cancel:https://langchain-ai.github.io/agent-protocol/api.html#tag/runs/POST/threads/{thread_id}/runs/{run_id}/cancel

[8]

DELETE /threads/{thread_id}/runs/{run_id}:https://langchain-ai.github.io/agent-protocol/api.html#tag/runs/DELETE/threads/{thread_id}/runs/{run_id}

[9]

GET /threads/{thread_id}/runs/{run_id}/wait:https://langchain-ai.github.io/agent-protocol/api.html#tag/runs/GET/threads/{thread_id}/runs/{run_id}/wait

[10]

GET /threads/{thread_id}/runs/{run_id}/stream:https://langchain-ai.github.io/agent-protocol/api.html#tag/runs/GET/threads/{thread_id}/runs/{run_id}/stream

[11]

POST /threads/{thread_id}/runs/wait:https://langchain-ai.github.io/agent-protocol/api.html#tag/runs/POST/threads/{thread_id}/runs/wait

[12]

POST /threads/{thread_id}/runs/stream:https://langchain-ai.github.io/agent-protocol/api.html#tag/runs/POST/threads/{thread_id}/runs/stream

[13]

POST /threads:https://langchain-ai.github.io/agent-protocol/api.html#tag/threads/POST/threads

[14]

POST /threads/search:https://langchain-ai.github.io/agent-protocol/api.html#tag/threads/POST/threads/search

[15]

GET /threads/{thread_id}:https://langchain-ai.github.io/agent-protocol/api.html#tag/threads/GET/threads/{thread_id}

[16]

GET /threads/{thread_id}/state:https://langchain-ai.github.io/agent-protocol/api.html#tag/threads/GET/threads/{thread_id}/state

[17]

POST /threads/{thread_id}/state:https://langchain-ai.github.io/agent-protocol/api.html#tag/threads/POST/threads/{thread_id}/state

[18]

GET /threads/{thread_id}/history:https://langchain-ai.github.io/agent-protocol/api.html#tag/threads/GET/threads/{thread_id}/history

[19]

POST /threads/{thread_id}/copy:https://langchain-ai.github.io/agent-protocol/api.html#tag/threads/POST/threads/{thread_id}/copy

[20]

DELETE /threads/{thread_id}:https://langchain-ai.github.io/agent-protocol/api.html#tag/threads/DELETE/threads/{thread_id}

[21]

PATCH /threads/{thread_id}:https://langchain-ai.github.io/agent-protocol/api.html#tag/threads/PATCH/threads/{thread_id}

[22]

PUT /store/items:https://langchain-ai.github.io/agent-protocol/api.html#tag/store/PUT/store/items

[23]

DELETE /store/items:https://langchain-ai.github.io/agent-protocol/api.html#tag/store/DELETE/store/items

[24]

GET /store/items:https://langchain-ai.github.io/agent-protocol/api.html#tag/store/GET/store/items

[25]

POST /store/items/search:https://langchain-ai.github.io/agent-protocol/api.html#tag/store/POST/store/items/search

[26]

POST /store/namespaces:https://langchain-ai.github.io/agent-protocol/api.html#tag/store/POST/store/namespaces