Document custom visualizer feature

- Added comprehensive guide for using custom ConversationVisualizer
- Shows the new direct API: visualize=custom_visualizer
- Includes examples of highlight patterns and customization options
- Documents the improvement over the old callback-based approach

Related to: OpenHands/software-agent-sdk#1025

Co-authored-by: openhands <[email protected]>

Author: openhands-agent

sdk/guides/convo-custom-visualizer.mdx

@@ -0,0 +1,192 @@
+---
+title: Custom Visualizer
+description: Customize conversation visualization with custom highlighting patterns and display options.
+---
+
+<Note>
+This example is available on GitHub: [examples/01_standalone_sdk/20_custom_visualizer.py](https://github.com/OpenHands/software-agent-sdk/blob/main/examples/01_standalone_sdk/20_custom_visualizer.py)
+</Note>
+
+Customize how your agent's conversation is displayed by passing a custom `ConversationVisualizer` instance directly to the `visualize` parameter:
+
+```python icon="python" expandable examples/01_standalone_sdk/20_custom_visualizer.py
+"""Example demonstrating custom visualizer usage.
+
+This example shows how to pass a custom ConversationVisualizer directly
+to the Conversation, making it easy to customize the visualization without
+the need for callbacks.
+"""
+
+import os
+
+from pydantic import SecretStr
+
+from openhands.sdk import LLM, Agent, Conversation
+from openhands.sdk.conversation.visualizer import ConversationVisualizer
+
+
+def main():
+    # Get API key from environment
+    api_key = os.environ.get("LLM_API_KEY")
+    if not api_key:
+        raise ValueError("LLM_API_KEY environment variable is not set")
+
+    # Create LLM and Agent
+    llm = LLM(model="gpt-4o-mini", api_key=SecretStr(api_key))
+    agent = Agent(llm=llm, tools=[])
+
+    # Create a custom visualizer with specific highlighting
+    custom_visualizer = ConversationVisualizer(
+        highlight_regex={
+            r"^Reasoning:": "bold cyan",
+            r"^Thought:": "bold green",
+            r"^Action:": "bold yellow",
+        },
+        skip_user_messages=False,  # Show user messages
+    )
+
+    # Pass the custom visualizer directly to the conversation
+    # This is more intuitive than visualize=False + callbacks=[...]
+    conversation = Conversation(
+        agent=agent,
+        workspace="./workspace",
+        visualize=custom_visualizer,  # Direct and clear!
+    )
+
+    # Send a message and run
+    conversation.send_message("What is 2 + 2?")
+    conversation.run()
+
+    print("\n✅ Example completed!")
+    print("The conversation used a custom visualizer with custom highlighting.")
+
+
+if __name__ == "__main__":
+    main()
+```
+
+```bash Running the Example
+export LLM_API_KEY="your-api-key"
+cd agent-sdk
+uv run python examples/01_standalone_sdk/20_custom_visualizer.py
+```
+
+## Creating a Custom Visualizer
+
+Configure a `ConversationVisualizer` with custom highlighting patterns:
+
+```python
+from openhands.sdk.conversation.visualizer import ConversationVisualizer
+
+custom_visualizer = ConversationVisualizer(
+    highlight_regex={
+        r"^Reasoning:": "bold cyan",
+        r"^Thought:": "bold green",
+        r"^Action:": "bold yellow",
+    },
+    skip_user_messages=False,  # Show user messages
+)
+```
+
+### Visualization Options
+
+The `visualize` parameter accepts three types:
+
+- **`True`** (default): Use the default visualizer with standard formatting
+- **`False` or `None`**: Disable visualization entirely
+- **`ConversationVisualizer` instance**: Use your custom visualizer
+
+### Before and After
+
+**Previous approach** (confusing):
+```python
+# Had to set visualize=False and pass callback manually
+conversation = Conversation(
+    agent=agent,
+    workspace=cwd,
+    visualize=False,  # Confusing: we DO want visualization!
+    callbacks=[custom_visualizer.on_event],
+)
+```
+
+**New approach** (clear and direct):
+```python
+# Pass the visualizer directly
+conversation = Conversation(
+    agent=agent,
+    workspace=cwd,
+    visualize=custom_visualizer,  # Direct and clear!
+)
+```
+
+## Customization Options
+
+### Highlight Patterns
+
+Use regex patterns to highlight specific content:
+
+```python
+highlight_regex={
+    r"^Reasoning:": "bold cyan",      # Lines starting with "Reasoning:"
+    r"^Thought:": "bold green",       # Lines starting with "Thought:"
+    r"^Action:": "bold yellow",       # Lines starting with "Action:"
+    r"\[ERROR\]": "bold red",         # Error markers
+    r"\[SUCCESS\]": "bold green",     # Success markers
+}
+```
+
+### Available Colors and Styles
+
+Colors: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
+
+Styles: `bold`, `dim`, `italic`, `underline`
+
+Combine them: `"bold cyan"`, `"underline red"`, `"bold italic green"`
+
+### Message Filtering
+
+Control which messages are displayed:
+
+```python
+ConversationVisualizer(
+    skip_user_messages=False,  # Show user messages (default: True)
+    skip_system_messages=False, # Show system messages (default: False)
+)
+```
+
+## Advanced Usage
+
+### Combining with Callbacks
+
+You can still use custom callbacks alongside a custom visualizer:
+
+```python
+def my_callback(event):
+    # Custom logging or processing
+    print(f"Event received: {event.event_type}")
+
+conversation = Conversation(
+    agent=agent,
+    workspace=cwd,
+    visualize=custom_visualizer,
+    callbacks=[my_callback],  # Additional callbacks
+)
+```
+
+### Disabling Visualization
+
+To disable visualization entirely:
+
+```python
+conversation = Conversation(
+    agent=agent,
+    workspace=cwd,
+    visualize=None,  # or False
+)
+```
+
+## Next Steps
+
+- **[Callbacks](/sdk/guides/convo-async)** - Learn about custom event callbacks
+- **[Persistence](/sdk/guides/convo-persistence)** - Save and restore conversation state
+- **[Pause and Resume](/sdk/guides/convo-pause-and-resume)** - Control agent execution flow