Open Agent Compliance Protocol (OACP)

A governance layer for LangGraph that adds voting, consensus, and audit trails to multi-agent workflows. OACP transforms your agent systems with democratic decision-making, adaptive prompting, and comprehensive oversight.

Overview

OACP provides a framework for building trustworthy multi-agent systems by adding governance mechanisms on top of LangGraph. It enables agents to vote on decisions, reach consensus, maintain audit trails, and adapt their behavior based on feedback.

Key Features

Governance Layer: Add voting and consensus mechanisms to any LangGraph workflow
Adaptive Prompting: Automatically improve prompts based on rejection feedback
Audit Trails: Complete logging and tracking of all agent decisions and votes
Multiple Storage Backends: File, SQLite, and PostgreSQL support
Voting Strategies: Unanimous, majority, and weighted voting systems
Retry Logic: Intelligent retry mechanisms with exponential backoff
LLM Integration: Built-in adapters for popular language models
CLI Tools: Command-line interface for management and monitoring

Installation

From Source

git clone https://github.com/your-org/oacp.git
cd oacp
pip install -e .

Dependencies

OACP requires Python 3.10+ and depends on:

LangGraph: Core workflow framework
Pydantic: Data validation and settings
SQLAlchemy: Database abstraction layer
Typer: CLI framework
Rich: Terminal formatting

Optional dependencies:

psycopg: PostgreSQL support
FastAPI: Web interface
Google Generative AI: Gemini integration

Quick Start

Basic Usage

from oacp import with_oacp, decision_contract, vote, VoteDecision
from langgraph.graph import StateGraph

# Wrap any function with OACP governance
@with_oacp(
    role="researcher",
    invariants=["factual_accuracy", "comprehensive_coverage"],
    log_inputs=True,
    log_outputs=True
)
def research_agent(research_request: dict) -> dict:
    """Conducts initial research on the given topic."""
    # Your agent logic here
    return {"research_results": "..."}

# Create decision contracts for consensus
@with_oacp(
    role="synthesizer",
    contract=decision_contract(
        required_approvers=["researcher", "analyst", "critic"],
        strategy="unanimous",
        timeout_seconds=30
    )
)
def synthesis_agent(data) -> dict:
    """Synthesizes inputs into final report (requires consensus)."""
    # Your synthesis logic here
    return {"final_report": "..."}

# Voting functions
def researcher_vote(run_id: str, content: str):
    if meets_standards(content):
        vote(run_id=run_id, voter_id="researcher", 
             decision=VoteDecision.APPROVE, 
             reason="Content meets research standards")
    else:
        vote(run_id=run_id, voter_id="researcher", 
             decision=VoteDecision.REJECT, 
             reason="Insufficient research depth")

LangGraph Integration

from langgraph.graph import StateGraph

# Create your workflow
workflow = StateGraph(YourState)
workflow.add_node("research", research_agent)
workflow.add_node("synthesis", synthesis_agent)
workflow.add_edge("research", "synthesis")

# OACP governance is automatically applied
app = workflow.compile()

Examples

Research Team Workflow

A multi-agent research team with four specialized agents:

cd examples/research_team
export GOOGLE_AI_API_KEY=your_api_key
python main.py

Features demonstrated:

Multi-agent collaboration
Consensus-based decision making
Real LLM integration (Gemini 2.5 Flash)
Audit trails and governance

Flappy Bird Game Design

Agent-based game design with component compatibility voting:

cd examples/flappy_bird_sim
python main.py

Features demonstrated:

Component compatibility validation
Quality control through voting
Design iteration with feedback

Architecture

Core Components

Decorators (@with_oacp, wrap_node): Apply governance to functions
Contracts: Define voting requirements and strategies
Votes: Cast and track voting decisions
Context: Access current execution context
Storage: Pluggable storage backends
Events: Comprehensive event system
Adaptive Prompting: Automatic prompt improvement

Storage Backends

File Storage: JSON-based local storage
SQLite: Lightweight database storage
PostgreSQL: Production-ready database storage

Voting Strategies

Unanimous: All voters must approve
Majority: More than 50% approval required
Weighted: Votes have different weights

Configuration

Environment Variables

# Storage configuration
OACP_STORAGE_TYPE=sqlite
OACP_STORAGE_URL=sqlite:///oacp.db

# PostgreSQL example
OACP_STORAGE_TYPE=postgresql
OACP_STORAGE_URL=postgresql://user:pass@localhost/oacp

# File storage example
OACP_STORAGE_TYPE=file
OACP_STORAGE_PATH=./oacp_data

Programmatic Configuration

from oacp.storage import configure_storage

# Configure storage backend
configure_storage(
    storage_type="sqlite",
    storage_url="sqlite:///my_oacp.db"
)

CLI Usage

OACP includes a command-line interface for management:

# View recent activity
oacp logs --limit 50

# Show statistics
oacp stats

# Export audit trail
oacp export --format json --output audit.json

# View voting patterns
oacp votes --agent researcher --days 7

Development

Setup Development Environment

git clone https://github.com/your-org/oacp.git
cd oacp
pip install -e ".[dev]"
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=oacp --cov-report=html

# Run specific test file
pytest tests/test_decorators.py

Code Quality

# Format code
black oacp tests

# Lint code
ruff check oacp tests

# Type checking
mypy oacp

API Reference

Core Decorators

@with_oacp(): Apply OACP governance to functions
wrap_node(): Wrap LangGraph nodes with governance

Decision Making

decision_contract(): Define voting requirements
vote(): Cast votes on decisions
VoteDecision: Vote decision enum (APPROVE, REJECT, ABSTAIN)

Context Access

current_context(): Access current execution context
get_adaptation_statistics(): View adaptive prompting stats

Storage Interface

IStorage: Abstract storage interface
FileStorage: File-based storage implementation
SqliteStorage: SQLite storage implementation
PostgresStorage: PostgreSQL storage implementation

Contributing

We welcome contributions! Please see our contributing guidelines:

Fork the repository
Create a feature branch
Make your changes with tests
Ensure code quality checks pass
Submit a pull request

Development Guidelines

Follow PEP 8 style guidelines
Write comprehensive tests
Update documentation for new features
Use type hints throughout
Add docstrings for public APIs

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

Documentation: Full documentation available in the docs/ directory
Issues: Report bugs and request features on GitHub Issues
Examples: See examples/ directory for working implementations
CLI Help: Run oacp --help for command-line usage

Roadmap

Integration with more LLM providers
Advanced voting strategies
Web-based monitoring dashboard
Distributed agent coordination
Performance optimizations
Enhanced adaptive prompting algorithms

Version

Current version: 0.1.0 (Beta)

OACP is under active development. APIs may change between versions until 1.0.0 release.

Aaditya17032002/OACP