script-build-and-framework-tmp/agent/agent/docs/presets.md

Agent Preset 与角色边界

agent_type 表示使用哪套具体 preset，role 表示框架安全边界。调用方不能在 RunConfig 里直接声明 role；Runner 始终从 preset 解析。

内置 preset：

preset	role	用途
default、delegate、explore、evaluate	legacy	兼容旧运行方式
planner	planner	规划、派发和决策
worker	worker	执行一个 TaskSpec 并提交 Attempt
validator	validator	只读评估固定 Snapshot

自定义显式 preset 必须声明 role。例如给 Validator 增加业务只读查询工具：

{
  "my_validator": {
    "role": "validator",
    "allowed_tools": ["read_file", "grep_content", "lookup_readonly", "submit_validation"],
    "denied_tools": ["write_file", "edit_file", "bash_command"],
    "max_iterations": 30,
    "temperature": 0,
    "skills": []
  }
}

Host 注册给 explicit-validation 角色的工具还必须通过 @tool(capabilities=[...]) 或 ToolRegistry.register(..., capabilities=[...]) 声明安全副作用。未分类工具在 explicit 模式中 fail-closed，但在 legacy_auto 中保持原行为。

核心 capability：read、write、agent_spawn、external_send、task_control、attempt_submit、validation_submit。一个工具可以同时声明多个 capability，只要其中一个超过当前角色上限，Schema 和执行层都会拒绝。

有效工具集合按以下顺序计算：RunConfig 候选工具，与 preset 白名单取交集，再减去 preset、RunConfig 和 role 的禁用项。Schema 生成和真实执行前都会执行相同授权检查，因此模型伪造未授权 Tool Call 也不会进入工具函数。

legacy_auto 继续使用原来的 tools/tool_groups 并集算法，但 V1 orchestration 工具不会出现在 legacy Schema 中。