🛡️ AgentFlare Docs

@guard.track decorator

Automatically emit agent_start and agent_end events around any function.

Overview

The @guard.track decorator wraps any Python function and automatically emits:

  • agent_start when the function is called
  • agent_end when the function returns (success or exception)

It uses functools.wraps, so the wrapped function's name, docstring, and signature are preserved.

Usage

from agentflare import AgentFlare
 
guard = AgentFlare(api_key="ag_...", agent_id="my-agent")
 
@guard.track
def run_agent(query: str) -> str:
    # Your full agent logic lives here
    # ... call LLMs, use tools, etc.
    return result

Calling run_agent("some input") is now equivalent to:

guard.send_event(AgentEvent(agent_id="my-agent", event_type="agent_start"))
try:
    result = run_agent("some input")
    guard.send_event(AgentEvent(agent_id="my-agent", event_type="agent_end"))
    return result
except Exception as exc:
    guard.send_event(AgentEvent(
        agent_id="my-agent",
        event_type="agent_end",
        metadata={"error": str(exc)},
    ))
    raise

Combining with send_event

The decorator handles lifecycle events. You still call send_event manually for LLM calls inside the function:

@guard.track
def run_agent():
    # Lifecycle is handled by @guard.track
 
    # Report individual LLM calls manually
    response = call_my_llm("What's the weather?")
    alive = guard.send_event(AgentEvent(
        agent_id="my-agent",
        event_type="llm_call",
        model="gpt-4o",
        input_tokens=response.usage.prompt_tokens,
        output_tokens=response.usage.completion_tokens,
    ))
 
    if not alive:
        return  # Paused — exit early

Error handling

If the wrapped function raises an exception, agent_end is still emitted with metadata={"error": "<exception message>"}. The exception is then re-raised, so your existing error handling is unaffected.

@guard.track
def risky_agent():
    raise ValueError("Something went wrong")
 
# risky_agent() raises ValueError as normal,
# but agent_end is still recorded in AgentFlare

Previous

LangChain Integration

Next

API Overview

On this page

OverviewUsageCombining with send_eventError handling