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_contentstrChain-of-thought reasoning (if applicable)
reasoning_stepslistIndividual reasoning steps

​
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.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.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.output.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_name}({event.tool_args})")
        case "ToolCallCompleted":
            print(f"  Result: {event.result}")
        case "ToolCallError":
            print(f"  Error: {event.error}")

​
Reasoning Events

for event in agent.run_stream("Solve this math problem"):
    match event.event:
        case "ReasoningStep":
            print(f"[thinking] {event.content}")
        case "ReasoningContentDelta":
            print(event.delta, end="")

​
Complete Event Reference

EventKey FieldsDescription
RunStartedrun_id, agent_idExecution began
RunContentcontentContent chunk
RunContentCompletedfull_contentAll content generated
IntermediateRunContentcontentIntermediate content (between tool calls)
ToolCallStartedtool_name, tool_argsTool call began
ToolCallCompletedtool_name, resultTool call finished
ToolCallErrortool_name, errorTool call failed
PreHookStartedtool_namePre-hook began
PreHookCompletedtool_namePre-hook finished
PostHookStartedtool_namePost-hook began
PostHookCompletedtool_namePost-hook finished
ReasoningStartedReasoning began
ReasoningStepcontentOne reasoning step
ReasoningContentDeltadeltaReasoning text chunk
ReasoningCompletedReasoning 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
RunCompletedoutputRun finished (includes full RunOutput)
RunErrorerrorRun failed
RunCancelledRun was cancelled
CustomEventdataApplication-defined event

​
Getting RunOutput from a Stream

The RunCompleted event contains the full RunOutput: 
final_output = None

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

# Now you have full metrics, messages, etc.
print(f"\nTokens: {final_output.metrics.total_tokens}")
print(f"Cost: ${final_output.metrics.cost:.4f}")