5.1 Agents代理系统

Agents（代理）是OpenCode的核心概念，它们是具有特定角色和能力的AI助手。通过配置不同的代理，可以针对不同任务优化AI的行为。

什么是Agents

OpenCode采用多代理架构，包含两类代理：

主代理（Primary Agents）

• Build - 默认的主代理，用于代码构建、编辑和执行任务
• Plan - 规划代理，用于任务规划和架构设计，不直接修改代码

子代理（Sub Agents）

• General - 通用代理，适合一般性任务
• Explore - 探索代理，专注于代码库探索和理解

内置代理介绍

Build代理

默认的主代理，具有完整的工具访问权限：

• 可以读取、编辑、创建文件
• 可以执行shell命令
• 可以搜索代码库
• 适合实际的开发任务

Plan代理

规划代理，只有只读权限：

• 只能读取文件和搜索代码
• 不能修改文件或执行命令
• 适合架构设计和任务规划
• 输出详细的实施计划

Explore代理

代码探索专用：

• 专注于理解代码结构
• 分析依赖关系
• 提供代码解释

代理配置方法

代理可以通过两种方式配置：JSON配置文件或Markdown文件。

JSON配置

在 opencode.json 中配置：

{
  "agent": {
    "myagent": {
      "description": "我的自定义代理",
      "mode": "primary",
      "temperature": 0.7,
      "maxSteps": 100,
      "tools": ["read", "edit", "bash"],
      "permission": {
        "bash": "ask"
      },
      "prompt": "你是一个专注于代码审查的AI助手...",
      "model": "claude-sonnet-4-20250514"
    }
  }
}

Markdown配置

创建 AGENT.md 文件：

---
description: 代码审查专家
mode: primary
temperature: 0.5
maxSteps: 50
tools:
  - read
  - grep
  - glob
permission:
  bash: deny
model: claude-sonnet-4-20250514
---

# 代码审查代理

你是一个专业的代码审查专家。

## 职责

- 检查代码质量
- 发现潜在问题
- 提供改进建议

## 注意事项

- 关注可读性和可维护性
- 检查安全漏洞
- 验证最佳实践

配置选项详解

选项	类型	说明
description	string	代理的简短描述，在代理列表中显示
mode	string	代理模式：primary（主代理）或 sub（子代理）
temperature	number	生成温度，0-2之间，越高越有创造性
maxSteps	number	最大执行步骤数，防止无限循环
tools	array	可用工具列表，如 ["read", "edit", "bash"]
permission	object	工具权限配置，覆盖全局设置
prompt	string	系统提示词，定义代理行为
model	string	使用的模型，覆盖默认模型

创建自定义代理

示例1：安全审计代理

{
  "agent": {
    "security": {
      "description": "安全漏洞检测",
      "mode": "primary",
      "temperature": 0.3,
      "maxSteps": 200,
      "tools": ["read", "grep", "glob", "list"],
      "permission": {
        "bash": "deny",
        "edit": "deny",
        "write": "deny"
      },
      "prompt": "你是安全审计专家，专注于发现代码中的安全漏洞..."
    }
  }
}

示例2：文档生成代理

{
  "agent": {
    "docs": {
      "description": "文档生成助手",
      "mode": "primary",
      "temperature": 0.7,
      "maxSteps": 100,
      "tools": ["read", "write", "glob"],
      "permission": {
        "bash": "deny"
      },
      "prompt": "你是技术文档专家，帮助生成清晰的API文档和README..."
    }
  }
}

示例3：测试生成代理

{
  "agent": {
    "test": {
      "description": "测试用例生成",
      "mode": "primary",
      "temperature": 0.5,
      "maxSteps": 150,
      "tools": ["read", "write", "edit", "bash", "grep"],
      "permission": {
        "bash": "ask"
      },
      "prompt": "你是测试工程师，专注于生成全面的单元测试和集成测试..."
    }
  }
}

切换代理

使用斜杠命令切换主代理：

# 切换到Plan代理
/agent plan

# 切换到自定义代理
/agent security

# 切换回Build代理
/agent build

代理继承

自定义代理可以基于内置代理进行扩展，只需覆盖需要修改的选项：

{
  "agent": {
    "careful-build": {
      "description": "谨慎的构建代理",
      "mode": "primary",
      "permission": {
        "bash": "ask",
        "edit": "ask",
        "write": "ask"
      }
    }
  }
}

下一步

了解如何通过Rules配置文件来定义项目规则和AI行为指南。