8c6e7831e9
Major additions: - marketplace/: Agent template registry with FTS5 search, ratings, versioning - observability/: Prometheus metrics, distributed tracing, structured logging - ledger/migrations/: Database migration scripts for multi-tenant support - tests/governance/: 15 new test files for phases 6-12 (295 total tests) - bin/validate-phases: Full 12-phase validation script New features: - Multi-tenant support with tenant isolation and quota enforcement - Agent marketplace with semantic versioning and search - Observability with metrics, tracing, and log correlation - Tier-1 agent bootstrap scripts Updated components: - ledger/api.py: Extended API for tenants, marketplace, observability - ledger/schema.sql: Added tenant, project, marketplace tables - testing/framework.ts: Enhanced test framework - checkpoint/checkpoint.py: Improved checkpoint management Archived: - External integrations (Slack/GitHub/PagerDuty) moved to .archive/ - Old checkpoint files cleaned up Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
185 lines
7.3 KiB
Markdown
185 lines
7.3 KiB
Markdown
# 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*
|