docs(sdk): Add guide for custom tools with remote agent server #177
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
This guide documents how to use custom tools with a remote agent server by building a custom Docker image that includes tool implementations. Covers: - Overview and use cases for custom tools with remote servers - Architecture and workflow - Step-by-step implementation guide - Dynamic tool registration - Production deployment best practices - Troubleshooting common issues - Real-world example (bug reporting bot) References the complete example in the SDK repository: examples/02_remote_agent_server/05_custom_tool/ Relates to: OpenHands/software-agent-sdk#1381 Co-authored-by: openhands <[email protected]>
- Update example from ReportBugTool to LogDataTool (matching actual implementation) - Change from DockerWorkspace to DockerDevWorkspace with base_image parameter - Update Dockerfile to use simple base image approach - Add note about importing tool module to register in client registry - Update code examples to match the actual SDK example - Update troubleshooting section with additional guidance Co-authored-by: openhands <[email protected]>
Custom tools only work with source mode deployments because PyInstaller binaries cannot dynamically import external Python modules at runtime. References GitHub issue #1531 for more details and alternatives. Co-authored-by: openhands <[email protected]>
xingyaoww
commented
Dec 29, 2025
|
|
||
| Create a Python module for your tool (e.g., `custom_tools/log_data.py`): | ||
|
|
||
| ```python |
Contributor
Author
There was a problem hiding this comment.
@OpenHands please make this PR more succinct - you only need to mention the core part in this doc. Please refer to the corresponding PR to understand the context
There was a problem hiding this comment.
I'm on it! xingyaoww can track my progress at all-hands.dev
There was a problem hiding this comment.
I've made the custom tools documentation more succinct as requested. The changes have been pushed to the PR.
Summary of Changes
File: sdk/guides/agent-server/custom-tools.mdx
- Reduced from 510 lines to 113 lines (78% reduction)
What was removed:
- Full 130-line code example for the custom tool (now links to GitHub)
- Detailed production deployment section
- Extensive best practices section
- Verbose troubleshooting section (replaced with a concise table)
- Redundant example use case section
- Mermaid sequence diagram
What was kept (core content):
- Overview with link to standalone custom tools guide
- Binary mode limitation warning (condensed)
- Link to complete GitHub example
- Quick Start with minimal code snippets showing the pattern
- Brief "How It Works" explanation (4 bullet points)
- Troubleshooting table with common issues
- See Also links
The documentation now focuses on the core concepts and directs users to the complete working example on GitHub for full implementation details.
Reduce documentation from 510 to 113 lines by: - Removing full code listings (link to GitHub example instead) - Condensing step-by-step guide to Quick Start - Simplifying troubleshooting to a table - Removing redundant sections (production deployment, best practices, example use case) The complete working example is available on GitHub for reference. Co-authored-by: openhands <[email protected]>
…vigation - Use sync code blocks to auto-populate example code from agent-sdk - Add custom-tools page to docs.json navigation under Remote Agent Server - Follow the same format as other SDK guides - Include both main example and custom tool implementation files Co-authored-by: openhands <[email protected]>
neubig
approved these changes
Dec 29, 2025
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 documentation for using custom tools with remote agent servers in the OpenHands SDK.
Changes
New Guide
Added
sdk/guides/custom-tools-remote-agent.mdcovering:@register_toolUpdated Sidebar
Related PRs
Use Case
Addresses a common user need: collecting structured data from agent runs (e.g., bug reports from QA bots, test results, audit findings) where enforcing a specific schema is critical for downstream processing.
Co-authored-by: openhands [email protected]
@xingyaoww can click here to continue refining the PR