Governed AI Agent Blueprint
A small, executable reference architecture for grounded and auditable AI agents.
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
LanguageModelprotocol
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.