Quickstart

What you’ll build

In ~10 minutes you will:

Instrument a function with @guarded_action
Produce a local JSONL ledger at .agent-sentinel/ledger.jsonl
Connect to the Agent Sentinel cloud platform to view telemetry in real-time

Requirements:

Python 3.9+
Your agent functions already estimate or know per-call cost (USD) for cost_usd

Step 1: Install the SDK

pip install agentsentinel-sdk

To enable remote sync (platform uploads), install with:

pip install "agentsentinel-sdk[remote]"

Step 2: Instrument an action

from agent_sentinel import guarded_action

@guarded_action(name="search_web", cost_usd=0.02, tags=["tool", "search"], impact="read")
def search_web(query: str) -> dict:
    # Your tool call here
    return {"query": query, "results": ["..."]}

search_web("agent sentinel quickstart")

impact="read" is there on purpose: since 0.4.0 the SDK blocks unconfigured actions of impact medium/high (the default) by default. search_web only queries and returns results, so it declares itself as a read. Anything that writes needs a policy configured (see Policies) or the AGENT_SENTINEL_ENFORCEMENT=fail_open escape hatch.

On the first guarded call you will see:

Policy engine is not configured; permitting action 'search_web' (impact='read') because enforcement mode is 'fail_closed_writes', which only blocks impact 'medium'/'high' actions. Load a policy, or set enforcement mode to 'fail_closed' to block every action regardless of declared impact.

That is expected here — you have not loaded a policy yet, but search_web is declared impact="read", so it is still permitted under the default fail_closed_writes enforcement mode. It is logged once per process, and it goes away as soon as you configure a policy. See Policies for budgets, deny lists and rate limits. An action declared impact="medium" or "high" (a write) would instead raise NoPolicyForWriteError until a policy is loaded.

Step 3: Inspect the local ledger

By default, Agent Sentinel appends JSON Lines to:

.agent-sentinel/ledger.jsonl

Each line is a full JSON object with action metadata:

{
  "id": "uuid",
  "timestamp": "2025-01-15T10:30:00.123456Z",
  "action": "search_web",
  "cost_usd": 0.02,
  "duration_ms": 12.3,
  "outcome": "success",
  "tags": ["tool", "search"],
  "payload": {
    "inputs": {"args": [], "kwargs": {"query": "agent sentinel quickstart"}},
    "outputs": {"query": "agent sentinel quickstart", "results": ["..."]}
  }
}

Need to change the ledger directory? Set AGENT_SENTINEL_HOME (see Ledger).

Step 4: Connect to the cloud platform

Visit console.agentsentinel.dev and create an account.

2) Generate an API key

Navigate to Settings → API Keys
Click Generate New Key
Copy the key immediately (shown only once)
Store it securely

3) Enable remote sync in your code

from agent_sentinel import enable_remote_sync, flush_and_stop, guarded_action

# Enable platform sync
sync = enable_remote_sync(
    platform_url="https://platform.agentsentinel.dev",
    api_token="as_your_api_key_here",
    flush_interval=10.0,
)

# Your instrumented functions
@guarded_action(name="search_web", cost_usd=0.02, tags=["tool", "search"], impact="read")
def search_web(query: str) -> dict:
    return {"query": query, "results": ["..."]}

# Use your agent
search_web("agent sentinel quickstart")

# Graceful shutdown (flushes remaining logs)
flush_and_stop()

4) View telemetry in the web console

Go to console.agentsentinel.dev
Navigate to Runs to see your agent execution
Click into a run to see all actions, costs, and timing
Explore Interventions, Activity Ledger, and Analytics

Next steps

Set up policies

Configure budget limits, denied actions, and rate limits

Add approvals

Require human approval for sensitive actions

Instrument LLMs

Automatically track OpenAI, Anthropic, Grok, or Gemini calls

Web console guide

Learn all the features of the web console

Getting started

Concepts

Project direction

SDK (Python)

Platform API

Web Console

What you’ll build

Step 1: Install the SDK

Step 2: Instrument an action

Step 3: Inspect the local ledger

Step 4: Connect to the cloud platform

2) Generate an API key

3) Enable remote sync in your code

4) View telemetry in the web console

Next steps

Set up policies

Add approvals

Instrument LLMs

Web console guide

​What you’ll build

​Step 1: Install the SDK

​Step 2: Instrument an action

​Step 3: Inspect the local ledger

​Step 4: Connect to the cloud platform

​1) Sign up for Agent Sentinel

​2) Generate an API key

​3) Enable remote sync in your code

​4) View telemetry in the web console

​Next steps

Set up policies

Add approvals

Instrument LLMs

Web console guide

What you’ll build

Step 1: Install the SDK

Step 2: Instrument an action

Step 3: Inspect the local ledger

Step 4: Connect to the cloud platform

1) Sign up for Agent Sentinel

2) Generate an API key

3) Enable remote sync in your code

4) View telemetry in the web console

Next steps