Skip to main content

Documentation Index

Fetch the complete documentation index at: https://agentrail.app/docs/llms.txt

Use this file to discover all available pages before exploring further.

The stream_events method opens a server-sent event (SSE) connection and yields TaskLifecycleEvent Pydantic models as they arrive. Pass a StreamOptions instance to filter by event type, set a heartbeat interval, and resume from a cursor after reconnection.

​
Basic usage

from agentrail import StreamOptions, TaskEventType

async for event in client.stream_events(
    StreamOptions(
        event_types=[
            TaskEventType.TASK_UPDATED.value,
            TaskEventType.TASK_REVIEWED.value,
            TaskEventType.TASK_SHIPPED.value,
        ],
        heartbeat_seconds=30,
    )
):
    print(event.id, event.type)
The async for loop runs until the server closes the stream or an error is raised. Each event is a validated TaskLifecycleEvent with id, type, and data fields.

​
Reconnect with a cursor

After a disconnect, pass the last received event ID as cursor to resume the stream without missing events: 
from agentrail import StreamOptions, TaskEventType

last_event_id: str | None = None

async for event in client.stream_events(
    StreamOptions(
        event_types=[
            TaskEventType.TASK_UPDATED.value,
            TaskEventType.TASK_REVIEWED.value,
            TaskEventType.TASK_SHIPPED.value,
        ],
        heartbeat_seconds=30,
        cursor=last_event_id,
    )
):
    last_event_id = event.id
    print(event.id, event.type)
The server replays any events that occurred after the cursor position.

​
Event types

TaskEventType valueString valueWhen it fires
TaskEventType.TASK_UPDATEDtask.updatedThe task’s status, branch, or metadata changed
TaskEventType.TASK_REVIEWEDtask.reviewedA review decision was posted
TaskEventType.TASK_SHIPPEDtask.shippedThe task was shipped (merged and deployed)
Set heartbeat_seconds to a value lower than your infrastructure’s idle connection timeout. A value of 30 works well for most deployments.

​
StreamOptions fields

FieldTypeDescription
event_typeslist[str] | NoneEvent type strings to subscribe to. None receives all types.
task_idstr | NoneScope the stream to a single task.
cursorstr | NoneResume from this event ID.
heartbeat_secondsint | NoneInterval for server-sent heartbeat pings.

​
Required scope

Streaming events requires the events:read scope on your API key. A missing scope raises an InsufficientScopeError before the stream opens.