Skip to main content
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.
  • <<STEP_START>>: Marks the beginning of a step block.
  • <<STEP_END>>: Marks the end of a step block.
  • <<SINGLE_STEP_FLAG>>: An optional flag inside a step block indicating this is a single-step agent action.
Example: 
<<STEP_START>>
Step 1: Analyzing the user request ✓
I will now look up the information.
<<STEP_END>>

​
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 guide.

​
Structure and Handling Stages

  1. Start: <<TOOL_STEP_START/tool_name:execution_id>>
    • Action: Initialize a UI container for the tool.
    • Real-time: Begin listening for tool_update events matching this execution_id (see Handling Tool Streaming).
  2. Input: <<TOOL_STEP_INPUT_START>> … JSON input … <<TOOL_STEP_INPUT_END>>
    • Action: Parse the JSON content to display the specific arguments passed to the tool.
  3. Result: <<TOOL_STEP_RESULT_START>> … JSON result … <<TOOL_STEP_RESULT_END>>
    • 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: <<TOOL_STEP_END/tool_name:execution_id>>
    • Action: Mark the tool execution as complete in the UI.
Example: 
<<TOOL_STEP_START/web_search:call_123abc>>
<<TOOL_STEP_INPUT_START>>
{"query": "current weather in Paris"}
<<TOOL_STEP_INPUT_END>>
<<TOOL_STEP_RESULT_START>>
{"temperature": "15°C", "condition": "Cloudy"}
<<TOOL_STEP_RESULT_END>>
<<TOOL_STEP_END/web_search:call_123abc>>

​
Checkpoint Tags

Checkpoints mark significant points in the conversation history, often used for navigation or restoring state.
  • <<CHECKPOINT_START>>: Starts a checkpoint block.
  • Checkpoint: name: The name of the checkpoint (inside the block).
  • <<CHECKPOINT_END>>: Ends the checkpoint block.
Example: 
<<CHECKPOINT_START>>
Checkpoint: step1_completed
<<CHECKPOINT_END>>

​
Input Request Tags

When the agent needs information from the user, it pauses and waits for input. This interaction is recorded using specific tags.
  • <<INPUT_REQUIRED_START>>: Begins the input request block.
  • <<INPUT_REQUIRED_END>>: Ends the block.
  • <<USER_INPUT_PROVIDED_START>>: (Optional) If the user has already replied, their input is stored here.
  • <<USER_INPUT_PROVIDED_END>>: Ends the user input section.
Example (Waiting for input): 
<<INPUT_REQUIRED_START>>
Please provide your email address.
Expected input types: text
checkpoint_name: wait_for_email
<<INPUT_REQUIRED_END>>
Example (With user input): 
<<INPUT_REQUIRED_START>>
Please provide your email address.
Expected input types: text

<<USER_INPUT_PROVIDED_START>>
{"input": "user@example.com", "type": "text"}
<<USER_INPUT_PROVIDED_END>>
<<INPUT_REQUIRED_END>>

​
Error Tags

If an error occurs during the agent’s execution, it is recorded within the message content using specific tags.
  • <<ERROR_START>>: Marks the start of an error message.
  • <<ERROR_END>>: Marks the end of the error message.
  • <<ERROR_JSON_START>>: Marks the start of a detailed JSON error object (traceback, metadata).
  • <<ERROR_JSON_END>>: Marks the end of the JSON error object.
Example: 
<<ERROR_START>>
Error: Tool execution failed
<<ERROR_END>>

<<ERROR_JSON_START>>
{
  "error": "Tool execution failed",
  "traceback": "...",
  "timestamp": "2023-10-27T10:00:00Z"
}
<<ERROR_JSON_END>>

​
Thinking Tags

Models that support “Chain of Thought” or reasoning will output their internal monologue wrapped in thinking tags.
  • <<thinking>>: Starts the thinking block.
  • <</thinking>>: Ends the thinking block.
Example: 
<<thinking>>
The user is asking for weather data. I should use the weather tool.
<</thinking>>
I will check the weather for Paris.

​
Parsing Strategy

To render this content, you have two main options: 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 <<TOOL_STEP_INPUT_START>> and <<TOOL_STEP_RESULT_START>> 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 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:
PhaseTagDescription
Step<<STEP_START>>Begins a high-level step.
Thinking<<thinking>> … <</thinking>>Internal monologue (optional).
Tool Start<<TOOL_STEP_START/name:id>>Begins a tool execution block.
Tool Input<<TOOL_STEP_INPUT_START>> … <<TOOL_STEP_INPUT_END>>JSON arguments for the tool.
Tool Result<<TOOL_STEP_RESULT_START>> … <<TOOL_STEP_RESULT_END>>JSON output from the tool.
Tool End<<TOOL_STEP_END/name:id>>Ends the tool execution block.
Step End<<STEP_END>>Ends the high-level step.
Checkpoint<<CHECKPOINT_START>> … <<CHECKPOINT_END>>Marks a save point in the conversation.
Input<<INPUT_REQUIRED_START>> … <<INPUT_REQUIRED_END>>Pauses for user input.
User Reply<<USER_INPUT_PROVIDED_START>> … <<USER_INPUT_PROVIDED_END>>Records the user’s response.
Error<<ERROR_START>> … <<ERROR_END>>Wraps error messages.