Blueprint-Based SDK Usage Guide

Overview

The ACGP SDK uses Blueprints as the primary configuration format. Blueprints provide rich governance capabilities including inheritance, scope filtering, CTQ checks, evidence requirements, and trust debt tracking.

Important: Blueprints are configured on the Governance Steward side, not on the agent side. The steward automatically selects the appropriate blueprint based on agent scope, inheritance rules, and request context. Agents simply submit cognitive traces for evaluation.

Quick Start

Python

from acgp import GovernanceSteward, CognitiveTrace

# Initialize steward with blueprint file
steward = GovernanceSteward(
    blueprint_file="blueprints/finance_trading.yaml",
    conformance_level="standard"
)

# Create a cognitive trace
trace = CognitiveTrace(
    reasoning="Executing trade based on market analysis",
    action="execute_trade",
    parameters={
        "symbol": "AAPL",
        "quantity": 100,
        "price": 150.00
    },
    agent_id="trading_agent_1",
    agent_tier="ACL-3"
)

# Evaluate
result = steward.evaluate(trace)

if result.intervention == "OK":
    # Proceed with action
    execute_trade(trace.parameters)
else:
    # Handle intervention
    print(f"Blocked: {result.message}")

TypeScript

GovernanceSteward Coming Soon

The TypeScript GovernanceSteward runtime is planned for a future release. Currently, the TypeScript SDK provides type definitions. Use the Python SDK for full runtime support.

import { CognitiveTrace, InterventionType } from '@acgp-protocol/sdk';

// Create trace (types are available now)
const trace: CognitiveTrace = {
  reasoning: "Executing trade based on market analysis",
  action: "execute_trade",
  parameters: {
    symbol: "AAPL",
    quantity: 100,
    price: 150.00
  },
  agentId: "trading_agent_1",
  agentTier: "ACL-3"
};

// Check intervention types
if (result.intervention === InterventionType.OK) {
  await executeTrade(trace.parameters);
}

Blueprint Structure

Minimal Blueprint

id: my_app/basic_governance@1.0
version: "1.0.0"
description: "Basic governance for my application"

# Tripwires (hard limits)
tripwires:
  - id: high_value_check
    when:
      hook: "tool_call"
      tool: "process_payment"
    condition: "args.amount <= 10000"
    evalTier: 0
    severity: critical
    onFail:
      decision: "BLOCK"
      reason: "Payment amount exceeds $10,000 limit"

# Scoring thresholds
scoring:
  ok: 0.20
  nudge: 0.35
  escalate: 0.50
  block: 0.65

Standard Blueprint with Inheritance

id: finance/trading_regulated@1.0
version: "1.0.0"
description: "Regulated trading agent governance"
inherits: clarity.baseline@1.0

scope:
  agentTier: ["ACL-3", "ACL-4"]
  tools: ["execute_trade", "analyze_signal"]
  domains: ["production"]

tripwires:
  - id: single_trade_limit
    when:
      hook: "tool_call"
      tool: "execute_trade"
    condition: "args.trade_value <= 100000"
    evalTier: 0
    severity: critical
    onFail:
      decision: "HALT"
      reason: "Trade exceeds $100K limit"

checks:
  - id: trade_rationale_quality
    when:
      hook: "tool_call"
      tool: "execute_trade"
    metric:
      name: "reasoning_quality"
      weight: 0.4
      check:
        type: "llm-judge"
        args:
          model: "gpt-4"
          promptTemplate: "evaluate_trading_rationale"

evidence:
  minCertifiedSources: 2
  sourceCategories: ["regulatory", "market_data"]
  minTrustScore: 0.85

scoring:
  ok: 0.15
  nudge: 0.25
  escalate: 0.40
  block: 0.60

trustDebt:
  enabled: true
  accumulation:
    block: 0.20
    halt: 0.50
  decay:
    rate: 0.95
    periodHours: 24
  thresholds:
    elevatedMonitoring: 0.30
    restrictedMode: 0.50
    reTieringReview: 0.75

Advanced Features

Blueprint Inheritance

Blueprints can inherit from parent blueprints, enabling policy reuse:

# Parent blueprint is automatically loaded from registry
steward = GovernanceSteward(
    blueprint_file="my_specific_agent.yaml"  # Inherits from parent
)

Registry-Based Loading

from acgp import GovernanceSteward, BlueprintRegistry

# Use custom registry
registry = BlueprintRegistry(
    registry_url="https://blueprints.example.com/api"
)

steward = GovernanceSteward(
    blueprint_id="finance/trading_system@1.0",
    registry=registry
)

State Storage for Stateful Tripwires

from acgp import GovernanceSteward
from acgp.state_storage import create_state_storage

# Use ReflectionDB for distributed state
state_storage = create_state_storage(
    storage_type="reflectiondb",
    connection_string="postgresql://localhost/reflectiondb"
)

steward = GovernanceSteward(
    blueprint_file="blueprint.yaml",
    state_storage=state_storage
)

Trust Debt Tracking

Trust debt automatically accumulates based on interventions:

# Get trust debt metrics for an agent
metrics = steward.get_metrics()
agent_trust = metrics["trust_debt"]["trading_agent_1"]

print(f"Current debt: {agent_trust['current_debt']}")
print(f"Restricted mode: {agent_trust['restricted_mode']}")

API Reference

GovernanceSteward Constructor

GovernanceSteward(
    blueprint_file: Optional[str] = None,
    blueprint_dict: Optional[Dict] = None,
    blueprint_id: Optional[str] = None,
    registry: Optional[BlueprintRegistry] = None,
    state_storage: Optional[StateStorage] = None,
    conformance_level: str = "minimal",
    enable_warnings: bool = True
)

Parameters: - blueprint_file: Path to blueprint YAML file (loaded by steward at initialization) - blueprint_dict: Blueprint as dictionary (for testing/development) - blueprint_id: Blueprint ID to load from registry - registry: Custom blueprint registry client - state_storage: State storage for stateful tripwires - conformance_level: "minimal", "standard", or "complete" - enable_warnings: Enable production warnings

Blueprint Selection: The steward automatically selects the appropriate blueprint for each evaluation based on: 1. Agent scope (agent_id, agent_tier, tools used) 2. Blueprint inheritance rules 3. Request context (action type, parameters)

Agents do NOT specify blueprints in their cognitive traces. Blueprint selection is entirely steward-side to maintain separation of concerns and prevent agents from bypassing governance.

Blueprint Fields

Field Required Description
id Yes Unique blueprint identifier
version Yes Semantic version
description Yes Blueprint description
inherits No Parent blueprint ID
scope No Scope restrictions (agent_tier, tools, domains)
tripwires No List of tripwire configurations
checks No List of CTQ check configurations
evidence No Evidence requirements
scoring No Risk score thresholds
trustDebt No Trust debt configuration

Examples

Complete blueprint examples are available in /examples/blueprints/:

  • regulated-trading-single-agent.yaml - Single agent with comprehensive governance
  • multi-agent-trading-system.yaml - Multi-agent system with hierarchical blueprints
  • customer-service-agent.yaml - Customer service agent with evidence requirements

Next Steps