WAGF: Building a Governance Layer for LLM Agents to Bridge the Gap Between Logic and Action

WAGF (Water Agent Governance Framework) is an open-source governance framework designed for LLM-driven agents, aiming to address the 'logic-action gap' problem of agents: while agents can generate reasonable reasoning, they may make unrealistic decisions. The framework uses a three-layer architecture (LLM layer, governance layer, execution layer) and a six-stage validation pipeline to ensure decisions undergo multi-dimensional checks (including physical constraints, behavioral theories, and financial feasibility), while providing complete audit trails to support scientific reproducibility. Its design is suitable for key fields like water resource management and has cross-domain extensibility.

LLM agents perform well in simulating human decisions but often stay at the 'paper-talk' level. For example, when suggesting 'raising a house by $30,000 to deal with floods', they may ignore the feasibility of residents' income, neighborhood patterns, or insurance alternatives. This disconnect between logic and action is particularly dangerous in fields like public safety and resource management. WAGF was developed for coupled human-water systems (e.g., flood adaptation, irrigation management), with the core insight: each decision from the LLM must pass through a validation pipeline instead of acting directly on the environment.

WAGF uses a three-layer architecture to decouple agent cognition and action:

LLM Layer: Only generates candidate decisions and reasoning, does not directly execute operations—reducing risks at the source; Governance Layer (core innovation): Candidate decisions must go through a six-stage validation pipeline: Context Retrieval → LLM Reasoning Parsing → Structured Proposal Extraction → Multi-dimensional Validation → Approval/Retry (with targeted feedback if failed) → Execution; The validation stage includes six validators: Physical (real-world feasibility), Thinking (reasoning consistency), Individual (financial feasibility), Social (group behavior), Ethical (behavioral theories like PMT), and Skill Registry (safe operations); Execution Layer: Only decisions that pass validation can modify the simulation environment, and results are fed back to the memory system.

The project provides three reference implementations in the water resource domain:

• Flood Household Adaptation Simulation: Based on flood data from 2011-2023 in the Passaic River Basin, New Jersey, simulates a single household's 13-year adaptation decisions and compares behavioral differences under different governance strictness levels;
• Multi-agent Flood Scenario: Includes 402 agents (homeowners, tenants, government, insurance companies) to simulate complex social interactions and institutional feedback;
• Irrigation Management ABM: Based on the Hung & Yang (2021) system in the Colorado River Basin, uses 78 CRSS agents to make 42-year water allocation decisions and tests multiple models like Gemma 3 4B.

WAGF supports complete audit capabilities: each decision, rejection, retry, and reasoning process is recorded in JSONL/CSV format, enabling scientific review and cross-experiment comparison. Unlike traditional LLM 'black-box' decisions, researchers can precisely track the reasons behind an agent's decision (e.g., why it chose to buy insurance instead of raising the house). The audit log includes input context, LLM reasoning, validation results, feedback loops, and final execution—transparency is crucial for trustworthy agent systems.

Composable Agents: Supports progressive construction: Basic Level (execution engine only) → Level 1 (context + window memory) → Level 2 (weighted memory engine) → Level3 (complete governance agent); The modular design facilitates isolating validation impacts and conducting controlled experiments.

YAML-driven Configuration: Most settings do not require code modification: Adding skills/agent types/governance rules, adjusting memory parameters, replacing LLM models, etc., can all be done via YAML. Adding a new domain only requires three files: skill_registry.yaml (actions and premises), agent_types.yaml (personality and rules), and lifecycle_hooks.py (environment transformation subclass).

WAGF represents a paradigm shift: from 'LLM acting directly' to 'LLM proposing solutions, governance layer gatekeeping'. This is crucial for deploying LLM agents to the real world (climate adaptation, public health, financial risk control, etc.). The project's open-source implementation and documentation lower the entry barrier, and multiple reproducibility tests ensure robust results. As LLM agents move toward applications, WAGF's governance-first concept will become a key reference for building trustworthy, auditable, and interpretable systems.