Quick Start

1. Install the SDK

pip install agentflare

2. Get an API key

3. Add to your agent

Option A — LangChain / LangGraph (drop-in callback)

This is the easiest integration. Add one line to any existing LangChain chain or graph:

from agentflare import AgentFlare
 
guard = AgentFlare(
    api_key="ag_your_key_here",
    agent_id="my-sales-agent",        # choose any unique name
    cost_threshold=10.0,              # pause when $10/day is hit
    slack_webhook="https://hooks.slack.com/services/...",  # optional
)
 
# Drop the callback into your existing chain
result = my_chain.with_config(callbacks=[guard.callback]).invoke(
    {"input": "Write a cold email for Acme Corp"}
)

That's it. AgentFlare now tracks every LLM call in the chain and stops the agent if your daily budget is exceeded.

Option B — Custom / raw agent

If you're calling the LLM directly (not via LangChain), use send_event manually:

from agentflare import AgentFlare, AgentEvent
 
guard = AgentFlare(
    api_key="ag_your_key_here",
    agent_id="my-research-agent",
    cost_threshold=5.0,
)
 
def call_llm(prompt: str) -> str:
    # ... call your LLM here ...
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    )
 
    # Report the usage to AgentFlare
    alive = guard.send_event(AgentEvent(
        agent_id="my-research-agent",
        event_type="llm_call",
        model="gpt-4o",
        input_tokens=response.usage.prompt_tokens,
        output_tokens=response.usage.completion_tokens,
    ))
 
    if not alive:
        raise RuntimeError("Agent paused — budget exceeded")
 
    return response.choices[0].message.content

Option C — Function decorator

Wrap your entire agent function to automatically emit agent_start and agent_end events:

@guard.track
def run_agent():
    # Your agent logic here
    ...

4. Watch it in the dashboard

Open your AgentFlare dashboard. You'll see:

Live event feed — every LLM call as it happens
Cost meter — cumulative USD spend in the last 24h
Hourly chart — where your budget is going
Pause / resume button — manual override at any time

What happens when the budget is hit?

AgentFlare backend sets is_paused = true for your agent in Supabase.
The next send_event call from your SDK returns False.
Your agent checks the return value and stops.
Slack alert fires (if you configured a webhook).
The dashboard shows the agent as paused in red.

You can resume the agent from the dashboard or via POST /config/pause.

On this page