Agents

In ChooChoo, an Agent is a first-class passenger. It is an actor that can produce artifacts, execute workflows, and make decisions. Every agent action is recorded in the Audit Trail, and agents are governed by boundaries that the validation engine enforces.

Agent Registration

All agents operating within a governed repository MUST be registered in agents/AGENTS.md. This file serves as a human-readable registry and a machine-readable configuration source. See the Project Structure for where this fits in the directory layout.

Format

# Registered Agents

## Cursor Agent 001

**ID:** `cursor-agent-001`
**System Card:** `system-cards/cursor.yaml`
**Status:** `active`

### Capabilities

- Read codebase
- Propose code changes
- Run tests

### Boundaries

- Cannot modify `contracts/` without approval
- No access to `production` environment
- Cannot read fields tagged `pii`

Each agent should have a corresponding System Card that documents its capabilities, limitations, and compliance frameworks. System Cards are referenced during risk scoring to determine the level of trust assigned to an agent.

Boundaries (Rails)

Boundaries defined in the Agent Registry are enforced by the ChooChoo Engine. If an agent attempts an action that violates a boundary, the CLI will block the operation and return error E007 (Agent boundary violation).

Boundary enforcement is part of the validation pipeline. In CI/CD, boundary violations produce exit code 1 (VALIDATION_ERROR).

Agent Activity Log

Every action an agent takes is recorded in the Audit Trail. This log links the agent to its System Card, the artifact modified, and the full decision context captured via Agent Trace.

{
  "timestamp": "2026-01-31T14:23:45Z",
  "agentId": "cursor-agent-001",
  "action": "modify",
  "artifact": "contracts/customer-360.contract.yaml",
  "context": {
    "prompt": "Add phone number field",
    "confidence": 0.85
  }
}

The confidence field feeds into the risk scoring algorithm as the Agent Confidence (A) factor — lower confidence increases the risk score.

Managing Agents via CLI

Use the choochoo agent commands to manage your agent registry:

choochoo agent list          # List all registered agents
choochoo agent register      # Interactively register a new agent
choochoo agent audit <id>    # View activity history for an agent

See the CLI Reference for full documentation on all agent management commands.

Related