AgentFlare class

Constructor

from agentflare import AgentFlare
 
guard = AgentFlare(
    api_key="ag_...",
    agent_id="my-agent",
    cost_threshold=10.0,
    slack_webhook="https://hooks.slack.com/...",
)

Parameters

Parameter	Type	Required	Default	Description
`api_key`	`str`	Yes	—	Your AgentFlare API key (starts with `ag_`). Found in the dashboard.
`agent_id`	`str`	Yes	—	Unique identifier for this agent. All events and costs are grouped by this ID.
`backend_url`	`str`	No	AgentFlare hosted backend	URL of the AgentFlare backend. Only set this when self-hosting.
`cost_threshold`	`float`	No	`None`	Daily spend limit in USD. If set, automatically registers the threshold with the backend on startup.
`slack_webhook`	`str`	No	`None`	Slack incoming webhook URL. If set, a message is sent when the agent is auto-paused.

Methods

`send_event(event: AgentEvent) → bool`

Sends one event to the backend. Returns True if the agent is still alive, False if it has been paused (either by threshold or manually).

alive = guard.send_event(AgentEvent(
    agent_id="my-agent",
    event_type="llm_call",
    model="gpt-4o",
    input_tokens=800,
    output_tokens=400,
))
 
if not alive:
    # The agent was paused — stop processing
    return

Important: When send_event returns False, it also sets the internal _paused flag. All subsequent calls to send_event will immediately return False without making a network request, so it's safe to call this in a tight loop.

`is_paused` (property)

Returns True if the agent has been paused (either detected via send_event or set externally).

if guard.is_paused:
    print("Agent is paused, skipping LLM call")

`callback` (property)

Returns an AgentFlareCallback instance bound to this tracker. Use this with LangChain chains.

result = chain.with_config(callbacks=[guard.callback]).invoke(input)

`track(fn)` (decorator)

Wraps a function to automatically emit agent_start and agent_end events. See the decorator docs.

How the pause flag works

When AgentFlare pauses your agent, it's a two-step process:

The backend sets is_paused = true in Supabase for your agent_id.
The SDK receives "paused": true in the next send_event response and caches it locally as _paused = True.

Once _paused is True, the SDK short-circuits all future send_event calls — it returns False immediately without a network hop. This means even if your agent has many LLM calls queued up, they all get blocked quickly after a pause is registered.

The _paused flag is in-memory only. It resets when you create a new AgentFlare instance (e.g. on the next run of your agent). If the agent was paused in Supabase but your code restarts, the flag will be re-detected on the first send_event call.

On this page