AgentAPI - 多种编程 Agent 的统一 HTTP 接口

通过 HTTP API 控制 Claude Code、AmazonQ、Opencode、Goose、Aider、Gemini、GitHub Copilot、Sourcegraph Amp、Codex、Auggie 和 Cursor CLI。

你可以使用 AgentAPI：

• 构建统一的编码 agent 聊天界面
• 作为 MCP 服务器的后端，让一个 agent 控制另一个编码 agent
• 创建向 agent 提交 pull request 审查的工具

安装 agentapi

OS=$(uname -s | tr "[:upper:]" "[:lower:]");
ARCH=$(uname -m | sed "s/x86_64/amd64/;s/aarch64/arm64/");
curl -fsSL "https://github.com/coder/agentapi/releases/latest/download/agentapi-${OS}-${ARCH}" -o agentapi && chmod +x agentapi

或者，你可以从发布页面下载最新的 release 二进制文件。

验证安装

agentapi --help

在 macOS 上，如果系统提示无法验证二进制文件，请前往「系统设置」→「隐私和安全」，点击「打开」，然后再次运行命令。

运行 Claude Code 服务器

假设 claude 已安装在你的系统中并在 PATH 中：

agentapi server -- claude

如果你遇到 claude 不在 PATH 中的错误，但可以从 shell 运行它，请尝试 which claude 获取完整路径并使用该路径。

发送消息给 agent

curl -X POST localhost:3284/message \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, agent!", "type": "user"}'

获取对话历史

curl localhost:3284/messages

尝试访问 http://localhost:3284/chat 处的聊天 web 界面。

运行 HTTP 服务器

运行一个 HTTP 服务器，让你控制 agent。如果你想用额外的参数启动 agent，请在 -- 标志后传递完整的 agent 命令。

agentapi server -- claude --allowedTools "Bash(git*) Edit Replace"

你也可以使用 agentapi 运行 Aider 和 Goose agent：

agentapi server -- aider --model sonnet --api-key anthropic=sk-ant-apio3-XXX
agentapi server -- goose

使用 Claude、Codex、Opencode、Copilot、Gemini、Amp 或 CursorCLI 时，始终显式指定 agent 类型（例如：agentapi server --type=codex -- codex），否则消息格式可能会破损。

OpenAPI schema 可在 openapi.json 中获得。

服务器端口与文档

默认情况下，服务器运行在端口 3284。此外，服务器在 http://localhost:3284/openapi.json 处公开相同的 OpenAPI schema，并在 http://localhost:3284/docs 处的文档 UI 中公开可用的端点。

共有 4 个端点：

• GET /messages - 返回与 agent 的对话中所有消息的列表
• POST /message - 向 agent 发送消息。当返回 200 响应时，AgentAPI 已检测到 agent 开始处理消息
• GET /status - 返回 agent 的当前状态，为「stable」或「running」
• GET /events - 来自 agent 的事件的 SSE 流：消息和状态更新

主机名配置

默认情况下，服务器只允许 host 标头设置为 localhost 的请求。如果你想在其他地方托管 AgentAPI，可以使用 AGENTAPI_ALLOWED_HOSTS 环境变量或 --allowed-hosts 标志来更改。主机必须仅为主机名（不包括端口）；服务器在授权时忽略传入请求的端口部分。

要允许来自任何主机的请求，请使用 * 作为允许的主机。

agentapi server --allowed-hosts '*' -- claude

要允许特定主机，请使用：

agentapi server --allowed-hosts 'example.com' -- claude

要指定多个主机，在使用 --allowed-hosts 标志时使用逗号分隔的列表，或在使用 AGENTAPI_ALLOWED_HOSTS 环境变量时使用空格分隔的列表。

agentapi server --allowed-hosts 'example.com,example.org' -- claude
# or
AGENTAPI_ALLOWED_HOSTS='example.com example.org' agentapi server -- claude

CORS 配置

默认情况下，服务器允许来自 http://localhost:3284、http://localhost:3000 和 http://localhost:3001 的 CORS 请求。如果你想更改哪些来源可以向 AgentAPI 发起跨来源请求，可以使用 AGENTAPI_ALLOWED_ORIGINS 环境变量或 --allowed-origins 标志来更改。

要允许来自任何来源的请求，请使用 * 作为允许的来源：

agentapi server --allowed-origins '*' -- claude

要允许特定的来源，请使用：

agentapi server --allowed-origins 'https://example.com' -- claude

要指定多个来源，在使用 --allowed-origins 标志时使用逗号分隔的列表，或在使用 AGENTAPI_ALLOWED_ORIGINS 环境变量时使用空格分隔的列表。来源必须包括协议（http:// 或 https://）并支持通配符（例如 https://*.example.com）：

agentapi server --allowed-origins 'https://example.com,http://localhost:3000' -- claude
# or
AGENTAPI_ALLOWED_ORIGINS='https://example.com http://localhost:3000' agentapi server -- claude

连接到运行中的 agent

agentapi attach --url localhost:3284

按 Ctrl+C 从会话中分离。

终端模拟与消息处理

AgentAPI 运行内存中的终端模拟器。它将 API 调用转换为适当的终端键击，并将 agent 的输出解析为单个消息。

将终端输出分割为消息

有 2 种消息类型：

• 用户消息：用户发送给 agent 的消息
• Agent 消息：agent 发送给用户的消息

要从终端输出中解析单个消息，我们采取以下步骤：

1. 发送任何用户消息之前的初始终端输出被视为 agent 的第一条消息。
2. 当用户通过 API 发送消息时，在发送任何键击之前拍摄终端的快照。
3. 然后将用户消息提交给 agent。从此刻起，每当终端输出改变时，就会拍摄新的快照。它与初始快照进行比较，初始内容下方出现的任何新文本都被视为 agent 的下一条消息。
4. 如果在发送新用户消息之前终端输出再次改变，agent 消息就会更新。

这让我们能够将终端输出分割为一系列消息。

从 agent 消息中删除 TUI 元素

每条 agent 消息都包含一些对最终用户不实用的额外部分：

• 消息开头的用户输入。编码 agent 通常会将输入回显给用户，使其在终端中可见。
• 消息末尾的输入框。这是用户通常输入的地方。

AgentAPI 会自动删除这些。

• 对于用户输入，我们删除包含用户最后一条消息中的文本的行。
• 对于输入框，我们在消息末尾查找包含常见 TUI 元素（如 > 或 --------）的行。

当 Claude Code、Goose、Aider 或 Codex 更新其 TUI 时会发生什么？

将终端输出分割为一系列消息应该仍然有效，因为它不依赖于 TUI 结构。用于删除额外部分的逻辑可能需要更新以考虑新元素。AgentAPI 仍然可用，但一些额外的 TUI 元素可能会在 agent 消息中变得可见。

未来规划

根据反馈，我们正在考虑以下功能：

• 支持 MCP 协议
• 支持 Agent2Agent 协议

在短期内，AgentAPI 解决了如何以编程方式控制编码 agent 的问题。随着时间的推移，我们希望看到主要的 agent 发布适当的 SDK。有人可能会想知道到那时 AgentAPI 是否仍然需要。我们认为这取决于 agent 供应商是否决定标准化为公共 API，还是各自坚持专有格式。

在前一种情况下，我们将弃用 AgentAPI，转而使用官方 SDK。在后一种情况下，我们的目标是使 AgentAPI 成为控制任何编码 agent 的通用适配器，以便使用 AgentAPI 的开发者可以在不改变代码的情况下在 agent 之间切换。