Improve visualization API: allow passing ConversationVisualizer directly (#1025)

Co-authored-by: openhands <[email protected]>
Co-authored-by: John-Mason P. Shackelford <[email protected]>
Co-authored-by: simonrosenberg <[email protected]>
Co-authored-by: Engel Nyst <[email protected]>
Co-authored-by: Rohit Malhotra <[email protected]>

Author: 6 people

.github/scripts/check_documented_examples.py

@@ -165,6 +165,30 @@ def main() -> None:
             print(f"   - {example}")
         print("\n⚠️  Please add documentation for these examples in the docs repo.")
         print("=" * 60)
+        print("\n📚 How to Document Examples:")
+        print("=" * 60)
+        print("1. Clone the docs repository:")
+        print("   git clone https://github.com/OpenHands/docs.git")
+        print()
+        print("2. Create a new .mdx file in sdk/guides/ directory")
+        print("   (e.g., sdk/guides/my-feature.mdx)")
+        print()
+        print("3. Add the example code block with this format:")
+        print('   ```python icon="python" expandable examples/path/to/file.py')
+        print("   <code will be auto-synced>")
+        print("   ```")
+        print()
+        print("4. See the format documentation at:")
+        print(
+            "   https://github.com/OpenHands/docs/blob/main/.github/scripts/README.md"
+        )
+        print()
+        print("5. Example documentation files can be found in:")
+        print("   https://github.com/OpenHands/docs/tree/main/sdk/guides")
+        print()
+        print("6. After creating the PR in docs repo, reference it in your")
+        print("   agent-sdk PR description.")
+        print("=" * 60)
         sys.exit(1)
     else:
         print("✅ All examples are documented!")

.github/workflows/run-examples.yml

@@ -80,6 +80,8 @@ jobs:
                       "examples/01_standalone_sdk/22_anthropic_thinking.py"
                       "examples/01_standalone_sdk/23_responses_reasoning.py"
                       "examples/01_standalone_sdk/24_planning_agent_workflow.py"
+                      "examples/01_standalone_sdk/25_agent_delegation.py"
+                      "examples/01_standalone_sdk/26_custom_visualizer.py"
                       "examples/02_remote_agent_server/01_convo_with_local_agent_server.py"
                       "examples/02_remote_agent_server/02_convo_with_docker_sandboxed_server.py"
                       "examples/02_remote_agent_server/03_browser_use_with_docker_sandboxed_server.py"

examples/01_standalone_sdk/25_agent_delegation.py

@@ -18,6 +18,7 @@
     Tool,
     get_logger,
 )
+from openhands.sdk.conversation import DefaultConversationVisualizer
 from openhands.sdk.tool import register_tool
 from openhands.tools.delegate import DelegateTool
 from openhands.tools.preset.default import get_default_tools
@@ -50,7 +51,7 @@
 conversation = Conversation(
     agent=main_agent,
     workspace=cwd,
-    name_for_visualization="Delegator",
+    visualizer=DefaultConversationVisualizer(name="Delegator"),
 )
 
 task_message = (

examples/01_standalone_sdk/26_custom_visualizer.py

@@ -0,0 +1,77 @@
+"""Custom Visualizer Example
+
+This example demonstrates how to create and use a custom visualizer by subclassing
+ConversationVisualizer. This approach provides:
+- Clean, testable code with class-based state management
+- Direct configuration (just pass the visualizer instance to visualizer parameter)
+- Reusable visualizer that can be shared across conversations
+
+This demonstrates how you can pass a ConversationVisualizer instance directly
+to the visualizer parameter for clean, reusable visualization logic.
+"""
+
+import logging
+import os
+
+from pydantic import SecretStr
+
+from openhands.sdk import LLM, Conversation
+from openhands.sdk.conversation.visualizer import ConversationVisualizerBase
+from openhands.sdk.event import (
+    Event,
+)
+from openhands.tools.preset.default import get_default_agent
+
+
+class MinimalVisualizer(ConversationVisualizerBase):
+    """A minimal visualizer that print the raw events as they occur."""
+
+    def __init__(self, name: str | None = None):
+        """Initialize the minimal progress visualizer.
+
+        Args:
+            name: Optional name to identify the agent/conversation.
+        """
+        # Initialize parent - state will be set later via initialize()
+        super().__init__(name=name)
+
+    def on_event(self, event: Event) -> None:
+        """Handle events for minimal progress visualization."""
+        print(f"\n\n[EVENT] {type(event).__name__}: {event.model_dump_json()[:200]}...")
+
+
+api_key = os.getenv("LLM_API_KEY")
+assert api_key is not None, "LLM_API_KEY environment variable is not set."
+model = os.getenv("LLM_MODEL", "openhands/claude-sonnet-4-5-20250929")
+base_url = os.getenv("LLM_BASE_URL")
+llm = LLM(
+    model=model,
+    api_key=SecretStr(api_key),
+    base_url=base_url,
+    usage_id="agent",
+)
+agent = get_default_agent(llm=llm, cli_mode=True)
+
+# ============================================================================
+# Configure Visualization
+# ============================================================================
+# Set logging level to reduce verbosity
+logging.getLogger().setLevel(logging.WARNING)
+
+# Start a conversation with custom visualizer
+cwd = os.getcwd()
+conversation = Conversation(
+    agent=agent,
+    workspace=cwd,
+    visualizer=MinimalVisualizer(),
+)
+
+# Send a message and let the agent run
+print("Sending task to agent...")
+conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
+conversation.run()
+print("Task completed!")
+
+# Report cost
+cost = llm.metrics.accumulated_cost
+print(f"EXAMPLE_COST: ${cost:.4f}")

examples/02_remote_agent_server/01_convo_with_local_agent_server.py

@@ -169,7 +169,6 @@ def event_callback(event):
         agent=agent,
         workspace=workspace,
         callbacks=[event_callback],
-        visualize=True,
     )
     assert isinstance(conversation, RemoteConversation)
 

examples/02_remote_agent_server/02_convo_with_docker_sandboxed_server.py

@@ -74,7 +74,6 @@ def event_callback(event) -> None:
         agent=agent,
         workspace=workspace,
         callbacks=[event_callback],
-        visualize=True,
     )
     assert isinstance(conversation, RemoteConversation)
 

examples/02_remote_agent_server/03_browser_use_with_docker_sandboxed_server.py

@@ -61,7 +61,6 @@ def event_callback(event) -> None:
         agent=agent,
         workspace=workspace,
         callbacks=[event_callback],
-        visualize=True,
     )
     assert isinstance(conversation, RemoteConversation)
 

examples/02_remote_agent_server/04_convo_with_api_sandboxed_server.py

@@ -63,7 +63,7 @@ def event_callback(event) -> None:
     logger.info(f"Command completed: {result.exit_code}, {result.stdout}")
 
     conversation = Conversation(
-        agent=agent, workspace=workspace, callbacks=[event_callback], visualize=True
+        agent=agent, workspace=workspace, callbacks=[event_callback]
     )
     assert isinstance(conversation, RemoteConversation)
 

examples/02_remote_agent_server/04_vscode_with_docker_sandboxed_server.py

@@ -64,7 +64,6 @@ def event_callback(event) -> None:
         agent=agent,
         workspace=workspace,
         callbacks=[event_callback],
-        visualize=True,
     )
     assert isinstance(conversation, RemoteConversation)
 

openhands-agent-server/openhands/agent_server/event_service.py

@@ -251,7 +251,7 @@ async def start(self):
             ],
             max_iteration_per_run=self.stored.max_iterations,
             stuck_detection=self.stored.stuck_detection,
-            visualize=False,
+            visualizer=None,
             secrets=self.stored.secrets,
         )