Data Models

Pydantic models that power AgentLens event tracking.

All data models use Pydantic v2 for validation and serialization. Import them from agentlens.models.

AgentEvent

The core model — a single observable event in an agent's execution.

from agentlens.models import AgentEvent

event = AgentEvent(
    event_type="llm_call",
    model="gpt-4",
    input_data={"prompt": "Hello"},
    output_data={"response": "Hi there"},
    tokens_in=5,
    tokens_out=3,
    duration_ms=150.0,
)

Field	Type	Default	Description
`event_id`	`str`	auto (UUID hex)	Unique event identifier
`session_id`	`str`	`""`	Parent session ID
`event_type`	`str`	`"generic"`	Category: `llm_call`, `tool_call`, `agent_call`, `agent_error`, `tool_error`, `decision`, `generic`
`timestamp`	`datetime`	now (UTC)	When the event occurred
`input_data`	`dict \| None`	`None`	Input to the operation
`output_data`	`dict \| None`	`None`	Output from the operation
`model`	`str \| None`	`None`	LLM model name
`tokens_in`	`int`	`0`	Input token count
`tokens_out`	`int`	`0`	Output token count
`tool_call`	`ToolCall \| None`	`None`	Associated tool call
`decision_trace`	`DecisionTrace \| None`	`None`	Associated reasoning
`duration_ms`	`float \| None`	`None`	Execution time in milliseconds

Methods

to_api_dict()

Converts the event to a dictionary suitable for the REST API (JSON-serializable, excludes None fields).

event = AgentEvent(event_type="llm_call", model="gpt-4", tokens_in=100)
api_dict = event.to_api_dict()
# {"event_id": "a1b2c3...", "session_id": "", "event_type": "llm_call",
#  "model": "gpt-4", "tokens_in": 100, "tokens_out": 0, ...}

ToolCall

Represents a single tool/function call made by an agent.

from agentlens.models import ToolCall

tc = ToolCall(
    tool_name="web_search",
    tool_input={"query": "AI safety papers"},
    tool_output={"results": [...]},
    duration_ms=890.2,
)

Field	Type	Default	Description
`tool_call_id`	`str`	auto (UUID hex)	Unique identifier
`tool_name`	`str`	required	Name of the tool
`tool_input`	`dict`	`{}`	Input parameters
`tool_output`	`dict \| None`	`None`	Return value
`timestamp`	`datetime`	now (UTC)	When the call was made
`duration_ms`	`float \| None`	`None`	Execution time in ms

DecisionTrace

Captures the reasoning behind an agent decision.

from agentlens.models import DecisionTrace

dt = DecisionTrace(
    reasoning="The user asked about weather, so I need to call the weather API rather than using cached data.",
    step=3,
    alternatives_considered=["Use cached data", "Ask user for location first"],
    confidence=0.92,
)

Field	Type	Default	Description
`trace_id`	`str`	auto (UUID hex)	Unique identifier
`step`	`int`	`0`	Step number in the execution sequence
`reasoning`	`str`	`""`	Why this decision was made
`alternatives_considered`	`list[str]`	`[]`	Other options the agent considered
`confidence`	`float \| None`	`None`	Confidence score (0.0–1.0)
`timestamp`	`datetime`	now (UTC)	When the decision was made

Session

Represents an agent tracking session — a collection of events for one agent run.

from agentlens.models import Session

session = Session(
    agent_name="research-agent",
    metadata={"version": "2.0", "env": "prod"},
)

Field	Type	Default	Description
`session_id`	`str`	auto (UUID hex)	Unique session identifier
`agent_name`	`str`	`"default-agent"`	Name of the agent
`started_at`	`datetime`	now (UTC)	Session start time
`ended_at`	`datetime \| None`	`None`	Session end time
`metadata`	`dict`	`{}`	Arbitrary metadata
`events`	`list[AgentEvent]`	`[]`	Events in this session
`total_tokens_in`	`int`	`0`	Cumulative input tokens
`total_tokens_out`	`int`	`0`	Cumulative output tokens
`status`	`str`	`"active"`	`active`, `completed`, or `error`

Methods

add_event(event)

Add an event to the session. Automatically sets the event's session_id and updates token counters.

end()

Mark the session as completed and set ended_at to now.

to_api_dict()

Convert to a dictionary for the API (excludes the events list for lightweight session listing).