> ## 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. # Run Output & Events > Understand the data returned from every agent run. 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: ```python theme={null} 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](/agents/thinking) or model-native reasoning) | | `reasoning_steps` | `List[ReasoningStep]` | Structured reasoning steps from the [thinking layer](/agents/thinking) | | `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 | ### Media | 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 ```python theme={null} 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 ```python theme={null} 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 ```python theme={null} 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 ```python theme={null} 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](/agents/thinking) is enabled (`Agent(thinking=True)`), the agent emits reasoning events before the main response: ```python theme={null} 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](/agents/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: ```python theme={null} 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}") ```