Agent API 设计：同步接口与异步任务接口如何分层

一、先回答一个根问题：你的接口是在“返回结果”还是“管理任务”

很多 Agent API 设计失败，不是代码问题，而是语义错误：

• 把长任务当短请求
• 把任务生命周期压扁成一次 HTTP 响应

当链路涉及模型推理、外部工具、重试与补偿时，API 目标应该从“即时返回”升级为“可追踪执行”。

因此，设计第一步是分层：

• 同步层：快速、可判定、低副作用
• 异步层：长时、可恢复、有状态

二、同步接口该做什么：快、确定、可缓存

同步接口适合三类场景：

1. 参数校验与预检
2. 轻量推理（低时延）
3. 任务创建（返回 ticket）

同步接口不应该承担：

• 多步骤外部写操作
• 不确定执行时长
• 复杂重试与回滚

一个健康的同步响应应在可控时延内完成，并明确告诉客户端：

• 已完成（直接结果）
• 已受理（taskId）
• 已拒绝（错误码 + 可恢复建议）

三、异步任务接口：把执行变成显式生命周期

建议最小任务模型：

• queued
• running
• waiting_approval
• retrying
• succeeded
• failed
• canceled

并暴露三个核心接口：

• POST /tasks：创建任务
• GET /tasks/{id}：查询状态
• POST /tasks/{id}/actions：取消、重试、确认

这比“一个 /run 接口阻塞到底”更可扩展，也更利于前端控制台展示。

四、任务票据（Job Ticket）设计：不是随机 ID 那么简单

taskId 至少要满足：

• 全局唯一
• 可路由（可定位租户/区域）
• 可关联审计日志

推荐附加字段：

• idempotencyKey
• requestDigest
• deadline
• priority

这样你就能区分：

• “同一任务重复提交”
• “同一用户不同任务”
• “超时但可继续恢复”

五、状态查询与回调：一致性比实时性更重要

实践建议：

• 对外返回“最终一致”状态，不暴露内部抖动
• 回调 payload 带 eventSequence，避免乱序覆盖
• 轮询接口支持 etag 或 updatedSince 降低开销

Web 层可以采用：

• 前端：SSE/WS 显示实时进度
• 后端：状态接口作为权威真相

当实时通道异常时，前端可回退轮询而不丢任务语义。

六、错误模型：让客户端“可恢复”，而不是“只看到 500”

建议将错误分成三类：

1. 可重试（临时网络、下游 429）
2. 需修正参数（校验失败、权限不足）
3. 终止失败（业务冲突、不可逆错误）

每类都应返回：

• 稳定错误码
• 用户可读提示
• 建议动作（retry / edit / contact support）

这会直接提升前端可用性与用户信任。

七、落地清单：两周内可实现的 API 分层 MVP

• 拆分同步 /run 与异步 /tasks
• 统一任务状态机
• 增加幂等键与 requestDigest
• 支持 cancel/retry/approve 动作接口
• 打通 webhook + 轮询双通道

配套阅读：

• AI 应用后端第一课：幂等、限流、超时与熔断怎么一起工作

更多内容见 /articles，也可在 /apps/new 体验任务式交互。