Agenvoy HTTP API完整参考：/v1/send、chat/completions与Session管理接口全解

【免费下载链接】AgenvoyA local AI agent harness in Go that runs 24/7 with auto-built tools, MCP, and Ollama项目地址https://gitcode.com/gh_mirrors/ag/Agenvoy点击查看免费下载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可以粗略分为两类访问范围典型接口说明 开放仍只监听 loopbackPOST /v1/send、POST /v1/chat/completions、GET /v1/sessions、GET /v1/models、GET /v1/logAgent 执行、会话列表、模型列表、SSE 日志供同机器上的 dashboard 与外部脚本调用local-onlylocalhostOnly()守卫POST /v1/session、GET/POST/DELETE /v1/session/:id、POST /v1/session/:id/memory、模型路由、Provider 凭据、MCP 配置、Skill、排程等会改动凭据、配置或进程生命周期设计上只给本机 dashboard 使用 想动手前先看一眼版本与健康状态GET /v1/info/version返回{version, dev}是最简单的连通性检查。二、/v1/send一条请求驱动本地 AI Agent 执行任务POST /v1/send是 Agenvoy 的核心 Agent 执行入口实现见 internal/runtime/routes/handler/send.go一次请求即可让 Agent 在本机真正干活调用工具、读写文件、交付结果。请求参数速查参数类型必填说明contentstring✅任务内容为空返回 400session_idstring❌不传则自动创建会话默认前缀temp-persist: true时用chat-ssebool❌true时以 SSEtext/event-stream流式推送事件直到 done / error / canceledpersistbool❌是否把临时会话持久化为chat-会话modelstring❌指定模型缺省走默认/自动路由work_dirstring❌工作目录必须已存在且是目录缺省为用户主目录skillstring❌直接指定要执行的 Skillsystem_promptstring❌附加的 system promptexclude_toolsstring[]❌排除某些工具三个值得记住的行为细节自动创建会话不带session_id时Agenvoy 会生成temp-xxxx或chat-xxxx会话响应里带回session_id后续请求带上它即可延续上下文。运行中自动转为 steer转向如果该会话正在执行任务新内容会被作为转向指令追加进去响应为{session_id, steer: true}——适合在执行中途补充要求。两种响应形态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/completionsOpenAI 兼容接口快速接入现有工具链POST /v1/chat/completions实现了 OpenAI 兼容协议实现见 internal/runtime/routes/handler/chatCompletions/chatCompletions.go把 OpenAI SDK 或任意兼容客户端的base_url指到 Agenvoy 即可复用。请求要点字段说明model模型名缺省使用 daemon 默认模型messages标准 OpenAI 消息数组必须包含至少一条 user 消息否则 400no user messagestreamtrue时按 SSE chunk 输出reasoning_effort可选nonelowmediumhighxhighmax另支持别名minimalextraultra无效值退回会话级或mediumtools客户端工具声明模型可返回tool_calls由你本地执行两个进阶开关Agent 模式请求头加X-Agenvoy-Agent: 1或true/yes。默认情况下该接口是纯对话排除所有内置工具开启 Agent 模式后Agenvoy 的内置工具链对模型开放等价于把完整 Agent 能力挂到 OpenAI 协议后面。Zed 风格工作目录system 消息中出现- /绝对路径形式时会被识别为本次任务的工作目录。无状态设计每次请求自带上下文该端点是stateless的延续对话需要在每次请求中带上完整messages历史。响应严格对齐 OpenAI 结构非流式chat.completion对象含choices、finish_reasonstop或tool_calls与usage含cached_tokens明细流式stream.go逐帧chat.completion.chunk工具调用过程会以▸ 工具名摘要出现在reasoning_content中最后以data: [DONE]收尾。四、Session 管理接口全解创建、查询、更新、删除与记忆维护Session会话是 Agenvoy 组织的核心单位每个会话拥有独立的配置、历史与任务记录。接口实现集中在 internal/runtime/routes/handler/session.go。会话生命周期 CRUD方法路径作用GET/v1/sessions?filterall\|active\|permanent\|temporary列出会话与状态按最近活跃排序filter可按活跃/永久/临时筛选POST/v1/session创建会话body{prefix}默认cli-返回{session_id}GET/v1/session/:id读取完整状态id、self_id、name、role、state、model、reasoning、levels、count可加?chat1附原始 action log、?usage1附 24h/7d/28d token 用量POST/v1/session/:id部分更新self_id/name/role/model/reasoning均为选填未传字段不动model: 重置为autoself_id重复返回 409DELETE/v1/session/:id删除会话目录、历史、状态与向量返回{ok: true}记忆与上下文维护方法路径作用POST/v1/session/:id/memory按action执行记忆操作summary重建滚动摘要回count、compact丢弃旧消息回removed、reset清空对话需带mode: summary\|allPOST/v1/session/:id/followup基于对话生成后续建议返回{title, suggests}无历史时为空值这套接口让长期运行的 Agent变得可控上下文变长时用compact瘦身想彻底重来时用reset而summary模式会先保住滚动摘要再清理避免丢失关键上下文。五、任务控制取消执行、恢复 pending 与审批工具确认Agent 任务执行到一半卡住或需要人工拍板时有三组接口可用实现见 pending.go 与 confirm.go。1. 待处理pending任务提问、恢复、丢弃当任务触发ask_user或工具确认而挂起时例如窗口关闭、进程被杀它会以 pending 形式留存在会话中约一分钟内重新可查方法路径作用GET/v1/session/:id/task列出可恢复的 pending 任务仍在运行的不列出GET/v1/session/:id/task/:task_hash/questions读取该任务提出的问题含选项、是否多选、是否机密POST/v1/session/:id/task/:task_hash/resume以{answers}作答并恢复执行DELETE/v1/session/:id/task/:task_hash直接丢弃任务不作答2. 取消与工具确认方法路径作用POST/v1/session/:id/cancel/:task_hash以用户取消方式终止运行中任务返回{ok, cancelled: true}hash 已失效时返回stale: truePOST/v1/session/:id/confirm/:confirm_hash审批挂起的工具确认{approve, remember?, allow_turn?, abort?, reason?, password?}确认已处理或过期返回 410安全细节批准受限路径或 Linux 上的pkg_manage调用时必须携带系统password且只接受本机来源否则 403密码错误返回 401——高危操作的远程代批是被显式堵死的。六、常见错误码与安全边界速查状态码典型场景400content为空、缺少 user 消息、reasoning/model取值非法、body 解析失败401受限审批的password错误403非本机来源调用 local-only 接口localhost only404会话不存在、模型不存在、pending 任务无记录409self_id与已有会话冲突410工具确认已被处理或过期500执行过程中的内部/上游错误安全模型一句话总结API 只绑定回环地址 local-only 守卫 高危操作二次验证三层叠加保证你的文件、凭据与工具执行始终留在本机边界内。七、延伸阅读源码与文档索引路由总表internal/runtime/routes/new.go/v1/send实现internal/runtime/routes/handler/send.goOpenAI 兼容层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 接口管好上下文与任务生命周期。赞分享【免费下载链接】AgenvoyA local AI agent harness in Go that runs 24/7 with auto-built tools, MCP, and Ollama项目地址https://gitcode.com/gh_mirrors/ag/Agenvoy点击查看免费下载相关推荐Gemini-FastAPI API 接口完整参考/v1/chat/completions 流式、工具调用与结构化输出全解Gemini FastAPI API 接口完整参考/v1/chat/completions 流式、工具调用与结构化输出全解 Gemini FastAPI 将Cursor2API-go OpenAI 兼容 API 完全参考/v1/chat/completions 与 /v1/models 全字段解析清单Cursor2API go OpenAI 兼容 API 完全参考/v1/chat/completions 与 /v1/models 全字段解析清单 cursoAI 应用LLM 网关后端API网关WorkBuddy Manager API参考/v1网关与/api管理面接口完整清单WorkBuddy Manager API参考/v1网关与/api管理面接口完整清单 WorkBuddy Manager 是腾讯 CodeBuddy 账号池管后端API网关前端认证鉴权上一篇flatpickr禁用日期完全指南用minDate、disable和自定义函数轻松控制可选范围下一篇OpenArm 7 自由度开源机械臂快速上手从接线到 Demo 的完整安装教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考