Skip to main content
This guide explains how the OpenHands app (V1) composes an SDK Agent when you start a conversation in the GUI, and where you can customize behavior using the SDK.
Best read alongside:

​
How the App Loads an SDK Agent

When you start a V1 conversation from the GUI, the app-server:
  • Launches an SDK Agent Server (locally or via the configured host)
  • Builds a StartConversationRequest that includes an Agent specification
  • Sends that request to the Agent Server’s conversation API
Key references:
  • App builds the V1 router only if V1 is enabled: server/app.py
  • Conversation request assembly: live_status_app_conversation_service.py
  • Agent Server endpoints: conversation_router.py, server_details_router.py

​
Customization Paths

​
1) Skills and MCP (No-Code)

The app merges skills and MCP server config into the agent context:
  • User skills from ~/.openhands/skills and ~/.openhands/microagents/
  • Repo/org skills resolved from your working repository
  • MCP servers from settings and defaults (OpenHands + Tavily)
This path lets you steer agent behavior without changing code.

​
2) Agent Type Selection (Low-Code)

The app selects an Agent preset based on AgentType (DEFAULT or PLAN). You can:
  • Toggle the AgentType in the Start request (UI or API)
  • Adjust LLM and MCP settings in the UI
See also SDK presets for default and planning agents.

​
3) Define a New Agent Type in the App (Advanced)

If you need the GUI to instantiate a different agent layout (custom tools, system prompt, etc.):
  1. Add a new enum value to AgentType in the app
  2. Extend the builder to construct your custom Agent for that type
  3. Optionally expose it in the frontend for selection
This keeps the App as the source of truth for Agent construction while leveraging SDK components.

​
Validate with the SDK First

Before wiring into the App, validate your design directly with the SDK:
  • Run the Local Agent Server guide to test endpoints
  • Use the Creating Custom Agent guide to build presets and behaviors

​
See Also

  • /sdk/guides/agent-custom
  • /sdk/guides/custom-tools
  • /sdk/guides/mcp
  • /sdk/guides/agent-server/overview
  • /sdk/guides/agent-server/local-server