> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-extend-api-reference-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# openhands.sdk.subagent

> API reference for openhands.sdk.subagent module

***

### class AgentDefinition

Bases: `BaseModel`

Agent definition loaded from Markdown file.

Agents are specialized configurations that can be triggered based on
user input patterns. They define custom system prompts and tool access.

#### Properties

* `color`: str | None
* `description`: str
* `hooks`: HookConfig | None
* `max_iteration_per_run`: int | None
* `mcp_servers`: dict\[str, Any] | None
* `metadata`: dict\[str, Any]
* `model`: str
* `name`: str
* `permission_mode`: str | None
* `profile_store_dir`: str | None
* `skills`: list\[str]
* `source`: str | None
* `system_prompt`: str
* `tools`: list\[str]
* `when_to_use_examples`: list\[str]

#### Methods

#### get\_confirmation\_policy()

Convert permission\_mode to a ConfirmationPolicyBase instance.

Returns None when permission\_mode is None (inherit parent policy).

#### classmethod load()

Load an agent definition from a Markdown file.

Agent Markdown files have YAML frontmatter with:

* name: Agent name
* description: Description with optional `<example>` tags for triggering
* tools (optional): List of allowed tools
* skills (optional): Comma-separated skill names or list of skill names
* mcp\_servers (optional): MCP server configurations mapping
* model (optional): Model profile to use (default: ‘inherit’)
* color (optional): Display color
* permission\_mode (optional): How the subagent handles permissions

(‘always\_confirm’, ‘never\_confirm’, ‘confirm\_risky’). None inherits parent.

* max\_iterations\_per\_run: Max iteration per run
* hooks (optional): List of applicable hooks

The body of the Markdown is the system prompt.

* Parameters:
  `agent_path` – Path to the agent Markdown file.
* Returns:
  Loaded AgentDefinition instance.

#### model\_config = (configuration object)

Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].

#### NOTE

Failures to load individual files are logged as warnings with stack traces
but do not halt the overall loading process.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.