> ## Documentation Index > Fetch the complete documentation index at: https://docs.ubik-agent.com/llms.txt > Use this file to discover all available pages before exploring further. # Agent Message Structure > Reference for the internal structure and tags of Agent Session messages. When an Agent Session processes a request, it generates a response that is not just plain text. The final message content is a structured string containing special tags that represent the agent's thought process, tool executions, steps, and interactions. This guide details the specific tags and structure used in these messages. ## Overview The message content is a linear history of the agent's execution. It is designed to be parsed by the client to render a rich UI with steps, tool inputs/outputs, and user interactions, while remaining a single storable string. ## Step Tags Steps represent high-level actions or phases in the agent's plan. * `<>`: Marks the beginning of a step block. * `<>`: Marks the end of a step block. * `<>`: An optional flag inside a step block indicating this is a single-step agent action. **Example:** ```text theme={null} <> Step 1: Analyzing the user request ✓ I will now look up the information. <> ``` ## Tool Execution Tags When the agent uses a tool, the execution details are embedded directly into the content stream using a specific set of tags. This allows for a precise record of what tool was called, with what arguments, and what the result was. > **Note**: These tags represent the *history* of the tool execution. To display real-time progress (like a spinner or logs) *while* the tool is running, you should listen to the SSE events described in the **[Handling Tool Streaming](/en/guides/streaming-results)** guide. ### Structure and Handling Stages 1. **Start**: `<>` * **Action**: Initialize a UI container for the tool. * **Real-time**: Begin listening for `tool_update` events matching this `execution_id` (see [Handling Tool Streaming](/en/guides/streaming-results)). 2. **Input**: `<>` ... JSON input ... `<>` * **Action**: Parse the JSON content to display the specific arguments passed to the tool. 3. **Result**: `<>` ... JSON result ... `<>` * **Action**: Parse the JSON content to display the final output. * **Real-time**: This static result replaces any transient loading states or logs derived from SSE events. 4. **End**: `<>` * **Action**: Mark the tool execution as complete in the UI. **Example:** ```text theme={null} <> <> {"query": "current weather in Paris"} <> <> {"temperature": "15°C", "condition": "Cloudy"} <> <> ``` ## Checkpoint Tags Checkpoints mark significant points in the conversation history, often used for navigation or restoring state. * `<>`: Starts a checkpoint block. * `Checkpoint: name`: The name of the checkpoint (inside the block). * `<>`: Ends the checkpoint block. **Example:** ```text theme={null} <> Checkpoint: step1_completed <> ``` ## Input Request Tags When the agent needs information from the user, it pauses and waits for input. This interaction is recorded using specific tags. * `<>`: Begins the input request block. * `<>`: Ends the block. * `<>`: (Optional) If the user has already replied, their input is stored here. * `<>`: Ends the user input section. **Example (Waiting for input):** ```text theme={null} <> Please provide your email address. Expected input types: text checkpoint_name: wait_for_email <> ``` **Example (With user input):** ```text theme={null} <> Please provide your email address. Expected input types: text <> {"input": "user@example.com", "type": "text"} <> <> ``` ## Error Tags If an error occurs during the agent's execution, it is recorded within the message content using specific tags. * `<>`: Marks the start of an error message. * `<>`: Marks the end of the error message. * `<>`: Marks the start of a detailed JSON error object (traceback, metadata). * `<>`: Marks the end of the JSON error object. **Example:** ```text theme={null} <> Error: Tool execution failed <> <> { "error": "Tool execution failed", "traceback": "...", "timestamp": "2023-10-27T10:00:00Z" } <> ``` ## Thinking Tags Models that support "Chain of Thought" or reasoning will output their internal monologue wrapped in thinking tags. * `<>`: Starts the thinking block. * `<>`: Ends the thinking block. **Example:** ```text theme={null} <> The user is asking for weather data. I should use the weather tool. <> I will check the weather for Paris. ``` ## Parsing Strategy To render this content, you have two main options: ### Option 1: Use the Ubik Agent SDK (Recommended) The `ubik-agent` (JS/TS) and `ubik-agent-py` (Python) SDKs (currently under development) automatically parse these tags and provide a structured object model or a clean Markdown string ready for rendering. This is the preferred method for most applications. ### Option 2: Manual Parsing (Advanced) If you are building a custom UI and processing the raw content string yourself, you will need to combine two data sources: 1. **Text Delimiters**: Parse the `<>` and `<>` blocks from the message content to display the final tool state. 2. **SSE Events**: Listen for `tool_update` and `tool_partial_update` events to show real-time progress (spinners, logs) before the tool finishes. For a complete tutorial on combining these streams to build a rich interface, please refer to the **[Handling Tool Streaming](/en/guides/streaming-results)** guide. **General Parsing Strategy:** 1. **Regex Matching**: Use regular expressions to find these blocks. 2. **State Machine**: Iterate through the string, maintaining a state (e.g., `in_step`, `in_tool`, `in_thinking`) to render the appropriate UI component for each section. 3. **JSON Parsing**: For tool inputs/outputs and user inputs, extract the text between the tags and parse it as JSON. ## Tag Reference Summary Here is a quick reference of all delimiters in their typical order of appearance during an agent's execution lifecycle: | Phase | Tag | Description | | :-------------- | :---------------------------------------------------------------- | :-------------------------------------- | | **Step** | `<>` | Begins a high-level step. | | **Thinking** | `<>` ... `<>` | Internal monologue (optional). | | **Tool Start** | `<>` | Begins a tool execution block. | | **Tool Input** | `<>` ... `<>` | JSON arguments for the tool. | | **Tool Result** | `<>` ... `<>` | JSON output from the tool. | | **Tool End** | `<>` | Ends the tool execution block. | | **Step End** | `<>` | Ends the high-level step. | | **Checkpoint** | `<>` ... `<>` | Marks a save point in the conversation. | | **Input** | `<>` ... `<>` | Pauses for user input. | | **User Reply** | `<>` ... `<>` | Records the user's response. | | **Error** | `<>` ... `<>` | Wraps error messages. |