名称: 多智能体可观测性描述: 为多智能体系统构建可观测性接口。用于监控多智能体执行、跟踪代理指标、实现并行代理的日志记录或调试代理工作流。允许工具: Read, Grep, Glob

多智能体可观测性技能

为监控和测量多智能体系统构建可观测性接口。

目的

指导设计和实现可观测性层，以提供多智能体执行的实时可见性。

何时使用

设计代理舰队的监控
构建指标仪表板
实施日志架构
创建成本跟踪系统

先决条件

理解三大支柱（@three-pillars-orchestration.md）
熟悉结果导向模式（@results-oriented-engineering.md）
访问Claude Agent SDK文档

SDK要求

实施说明: 完整的可观测性需要Claude Agent SDK与自定义MCP工具和UI组件。本技能提供设计模式。

关键原则

“如果你不能测量它，你就不能改进它。如果你不能测量它，你就不能扩展它。”

观察内容

每代理指标

指标	目的	如何跟踪
状态	了解状态	代理状态枚举
上下文使用	令牌消耗	API响应
成本	财务影响	API使用数据
工具调用	它在做什么	钩子日志
结果	输出验证	结果解析
持续时间	执行时间	时间戳

聚合指标

指标	目的	计算
总代理数	规模	统计活动代理
总持续时间	端到端时间	第一个到最后一个
总成本	财务总计	每代理求和
成功率	可靠性	成功 / 总数
覆盖率	范围	触及的文件

可观测性组件

1. 代理卡片

每个代理的实时状态：

┌─────────────────────────────────────┐
│ scout_1                 [执行中] │
├─────────────────────────────────────┤
│ 模板: scout-fast                │
│ 模型: haiku                        │
│ 上下文: 12,500 / 100,000 令牌    │
│ 成本: $0.05                         │
│ 持续时间: 45秒                       │
│ 工具调用: 15                      │
└─────────────────────────────────────┘

必填字段:

代理ID和模板
状态（空闲、执行中、完成、错误）
使用的模型
上下文使用（当前 / 最大）
运行成本
执行持续时间
工具调用计数

2. 事件流

所有活动的实时日志：

[10:30:00] scout_1 创建（模板: scout-fast）
[10:30:01] scout_1 命令: “分析身份验证模块”
[10:30:05] scout_1 Read: src/auth/login.ts
[10:30:08] scout_1 Grep: “password” 在 src/auth/
[10:30:15] scout_1 完成（持续时间: 14秒）
[10:30:16] scout_1 删除

事件类型:

代理生命周期（创建、删除）
发送的命令
工具调用
状态更改
错误

3. 成本跟踪

跟踪每个代理和总花费：

成本摘要
────────────────────────────────────
scout_1 (haiku)      $0.05
scout_2 (haiku)      $0.04
builder_1 (sonnet)   $0.35
reviewer_1 (sonnet)  $0.12
────────────────────────────────────
总计                $0.56
剩余预算            $4.44 (89%)

成本组件:

输入令牌
输出令牌
每代理细目
运行总计
预算跟踪

4. 结果检查器

查看消耗和生成的资产：

代理: builder_1

消耗的资产:
├── 侦察报告（摘要）
├── src/auth/middleware.ts
└── package.json

生成的资产:
├── src/auth/rate-limit.ts（创建）
├── src/auth/middleware.ts（修改）
└── tests/rate-limit.test.ts（创建）

摘要: “实施了速率限制中间件”
状态: 完成

5. 日志查看器

可过滤的活动历史：

过滤器: [代理: 全部] [级别: 全部] [工具: 全部]

10:30:00 INFO  scout_1   从模板创建
10:30:01 INFO  scout_1   接收命令
10:30:05 DEBUG scout_1   Read: src/auth/login.ts (1,200 令牌)
10:30:08 DEBUG scout_1   Grep: 找到 5 个匹配项
10:30:12 WARN  scout_1   上下文达到80%容量
10:30:15 INFO  scout_1   成功完成

实施模式

日志架构

# 事件类型
class AgentEvent:
    timestamp: datetime
    agent_id: str
    event_type: str  # 创建、命令、工具、状态、错误
    details: dict

# 日志收集器
def log_event(event: AgentEvent):
    # 存储到数据库
    db.events.insert(event)
    # 通过WebSocket发射
    ws.broadcast(event)
    # 更新指标
    metrics.update(event)

实时更新

# 用于实时更新的WebSocket
async def agent_status_stream(agent_id):
    while agent_active(agent_id):
        status = get_agent_status(agent_id)
        yield status
        await asyncio.sleep(1)

成本计算

def calculate_cost(usage):
    input_cost = usage.input_tokens * MODEL_INPUT_PRICE
    output_cost = usage.output_tokens * MODEL_OUTPUT_PRICE
    return input_cost + output_cost

UI组件

最小CLI视图

编排: 添加速率限制
────────────────────────────────────
代理: 3 活动 | 2 完成 | 0 错误
成本: $0.56 / $5.00 预算
进度: ████████░░ 80%

[scout_1] ✓ 完成 (14秒)
[scout_2] ✓ 完成 (12秒)
[builder] ⚡ 执行中 (45秒)

丰富仪表板视图

┌─────────────────────────────────────────────────────────────┐
│                    编排仪表板                    │
├─────────────────────────────────────────────────────────────┤
│ 任务: 向身份验证添加速率限制                    │
│ 开始: 10:30:00 | 持续时间: 2分 15秒 | 成本: $0.56          │
├─────────────────────────────────────────────────────────────┤
│ 代理舰队                          │ 事件流          │
│ ┌─────────────────────────────────┐  │ [10:32:15] builder   │
│ │ scout_1        [✓ 完成]    │  │   Write: rate-limit  │
│ │ scout_2        [✓ 完成]    │  │ [10:32:10] builder   │
│ │ builder        [⚡ 执行中]   │  │   Read: middleware   │
│ │ reviewer       [○ 待定]     │  │ [10:30:15] scout_2   │
│ └─────────────────────────────────┘  │   完成          │
├─────────────────────────────────────────────────────────────┤
│ 成本细目     │ 结果摘要                         │
│ haiku:  $0.09     │ 读取的文件: 8                           │
│ sonnet: $0.47     │ 写入的文件: 3                        │
│ 总计:  $0.56     │ 测试: 5/5 通过                      │
└─────────────────────────────────────────────────────────────┘

设计检查清单

[ ] 每代理指标定义
[ ] 聚合指标计算
[ ] 事件日志实施
[ ] 通过WebSocket实时更新
[ ] 每代理成本跟踪
[ ] 结果检查可用
[ ] 支持日志过滤
[ ] UI组件设计

输出格式

设计可观测性时，提供：

## 可观测性设计

### 指标

**每代理:**
[列出跟踪方法]

**聚合:**
[列出计算]

### 组件

**代理卡片:** [字段和更新频率]
**事件流:** [事件类型和存储]
**成本跟踪:** [细目和预算]
**结果检查器:** [消耗/生成格式]
**日志查看器:** [过滤器和保留]

### 实施

**日志:** [架构]
**实时:** [WebSocket设计]
**存储:** [数据库模式]
**UI:** [组件规格]

反模式

反模式	问题	解决方案
无指标	盲目飞行	跟踪一切
延迟更新	陈旧状态	实时WebSocket
无成本跟踪	预算超支	每代理成本
缺少日志	无法调试	记录所有事件
无聚合	无法总结	计算总计

交叉引用

@three-pillars-orchestration.md - 可观测性支柱
@results-oriented-engineering.md - 结果模式
@agent-lifecycle-crud.md - 代理状态跟踪
@orchestrator-design skill - 系统架构

版本历史

v1.0.0 (2025-12-26): 初始发布

最后更新

日期: 2025-12-26 模型: claude-opus-4-5-20251101

名称: 多智能体可观测性 描述: 为多智能体系统构建可观测性接口。用于监控多智能体执行、跟踪代理指标、实现并行代理的日志记录或调试代理工作流。 允许工具: Read, Grep, Glob

多智能体可观测性技能

目的

何时使用

先决条件

SDK要求

关键原则

观察内容

每代理指标

聚合指标

可观测性组件

1. 代理卡片

2. 事件流

3. 成本跟踪

4. 结果检查器

5. 日志查看器

实施模式

日志架构

实时更新

成本计算

UI组件

最小CLI视图

丰富仪表板视图

设计检查清单

输出格式

反模式

交叉引用

版本历史

最后更新

名称: 多智能体可观测性描述: 为多智能体系统构建可观测性接口。用于监控多智能体执行、跟踪代理指标、实现并行代理的日志记录或调试代理工作流。允许工具: Read, Grep, Glob