V1 任务执行与独立验证

V1 提供一套与具体业务无关的显式任务闭环：主 Agent 负责规划和决策，Worker 只执行，Validator 只评估。Worker 或 Validator 的 Trace 结束都不等于 Task 完成。

Planner -> Root Task -> Child Task -> Worker Attempt -> Artifact Snapshot
        -> independent Validator -> Planner Decision -> Root replan
        -> Root Attempt -> Root Validation -> Planner accepts Root

两种完成策略

legacy_auto：默认值。保留原有 agent、evaluate、goal 和 Goal 父节点级联语义。
explicit_validation：启用 V1。只能配合带 planner、worker、validator role 的 preset 使用，且必须先装配 TaskCoordinator。

legacy_auto 与 explicit_validation 的计划模型彻底隔离：legacy 使用 GoalTree，explicit 只使用 TaskLedger，不创建、读取或维护 Goal 投影。显式模式的当前计划和可视化都应读取 Ledger 视图；get_current_context 会由 Coordinator 生成紧凑的 Task 摘要。基于已完成 Goal 的 Level 1 压缩仅在 legacy 模式执行，explicit 保留 Level 2 LLM 总结。

最小装配

from agent import (
    AgentRunner,
    FileSystemTraceStore,
    FileSystemTaskStore,
    FileSystemArtifactStore,
    OrchestrationConfig,
    wire_orchestration,
)

trace_store = FileSystemTraceStore(".trace")
runner = AgentRunner(trace_store=trace_store, llm_call=my_llm_call)

coordinator = wire_orchestration(
    runner,
    FileSystemTaskStore(".trace"),
    FileSystemArtifactStore(".trace"),
    OrchestrationConfig(max_parallel_tasks=4),
)

主 Agent 使用：

from agent import CompletionPolicy, RunConfig

config = RunConfig(
    agent_type="planner",
    completion_policy=CompletionPolicy.EXPLICIT_VALIDATION,
    tool_groups=None,
    root_task_spec={
        "objective": "完成调用方定义的任务",
        "acceptance_criteria": [
            {
                "criterion_id": "mission-complete",
                "description": "任务整体结果满足调用方定义的验收要求",
                "hard": True,
            }
        ],
    },
)

result = await runner.run_result(
    [{"role": "user", "content": "根据目标制定任务树并执行；每个任务必须独立验证。"}],
    config,
)

通过 invoke_agent() 启动本地项目时，如果项目 RUN_CONFIG 使用 explicit_validation，SDK 会用项目的 TRACE_STORE_PATH 自动装配文件 Store。项目可以在 config.py 暴露 ORCHESTRATION_CONFIG 覆盖并行度和 preset 名称。

Agent 工具

Planner：

task_plan：检查 Ledger、创建 Root 的子 Task、插入同级 Task、切换焦点。
dispatch_tasks：运行一个或多个互相隔离的 Worker→Validator 闭环。
task_decide：执行 accept、repair、retry、revise、split、block、unblock、cancel、supersede。
validate_attempt：仅在 Validator error、stopped、expired 后，对未变化的 Snapshot 发起新 Validator Trace。

Worker 只能使用 submit_attempt 正式交付。Validator 只能使用 submit_validation 正式提交结构化报告。二者都是 terminal tool：结果会先写入 Trace，然后结束当前 Agent Loop。

关键不变量

Planner 是唯一可以改变任务树和作出完成决策的角色。
Ledger 中只有一个特殊 Root Task；调用方提供它的 objective 和验收标准，框架不生成业务验收语义。
普通顶层 Task 默认挂在 Root 下；所有直接子 Task 终态后，父 Task 回到 needs_replan，不会自动完成。
父 Attempt 创建时会按直接子 Task 的 display_path 冻结 ACCEPT Decision ID；父 Worker 只解析这组不可变绑定，不扫描后续“最新状态”。旧 RUNNING Attempt 没有该绑定时按协议失败并重新规划。
Worker 看不到且不能执行 agent、evaluate、goal 或 Planner/Validator 工具。
Validator 使用独立 Trace，只能访问 preset 明确允许的只读工具。
explicit 模式的工具必须声明 capability；未分类工具默认拒绝。Validator 仅允许 read + validation_submit，Worker 不允许 agent_spawn 和 task_control。
Worker 未调用 submit_attempt，Attempt 失败，Task 进入 needs_replan。
Validator 未调用 submit_validation，Validation 状态为 error，不是业务 failed。
passed 只让 Task 进入 awaiting_decision；只有 Planner 对当前版本、当前 Attempt、当前 Snapshot 执行 accept 才完成。
failed、inconclusive 没有 override 接受入口。
同一 TaskSpec 最多 repair 一次；repair 产生新 Attempt 和 Snapshot，但续用原 Worker Trace。retry、revise 使用新 Worker Trace。
Root Task 也必须经历 Attempt、独立 Validation 和 Planner accept；只有 Root completed 才允许 Planner Trace completed。
Planner 自由文本退出不会绕过 Root；迭代耗尽且 Root 未完成时 Trace 为 incomplete。
TaskSpec 必须有非空 objective 和至少一条 ID 唯一、描述非空的验收标准。
带幂等键的批量 dispatch 在逐 Task 周期完成后，即使整批结果缓存写入失败，也会返回已持久化的逐 Task 结果；重试会复用原 Attempt/Validation，不会重复执行 Agent。幂等键绑定原始 Task 列表和 Worker preset，不能串用于另一批请求。

存储与扩展点

默认目录：

.trace/{root_trace_id}/orchestration/
├── ledger.json
└── artifacts/{snapshot_id}.json

Orchestration Event v2 的 durable journal 位于 ledger.json，是默认唯一真源；只保存变化通知与实体 ID。wire_orchestration(..., event_sink=...) 可以显式注入外部 Sink；TraceEventSink 仅作为兼容镜像适配器，不再默认创建 orchestration/events.jsonl。Trace 自身的消息事件文件不受影响。

通用观测 API

GET /api/v2/roots/{root_trace_id}/snapshot：单次 Ledger load 得到同一 revision 的 Mission 原子视图。
GET /api/v2/roots/{root_trace_id}/completion：Root objective、状态、阻塞原因与结果摘要。
GET /api/v2/roots/{root_trace_id}/snapshots/{snapshot_id}：Artifact 摘要哈希与不可变引用，不重复返回正文。
GET /api/v2/roots/{root_trace_id}/events：支持 v1/v2 混读的稳定 cursor。
GET /api/v2/capabilities：API、Mission Snapshot、Event schema 版本与能力发现。

OrchestrationClient 提供对应的 Mission、Completion、Artifact、Event 读取方法，并可按 role、Root、Task、Attempt、Validation、Operation 或父 Trace 查询关联 Trace。TaskStore、ArtifactStore、AgentExecutor、ToolPolicy、EventSink 都是端口，可增加远程执行器或分布式 Store，而不改变 Task 状态机和 Coordinator 决策语义。

V1 限制

显式闭环只支持本地 Sub-Trace；远程 Agent 继续使用 legacy_auto。
V2 控制 API 可查询和控制已有 Task/Operation，但不负责启动 Planner Run。
默认 Store 只保证单进程内并发安全；跨进程/分布式调度不在 V1 范围。

orchestration-v1.md 7.0 KB Historie Surový