📚 课程目录第3章 Agent角色与能力定义

3. Agent角色与能力定义

多Agent系统的协作效率直接取决于角色划分的合理性与能力描述的精确度。本章围绕角色设计原则、能力注册与描述、工具调用接口规范三条主线，建立从职责抽象到接口暴露的标准化路径，为后续任务编排打下结构基础。

3.1 角色设计原则

角色（Role）是Agent职责与行为边界的逻辑封装。良好的角色设计应遵循四项核心原则：

单一职责：每个角色只负责一个业务领域的能力集合，避免“万能Agent”导致职责模糊。
最小权限：角色仅持有完成其任务所必需的资源与能力，降低安全风险与误操作概率。
可组合性：角色之间可通过标准化接口灵活组合，支持动态编排与多轮协作。
可观测性：角色的运行状态、能力调用记录必须可监控、可追溯，便于调试与审计。

原则	关键约束	违反后果
单一职责	一个角色只对应一个能力域	角色职责膨胀，协作链路混乱
最小权限	只注册任务必需的能力	安全漏洞增多，越权调用风险
可组合性	能力输入输出满足统一Schema	编排引擎无法动态匹配Agent
可观测性	能力调用日志结构化输出	故障定位困难，无法性能分析

设计建议：在系统初始阶段，优先按“数据采集→处理→决策→执行”四个基础域划分角色，后续根据业务复杂度逐步拆分。避免一开始就设计过细的角色粒度，否则会增加注册与调度的管理开销。

3.2 能力注册与描述

每个Agent在启动后必须向注册中心声明自身的能力集合。能力描述采用JSON Schema格式，包含能力名称、输入参数、输出结构及语义标签。注册中心维护全局能力目录，供编排引擎在任务分配时查询匹配。

以下是一个典型的能力注册描述示例：

{
  "agent_id": "collector-01",
  "role": "数据采集员",
  "capabilities": [
    {
      "name": "fetch_web_content",
      "description": "抓取指定URL的网页正文",
      "tags": ["web", "html", "scrape"],
      "parameters": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "目标网页URL",
            "example": "https://example.com/data"
          },
          "timeout": {
            "type": "integer",
            "default": 30,
            "minimum": 5,
            "maximum": 120
          },
          "include_metadata": {
            "type": "boolean",
            "default": false
          }
        },
        "required": ["url"]
      },
      "output": {
        "type": "object",
        "properties": {
          "content": { "type": "string" },
          "charset": { "type": "string" },
          "size_bytes": { "type": "integer" }
        }
      }
    }
  ]
}

注册中心在接收到能力声明后会进行校验：检查参数Schema完整性、能力名称唯一性、角色与能力的语义一致性。校验通过后，将能力元数据存入全局目录，并返回注册确认。

  能力描述要点：

  ▪ parameters 必须明确 required 字段，避免编排时缺少必要参数。

  ▪ output 应定义结构化返回，方便下游Agent直接引用字段。

  ▪ tags 字段用于能力发现时的语义检索，建议统一维护标签词典。

3.3 工具调用接口规范

工具调用接口是Agent对外暴露能力的统一边界。本课程采用JSON-RPC 2.0作为基础协议，所有能力调用均通过标准化的请求/响应格式进行。接口规范包含三个部分：

请求格式：指定目标Agent、能力名称、参数列表及调用ID。
成功响应：返回能力执行结果，包含状态码与数据载荷。
错误响应：返回结构化错误信息，包含错误码、消息及可选的诊断数据。

请求示例：

{
  "jsonrpc": "2.0",
  "method": "call_capability",
  "params": {
    "target_agent": "collector-01",
    "capability": "fetch_web_content",
    "arguments": {
      "url": "https://example.com/report",
      "timeout": 15,
      "include_metadata": true
    }
  },
  "id": "req-001"
}

成功响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "status": "success",
    "data": {
      "content": "<html>……</html>",
      "charset": "utf-8",
      "size_bytes": 45230
    }
  },
  "id": "req-001"
}

错误响应示例：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "能力调用失败",
    "data": {
      "reason": "timeout",
      "capability": "fetch_web_content",
      "detail": "目标服务器无响应，超时时间 15s"
    }
  },
  "id": "req-001"
}

接口安全约束：所有工具调用必须携带调用链溯源ID（trace_id），便于审计和问题隔离。错误响应中禁止泄漏堆栈信息或内部网络拓扑，仅返回预定义的业务错误码。

下图总结了从角色设计到能力注册，再到工具调用接口暴露的完整流程：

上图中的箭頭展示了核心流程：角色设计原则同时指导能力注册与能力描述；能力描述Schema为注册提供结构化模板；注册中心与Schema共同产出工具调用接口规范；执行引擎基于规范调度Agent完成任务。三者环环相扣，缺一不可。

本章小结

角色设计需遵循单一职责、最小权限、可组合性、可观测性四项原则，避免职责过重或边界模糊。
能力注册使用JSON Schema描述输入输出，注册中心负责校验、存储与发现。
工具调用接口采用JSON-RPC 2.0协议，统一请求/成功响应/错误响应三种消息格式，保证调用链路可追溯。