agents/ 角色目录

agents/ 目录存放 worker/subagent 定义。推荐使用 .a3s/agents/ 作为 A3S 原生位置；迁移项目可以继续读取 .claude/agents/，但新文档和新项目应优先使用 .a3s/agents/。

Text

repo/
└── .a3s/
    └── agents/
        ├── explorer.md
        ├── security-reviewer.md
        └── verification-runner.md

这些文件不是主 Agent 目录。它们会被 task、parallel_task、session.task(...)、session.tasks(...) 或 autoDelegation 调用，父 session 仍负责最终汇总、验证和权限边界。

Agent 文件格式

Markdown

---
name: security-reviewer
description: Use for permission, secret, and external side-effect review
tools: Read, Grep, Glob, Bash(rg *)
disallowedTools:
  - Write
  - Bash(git push *)
---

Review security risks first. Return blockers, evidence paths, and required verification.

name 是调用名，description 决定自动委派时是否匹配，正文是该 worker 的角色说明。工具字段收窄 worker 可见能力；不要依赖 worker 自己“承诺不做危险事”。

手动委派

TypeScript

const session = agent.session('/repo', {
  agentDirs: ['./.a3s/agents'],
  maxParallelTasks: 4,
});

await session.task({
  agent: 'security-reviewer',
  description: 'Review release side effects',
  prompt: 'Check changed auth, permission, and external API paths.',
});

固定流程更适合手动委派或可编程编排；自动委派适合“父 Agent 读到目标后自行选择专家”的场景。

自动委派

TypeScript

const session = agent.session('/repo', {
  agentDirs: ['./.a3s/agents'],
  autoDelegation: { enabled: true, minConfidence: 0.72, maxTasks: 4 },
});

自动委派依赖 agent 描述和置信度评分。写 description 时要说清楚“何时使用”，而不是只写角色口号。

最佳实践

一个文件只做一个角色，避免“万能 reviewer”。
description 面向路由，正文面向执行。
worker 输出应包含证据、风险和建议下一步，方便父 session 汇总。
高权限动作留给父 session 或显式工具，不要让子 Agent 默认获得发布、删除、推送权限。
需要动态创建的一次性 worker，用 workerAgents 或 registerWorkerAgent()，不用落盘。

#agents/ 角色目录

#Agent 文件格式

#手动委派

#自动委派

#最佳实践

agents/ 角色目录

Agent 文件格式

手动委派

自动委派

最佳实践