完整指南：Atomic Agent API 参考，OpenAI 兼容 HTTP 接口与 Tauri Sidecar 嵌入详解

完整指南：Atomic Agent API 参考，OpenAI 兼容 HTTP 接口与 Tauri Sidecar 嵌入详解

【免费下载链接】atomic-agentAtomic Agent is a local-first AI agent. Runs open-weight models on your own machine via llama.cpp.项目地址: https://gitcode.com/gh_mirrors/at/atomic-agent

Atomic Agent 是一款本地优先（local-first）的 AI Agent，它在你自己的机器上通过 llama.cpp 运行开源权重模型。除了命令行和 TUI 交互外，它还提供两种官方嵌入方式：一套OpenAI 兼容的 HTTP API（可直接用现成的 OpenAI SDK 调用），以及一个面向桌面应用的Tauri Sidecar 通道（基于 stdio 的 NDJSON 协议）。本文带你从零启动服务、摸清每个接口，再到把它嵌进自己的应用里。

🧭 两种集成方式怎么选

先花 30 秒搞清楚架构，能帮你少走弯路：

• HTTP 服务（serve模式）：启动一个本地 HTTP 服务器，POST /v1/chat/completions完全兼容 OpenAI 协议。适合 Web 后端、脚本、CI、以及其他已经对接 OpenAI 的服务。
• Tauri Sidecar：Agent 以子进程方式运行，通过 stdin/stdout 用换行分隔的 JSON（NDJSON）通信。适合 Tauri、Electron 等桌面应用，无需开放端口、无需管理鉴权。

下面的演示图展示了 Atomic Agent 在实际运行中驱动工具、执行多步任务的样子（终端动图）：

一句话建议：要"网络可达、多客户端共享"选 HTTP；要"单进程内嵌、UI 实时渲染"选 Sidecar。

🚀 一键启动：atomic-agent serve 快速上手

安装后（macOS / Linux 一行安装脚本即可，仓库根目录的 scripts/install.sh 也包含完整流程），用serve命令把 Agent 变成 HTTP 服务：

atomic-agent serve \ --host 127.0.0.1 \ --port 8787 \ --cwd /path/to/work \ --api-key "$ATOMIC_AGENT_API_KEY"

几个新手必须知道的行为细节（都来自 README.md 的官方说明）：

1. 服务会随启动它的父进程退出而结束——崩溃的桌面应用或关闭的终端不会留下占用端口的僵尸服务。
2. 想常驻后台？加--no-parent-exit（或设置ATOMIC_AGENT_SERVE_NO_PARENT_EXIT=1），这是官方支持的守护化方式，nohup和& disown都不行。
3. 孤儿清理：每次启动都会在状态目录serve/下登记自己并清理历史遗留进程；手动执行atomic-agent serve --reap也可触发扫描。
4. 配置好 Token 后所有业务接口都走 Bearer 鉴权；/health和/v1/models例外，免鉴权——因为 OpenAI SDK 会在发正式请求前先探测这两个地址。

📡 核心 OpenAI 兼容端点

POST /v1/chat/completions：一个请求 = 一个完整回合

这是最重要的接口。一次请求对应 Agent 的一整个宏回合（macro-turn）：用户消息 → 0..N 步工具调用 → 最终回复。你不需要为每个工具步骤单独发请求，SDK 只管发一句话、收一条回复。

请求体遵循 OpenAI 格式（model/messages/stream），还支持一个可选的session_id字段复用会话。响应头里藏着三个 Atomic Agent 专属信息（定义见 src/http/openai-chat-completions.ts）：

响应头	含义
X-Atomic-Session-Id	本回合所属会话 ID，下次请求带上即可延续上下文
X-Atomic-Completion-Id	回合唯一 ID，可用于中途取消
X-Atomic-Extensions	请求头开关；开启后 SSE 流会额外推送tool_progress、session_id等扩展事件

💡 兼容性细节：默认情况下，流式响应的每一帧都是 OpenAIchat.completion.chunk协议的严格子集，Vercel AI SDK 这类带严格 schema 校验的客户端不会报错；只有显式开启扩展头，才会看到 Agent 专属的富事件流。

GET /v1/models 与 GET /health

• /v1/models：列出当前可用的模型，OpenAI SDK 探测端点连通性时会调用它；
• /health：健康检查，供编排系统做存活判断。

POST /v1/chat/completions/{completion_id}/cancel

用X-Atomic-Completion-Id拿到回合 ID 后，可以主动取消一个正在执行的多步回合，防止长任务跑偏。

🗂 Atomic 专属 /api/* 路由一览

OpenAI 协议只覆盖了"对话"这一件事。Agent 的会话管理、审批流、任务队列等能力，则由一套独立的/api/*路由暴露。完整的路由注册表就在 src/http/route-table.ts 里，一张表看全：

路由	方法	用途
/api/capabilities	GET	查询服务端支持的能力清单
/api/config	GET / PATCH	读取 / 局部修改配置
/api/sessions·/api/sessions/{id}	GET / DELETE	列出、查看、删除会话
/api/sessions/{id}/steer	POST / GET / DELETE	向运行中的回合"中途插话"，以及查看未送达的插话
/api/approval/resolve	POST	处理危险操作的人工审批请求
/api/events	GET	审批等实时事件流（SSE）
/api/tasks·/api/tasks/{id}/run·/api/tasks/drain	增删查 / 执行 / 批量出队	任务队列管理
/api/skills·/api/skills/{name}·/api/skills/install·/api/skills/uninstall	GET / POST	技能（Skills）安装与查看
/api/mcp/servers/{name}/restart·enable·disable	POST	管理外部 MCP 工具服务器
/api/webhooks/{name}	POST	外部系统触发 Agent 任务

路由匹配规则实现于 src/http/http-server.ts：路径模板中{name}形式的段会被捕获为参数（如/api/skills/{name}），查询串可直接从原始请求中读取。

对新手最实用的两条链路：

• 审批闭环：Agent 要执行危险命令（写文件、跑 shell 等）时会发出approval_request，你的后端在/api/events上监听，再调/api/approval/resolve批准或拒绝——这是把 Agent 安全地暴露给前端的正确姿势。
• Webhook 触发：外部系统（比如 CI）POST 到/api/webhooks/{name}即可让 Agent 开工，实现"事件驱动的自动化"。

🖥 Tauri Sidecar 嵌入：桌面应用的内嵌指南

如果你做的是桌面应用（Tauri / Electron），Sidecar 模式更优雅：启动一个atomic-agent子进程，所有通信走 stdin/stdout，零端口、零鉴权配置。

协议本质：换行分隔的 JSON 帧

协议实现非常薄：每帧一个 JSON 对象、以\n结尾。宿主（你的应用）发request，Sidecar 回event和response，三者的类型定义都集中在 src/sidecar/sidecar-events.ts，TypeScript 项目可以直接 import 同一份类型。帧结构的组装逻辑在 src/sidecar/stdio-protocol.ts。

宿主 → Sidecar 的请求类型（HostRequestType）：

start_session·send_message·steer_message·run_step·cancel·approval_response·get_session·skill_install/skill_uninstall/skill_list·shutdown·ping

Sidecar → 宿主的事件类型（SidecarEventType）涵盖完整生命周期：

turn_started/turn_finished·step_started/step_finished·tool_call_started/tool_call_result·assistant_delta/assistant_reply/reasoning_delta·approval_request·llm_request/llm_response/llm_unavailable·session_completed/session_failed·log/metric/trace·pong

一个最小对话示例

{"kind":"request","id":"r-1","type":"start_session","payload":{"workingDir":"/home/me"}} {"kind":"request","id":"r-2","type":"send_message","payload":{"sessionId":"s-1","text":"Check the inbox and summarize urgent mail."}}

Sidecar 会边执行边推回事件：

{"kind":"event","id":"e-1","type":"turn_started","correlationId":"r-2","payload":{"sessionId":"s-1","turnIndex":0}} {"kind":"event","id":"e-2","type":"tool_call_result","correlationId":"r-2","payload":{"sessionId":"s-1","stepIndex":0,"tool":"browser.read_aria","status":"ok","summary":"url: https://mail.google.com/ ..."}} {"kind":"event","id":"e-3","type":"assistant_reply","correlationId":"r-2","payload":{"sessionId":"s-1","text":"You have 3 urgent threads."}}

注意correlationId字段——它把事件串回你发出的那条请求，UI 层据此把tool_call_result渲染进对应的消息气泡。

嵌入时值得知道的三个设计点

1. 每个 Sidecar 进程只托管一个活跃会话：start_session会建立或替换当前会话，逻辑见 src/sidecar/main.ts。多窗口应用可以起多个子进程，互不干扰。
2. 中途转向（steer）：steer_message会把消息折叠进正在运行的回合，而不是排队等下一轮。如果会话处于空闲，响应里的steered: false表示转向没接住，宿主应回退到send_message。
3. 对端消失的优雅处理：桌面应用突然退出时，管道会报 EPIPE；Sidecar 内部已捕获这种情况并转为"停止输出"，不会因宿主先走而崩溃——这个健壮性正是它敢被桌面应用直接 spawn 的原因。

📊 为什么敢用它接生产流量

本地模型 + Agent 循环的可靠性，官方在公开基准上做过对比：GAIA Level 1 验证集（53 个任务）中，Atomic Agent 使用本地qwen-3.6-35b-a3b跑出了69.8%的准确率，且平均每任务耗时显著低于对照组：

对 API 用户来说这意味着：即使挂在本地小模型上，多步工具调用的完成率也足够稳定，/api/tasks队列 + 审批路由的组合可以撑起真实的自动化场景。

✅ 新手最佳实践清单

• 先用 SDK 再写裸请求：把 base URL 指到http://127.0.0.1:8787，任何 OpenAI SDK 开箱即用；只有需要审批、steer 等高级能力时才走/api/*。
• 会话 ID 一定要存下来：X-Atomic-Session-Id是延续上下文的钥匙，丢了就变成一次性对话。
• 别裸奔开放网络：--host默认绑本机；如果确实要跨机器访问，务必设置--api-key并加上反向代理的 TLS。
• 桌面应用优先 Sidecar：省掉端口冲突、防火墙和 token 管理，assistant_delta事件还能做逐字打字机效果。
• 盯住审批事件流：不处理approval_request的集成，等于把 Agent 卡死在第一个危险操作上。

想深入源码？两个入口目录：HTTP 层看 src/http/（路由表、OpenAI 协议封装、审批总线），Sidecar 层看 src/sidecar/（NDJSON 协议、消息路由、事件类型）。读完这两个目录，你对 Atomic Agent 的整个对外接口就有了完整的心智模型。

【免费下载链接】atomic-agentAtomic Agent is a local-first AI agent. Runs open-weight models on your own machine via llama.cpp.项目地址: https://gitcode.com/gh_mirrors/at/atomic-agent