Agents

Modular execution substrate for governed agentic workloads: enforces behavioral contracts and resource budgets between untrusted model outputs and system capabilities, with pluggable memory backends and portable skill bundles.

Status

L1 framework, the full L2 implementation wave, the L3 default-path wiring + audit wave, the third-audit + L3 capability wave, the run-provenance + provider-batch wave, the fifth-code-audit hardening (plus the post-audit approval-resume binding fix, BL-193), the BL-180 durable-adapter MVCC + transactional Protocol wave, the sixth-code-audit hardening (BL-197-208 plus the ADR 0015 deferred close BL-209-211), the BL-133 skill execution isolation Protocol + subprocess reference, the BL-212-BL-214 / BL-224 / BL-225 sweeper size-bound wave (BoundedSweepableStore extension Protocol with in-memory, SQLite, and opt-in Redis / DynamoDB / S3 references), the seventh-code-audit hardening (BL-215-BL-218), the eighth-code-audit hardening (BL-219-BL-222), the ninth-code-audit hardening (BL-223), the tenth-code-audit hardening (BL-226 / BL-227, against the just-merged BoundedS3Store), the eleventh-code-audit hardening (BL-228 / BL-229, closing the two open ADR 0020 revisit triggers), the twelfth-code-audit hardening (BL-231 / BL-232, non-finite numeric configuration validation), the thirteenth-code-audit hardening (BL-233, sweep per-item DELETE containment on the network adapters), the compaction / summarisation / tiering wave (ADR 0024, BL-234 / BL-235, closing BL-135), and the fourteenth-audit process hardening (ADR 0025, BL-236-BL-239: stale pip-audit suppression removed, lockfile-freshness CI gate, unused logfire declaration dropped, comment-accuracy fixes), and prompt caching on the runtime adapter (ADR 0026, BL-132 / BL-171: opt-in model_settings pass-through + cache-token surfacing, live cache-hit validation coupled to BL-120), and the deferred (non-replay) approval resume (ADR 0027, BL-114: opt-in approval_mode="deferred", the paused leg's history travels in ResumableState.runtime_state and prior tool calls run exactly once), the Vertex MCP analysis capability wave (ADR 0028-0038, BL-242-BL-253: hybrid retrieval fusion + decay-ranked demotion, graduated authority tiers, DEGRADED disposition + grounding, the approval-context payload, the bitemporal fact store, two-step parameter restatement, the operational-memory journal, the graceful-degradation fallback chain, read-side freshness, session rehydration, and the evidence-capture hook), and the fifteenth-code-audit hardening (ADR 0039, BL-254-BL-263: LocalSkillSource hardlink refusal, two run-time non-finite guards, the fuse_rrf distinct-rank fix, the SQLite TTL-clock ordering fix, the S3 list-vs-HEAD read-path fix, and the BoundedRedisStore.write atomicity fix) on main (see docs/backlog.md, ADR 0007, ADR 0010, ADR 0011, ADR 0012, ADR 0013, ADR 0014, ADR 0015, ADR 0016, ADR 0017, ADR 0018, ADR 0019, ADR 0020, ADR 0021, ADR 0022, ADR 0023, ADR 0024, ADR 0025, ADR 0026, ADR 0027, ADR 0028, ADR 0029, ADR 0030, ADR 0031, ADR 0032, ADR 0033, ADR 0034, ADR 0035, ADR 0036, ADR 0037, ADR 0038, ADR 0039). Every L2/L3 change is additive to the L1 Protocols: new optional parameters, new modules, and side-by-side Protocols; nothing in the L1 surface was removed. The package imports and type-checks with no optional dependencies installed.

See CLAUDE.md for repository structure and conventions.

Layout

• agents/ operator CLI (python -m agents)
• workloads/ individual agent workloads + loader (in-tree and out-of-tree)
• skills/ Agent Skills bundles, registry, dispatchers, install sources
• harness/ contracts, enforcement, runtime adapter, budgets, events
• memory/ namespace-bound stores and production adapters
• evaluation/ behavioural regression gate (dispatch P@1/MRR, trajectory)
• tests/ test suite (mirrors the source layout)
• docs/ architecture, ADRs, the L2 backlog, generated JSON Schema
• scripts/ operational and developer scripts

Capabilities

• Harness. Behavioral contracts (pre/invariant/post/governance, hard/soft severity), run_under_contract enforcement with opt-in default-path wiring (skill-contract composition, drift recording + threshold events, recovery directives, run-scoped lifecycles), action budgets (steps/tokens/wall-clock/tool-calls, per-tool quotas, plus a cost dimension and per-tool token/wall-clock caps, cumulative across an approval pause), structured OTel-ready events, Jensen-Shannon distributional drift, and opt-in self-attesting run-provenance records (record_sink, contract_digest, verify_run_record, the scripts/check_run_records.py offline gate).
• Authority, approval, and output quality (ADR 0028-0038). Graduated AuthorityTier classification (TierClassifier / MappingTierClassifier) escalating a tiered action to require-approval beyond the static list (GuardResponse.tier); an approval-context payload on the human-facing pause (ApprovalInterruption.tier / rollback_plan, RollbackPlanner / MappingRollbackPlanner); two-step parameter restatement for an irreversible (Tier 3) resume (restated_arguments); a RunRecord.degraded quality axis with deterministic anti-confabulation grounding (ungrounded_citations, grounding_predicate); read-side freshness gating via the require_fresh predicate factory, with the separate typed, model-legible Refusal return type for refusal-as-data; and an opt-in evidence-capture hook bracketing an approved Tier 3 action (EvidenceHook / EvidenceContext / RecordingEvidenceHook).
• Provider batch capabilities (optional extras). AnthropicBatchProcessor (Message Batches) and cache_control_system (prefix-stable prompt caching) under the anthropic extra; OpenAIBatchProcessor (OpenAI Batch API) under the openai extra. Async bulk at roughly 50% token price; lazily imported, the package type-checks without either SDK.
• Runtime adapter. PydanticAIRuntime wires the guard and budget into the tool-call path: every local and MCP tool call passes the same guard gate (approve / reject / require-approval), a wall-clock watchdog (preempts at an await boundary), streaming budget enforcement, a pause/ResumableState/resume approval flow (replay by default; opt-in approval_mode="deferred" continues from the paused leg's message history so prior tool calls run exactly once, BL-114), an opt-in RetryPolicy (backoff + circuit breaker), an opt-in structured soft-reject, and an opt-in model_settings pass-through with prompt-cache token surfacing (BL-132/BL-171: Anthropic cache breakpoints ride AnthropicModelSettings; cache hit/creation counts land on the BudgetTracker, not charged to max_tokens), an opt-in evidence_hook bracketing an approved irreversible action's execution, and composition via FallbackChain (an ordered runtime degradation ladder tried until one returns, distinct from RetryPolicy; a governance / budget / approval halt never reroutes). Provider selection and credentials: docs/runtime-providers.md.
• Memory. Namespace-bound MemoryStore with InMemoryStore reference plus SQLiteStore, RedisStore, S3Store, DynamoDBStore adapters; extension Protocols for batch, cursor scan, content-addressing, CAS, MVCC version tokens (VersionedMemoryStore), atomic multi-key transactions (TransactionalMemoryStore), and similarity query (SemanticMemoryStore + InMemorySemanticStore); TTLSweeper; MemoryCompactor with the Summarizer Protocol and TruncatingSummarizer reference (version-gated compaction) and TieredMemoryStore (hot/cold tiering, CAS-guarded promotion); hybrid retrieval (InMemorySemanticStore.query_hybrid, fuse_rrf Reciprocal Rank Fusion, the Reranker Protocol, decay_strength-ranked demote_to_capacity); a bitemporal fact store (BitemporalMemoryStore
  • InMemoryBitemporalStore, validity time separate from transaction time); a structured operational-memory Journal (Task / Thread / Decision / Event over any MemoryStore) with context_pack session rehydration; transparent EncryptedStore (AES-256-GCM) with static / env / file / rotating (VersionedKeyProvider) key providers, and ACLStore with role and attribute-based (AttributeACL) policies and an audited AccessDenied event, both with wrap_encrypted / wrap_acl forwarding the wrapped backend's extension Protocols truthfully; optional audit events.
• Evaluation. A behavioural regression gate: evaluate_dispatch (P@1 / MRR over a JSON golden set) and evaluate_trajectory (expected vs actual contract terminal outcome), deterministic and network-free, run as a blocking CI job via scripts/eval.py.
• Skills. Agent Skills spec-compliant loader/registry, skill versioning (name@version), seven router dispatchers (the five core keyword, LLM, lane, routing-chain, skill-based, plus the L2 multi-ensemble and embedding), an InstrumentedDispatcher telemetry wrapper, and a default_dispatcher factory for the recommended instrumented chain; a deterministic HashingEmbeddingProvider; skill-level contracts; and pluggable install sources (local, GitHub, marketplace) with bounded symlink-safe extraction, optional checksum and signature verification, and gated contract execution for untrusted bundles.
• CLI. python -m agents workloads list | skills list | skills install <name> --from <src> | run <wl> <q> [--json].

Install

uv sync --all-extras        # dev: every adapter + test doubles

Production backends are optional extras, lazily imported:

pip install 'agents[redis]'   # RedisStore
pip install 'agents[aws]'     # S3Store, DynamoDBStore
pip install 'agents[crypto]'  # EncryptedStore (AES-256-GCM)
pip install 'agents[otel]'    # OTelSink (OTLP/HTTP)

Build and test

make check     # ruff + mypy + pytest
make schema    # regenerate docs/schema/*.json from the models
uv run python scripts/eval.py   # the BL-130 dispatch regression gate

Project status and security

Pre-1.0 infrastructure. See STATUS.md for phase and document maturity, LIMITATIONS.md for explicit scope boundaries and known gaps, CHANGELOG.md for material changes, docs/releasing.md for the versioning, release, and operations policy, and SECURITY.md for the hardening posture and disclosure process. Roadmap: docs/backlog.md; decisions: docs/adr/.

License

Apache License 2.0. See LICENSE and NOTICE.