---

name: software-agent-sdk description: "Router for using and maintaining the OpenHands Software Agent SDK, including local agents, tools, AgentSkills, agent-server runtimes, GitHub automation, and repository development workflows." disable-model-invocation: true metadata: disco-role: operating license: MIT

OpenHands Software Agent SDK

Use this repo skill when a task involves the OpenHands software-agent-sdk packages or source repository: building code agents, selecting built-in tools, loading AgentSkills/plugins/hooks/MCP, running local or remote conversations, using the agent-server and workspace backends, automating GitHub workflows, or maintaining this monorepo.

The runtime packages are:

• openhands-sdk: core agent, LLM, conversation, settings, skills, MCP, hooks, plugins, and workspace interfaces.
• openhands-tools: built-in tool implementations and default presets.
• openhands-workspace: Docker, Apptainer, cloud, and runtime-API remote workspace implementations.
• openhands-agent-server: FastAPI REST/WebSocket server for remote conversations, workspace routes, deferred init, and local/hosted runtimes.

First checks

For an installed package environment:

python -m pip install openhands-sdk openhands-tools openhands-workspace openhands-agent-server
python - <<'PY'
import openhands.sdk, openhands.tools, openhands.workspace, openhands.agent_server
print("OpenHands SDK packages import successfully")
PY
python -m openhands.agent_server --help

For a source checkout, run make build before package tests. Use uv run pytest ... and uv run pre-commit run --files <changed-file> for focused validation.

Run scripts/check_env.py for a safe import/tool/server capability report.

Route map

agent-core

Use sub-skills/agent-core/SKILL.md for local SDK agent construction, LLM configuration, Agent, Conversation, LocalConversation, RemoteConversation, callbacks, async/sync execution, persistence, interruption, condensation, settings, security analyzers, and title generation.

Read it when the request mentions LLM, Agent, Conversation, AgentContext as prompt context rather than skill loading mechanics, local runs, remote conversation factory routing, events, metrics, cancellation, or model/provider behavior.

extensions

Use sub-skills/extensions/SKILL.md for AgentSkills, project/user/public skill loading, plugins and marketplaces, hooks, MCP server maps, memory, secrets, prompt suffixes, and other extension points.

Read it when the request mentions SKILL.md, .agents/skills, .openhands/skills, AGENTS.md, load_project_skills, registered_marketplaces, .mcp.json, HookConfig, LookupSecret, or plugin lazy loading.

built-in-tools

Use sub-skills/built-in-tools/SKILL.md for openhands-tools, default tool presets, tool registration, usable-tool filtering, terminal/file-editor/browser/task/workflow/grep/glob/planning/delegate/TOM tools, custom tool classes, and sub-agent tool wiring.

Read it when the request asks which tool names to use, how to register or resolve tools, how browser availability is detected, how workflow scripts work, or why a tool is missing from /server_info.

remote-runtime

Use sub-skills/remote-runtime/SKILL.md for openhands-agent-server, REST/WebSocket routes, RemoteWorkspace, Workspace(host=...), Docker/Apptainer/API/cloud workspaces, deferred init, session API keys, custom tool import modules, and local server helpers.

Read it when the request mentions python -m openhands.agent_server, /api/conversations, /api/init, X-Session-API-Key, WebSockets, Docker workspace images, OH_EXTRA_PYTHON_PATH, or warm-pool/dormant server behavior.

github-automation

Use sub-skills/github-automation/SKILL.md for SDK-powered GitHub Actions examples, prompt-driven task runners, TODO scanning, examples-report rendering, and automation scripts that run agents from CI.

Read it when the request involves GitHub workflow YAML, PROMPT_STRING, prompt files/URLs, LLM_API_KEY, automated TODO management, routine maintenance actions, PR automation, or example-run summaries.

repo-development

Use sub-skills/repo-development/SKILL.md for maintaining this monorepo: package boundaries, import rules, tool registration linting, settings compatibility, SDK/REST API deprecation policy, test selection, examples runner, release PR checks, pre-commit, and CI workflows.

Read it when editing source code, tests, examples, settings models, public APIs, REST routes, tools, workspace backends, Docker image publishing, or repository automation.

Cross-cutting references

• references/package-overview.md: package surfaces, versions, public imports, and capability ownership.
• references/troubleshooting.md: install/import, credentials, optional browser/runtime, server, workspace, and maintenance failure patterns.
• references/repo-provenance.md: source snapshot and evidence paths used to create this skill; read before deciding whether a skill refresh is needed.
• references/repo-routing-metadata.json: structured metadata consumed by the managed repo-skills-router import flow.

Boundary rules for future agents

• Use this skill as operating guidance; do not import it into live router state unless a user explicitly approves managed import.
• Runtime guidance is self-contained in this skill tree. Do not require access to the original generation checkout to use it.
• When maintaining a fresh checkout of software-agent-sdk, confirm current code and nearby AGENTS.md files before editing because repo policies may have changed after the provenance snapshot.
• Use generated scripts from this skill tree for diagnostics and helper workflows; when editing a live checkout, run that checkout's native tests and scripts from its repository root.