agno-dcp

agno-dcp

Cryptographic governance for Agno agents. Identity, policy gates, and tamper-evident audit trails for production agentic systems.

agno-dcp is an opt-in governance layer that wraps Agno's Agent, Team, Workflow, and MCP primitives with the Digital Citizenship Protocol for AI Agents (DCP-AI). The library does not modify Agno; you import DCPAgent instead of Agent, pass two extra arguments, and gain:

• a tamper-evident Citizenship Bundle for every agent (DCP-01)
• a signed Intent Declaration plus signed Policy Decision for every action (DCP-02)
• a hash-chained, Merkle-sealed audit trail that any external auditor can verify offline (DCP-03)
• signed inter-agent (MCP) messages for cross-organisation trust (DCP-04)

If DCP-AI is not active, the agent runs identically to a plain Agno agent.

---

Why agno-dcp

Agno gives you the runtime. agno-dcp gives you the paper trail regulated buyers ask for before signing.

For a longer pitch see docs/why.md.

---

Installation

pip install agno-dcp

For the production Postgres backend:

pip install "agno-dcp[postgres]"

Requires Python 3.11 or newer. Agno is a peer dependency: install your preferred Agno version separately.

---

Quickstart

import asyncio

from agno_dcp import (
    DCPAgent,
    PolicyEngine,
    MerkleAuditChain,
    SQLiteStorage,
)


async def main() -> None:
    # 1. Storage and audit chain
    storage = SQLiteStorage("./agent.db")
    audit = MerkleAuditChain(storage=storage)

    # 2. Policy engine from a YAML file
    policy = PolicyEngine.from_yaml("policies.yaml")

    # 3. Wrap an Agno Agent
    agent = DCPAgent(
        # Native Agno arguments (forwarded as-is)
        name="Collections Agent",
        model="claude:sonnet-4",
        tools=[crm_lookup, payment_plan_offer],
        instructions="You help customers reschedule overdue invoices.",
        # DCP-AI governance arguments
        dcp_human_principal="ops@example.com",
        dcp_security_tier="tier-3",
        dcp_audit_chain=audit,
        dcp_policy_engine=policy,
        dcp_strict_mode=True,
    )
    await agent.dcp_initialize()

    # 4. Run a tool through the full DCP-AI pipeline
    result = await agent.run_tool(
        crm_lookup,
        {"customer_id": 12345},
    )

    # 5. Periodically seal a tamper-evident root signature
    root = await audit.seal_root()
    print(f"Sealed Merkle root: {root.root_hash}, entries: {root.entry_count}")


asyncio.run(main())

The corresponding policies.yaml:

version: "1.0"
default: deny
rules:
  - name: "Allow CRM lookups"
    when:
      action_type: tool_call
      tool_name: crm_lookup
    then: allow

  - name: "Limit payment discounts"
    when:
      action_type: tool_call
      tool_name: payment_plan_offer
      payload.discount_pct:
        gt: 20
    then: deny
    reason: "Discounts above 20% require human approval"

---

How it works

+------------------------------------------------------------+
|  Your application                                          |
|  (FastAPI, CLI, scheduled job, ...)                        |
+------------------------------------------------------------+
                |
                v
+------------------------------------------------------------+
|  DCPAgent  =  Agno Agent  +  governance hooks              |
|                                                            |
|     pre_tool_call:  build + sign IntentDeclaration         |
|                     PolicyGate.evaluate -> PolicyDecision  |
|                     (deny -> raise PolicyDenied in strict) |
|     run tool                                               |
|     post_tool_call: append TOOL_EXECUTED audit event       |
+------------------------------------------------------------+
                |               |
                v               v
       PolicyEngine        MerkleAuditChain
       (YAML rules)        (hash-chained)
                                |
                                v
                           Storage
                  (SQLiteStorage / PostgresStorage)
                                |
                                v
                  AuditChainVerifier  (offline)
                  ComplianceBundleExporter
                  (signed ZIP for auditors)

The full architecture is documented in docs/architecture.md.

---

Compliance mapping

• EU AI Act: Articles 12, 13, 14, 15, and 50 are mapped to specific DCP-AI artefacts. See docs/compliance_mapping.md.
• NIST AI RMF: Govern, Map, Measure, and Manage functions each have at least two mapped subcategories.

The library ships a one-call exporter that produces a signed ZIP archive an auditor can verify offline:

from agno_dcp import ComplianceBundleExporter
from pathlib import Path

exporter = ComplianceBundleExporter(audit, storage)
bundle_path = await exporter.export(
    framework="eu_ai_act",
    output_dir=Path("./bundles"),
)

---

Verifying an audit chain offline

agno-dcp verify --sqlite ./agent.db
agno-dcp verify --postgres-url $DATABASE_URL --agent-id agent:abc123 --range 0:1000

Recomputes every entry hash, walks the prev_hash linkage, and verifies the embedded signature on every sealed root. Exits non-zero on corruption.

---

Status

v0.1.0 is an early access release. The public API surface listed in agno_dcp/__init__.py is the contract; everything else is internal and may change. Not yet recommended for production deployments handling regulated data; suitable for evaluation, demo work, and internal pilots.

What ships today (DCP-01 through DCP-04):

• Citizenship Bundle generation, loading, verification.
• Declarative YAML policy engine with signed verdicts.
• Hash-chained, Merkle-sealed audit log on SQLite or Postgres.
• MCP envelope signing and verification.
• agno-dcp verify CLI for offline integrity checks.
• Compliance Bundle exporter (EU AI Act + NIST AI RMF mappings).

What is not in v0.1.0:

• End-to-end demo (planned for v0.2.0).
• External HTTP policy engine.
• DCP-05 through DCP-09 (lifecycle, succession, dispute, rights, delegation).
• UI or dashboard.
• MongoDB and other non-SQL backends.
• Hardware-backed key custody (AWS KMS, GCP Cloud KMS).

A production-ready demo is on the roadmap for Q2 2026.

---

Contributing

See CONTRIBUTING.md. The project follows the same conventions as DCP-AI: Conventional Commits, Apache 2.0, ruff for formatting, mypy strict for typing.

---

License and acknowledgments

Apache 2.0. See LICENSE.

agno-dcp is built on top of:

• Agno for the agent runtime.
• DCP-AI for the protocol and crypto primitives.
• Pydantic 2, SQLAlchemy 2, and PyYAML for the data plane.