Agenvoy 是一个在本地运行的开源 AI Agent 框架，以单个 Go 二进制提供 7×24 小时常驻的 HTTP API：你可以用/v1/send直接驱动 Agent 在本机执行任务，用 OpenAI 兼容的/v1/chat/completions把现有工具链无缝接上，再配合一组 session 管理接口完成会话创建、模型切换、记忆维护与任务控制。本文带你把这套本地接口一次性讲清楚。

一、本地 HTTP API 整体概览：端口、监听与接口分层

Agenvoy 以 daemon（守护进程）形式常驻，启动后自动在127.0.0.1:17989与[::1]:17989上监听，端口固定不可调整（定义见 internal/filesystem/runtime.go）。也就是说：

• API 只绑定回环地址，天然不会暴露到局域网或公网；
• 部分接口还叠加了localhostOnly()守卫，要求请求来源必须是本机回环地址，否则返回 403localhost only。

全部路由集中注册在 internal/runtime/routes/new.go，可以粗略分为两类：

💡 想动手前先看一眼版本与健康状态：GET /v1/info/version返回{version, dev}，是最简单的连通性检查。

二、/v1/send：一条请求驱动本地 AI Agent 执行任务

POST /v1/send是 Agenvoy 的核心 Agent 执行入口（实现见 internal/runtime/routes/handler/send.go），一次请求即可让 Agent 在本机真正干活：调用工具、读写文件、交付结果。

请求参数速查

三个值得记住的行为细节

1. 自动创建会话：不带session_id时，Agenvoy 会生成temp-xxxx（或chat-xxxx）会话，响应里带回session_id，后续请求带上它即可延续上下文。
2. 运行中自动转为 steer（转向）：如果该会话正在执行任务，新内容会被作为"转向指令"追加进去，响应为{session_id, steer: true}——适合在执行中途补充要求。
3. 两种响应形态：
   • JSON 模式：{text, model?, usage?, session_id}；被取消时为{session_id, canceled: true}；
   • SSE 模式（sse: true）：先推一帧会话确认信息，随后逐帧推送执行事件。

curl -sS -H 'Content-Type: application/json' \ -d '{"content":"列出目前可用工具","persist":false}' \ http://127.0.0.1:17989/v1/send

三、/v1/chat/completions：OpenAI 兼容接口快速接入现有工具链

POST /v1/chat/completions实现了 OpenAI 兼容协议（实现见 internal/runtime/routes/handler/chatCompletions/chatCompletions.go），把 OpenAI SDK 或任意兼容客户端的base_url指到 Agenvoy 即可复用。

请求要点

两个进阶开关

• 🤖Agent 模式：请求头加X-Agenvoy-Agent: 1（或true/yes）。默认情况下该接口是"纯对话"（排除所有内置工具）；开启 Agent 模式后，Agenvoy 的内置工具链对模型开放，等价于把完整 Agent 能力挂到 OpenAI 协议后面。
• 📁Zed 风格工作目录：system 消息中出现- `/绝对路径`形式时会被识别为本次任务的工作目录。

无状态设计：每次请求自带上下文

该端点是stateless的：延续对话需要在每次请求中带上完整messages历史。响应严格对齐 OpenAI 结构：

• 非流式：chat.completion对象，含choices、finish_reason（stop或tool_calls）与usage（含cached_tokens明细）；
• 流式（stream.go）：逐帧chat.completion.chunk，工具调用过程会以▸ 工具名摘要出现在reasoning_content中，最后以data: [DONE]收尾。

四、Session 管理接口全解：创建、查询、更新、删除与记忆维护

Session（会话）是 Agenvoy 组织的核心单位：每个会话拥有独立的配置、历史与任务记录。接口实现集中在 internal/runtime/routes/handler/session.go。

会话生命周期 CRUD

记忆与上下文维护

这套接口让"长期运行的 Agent"变得可控：上下文变长时用compact瘦身，想彻底重来时用reset，而summary模式会先保住滚动摘要再清理，避免丢失关键上下文。

五、任务控制：取消执行、恢复 pending 与审批工具确认

Agent 任务执行到一半"卡住"或"需要人工拍板"时，有三组接口可用（实现见 pending.go 与 confirm.go）。

1. 待处理（pending）任务：提问、恢复、丢弃

当任务触发ask_user或工具确认而挂起时（例如窗口关闭、进程被杀），它会以 pending 形式留存在会话中，约一分钟内重新可查：

2. 取消与工具确认

🔐安全细节：批准"受限路径"或 Linux 上的pkg_manage调用时，必须携带系统password，且只接受本机来源（否则 403），密码错误返回 401——高危操作的远程代批是被显式堵死的。

六、常见错误码与安全边界速查

安全模型一句话总结：API 只绑定回环地址 + local-only 守卫 + 高危操作二次验证，三层叠加，保证你的文件、凭据与工具执行始终留在本机边界内。

七、延伸阅读：源码与文档索引

• 路由总表：internal/runtime/routes/new.go
• /v1/send实现：internal/runtime/routes/handler/send.go
• OpenAI 兼容层：internal/runtime/routes/handler/chatCompletions/
• Session 管理：internal/runtime/routes/handler/session.go
• 完整中文接口文档：doc/doc.zh.md / 英文：doc/doc.md
• 架构说明：doc/architecture.zh.md

掌握/v1/send、/v1/chat/completions与 session 管理这三块，就基本能用 Agenvoy 的 HTTP API 搭建属于自己的自动化流程了：用兼容端点做轻量问答，用/v1/send触发完整 Agent 执行，再用 session 接口管好上下文与任务生命周期。