完整指南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-agentAtomic 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 SidecarAgent 以子进程方式运行通过 stdin/stdout 用换行分隔的 JSONNDJSON通信。适合 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 的官方说明服务会随启动它的父进程退出而结束——崩溃的桌面应用或关闭的终端不会留下占用端口的僵尸服务。想常驻后台加--no-parent-exit或设置ATOMIC_AGENT_SERVE_NO_PARENT_EXIT1这是官方支持的守护化方式nohup和 disown都不行。孤儿清理每次启动都会在状态目录serve/下登记自己并清理历史遗留进程手动执行atomic-agent serve --reap也可触发扫描。配置好 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/capabilitiesGET查询服务端支持的能力清单/api/configGET / PATCH读取 / 局部修改配置/api/sessions·/api/sessions/{id}GET / DELETE列出、查看、删除会话/api/sessions/{id}/steerPOST / GET / DELETE向运行中的回合中途插话以及查看未送达的插话/api/approval/resolvePOST处理危险操作的人工审批请求/api/eventsGET审批等实时事件流SSE/api/tasks·/api/tasks/{id}/run·/api/tasks/drain增删查 / 执行 / 批量出队任务队列管理/api/skills·/api/skills/{name}·/api/skills/install·/api/skills/uninstallGET / POST技能Skills安装与查看/api/mcp/servers/{name}/restart·enable·disablePOST管理外部 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 触发外部系统比如 CIPOST 到/api/webhooks/{name}即可让 Agent 开工实现事件驱动的自动化。 Tauri Sidecar 嵌入桌面应用的内嵌指南如果你做的是桌面应用Tauri / ElectronSidecar 模式更优雅启动一个atomic-agent子进程所有通信走 stdin/stdout零端口、零鉴权配置。协议本质换行分隔的 JSON 帧协议实现非常薄每帧一个 JSON 对象、以\n结尾。宿主你的应用发requestSidecar 回event和response三者的类型定义都集中在 src/sidecar/sidecar-events.tsTypeScript 项目可以直接 import 同一份类型。帧结构的组装逻辑在 src/sidecar/stdio-protocol.ts。宿主 → Sidecar 的请求类型HostRequestTypestart_session·send_message·steer_message·run_step·cancel·approval_response·get_session·skill_install/skill_uninstall/skill_list·shutdown·pingSidecar → 宿主的事件类型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渲染进对应的消息气泡。嵌入时值得知道的三个设计点每个 Sidecar 进程只托管一个活跃会话start_session会建立或替换当前会话逻辑见 src/sidecar/main.ts。多窗口应用可以起多个子进程互不干扰。中途转向steersteer_message会把消息折叠进正在运行的回合而不是排队等下一轮。如果会话处于空闲响应里的steered: false表示转向没接住宿主应回退到send_message。对端消失的优雅处理桌面应用突然退出时管道会报 EPIPESidecar 内部已捕获这种情况并转为停止输出不会因宿主先走而崩溃——这个健壮性正是它敢被桌面应用直接 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考