Agent 系统快速参考

快速入门

1. 核心概念速查

概念	说明	源码位置
Agent.Info	Agent 配置结构体	src/agent/agent.ts:23
Agent.get(name)	获取指定 Agent	src/agent/agent.ts:251
Agent.list()	列出所有 Agent	src/agent/agent.ts:255
Agent.defaultAgent()	获取默认主 Agent	src/agent/agent.ts:264
SessionPrompt.prompt()	发起一次对话	src/session/prompt.ts:195
SessionPrompt.loop()	主处理循环	src/session/prompt.ts:305
TaskTool	子 Agent 调用工具	src/tool/task.ts:23
PermissionNext	权限系统	src/permission/next.ts:13

2. Agent 模式速查

// Agent 有三种模式
mode: "primary"   // 主 Agent - 处理用户主对话
mode: "subagent"  // 子 Agent - 被 TaskTool 调用
mode: "all"       // 通用 - 两者皆可

// 内置 Agent
Agent.build      // 默认主 Agent
Agent.plan       // 计划模式
Agent.explore    // 代码探索子 Agent
Agent.general    // 通用任务子 Agent
Agent.compaction // 上下文压缩（隐藏）
Agent.title      // 标题生成（隐藏）
Agent.summary    // 摘要生成（隐藏）

3. 权限 Action

action: "allow"  // 直接执行
action: "ask"   // 询问用户
action: "deny"  // 拒绝执行

---

常见操作

创建自定义 Agent（opencode.json）

{
  "agent": {
    "my-agent": {
      "description": "我的自定义 Agent",
      "mode": "primary",
      "model": "anthropic/claude-3-5-sonnet",
      "temperature": 0.7,
      "steps": 30,
      "permission": {
        "*": "allow",
        "bash": "ask",
        "external_directory": "deny"
      }
    }
  }
}

创建子 Agent

{
  "agent": {
    "reviewer": {
      "description": "代码审查专家",
      "mode": "subagent",
      "permission": {
        "read": "allow",
        "grep": "allow",
        "*": "deny"
      }
    }
  }
}

调用子 Agent（TaskTool）

@reviewer 请帮我审查 src/auth/login.ts 文件

或通过命令：

// 内部会创建 SubtaskPart，触发 TaskTool
parts: [{
  type: "subtask",
  agent: "reviewer",
  prompt: "请帮我审查...",
  description: "代码审查"
}]

---

源码速查

Agent 定义模板

// src/agent/agent.ts
export namespace Agent {
  const state = Instance.state(async () => {
    const result: Record<string, Info> = {
      myAgent: {
        name: "myAgent",
        description: "描述",
        mode: "primary" | "subagent" | "all",
        native: true,
        permission: PermissionNext.merge(
          defaults,
          PermissionNext.fromConfig({ /* 权限配置 */ }),
          user
        ),
        options: {},
      }
    }
    return result
  })
}

TaskTool 调用子 Agent

// src/tool/task.ts
const result = await SessionPrompt.prompt({
  sessionID: session.id,      // 子会话 ID
  agent: agent.name,          // 子 Agent 名称
  model: { /* 模型配置 */ },
  tools: { task: false },     // 禁用递归
  parts: promptParts,
})

权限检查

// src/permission/next.ts
const action = PermissionNext.evaluate(
  "bash",           // 权限名称
  "/tmp/test.sh",   // 模式
  agent.permission,
  session.permission
)

if (action === "deny") throw new DeniedError(...)
if (action === "ask") await ctx.ask({ ... })
// action === "allow" 直接执行

会话循环

// src/session/prompt.ts
export const loop = fn(Identifier.schema("session"), async (sessionID) => {
  while (true) {
    // 1. 加载消息
    const msgs = await MessageV2.filterCompact(MessageV2.stream(sessionID))

    // 2. 处理 subtask
    const task = tasks.pop()
    if (task?.type === "subtask") {
      await executeSubtask(task)
      continue
    }

    // 3. 正常处理
    const result = await processor.process({ ... })
    if (result === "stop") break
  }
})

---

调试技巧

查看当前 Agent

const agent = await Agent.get(session.agent)
console.log(agent.name, agent.mode, agent.permission)

查看可用工具

const tools = await ToolRegistry.tools({ modelID, providerID }, agent)
console.log(tools.map(t => t.id))

模拟权限检查

const action = PermissionNext.evaluate("bash", "/tmp/test", agent.permission)
console.log(`bash 权限: ${action}`)

---

错误处理

错误类型	说明	处理
DeniedError	权限被拒绝	规则配置问题
RejectedError	用户拒绝	正常流程
CorrectedError	用户拒绝但有建议	采纳建议
Session.BusyError	会话忙碌中	等待或取消

---

关键文件速查

src/agent/agent.ts          # Agent 定义
src/session/prompt.ts       # 会话循环
src/session/processor.ts    # LLM 响应处理
src/tool/task.ts            # 子 Agent 调用
src/permission/next.ts      # 权限系统
src/config/config.ts        # 配置加载
src/session/message-v2.ts   # 消息结构
src/tool/registry.ts        # 工具注册

---

快速参考版本: 1.0 更新时间: 2026-03-28