# Agents

> Agent implementations for the Agent Governance System

## Overview

This directory contains all agent implementations organized by tier level and function. Agents operate under governance constraints with tiered capabilities based on trust level.

## Agent Inventory

| Agent | Type | Language | Lines | Description |
|-------|------|----------|-------|-------------|
| [tier0-agent](./tier0-agent) | Observer | Python | 603 | Read-only monitoring agent |
| [tier1-agent](./tier1-agent) | Operator | Python | 1205 | Execution-capable operator agent |
| [llm-planner](./llm-planner) | Planner | Python | ~2000 | LLM-powered plan generation |
| [llm-planner-ts](./llm-planner-ts) | Planner | TypeScript | ~900 | TypeScript LLM planner variant |
| [multi-agent](./multi-agent) | Orchestrator | TypeScript | ~1700 | Multi-agent coordination system |

## Tier System

```
┌─────────────────────────────────────────────────────────────────────┐
│  TIER 2: Automator (Future)                                         │
│  - Full automation capabilities                                      │
│  - Production access with approval                                   │
└─────────────────────────────────────────────────────────────────────┘
        ▲ Promotion (10 compliant runs, required actions)
┌─────────────────────────────────────────────────────────────────────┐
│  TIER 1: Operator                                                    │
│  - Command execution                                                 │
│  - File read/write                                                   │
│  - Terraform, Ansible, Docker                                        │
│  - Sandbox access only                                               │
└─────────────────────────────────────────────────────────────────────┘
        ▲ Promotion (100 actions, 10 consecutive compliant)
┌─────────────────────────────────────────────────────────────────────┐
│  TIER 0: Observer                                                    │
│  - Read-only access                                                  │
│  - Plan generation                                                   │
│  - Monitoring and reporting                                          │
└─────────────────────────────────────────────────────────────────────┘
```

## Quick Start

### Tier 0 Agent (Observer)

```bash
cd tier0-agent
./bootstrap.sh
./run-agent.sh status
./run-agent.sh read /path/to/file
./run-agent.sh list /path/to/directory
```

### Tier 1 Agent (Operator)

```bash
cd tier1-agent
./bootstrap.sh
./run-agent.sh status
./run-agent.sh exec ls -la
./run-agent.sh write workspace/test.txt --content "Hello"
./run-agent.sh tf-plan /path/to/terraform
```

### LLM Planner (Python)

```bash
cd llm-planner
source .venv/bin/activate
python main.py
```

### Multi-Agent Orchestrator

```bash
cd multi-agent
bun run orchestrator.ts
```

## Agent Capabilities Matrix

| Capability | Tier 0 | Tier 1 | LLM Planner | Multi-Agent |
|------------|--------|--------|-------------|-------------|
| Read files | Yes | Yes | Yes | Yes |
| List directories | Yes | Yes | Yes | Yes |
| Generate plans | Yes | Yes | Yes | Yes |
| Execute commands | No | **Yes** | No | Via delegation |
| Write files | No | **Yes** | No | Via delegation |
| Terraform | No | **Yes** | Plan only | Via delegation |
| Ansible | No | **Yes** | Plan only | Via delegation |
| Docker | No | **Yes** | No | Via delegation |
| Coordinate agents | No | No | No | **Yes** |
| LLM integration | No | No | **Yes** | **Yes** |

## Governance Integration

All agents integrate with the governance framework:

- **Ledger**: Actions logged to `/opt/agent-governance/ledger/governance.db`
- **Heartbeat**: State tracked in DragonflyDB (`agent:state:{id}`)
- **Revocation**: Checked before each action (`agent:revoked:{id}`)
- **Promotion**: Metrics tracked for tier advancement

### Forbidden Actions (All Tiers)

- `delete_production` - Cannot delete production resources
- `access_vault_root` - Cannot access Vault root credentials
- `modify_governance` - Cannot modify governance rules

### Allowed Targets

- `localhost` (Tier 0+)
- `sandbox-*` (Tier 1+)
- `staging-*` (Tier 2 only, with approval)

## Directory Structure

```
agents/
├── README.md              # This file
├── STATUS.md              # Progress tracking
├── tier0-agent/           # Observer agent
│   ├── agent.py           # Main implementation
│   ├── bootstrap.sh       # Setup script
│   ├── run-agent.sh       # Runner
│   ├── config/            # Agent config
│   ├── workspace/         # Working directory
│   ├── plans/             # Generated plans
│   ├── logs/              # Agent logs
│   └── credentials/       # Vault credentials
├── tier1-agent/           # Operator agent
│   └── (same structure)
├── llm-planner/           # Python LLM planner
│   ├── agent.py           # Core agent
│   ├── governance.py      # Governance integration
│   ├── governed_agent.py  # Governed wrapper
│   ├── monitors.py        # Monitoring
│   └── .venv/             # Python virtual env
├── llm-planner-ts/        # TypeScript LLM planner
│   ├── index.ts           # Entry point
│   ├── governed-agent.ts  # Governed agent
│   └── node_modules/      # Dependencies
└── multi-agent/           # Orchestrator
    ├── orchestrator.ts    # Main orchestrator
    ├── agents.ts          # Agent definitions
    ├── coordination.ts    # Coordination logic
    ├── types.ts           # Type definitions
    └── node_modules/      # Dependencies
```

## Dependencies

| Agent | Runtime | Dependencies |
|-------|---------|--------------|
| tier0-agent | Python 3.11+ | sqlite3, requests |
| tier1-agent | Python 3.11+ | sqlite3, requests, redis |
| llm-planner | Python 3.11+ | OpenAI SDK (in .venv) |
| llm-planner-ts | Bun 1.0+ | openai, redis |
| multi-agent | Bun 1.0+ | typescript, redis |

## Testing

```bash
# Test tier0 agent
cd tier0-agent && ./run-agent.sh status

# Test tier1 agent (includes forbidden action tests)
cd tier1-agent && ./run-agent.sh test-forbidden

# Run governance tests
cd /opt/agent-governance/tests/governance
python test_phase3_execution.py
```

## Architecture Reference

Part of the [Agent Governance System](../docs/ARCHITECTURE.md).

For tier system details, see [Promotion Rules](../docs/ARCHITECTURE.md#promotion-system).

---
*Last updated: 2026-01-24*