Agentium
The Zero-Dependency Context and Trust Integrity Toolkit for Autonomous AI Agents
Agentium is an open-source engineering toolkit designed to guarantee context survival, claim grounding, and safe execution across multi-agent pipelines and long-running autonomous workflows.
Table of Contents
- The Core Challenge in Autonomous Agents
- Zero Runtime Dependency Guarantee
- Quick Start Guide for Beginners
- Comprehensive Feature Walkthrough
- Feature 1: Context Pins and Compaction Guard
- Feature 2: Action Gate - Shadow and Enforce Modes
- Feature 3: Evidence-Based Claims and Peer Agreement Defense
- Feature 4: Multi-Agent Lineage Graph and Root-Cause Blame
- Feature 5: Handoff Contracts and Token Envelopes
- Feature 6: Speculative Read-Only Prefetch Engine
- Feature 7: Cryptographic Run Fingerprints
- Feature 8: Continuous Integration Drift Gate
- Feature 9: Developer Diagnostics - Init and Doctor
- Feature 10: Automatic Secret and PII Redaction
- Universal Integration Hub
- Production Recipes Catalog
- Framework Adapters
- Command Line Interface Reference
- Backward Compatibility with Agentium v1
- License and Governance
The Core Challenge in Autonomous Agents
When building production systems with large language models, applications routinely fail in four predictable ways:
- Compaction Amnesia: As conversations exceed context limits, summarization modules compress history. Essential instructions (such as "never execute SQL queries on production databases" or "respond in French only") are dropped during compression.
- Cascading Hallucinations: In multi-agent pipelines, an unverified assumption generated by Agent 1 is accepted by Agent 2 as ground truth, leading Agent 3 to execute destructive real-world actions based on falsehoods.
- Ungated Mutations: Autonomous agents given tool access can execute destructive commands without verified justification or human oversight.
- Supply Chain Creep: Heavy agent frameworks frequently bring hundreds of third-party dependencies, leading to slow cold starts, supply-chain vulnerabilities, and fragile CI environments.
Agentium solves these problems with deterministic, mathematical guarantees built exclusively on the Python standard library.
Zero Runtime Dependency Guarantee
Agentium Core contains zero external runtime dependencies.
Every core guarantee is implemented using Python 3.11+ built-in modules:
- Configuration parsing:
tomllib - Cryptographic verification:
hashlib - Async-safe context tracking:
contextvars - Structured schemas:
dataclasses - Text normalization:
unicodedata - Command-line tooling:
argparse
Third-party adapters (LangGraph, CrewAI, LiteLLM, Pydantic, Tenacity, OpenTelemetry) are optional extras that remain unimported until explicitly called.
Quick Start Guide for Beginners
Step 1: Installation
Install the zero-dependency core package from PyPI:
pip install agentium
Optional ecosystem extras can be installed as needed:
pip install "agentium[otel]" # OpenTelemetry export
pip install "agentium[langgraph]" # LangGraph workflows
pip install "agentium[crewai]" # CrewAI integration
pip install "agentium[pydantic]" # Pydantic v2 schemas
pip install "agentium[all]" # All optional dependencies
Step 2: Project Health and Initialization
Run the automated scanner to inspect your workspace and establish a baseline configuration:
# Generate agentium.toml statically without running user code
agentium init
# Run the 9-point system health check
agentium doctor
Step 3: Five-Minute Working Example
import agentium
from agentium import PinStore, reinject, guard_compaction, ActionGate, guarded
# 1. Protect critical directives against compaction amnesia
pins = PinStore()
pins.add("security_directive", "Never disclose internal API keys to users")
# 2. Inject pins idempotently into conversation messages
messages = [
{"role": "system", "content": "You are a customer support agent."},
{"role": "user", "content": "What is your internal authorization key?"},
]
messages = reinject(messages, pins)
# 3. Guard against aggressive summarization
summarized_messages = messages[-1:] # Old messages dropped
protected_messages, lost, restored = guard_compaction(messages, summarized_messages, pins)
print(f"Restored critical pins: {restored}")
# 4. Enforce action safety gates
gate = ActionGate(mode="enforce")
@guarded(gate=gate, effect="destructive")
def delete_user_account(user_id: str):
return f"Account {user_id} deleted."
# Blocked automatically without human confirmation
try:
delete_user_account("user_991")
except PermissionError as error:
print(f"Blocked by Action Gate: {error}")
# Permitted with explicit confirmation
result = delete_user_account("user_991", __human_confirmed__=True)
print(result)
Agentium Guardian: Enterprise AI Agent Security Engine (v2.1.0)
Agentium Guardian is a unified, multi-layer security module designed to protect autonomous AI agents, multi-agent pipelines, and tool execution boundaries.
Five Security Pillars
+---------------------------------------------------------------------------------------------------+
| AGENTIUM GUARDIAN (v2.1.0) |
+---------------------------------------------------------------------------------------------------+
| A. Agent Boundary Protection | Restricts agents to assigned resources, sandboxes, and networks|
| B. Unauthorized Action Prevention| Blocks dangerous shell commands, SQL injections, runaway loops |
| C. AI Attack & Manipulation | Neutralizes prompt injections, goal hijacking, memory poisoning|
| D. Data Protection & Vault | Redacts secrets, masks PII, and isolates credentials in vault |
| E. Emergency Response & Recovery | Instant kill switch, automatic quarantine, hash-chained audit |
+---------------------------------------------------------------------------------------------------+
Quickstart with Guardian
from agentium import Guardian
# Initialize Guardian for your agent
guardian = Guardian(agent_id="finance_bot", strict=True)
# 1. Enforce execution boundaries
guardian.boundary.allow_resource("dataset:q4_earnings")
guardian.database_guard.read_only = True
guardian.tool_permissions.allow_agent_tool("finance_bot", "calc_revenue")
# 2. Intercept and guard tool execution
@guardian.guard
def calc_revenue(quarter: str) -> str:
return f"Revenue for {quarter}: $12,500,000"
# 3. Validate user input (blocks jailbreaks, prompt injections, and escape patterns)
guardian.validate_input("Calculate total revenue for Q4 from dataset:q4_earnings")
# 4. Safe execution
output = calc_revenue(quarter="Q4")
# 5. Sanitize outgoing output (auto-redacts leaked secrets and masks PII)
clean_output = guardian.validate_output(output)
print(clean_output)
Complete 34 Security Features
| Category | Features |
|---|---|
| A. Boundary Protection | F1: Boundary Enforcement, F2: Egress Control, F3: Internal Network / SSRF Shield, F4: Filesystem Isolation, F5: Process Isolation, F6: Resource Boundary Guard, F7: Agent Escape Detection |
| B. Unauthorized Action Prevention | F8: Tool Permission Guard, F9: Command Execution Guard, F10: Database Access Guard, F11: API Access Guard, F12: Privilege Escalation Detection, F13: Sensitive Action Approval, F14: Action Rate Limiter |
| C. AI Attack & Manipulation | F15: Prompt Injection Defense, F16: Goal Hijacking Detection, F17: Memory Poisoning Detection, F18: Tool Output Validation, F19: Agent-to-Agent Trust Verification, F20: Context Trust Classification, F21: Malicious Skill Detection |
| D. Data Protection | F22: Secret Detection, F23: Data Exfiltration Prevention, F24: PII Protection, F25: Credential Isolation, F26: Data Access Monitoring, F27: Output Security Scanner |
| E. Emergency Response | F28: Emergency Kill Switch, F29: Agent Quarantine, F30: Credential Revocation, F31: Incident Response Engine, F32: Immutable Security Audit (SHA-256 hash-chained), F33: Agent Rollback, F34: Threat Alert System |
Extended Capabilities: Features 1–45
- Execution & Reliability (
agentium.reliability): Replay Engine, Failure Recovery, Checkpointing, Automatic Retry Engine, Execution Trace, Run Comparison, Deterministic Replay. - Security & Trust Management (
agentium.trust): Runtime Policy Engine, Agent Identity, Agent Permission Manager, Agent Sandbox, Human Approval Workflow, Trust Score Engine, Security Audit Trail. - Memory & Context Intelligence (
agentium.memory): Memory Versioning, Memory Provenance, Memory Conflict Detection, Memory Expiration, Context Compression, Context Recovery, Context Consistency Validator. - Monitoring & Observability (
agentium.monitoring): Agentium Dashboard (Terminal & HTML), Token Usage Tracker, Execution Cost Guard, Performance Monitoring, Error Monitoring, Agent Health Monitor, Multi-Agent Audit Trail. - Benchmarking & Testing (
agentium.benchmark): Agentium Benchmark Suite, Context Retention Benchmark, Handoff Accuracy Benchmark, Security Testing Suite, Replay Consistency Testing, Stress Testing. - Integrations & Developer Experience (
agentium.integrations,agentium.cli): OpenAI, Anthropic, Gemini, Ollama, AWS Bedrock, LangChain, LangGraph Connectors, Developer CLI (agentium guardian,dashboard,benchmark,audit,replay), Configuration Manager, and Plugin Architecture.
Feature 1: Context Pins and Compaction Guard
Use Case
Long-running customer support chats or multi-turn coding sessions where history is continuously condensed by summarizers.
How It Works
- You register critical requirements (SLA policies, compliance rules, security constraints) in a
PinStore. reinject(messages, pins)inserts the pins into the message list. If pins already exist, it is an idempotent no-op.- When any compaction strategy (truncation, sliding window, LLM summarization) is executed,
guard_compaction(original, compacted, pins)inspects the output. If a pin was removed, it is automatically restored to the prompt context.
from agentium import PinStore, guard_compaction
pins = PinStore()
pins.add("refund_policy", "Refunds above $100 require supervisor approval")
original_chat = [
{"role": "system", "content": "You are a sales assistant. Refunds above $100 require supervisor approval."},
{"role": "user", "content": "I would like a refund of $250 for order 491."},
]
# Compactor compresses history to a brief summary
compressed_chat = [
{"role": "system", "content": "User requested refund for order 491."},
]
# Guard detects lost refund policy and restores it
safe_chat, lost_pins, restored_pins = guard_compaction(original_chat, compressed_chat, pins)
print("Protected messages:", safe_chat)
Feature 2: Action Gate - Shadow and Enforce Modes
Use Case
Protecting production systems from accidental database deletions, ungrounded financial transactions, or unauthorized cloud infrastructure modifications.
How It Works
Decorate functions with @agentium.tool(effect="read"|"mutate"|"destructive").
read: Always allowed (e.g., retrieving balance, viewing user profile).mutate: Permitted if standard execution context is valid.destructive: Blocked inenforcemode unless grounded by verified evidence or explicit human approval. Inshadowmode, actions execute while logging security telemetry.
from agentium import ActionGate, guarded
gate = ActionGate(mode="enforce")
@guarded(gate=gate, effect="destructive")
def refund_transaction(transaction_id: str, amount: float):
return f"Refunded {amount} for {transaction_id}"
# This call raises PermissionError
try:
refund_transaction("tx_881", 450.00)
except PermissionError:
print("Action blocked: unauthorized destructive mutation")
# This call succeeds
confirmed = refund_transaction("tx_881", 450.00, __human_confirmed__=True)
Feature 3: Evidence-Based Claims and Peer Agreement Defense
Use Case
Multi-agent research pipelines where one agent speculates about a financial number or medical diagnosis, and other agents repeat it as verified fact.
How It Works
ClaimStore tracks statements made by agents. A claim begins as unverified.
- Peer Agreement Defense: If another agent says "I agree with Agent 1", Agentium records the peer agreement for audit logs, but refuses to change status to verified.
- Evidence Verification: The claim only transitions to
verifiedwhen anEvidenceReflinking to an external tool call or document excerpt is supplied.
from agentium import ClaimStore, EvidenceRef
claims = ClaimStore(run_id="research_run_01")
# Agent 1 proposes an unverified statement
c1 = claims.add("Company revenue grew 34% in Q3", source_agent="extractor_agent")
assert claims.get(c1.id).status == "unverified"
# Agent 2 agrees with Agent 1
claims.record_peer_agreement(c1.id, peer_agent="analyst_agent")
assert claims.get(c1.id).status == "unverified" # Still unverified!
# Grounding evidence verifies the claim
evidence = EvidenceRef(
source_type="sec_filing",
source_id="10-Q_Q3_2026",
excerpt="Revenue increased 34% year-over-year to $4.2B",
)
claims.verify(c1.id, verifier_name="financial_auditor", evidence=evidence)
assert claims.get(c1.id).status == "verified"
Feature 4: Multi-Agent Lineage Graph and Root-Cause Blame
Use Case
Auditing complex multi-agent workflows (e.g., planner -> coder -> reviewer -> deployer) to discover which agent introduced an erroneous assumption.
How It Works
LineageGraph builds an execution DAG tracking agent delegations, tool invocations, and claim dependencies. When an error is found, graph.blame(claim_id) walks backwards through the DAG to isolate the origin agent, tools used, and intermediate hops.
from agentium import LineageGraph
graph = LineageGraph(run_id="deploy_run_12")
graph.record_agent("planner")
graph.record_agent("code_generator")
graph.record_agent("security_scanner")
graph.record_step("planner", "code_generator", message_tokens=150)
graph.record_claim_origin("claim_sql_safe", agent="code_generator")
graph.record_step("code_generator", "security_scanner", message_tokens=280)
# Automated blame report
report = graph.blame("claim_sql_safe")
print(f"Origin agent: {report.origin_agent}")
print(f"Dependency path: {report.path}")
# Export to Mermaid flowchart
print(graph.to_mermaid())
Feature 5: Handoff Contracts and Token Envelopes
Use Case
Ensuring structured context passing between agents without dropped fields, token explosions, or circular handoff loops.
How It Works
HandoffContract defines the contract between a sender and receiver. lint_handoff checks for missing required keys, circular delegation loops (A -> B -> A), and token budget violations.
from agentium import HandoffContract, HandoffPacket
contract = HandoffContract(
source_agent="triage",
target_agent="database_admin",
max_tokens=250,
required_keys=["incident_id", "severity"],
)
packet = HandoffPacket(
source_agent="triage",
target_agent="database_admin",
payload={"incident_id": "INC-404", "severity": "HIGH"},
)
validation = contract.validate(packet)
assert validation.is_valid is True
Feature 6: Speculative Read-Only Prefetch Engine
Use Case
Reducing turn latency in multi-turn tool calling pipelines by speculatively running read-only lookups in the background.
How It Works
A Markov transition model monitors sequential tool calls. When a predictable pattern occurs (such as get_order_details always being followed by get_shipping_status), Agentium speculatively executes the second tool if and only if it has effect="read". Destructive or mutating tools are strictly prohibited from speculative execution.
from agentium.speed import PrefetchEngine
engine = PrefetchEngine()
engine.record_transition("fetch_user", "fetch_permissions")
# When fetch_user is invoked, engine predicts next tool
predicted = engine.predict_next("fetch_user")
print(f"Predicted tool for prefetch: {predicted}")
Feature 7: Cryptographic Run Fingerprints
Use Case
Detecting unintended changes in system prompts, model identifiers, or tool schemas between code commits and production deployments.
How It Works
compute_fingerprint normalizes strings using Unicode NFC and produces a deterministic SHA-256 hash encompassing prompts, parameters, and tool schemas.
from agentium.fingerprint import compute_fingerprint
fp = compute_fingerprint(
model="gpt-4o",
prompt_template="You are an enterprise code reviewer.",
tools=[{"name": "lint_code", "parameters": {"type": "object"}}],
)
print("Run Fingerprint:", fp.hash)
Feature 8: Continuous Integration Drift Gate
Use Case
Preventing pull requests from silently altering agent prompts or schema definitions.
How It Works
Run agentium lock to capture approved baselines. In your CI workflow, run agentium check. If any prompt, tool argument, or model configuration drifted without an updated lockfile, the CI step exits with code 1.
# Capture approved fingerprint
agentium lock --from my_module.agent:build_pipeline
# Check in CI
agentium check --strict
Feature 9: Developer Diagnostics - Init and Doctor
Use Case
Non-destructive environment setup, configuration verification, and troubleshooting.
How It Works
agentium init: Scans workspace files to detect frameworks (LangGraph, CrewAI, OpenAI) and outputs a validagentium.tomlwithout modifying project code.agentium doctor: Runs a 9-point diagnostic verifying Python versions, config validity, event stores, lock status, pin retention rates, and lineage graph integrity.
agentium init
agentium doctor --strict
Feature 10: Automatic Secret and PII Redaction
Use Case
Preventing API keys, authorization tokens, and personal credentials from leaking into OpenTelemetry spans, logs, or JSONL trace files.
How It Works
The redaction engine evaluates outgoing event payloads against high-entropy regex patterns matching OpenAI keys (sk-...), GitHub tokens (ghp_...), Slack tokens (xoxb-...), and generic Bearer headers, replacing them with [REDACTED_API_KEY].
from agentium.core.redact import redact_payload
raw_data = {"headers": {"Authorization": "Bearer sk-proj-1234567890abcdef1234567890"}}
safe_data = redact_payload(raw_data)
print(safe_data["headers"]["Authorization"])
# Output: Bearer [REDACTED_API_KEY]
Universal Integration Hub
Agentium's integration hub allows wrapping any existing function, API client, or framework tool to instantly provide effect tagging, secret scrubbing, and action gate protection:
from agentium.hub import wrap
def fetch_weather(city: str):
return {"city": city, "temp": 72}
# Wrap function with read-only effect tag and automatic redaction
safe_fetch = wrap(fetch_weather, effect="read", redact_output=True)
result = safe_fetch("San Francisco")
Production Recipes Catalog
Agentium includes 20 pre-built Tier-1 recipes (40 sync/async twins) covering the most common agent engineering patterns:
| ID | Recipe Name | Integrated Tools | Primary Guarantee |
|---|---|---|---|
| R01 | api_call_safe |
httpx, tenacity |
Safe HTTP calls with exponential backoff and secret scrubbing |
| R03 | cached_tool |
cachetools |
Read-only TTL caching keyed on canonical argument hashes |
| R05 | validated_tool_args |
pydantic |
Automatic schema validation for LLM-generated arguments |
| R06 | structured_llm |
jsonrepair, pydantic |
Parsing and repair of malformed LLM JSON responses |
| R08 | smart_compact |
tiktoken |
Context compaction that preserves all active pins |
| R10 | llm_failover |
litellm |
Multi-model failover routing upon provider outage |
| R15 | mcp_safe_tools |
mcp |
Model Context Protocol tools gated by ActionGate |
| R22 | fuzzy_verify |
rapidfuzz |
Grounding claims against documents using fuzzy similarity |
| R23 | graph_retry |
langgraph |
Resilient LangGraph nodes with automated rollback |
| R25 | graph_tracing |
langgraph, otel |
Automated OpenTelemetry span generation for graph runs |
| R27 | protected_handoff |
pydantic, jsonschema |
Token-capped, validated inter-agent handoff envelopes |
| R28 | mcp_bridge |
mcp |
Bidirectional bridge connecting MCP tools to Agentium |
| R39 | fuzzy_dedupe_cache |
rapidfuzz |
Semantic deduplication of incoming tool arguments |
| R42 | http_cache_tool |
cachetools, httpx |
RFC-compliant HTTP caching for API tools |
| R43 | budget_llm |
litellm |
Hard token budget and cost tracking per session |
| R44 | typed_agent_tools |
openai-agents |
Type-safe tool signatures with automatic schema export |
| R45 | safe_call |
pybreaker |
Circuit breaker protection preventing cascade outages |
| R51 | drift_report |
deepdiff |
Structural diff reports across agent runs |
| R58 | verified_extract |
jmespath |
Grounded extraction generating verified claims |
Framework Adapters
Agentium adapters connect seamlessly to popular agent runtimes:
- LangGraph:
agentium.adapters.LangGraphAdapterwraps state nodes and checkpointers. - CrewAI:
agentium.adapters.CrewAIAdapterguards agent delegations and task outputs. - OpenAI Agents:
agentium.adapters.OpenAIAgentsAdapterprovides function schema generation and effect gating.
Command Line Interface Reference
# Workspace setup and validation
agentium init [--dry-run] [--force]
agentium doctor [--strict] [--json]
# Schema fingerprinting and CI gates
agentium lock --from <module:function>
agentium check [--strict] [--format text|json|md]
# Provenance and lineage analysis
agentium lineage claims <run_id>
agentium lineage blame <run_id> <claim_id>
agentium lineage diff <run_a> <run_b>
# Handoff packet validation
agentium handoff lint <path_to_json>
# Context pins and soak testing
agentium pins render [--run_id id]
agentium soak [--cycles N] [--loss-target float]
Backward Compatibility with Agentium v1
All legacy Agentium v1 text-processing classes (Condenser, Optimizer, Rearranger, Extractor, Communicator, Translator, InsightGenerator, WorkflowHelper, TemplateManager, MemoryHelper, CustomSummarizer, and LoggerUtils) remain operational:
# Legacy v1 usage continues to work seamlessly:
from agentium import Condenser, Optimizer, Agentium
agent = Agentium()
result = agent.process_content("Sample text to condense", workflow="basic")
License and Governance
Agentium is open-source software licensed under the MIT License.
Copyright (c) 2024-2026 Sanjay N.
Metadata
Release files for agentium 2.1.0
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 |
|---|---|---|---|---|
| agentium-2.1.0.tar.gz | 207.2 kB | Without provenance | Details for agentium-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentium-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentium-2.1.0-py3-none-any.whl |
Total release size: 459.3 kB
Release files / agentium-2.1.0.tar.gz
| Download URL | agentium-2.1.0.tar.gz |
|---|---|
| Size | 207.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9e1d45420f0d922e718d5c5cf36843953190b1e996dd95ef556446522d48bb31
|
|
BLAKE2b-256 checksum How to use checksums |
1f4d99e4c86902d05c1f86bee4413f87f648820666fe6840d7dae3f44dbe55f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / agentium-2.1.0-py3-none-any.whl
| Download URL | agentium-2.1.0-py3-none-any.whl |
|---|---|
| Size | 252.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b06f5bf4c4f2e5ef512bf26475f703c188cf1f81cae1fddd8ae87d7a7dce6572
|
|
BLAKE2b-256 checksum How to use checksums |
ea6b8719836095cbbcd5f7ff3d07974dbcce0119473dfe40b30d3b65dce11dee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for agentium 2.1.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.