multi-agent-observability

# Multi-Agent Observability Skill

Build observability interfaces for monitoring and measuring multi-agent systems.

## Purpose

Guide the design and implementation of observability layers that provide real-time visibility into multi-agent execution.

## When to Use

- Designing monitoring for agent fleets
- Building metrics dashboards
- Implementing logging architecture
- Creating cost tracking systems

## Prerequisites

- Understanding of the Three Pillars (@three-pillars-orchestration.md)
- Familiarity with results-oriented patterns (@results-oriented-engineering.md)
- Access to Claude Agent SDK documentation

## SDK Requirement

> **Implementation Note**: Full observability requires Claude Agent SDK with custom MCP tools and UI components. This skill provides design patterns.

## The Critical Principle

> "If you can't measure it, you can't improve it. If you can't measure it, you can't scale it."

## What to Observe

### Per-Agent Metrics

| Metric | Purpose | How to Track |
| --- | --- | --- |
| Status | Know state | Agent state enum |
| Context usage | Token consumption | API response |
| Cost | Financial impact | API usage data |
| Tool calls | What it's doing | Hook logging |
| Results | Output verification | Result parsing |
| Duration | Execution time | Timestamps |

### Aggregate Metrics

| Metric | Purpose | Calculation |
| --- | --- | --- |
| Total agents | Scale | Count active |
| Total duration | End-to-end time | First to last |
| Total cost | Financial total | Sum per-agent |
| Success rate | Reliability | Success / total |
| Coverage | Scope | Files touched |

## Observability Components

### 1. Agent Cards

Real-time status for each agent:

```text
┌─────────────────────────────────────┐
│ scout_1                 [EXECUTING] │
├─────────────────────────────────────┤
│ Template: scout-fast                │
│ Model: haiku                        │
│ Context: 12,500 / 100,000 tokens    │
│ Cost: $0.05                         │
│ Duration: 45s