Quickstart

Get AgentWatch running in under 2 minutes. This guide covers installation, initialization, and your first budget-protected API call.

Prerequisites

• Python 3.9+ or Node.js 18+
• An OpenAI API key (or other supported provider)
• An AgentWatch API key (get one at agent-watch.dev)

Step 1: Install the SDK

Python

pip install aw-sdk

TypeScript

npm install @agentwatch-sdk/sdk

Step 2: Initialize the Client

AgentWatch wraps your existing LLM client. You simply provide your AgentWatch API key and define the budget for the session.

Python

from agentwatch import WatchedOpenAI, AgentBudgetExceeded

client = WatchedOpenAI(
    api_key="your-openai-key",
    agentwatch_api_key="aw_live_xxx",
    agentwatch_session_id="ci-run-123",
    agentwatch_session_budget_usd=2.00,
    agentwatch_enforcement_mode=True,
)

TypeScript

import { WatchedOpenAI } from "@agentwatch-sdk/sdk";

const client = new WatchedOpenAI({
    apiKey: "your-openai-key",
    agentwatch_api_key: "aw_live_xxx",
    sessionId: "ci-run-123",
    sessionBudgetUsd: 2.00,
    enforcementMode: true,
});

Step 3: Make API Calls

Use the client exactly like the standard OpenAI client. Budget enforcement happens automatically.

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Refactor this module..."}]
    )
    print(response.choices[0].message.content)
except AgentBudgetExceeded as e:
    print(f"Blocked: spent ${e.spent:.4f}, limit ${e.limit:.4f}")
    print(f"Session: {e.session_id}")

Step 4: Run Your Agent

python my_agent.py

If the session exceeds $2.00 in token costs, the SDK will raise AgentBudgetExceeded before the next API call is made. The upstream LLM provider is never billed for the blocked request.

What Just Happened

1. The SDK routed your API call through the AgentWatch edge proxy
2. Before each call, a pre-flight budget check was performed against Cloudflare KV
3. Token costs were calculated in real-time using the provider's pricing
4. If the session budget was exceeded, the request was blocked at the edge
5. Telemetry was logged asynchronously (zero latency added to your call)

Key Parameters

Parameter	Required	Description
agentwatch_api_key	Yes	Your AgentWatch API key
agentwatch_session_id	No	Session identifier (auto-generated if omitted)
agentwatch_session_budget_usd	No	Per-session budget ceiling
agentwatch_enforcement_mode	No	Enable pre-call budget checks (default: false)
agentwatch_enforcement_fail_open	No	Fail open on AgentWatch outage (default: true)
agentwatch_project	No	Project name for attribution
agentwatch_team	No	Team name for team budget enforcement

Next Steps

• Session Budgets — Configure budget enforcement
• Anomaly Detection — Detect runaway loops early
• Python SDK — Full SDK reference