inspect_ai.event
Core Events
ModelEvent
Call to a language model.
class ModelEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['model']-
Event type.
modelstr-
Model name.
rolestr | None-
Model role.
requested_modelstr | None-
Model name the client requested, for calls made through an agent bridge (
Nonefor direct calls). Differs frommodelwhen the bridge served the request with a different model. originstr | None-
Where the call was made:
"agent"for one of its conversation’s agent turns; otherwise"environment","helper","tool","compaction","approval","review","sampling","sentinel","scorer"or"setup"(a call outside the solve that is not scoring, such as one at sample init). Inspect owns the set of kinds, and a reader treats a kind it does not know as not an agent turn.Nonein logs written before it was recorded. inputlist[ChatMessage]-
Model input (list of messages).
input_refslist[tuple[int, int]] | None-
Message pool references for input. Each element is a (start, end_exclusive) range.
toolslist[ToolInfo]-
Tools available to the model.
tool_choiceToolChoice-
Directive to the model which tools to prefer.
configGenerateConfig-
Generate config used for call to model.
outputModelOutput-
Output from model.
retriesint | None-
Retries for the model API request.
request_idslist[ModelRequestId] | None-
Provider request ids from the responses to this call’s requests (including retries).
errorstr | None-
Error which occurred during model call.
tracebackstr | None-
Error traceback (plain text).
traceback_ansistr | None-
Error traceback with ANSI color codes for display.
cacheLiteral['read', 'write'] | None-
Was this a cache read or write.
callModelCall | None-
Raw call made to model API.
completedUtcDatetime | None-
Time that model call completed (see
timestampfor started) working_timefloat | None-
working time for model call that succeeded (i.e. was not retried).
ToolEvent
Call to a tool.
A host tool that sandbox_agent_bridge(bridged_tools=...) runs for a sandboxed agent is recorded with metadata["bridge"]: server and tool (the bridged server and the tool name within it, also the event’s function), function (the name the model called it by, or None), proposal_id (the id of the model’s proposing tool call, or None) and grant ("consumed" when a proposal matched, "denied" when the call was refused for lack of one, "exempt" when a server registered with require_proposal=False ran it without one, or None when the request was rejected before that check).
class ToolEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['tool']-
Event type.
typeLiteral['function']-
Type of tool call (currently only ‘function’)
idstr-
Unique identifier for tool call.
execution_idstr | None-
Id of this execution of the call, which the approvals and sentinel steps that judged it record as their
execution_id.Unique to each execution of a native call, also when a model repeats a call id. For a host tool a sandbox agent bridge runs, the handout it ran for (each response’s handing of the call to the scaffold has its own) and the bridged tool it ran, as
<handout>/<server>/<tool>: a call that denotes several bridged tools sharing a description runs once per tool, each an execution of its own.Nonefor a host call no handout accounts for, for a host call whose request matched the grants of more than one handout (which one it ran for is unknown), and in logs written before this field.The id is opaque: compare it for equality, and don’t parse it.
Experimental: not yet a stable API; may change without notice.
functionstr-
Function called.
argumentsdict[str, JsonValue]-
Arguments to function.
viewToolCallContent | None-
Custom view of tool call input.
resultToolResult-
Function return value.
truncatedtuple[int, int] | None-
Bytes truncated (from,to) if truncation occurred
errorToolCallError | None-
Error that occurred during tool call.
completedUtcDatetime | None-
Time that tool call completed (see
timestampfor started) working_timefloat | None-
Working time for tool call (clock time minus the sample’s waiting time).
The sample is waiting while a wait is open and no model call, sandbox command or tool call is running (not counting commands run with
exec_remote()or inside sandbox_agent_bridge()). Other work done during a wait is not counted, so settime_limitalongsideworking_limitto bound clock time. agentstr | None-
Name of agent if the tool call was an agent handoff.
agent_span_idstr | None-
Span ID of the agent span, if this tool call spawned an agent.
failedbool | None-
Did the tool call fail with a hard error?.
message_idstr | None-
Id of ChatMessageTool associated with this event.
The message may not stay in the conversation (react removes its
submittool’s result). For a host tool a sandbox agent bridge runs for the scaffold, the result reaches the conversation only when the scaffold sends it back, so this is set then, on the completed event, and only when the answer is certain: the scaffold sends back the reply holding the call unchanged and the bridge places it under the id it handed it with, the call ran once, no other call of the reply has its id or its function and arguments, and exactly one tool message answers it (by call id, before the next assistant message with tool calls), is new in that request, and contains the start of the result the scaffold received. Its content may otherwise differ fromresult: scaffolds edit results and dialects reshape them.Otherwise it stays
None: the scaffold never sends the result, edits the reply, or sends it where the bridge can’t place it (another conversation may hold an equal reply); a message the bridge couldn’t place took the reply’s id; the call executed more than once; more than one tool message answers it; the answer equals a message sent before, was sent before the call completed, or doesn’t contain the start of the result (e.g. the scaffold’s client gave up on the call and answered with its own timeout); Google names only the result’s function and several calls of the reply share it; the sample resumed from a checkpoint first; or 256 later host calls are tracked before its result arrives. call_message_idstr | None-
Id of the assistant message that proposed this tool call.
The output of the ModelEvent that generated the call. In the agent bridge this is the generated output even when a response filter or approval changed the message handed to the scaffold;
Nonefor a call the model did not propose or one the bridge can’t verify against the generation (arguments a filter changed, a reply whose text a request filter edited, identical calls repeated in one reply). It identifies the proposing message, not necessarily one model call: a cached output reused by several model calls (even within one sample and epoch) has one id, so a join that matches more than one ModelEvent is ambiguous.message_idis the id of the tool message holding its result. cancelledbool-
Was the task cancelled?
BranchEvent
Marks where a branched trajectory’s unique content begins.
Emitted at the point where a branch transitions from replaying its parent’s prefix to live execution. Events before this in the trajectory’s span are replay-phase re-execution; events after are the branch’s genuine new content.
class BranchEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['branch']-
Event type.
from_anchorstr-
Anchor at the branch point (matches an
AnchorEvent.anchor_idin the parent).
CompactionEvent
Compaction of conversation history.
class CompactionEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['compaction']-
Event type.
typeLiteral['summary', 'edit', 'trim']-
Compaction type.
rolestr | None-
Model role whose conversation was compacted.
tokens_beforeint | None-
Tokens before compaction.
tokens_afterint | None-
Tokens after compaction.
sourcestr | None-
Compaction source (e.g. ‘inspect’, ‘claude_code’, etc.)
ApprovalEvent
Tool approval.
class ApprovalEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['approval']-
Event type
messagestr-
Message generated by model along with tool call.
callToolCall-
Tool call being approved.
execution_idstr | None-
The execution of the call this approval judged: the
execution_idof the ToolEvent that ran it, if one did.Set for a native tool call and for a call an agent bridge reviews before handing it to its scaffold, where it names that handout and the bridged tool the approval reviewed the call as, as a host ToolEvent records it (a call the scaffold runs itself has no ToolEvent).
Nonein logs written before this field, and for a call approved outside execute_tools() and the agent bridge.Experimental: not yet a stable API; may change without notice.
viewToolCallView | None-
View presented for approval.
approverstr-
Aprover name.
decisionLiteral['approve', 'modify', 'reject', 'escalate', 'terminate']-
Decision of approver.
modifiedToolCall | None-
Modified tool call for decision ‘modify’.
explanationstr | None-
Explanation for decision.
SandboxEvent
Sandbox execution or I/O
class SandboxEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['sandbox']-
Event type
actionLiteral['exec', 'read_file', 'write_file']-
Sandbox action
cmdstr | None-
Command (for exec)
optionsdict[str, JsonValue] | None-
Options for exec, read_file and write_file.
filestr | None-
File (for read_file and write_file)
inputstr | None-
Input (for cmd and write_file). Truncated to 100 lines.
resultint | None-
Result (for exec)
outputstr | None-
Output (for exec and read_file). Truncated to 100 lines.
completedUtcDatetime | None-
Time that sandbox action completed (see
timestampfor started)
InfoEvent
Event with custom info/data.
class InfoEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['info']-
Event type.
sourcestr | None-
Optional source for info event.
dataJsonValue-
Data provided with event.
ScoreEvent
Event with score.
Can be the final score for a Sample, or can be an intermediate score resulting from a call to score.
class ScoreEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['score']-
Event type.
scoreScore-
Score value.
targetstr | list[str] | None-
“Sample target.
intermediatebool-
Was this an intermediate scoring?
scorerstr | None-
Name of the scorer that produced this score (unique within the task).
scorer_argsdict[str, Any] | None-
Arguments the scorer was instantiated with (
Nonefor scores set directly by a solver viastate.scores). model_usagedict[str, ModelUsage] | None-
Cumulative model usage at the time of this score.
role_usagedict[str, ModelUsage] | None-
Cumulative model usage by role at the time of this score.
LoggerEvent
Log message recorded with Python logger.
class LoggerEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['logger']-
Event type.
messageLoggingMessage-
Logging message
ErrorEvent
Event with sample error.
class ErrorEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['error']-
Event type.
errorEvalError-
Sample error
SpanBeginEvent
Mark the beginning of a transcript span.
class SpanBeginEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['span_begin']-
Event type.
idstr-
Unique identifier for span.
parent_idstr | None-
Identifier for parent span.
typestr | None-
Optional ‘type’ field for span.
namestr-
Span name.
SpanEndEvent
Mark the end of a transcript span.
class SpanEndEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['span_end']-
Event type.
idstr-
Unique identifier for span.
Multi-Agent Events
CommunicationEvent
Communication between agents: a record sent or delivered, a read of what others communicated, or a wait for others.
Experimental: not yet a stable API.
class CommunicationEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['communication']-
Event type.
kindCommunicationKind-
sent: an agent sent a record, which was delivered or refused (send).delivered: a record reached its channel and recipients (delivery).read: an agent read what others communicated, or a listing of it.waited: an agent waited for others (wait). sourcestr-
What produced the event (
"inspect_swarm"). It names the owner ofdata. agentstr-
The name of the agent that acted: the sender (
sent,delivered), the reader (read) or the waiter (waited). agent_span_idstr | None-
The span of the agent that acted.
loop_span_idstr | None-
The agent span of the loop that acted: the agent’s own loop, or a subagent acting for it.
nestedbool-
The loop that acted is not the agent’s own, such as one of its subagents.
channelstr | None-
The channel the communication went through.
Nonefor a wait, whose channels are inwait. record_idslist[str]-
The ids of the records the event concerns: the record sent or delivered, or, for
read, the producer’s records for what was read (for the shared memory, each file’s last write at the version read). They identify state, not text: a listing or a partial view names a record whose content it did not show. sendCommunicationSend | None-
For
sent, the record and its refusal. deliveryCommunicationDelivery | None-
For
delivered, the recipients and the delivery’s order. waitCommunicationWait | None-
For
waited, the wait. datadict[str, JsonValue]-
Further details in the format
sourcedefines, such as a channel’s operation or the versions of files read.
SwarmEvent
Evidence from an agent swarm (inspect_swarm) other than communication: a member’s result, the final answer’s selection, the swarm’s ledger or its metrics.
The swarm defines kind and the format of data. Experimental: not yet a stable API.
class SwarmEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['swarm']-
Event type.
kindstr-
What the event records (
"member_result","final","ledger","metrics"). memberstr | None-
The member the event concerns, if any.
datadict[str, JsonValue]-
The evidence, in the format the swarm defines for
kind, with that format’s version indata["version"].
Event Tree
event_tree
Build a tree representation of a sequence of events.
Organize events heirarchially into event spans.
def event_tree(events: Sequence[Event]) -> EventTreeeventsSequence[Event]-
Sequence of
Event.
event_tree_walk
Walk an event tree yielding nodes matching a filter.
def event_tree_walk(
tree: EventTree,
filter: type[T]
| tuple[type[T], ...]
| Callable[[EventTreeNode], bool]
| None = None,
) -> Iterable[T] | Iterable[EventTreeNode]treeEventTree-
Event tree to walk.
filtertype[T] | tuple[type[T], ...] | Callable[[EventTreeNode], bool] | None-
A type, tuple of types (passed to
isinstance), a predicate function, or None to yield all nodes.
event_sequence
Flatten a span forest back into a properly ordered seqeunce.
def event_sequence(tree: EventTree | EventTreeSpan) -> Iterable[Event]treeEventTree | EventTreeSpan-
Event tree or EventTreeSpan.
EventTree
Tree of events (has invividual events and event spans).
EventTree: TypeAlias = list[EventTreeNode]EventTreeSpan
Event tree node representing a span of events.
@dataclass
class EventTreeSpanAttributes
idstr-
Span id.
parent_idstr | None-
Parent span id.
typestr | None-
Optional ‘type’ field for span.
namestr-
Span name.
beginSpanBeginEvent-
Span begin event.
endSpanEndEvent | None-
Span end event (if any).
childrenlist[EventTreeNode]-
Children in the span.
EventTreeNode
Node in an event tree.
EventTreeNode: TypeAlias = Union["EventTreeSpan", Event]Timeline
timeline_build
Build a Timeline from a flat event list.
Transforms a flat event stream into a hierarchical Timeline tree with agent-centric interpretation. The pipeline has two phases:
Phase 1 — Structure extraction:
Uses event_tree() to parse span_begin/span_end events into a tree, then looks for top-level phase spans (“init”, “solvers”, “scorers”):
- If present, partitions events into init (setup), agent (solvers), and scoring sections.
- If absent, treats the entire event stream as the agent.
Phase 2 — Agent classification:
Within the agent section, spans are classified as agents or unrolled:
============================== ======================================= Span type Result ============================== ======================================= type="agent" TimelineSpan(span_type="agent") type="solver" wrapping agent TimelineSpan(span_type="agent") type="solver" (primitive) Unrolled into parent type="tool" + ModelEvents TimelineSpan(span_type="agent") ToolEvent with agent field TimelineSpan(span_type="agent") type="tool" (no models) Unrolled into parent Any other span type Unrolled into parent ============================== =======================================
“Unrolled” means the span wrapper is removed and its child events dissolve into the parent’s content list.
Phase 3 — Post-processing passes:
- Utility agent classification (single-turn agents with different system prompts)
def timeline_build(
events: list[Event], *, name: str | None = None, description: str | None = None
) -> Timelineeventslist[Event]-
Flat list of Events from a transcript.
namestr | None-
Optional name for timeline (defaults to “Default”)
descriptionstr | None-
Optional description for timeline (defaults to ““)
timeline_dump
Serialize a Timeline to a JSON-compatible dict.
Converts a Timeline into a plain dictionary suitable for JSON serialization. Event objects within the timeline are replaced by their UUIDs, keeping the serialized form compact and self-referencing.
def timeline_dump(timeline: Timeline) -> dict[str, Any]timelineTimeline-
The Timeline to serialize.
timeline_filter
Return a new timeline with only spans matching the predicate.
Recursively walks span content and branches, keeping TimelineSpan items where predicate(span) returns True. Non-matching spans and their entire subtrees are pruned. TimelineEvent items are always kept because they belong to the parent span.
Use this to pre-filter a timeline before passing it to timeline_messages().
def timeline_filter(
timeline: Timeline,
predicate: Callable[[TimelineSpan], bool],
) -> TimelinetimelineTimeline-
The timeline to filter.
predicateCallable[[TimelineSpan], bool]-
Function that receives a TimelineSpan and returns
Trueto keep it (and its subtree),Falseto prune it.
timeline_load
Deserialize a Timeline from a dict produced by timeline_dump.
Reconstructs a full Timeline by resolving the UUID strings stored in data back to their corresponding Event objects from events.
def timeline_load(data: dict[str, Any], events: list[Event]) -> Timelinedatadict[str, Any]-
A dict previously produced by
timeline_dump. eventslist[Event]-
The flat list of Event objects whose UUIDs appear in
data. Events without a UUID are ignored.
timeline_branch
Context manager for creating a timeline branch.
Emits an AnchorEvent in the current (parent) span so the viewer can resolve from_anchor to a position, then opens a type="branch" span and emits a BranchEvent inside it.
@contextlib.asynccontextmanager
async def timeline_branch(
*, name: str, from_anchor: str, id: str | None = None
) -> AsyncIterator[None]namestr-
Name of branch span.
from_anchorstr-
Anchor id at the branch point.
idstr | None-
Optional span ID. Generated if not provided.
Timeline
A named timeline view over a transcript.
Multiple timelines allow different interpretations of the same event stream — e.g. a default agent-centric view alongside an alternative grouping or filtered view.
class Timeline(BaseModel)Methods
- render
-
Render an ASCII swimlane diagram of the timeline.
def render(self, width: int | None = None) -> strwidthint | None-
Total width of the output in characters. Defaults to 120.
TimelineEvent
Wraps a single Event.
class TimelineEvent(BaseModel)Methods
- start_time
-
Event timestamp (required field on all events).
def start_time(self) -> datetime - end_time
-
Event completion time if available, else timestamp.
def end_time(self) -> datetime - total_tokens
-
Tokens from this event (ModelEvent only).
Includes input_tokens_cache_read and input_tokens_cache_write in the total, as these represent actual token consumption for any LLM system using prompt caching. The sum of all token fields provides an accurate measure of total context window usage across all sources.
def total_tokens(self) -> int - idle_time
-
Seconds of idle time (always 0 for a single event).
def idle_time(self) -> float
TimelineSpan
A span of execution — agent, scorer, tool, or root.
class TimelineSpan(BaseModel)Attributes
tool_invokedbool-
True if this agent span was invoked as a tool (via task/as_tool/handoff).
Tool-invoked subagents are explicit user-intended sub-trajectories and are never classified as
utilityregardless of turn count or prompt differences. The_classify_utility_agentsheuristic targets internal helper model calls, not explicit subagent invocations.
Methods
- start_time
-
Earliest start time among content (and optionally branches).
def start_time(self, include_branches: bool = True) -> datetimeinclude_branchesbool-
Include branches in time calcluation.
- end_time
-
Latest end time among content (and optionally branches).
def end_time(self, include_branches: bool = True) -> datetimeinclude_branchesbool-
Include branches in time calcluation.
- total_tokens
-
Sum of tokens from content (and optionally branches).
def total_tokens(self, include_branches: bool = True) -> intinclude_branchesbool-
Include branches in token calcluation.
- idle_time
-
Seconds of idle time within this span (and optionally branches).
def idle_time(self, include_branches: bool = True) -> floatinclude_branchesbool-
Include branches in time calcluation.
Outline
Hierarchical outline of events for an agent.
class Outline(BaseModel)OutlineNode
A node in an agent’s outline, referencing an event by UUID.
class OutlineNode(BaseModel)Eval Events
SampleInitEvent
Beginning of processing a Sample.
class SampleInitEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['sample_init']-
Event type.
sampleAnnotated[Sample, PlainSerializer(lambda sample: sample.model_copy(update={description: None}), return_type=Sample)]-
Sample.
stateJsonValue-
Initial state.
Defaults to None so events round-trip through log serialization, which writes with exclude_none=True (a None state is omitted from the written JSON and must not fail validation on read).
SampleLimitEvent
The sample was unable to finish processing due to a limit
class SampleLimitEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['sample_limit']-
Event type.
typeLiteral['message', 'time', 'working', 'token', 'turn', 'cost', 'operator', 'custom']-
Type of limit that halted processing
messagestr-
A message associated with this limit
limitfloat | None-
The limit value (if any)
StateEvent
Change to the current TaskState
class StateEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['state']-
Event type.
changeslist[JsonChange]-
List of changes to the TaskState
StoreEvent
Change to data within the current Store.
class StoreEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['store']-
Event type.
changeslist[JsonChange]-
List of changes to the Store.
InputEvent
Input screen interaction.
class InputEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['input']-
Event type.
inputstr-
Input interaction (plain text).
input_ansistr-
Input interaction (ANSI).
messagestr | None-
Prompt shown to the user (set for
ask_user/request_inputinteractions). fieldslist[InputField] | None-
Fields requested from the user (set for
ask_user/request_inputinteractions). outcomeLiteral['accepted', 'declined', 'cancelled'] | None-
How the
ask_userinteraction concluded. contentdict[str, Any] | None-
Structured answer when
outcome == "accepted".
ScoreEditEvent
Event recorded when a score is edited.
class ScoreEditEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['score_edit']-
Event type.
score_namestr-
Name of the score being edited.
editScoreEdit-
The edit being applied to the score.
InterruptEvent
Records that an agent’s turn or sample was cut short.
Emitted in three cases:
source="user_cancel"— an ACP client (e.g. an editor or TUI) calledsession/cancelwhile a turn was in flight.source="limit"— a sample-level limit (tokens, time, cost, messages) tripped during execution.source="system"— the eval is shutting down for an external reason and is cancelling active samples.
The interrupted field records what was running at the moment the cancel reached the cancel scope. interrupted_tool_call_id and interrupted_model_event_id give cross-references when applicable so downstream consumers can correlate this event with the in-flight ToolEvent or ModelEvent.
class InterruptEvent(BaseEvent)Attributes
uuidstr | None-
Unique identifer for event.
span_idstr | None-
Span the event occurred within.
timestampUtcDatetime-
Clock time at which event occurred.
working_startfloat-
Working time (within sample) at which the event occurred.
metadatadict[str, Any] | None-
Additional event metadata.
pendingbool | None-
Is this event pending?
eventLiteral['interrupt']-
Event type.
sourceLiteral['user_cancel', 'limit', 'system']-
What caused the interrupt.
interruptedLiteral['generate', 'tool_call', 'between_turns']-
What was running at the moment of the interrupt.
interrupted_tool_call_idstr | None-
ToolEvent.id(the underlyingToolCall.id) of the in-flight tool, if any. interrupted_model_event_idstr | None-
ModelEvent.uuidof the in-flight model call, if any.
Types
LoggingLevel
Logging level.
LoggingLevel = Literal[
"debug", "trace", "http", "sandbox", "info", "warning", "error", "critical"
]LoggingMessage
Message written to Python log.
class LoggingMessage(BaseModel)Attributes
namestr | None-
Logger name (e.g. ‘httpx’)
levelLoggingLevel-
Logging level.
messagestr-
Log message.
createdfloat-
Message created time.
filenamestr-
Logged from filename.
modulestr-
Logged from module.
linenoint-
Logged from line number.
CommunicationKind
What a CommunicationEvent records.
Experimental: not yet a stable API.
CommunicationKind: TypeAlias = Literal["sent", "delivered", "read", "waited"]CommunicationRecord
For sent, what one agent communicated: a message, or a change to state other agents read.
class CommunicationRecord(BaseModel)Attributes
idstr | None-
For
sent, the producer’s id for the record, if it has one. kindstr-
For
sent, what the record does in its channel, in the channel’s terms ("message","create","append"). senderstr-
For
sent, the name of the agent that sent it. tolist[str]-
For
sent, the addresses as written. Empty for an unaddressed record, such as a write to shared state. recipientslist[str]-
For
sent, the agents the addresses resolved to. contentstr | None-
For
sent, the text it carries, orNonewhen the producer cannot see it (such as encrypted content). reply_tostr | None-
For
sent, the id of a record this one answers.
CommunicationRejection
For sent, why a record that was sent was not delivered.
class CommunicationRejection(BaseModel)Attributes
controlstr-
For
sent, the control that refused it, in the producer’s terms ("rate","admit"). reasonstr-
For
sent, the reason the sender was given.
CommunicationSend
For sent, the record an agent sent, and why it was refused if it was.
class CommunicationSend(BaseModel)Attributes
recordCommunicationRecord-
For
sent, the record. rejectedCommunicationRejection | None-
For
sent, why the record was refused;Nonewhen it was delivered.
CommunicationDelivery
For delivered, whom a record reached and in what order.
class CommunicationDelivery(BaseModel)Attributes
recipientslist[str]-
For
delivered, the agents it reached. seqint | None-
For
delivered, the delivery’s position in the order the producer delivered records, across its channels.
CommunicationWait
For waited, an agent waiting for other agents.
class CommunicationWait(BaseModel)Attributes
idstr | None-
For
waited, the producer’s id for the wait. channelslist[str]-
For
waited, the channels it waited on. outcomestr-
For
waited, what ended it, in the producer’s terms ("news","timeout","cancelled"). durationfloat-
For
waited, seconds from the start of the wait until it ended.