AgentField异步执行完全指南：Webhooks、SSE实时流式与让AI Agent运行数小时的秘密

AgentField异步执行完全指南Webhooks、SSE实时流式与让AI Agent运行数小时的秘密【免费下载链接】agentfieldBuild, run and scale AI agents like API and microservices项目地址: https://gitcode.com/gh_mirrors/ag/agentfieldAgentField 是一个让你像调用 API 和微服务一样构建、运行和扩展 AI Agent 的开源平台。它的异步执行能力是整套体系的核心一次POST请求把任务丢进队列返回 202执行结果通过 Webhook 主动推送实时进度通过 SSEServer-Sent Events流式下发——这让 AI Agent 摆脱了请求-响应的秒级限制得以稳定运行数小时甚至更久。为什么 AI Agent 需要异步执行传统 API 是请求进来、几秒内返回。但 AI Agent 完全不同一次深度研究可能要先检索几十篇资料、多轮推理、调用子 Agent动辄几十分钟一次代码修复流程可能要跑数小时测试。如果调用方一直挂着 HTTP 连接等待网关超时、客户端断连、代理缓冲……任何一环掉链子任务就前功尽弃。AgentField 的解法很简单把执行变成有状态的长任务——请求被接受后立即返回任务 ID调用方随时可以挂掉任务状态由控制面持久化queued→running→succeeded/failed全程可查结果到达时 Webhook 主动通知你进度通过 SSE 实时推送到看板。相关 API 的完整定义见官方文档docs/api/EXECUTE.md。两种执行模式同步与异步同步执行小任务直接返回对于秒级小任务直接调用同步端点POST /api/v1/execute/{agent}.{reasoner}响应里就带着终态结果status: succeeded、result、duration_ms一应俱全。异步执行202 queued把任务交给后台对于长任务调用异步端点POST /api/v1/execute/async/{agent}.{reasoner}控制面返回HTTP 202和status: queued——注意queued不是失败而是已入队、等待调度的非终态轮询时要一直跟到running为止详见 docs/api/EXECUTE.md。之后的状态轮询只有一条简单路径GET /api/v1/executions/{execution_id}。有边界的队列拒绝也是设计异步队列是有界的容量打满后新请求不会无限堆积而是返回带Retry-After头的503并发超限返回429。这种快速失败比无界积压更符合微服务的弹性原则HTTP 状态场景处理建议429目标 Agent 并发数已满按Retry-After退避重试503异步调度队列已满按Retry-After退避重试503目标节点已知离线稍后重试或检查节点健康413请求体超过 32 MiB 默认上限精简 input 或调大AGENTFIELD_MAX_EXECUTE_BODY_BYTES这些预检在落库前完成被拒绝的请求不会留下任何僵尸执行记录。Webhook结果就绪时它主动来找你轮询能用但不够优雅——高频轮询既费资源又慢。AgentField 支持在提交异步执行时顺带注册一个完成 Webhook{ input: {question: 分析本次变更}, webhook: { url: https://example.com/execution-events, secret: shared-secret } }响应中的webhook_registered: true表示注册成功若注册失败会返回webhook_error字段告诉你原因。执行终态到达时控制面就会把事件推送到你的 URL——你的服务不需要轮询、不需要常驻连接收到通知再拉取详情即可。几个值得注意的工程细节可重放UI API 提供重试入口可对已注册 Webhook 的执行重新入队通知实现见 control-plane/internal/handlers/ui/executions.go签名校验审批类回调如人工审批 Webhook使用 HMAC-SHA256 验签未配置密钥时端点直接禁用防伪造设计见 control-plane/internal/handlers/webhook_approval.go幂等重复送达的审批回调会被识别并直接返回 200不会二次执行状态变更。SSE 实时流式不轮询也能看到每一秒Webhook 解决结果到了SSE 解决过程在看。AgentField 内置了多条事件流通道全部基于标准text/event-stream浏览器EventSource原生支持无需 WebSocket端点用途GET /api/ui/v1/executions/events全局执行生命周期事件流看板实时刷新GET /api/v1/triggers/:trigger_id/events/stream指定 Trigger 的事件流GET /api/ui/v1/nodes/events节点状态事件流GET /api/ui/v1/reasoners/eventsReasoner 目录事件流GET /api/ui/v1/workflows/:workflowId/notes/events工作流节点备注流以执行事件流为例control-plane/internal/handlers/ui/executions.go它的设计对新手很友好connected首帧连接建立立即下发一帧connected事件客户端可以确认通道已打开心跳保活每 30 秒Trigger 流为 15 秒发送一次心跳帧防止 Nginx 等代理把空闲连接掐断源码里还专门设置了X-Accel-Buffering: no关闭代理缓冲慢消费者降级事件总线在订阅者通道满时会丢弃旧帧而不是阻塞生产者——UI 端在重连时通过一次性GET /events全量补齐丢帧不破坏正确性设计思路见 control-plane/internal/handlers/triggers_sse.go。让 AI Agent 稳定运行数小时的三个秘密任务只跑一次在分钟级没问题跑到小时级就会撞上三堵墙进程重启、人工审批、部分失败。AgentField 分别给了三个答案秘密 1状态持久化 轮询语义明确所有中间状态queued、running、paused、awaiting_approval…都持久化在控制面GET /api/v1/executions/{execution_id}是薄状态视图需要完整记录input、result、notes、时间戳时用POST /api/v1/agentic/query或 UI 详情接口获取。调用方哪怕中途重启拿execution_id回来就能无缝续看。秘密 2重启与重放Restart/ReplayAPI任务失败后不要盲目重新/execute——那会产生一条毫无血缘关系的新执行。正确姿势是调用POST /api/v1/executions/{execution_id}/restart文档docs/api/EXECUTION_RESTART.md它会铸造新的execution_id/run_id同时在新旧记录间建立lineage/restarted_as双向血缘指针按reuse策略succeeded-before/all-succeeded/none复用源运行中已成功子步骤的结果只重跑失败的部分——对数小时的任务能省下大量算力源执行的轮询响应中会带restarted_as指针轮询客户端可以顺着它继续跟到后继执行。秘密 3自动接管中断的运行即使控制面或 Agent 进程在任务中途崩溃打开AGENTFIELD_RESUME_INTERRUPTED_RUNStrue后控制面在启动时会自动把符合条件的中断根执行agent_restart_orphaned、control_plane_shutdown等交给工作流范围的 restart 操作接管且默认用reuse: all-succeeded策略复用已完成子步骤。通过AGENTFIELD_RESUME_INTERRUPTED_WINDOW默认 1 小时、AGENTFIELD_RESUME_INTERRUPTED_DELAY等环境变量可精确调节接管窗口与调度延迟——详见 docs/api/EXECUTION_RESTART.md 的Automatic handoff一节。此外需要人工介入的步骤会以waiting_for_approval状态挂起等待审批 Webhook 或 UI 批准后才继续执行——长任务中途等人而不自毁是小时级稳定性的最后一块拼图。总结把 AI Agent 当微服务运营回顾一下 AgentField 异步执行的完整拼图202 有界队列请求即返回过载快速失败绝不无限积压Webhook 回调结果就绪主动推送签名校验 幂等 可重放SSE 事件流执行、节点、Reasoner、Trigger 多通道实时流心跳保活、丢帧可补Restart/Replay 自动接管失败重跑复用已成功步骤进程崩溃后自动接力。正是这套组合拳让 AI Agent 第一次真正可以像微服务一样被构建、被观测、被规模化——包括稳定地运行数小时。延伸阅读执行 API 全解docs/api/EXECUTE.md重启与重放 APIdocs/api/EXECUTION_RESTART.md执行可观测性设计日志/事件/原始日志三层模型docs/design/execution-observability-rfc.md异步执行入口实现control-plane/internal/handlers/execute.goSSE 执行事件流实现control-plane/internal/handlers/ui/executions.go架构总览docs/ARCHITECTURE.md【免费下载链接】agentfieldBuild, run and scale AI agents like API and microservices项目地址: https://gitcode.com/gh_mirrors/ag/agentfield创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考