Let tool functions yield custom events

[DouweM]

• Closes Send custom events from tool function, for AG-UI and event_stream_handler #2382

Example based on https://ai.pydantic.dev/ag-ui/#events, using ag_ui.core.CustomEvent and ToolReturn:

@agent.tool_plain
async def yield_custom() -> AsyncIterator[CustomEvent | ToolReturn]:
    yield CustomEvent(
        type=EventType.CUSTOM,
        name='custom_event1',
        value={'key1': 'value1'},
    )
    yield CustomEvent(
        type=EventType.CUSTOM,
        name='custom_event2',
        value={'key2': 'value2'},
    )
    yield ToolReturn('Done')

If the yielded item is a pydantic_ai.messages.CustomEvent, it'll show up in the event streams as-is. If it's ToolReturn, it's the tool return value. If it's Anything else, it'll be wrapped in a CustomEvent.

AG-UI integration automatically forwards ag_ui.core.CustomEvent payloads to the frontend.

---

To do:

• Some cleanup (see todo comments)
• Handle exceptions
• Temporal, DBOS, etc
• Vercel AI data-* custom chunk type Support Vercel AI Data Stream Protocol #2923
• Docs

[github-actions]

Docs Preview

commit:	d349a7a
Preview URL:	https://bd566ace-pydantic-ai-previews.pydantic.workers.dev