#子代理

Agent 工具把大型或上下文密集的子任务委派给运行在隔离会话中的子代理：每个子代理只能看到你传给它的 prompt（永远看不到父会话），并且只返回最终文本。隔离保证了父会话上下文的干净——你拿到答案，却不必为产生答案的探索过程付出上下文。

#声明子代理

一个子代理就是一个带 YAML frontmatter 的 agents/*.md 文件；正文即子代理的系统提示：

---
name: researcher
description: Research a topic and report findings with sources
tools: [read_file, bash]   # optional allow-list; absent = inherit the parent's tools
model: simple              # 可选：配置的档位或 raw model id 覆盖
---

You are a research agent. Always cite your sources ...

加载顺序（同名时后加载的目录覆盖先加载的）：

1. 全局：~/.lite-agent/agents
2. 项目：<workdir>/.lite-agent/agents
3. 配置项 agentsDir（如设置）

内置的 general-purpose 代理（继承父代理的全部工具与模型）总是可用，因此零配置文件也能用子代理。设 agents: false 可整体关闭该能力。

#模型选择

配置了 models catalog 后，可以在 definition 或单个任务中选择 simple、medium、complex。选择顺序固定为：

task.model -> 子代理 definition 的 model -> 当前/默认档位

例如，definition 中的 simple 会被此任务中的 complex 覆盖：

{
  "tasks": [{
    "display_name": "架构审查",
    "subagent_type": "researcher",
    "model": "complex",
    "prompt": "比较两个跨包设计"
  }]
}

配置 catalog 后，工具调用和子代理 definition 只能选择已配置档位；未知模型名会被拒绝。未配置 catalog 时，旧的 raw model 覆盖仍使用继承的 provider。主 Agent 的工具 schema 和说明会展示可用档位。

档位支持 reasoningEffort: "low" | "medium" | "high"。OpenAI 兼容 provider 发送 reasoning_effort；Anthropic 启用 adaptive thinking 和 output_config.effort。需要使用支持这些参数的模型；不支持时报告 provider 错误，不自动升级模型。推理配置不能与 temperature/topP 同时设置；Anthropic adaptive thinking 也不支持强制工具选择。权限和并发保持独立。

默认提示会引导模型处理明确的委派请求和独立复杂工作，但自动调用工具仍由模型决定，配置档位本身不保证触发派发。

#派发

每次 Agent 调用都会创建一个同级组。每个任务必须提供非空、可见的 display_name：它是本次调用在 UI 和结果中的名称。subagent_type 只用于选择 AgentLoader definition；返回的 agentId 则是稳定的运行身份，之后可作为 resume 继续该子代理。

长期 createLiteAgent() 会话中的组一律 detached。工具会立即返回“已接受组”的 占位结果；仅在所有 child settle 后，会话才收到一次、按输入顺序排列的聚合 completion。旧的 run_in_background 字段仍可解析，但不再改变语义；即使传入 run_in_background: false 也不会使组同步。只有在希望 Agent 派发明确失败、而非 创建后台任务时，才设置 background: false。

根 agent 持有一个共享 FIFO pool。maxParallelSubagents 默认是 5，且由同一根 实例的所有 session/group 共用，因此两个各含三个任务的组不会各自获得五个 child 槽位。结果保持任务输入顺序：全成功才是 completed；混合结果为 partial；全部 失败或取消分别为 failed、cancelled。child 抛异常、被取消、达到 max_turns， 或停止却没有最终文本时，绝不会伪装成成功。

例如，可以用两次调用提交两个各含三个任务的组：

{
  "tasks": [
    { "display_name": "架构调研", "subagent_type": "researcher", "prompt": "比较 Rspress 和 VitePress" },
    { "display_name": "依赖审计", "subagent_type": "general-purpose", "prompt": "审计依赖中的漏洞" },
    { "display_name": "测试计划", "subagent_type": "general-purpose", "prompt": "起草回归测试" }
  ]
}

{
  "tasks": [
    { "display_name": "API 审查", "subagent_type": "reviewer", "prompt": "审查公开 API" },
    { "display_name": "文档审查", "subagent_type": "writer", "prompt": "找出迁移缺口" },
    { "display_name": "安全审查", "subagent_type": "general-purpose", "prompt": "审查安全假设" }
  ]
}

某个组混合完成时，只会在组 settle 后送达一次：

<background-task-completed id="bg_…" label="Subagent group: 架构调研, 依赖审计, 测试计划" status="partial">
## 架构调研 (agentId: agent-researcher-…; status: completed)
…最终文本…

## 依赖审计 (agentId: agent-general-purpose-…; status: failed)
Error: Subagent reached max turns
</background-task-completed>

长期交互请用 createLiteAgent() 配合 subscribe() / close()：同一 session 的用户 轮次和自主 completion 轮次会串行，订阅可收到 child 与聚合事件。query() 是一次性 API：关闭临时 agent 前会等待自己发起的 Agent groups 及其自主 completion，不会等待 不相关的 detached daemon（例如后台 Bash）。

child 使用 agents: false；不支持递归子代理、Agent Teams、消息总线和共享收件箱。

子代理继承父级权限和工具白名单；subagentPermission 与 definition 的 tools 只能进一步收紧。父子代理共用串行审批队列，没有处理器时拒绝 ask。

启用任务后，派发会自动创建可追踪任务；传入 task_id 可以关联已有任务。子代理成功后进入 review，失败和取消保留对应状态。检查结果后再标记 completed。

#编程式访问

如需在 createLiteAgent 之外使用同一套加载机制，可直接使用 AgentLoader / builtinAgents。

#另请参阅

• 内置工具——Agent 工具说明及如何禁用（agents: false）。
• Skills——另一个由 Markdown 驱动、按需加载的能力。
• 权限——编写 subagentPermission 所需的 allow/deny 规则。
• 自定义工具——添加可被子代理继承的工具。