Document custom visualizer feature #77
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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 <openhands@all-hands.dev>
- Fix file reference from 20_custom_visualizer.py to 26_custom_visualizer.py - Update example code to match the comprehensive MinimalProgressVisualizer implementation - Add documentation for both simple configuration and custom subclass approaches - Clarify the difference between basic highlighting and full custom visualization - Update running instructions to use correct file name This aligns with the improved example in software-agent-sdk PR #1025. Co-authored-by: openhands <openhands@all-hands.dev>
Transform the documentation from simple API usage examples to comprehensive educational content that teaches developers how to create effective custom visualizers: Key improvements: - Detailed explanation of the event system (ActionEvent, ObservationEvent, MessageEvent, AgentErrorEvent) - Two clear approaches: simple configuration vs. full subclassing - Comprehensive best practices section covering: * State management and progress tracking * Error handling and fallback strategies * Performance considerations for high-frequency events * Flexible output formats for different environments * Integration with external systems (webhooks, logging, monitoring) - Real-world code examples for each concept - Built-in visualizer reference with default patterns and configuration options - Updated to reference the improved 26_custom_visualizer.py example This transforms the guide from basic API documentation into a complete tutorial for building production-ready custom visualizers. Co-authored-by: openhands <openhands@all-hands.dev>
jpshackelford
requested changes
Nov 4, 2025
| ``` | ||
|
|
||
| ## Next Steps | ||
|
|
There was a problem hiding this comment.
Are these the correct next steps based on the location of the example in relation to other examples and other documentation?
…isualizers, improve next steps - Remove 'production-ready' language as requested - Remove mention of API improvement to focus on custom visualizers - Update Next Steps section with more relevant related topics: * Async conversations and event callbacks * Conversation metrics and performance tracking * Interactive conversations with real-time updates * Pause/resume with custom logic Co-authored-by: openhands <openhands@all-hands.dev>
- Add convo-custom-visualizer to Agent Features section in docs.json - Position it after agent-custom as requested - This should resolve the 404 error and make the guide appear in sidebar Co-authored-by: openhands <openhands@all-hands.dev>
- Add reference link to ConversationVisualizer implementation - Helps developers understand the code structure and implementation details - Positioned in Built-in Visualizer Reference section for easy access Co-authored-by: openhands <openhands@all-hands.dev>
- Update example code to match the actual MinimalProgressVisualizer implementation - Remove overly speculative best practices that aren't evident in the code - Focus best practices on patterns actually demonstrated in the examples - Simplify performance considerations to match what's actually shown - Update state management examples to use the actual implementation patterns Co-authored-by: openhands <openhands@all-hands.dev>
Add a table overview of all event types handled by the default visualizer before diving into detailed descriptions. This provides a quick reference for developers to understand the complete event system. Co-authored-by: openhands <openhands@all-hands.dev>
…dering details - Replace 'when fired' code snippets with detailed property information - Add comprehensive event property descriptions and default rendering info - Add Approach 3: Custom Object with on_event Method (no subclassing required) - Improve subclassing documentation with built-in features and patterns - Update code examples to show actual event property usage - Better explain ConversationVisualizer inheritance benefits Co-authored-by: openhands <openhands@all-hands.dev>
- Add section on EventHandlerMixin and @Handles decorator - Show how to avoid long if/elif chains in on_event methods - Explain benefits: self-documenting, type-safe, extensible - Provide complete working example with best practices Co-authored-by: openhands <openhands@all-hands.dev>
- Updated all GitHub repository references across documentation files - Changed URLs from github.com/All-Hands-AI/OpenHands to github.com/OpenHands/OpenHands - Updated Mintlify configuration (docs.json) navigation and footer links - Updated issue links, repository links, and documentation references - Updated Slack integration documentation with new repo format This addresses the GitHub organization rename from All-Hands-AI to OpenHands. Co-authored-by: Your Name <your-email@example.com>
- Fix parameter name from 'visualize' to 'visualizer' throughout documentation - Update visualization options to reflect simplified API: * Default behavior (no parameter): Creates default visualizer automatically * None: Disable visualization entirely * ConversationVisualizer instance: Use custom visualizer - Improve error handling example with more practical code - Align all examples with the API simplification changes Related to: OpenHands/software-agent-sdk#1025 Co-authored-by: openhands <openhands@all-hands.dev>
Documentation Updated for API AlignmentUpdated the custom visualizer documentation to align with the recent API changes in OpenHands/software-agent-sdk#1025. Changes Made:
The documentation now accurately represents the current API and existing code patterns without going beyond what's evident in the implementation. |
Co-authored-by: openhands <openhands@all-hands.dev>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds comprehensive educational documentation for the new custom visualizer feature in the OpenHands agent-sdk.
Changes
Added
sdk/guides/convo-custom-visualizer.mdxwhich provides:Educational Content
Comprehensive Example
26_custom_visualizer.py(renamed from 20 to fix numbering conflict)MinimalProgressVisualizerimplementationCode Block Format
The documentation includes the example code block with proper format for auto-syncing:
python icon="python" expandable examples/01_standalone_sdk/26_custom_visualizer.pyRelated PRs
This documentation is for the feature implemented in:
Key Improvements from Original
Preview
The documentation now covers:
Note: This PR should be merged after the related agent-sdk PR is merged to ensure the example file exists in the main branch.
@xingyaoww can click here to continue refining the PR