Events

Events are Python objects that components use to communicate in the Line SDK.

What is an Event?

An event is a Python object that carries information between nodes, bridges, and the user.

Basic Example

from pydantic import BaseModel
from line.events import UserTranscriptionReceived, AgentResponse

# Built-in events
user_message = UserTranscriptionReceived(
    content="Hello, how are you?"
)
agent_reply = AgentResponse(content="I'm doing well, thank you!")


# Custom events
class CustomerInsight(BaseModel):
    customer_id: str
    sentiment: str
    priority_level: str


insight = CustomerInsight(
    customer_id="123", sentiment="positive", priority_level="high"
)

Built-in Event Types

For a full list of built-in events and their descriptions, see line/events.py.

Category	Events
User Events	UserTranscriptionReceived, UserStartedSpeaking,UserStoppedSpeaking
Agent Events	AgentResponse, AgentStartedSpeaking,AgentStoppedSpeaking
System Events	ToolCall, ToolResult, AgentHandoff, EndCall

Events let components communicate without being tightly coupled. See Agent Patterns for examples.

Defining Custom Event Types

Any object can be an event. This is useful for passing arbitrary data between components.

Use structured classes like Pydantic BaseModel or Python dataclasses for your custom events. This provides type safety and validation and makes your code more readable.

from pydantic import BaseModel


class MyEvent(BaseModel):
    field1: str
    field2: int

Messages

Messages are the wrappers around events. They contain the event, but also additional metadata:

Field	Description
event	The event object
source	The node that sent the event
timestamp	The time the event was sent

Events are automatically wrapped in Messages before being sent to the bus.