尧图网站建设 
go-micro Agent 人工输入暂停与恢复基于 request_input 的持久化运行中断续【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro导读在 services → agents → workflows 的统一运行时生命周期中Agent 常常在执行中途遇到必须由人来拍板的节点——选择部署区域、审批发布、补充缺失参数等。go-micro 通过内置的request_input工具与持久化 Checkpoint 机制让 Agent 运行可以在该节点以paused/input-required状态落盘保存等人工输入到位后再以同一个 run ID无缝续跑且原始提示词、记忆、已完成工具调用历史全部保留。本文以 examples/agent-human-input/README.md 为核心结合 agent/checkpoint.go、agent/builtin.go 等源码实现完整讲解该模式的 API 用法、内部状态机、取消与超时语义以及 CLI 操作方式。一、为什么需要人工输入暂停/恢复Agent 的自动执行链路并不总是能独立走完决策缺失模型需要用户决定部署到哪个区域、选择哪个套餐、确认某个业务口径审批门槛上线前必须由运维或负责人确认参数补充用户最初的指令本身不完整缺少继续执行所需的关键信息。如果在这类节点上直接结束运行前面已经完成的工具调用如服务探测、配置下发就全部白费如果强制模型猜一个答案又违背了变更流程的确定性要求。go-micro 的做法是把整个 services → agents → workflows 生命周期收敛到同一个持久化运行时中服务暴露工具tools→ Agent 判断需要人工输入 → 调用内置request_input→ 运行以paused/input-required保存 → 人工输入到达后同一 checkpoint 运行继续。这意味着暂停不是丢失状态而是一次有据可查的持久化中断。运行记录本身flow/steps.go 中的flow.Run被保存到 store等待续跑。二、核心 API 模式完整代码示例原文档给出了最精简的可用模式完整继承如下cp : flow.StoreCheckpoint(nil, deploy-agent) ag : agent.New( agent.Name(deploy-agent), agent.WithCheckpoint(cp), ) resp, err : ag.Ask(ctx, Deploy the service) if err ! nil { // 如果模型调用了内置 request_input 工具运行会以 // paused/input-required 保存而不是丢失状态或提前结束。 pending, _ : agent.Pending(ctx, ag) runID : pending[0].ID // 稍后当操作员提供了缺失的答案后同一个 run ID // 带着原始提示词、人工输入、记忆、已完成的工具历史继续执行。 resp, err agent.ResumeInput(ctx, ag, runID, Deploy to us-east-1) } _ resp2.1 各环节拆解步骤API作用创建持久化 Checkpointflow.StoreCheckpoint(store, scope)返回 store 支撑的flow.Checkpointscope是该 Agent 专属的运行表名如deploy-agent。传nil时使用store.DefaultStore装配 Agentagent.New(...)agent.WithCheckpoint(cp)只有配置了 Checkpoint暂停/恢复才生效发起运行ag.Ask(ctx, message)模型若调用request_inputAsk返回错误并已落盘保存运行列出待处理运行agent.Pending(ctx, ag)返回该 Agent 名下所有未终结非 done/canceled/timeout/rate_limited/expired的运行携带人工输入续跑agent.ResumeInput(ctx, ag, runID, input)仅适用于input-required状态的运行input会显式追加到原始消息之后关于flow.StoreCheckpoint的实现细节flow/steps.go 展示了它如何把运行隔离到独立的 store 表通过store.Scope(s, flow, scope)将每个 flow 名称作为独立表避免与其他 flow、服务或 Agent 状态互相污染。flow.Checkpoint接口flow/steps.go定义Save/Load/Delete/List四个方法StoreCheckpoint是默认的 store 支撑实现你也可以实现该接口接入其它持久化后端。2.2 内置 request_input 工具模型侧看到的是一个名为request_input的内置工具定义见 agent/builtin.go 中的builtinTools()其描述为Pause this agent run when you need missing information, a decision, or other human input before you can continue. The run is checkpointed as input-required and can be resumed with the human response without losing completed tool history.它只有一个promptstring参数用于说明需要操作员提供的具体问题、决策或指令。当模型调用它时agent/builtin.go 的handleHumanInput会记录暂停信息并返回RefusedApproval类型的结果input-required: prompt随后 agent/agent.go 将运行状态置为paused、stage 置为input-required并通过run.State.Set(inputPause{...})把original_message与prompt一并序列化保存inputPause结构见 agent/builtin.go。除request_input外Agent 还内置了plan维护计划与delegate委托子任务/A2A 外部 Agent两个工具三者同属Agent 对自身的能力与发现到的服务工具并列装配进工具链agent/builtin.go。三、运行状态机谁该用 Resume谁该用 ResumeInputgo-micro 对暂停运行做了精细区分不同暂停原因对应不同恢复 API普通agent.Resume继续支持已完成done、失败failed以及审批暂停approval-paused的运行。完成态直接从 checkpoint 返回结果而不重新调用模型失败或进行中则从保存的输入消息继续agent/checkpoint.goagent.ResumeInput专用于input-required暂停。因为人工回答必须显式传入普通Resume遇到input-required运行会直接报错并提示改用ResumeInputagent/checkpoint.go。ResumeInput的内部流程agent/checkpoint.go从 checkpoint 加载该 run校验status paused且stage input-required否则返回agent run %s is not waiting for human input通过run.State.Scan(p)解码inputPause取回OriginalMessage缺失时回退到run.State.Data构造续跑消息original \n\nHuman input: input将 run 置为running、stage 重置为ask复用askLocked携带existingrun 与addUserMessagefalse语义继续模型/工具循环——因此已完成工具历史steps会被合并保留mergeCheckpointToolCalls见 agent/checkpoint.go。3.1 测试证据仓库的 agent/checkpoint_test.goTestHumanInputPauseResumesSameRunWithInput完整验证了该闭环Ask返回错误 →Pending恰好返回 1 条paused/input-required运行 →State.Scan能解码出original_message与prompt→ 普通Resume报错并提示ResumeInput→ResumeInput(ctx, a, runID, us-east-1)成功后续跑提示词中包含Human input: us-east-1最终 checkpoint 中的运行状态变为done。审批暂停approval则走另一条路径Approve回调拒绝工具调用时agent/builtin.gorun 以paused/approval保存由普通Resume继续agent/checkpoint_test.go 起有对应测试。四、取消与截止时间语义重要边界ResumeInput使用的是调用方的context.Context——checkpoint 读取、写入以及续跑的模型/工具轮次全部沿用该 context。关键语义如下agent/checkpoint.go若在恢复提交完成之前 context 被取消或截止时间到期调用返回 context 错误同时 checkpoint 中的运行仍保持paused/input-required不会出现半恢复状态后续用agent.Pending再次列出待操作员就绪后用新的 context重试即可。agent/checkpoint_test.go 的TestHumanInputResumeHonorsCanceledContextAndLeavesRunPending正是这一语义的回归测试用已取消的 context 调用ResumeInput返回context.Canceled随后重新加载 checkpoint运行依旧是paused/input-required且original_message与prompt完整无缺。值得一提的配套保护是 agent/builtin.go 的contextWrap当Ask的 context 已被取消或过期时任何工具调用都会立即返回 context 错误防止守卫簿记与有副作用的工具在调用方放弃运行后继续执行。五、CLI 与高层 API 操作除了直接调用 Go APImicro命令提供了对应运维入口见 cmd/micro/cli/agent/agent.go# 列出待处理/暂停运行其中 input-required 运行会提示如下命令 micro agent inspect name --status paused # 为 input-required 运行补录人工输入 micro agent resume-input name run-id --input text从源码看micro agent resume-input要求--input必填cmd/micro/cli/agent/agent.go它会校验运行确实处于paused/input-required将人工输入记入运行步骤后提示重建同一 checkpoint store 下的 Agent 并调用micro.AgentResumeInput继续模型执行cmd/micro/cli/agent/agent.goinspect 输出中input-required运行会直接给出micro agent resume-input ...的建议命令cmd/micro/cli/agent/agent.go。面向服务端 RPC 场景agent.Pending与agent.ResumePendingagent/agent.go可用于启动恢复循环用相同 checkpoint store 重建 Agent 后调用ResumePending即可按旧→新顺序排空持久化积压运行某条运行再次失败时返回其 run ID 与错误便于告警与后续重试。六、适用前提与注意事项必须配置 Checkpoint未通过agent.WithCheckpoint配置时Resume/ResumeInput会直接报agent %s has no checkpoint configuredagent/checkpoint.go恢复方式必须匹配暂停类型input-required只能用ResumeInput恢复用普通Resume会得到明确提示错误agent/checkpoint.gocontext 即恢复的事务边界恢复未提交前取消/超时运行保持不变可安全重试运行终结状态不可恢复done、canceled、timeout、rate_limited、expired均为终态terminalAgentRunStatus见 agent/checkpoint.go对这些状态调用Resume会返回 terminal 错误存储作用域隔离flow.StoreCheckpoint的 scope 参数应保持稳定同一 Agent 续跑时必须使用指向同一存储的 checkpoint否则无法按 run ID 找回运行。七、小结go-micro 的人工输入暂停/恢复把人参与决策以一等公民的方式嵌入持久化 Agent 运行模型在需要决策时调用内置request_input工具运行以paused/input-required落盘agent.Pending负责发现agent.ResumeInput携带显式人工输入按同一 run ID 续跑context 取消/超时则保证恢复操作的原子性。整个机制与审批暂停、终态分类、工具历史合并共同构成了 agent/checkpoint.go 所实现的完整 durable agent 执行语义可直接用于部署审批、人工审核、参数补全等真实场景。【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 go-micro Agent 人工输入暂停与恢复：基于 request_input 的持久化运行中断续
go-micro Agent 人工输入暂停与恢复基于 request_input 的持久化运行中断续【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro导读在 services → agents → workflows 的统一运行时生命周期中Agent 常常在执行中途遇到必须由人来拍板的节点——选择部署区域、审批发布、补充缺失参数等。go-micro 通过内置的request_input工具与持久化 Checkpoint 机制让 Agent 运行可以在该节点以paused/input-required状态落盘保存等人工输入到位后再以同一个 run ID无缝续跑且原始提示词、记忆、已完成工具调用历史全部保留。本文以 examples/agent-human-input/README.md 为核心结合 agent/checkpoint.go、agent/builtin.go 等源码实现完整讲解该模式的 API 用法、内部状态机、取消与超时语义以及 CLI 操作方式。一、为什么需要人工输入暂停/恢复Agent 的自动执行链路并不总是能独立走完决策缺失模型需要用户决定部署到哪个区域、选择哪个套餐、确认某个业务口径审批门槛上线前必须由运维或负责人确认参数补充用户最初的指令本身不完整缺少继续执行所需的关键信息。如果在这类节点上直接结束运行前面已经完成的工具调用如服务探测、配置下发就全部白费如果强制模型猜一个答案又违背了变更流程的确定性要求。go-micro 的做法是把整个 services → agents → workflows 生命周期收敛到同一个持久化运行时中服务暴露工具tools→ Agent 判断需要人工输入 → 调用内置request_input→ 运行以paused/input-required保存 → 人工输入到达后同一 checkpoint 运行继续。这意味着暂停不是丢失状态而是一次有据可查的持久化中断。运行记录本身flow/steps.go 中的flow.Run被保存到 store等待续跑。二、核心 API 模式完整代码示例原文档给出了最精简的可用模式完整继承如下cp : flow.StoreCheckpoint(nil, deploy-agent) ag : agent.New( agent.Name(deploy-agent), agent.WithCheckpoint(cp), ) resp, err : ag.Ask(ctx, Deploy the service) if err ! nil { // 如果模型调用了内置 request_input 工具运行会以 // paused/input-required 保存而不是丢失状态或提前结束。 pending, _ : agent.Pending(ctx, ag) runID : pending[0].ID // 稍后当操作员提供了缺失的答案后同一个 run ID // 带着原始提示词、人工输入、记忆、已完成的工具历史继续执行。 resp, err agent.ResumeInput(ctx, ag, runID, Deploy to us-east-1) } _ resp2.1 各环节拆解步骤API作用创建持久化 Checkpointflow.StoreCheckpoint(store, scope)返回 store 支撑的flow.Checkpointscope是该 Agent 专属的运行表名如deploy-agent。传nil时使用store.DefaultStore装配 Agentagent.New(...)agent.WithCheckpoint(cp)只有配置了 Checkpoint暂停/恢复才生效发起运行ag.Ask(ctx, message)模型若调用request_inputAsk返回错误并已落盘保存运行列出待处理运行agent.Pending(ctx, ag)返回该 Agent 名下所有未终结非 done/canceled/timeout/rate_limited/expired的运行携带人工输入续跑agent.ResumeInput(ctx, ag, runID, input)仅适用于input-required状态的运行input会显式追加到原始消息之后关于flow.StoreCheckpoint的实现细节flow/steps.go 展示了它如何把运行隔离到独立的 store 表通过store.Scope(s, flow, scope)将每个 flow 名称作为独立表避免与其他 flow、服务或 Agent 状态互相污染。flow.Checkpoint接口flow/steps.go定义Save/Load/Delete/List四个方法StoreCheckpoint是默认的 store 支撑实现你也可以实现该接口接入其它持久化后端。2.2 内置 request_input 工具模型侧看到的是一个名为request_input的内置工具定义见 agent/builtin.go 中的builtinTools()其描述为Pause this agent run when you need missing information, a decision, or other human input before you can continue. The run is checkpointed as input-required and can be resumed with the human response without losing completed tool history.它只有一个promptstring参数用于说明需要操作员提供的具体问题、决策或指令。当模型调用它时agent/builtin.go 的handleHumanInput会记录暂停信息并返回RefusedApproval类型的结果input-required: prompt随后 agent/agent.go 将运行状态置为paused、stage 置为input-required并通过run.State.Set(inputPause{...})把original_message与prompt一并序列化保存inputPause结构见 agent/builtin.go。除request_input外Agent 还内置了plan维护计划与delegate委托子任务/A2A 外部 Agent两个工具三者同属Agent 对自身的能力与发现到的服务工具并列装配进工具链agent/builtin.go。三、运行状态机谁该用 Resume谁该用 ResumeInputgo-micro 对暂停运行做了精细区分不同暂停原因对应不同恢复 API普通agent.Resume继续支持已完成done、失败failed以及审批暂停approval-paused的运行。完成态直接从 checkpoint 返回结果而不重新调用模型失败或进行中则从保存的输入消息继续agent/checkpoint.goagent.ResumeInput专用于input-required暂停。因为人工回答必须显式传入普通Resume遇到input-required运行会直接报错并提示改用ResumeInputagent/checkpoint.go。ResumeInput的内部流程agent/checkpoint.go从 checkpoint 加载该 run校验status paused且stage input-required否则返回agent run %s is not waiting for human input通过run.State.Scan(p)解码inputPause取回OriginalMessage缺失时回退到run.State.Data构造续跑消息original \n\nHuman input: input将 run 置为running、stage 重置为ask复用askLocked携带existingrun 与addUserMessagefalse语义继续模型/工具循环——因此已完成工具历史steps会被合并保留mergeCheckpointToolCalls见 agent/checkpoint.go。3.1 测试证据仓库的 agent/checkpoint_test.goTestHumanInputPauseResumesSameRunWithInput完整验证了该闭环Ask返回错误 →Pending恰好返回 1 条paused/input-required运行 →State.Scan能解码出original_message与prompt→ 普通Resume报错并提示ResumeInput→ResumeInput(ctx, a, runID, us-east-1)成功后续跑提示词中包含Human input: us-east-1最终 checkpoint 中的运行状态变为done。审批暂停approval则走另一条路径Approve回调拒绝工具调用时agent/builtin.gorun 以paused/approval保存由普通Resume继续agent/checkpoint_test.go 起有对应测试。四、取消与截止时间语义重要边界ResumeInput使用的是调用方的context.Context——checkpoint 读取、写入以及续跑的模型/工具轮次全部沿用该 context。关键语义如下agent/checkpoint.go若在恢复提交完成之前 context 被取消或截止时间到期调用返回 context 错误同时 checkpoint 中的运行仍保持paused/input-required不会出现半恢复状态后续用agent.Pending再次列出待操作员就绪后用新的 context重试即可。agent/checkpoint_test.go 的TestHumanInputResumeHonorsCanceledContextAndLeavesRunPending正是这一语义的回归测试用已取消的 context 调用ResumeInput返回context.Canceled随后重新加载 checkpoint运行依旧是paused/input-required且original_message与prompt完整无缺。值得一提的配套保护是 agent/builtin.go 的contextWrap当Ask的 context 已被取消或过期时任何工具调用都会立即返回 context 错误防止守卫簿记与有副作用的工具在调用方放弃运行后继续执行。五、CLI 与高层 API 操作除了直接调用 Go APImicro命令提供了对应运维入口见 cmd/micro/cli/agent/agent.go# 列出待处理/暂停运行其中 input-required 运行会提示如下命令 micro agent inspect name --status paused # 为 input-required 运行补录人工输入 micro agent resume-input name run-id --input text从源码看micro agent resume-input要求--input必填cmd/micro/cli/agent/agent.go它会校验运行确实处于paused/input-required将人工输入记入运行步骤后提示重建同一 checkpoint store 下的 Agent 并调用micro.AgentResumeInput继续模型执行cmd/micro/cli/agent/agent.goinspect 输出中input-required运行会直接给出micro agent resume-input ...的建议命令cmd/micro/cli/agent/agent.go。面向服务端 RPC 场景agent.Pending与agent.ResumePendingagent/agent.go可用于启动恢复循环用相同 checkpoint store 重建 Agent 后调用ResumePending即可按旧→新顺序排空持久化积压运行某条运行再次失败时返回其 run ID 与错误便于告警与后续重试。六、适用前提与注意事项必须配置 Checkpoint未通过agent.WithCheckpoint配置时Resume/ResumeInput会直接报agent %s has no checkpoint configuredagent/checkpoint.go恢复方式必须匹配暂停类型input-required只能用ResumeInput恢复用普通Resume会得到明确提示错误agent/checkpoint.gocontext 即恢复的事务边界恢复未提交前取消/超时运行保持不变可安全重试运行终结状态不可恢复done、canceled、timeout、rate_limited、expired均为终态terminalAgentRunStatus见 agent/checkpoint.go对这些状态调用Resume会返回 terminal 错误存储作用域隔离flow.StoreCheckpoint的 scope 参数应保持稳定同一 Agent 续跑时必须使用指向同一存储的 checkpoint否则无法按 run ID 找回运行。七、小结go-micro 的人工输入暂停/恢复把人参与决策以一等公民的方式嵌入持久化 Agent 运行模型在需要决策时调用内置request_input工具运行以paused/input-required落盘agent.Pending负责发现agent.ResumeInput携带显式人工输入按同一 run ID 续跑context 取消/超时则保证恢复操作的原子性。整个机制与审批暂停、终态分类、工具历史合并共同构成了 agent/checkpoint.go 所实现的完整 durable agent 执行语义可直接用于部署审批、人工审核、参数补全等真实场景。【免费下载链接】go-microA Go agent harness and service framework项目地址: https://gitcode.com/gh_mirrors/go/go-micro创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考