Prompts & Retry API

This page documents the exported prompt builders, the static prompt/tool description constants, and the auto-retry helpers.

Prompt Builders

get_subagent_system_prompt

subagents_pydantic_ai.get_subagent_system_prompt(configs, include_dual_mode=False)

Generate the system prompt section describing available subagents.

Parameters:

Name	Type	Description	Default
configs	list[SubAgentConfig]	Subagent configurations to list.	required
include_dual_mode	bool	Append DUAL_MODE_SYSTEM_PROMPT, explaining sync versus background execution. Off by default because TASK_TOOL_DESCRIPTION already covers execution modes where the model needs them, and repeating it in the system prompt is wasted context. The parameter used to be accepted and ignored.	False

Returns:

Type	Description
str	Formatted system prompt section.

Example

Python

configs = [
    SubAgentConfig(
        name="researcher",
        description="Researches topics",
        instructions="...",
    ),
]
prompt = get_subagent_system_prompt(configs)

Source code in src/subagents_pydantic_ai/prompts.py

def get_subagent_system_prompt(
    configs: list[SubAgentConfig],
    include_dual_mode: bool = False,
) -> str:
    """Generate the system prompt section describing available subagents.

    Args:
        configs: Subagent configurations to list.
        include_dual_mode: Append `DUAL_MODE_SYSTEM_PROMPT`, explaining sync
            versus background execution. Off by default because
            `TASK_TOOL_DESCRIPTION` already covers execution modes where the
            model needs them, and repeating it in the system prompt is wasted
            context. The parameter used to be accepted and ignored.

    Returns:
        Formatted system prompt section.

    Example:
        ```python
        configs = [
            SubAgentConfig(
                name="researcher",
                description="Researches topics",
                instructions="...",
            ),
        ]
        prompt = get_subagent_system_prompt(configs)
        ```
    """
    lines = [
        "## Available Subagents",
        "",
        "Use the `task` tool to delegate work to these subagents:",
        "",
    ]

    for config in configs:
        line = f"- **{config['name']}**: {config['description']}"
        if config.get("can_ask_questions") is False:
            line += " *(cannot ask clarifying questions)*"
        lines.append(line)

    if include_dual_mode:
        lines.extend(["", DUAL_MODE_SYSTEM_PROMPT])

    return "\n".join(lines)

get_task_instructions_prompt

subagents_pydantic_ai.get_task_instructions_prompt(task_description, can_ask_questions=True, max_questions=None)

Generate the task instructions for a subagent.

Parameters:

Name	Type	Description	Default
task_description	str	The task to perform.	required
can_ask_questions	bool	Whether the subagent can ask the parent questions.	True
max_questions	int | None	Maximum number of questions allowed.	None

Returns:

Type	Description
str	Formatted task instructions.

Source code in src/subagents_pydantic_ai/prompts.py

def get_task_instructions_prompt(
    task_description: str,
    can_ask_questions: bool = True,
    max_questions: int | None = None,
) -> str:
    """Generate the task instructions for a subagent.

    Args:
        task_description: The task to perform.
        can_ask_questions: Whether the subagent can ask the parent questions.
        max_questions: Maximum number of questions allowed.

    Returns:
        Formatted task instructions.
    """
    lines = ["## Your Task", "", task_description, ""]

    if can_ask_questions:
        lines.append("## Asking Questions")
        lines.append("If you need clarification, use the `ask_parent` tool.")
        if max_questions is not None:
            lines.append(f"You may ask up to {max_questions} questions.")
        lines.append("Keep questions specific and essential.")
    else:
        lines.append("## Note")
        lines.append("Complete this task using your best judgment.")
        lines.append("You cannot ask the parent for clarification.")

    return "\n".join(lines)

Prompt & Description Constants

These string constants are exported for inspection and overriding. The *_DESCRIPTION constants are the default model-facing tool descriptions used by create_subagent_toolset (override them per-tool via its descriptions argument).

subagents_pydantic_ai.SUBAGENT_SYSTEM_PROMPT = 'You are a specialized subagent working on a delegated task.\n\n## Your Role\nYou have been spawned by a parent agent to handle a specific task. Focus entirely\non completing the assigned task to the best of your ability.\n\n## Communication\n- If you need clarification, use the `ask_parent` tool to ask the parent agent\n- Keep questions specific and actionable\n- Do not ask unnecessary questions - use your judgment when possible\n- If you cannot complete a task, explain why clearly\n\n## Task Completion\n- Complete the task thoroughly before returning\n- Provide clear, structured results\n- If the task cannot be completed, explain what was attempted and why it failed\n' module-attribute

subagents_pydantic_ai.DUAL_MODE_SYSTEM_PROMPT = '## Subagent Execution Modes\n\nYou can delegate tasks to subagents in two modes:\n\n### Sync Mode (Default)\n- Use for simple, quick tasks\n- Use when you need the result immediately\n- Use when the task requires back-and-forth communication\n- The task runs and you wait for the result\n\n### Async Mode (Background)\n- Use for complex, long-running tasks\n- Use when you can continue with other work while waiting\n- Use for tasks that can run independently\n- Returns a task handle immediately - check status later\n' module-attribute

subagents_pydantic_ai.DEFAULT_GENERAL_PURPOSE_DESCRIPTION = 'A general-purpose agent for a wide variety of tasks.\nUse this when no specialized subagent matches the task requirements.\nCapable of research, analysis, writing, and problem-solving.' module-attribute

subagents_pydantic_ai.TASK_TOOL_DESCRIPTION = TASK_TEXT.render() module-attribute

subagents_pydantic_ai.CHECK_TASK_DESCRIPTION = CHECK_TASK_TEXT.render() module-attribute

subagents_pydantic_ai.ANSWER_SUBAGENT_DESCRIPTION = ANSWER_SUBAGENT_TEXT.render() module-attribute

subagents_pydantic_ai.LIST_ACTIVE_TASKS_DESCRIPTION = LIST_ACTIVE_TASKS_TEXT.render() module-attribute

subagents_pydantic_ai.WAIT_TASKS_DESCRIPTION = WAIT_TASKS_TEXT.render() module-attribute

subagents_pydantic_ai.SOFT_CANCEL_TASK_DESCRIPTION = SOFT_CANCEL_TASK_TEXT.render() module-attribute

subagents_pydantic_ai.HARD_CANCEL_TASK_DESCRIPTION = HARD_CANCEL_TASK_TEXT.render() module-attribute