Skip to main content

​
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"])
def search_web(query: str) -> dict:
    # Your tool call here
    return {"query": query, "results": ["..."]}

search_web("agent sentinel quickstart")

​
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

​
1) Sign up for Agent Sentinel

Visit console.agentsentinel.dev and create an account.

​
2) Generate an API key

  1. Navigate to Settings → API Keys
  2. Click Generate New Key
  3. Copy the key immediately (shown only once)
  4. 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"])
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

  1. Go to console.agentsentinel.dev
  2. Navigate to Runs to see your agent execution
  3. Click into a run to see all actions, costs, and timing
  4. 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