Skip to main content

​
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.