Agent Sentinel SDK

The runtime authority for AI agents. Every tool call your agent makes is authorized before it runs, budgets are reserved before execution, and what happened is recorded in a ledger you can verify.

Documentation · Console · Website · Changelog

What it does

Observability tells you what happened. Agent Sentinel decides what is allowed to happen, before it does. Two ways to put it in front of your agent:

• In-process, with the SDK. Decorate functions with @guarded_action. Policy, budgets, approvals, loop protection and PII/moderation guardrails run before the function body does. No approval, no execution.
• In front of every MCP tool call. agentsentinel-mcp and agentsentinel-runtime connect Claude Code, Cursor or any MCP client to the hosted gateway, so each tools/call is authorized first and the model never holds the credential.

What you get:

• Hard budget caps per action, run and session, reserved before execution
• Deny lists, allow lists, rate limits and policy-as-YAML
• Human approval workflows for sensitive actions
• Fail-closed by default for writes (since 0.4.0)
• Secrets redacted from ledger inputs before they are written or uploaded
• A local JSONL ledger, plus remote sync to the hosted platform, where ledger rows are Ed25519-signed and the chain can be verified from the console or API
• Remediation on every block (retry guidance, safe alternatives) so an agent can self-correct

Installation

pip install agentsentinel-sdk                  # core: decorator, policy, local ledger
pip install "agentsentinel-sdk[remote]"        # sync to the hosted platform
pip install "agentsentinel-sdk[mcp]"           # agentsentinel-mcp and agentsentinel-runtime
pip install "agentsentinel-sdk[langchain]"     # LangChain callbacks
pip install "agentsentinel-sdk[crewai]"        # CrewAI callbacks
pip install "agentsentinel-sdk[llm]"           # OpenAI, Anthropic, Grok, Gemini helpers
pip install "agentsentinel-sdk[integrations]"  # all framework integrations
pip install "agentsentinel-sdk[all]"           # everything

The package needs Python 3.11+. For development, work from packages/agent-sentinel-sdk in the monorepo with uv sync.

Quick Start

Basic Usage

from agent_sentinel import guarded_action

# Decorate any function to track it. impact="read" declares this as a
# read: since 0.4.0 the default enforcement mode blocks unconfigured
# actions of impact "medium"/"high" (see Enforcement modes below).
@guarded_action(name="search_tool", cost_usd=0.01, tags=["search", "api"], impact="read")
def search_web(query: str) -> dict:
    """Search the web for a query"""
    results = call_search_api(query)
    return {"results": results, "count": len(results)}

# Use it normally - telemetry happens automatically
response = search_web("Python best practices")

Async Support

@guarded_action(name="generate_text", cost_usd=0.05, tags=["llm"])
async def generate_text(prompt: str) -> str:
    """Generate text using an LLM"""
    response = await openai_client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

# Async works automatically
result = await generate_text("Write a haiku about Python")

Complex Objects

The SDK handles complex, non-serializable objects gracefully:

from dataclasses import dataclass
import socket

@dataclass
class Context:
    user_id: int
    session: str
    connection: socket.socket  # Not JSON-serializable!

@guarded_action(name="process_data", cost_usd=0.001)
def process_data(ctx: Context, data: dict):
    # Complex objects are automatically stringified
    return {"processed": True, "user": ctx.user_id}

# No crashes even with non-serializable objects!
ctx = Context(user_id=123, session="abc", connection=socket.socket())
process_data(ctx, {"value": 42})

MCP authority

Every MCP tools/call goes through the gateway's authorize decision before the tool executes (allow, deny or require approval), and the result is recorded as a ledger row. Two stdio entry points ship in the [mcp] extra:

agentsentinel-mcp

A stdio MCP server for MCP-native harnesses such as Claude Code and Cursor. It answers initialize locally and forwards tools/list and tools/call to the platform's /mcp endpoint with an agent-bound API key, so the harness gets governed tools and the model never sees a credential. Results pass through unchanged, including isError and structuredContent.reason_code on refusals.

{
  "mcpServers": {
    "agentsentinel": {
      "command": "agentsentinel-mcp",
      "env": {
        "AGENT_SENTINEL_API_KEY": "<agent-bound API key>",
        "AGENT_SENTINEL_HARNESS": "claude-code"
      }
    }
  }
}

Put this in .mcp.json for Claude Code or .cursor/mcp.json for Cursor. The file then holds the key, so keep it out of version control, or use agentsentinel-runtime below to keep the key out of the workspace entirely.

• AGENT_SENTINEL_API_KEY (required) must be an agent-bound key.
• AGENT_SENTINEL_URL (optional) overrides the hosted platform URL for self-hosted or staging; the proxy targets <url>/mcp. https is required unless the host is localhost or 127.0.0.1.
• AGENT_SENTINEL_HARNESS (optional) is sent as X-Sentinel-Harness.

This is the beginning of the README. Read the rest at the original. Read the full README ↗