Skip to main content
Agent Sentinel is a monorepo with three runtime surfaces:
  • Python SDK: instruments agent actions, enforces local and synced policies, writes the local ledger, and optionally uploads telemetry.
  • Platform API: ingests telemetry, stores runs/actions/policies, serves governance APIs, and broadcasts real-time events.
  • Web Console: gives operators visibility and control over runs, interventions, approvals, policies, replay, analytics, and agents.
Supporting packages and apps exist for benchmarks, canary validation, marketing, and generated clients, but the SDK, platform API, and console are the core product.

​
Repository Map

agent-sentinel/
├── apps/
│   ├── platform/          # FastAPI backend, DB models, migrations, API routes
│   ├── console-sentinel/  # Next.js operator console
│   └── web/               # Public web/marketing app
├── packages/
│   ├── agent-sentinel-sdk/  # Python SDK package
│   └── agent-sentinel-gym/  # Benchmarks/evaluation package
├── platform-canary/       # End-to-end reference and validation app
├── examples/              # Cross-package examples
├── benchmarks/            # Benchmark output and reports
└── docs/                  # Canonical documentation

​
Runtime Flow

Agent code
  |
  | @guarded_action / SDK integrations
  v
SDK policy engine
  |-- local policy config
  |-- remote policy cache
  |
  | allowed action
  v
User function executes
  |
  v
Local ledger JSONL
  |
  | optional background sync
  v
Platform API ingest
  |
  v
Postgres
  |
  | REST + WebSocket APIs
  v
Console and API consumers

​
Core Boundaries

​
SDK

The SDK owns runtime instrumentation and local enforcement:
  • @guarded_action and integration adapters wrap actions.
  • Policy checks happen before action execution.
  • Ledger writes happen after execution.
  • Telemetry failures should not crash user code.
  • Policy violations intentionally block execution.
  • Remote sync is optional and backgrounded.
The SDK must remain lightweight. Optional integrations should stay behind extras such as remote, llm, integrations, or all.

​
Platform API

The platform owns shared state and governance workflows:
  • Ingests runs, actions, interventions, replay summaries, and compliance metadata.
  • Stores policy state and exposes policy sync APIs to SDK clients.
  • Serves approval, ledger, agent, analytics, replay, MCP, and compliance APIs.
  • Emits WebSocket events for the console.
  • Applies authentication and tenant boundaries before returning organization data.
The platform is the source of truth for organization-wide policy and audit state. SDK-local state is a cache or local fallback.

​
Console

The console owns operator workflows:
  • Explore runs and actions.
  • Review interventions and approval requests.
  • Manage API keys, policies, integrations, and settings.
  • Trigger and inspect replay/determinism workflows.
  • Surface analytics, agents, and compliance/audit state.
Console docs belong in docs/console/. API behavior belongs in docs/platform/.

​
Data Model

The durable product model is:
  • Organization / tenant: isolation boundary for users, agents, policies, and telemetry.
  • Agent: logical autonomous system or integration source.
  • Run: one execution session for an agent.
  • Action: one instrumented tool/function/LLM call within a run.
  • Policy: organization-level control rules synced to SDK clients.
  • Intervention: a policy or guardrail decision that blocked, required approval, or otherwise changed execution.
  • Approval: human decision record for sensitive actions.
  • Ledger entry: audit representation of action execution and metadata.
  • Replay summary: local replay outcome, divergence data, determinism score, and estimated savings.

​
Design Principles

  • Runtime authority first: Agent Sentinel decides whether an autonomous action may proceed, not merely whether it should be logged.
  • Local-first SDK, platform-backed governance: agents can write local ledgers and enforce local policy; organization policy and audit state are centralized in the platform.
  • Fail-open telemetry, fail-closed enforcement: logging/sync failures should not crash agents, but policy violations block by design.
  • Explicit tenant boundaries: platform and console behavior must preserve organization isolation.
  • Evidence over claims: public docs and marketing claims must match shipped behavior or clearly label roadmap items.

​
Where Architecture Changes Go

Update this page when changing the product shape, runtime flow, service boundaries, or durable data model. Do not create a second architecture document. If a proposal needs temporary detail, put it under docs/archive/ after the decision is made and fold the final decision back here.