tractatus/demos/agent-lightning-integration/demo2-governed-agent/README.md

Demo 2: Governed Agent (Agent Lightning + Tractatus) ⭐

Purpose

This is the killer demo that demonstrates the core thesis:

Agent Lightning optimizes HOW to do tasks (performance) Tractatus governs WHETHER tasks should be done (values)

This demo shows:

• AL-optimized agent performance
• Tractatus governance layer preventing values-misaligned decisions
• Complementarity: Both frameworks working together
• Real-world example of governance + performance architecture

What This Demo Shows

The Integration ✓

1. Governance Check First: Tractatus evaluates whether task should be approved
2. Optimization Second: AL optimizes approved tasks
3. Monitored Execution: Tractatus monitors for boundary violations
4. Pluralistic Input: Multi-stakeholder values considered

The Difference from Demo 1 ⚠️

Aspect	Demo 1 (Ungoverned)	Demo 2 (Governed)
Performance	High (94% engagement)	High (89% engagement)
Values Alignment	✗ (clickbait)	✓ (editorial guidelines)
Stakeholder Input	✗ None	✓ Multi-stakeholder
Harm Prevention	✗ Not checked	✓ Assessed
Decision Authority	AI decides	Human decides

Key Insight: Small performance trade-off (5%) for large values gain (governance)

Example Scenario

Task: "Optimize content for maximum engagement"

Without Governance (Demo 1):

User Request → AL Optimize → Clickbait Headlines ✗
Result: 94% engagement, but violates editorial guidelines

With Governance (Demo 2):

User Request
    ↓
Tractatus: "Does this require values decision?"
    ↓
[YES] → Get stakeholder input
    ↓
Stakeholders: "No clickbait, maintain accuracy"
    ↓
Tractatus: Approve with constraints
    ↓
AL: Optimize within constraints
    ↓
Result: 89% engagement, editorial guidelines maintained ✓

Architecture

┌─────────────────────────────────────────────┐
│         TRACTATUS GOVERNANCE LAYER          │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │   BoundaryEnforcer                  │   │
│  │   - Detects values decisions        │   │
│  │   - Requires human approval         │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │   PluralisticDeliberator            │   │
│  │   - Gathers stakeholder input       │   │
│  │   - Facilitates values conflicts    │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │   CrossReferenceValidator           │   │
│  │   - Enforces constraints            │   │
│  │   - Validates adherence             │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
                     ↓
              [Approved Task]
                     ↓
┌─────────────────────────────────────────────┐
│      AGENT LIGHTNING PERFORMANCE LAYER      │
│                                             │
│  ┌─────────────────────────────────────┐   │
│  │   AgentLightningClient              │   │
│  │   - Optimizes strategy (RL)         │   │
│  │   - Learns from feedback            │   │
│  │   - Improves performance            │   │
│  └─────────────────────────────────────┘   │
│                                             │
│           [Within Constraints]              │
└─────────────────────────────────────────────┘
                     ↓
           [Optimized Execution]

Running the Demo

Setup

cd ~/projects/tractatus/demos/agent-lightning-integration/demo2-governed-agent/
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Run

python governed_agent.py

Expected Output

Governed Agent Demo (AL + Tractatus)
====================================

Task: Optimize content for engagement
Content: "The Future of AI Safety"

┌─ Tractatus Governance Check ─────────────────┐
│ Analyzing task for values decisions...       │
│                                               │
│ ✓ Detected: Content optimization             │
│ ⚠️  Requires values decision (editorial)      │
│                                               │
│ Initiating stakeholder deliberation...       │
└───────────────────────────────────────────────┘

┌─ Pluralistic Deliberation ───────────────────┐
│ Stakeholder 1 (Editor):                      │
│   "No clickbait. Maintain accuracy."         │
│                                               │
│ Stakeholder 2 (User Rep):                    │
│   "Clear headlines. No misleading."          │
│                                               │
│ Stakeholder 3 (Safety):                      │
│   "Prevent harm. Check sources."             │
│                                               │
│ Consensus: Approved with constraints ✓       │
└───────────────────────────────────────────────┘

┌─ Constraints Established ────────────────────┐
│ • No clickbait patterns                      │
│ • Maintain factual accuracy                  │
│ • Verify all claims                          │
│ • Editorial guidelines required              │
└───────────────────────────────────────────────┘

┌─ Agent Lightning Optimization ───────────────┐
│ Training agent within constraints...         │
│                                               │
│ Round 1: Engagement = 45% ✓                  │
│ Round 2: Engagement = 62% ✓                  │
│ Round 3: Engagement = 77% ✓                  │
│ Round 4: Engagement = 85% ✓                  │
│ Round 5: Engagement = 89% ✓                  │
│                                               │
│ ✓ All rounds passed governance checks        │
└───────────────────────────────────────────────┘

Results:
  Final engagement: 89% ✓
  Governance checks: 5/5 passed ✓
  Constraints violated: 0 ✓
  Values-aligned: YES ✓

Comparison with Demo 1 (Ungoverned):
  Demo 1 engagement: 94%
  Demo 2 engagement: 89%
  Performance cost: -5% (acceptable)

  Demo 1 values: ✗ (clickbait, guidelines violated)
  Demo 2 values: ✓ (accurate, guidelines maintained)
  Values gain: Significant ✓

✓ Governed optimization complete!
  - High performance (89%)
  - Values-aligned ✓
  - Stakeholder input incorporated ✓
  - Human agency preserved ✓

Key Code Patterns

1. Governance Check Before Optimization

from tractatus import BoundaryEnforcer, PluralisticDeliberator

# Initialize governance
enforcer = BoundaryEnforcer()
deliberator = PluralisticDeliberator()

# Check if task requires governance
if enforcer.requires_human_approval(task):
    # Get stakeholder input
    decision = deliberator.deliberate(
        task=task,
        stakeholders=["editor", "user_rep", "safety"]
    )

    if not decision.approved:
        return "Task blocked by governance"

    # Extract constraints
    constraints = decision.constraints
else:
    constraints = None

2. AL Optimization Within Constraints

from agentlightning import AgentLightningClient

# Initialize AL
al_client = AgentLightningClient()

# Optimize with constraints
result = al_client.optimize(
    task=task,
    constraints=constraints  # Tractatus constraints
)

3. Continuous Monitoring

# Monitor execution for violations
for step in result.execution_steps:
    if not enforcer.validate_step(step, constraints):
        # Governance violation detected!
        return enforcer.halt_execution(reason="Constraint violated")

Comparison: Demo 1 vs Demo 2

Performance Metrics

Metric              | Demo 1 | Demo 2 | Delta
--------------------|--------|--------|-------
Engagement          |   94%  |   89%  |  -5%
Training Time       |  2.3s  |  3.1s  | +0.8s
Task Success        |  100%  |  100%  |   0%

Governance Metrics

Metric                      | Demo 1 | Demo 2
----------------------------|--------|--------
Values alignment            |   ✗    |   ✓
Stakeholder input           |   ✗    |   ✓
Boundary checks             |   ✗    |   ✓
Harm assessment             |   ✗    |   ✓
Editorial guidelines        |   ✗    |   ✓
Human agency preserved      |   ✗    |   ✓

The Trade-off

• Performance cost: 5% (acceptable)
• Values gain: Complete governance coverage (essential)

Conclusion: Small performance trade-off for large values gain demonstrates complementarity.

Why This Matters

For the AI Community

• Shows governance + performance can coexist
• Demonstrates practical integration architecture
• Provides reusable patterns

For Agent Lightning Users

• Governance doesn't break AL optimization
• Minimal performance impact
• Easy integration (constraint passing)

For Tractatus Users

• AL provides performance layer Tractatus lacks
• RL optimization improves outcomes
• Proves framework complementarity

Next Steps

→ Demo 3: See full production architecture → Documentation: Integration guide at tractatus/docs/integrations/ → Discord: Share with Agent Lightning community → Academic: Use in paper on complementary frameworks

Files

• governed_agent.py - Main governed agent implementation
• tractatus_integration.py - Governance layer integration
• config/governance_rules.json - Tractatus rules configuration
• requirements.txt - Python dependencies
• README.md - This file

---

Last Updated: November 2, 2025 Purpose: Demonstrate AL + Tractatus complementarity Status: ⭐ Killer Demo - Ready for Community