Measure integrity. Enforce authority. Verify outcomes.
Quick Start · Demo · Architecture · Security Controls · Frameworks · Documentation
AI agents do more than generate responses. They execute code, access sensitive systems, use tools with real consequences, and delegate tasks to other agents.
Agentegrity is an open-source framework for assessing the integrity of those systems, evaluating adversarial behavior and drift, enforcing explicit authorization on supported tool actions, and producing evidence of decisions and downstream effects.
Use it to observe your existing agent, enforce task-bound authority at a trusted execution boundary, and verify what the evidence actually establishes. It complements service-side access control, sandboxes, guardrails, and independent monitoring; it does not replace them.
| Observe | Enforce | Verify | Recover |
|---|---|---|---|
| Detect adversarial signals, drift, and integrity degradation | Constrain supported tool actions using trusted task mandates | Record decisions and reconcile downstream effects | Evaluate continuity, checkpoints, and recovery mechanisms |
v0.13.0 is published on PyPI and npm (2026-10-21). The Runtime Action Authority APIs are new in v0.13.0, so an installed v0.12.0 does not have them; run pip install -U agentegrity to upgrade. See the changelog.
An agent has a permitted transfer tool, but its task authorizes only a single synthetic account. A request for a different account is stopped at the tool execution boundary. A permitted action returns, but remains pending until a trusted host checks its downstream evidence.
The animation is a replay of the output asserted by the repository's example tests, not a literal screen recording or a real banking integration. It uses no real accounts, external evidence attestation, or production attack. Run the exact synthetic example.
Dependency security notice for v0.13.0: The base Python package has no required framework dependencies, but installing the optional CrewAI integration or using an AI SDK v5 application can introduce known upstream vulnerabilities, including code injection, authorization and denial-of-service risks. The temporary distribution-only risk disposition does not approve insecure deployments. Review the advisory and deploy with patched upstream components and restricted network boundaries.
pip install agentegrity
python -m agentegrity doctorTo evaluate an agent profile directly:
from agentegrity import AgentegrityClient
client = AgentegrityClient()
score = client.evaluate(client.create_profile(name="my-agent"))
print(f"Integrity: {score.composite:.3f} — action: {score.action}")Or instrument an existing supported agent using its framework integration. For example, with Claude Agent SDK:
pip install "agentegrity[claude]"from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from agentegrity.claude import hooks, report
# Inside an async function:
async with ClaudeSDKClient(
options=ClaudeAgentOptions(hooks=hooks())
) as agent:
await agent.query("Summarize this document")
print(report())This hook example uses measure-only semantics by default, not automatic tool blocking. See the framework quickstart for LangChain/LangGraph, CrewAI, OpenAI Agents, Google ADK, coding agents, and TypeScript.
To try the new task-scoped Python APIs before they appear in a published release:
git clone https://github.com/Cogensec/agentegrity.git
cd agentegrity
pip install -e .
python examples/action_authority_evidence.pyThe offline, test-covered example prints:
Out-of-scope action: denied
Before simulated evidence verification: pending
After simulated evidence verification: confirmed
The example uses TaskMandate and ToolAuthority to authorize a specific tool, resource, and effect. ActionSecurityGate.invoke() checks authority before the synthetic executor runs. The successful return stays PENDING; only an application-owned verifier consulting the example's separate, in-memory synthetic ledger promotes the receipt to CONFIRMED.
That ledger is a teaching aid, not independent proof of an external effect. In production, the verifier must authenticate an authoritative downstream system and bind the evidence to the action, principal, run, resource, and effect.
Explore the runnable example → · Runtime Action Authority guide →
Agentegrity has two complementary integration paths:
- Observe and evaluate: Supported framework adapters capture available lifecycle events; the Python evaluation pipeline processes integrity signals, records decisions, and can append attestations signed with configured keys. TypeScript packages capture and stream events but do not run the Python evaluator or create its local attestation chain.
- Authorize and reconcile: A trusted application controller supplies task permissions, tool declarations, and (where used) provenance. The Python
ActionSecurityGatecan deny a wrapped action before execution. A return value is not treated as downstream proof; the host must reconcile independent evidence.
A pre-tool observation hook is not inherently a hard execution gate. For strict action authorization, integrate invoke() or ainvoke() at the trusted executor and enforce access again at the downstream service.
| Layer | What it evaluates |
|---|---|
| Adversarial | Threat patterns, suspicious inputs and tools, and supported adversarial signals |
| Cortical | Reasoning consistency, memory-related signals, behavioral baselines, and drift |
| Governance | Policies, approvals, enforcement decisions, and audit evidence |
| Recovery | Integrity continuity, score degradation, checkpoints, and supported recovery mechanisms |
The layers measure observed, supported capabilities, rather than treating declarations as proof of security. Read the technical specification or architecture reference.
The opt-in Python OSS Runtime Action Authority APIs address six failure patterns. They are merged into source, but do not provide universal interception across every framework.
| Failure pattern | Control | Technical guide |
|---|---|---|
| Standing access | Run-bound, time-limited mandates and explicit tool/resource/effect/credential scopes | Runtime authority |
| First-call effects | invoke() / ainvoke() deny before trusted tool execution |
Runtime authority |
| Unclear trust boundaries | Host-captured ActionProvenance and protected control arguments |
Trust boundaries |
| Data-as-control | Treat retrieved content, tool outputs, memory, and peer messages as data, not permissions | Trust boundaries |
| Cascading delegation | Trusted host creates attenuated child mandates with bounded depth, expiry, and in-process revocation | Delegation |
| Late-arriving evidence | PENDING, UNKNOWN, CONFIRMED, FAILED, CONFLICTED receipt handling |
Effect evidence |
Important limitations: Provenance must be supplied accurately outside model control. Delegation and effect receipts are process-local, not remotely verifiable capabilities or durable queues. Timeouts require an explicit host sweep, and a conflict is not automatically repaired. A callback that always returns True is not independent verification.
| State | Interpretation | Counts as verified success? |
|---|---|---|
PENDING |
Execution began; an external outcome is not yet proven | No |
UNKNOWN |
Missing/late evidence or an execution error leaves the effect uncertain | No |
CONFIRMED |
An authenticated host verifier accepted confirmation | Only with the verified flag set by the SDK |
FAILED |
A host verifier accepted independent failure evidence | No |
CONFLICTED |
Verified downstream reports disagree | No |
A remote timeout is not proof that no external effect occurred. An apparently successful tool response is not proof of commitment. See late-arriving effect evidence.
Integrated framework families in Python, TypeScript, or both. See the capability matrix below for exact support; logos identify third-party products and do not imply endorsement.
Agentegrity offers eight Python framework adapters and six TypeScript framework packages, plus Claude Code and Codex hook integrations. Framework support means event instrumentation on supported integration surfaces; coverage and enforcement vary.
| Framework | Python | TypeScript |
|---|---|---|
| Claude Agent SDK | ✓ | ✓ |
| LangChain / LangGraph | ✓ | ✓ (LangChain package) |
| OpenAI Agents SDK | ✓ | ✓ |
| CrewAI | ✓ | ✓ |
| Google ADK | ✓ | ✓ |
| AutoGen | ✓ | — |
| Agno | ✓ | — |
| AWS Bedrock Agents | ✓ | — |
| Vercel AI SDK | — | ✓ |
| Capability | Python adapters | TypeScript packages |
|---|---|---|
| Supported agent event capture and reporting | Yes | Yes |
| Local four-layer integrity evaluation | Yes | Not provided |
| Local attestation chain and optional Ed25519 signing | Yes | Not provided |
Host-controlled ActionSecurityGate |
Separate opt-in Python API | Not provided |
| Automatic blocking of every tool/handoff | No; host-dependent | No |
Claude Code and Codex use their own hook-plugin paths. See supported integrations for implementation and known limits. Our Agent Ecosystem Integration Roadmap targets enterprise, financial, customer-facing, browser, research, infrastructure, multi-agent, coding, and longer-term embodied agents. It describes proposed integrations, not additional shipped support.
Agentegrity supports locally evaluated integrity scores, structured decisions, session evidence, and (when configured) signed attestations. Hash linkage is not the same as trusted cryptographic verification: callers must configure suitable signing keys and independently verify against trusted material.
What it can help establish: the available events an adapter observed, the policy decision for an action, whether a wrapped executor was admitted, and whether a trusted host verifier accepted an externally correlated result.
What it cannot automatically establish: that every tool call was intercepted, that an untrusted lineage report is accurate, that an external service committed or rolled back, or that the agent is immune to all prompt injection. In-process receipts do not survive application crashes without additional infrastructure.
STATUS.md reports the repository's published benchmark measurements and their limitations. Those results must not be generalized outside their stated datasets or configurations. The planned 100-run synthetic banking-agent evaluation is a future research milestone, not a completed benchmark or a published prevention-rate claim.
Core Python evaluation is local unless optional integrations are enabled. Anonymous, shape-only usage telemetry is on by default, excluding prompt and tool content. Disable it with:
export DO_NOT_TRACK=1
# or
export AGENTEGRITY_TELEMETRY_DISABLED=1Session exporters may send full agent content, while opt-in LLM-backed evaluators may send classified content to their configured model endpoint. Review destination and credential handling before enabling either.
Telemetry details → · Security and supported versions →
| Resource | Purpose |
|---|---|
| Quickstart | Installation, sample evaluations, and framework adapters |
| Specification | Integrity properties, scoring and architecture |
| Action authority | Task scopes and execution-boundary enforcement |
| Trust boundaries | Protected arguments and trusted provenance |
| Delegation | Bounded subagent authority and revocation |
| Effect evidence | Deadlines, late outcomes, and conflicts |
| Example | Runnable offline authorization demonstration |
| Research status | Benchmark figures, methods, and limitations |
| Agent Ecosystem Roadmap | Planned coverage across digital and physical agent categories; not shipped support |
| Changelog | Releases and unreleased work |
| Manifesto | Research motivation and discipline |
| Contributor guide | Development and contribution guidelines |
Contributions and independent adversarial reproduction are welcome, especially for execution-boundary adapters, trusted evidence verification, distributed delegation, recovery validation, and cross-framework conformance.
Contributing guide · Open issues
If you use Agentegrity in research:
@misc{agentegrity2026,
title={The Agentegrity Framework: Building and Verifying Self-Securing Autonomous AI Agents},
author={Cogensec Research},
year={2026},
url={https://github.com/Cogensec/agentegrity}
}Apache License 2.0. See LICENSE.
Agentegrity is a Cogensec Research initiative. The framework and specification are open; the research is ongoing, and independent evaluation is encouraged.
