---

name: ai-python-subagents description: Use for the subagent-as-a-tool pattern. metadata: sdk-version: "0.4.0"

ai-python-subagents

Use a subagent tool when the parent model should choose when to call another agent.

@ai.tool
async def research(topic: str) -> ai.SubAgentTool:
    child = ai.Agent(tools=[lookup])
    messages = [
        ai.system_message("Research briefly."),
        ai.user_message(topic),
    ]

    async with child.run(model, messages) as stream:
        async for event in stream:
            yield event

The parent model sees the child agent's final assistant text as the tool result. The caller sees child events as ai.events.PartialToolCallResult.

Render nested output from event.value:

if isinstance(event, ai.events.PartialToolCallResult):
    if isinstance(event.value, ai.events.TextDelta):
        print(event.value.chunk, end="", flush=True)

Do not append child messages to the parent history yourself. The tool result stores the child transcript as a MessageBundle.

For MessageBundle, preliminary output, and streaming tool details, use ai-python-streaming-tools.