{"id":46574812,"url":"https://github.com/dgenio/agent-kernel","last_synced_at":"2026-06-07T07:02:10.535Z","repository":{"id":341670754,"uuid":"1171022621","full_name":"dgenio/agent-kernel","owner":"dgenio","description":"Capability-based authorization and policy enforcement for agents using large MCP and A2A tool ecosystems.","archived":false,"fork":false,"pushed_at":"2026-06-05T05:33:32.000Z","size":680,"stargazers_count":1,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T07:31:51.740Z","etag":null,"topics":["a2a","agent-security","ai-agents","authorization","capability-based-security","mcp","policy-engine","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dgenio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-02T19:40:10.000Z","updated_at":"2026-06-05T05:33:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dgenio/agent-kernel","commit_stats":null,"previous_names":["dgenio/agent-kernel"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/dgenio/agent-kernel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fagent-kernel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fagent-kernel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fagent-kernel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fagent-kernel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dgenio","download_url":"https://codeload.github.com/dgenio/agent-kernel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dgenio%2Fagent-kernel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34011813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","agent-security","ai-agents","authorization","capability-based-security","mcp","policy-engine","python"],"created_at":"2026-03-07T09:23:52.370Z","updated_at":"2026-06-07T07:02:10.529Z","avatar_url":"https://github.com/dgenio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-kernel\n\n[![CI](https://github.com/dgenio/agent-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/dgenio/agent-kernel/actions/workflows/ci.yml)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n**Least-privilege, revocable, principal-scoped authorization for agent tool calls — with a tamper-evident audit of everything that ran.**\n\nA capability-based security kernel for AI agents operating in large tool ecosystems (MCP, A2A, 1000+ tools).\n\nEvery tool call gets a **capability token** (HMAC-signed, time-bounded, scoped to one principal and one capability) and a **tamper-evident audit trace** (`ActionTrace`) recording who invoked what, under which policy decision, with what result. That **authorization + audit** layer is `agent-kernel`'s unique contribution to the [Weaver stack](#part-of-the-weaver-stack) — neither `contextweaver` nor `AgentFence` provides it.\n\n### Why `agent-kernel` and not `contextweaver` or `AgentFence`?\n\n- **`contextweaver`** decides *what context the LLM sees*. **`agent-kernel`** decides *what the agent is allowed to run, and proves what it ran.*\n- **`AgentFence`** is an external proxy that gates tool calls *at the process boundary*. **`agent-kernel`** is the *in-process* runtime that mints the capability token, enforces policy, firewalls the result, and writes the audit trace — compiled into your agent host.\n- They compose: author policy once and enforce it both embedded (`agent-kernel`) and at the edge (`AgentFence`); produce a `Frame` in `agent-kernel` and let `contextweaver` do budgeted selection over it. See the boundary notes below.\n\n## 30-second pitch\n\nModern AI agents face three hard problems when given access to hundreds or thousands of tools:\n\n1. **No authorization or audit** — nothing scopes what a tool call may do, and there's no record of what ran, when, and why.\n2. **Tool-space interference** — agents accidentally invoke the wrong tool or escalate privileges.\n3. **Context blowup** — raw tool output floods the LLM context window.\n\n`agent-kernel` solves all three with a thin, composable layer that sits above your tool execution layer. The first two features are its **unique, non-overlapping contribution**; the last two it *also* provides, with explicit boundaries against its siblings:\n\n- **Capability Tokens** *(unique to agent-kernel)* — HMAC-signed, time-bounded, principal-scoped. No token → no execution.\n- **Audit Trail** *(unique to agent-kernel)* — every invocation creates an `ActionTrace` retrievable via `kernel.explain()`.\n- **Policy Engine** *(boundary vs AgentFence)* — READ/WRITE/DESTRUCTIVE safety classes + PII/PCI sensitivity handling, enforced **in-process**. `AgentFence` enforces an equivalent gate at the **external boundary**; the goal is to author one policy and enforce it both places (shared-policy contract — [#111](https://github.com/dgenio/agent-kernel/issues/111)).\n- **Context Firewall** *(boundary vs contextweaver)* — raw driver output is *never* returned to the LLM; always a bounded `Frame`. `agent-kernel` is the **producer** of the canonical `Frame` at the execution boundary; `contextweaver` is a **consumer** that does budgeted selection over Frames — deliberate layering, not redundancy (canonical-`Frame` seam — [#110](https://github.com/dgenio/agent-kernel/issues/110)).\n\n## Architecture\n\n```mermaid\ngraph LR\n    LLM[\"LLM / Agent\"] --\u003e|goal| K[\"Kernel\"]\n    K --\u003e|search| REG[\"Registry\"]\n    K --\u003e|evaluate| POL[\"Policy Engine\"]\n    K --\u003e|sign| TOK[\"HMAC Token\"]\n    K --\u003e|route| DRV[\"Driver (MCP/HTTP/Memory)\"]\n    DRV --\u003e|RawResult| FW[\"Context Firewall\"]\n    FW --\u003e|Frame| LLM\n    K --\u003e|record| AUD[\"Audit Trace\"]\n```\n\n## Part of the Weaver Stack\n\n`agent-kernel` is the **execution / authorization runtime** of the **Weaver\nstack** — a set of composable, independently usable projects for building safe\nLLM-agent systems. On the request path:\n\n```\ncontextweaver  ─►  ChainWeaver   ─►  agent-kernel        ─►  AgentFence\n(select \u0026          (deterministic     (capability tokens,     (external policy\n compile context)   tool chains)        policy, firewall,       gate at the edge)\n                                         tamper-evident audit)\n```\n\n| Project | Role in the stack |\n|---|---|\n| [contextweaver](https://github.com/dgenio/contextweaver) | Selects and compiles the context the LLM sees. |\n| ChainWeaver | Orchestrates deterministic multi-step tool chains. |\n| **agent-kernel** *(this repo)* | Authorizes, executes, firewalls, and audits tool calls in-process. |\n| [AgentFence](https://github.com/dgenio/AgentFence) | Enforces a policy gate at the external process boundary. |\n| [weaver-spec](https://github.com/dgenio/weaver-spec) | The shared contracts (invariants; capability/token/`Frame`/policy) the others conform to. |\n\n**Standalone by design.** `agent-kernel` has no hard dependency on any sibling\nproject — its only runtime dependencies are `httpx` and `pydantic`. Use it on\nits own, or compose it with the rest of the stack; the siblings interoperate\nthrough the shared [weaver-spec](https://github.com/dgenio/weaver-spec)\ncontracts, not through tight coupling. A deeper, per-project comparison —\nincluding *when not* to reach for `agent-kernel` — is in\n[How this relates to neighboring projects](#how-this-relates-to-neighboring-projects).\n\n## Quickstart\n\n```bash\npip install weaver-kernel\n```\n\n```python\nimport weaver_kernel\n```\n\n\u003e ### 📦 Repo ↔ package ↔ import — read this once\n\u003e\n\u003e | Where you see it | Name |\n\u003e |---|---|\n\u003e | GitHub repository | `dgenio/agent-kernel` |\n\u003e | PyPI — what you `pip install` | **`weaver-kernel`** |\n\u003e | Python — what you `import` | **`weaver_kernel`** |\n\u003e\n\u003e **Decision (2026-06):** the install name and the import name are unified on\n\u003e **`weaver-kernel` / `weaver_kernel`** — the two names you actually type. There\n\u003e is **no `agent_kernel` import any more**; use `weaver_kernel`. The GitHub repo\n\u003e keeps its historical `agent-kernel` slug for now (GitHub redirects old URLs);\n\u003e the package is part of the [**Weaver stack**](#part-of-the-weaver-stack), which\n\u003e is why the distribution is `weaver-`prefixed. See\n\u003e [docs/architecture.md](docs/architecture.md#naming) for the full rationale.\n\n\u003e **New here?** [docs/tutorial.md](docs/tutorial.md) walks through register → grant → invoke → expand → explain in five minutes.\n\n```python\nimport asyncio, os\nos.environ[\"WEAVER_KERNEL_SECRET\"] = \"my-secret\"\n\nfrom weaver_kernel import (\n    Capability, CapabilityRegistry,\n    InMemoryDriver, Kernel, Principal, SafetyClass, StaticRouter,\n)\nfrom weaver_kernel.models import CapabilityRequest\n\n# 1. Register a capability\nregistry = CapabilityRegistry()\nregistry.register(Capability(\n    capability_id=\"tasks.list\",\n    name=\"List Tasks\",\n    description=\"List all tasks\",\n    safety_class=SafetyClass.READ,\n    tags=[\"tasks\", \"list\"],\n))\n\n# 2. Wire up a driver\ndriver = InMemoryDriver()\ndriver.register_handler(\"tasks.list\", lambda ctx: [{\"id\": 1, \"title\": \"Buy milk\"}])\n\n# 3. Build the kernel\nkernel = Kernel(registry=registry, router=StaticRouter(routes={\"tasks.list\": [\"memory\"]}))\nkernel.register_driver(driver)\n\nasync def main():\n    principal = Principal(principal_id=\"alice\", roles=[\"reader\"])\n\n    # 4. Discover → grant → invoke → expand → explain\n    token = kernel.get_token(\n        CapabilityRequest(capability_id=\"tasks.list\", goal=\"list tasks\"),\n        principal, justification=\"\",\n    )\n    frame = await kernel.invoke(token, principal=principal, args={})\n    print(frame.facts)           # ['Total rows: 1', 'Top keys: id, title', ...]\n    print(frame.handle)          # Handle(handle_id='...', ...)\n\n    # `principal` is required: the handle is bound to the granting principal,\n    # so an omitted principal raises HandleConstraintViolation.\n    expanded = kernel.expand(\n        frame.handle, query={\"limit\": 1, \"fields\": [\"title\"]}, principal=principal\n    )\n    print(expanded.table_preview)  # [{'title': 'Buy milk'}]\n\n    trace = kernel.explain(frame.action_id)\n    print(trace.driver_id)       # 'memory'\n\nasyncio.run(main())\n```\n\n\u003e This snippet is extracted and executed by CI (`tests/test_readme_quickstart.py`), and\n\u003e a standalone runnable mirror lives at\n\u003e [`examples/readme_quickstart.py`](examples/readme_quickstart.py) (run by `make example`).\n\u003e CI fails if either stops producing the documented output, so this quickstart cannot\n\u003e silently drift from the working API.\n\n## Where it fits\n\n```\n┌─────────────────────────────────────────────┐\n│             LLM / Agent loop                │\n├─────────────────────────────────────────────┤\n│  agent-kernel  ← you are here               │\n│  (registry · policy · tokens · firewall)    │\n├────────────────┬────────────────────────────┤\n│  contextweaver │  tool execution layer       │\n│  (context      │  (MCP · HTTP · A2A ·        │\n│   compilation) │   internal APIs)            │\n└────────────────┴────────────────────────────┘\n```\n\n`agent-kernel` sits **above** `contextweaver` (context compilation) and **above** raw tool execution. It provides the authorization, execution, and audit layer.\n\n## How this relates to neighboring projects\n\n`agent-kernel` is the embeddable runtime layer of the **Weaver ecosystem**. The\nprojects below solve adjacent problems and are designed to compose, not to\noverlap.\n\n| Project | Role | Where it runs | Use it when… |\n|---|---|---|---|\n| **agent-kernel** *(this repo)* | Embeddable library/runtime: capability registry, policy, HMAC tokens, context firewall, audit trace. | In-process inside your agent host. | You need authorization, redaction, and audit between an LLM loop and a large tool ecosystem. |\n| [**AgentFence**](https://github.com/dgenio/AgentFence) | External CLI / local proxy that intercepts tool calls and applies a policy gate. | Out-of-process, alongside your agent. | You want a policy boundary without changing your agent code, or you need to gate a third-party agent host you can't modify. |\n| [**contextweaver**](https://github.com/dgenio/contextweaver) | Library that selects and compiles the context an LLM receives. | In-process, before the LLM call. | You need to assemble relevant context for a prompt. It sits *under* the LLM loop; agent-kernel sits *between* the LLM and tools. |\n| **ChainWeaver** | Orchestrator for deterministic tool chains. | In-process or as a separate service. | You need to run a multi-step deterministic flow rather than free-form LLM tool use. |\n| [**weaver-spec**](https://github.com/dgenio/weaver-spec) | Specification: invariants, capability/token/frame contracts, conformance suite. | Not a runtime — it's docs + a contract test suite. | You're building another Weaver-compatible implementation, or you want to verify an existing one. |\n\nA minimal architecture using `agent-kernel` as the central runtime:\n\n```\nLLM / agent loop\n       │\n       ▼\ncontextweaver  ─►  agent-kernel  ─►  driver  ─►  MCP / HTTP / A2A / internal API\n                       │\n                       ▼\n                  ActionTrace\n```\n\n### When *not* to use this\n\n- You only need a process-level policy gate around an existing agent host —\n  reach for `AgentFence` instead.\n- You only need to compile context for a prompt — use `contextweaver`.\n- You want a deterministic, scripted workflow with no LLM in the inner loop —\n  use `ChainWeaver`.\n- You're writing a static analyzer or one-shot CLI scanner with no\n  per-invocation runtime — `agent-kernel` would be overkill.\n\nSee [docs/tutorial.md](docs/tutorial.md) for an end-to-end \"secure your first\nMCP tool in 5 minutes\" walkthrough.\n\n## Weaver Spec Compatibility: v0.1.0\n\nagent-kernel is a compliant implementation of [weaver-spec v0.1.0](https://github.com/dgenio/weaver-spec).\nThe following invariants are satisfied:\n\n| Invariant | Description | How agent-kernel satisfies it |\n|-----------|-------------|-------------------------------|\n| **I-01** | LLM never sees raw tool output by default | `Context Firewall` always transforms `RawResult → Frame`; raw driver output is not returned by default, and non-admin principals cannot obtain `raw` response mode |\n| **I-02** | Every execution is authorized and auditable | `PolicyEngine` authorizes at grant time; a valid `CapabilityToken` (HMAC-verified on every `invoke()`) carries the authorization decision; `TraceStore` records every `ActionTrace` |\n| **I-06** | CapabilityTokens are scoped | Tokens bind `principal_id + capability_id + constraints` with an explicit TTL; `revoke(token_id)` / `revoke_all(principal_id)` are supported |\n\nSee [docs/agent-context/invariants.md](docs/agent-context/invariants.md) for the full internal invariant list and [weaver-spec INVARIANTS.md](https://github.com/dgenio/weaver-spec/blob/main/docs/INVARIANTS.md) for the specification.\n\n## Security disclaimers\n\n\u003e **v0.1 is not production-hardened for real authentication.**\n\n- HMAC tokens are tamper-evident (SHA-256) but **not encrypted**. Do not put sensitive data in token fields.\n- Set `WEAVER_KERNEL_SECRET` to a strong random value in production. If unset, a random dev secret is generated per-process with a warning.\n- PII redaction is heuristic (regex). It is not a substitute for proper data governance.\n- See [docs/security.md](docs/security.md) for the full threat model.\n\n## Documentation\n\n- [Architecture](docs/architecture.md)\n- [Security model](docs/security.md)\n- [Integrations (MCP, HTTPDriver)](docs/integrations.md)\n  - [contextweaver: policy before action](docs/integrations/contextweaver.md)\n  - [Repository safety checks as a capability](docs/integrations/repository_safety_check.md)\n  - [ChainWeaver compiled flows as capabilities](docs/integrations/chainweaver.md)\n  - [Policy guardrails for evaluation artifacts](docs/integrations/evaluation_artifacts.md)\n- [Designing capabilities](docs/capabilities.md)\n- [Context Firewall](docs/context_firewall.md)\n\n## Development\n\n```bash\ngit clone https://github.com/dgenio/agent-kernel\ncd agent-kernel\npip install -e \".[dev]\"\nmake ci      # fmt-check + lint + type + test + examples\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdgenio%2Fagent-kernel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdgenio%2Fagent-kernel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdgenio%2Fagent-kernel/lists"}