Documentation Index
Fetch the complete documentation index at: https://docs.definable.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
| Field | Type | Description |
|---|
content | str | The agent’s final text response |
content_type | str | Content type ("text", "json") |
reasoning_content | str | XML-formatted reasoning for observability (from thinking layer or model-native reasoning) |
reasoning_steps | List[ReasoningStep] | Structured reasoning steps from the thinking layer |
reasoning_messages | List[Message] | The full thinking conversation (system prompt + model response) |
Identity
| Field | Type | Description |
|---|
run_id | str | Unique identifier for this run |
agent_id | str | Agent that produced this output |
session_id | str | Session this run belongs to |
parent_run_id | str | Parent run ID (for nested runs) |
model | str | Model used (e.g., "gpt-4o") |
model_provider | str | Provider name (e.g., "OpenAI") |
Execution
| Field | Type | Description |
|---|
status | RunStatus | COMPLETED, ERROR, PAUSED, CANCELLED |
messages | List[Message] | Full conversation history |
metrics | Metrics | Aggregated token usage, cost, and timing |
events | list | All events that occurred during the run |
| Field | Type | Description |
|---|
images | List[Image] | Generated images |
videos | List[Video] | Generated videos |
audio | List[Audio] | Generated audio |
files | List[File] | Generated files |
response_audio | Audio | Audio response (for audio models) |
Control
| Field | Type | Description |
|---|
requirements | list | Pending requirements (confirmations, user input) |
is_paused | bool | Whether 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 ---")
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
| Event | Key Fields | Description |
|---|
RunStarted | run_id, agent_id | Execution began |
RunContent | content | Content chunk |
RunContentCompleted | full_content | All content generated |
IntermediateRunContent | content | Intermediate content (between tool calls) |
ToolCallStarted | tool.tool_name, tool.tool_args | Tool call began |
ToolCallCompleted | tool.tool_name, tool.result | Tool call finished |
ToolCallError | tool.tool_name, error | Tool call failed |
PreHookStarted | tool_name | Pre-hook began |
PreHookCompleted | tool_name | Pre-hook finished |
PostHookStarted | tool_name | Post-hook began |
PostHookCompleted | tool_name | Post-hook finished |
ReasoningStarted | | Thinking phase began |
ReasoningContentDelta | reasoning_content | Thinking phase text chunk (for streaming) |
ReasoningStep | reasoning_content | One parsed reasoning step |
ReasoningCompleted | | Thinking phase finished |
KnowledgeRetrievalStarted | query | Knowledge retrieval began |
KnowledgeRetrievalCompleted | query, documents_found, documents_used, duration_ms | Knowledge retrieval finished |
MemoryRecallStarted | query | Memory recall began |
MemoryRecallCompleted | query, tokens_used, chunks_included, chunks_available, duration_ms | Memory recall finished |
MemoryUpdateStarted | message_count | Memory storage began |
MemoryUpdateCompleted | message_count, duration_ms | Memory storage finished |
FileReadStarted | file_count | File reading began |
FileReadCompleted | file_count, files_read, files_failed, duration_ms | File reading finished |
SessionSummaryStarted | | Session summary began |
SessionSummaryCompleted | | Session summary finished |
RunPaused | requirements | Waiting for user action |
RunContinued | | Resumed after pause |
RunCompleted | metrics, content, messages | Run finished (carries full run data directly) |
RunError | error | Run failed |
RunCancelled | | Run was cancelled |
CustomEvent | data | Application-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}")
