自定义代理定义与模型覆盖

创建 Markdown 代理，配置工具、执行限制及持久覆盖。

本地代理放在 .gemini/agents/*.md 或 ~/.gemini/agents/*.md。文件以 YAML frontmatter 开始，Markdown 正文成为该代理的系统提示。

定义格式

---
name: code-auditor
description: Review specified code for correctness and report actionable issues.
kind: local
tools:
  - read_file
  - grep_search
model: inherit
temperature: 0.2
max_turns: 10
---

Read the requested code and report verified issues with supporting evidence.
Do not edit files.

这是按官方字段整理的示例。只读要求既写在提示，也以工具列表缩小能力；真正执行仍受策略和环境约束。

字段与默认值

字段	要求或默认
`name`	必填，仅小写字母、数字、连字符、下划线
`description`	必填，供主 Agent 判断何时调用
`kind`	默认 local，也可 remote
`tools`	可选；省略继承父会话全部工具
`mcpServers`	可选，代理专用 MCP 配置
`model`	默认 inherit
`temperature`	默认 1，范围 0–2
`max_turns`	默认 30
`timeout_mins`	默认 10

省略 tools 并不是“没有工具”。需要受限代理时显式列出，避免只靠正文声明。

持久覆盖

{
  "agents": {
    "overrides": {
      "code-auditor": {
        "enabled": true,
        "runConfig": {
          "maxTurns": 20,
          "maxTimeMinutes": 10
        }
      }
    }
  }
}

定义文件使用 max_turns/timeout_mins，settings 覆盖使用 runConfig.maxTurns/maxTimeMinutes，拼写不同。modelConfig.model 可覆盖模型；主会话选择不等于覆盖所有代理。

模型专用参数

modelConfigs.overrides 可用 match.overrideScope 指定代理名称，再在 modelConfig.generateContentConfig 配置温度等。不要把这个匹配层写成定义文件 frontmatter 的 temperature 键。

发现与调试

修改后 /agents reload 再检查列表。描述应明确领域、触发条件和例子；只增加工具并不让主模型知道何时委派。单独确认工具权限、模型可用性和执行限制，避免把“发现成功”当成任务已可完成。