Skip to main content
Every agent execution produces structured output. Non-streaming runs return a RunOutput object; streaming runs yield a sequence of RunOutputEvent objects.

​
RunOutput

The RunOutput dataclass contains everything from a completed run: 
output = agent.run("Summarize this document.")

​
Content

FieldTypeDescription
contentstrThe agent’s final text response
content_typestrContent type ("text", "json")
reasoning_contentstrXML-formatted reasoning for observability (from thinking layer or model-native reasoning)
reasoning_stepsList[ReasoningStep]Structured reasoning steps from the thinking layer
reasoning_messagesList[Message]The full thinking conversation (system prompt + model response)

​
Identity

FieldTypeDescription
run_idstrUnique identifier for this run
agent_idstrAgent that produced this output
session_idstrSession this run belongs to
parent_run_idstrParent run ID (for nested runs)
modelstrModel used (e.g., "gpt-4o")
model_providerstrProvider name (e.g., "OpenAI")

​
Execution

FieldTypeDescription
statusRunStatusCOMPLETED, ERROR, PAUSED, CANCELLED
messagesList[Message]Full conversation history
metricsMetricsAggregated token usage, cost, and timing
eventslistAll events that occurred during the run

​
Media

FieldTypeDescription
imagesList[Image]Generated images
videosList[Video]Generated videos
audioList[Audio]Generated audio
filesList[File]Generated files
response_audioAudioAudio response (for audio models)

​
Control

FieldTypeDescription
requirementslistPending requirements (confirmations, user input)
is_pausedboolWhether the run is waiting for user action

​
RunStatus

from definable.agent.run import RunStatus

# Possible values:
RunStatus.pending      # Not yet started
RunStatus.running      # Currently executing
RunStatus.completed    # Finished successfully
RunStatus.paused       # Waiting for user action
RunStatus.cancelled    # Cancelled by user or system
RunStatus.blocked      # Blocked by guardrail
RunStatus.error        # Failed with an error

​
Stream Events

Streaming runs yield typed events. Each event has an event field identifying its type.

​
Lifecycle Events

for event in agent.run_stream("Hello"):
    match event.event:
        case "RunStarted":
            print(f"Run {event.run_id} started")
        case "RunCompleted":
            print(f"Done! Tokens: {event.metrics.total_tokens}")
        case "RunError":
            print(f"Error: {event.error}")

​
Content Events

for event in agent.run_stream("Write a story"):
    match event.event:
        case "RunContent":
            print(event.content, end="", flush=True)
        case "RunContentCompleted":
            print("\n--- Content complete ---")

​
Tool Events

for event in agent.run_stream("Check the weather"):
    match event.event:
        case "ToolCallStarted":
            print(f"Calling {event.tool.tool_name}({event.tool.tool_args})")
        case "ToolCallCompleted":
            print(f"  Result: {event.tool.result}")
        case "ToolCallError":
            print(f"  Error: {event.error}")

​
Reasoning Events

When thinking is enabled (Agent(thinking=True)), the agent emits reasoning events before the main response: 
for event in agent.run_stream("Solve this math problem"):
    match event.event:
        case "ReasoningStarted":
            print("[thinking...]")
        case "ReasoningContentDelta":
            print(event.reasoning_content, end="")
        case "ReasoningStep":
            print(f"\n[step] {event.reasoning_content}")
        case "ReasoningCompleted":
            print("\n[done thinking]")

​
Complete Event Reference

EventKey FieldsDescription
RunStartedrun_id, agent_idExecution began
RunContentcontentContent chunk
RunContentCompletedfull_contentAll content generated
IntermediateRunContentcontentIntermediate content (between tool calls)
ToolCallStartedtool.tool_name, tool.tool_argsTool call began
ToolCallCompletedtool.tool_name, tool.resultTool call finished
ToolCallErrortool.tool_name, errorTool call failed
PreHookStartedtool_namePre-hook began
PreHookCompletedtool_namePre-hook finished
PostHookStartedtool_namePost-hook began
PostHookCompletedtool_namePost-hook finished
ReasoningStartedThinking phase began
ReasoningContentDeltareasoning_contentThinking phase text chunk (for streaming)
ReasoningStepreasoning_contentOne parsed reasoning step
ReasoningCompletedThinking phase finished
KnowledgeRetrievalStartedqueryKnowledge retrieval began
KnowledgeRetrievalCompletedquery, documents_found, documents_used, duration_msKnowledge retrieval finished
MemoryRecallStartedqueryMemory recall began
MemoryRecallCompletedquery, tokens_used, chunks_included, chunks_available, duration_msMemory recall finished
MemoryUpdateStartedmessage_countMemory storage began
MemoryUpdateCompletedmessage_count, duration_msMemory storage finished
FileReadStartedfile_countFile reading began
FileReadCompletedfile_count, files_read, files_failed, duration_msFile reading finished
SessionSummaryStartedSession summary began
SessionSummaryCompletedSession summary finished
RunPausedrequirementsWaiting for user action
RunContinuedResumed after pause
RunCompletedmetrics, content, messagesRun finished (carries full run data directly)
RunErrorerrorRun failed
RunCancelledRun was cancelled
CustomEventdataApplication-defined event

​
Getting Metrics from a Stream

The RunCompleted event carries the full run metrics and content directly on the event object: 
completed_event = None

for event in agent.run_stream("Hello"):
    if event.event == "RunContent":
        print(event.content, end="")
    elif event.event == "RunCompleted":
        completed_event = event

# Access metrics directly on the RunCompleted event
print(f"\nTokens: {completed_event.metrics.total_tokens}")
print(f"Cost: ${completed_event.metrics.cost:.4f}")