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, PostgresStateStorage

# Production-oriented bootstrap with blueprint file
steward = GovernanceSteward.production(
    blueprint_file="blueprints/finance_trading.yaml",
    state_storage=PostgresStateStorage(connection_string="postgresql://runtime/acgp"),
)

# 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="urn:acgp:agent:trading:prod:7f4c9d2a",
    governance_tier="GT-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: "urn:acgp:agent:trading:prod:7f4c9d2a",
  governanceTier: "GT-3"
};

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

Blueprint Structure

Starter 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"
    eval_tier: 0
    severity: critical
    on_fail:
      decision: "block"
      reason: "Payment amount exceeds $10,000 limit"

# Scoring thresholds
scoring:
  thresholds:
    ok: 0.20
    nudge: 0.35
    escalate: 0.50
    # Risk > escalate → block (implicit; halt is tripwire-only)

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:
  governance_tiers: ["GT-3", "GT-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"
    eval_tier: 0
    severity: critical
    on_fail:
      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: "cognitive-evaluator"
        args:
          model: "gpt-4"
          promptTemplate: "evaluate_trading_rationale"

evidence:
  min_certified_sources: 2
  source_categories: ["regulatory", "market_data"]
  min_trust_score: 0.85

scoring:
  thresholds:
    ok: 0.15
    nudge: 0.25
    escalate: 0.40
    # Risk > escalate → block (implicit; halt is tripwire-only)

trust_debt:
  enabled: true
  accumulation:
    block: 0.20
    halt: 0.50
  decay:
    decay_fraction: 0.05
    period_hours: 24
  thresholds:
    elevated_monitoring: 0.30
    restricted_mode: 0.50
    re_tiering_review: 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
)

Merge Semantics

When inheritance is resolved, parent and child are merged with deterministic rules:

  • tripwires and checks append by default; duplicate ids are child overrides.
  • scope, scoring, evidence, and trust_debt are child override fields.
  • annotations are merged as dictionaries with child keys taking precedence.

For the full normative merge table, see ACGP-3 Section 2.4: Blueprints, Traces & Evaluation.

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 a durable backend for stateful tripwires and production posture
state_storage = create_state_storage(
  storage_type="governance_store",
  connection_string="postgresql://localhost/governance"
)

steward = GovernanceSteward.production(
    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"]["urn:acgp:agent:trading:prod:7f4c9d2a"]

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 = "dev_mode",
    enable_warnings: bool = True,
    deployment_mode: str = "development",
    require_production_posture: bool = False,
)

Use the general constructor for development, testing, and advanced bootstrap flows. For production deployments, prefer:

GovernanceSteward.production(
    blueprint_file="blueprint.yaml",
    state_storage=PostgresStateStorage(connection_string="postgresql://runtime/acgp"),
)

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; if omitted, the steward may default to in-memory state that is unsuitable for production - conformance_level: dev_mode, standard, or safety-critical - enable_warnings: Enable production warnings - deployment_mode: development, staging, or production - require_production_posture: Require production-safe runtime posture validation at startup

Blueprint Selection: The steward automatically selects the appropriate blueprint for each evaluation based on: 1. Agent scope (agent_id, governance_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 (governance_tiers, 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