> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsentinel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Instrument your agent in minutes, with local-first logs and optional platform sync.

## 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

<Info>
  **Requirements**:

  * Python **3.9+**
  * Your agent functions already estimate or know per-call cost (USD) for `cost_usd`
</Info>

## Step 1: Install the SDK

```bash theme={null}
pip install agentsentinel-sdk
```

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

```bash theme={null}
pip install "agentsentinel-sdk[remote]"
```

## Step 2: Instrument an action

```python theme={null}
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")
```

<Note>
  On the first guarded call you will see:

  ```
  Policy engine is not configured; permitting all actions (enforcement mode 'fail_open')
  ```

  That is expected here — you have not loaded a policy yet, so nothing is being
  enforced and every action is permitted. It is logged once per process, and it
  goes away as soon as you configure a policy. See
  [Policies](/sdk/python/policies) for budgets, deny lists and rate limits, and
  set `PolicyEngine.set_enforcement_mode("fail_closed")` in any deployment where
  an unconfigured engine should block rather than permit.
</Note>

## Step 3: Inspect the local ledger

By default, Agent Sentinel appends JSON Lines to:

```text theme={null}
.agent-sentinel/ledger.jsonl
```

Each line is a full JSON object with action metadata:

```json theme={null}
{
  "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": ["..."]}
  }
}
```

<Tip>
  Need to change the ledger directory? Set `AGENT_SENTINEL_HOME` (see <a href="/concepts/ledger">Ledger</a>).
</Tip>

## Step 4: Connect to the cloud platform

### 1) Sign up for Agent Sentinel

Visit [console.agentsentinel.dev](https://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

```python theme={null}
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](https://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

<CardGroup cols={2}>
  <Card title="Set up policies" icon="shield" href="/sdk/python/policies">
    Configure budget limits, denied actions, and rate limits
  </Card>

  <Card title="Add approvals" icon="user-check" href="/sdk/python/approvals">
    Require human approval for sensitive actions
  </Card>

  <Card title="Instrument LLMs" icon="brain" href="/sdk/python/llm-integrations">
    Automatically track OpenAI, Anthropic, Grok, or Gemini calls
  </Card>

  <Card title="Web console guide" icon="desktop" href="/console/overview">
    Learn all the features of the web console
  </Card>
</CardGroup>