[Example] End-to-end sample app: LLM agent with kernel-secured tools behind a web API

[dgenio]

Summary

Add a complete, realistic sample application: a small FastAPI service hosting an LLM agent whose tools are all registered as kernel capabilities — per-request principals derived from the API caller, declarative policy, firewalled Frames back to the model, and an /audit endpoint exposing the action traces for the session.

Why this matters

Every existing example demonstrates one mechanism in isolation. Adopters evaluating the library need to see the whole shape at once: where the kernel object lives in an app, how web-layer identity becomes a Principal, how the middleware adapters sit in the agent loop, and what the audit payoff looks like. A single coherent reference app is the strongest "I can see myself using this" artifact short of production use.

Proposed scope

• examples/sample_app/ (self-contained package): FastAPI app, agent loop using the existing OpenAIMiddleware or AnthropicMiddleware, 3–4 tools of mixed safety classes (e.g., search READ, create-ticket WRITE, delete-ticket DESTRUCTIVE), declarative policy file, and an /audit endpoint rendering recent ActionTrace records.
• Offline mode by default: a scripted fake LLM client driving a deterministic tool sequence so the app runs in make ci with no network or API key; a real-LLM mode behind an env var (network examples need a fallback per repo convention).
• Demonstrate one denial (DESTRUCTIVE without admin role) and one handle expansion in the scripted flow.
• A walkthrough doc (docs/sample_app.md or README inside the example) narrating the request path end to end.

Implementation notes

• FastAPI is a dev-time example dependency only — keep it out of runtime deps; either an examples extra or a documented pip install fastapi uvicorn step, with the CI-run path importable without serving (call the app functions directly or use httpx's ASGI transport, already a runtime dep).
• Principal derivation: API key header → static principal map (demo identity; link the security disclaimers).
• Reuse adapters/ middleware rather than re-implementing the loop; this doubles as living documentation for the adapters, which currently have no end-to-end example.
• Keep modules small per repo convention; the example may be multiple files.

Acceptance criteria

• Sample app runs fully offline with a deterministic scripted agent and passes in make ci.
• Shows allow, deny (with stable reason code), handle expansion, and the audit endpoint in one session.
• Real-LLM mode documented behind an env var with graceful fallback.
• Walkthrough doc linked from README and docs/integrations.md.

Out of scope

• Deployment assets (Docker, k8s) — possible follow-up.
• Multi-tenant auth done properly (demo identity only, clearly labeled).
• New kernel features; this is composition of what exists.

References

• In-repo: adapters/openai.py, adapters/anthropic.py, examples/http_driver_demo.py (offline-server pattern), examples/billing_demo.py.

---

Priority: P2 · Effort: M · Impact: High