Skip to content

Event Types

Base Event

All events derive from the base Event class, which has these common properties:

  • agent: The name of the agent that generated the event
  • type: The type of the event (e.g., "prompt", "chat_output")
  • payload: The data associated with the event
  • depth: The nesting level (0 for top-level agent, 1+ for sub-agents)

Communication Events

Prompt

Represents a request sent to an agent to perform an operation.

Prompt(
    agent="my_agent",
    message="What's the weather like today?",
    debug=DebugLevel.NONE,
    request_context={},  # Optional context data
    depth=0,  # Level in agent hierarchy
    ignore_result=False,  # Whether to ignore the result
    request_id=None  # Optional request ID (auto-generated if None)
)

PromptStarted

Signals that an agent has started processing a prompt.

PromptStarted(
    agent="my_agent",
    message="What's the weather like today?",
    depth=0
)

ResetHistory

Indicates that an agent's conversation history has been reset.

ResetHistory(agent="my_agent")

ChatOutput

Output containing a chat message.

ChatOutput(
    agent="my_agent",
    payload={"content": "This is a response", "role": "assistant"},
    depth=0
)

TurnEnd

Signals the completion of an agent's processing for a run.

TurnEnd(
    agent="my_agent",
    messages=[{"role": "assistant", "content": "Final response"}],
    run_context=run_context_obj,
    depth=0
)

TurnCancelled

Indicates that an agent's run was cancelled.

TurnCancelled(agent="my_agent", depth=0)

ToolCall

Represents an agent calling a tool with arguments.

ToolCall(
    agent="my_agent",
    name="weather_tool",
    arguments={"location": "New York"},
    depth=0
)

ToolResult

Contains the result returned from a tool call.

ToolResult(
    agent="my_agent",
    name="weather_tool",
    result="It's 75°F and sunny in New York",
    depth=0
)

ToolError

Represents an error that occurred during a tool call.

ToolError(
    agent="my_agent",
    name="weather_tool",
    error="Failed to retrieve weather data: API timeout",
    depth=0
)

LLM Completion Events

StartCompletion

Signals the start of an LLM completion operation.

StartCompletion(agent="my_agent", depth=0)

FinishCompletion

Contains information about a completed LLM operation, including token usage and cost.

FinishCompletion.create(
    agent="my_agent",
    llm_message="The generated response",
    model="gpt-4",
    cost=0.02,
    input_tokens=150,
    output_tokens=50,
    elapsed_time=1.5,
    depth=0
)

Human-in-the-loop Events

WaitForInput

Indicates that an agent is waiting for human input to continue.

WaitForInput(
    agent="my_agent",
    request_keys={"user_preference": "Please specify your preference"}
)

ResumeWithInput

Sent by the caller with human input to resume an agent's execution.

ResumeWithInput(
    agent="my_agent",
    request_keys={"user_preference": "Option A"},
    request_id="abc123"
)

Authentication Events

OAuthFlow

Emitted when OAuth authentication is required.

OAuthFlow(
    agent="my_agent",
    auth_url="https://example.com/oauth",
    tool_name="github_tool",
    depth=0
)

Agent State Events

SetState

Used to update an agent's internal state.

SetState(agent="my_agent", payload={"key": "value"}, depth=0)

AddChild

Adds a child agent to a parent agent.

AddChild(agent="parent_agent", remote_ref=child_agent_ref, handoff=False)

Special Result Types

These aren't events, but special return values that affect agent flow:

PauseForInputResult

Tells the agent to pause and wait for human input.

PauseForInputResult(request_keys={"user_preference": "Please specify your preference"})

OAuthFlowResult

Indicates that OAuth flow needs to be initiated.

OAuthFlowResult(request_keys={"auth_url": "https://example.com/oauth", "tool_name": "github_tool"})

FinishAgentResult

Tells the agent to stop processing entirely.

FinishAgentResult()

Event Flow Example

A typical event flow for a simple agent interaction might look like:

  1. Prompt - User sends a request to the agent
  2. PromptStarted - Agent begins processing the request
  3. StartCompletion - Agent starts an LLM completion
  4. FinishCompletion - LLM generates a response
  5. ToolCall - Agent decides to use a tool
  6. ToolResult - Tool returns a result
  7. StartCompletion - Agent starts another LLM completion
  8. ChatOutput - Agent returns a text response
  9. FinishCompletion - LLM generates final response
  10. TurnEnd - Agent completes processing the request