---
title: "自定义 Agent"
description: "用 Markdown 文件定义自己的 Agent。理解 Agent 定义的数据模型、工具过滤策略和与 AgentTool 的联动。"
keywords: ["自定义 Agent", "Agent 定义", "Markdown Agent", "角色定制"]
---

## 核心概念

自定义 Agent 是一个 Markdown 文件——frontmatter 定义配置，正文是 system prompt。不需要写代码。

```markdown
---
name: "reviewer"
description: "Code review specialist"
tools: "Read,Glob,Grep"
model: "haiku"
---

你是代码审查专家。你的职责是...
```

这个 Markdown 文件就定义了一个完整的 Agent：它使用什么工具、什么模型、什么行为规则。

## Agent 的三种来源

| 来源 | 位置 | 优先级 |
|------|------|--------|
| **Built-in** | 硬编码 | 最低（可被覆盖） |
| **Plugin** | 插件系统注册 | 中 |
| **User/Project** | `.claude/agents/*.md` | 最高 |

合并时按 `agentType` 去重，后者覆盖前者。这意味着你可以在 `.claude/agents/` 中放一个 `Explore.md` 来完全替换内置的 Explore Agent。

## 配置字段

### 工具控制

- `tools` — 允许的工具白名单（未指定 = 全部工具）
- `disallowedTools` — 显式禁止的工具（即使 `tools` 未指定也生效）

**设计考量**：`disallowedTools` 是比 `tools` 更安全的控制方式。如果只指定 `tools` 白名单，新增工具时需要更新白名单。`disallowedTools` 是黑名单思维——默认允许，只禁止危险的。

### 模型配置

- `model` — 指定模型（`haiku`/`sonnet`/`opus`/`inherit`）
- `effort` — 推理努力程度（`low`/`medium`/`high`）

`inherit` 使用主线程的模型——适合需要完整推理能力的任务。`haiku` 适合轻量任务（如搜索），更便宜更快。

### 行为控制

- `maxTurns` — 最大 agentic 轮次（防止无限循环）
- `permissionMode` — 权限模式（`plan`/`bypassPermissions` 等）
- `background` — 始终作为后台任务运行
- `isolation` — 在独立 worktree 中运行

### 持久化

- `memory` — 启用跨会话的持久记忆（`user`/`project`/`local`）
- `mcpServers` — 引用或内联定义 MCP 服务器
- `hooks` — Agent 专属的 Hook 配置
- `skills` — 预加载的技能

## System Prompt 的注入方式

Agent 的 Markdown 正文**完全替换**默认的 system prompt，而非追加。这意味着自定义 Agent 的行为完全由你定义——不受默认 prompt 的约束。

如果启用了 `memory`，记忆指令自动追加到 system prompt 末尾。

## 工具过滤流程

```
全部工具 → disallowedTools 移除 → tools 白名单过滤 → 可用工具
```

内置 Explore Agent 的工具限制是很好的例子：
- 禁止 `Agent`（不能嵌套调用子 Agent）
- 禁止 `FileEdit`/`FileWrite`（只读）
- 禁止 `ExitPlanMode`（不需要 plan mode）

这些限制让 Explore Agent 成为一个纯粹的搜索工具——它只能看，不能改。

## 与 AgentTool 的联动

当主 Agent 需要派生子 Agent 时：

```
查找 Agent 定义 → 检查 MCP 依赖 → 过滤工具 → 解析模型 → 构建隔离环境 → 注入 system prompt → 启动子 Agent
```

每一步都使用 Agent 定义中的配置——工具列表、模型选择、权限模式、隔离环境等。

## 内置 Agent 参考

| Agent | 角色 | 工具限制 | 模型 |
|-------|------|---------|------|
| General Purpose | 通用任务 | 全部工具 | 继承主线程 |
| Explore | 代码搜索 | 只读 | haiku |
| Plan | 规划研究 | 只读 + ExitPlanMode | 继承主线程 |
| Verification | 结果验证 | 由 feature flag 控制 | — |
| Code Guide | 使用指南 | 只读 | — |

## 接下来

- **子 Agent** — 理解子 Agent 的完整执行链路
- **Skills** — 理解 Skill 中指定 Agent 定义
- **MCP 配置** — 理解 Agent 中引用 MCP 服务器