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.