Skip to main content

Agent 接入总览

本目录按调用流程组织 Agent OpenAPI 文档,重点说明客户端应如何组合接口、维护状态和处理恢复。

开始前

你需要:
  • 1)OAuth Access Token 或用户 API Key。
  • 2)一个可访问项目的 url_id,作为 Agent 路径中的 project_id。
  • 3)查询模型与性能档位、启动和交互使用 agent.run;读取状态、SSE(默认包含 Write/Edit 正文)和历史使用 agent.read。 项目不存在时,可以先通过 POST /open/v1/projects 创建,详见 用户与项目 API。

自定义 Agent 角色

如需让 Agent 以指定身份处理业务,请在项目创建时配置角色,调用顺序为:
  1. 调用 POST /open/v1/projects,在请求中设置可选的 agent_definition;参数规则和完整示例见创建项目。
  2. 保存响应中的 url_id,后续作为 project_id 使用。
  3. 调用 POST /open/v1/projects/{project_id}/agent/runs,只提交业务消息及本次运行配置,不重复传入角色。
  4. 新会话不传 conversation_id,续聊传原 conversation_id;两者均自动沿用项目角色。
agent_definition 只能在创建项目时设置,之后不可修改或补设。项目内 OpenAPI 对话在版本切换、上下文压缩和任务或进程恢复后继续使用该角色;未配置时保持默认角色。Run 请求不接受该字段,传入返回 400 invalid_request。 角色定制不会增加工具权限或绕过权限、权益与交付限制。在 Meoo Web 页面新建对话使用主站默认角色;Web 续聊 OpenAPI 发起的对话时仍按 OpenAPI 会话处理。 生命周期
GET agent/capabilities ── 选择 model + speed_tier
│
POST agent/runs(可选 disable_cloud)
│
├─ 保存 run_id + conversation_id + 本次选择
└─ GET agent/runs/{run_id}/events
   ├─ run.working / tool.call / tool.input.* / message.* / preview.ready
   ├─ run.input_required ── POST agent/action-responses ──┐
   ├─ run.usage(可多次,按 usage_id 去重累加)               │
   └─ 最终 snapshot / usage(若有)→ terminal event ◀────┘
典型接入顺序:
  • 1)调用 GET .../agent/capabilities 获取实时模型目录、性能档位和默认值,不要硬编码模型 ID。
  • 2)携带 ZIP 时,先申请 agent/archives 票据、PUT 上传并调用 confirm,再使用返回的 archive_id;普通文件和 Skill 包按各自流程准备。详见附件与 Skills。
  • 3)为用户消息生成稳定的 Idempotency-Key。
  • 4)调用 POST .../agent/runs,保存返回的 run_id、conversation_id、本次 model 和 speed_tier;需要禁用 Meoo Cloud 时在请求中传 disable_cloud: true。
  • 5)立即订阅该 run_id 的 SSE;Write/Edit 白名单正文默认通过工具事件输出。
  • 6)将 message.delta 追加到回复;将 message.snapshot.content 作为全量文本替换。存在 tool_calls 时整体替换当前轮公开工具状态,缺省时保留已有状态。
  • 7)收到 run.input_required 时,根据 action.kind 和 action.input_schema 收集输入并回复。
  • 8)按 usage_id 去重并累加每条 run.usage.data.credits_used;一条是单次结算值,同一 Run 可多次结算。最终结算事件若有,会先于正常终态。
  • 9)收到终态后停止重连。继续对话时把原 conversation_id 放入新的 Run 请求;需要保持模型、档位或禁云配置时再次显式传入。
  • 10)每次新 Run 的 model、speed_tier 省略时使用当前 capabilities 默认值,disable_cloud 省略为 false;同一 Run 的恢复和压缩保留已保存配置。禁云时不会调用 Meoo Cloud CLI 或生成云确认卡,已有云资源不会被关闭;外部 API 仍可用,缺少后端时使用 mock 并如实说明。

状态模型

Run 的已知状态包括:
状态是否终态客户端处理
submitted否已准入,准备执行
working否展示公开进度并继续消费 SSE
input_required否展示 Action;提交回复后继续订阅
completed是展示最终内容或预览
failed是展示失败并允许用户重新发起
canceled是展示已取消
interrupted是展示执行中断
遇到未知状态时按非终态处理,避免后续扩展导致客户端提前结束。 run.superseded 是结束旧订阅的事件,不是新的 Run 状态。它携带旧 Run 的真实终态,并可能提供接管任务的 current_run_id。

客户端需要保存什么

数据保存期限用途
project_id项目生命周期所有项目资源路径
conversation_id会话生命周期继续同一对话、读取历史
run_id至少保留到 Run 结束订阅事件、取消和刷新恢复
ZIP 的 archive_id上传确认至启动及重试 Run 期间原样传递已确认附件引用;同时保留其所属项目
已处理的 usage_id 与积分累计值至少覆盖本次 Run 和页面恢复防止重连重放导致积分重复累计
model / speed_tier至少保留到 Run 结束展示本次选择;下一次 Run 需要显式重传才能保持
请求中的 disable_cloud至少保留到 Run 结束同 Run 恢复保留;下一次 Run 省略为 false
按 tool_call_id 维护的工具状态Run 展示和恢复期间处理输入 delta/snapshot 与当前轮工具快照
Idempotency-Key至少覆盖请求重试窗口同一消息的安全重试
action_id仅当前 Action,有效期内回复问答或确认;不得解析
X-Meoo-Trace-Id按排障需要联系支持时定位请求
不要保存 SSE 帧 id 用于跨连接续传;服务端不支持 Last-Event-ID。断线后重新连接同一事件端点,使用 message.snapshot 恢复文本和可选的 tool_calls,并按 usage_id 去重结算事件。

专题文档

专题内容
Run 生命周期capabilities、模型与档位、单次禁云、start/current/cancel、幂等与错误
事件流与 Action工具输入流、执行结果、文本/工具快照、积分去重、重连与 Action
附件与 Skills普通附件、ZIP 上传与确认、上传限额、自定义 Skill 三态选择语义
会话与恢复参数继承、conversation 延续、历史分页、页面刷新和断线恢复

生产接入检查

☐ Token 和 API Key 只保存在可信服务端。 ☐ 每条用户消息使用独立 Idempotency-Key,超时重试复用原键及相同配置。 ☐ run_id 与 conversation_id 分开保存,没有混用。 ☐ 模型选项来自 capabilities;模型和档位省略时使用本次默认值,继续会话时按需显式重传。 ☐ disable_cloud 仅本次 Run 生效;同 Run 恢复保留,下一次 Run 省略为 false,YOLO 不能绕过。 ☐ SSE 使用 Authorization Header,没有把 Token 放进 Query。 ☐ 凭证具有 agent.read,并按 tool_call_id 和字段正确处理默认发送的工具 delta/snapshot。 ☐ message.snapshot.content 使用替换语义;tool_calls 存在时整体替换,缺省时保留已有工具状态。 ☐ 区分参数生成完成与工具执行成功,实际结果读取 tool.call.outcome,并处理 truncated 标记。 ☐ run.usage 按 usage_id 去重,使用整数安全的方式累加字符串 credits_used;缺失事件不视为零消耗。 ☐ 能处理 run.input_required 的 answers 和 confirmation 两种 Action。 ☐ 能识别 unsupported_action 并引导用户到 Meoo Web。 ☐ 重连 input_required Run 时,用最新签发的 Action Token 替换旧 Token。 ☐ 将正常终态作为最后一个业务帧处理;终态后停止重连,未知事件和字段能够被忽略。 ☐ ZIP 已完成 PUT 和 confirm,大小未超过返回的 max_size_bytes;每次 Run 最多一个 ZIP,附件合计不超过 10 项。 ☐ 附件签名 URL 和 Action Token 没有进入日志。 ☐ 支持人员可以用 X-Meoo-Trace-Id 排查问题。