Skip to main content

Governed AI Agent Blueprint

A small, executable reference architecture for grounded and auditable AI agents.

CI License

This repository demonstrates the control boundaries an AI workflow should have before it reaches production. It keeps model generation separate from retrieval, policy decisions, tool approval and audit evidence.

It deliberately uses only the Python standard library. Connectors to a model, vector store, identity provider or durable audit system belong at explicit interfaces instead of being hidden inside the agent loop.

What it demonstrates

  • Answers grounded in retrieved records with machine-checkable citations
  • Tenant and role authorization before records enter model context
  • Refusal when the knowledge base has no relevant evidence
  • Tool allow, deny and human-approval decisions before execution
  • Persistent, expiring and idempotent approval state backed by SQLite
  • Structured audit events without prompts, secrets or full document content
  • Measurable evaluation thresholds independent of a model provider
  • Dependency inversion through a minimal LanguageModel protocol

Control flow

flowchart LR
    U[User request] --> R[Retriever]
    R --> Z[Record authorization]
    Z --> G{Authorized evidence?}
    G -- No --> F[Grounded refusal]
    G -- Yes --> M[Language model]
    M --> C[Citation validation]
    C --> A[Answer]
    U --> P[Tool policy]
    P --> D[Deny]
    P --> H[Persistent human approval]
    P --> T[Allowed tool request]
    R --> E[Audit sink]
    P --> E
    C --> E

The blueprint produces tool decisions; it does not execute tools. That separation prevents a model-generated request from becoming an external side effect without an application-owned authorization step.

The model must return both text and record identifiers. The agent rejects empty citations and identifiers that were not present in the retrieved context. This checks citation provenance; it does not prove that every natural-language claim is entailed by the cited text, which still requires domain-specific evaluation.

Quick start

python3 -m unittest discover -s tests -v
python3 evals/run.py
python3 evals/run.py --json
python3 examples/incident_assistant.py

Minimal usage:

from governed_agent import GovernedAgent, InMemoryAuditSink, KnowledgeRecord, ModelOutput
from governed_agent.retrieval import KeywordRetriever


class ExampleModel:
    def complete(self, question: str, context: tuple[KnowledgeRecord, ...]) -> ModelOutput:
        return ModelOutput(
            "The documented recovery target is four hours.",
            (context[0].record_id,),
        )


records = (
    KnowledgeRecord("runbook-7", "The recovery target is four hours."),
)
audit = InMemoryAuditSink()
agent = GovernedAgent(ExampleModel(), KeywordRetriever(records), audit)

answer = agent.answer("What is the recovery target?")
print(answer.text)
print(answer.citations)

Policy model

ToolPolicy classifies tools into three outcomes:

Outcome Meaning
allow The application may continue to its normal authorization checks
approval_required A human or separate approval service must authorize it
deny The request must not execute

The default policy denies unknown tools. This is intentional: adding a tool is a security decision, not a prompt-engineering detail.

SQLiteApprovalWorkflow persists approval requests with an expiration time and idempotency key. The requester cannot approve their own action. An approved request is consumed before a separate executor performs the side effect; this repository deliberately contains no tool executor.

Repository layout

src/governed_agent/   Agent, authorization, approval, policy and audit boundaries
tests/                Deterministic unit tests
evals/                Dataset, measurable thresholds and executable evaluator
examples/             Synthetic incident-assistant workflow
docs/                 Threat model and security boundaries

Reference scenario

examples/incident_assistant.py models an operations assistant using synthetic data. An authorized operator receives a cited runbook answer, proposes a high-severity ticket and obtains approval from a different incident manager. The approval is persisted and consumed, but no external ticket is created.

Project status and provenance

The initial implementation was generated with OpenAI Codex on 25 September 2026 during a GitHub-profile improvement task. It is an AI-assisted reference implementation, not a deployed client system or evidence of a completed client engagement. The repository is public so its code, limitations and subsequent maintainer review remain inspectable.

Production integration checklist

Before adapting this blueprint to production:

  • authenticate the caller and propagate a stable actor identifier;
  • enforce tenant and record authorization inside the retrieval service itself;
  • replace keyword retrieval with a tenant-aware retrieval service;
  • validate citations against the exact context supplied to the model;
  • keep secrets and sensitive document content out of audit payloads;
  • require idempotency keys for mutating tools;
  • execute tools in a separate, least-privilege service;
  • add timeouts, rate limits, cost limits and incident telemetry;
  • evaluate refusal, grounding and authorization behavior on domain-specific cases.

Read the threat model before adapting any component.

Non-goals

This is not a general-purpose agent framework, autonomous tool runner or claim that deterministic wrappers make model output deterministic. It is a compact example of where responsibility should live in a governed system.

Security

Please report vulnerabilities privately as described in SECURITY.md.

License

MIT

Metadata

Release files for governed-ai-agent-blueprint 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for governed-ai-agent-blueprint 0.3.1
File Size Uploaded Provenance Actions
governed_ai_agent_blueprint-0.3.1.tar.gz 18.7 kB With provenance Details for governed_ai_agent_blueprint-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for governed-ai-agent-blueprint 0.3.1
File Interpreter ABI Platform Actions
governed_ai_agent_blueprint-0.3.1-py3-none-any.whl Python 3 none any Details for governed_ai_agent_blueprint-0.3.1-py3-none-any.whl

Total release size: 30.5 kB

Release files / governed_ai_agent_blueprint-0.3.1.tar.gz

Download URL governed_ai_agent_blueprint-0.3.1.tar.gz
Size 18.7 kB
Tags Source
SHA-256 checksum
How to use checksums
62848d6f50591005d1c95d1b65d6b6c9d945eb762d49c85e6d206e761758a4df
BLAKE2b-256 checksum
How to use checksums
9f65be43878d6a12d660763bf5dc3f2fda8916bb464fc8b814015ab2d46409ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / governed_ai_agent_blueprint-0.3.1-py3-none-any.whl

Download URL governed_ai_agent_blueprint-0.3.1-py3-none-any.whl
Size 11.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9a24e8449fe4a548bd1cf8223a3b36c67817d6f07e7610caba3b53c32908c2e6
BLAKE2b-256 checksum
How to use checksums
001f74e71d1c5cf4081f1169acee2619b697e7a2a44d7fec6a6dc8c7100446dc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for governed-ai-agent-blueprint 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for governed_ai_agent_blueprint-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page