agent-governance/agents/llm-planner

LLM Planner Agent

Tier 0 Observer agent with LLM-powered plan generation

Overview

The LLM Planner is a governed Tier 0 Observer agent that uses OpenRouter LLMs to generate implementation plans. It follows strict governance constraints - it can read, analyze, and plan but cannot execute any actions.

Capabilities

Capability	Allowed
Read documentation	Yes
Read inventory	Yes
Read logs	Yes
Generate plans	Yes
LLM inference	Yes
Execute commands	No
Modify files	No
SSH/Terraform/Ansible	No

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      LLM Planner Agent                          │
├─────────────────────────────────────────────────────────────────┤
│  agent.py           Core agent with LLM integration             │
│  governance.py      DragonflyDB state tracking & revocation     │
│  governed_agent.py  Governance-wrapped agent runner             │
│  monitors.py        Action monitoring and logging               │
└─────────────────────────────────────────────────────────────────┘
         │                    │                    │
         ▼                    ▼                    ▼
    ┌─────────┐        ┌───────────┐        ┌──────────┐
    │OpenRouter│        │DragonflyDB│        │  Ledger  │
    │   LLM    │        │  (State)  │        │ (SQLite) │
    └─────────┘        └───────────┘        └──────────┘

Quick Start

# Enter the agent directory
cd /opt/agent-governance/agents/llm-planner

# Activate virtual environment
source .venv/bin/activate

# Run the agent
python main.py

Configuration

Agent Metadata

AGENT_METADATA = {
    "agent_id": "llm-planner-001",
    "agent_role": "observer",
    "tier": 0,
    "confidence_threshold": 0.7,
    "allowed_side_effects": [
        "read_docs",
        "read_inventory",
        "read_logs",
        "generate_plan",
        "llm_inference"
    ],
    "forbidden_actions": [
        "ssh", "create_vm", "modify_vm", "delete_vm",
        "run_ansible", "run_terraform", "write_secrets",
        "execute_shell", "modify_files"
    ]
}

Environment Variables

Variable	Description	Required
OPENROUTER_API_KEY	OpenRouter API key	Yes (or from Vault)

Structured Output

All agent outputs follow the Foundation Document schema:

class AgentOutput:
    agent_id: str           # Agent identifier
    version: str            # Agent version
    timestamp: str          # ISO timestamp
    action: str             # Action attempted
    decision: Decision      # EXECUTE, SKIP, ESCALATE, ERROR
    confidence: float       # 0.0 to 1.0
    assumptions: list[str]  # Assumptions made
    dependencies: list[str] # Required dependencies
    side_effects: list      # Side effects declared
    notes_for_humans: str   # Human-readable notes

Decision Types

Decision	Description
EXECUTE	Action approved and completed
SKIP	Action skipped (not applicable)
ESCALATE	Requires human review
INSUFFICIENT_INFORMATION	Cannot proceed without more data
ERROR	Action failed

Governance Integration

State Tracking (DragonflyDB)

from governance import AgentStateTracker

tracker = AgentStateTracker(agent_id="llm-planner-001")
tracker.update_phase(AgentPhase.PLAN)
tracker.update_heartbeat()

Revocation Checking

from governance import is_revoked, check_lock

if is_revoked(agent_id):
    # Agent has been revoked - stop immediately
    sys.exit(1)

Ledger Logging

All actions are logged to SQLite:

• /opt/agent-governance/ledger/governance.db

Modules

agent.py (410 lines)

Core agent implementation with:

• Task request handling
• LLM inference via OpenRouter
• Structured output generation
• Confidence scoring

governance.py (750 lines)

Real-time governance via DragonflyDB:

• Agent state tracking
• Phase transitions
• Error budget management
• Revocation handling
• Lock management

governed_agent.py (380 lines)

Governance-wrapped agent runner:

• Preflight checks
• Action monitoring
• Compliance verification
• Handoff support

monitors.py (300 lines)

Monitoring infrastructure:

• Action logging
• Metrics collection
• Alert generation

Example Usage

from agent import LLMPlannerAgent, TaskRequest

# Create agent
agent = LLMPlannerAgent()

# Create task
task = TaskRequest(
    task_type="plan",
    description="Create deployment plan for web service",
    constraints=["No production access", "Use sandbox only"]
)

# Generate plan
output = agent.process_task(task)

print(f"Decision: {output.decision}")
print(f"Confidence: {output.confidence}")
print(f"Plan: {output.notes_for_humans}")

Testing

# Activate venv
source .venv/bin/activate

# Run agent tests
python -m pytest tests/

# Test import
python -c "from agent import LLMPlannerAgent; print('OK')"

Dependencies

• Python 3.11+
• OpenAI SDK (for OpenRouter compatibility)
• Pydantic (structured outputs)
• Redis (DragonflyDB client)

All dependencies are installed in .venv/.

Architecture Reference

Part of the Agent Governance System.

See also:

• Tier 0 Agent - Base observer agent
• LLM Planner TS - TypeScript variant

---

Last updated: 2026-01-24