PhyAgentOS Forge统一Tool API详解Query、Action与Session生命周期完全指南【免费下载链接】PhyAgentOS-corePhyAgentOS is a Recursive Self-Improving (RSI) physical agent operating system that enables agents to recursively self-improve through agentic workflows.项目地址: https://gitcode.com/gh_mirrors/ph/PhyAgentOS-corePhyAgentOS Forge 统一 Tool API 是机器人物理执行的核心通道。本文面向新手用最少代码讲清 PhyAgentOS Forge Tool API 的三大语义Query、Action、Session、13 个 Agent 工具、身份关联与 AgentTask 生命周期帮你快速理解如何安全地让 AI 指挥机器人干活。一条物理执行平面所有调用走同一条路PhyAgentOSPAOS对物理世界的控制只有一条执行链不存在暗门绑定 AgentTask 的调用 / 诊断 Query → ForgeToolClient → Gateway /tools → ToolInvocation → ToolEndpoint → Dora 与机器人节点三个关键设计对新手最友好只认两个路由所有能力都通过/tools与/invocations完成不再调用旧式/agent/sessions、/policy/commandGateway 是执行所有者AgentTask 只聚合用户目标真正指挥机器人的是 Gateway并发由端点裁决所选 Endpoint operation 的max_concurrency决定并发上限PAOS 不额外引入跨 Tool 资源租约。执行链的客户端实现见 tool_client.py完整契约见 docs/forge/README_zh.md。三种 Tool 语义先选对工具类型每个 Forge Tool 的 ToolSpec 会声明query | action | session三种语义之一。调用前PAOS 会实时读取 ToolSpec 和 contextGET /tools、GET /tools/{tool_id}、GET /tools/{tool_id}/context调用方不能猜测坐标系、单位、就绪状态或绑定关系。语义行为特点是否需要 AgentTaskQuery同步只读查询HTTP 200 直接返回数据可选诊断可不建任务Action异步动作202 受理后靠对账读取结果必须绑定Session长期会话无 deadline需显式所有权必须绑定ToolSpec 还声明严格的输入/输出 schema、readiness 与机器人 frame profile相当于给每个工具上户口避免 AI 用错工具。Query 契约同步只读最安全的第一步forge_tool_query会先读取配置的 ToolSpec 并确认semanticsquery再调用POST /tools/{endpoint_id}/{operation}:invoke。成功响应为 HTTP 200 加{ ok: true, data: { ... } }见 Query 契约。对新手最重要的两点caller_id 由 PAOS 生成形如paos:task-or-diagnostic-identity用于幂等与关联你不需要自己编造两种用法绑定任务的 Query 会在当前 PlanRevision 下创建一条终态 ToolExecutionRecord参与任务验证与审计不带任务的 Query 是诊断模式返回相同 Gateway 数据但不做任务归因适合排障时快速看看机器人现在什么状态。对应封装见 forge_tool_api.py 中的ForgeToolQueryTool。Action 生命周期202 受理 ≠ 完成这是新手最容易踩坑的地方。Action 分两步走第一步受理AdmissionPOST /tools/{tool_id}:invoke → HTTP 202 → data.invocation_id data.attempt_id拿到invocation_id只表示Gateway 接受了这个动作不是执行完成更不是任务成功。第二步对账ReconciliationGET /invocations/{invocation_id} 查状态 GET /invocations/{invocation_id}/result 查结果202 表示仍在进行 POST /invocations/{invocation_id}/cancel 请求取消几条必须记住的安全规则见 Action 契约⚠️取消被接受 ≠ 物理停止。Cancel 返回 200/202 只说明取消请求已处理或接受不能宣称动作已停⚠️超时 远端状态未知不能当失败处理更不能盲目重试 POST✅ PAOS 在受理前就把 Action 意图和生成的 caller ID持久化落盘出现unknown终态时恢复只能凭已持久化的 invocation ID 去查询绝不重复发请求。这套先记账、再执行、凭 ID 对账的机制保证了网络抖动也不会让机器人收到重复指令。Session 生命周期长会话与所有权模型Session 面向需要持续交互的场景如持续控制、远程会话。它与 Action 走同一个受理路由返回 202 加 invocation ID但刻意不设 deadline状态与结果同样走/invocations/{id}停止则用POST /invocations/{id}/stop。Session 的关键概念是所有权ownershipPAOS 记录为三种所有权含义停止规则task归属当前 AgentTask只有本任务可停止非终态 task-owned Session 会阻止任务 finalizeshared共享会话可跨任务 finalize 继续存活runtimeRuntime 所有由 Agent 外部管理Agent 不能动此外Runtime 正常停止时会清点所有活动 Session——存在被追踪的非终态 invocation、Session 或 task binding 时正常 stop 会被拒绝force stop 只记审计事件不改变执行事实。封装代码见 forge_tool_api.py 的 Session 工具组。AgentTask 状态机任务如何走向终态Action 与 Session 必须绑定一个 AgentTask。任务创建时会冻结 Skill 版本、Runtime 身份、manifest/工作流 hash 与 ToolSpec hashbinding之后的每次执行都会复核这些快照。任务状态流转如下见 AgentTask 模型executing ├─ finalize → succeeded | failed ├─ recovery verdict → awaiting_replan → begin_revision → executing └─ cancel → cancelling → reconcile → finalize → cancelled | failed全局最多一个非终态 AgentTask诊断 Query 不占槽位任务包含只追加的 PlanRevision 列表恢复规划recovery revision复用同一个 task ID且受重规划次数与 deadline 限制Tool record 一旦终结后续 observation 不会改写执行事实。七个 ID 各司其职身份与关联PAOS 与 Gateway 的身份刻意分成两组互不派生、不互为别名完整表格见 Binding、Identity 与关联身份所有者作用task_id/revision_id/binding_id/record_id/caller_idPAOS任务聚合、规划世代、绑定快照、执行记录、幂等相关invocation_id/attempt_idGateway异步 Action/Session 生命周期、执行尝试关联必须显式保存Agent 侧工具如forge_tool_action_status在读取 Gateway 状态前会先校验该 invocation 确实属于本 task防止跨任务越权读取。证据采集与聚合验证任务成功前最后一道关PAOS 会在第一次绑定 Action 之前和所有绑定 Action 达到终态之后做 best-effort 证据采集前后 snapshot含 SHA-256 指纹采集错误会被显式记录而不是隐藏。forge_task_finalize聚合全部绑定 Tool facts 后按任务契约判定四种模式off直接采用执行派生结果audit记录语义判定但结果仍以执行为准enforce语义判定决定成败失败关闭fail closedrecovery在 enforce 基础上允许有预算的replan_required重规划。简单说Forge ToolResult 对执行发生了什么负责PAOS 验证器只回答用户任务完成了没有。13 个 Agent 工具速查表 ️工具用途forge_tool_context读取 ToolSpec 与实时 context无 Runtime 也可用forge_tool_query同步 Query可诊断或绑定 task_idforge_tool_start_action为绑定任务受理异步 Actionforge_tool_action_status/forge_tool_action_result读取 invocation 状态 / pending 或终态结果forge_tool_cancel_action请求取消不宣称已停止forge_tool_start_session以显式 ownership 受理绑定 Sessionforge_tool_session_status/forge_tool_session_result/forge_tool_stop_session核对、读取或停止有所有权的 Sessionforge_task_create创建唯一活动 AgentTask 与 revision 1见 forge_task.pyforge_task_get读取 task、revisions、Tool records、evidence 与 verdictforge_task_begin_revision恢复判定后追加新 revisionforge_task_finalize后置证据采集并执行聚合验证forge_task_cancel取消非终态 Action停止 task-owned Session受治理的 Forge 工具要求恰好一个健康的活动 Skill Runtime其 manifest 是 Gateway URL 的唯一来源。PhyAgentOS 分发包不包含具体 Forge Skill、Node、模型或仿真资源需要时由部署者通过paos skill显式安装manifest v2 SHA-256 清单 原子替换。常见问题速答QAction 返回超时了能直接重试吗不能。超时意味着远端状态未知只能凭已持久化的invocation_id查询对账盲目重复 POST 可能触发重复物理动作。Q诊断 Query 一定要建任务吗不需要。forge_tool_query不带 task_id 时即为诊断模式适合快速查看传感器读数、就绪状态等。Q任务失败了会自动重试吗只有验证契约为recovery时验证器给出replan_required判定后才会在同一 task上追加有预算的 PlanRevision且受maxReplansPerEpisode与 deadline 约束详见 docs/zh/04-forge-configuration-reference.md。延伸阅读接入契约中英对照docs/forge/README_zh.md · docs/forge/UNIFIED_TOOL_API.md配置参考请求超时、轮询间隔、证据采集、验证预算docs/zh/04-forge-configuration-reference.md客户端与 Agent 工具源码PhyAgentOS/forge/ · PhyAgentOS/agent/tools/forge_tool_api.py框架介绍docs/zh/01-framework-introduction.md【免费下载链接】PhyAgentOS-corePhyAgentOS is a Recursive Self-Improving (RSI) physical agent operating system that enables agents to recursively self-improve through agentic workflows.项目地址: https://gitcode.com/gh_mirrors/ph/PhyAgentOS-core创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考