agent-governance/agents/README.md

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	Observer	Python	603	Read-only monitoring agent
tier1-agent	Operator	Python	1205	Execution-capable operator agent
llm-planner	Planner	Python	~2000	LLM-powered plan generation
llm-planner-ts	Planner	TypeScript	~900	TypeScript LLM planner variant
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)

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)

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)

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

Multi-Agent Orchestrator

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

# 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.

For tier system details, see Promotion Rules.

---

Last updated: 2026-01-24