- Streaming: Iterate over events in real-time using a Python iterator
- Handlers: Register callback functions that are called for each event
Streaming
New in version 0.12.0 When you enable streaming, task execution returns an iterator that yields events as they occur. Each iteration provides a tuple of (event, snapshot, delta) representing what just happened in the workflow:Stream
enum. Here, we return only content updates:
Stream.ALL
: All events (equivalent tostream=True
)Stream.CONTENT
: Agent content and content deltasStream.TOOLS
: All tool eventsStream.COMPLETION_TOOLS
: Completion tool events (like marking a task successful or failed)Stream.AGENT_TOOLS
: Tools used by agents for any purpose other than completing a taskStream.TASK_EVENTS
: Task lifecycle events (starting, completion, failure, etc)
|
operator:
Handlers
New in version 0.9.2 For more complex event processing, or when you want to decouple event handling from your main workflow, use handlers:- Adding logging or monitoring
- Collecting metrics
- Updating UI elements
- Processing events asynchronously
on_<event-name>
methods for each event type. For a complete list of available methods, see the Event Details section below.
Async Handlers
New in version 0.11.1 For asynchronous event processing, useAsyncHandler
:
Example: Real-time Content Display
Here’s a complete example showing both approaches to display content in real-time:Event Details
Now that we’ve seen how to process events, let’s look at the types of events you can receive:Content Events
Content events give you access to what an agent is saying or writing:Tool Events
Tool events let you observe when agents use tools and get their results:Workflow Events
Task Events
Events that mark key points in a task’s lifecycle:TaskStart
: A task has begun executionTaskSuccess
: A task completed successfully (includes the final result)TaskFailure
: A task failed (includes the error reason)TaskSkipped
: A task was skipped
Orchestration Events
Events related to orchestrating the overall workflow:OrchestratorStart
/End
: Workflow orchestration starting/endingAgentTurnStart
/End
: An agent’s turn starting/endingOrchestratorError
: An error occurred during orchestration
Handler Methods
Each handler can implement methods for different types of events. The method will be called whenever that type of event occurs. Here are all available handler methods:Method | Event Type | Description |
---|---|---|
on_event(event) | Any | Called for every event, before any specific handler |
on_agent_message(event) | AgentMessage | Raw LLM output containing both content and tool calls |
on_agent_message_delta(event) | AgentMessageDelta | Incremental updates to raw LLM output |
on_agent_content(event) | AgentContent | Unstructured text output from an agent |
on_agent_content_delta(event) | AgentContentDelta | Incremental updates to agent content |
on_agent_tool_call(event) | AgentToolCall | Tool being called by an agent |
on_agent_tool_call_delta(event) | AgentToolCallDelta | Incremental updates to a tool call |
on_tool_result(event) | ToolResult | Result returned from a tool |
on_orchestrator_start(event) | OrchestratorStart | Workflow orchestration starting |
on_orchestrator_end(event) | OrchestratorEnd | Workflow orchestration completed |
on_agent_turn_start(event) | AgentTurnStart | An agent beginning their turn |
on_agent_turn_end(event) | AgentTurnEnd | An agent completing their turn |
on_orchestrator_error(event) | OrchestratorError | Error during orchestration |
- Handle all LLM output in one place with
on_agent_message
- Handle just content with
on_agent_content
- Handle just tool calls with
on_agent_tool_call