V1 任务执行与独立验证

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

Planner -> Task -> Worker Attempt -> Artifact Snapshot
        -> independent Validator -> Planner Decision

两种完成策略

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

显式模式的状态由 TaskLedger 决定。GoalTree 只用于兼容展示；二者不一致时可调用 TaskCoordinator.reconcile_goal_tree() 修复 Goal 投影。

最小装配

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,
)

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：创建顶层/子 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 是唯一可以改变任务树和作出完成决策的角色。
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。
子 Task 全部完成后，父 Task 进入 needs_replan，不会自动完成。

存储与扩展点

默认目录：

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

TaskStore、ArtifactStore、AgentExecutor、ToolPolicy、EventSink 都是端口。V2 可增加远程执行器和公开 API，V3 可增加队列与分布式 Store，而不改变 Task 状态机和 Coordinator 决策语义。

V1 限制

显式闭环只支持本地 Sub-Trace；远程 Agent 继续使用 legacy_auto。
没有 Task/Attempt/Validation HTTP API。
默认 Store 只保证单进程内并发安全；跨进程/分布式调度不在 V1 范围。

orchestration-v1.md 4.2 KB Historia Raaka