# Agent Reference Docs

This directory documents internal agents used by the auto-agents system. These agents are hidden infrastructure — they are not invoked directly by users or supervisors. They are called by `async-agent-util` as part of its internal operations.

## Health Evaluation Pipeline

The `health` operation in `async-agent-util` uses a three-agent pipeline to classify each session's health state without any single agent processing the full fleet's data.

```
async-agent-util (health op)
  └── session-health-util   (one per session, parallel batches of 10)
        ├── Tier 1: session-health-quick-util   (always)
        └── Tier 2: session-health-full-util    (only on escalate)
```

### Agents

| Agent | Docs | Role |
|-------|------|------|
| `session-health-util` | [docs](./session-health-util/) | Two-tier coordinator; orchestrates quick → full escalation for one session |
| `session-health-quick-util` | [docs](./session-health-quick-util/) | Fast classifier; commits only when obviously finished/errored, otherwise escalates |
| `session-health-full-util` | [docs](./session-health-full-util/) | Deep analyst; evaluates timing, tools, and content with full system context |

### Design Principles

- **No heuristics.** Every session receives LLM-based classification. The quick evaluator eliminates obvious cases cheaply; the full evaluator handles the rest.
- **Contextual awareness.** All three agents load the `auto-agents-system` skill, giving them knowledge of what each agent type is supposed to achieve and what healthy vs unhealthy operation looks like.
- **Fail safe.** The quick evaluator defaults to `escalate` when unsure. `healthy` is the default for the full evaluator when signals are mixed.
- **No data files.** All data flows through prompts and bash outputs. Nothing is written to disk as an intermediate step.
