OpenHands / OpenHands/software-agent-sdk
SDK vs Agent Server: Close compatibility gaps identified in compatibility matrix
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 539
- Avg merge
- 1d 19h
- Merged PRs (30d)
- 137
Description
Context
A compatibility matrix comparing the Python SDK (openhands-sdk) vs Agent Server (openhands-agent-server) feature support has been published:
π Compatibility Matrix
Overall the compatibility looks pretty solid, but there are several areas where the agent-server lacks parity with the SDK that would be valuable to close.
Key gaps to address
The following features are supported in the SDK but not yet exposed (or only partially exposed) in the agent-server:
High Priority
| Feature | SDK | Server | Notes |
|---|---|---|---|
| Sub-agents & delegation | β | β | SDK-only: register_agent, load_agents_from_dir. Vasco is actively working on this β believed to be close. |
| Critic / iterative refinement | β | β | SDK-only: CriticBase, APIBasedCritic, etc. |
| Multi-LLM / LLM fallback strategies | β | β | Automatic model fallback on failure β SDK only |
| LLM completions (direct) | β | β | Server uses LLM internally but has no direct completion endpoint; exposed indirectly via conversations |
Additional gaps
| Feature | SDK | Server | Notes |
|---|---|---|---|
| Delegate tool (sub-agents) | β | β | SDK-only delegation to sub-agents |
| Custom tool registration | β | β | SDK: @register_tool decorator for custom tools |
| MCP client (direct API) | β | β | SDK-only: MCPClient for programmatic MCP access |
| Cached git repo | β | β | SDK-only: CachedRepo for efficient git ops |
| Plugin system (install/uninstall/manage) | β | β | SDK-only: full plugin lifecycle management |
| Plugin marketplace | β | β | SDK-only: Marketplace, MarketplaceEntry |
| Token usage tracking | β | β | Tracked internally; exposed via conversation metrics |
| Stuck detector | β | β | Runs inside server conversations automatically |
| Hook execution engine | β | β | Executor runs inside conversations; no direct API |
| Security risk assessment | β | β | Runs inline; not a standalone endpoint |
Suggested addition (from discussion)
- LLMProfileStore β gives the agent-server the ability to load and persist LLM profiles across sessions
Future plans
- Add CLI/web and possibly the TypeScript client to the compatibility matrix
- Set up a CI job to keep the matrix updated automatically
Related PR: https://github.com/OpenHands/software-agent-sdk/pull/2710
This issue was created by an AI assistant (OpenHands) on behalf of the user.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up β it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the published compatibility matrix and related PR #2710, then choose one specific SDK-only or partially exposed feature from the listed gaps. Trace how that feature is represented in openhands-sdk and openhands-agent-server before defining the server-facing behavior. Done means the selected capability reaches parity and the compatibility matrix accurately reflects its support.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100