跳到主要内容

程序化集成

AigenLabs 提供三种协议，供外部程序驱动 agent——IDE 插件、自定义 UI、CI 流水线、嵌入式子 agent。根据你的传输方式和消费端选择合适的协议。

协议传输方式适用场景定义位置
ACPJSON-RPC over stdio已支持 Agent Client Protocol 的 IDE 客户端（VS Code、Zed、JetBrains）acp_adapter/
TUI gatewayJSON-RPC over stdio（或 WebSocket）需要精细控制会话、slash 命令、审批及流式事件的自定义宿主tui_gateway/server.py
API serverHTTP + Server-Sent Events兼容 OpenAI 的前端（Open WebUI、LobeChat、LibreChat……）及语言无关的 Web 客户端gateway/platforms/api_server.py

三种协议均驱动同一个 AIAgent 核心，区别仅在于线路格式和所暴露的功能集。

ACP（Agent Client Protocol）​

aigenlabs acp 启动一个基于 stdio 的 JSON-RPC 服务器，使用 ACP 协议。已在 VS Code（Zed Industries 的 ACP 扩展）、Zed 以及所有安装了 ACP 插件的 JetBrains IDE 中投入生产使用。

暴露的能力：会话创建、prompt（提示词）提交、流式 agent 消息块、工具调用事件、权限请求、会话 fork、取消及身份验证。工具输出会被渲染为 IDE 可理解的 ACP Diff/ToolCall 内容块。

完整生命周期、事件桥接及审批流程：ACP 内部机制。

aigenlabs acp                  # 在 stdio 上提供 ACP 服务
aigenlabs acp --bootstrap      # 打印适用于支持 ACP 的 IDE 的安装代码片段

TUI Gateway JSON-RPC​

tui_gateway/server.py 是 Ink TUI（aigenlabs --tui）和嵌入式仪表板 PTY 桥接所使用的协议。任何外部宿主均可通过 stdio（或经由 tui_gateway/ws.py 的 WebSocket）使用相同协议。

方法目录（精选）​

prompt.submit           prompt.background       session.steer
session.create          session.list            session.interrupt
session.history         session.compress        session.branch
session.title           session.usage           session.status
clarify.respond         sudo.respond            secret.respond
approval.respond        config.set / config.get commands.catalog
command.resolve         command.dispatch        cli.exec
reload.mcp              reload.env              process.stop
delegation.status       subagent.interrupt      spawn_tree.save / list / load
terminal.resize         clipboard.paste         image.attach

流式返回的事件​

message.delta、message.complete、tool.start、tool.progress、tool.complete、approval.request、clarify.request、sudo.request、secret.request、gateway.ready，以及会话生命周期和错误事件。

Pi 风格 RPC 映射​

Pi-mono RPC 规范（issue #360）中的每条命令均有对应的 TUI gateway 等价项：

Pi 命令AigenLabs 等价项
promptprompt.submit（或 ACP session/prompt）
steersession.steer
follow_up在当前轮次结束后排队的 prompt.submit
abortsession.interrupt
set_model通过 command.dispatch 执行 /model <provider:model>（会话中途生效，持久化）
compactsession.compress
get_statesession.status
get_messagessession.history
switch_sessionsession.resume
forksession.branch
ui_request / ui_responseclarify.respond / sudo.respond / secret.respond / approval.respond

兼容 OpenAI 的 API Server​

gateway/platforms/api_server.py 通过 HTTP 暴露 AigenLabs，供任何已支持 OpenAI 格式的客户端使用。适用于需要 Web 前端、curl 驱动的 CI 运行器或非 Python 消费端的场景。

端点：

POST /v1/chat/completions        OpenAI Chat Completions（通过 SSE 流式传输）
POST /v1/responses               OpenAI Responses API（有状态）
POST /v1/runs                    启动一次运行，返回 run_id（202）
GET  /v1/runs/{id}               运行状态
GET  /v1/runs/{id}/events        生命周期事件的 SSE 流
POST /v1/runs/{id}/approval      解决待处理的审批
POST /v1/runs/{id}/stop          中断运行
GET  /v1/capabilities            机器可读的功能标志
GET  /v1/models                  列出 aigenlabs-agent
GET  /health, /health/detailed

配置、请求头（X-AigenLabs-Session-Id、X-AigenLabs-Session-Key）及前端接入：API Server。

该选哪个？​

  • 正在编写 IDE 插件，且 IDE 已支持 ACP → 选 ACP。IDE 侧无需任何协议工作。
  • 正在编写自定义桌面 / Web / TUI 宿主，且需要 AigenLabs 的全部功能（slash 命令、审批、clarify、多 agent、会话分支）→ 选 TUI gateway JSON-RPC。
  • 需要任意兼容 OpenAI 的前端、语言无关的 HTTP 客户端或 curl 驱动的自动化 → 选 API server。
  • 需要在 Python 进程内嵌入，不想启动子进程 → 直接导入 run_agent.AIAgent。参见 Agent Loop。

模型热切换​

会话中途切换模型在所有接入方式上均可用——底层均为 /model slash 命令。

  • CLI / TUI： /model claude-sonnet-4 或 /model openrouter:anthropic/claude-sonnet-4.6
  • TUI gateway RPC： 使用 {"command": "/model claude-sonnet-4"} 调用 command.dispatch
  • ACP： IDE 将 slash 命令作为 prompt 发送，agent 负责分发
  • API server： 在请求体中包含 model 字段，或设置 X-AigenLabs-Model

内置 provider 感知解析（相同的模型名称会根据当前 provider 自动选择正确格式）。参见 aigenlabs_cli/model_switch.py。

关于 --mode rpc 的说明​

AigenLabs 没有 --mode rpc 标志。上述三种协议已覆盖所有使用场景——ACP 用于 IDE 协议客户端，TUI gateway 用于 stdio JSON-RPC 宿主，API server 用于 HTTP。如果你发现上述协议均无法满足的真实需求，请提交 issue 并说明你正在构建的具体消费端。