Agents Overview

AEGIS ships four specialized AI agents, each focused on a specific area of Texas oil and gas regulatory compliance. Agent configurations are defined as YAML files in the agents/ directory and loaded into the database by the skill registry seed script.

Agent Summary

All agents use gpt-4o as the primary model with gpt-4o-mini as the fallback.

Filing Agents vs. Monitoring Agents

The four agents fall into two categories:

Filing agents (Rule 37, Rule 32) assist with preparing regulatory filings. They run on demand when a user initiates a filing workflow, walk through a multi-step checklist, and always require HITL approval before any submission. These agents have larger per-execution budgets to accommodate the complexity of filing preparation.

Monitoring agents (Compliance Monitor, Flaring Monitor) run continuously or on a schedule. They scan portfolio data, detect anomalies, and raise alerts. Their HITL checkpoints are optional — they notify the compliance team but do not block on approval. These agents have smaller per-execution budgets but higher daily limits to support frequent assessments.

YAML Configuration Structure

Each agent is defined in a YAML file in agents/. Here is an annotated example showing all supported fields:

# Top-level identifiers
agent_id: rule37-agent            # Unique agent ID, used as primary key in the agents table
name: Rule 37 Spacing Exception Agent  # Human-readable display name
agent_type: rule_37               # Enum: rule_37, rule_32, compliance_monitor, flaring_monitor
 
# LLM model configuration
model:
  primary: gpt-4o                 # Primary model for all LLM calls
  fallback: gpt-4o-mini           # Fallback if primary fails or budget is tight
 
# System prompt injected at the start of every conversation
system_prompt: |
  You are the AEGIS Rule 37 Spacing Exception Agent...
  (multi-line prompt with capabilities, workflow, and rules)
 
# Skills this agent can use (references skill IDs in the skills table)
skills:
  - spacing-calculation
  - offset-well-analysis
  - rule37-filing-assembly
  - good-cause-narrative
 
# Human-in-the-loop policies
hitl_policies:
  - checkpoint_type: pre_filing        # When this checkpoint triggers
    required: true                      # Whether execution blocks until approved
    description: "Review the assembled filing package before RRC submission"
    reviewer_strategy: named_individual # named_individual or role_based
 
  - checkpoint_type: good_cause_review
    required: true
    description: "Review the good cause narrative for legal sufficiency"
    reviewer_strategy: role_based
 
# Token and cost budgets
budget:
  max_tokens_per_execution: 150000     # Hard limit per single execution
  max_cost_usd_per_execution: 10.0     # Dollar cap per execution
  max_tokens_per_day: 2000000          # Daily token ceiling
  max_cost_usd_per_day: 100.0          # Daily dollar ceiling
 
# Arbitrary metadata for filtering and context
metadata:
  domain: oil_and_gas
  jurisdiction: texas
  regulator: rrc
  primary_rule: "16 TAC §3.37"
  primary_forms:
    - W-1
    - W-1A

Configuration Fields Reference

How Agents Are Loaded

Agent YAML files are read by the seed script and upserted into the agents table in PostgreSQL:

cd services/orchestration-engine
poetry run python -m orchestration.seed_skills

This script processes all four YAML configs, builds the config JSONB payload (containing system prompt, model preferences, skills, budget, and HITL policies), and inserts or updates the agents row for each agent.

Budget Enforcement

Token and cost budgets are enforced at runtime by the budget.py module in the orchestration engine. When an agent execution approaches its limits:

1. Warning at 80% — the system logs a warning and may switch to the fallback model
2. Hard stop at 100% — raises BudgetExceededError, halting execution gracefully
3. Daily limits — tracked in the budget_usage table, reset at midnight UTC

HITL Checkpoint Flow

When an agent reaches a HITL checkpoint:

1. The orchestration engine pauses execution and creates an approval_requests record
2. The reviewer is notified (via dashboard or email, depending on the strategy)
3. The reviewer can approve, reject, or modify the agent’s output
4. On approval, execution resumes from the checkpoint
5. On rejection, the agent receives the reviewer’s comments and can revise

Source Files