AgentEvent model

Definition

from agentflare import AgentEvent

AgentEvent is a Pydantic BaseModel. All fields are validated at creation time.

Fields

Field	Type	Required	Description
`agent_id`	`str`	Yes	The agent this event belongs to. Must match the `agent_id` you configured on `AgentFlare`.
`event_type`	`Literal`	Yes	One of `"llm_call"`, `"tool_call"`, `"agent_start"`, `"agent_end"`. See below.
`model`	`str \| None`	No	The LLM model name (e.g. `"gpt-4o"`, `"claude-sonnet-4-6"`). Required for cost calculation on `llm_call` events.
`input_tokens`	`int`	No	Number of input/prompt tokens. Defaults to `0`.
`output_tokens`	`int`	No	Number of output/completion tokens. Defaults to `0`.
`tool_name`	`str \| None`	No	Name of the tool invoked. Used on `tool_call` events.
`metadata`	`dict \| None`	No	Any extra key-value pairs you want to store with the event (e.g. `run_id`, `session_id`).

Event types

`llm_call`

Emitted when your agent calls an LLM. This is the only event type that triggers cost calculation. You must include model, input_tokens, and output_tokens for an accurate cost.

AgentEvent(
    agent_id="my-agent",
    event_type="llm_call",
    model="gpt-4o",
    input_tokens=500,
    output_tokens=300,
)

`tool_call`

Emitted when your agent invokes an external tool (web search, code interpreter, etc.). These events are recorded but don't affect cost calculations.

AgentEvent(
    agent_id="my-agent",
    event_type="tool_call",
    tool_name="web_search",
)

`agent_start`

Emitted at the beginning of an agent run. Used to mark the start of a session in the event timeline.

AgentEvent(agent_id="my-agent", event_type="agent_start")

`agent_end`

Emitted when the agent finishes (success or error). If emitting on error, include details in metadata.

AgentEvent(
    agent_id="my-agent",
    event_type="agent_end",
    metadata={"error": str(exc)},  # optional
)

Example

from agentflare import AgentFlare, AgentEvent
 
guard = AgentFlare(api_key="ag_...", agent_id="research-agent")
 
# After any LLM call, report the usage:
guard.send_event(AgentEvent(
    agent_id="research-agent",
    event_type="llm_call",
    model="claude-sonnet-4-6",
    input_tokens=1200,
    output_tokens=800,
    metadata={"task": "summarise_article", "url": "https://example.com"},
))

On this page