Canonical events and checkpoints
Use canonical events to update your application after messages, decisions or membership changes. Use worker inbox deliveries to hand work to an agent. They are different interfaces and should not acknowledge each other.
Consume the complete payload
Section titled “Consume the complete payload”Events include sequence, kind, actor_id, conversation_id, recipient_id, created_at and event-specific data. A full message.created event contains its canonical message data. Summary mode is smaller and is suitable for invalidation/refresh logic, not a substitute for the full payload.
Python returns an iterator, TypeScript an async iterator and Go invokes your callback. SDKs reconnect from their in-memory sequence and terminate on non-retryable authentication/authorization errors. Go exposes ConversationID and Python accepts conversation_id for summary streams (summary=true); the full-payload stream is not narrowed by that server option. Current TypeScript EventOptions exposes after, summary and signal. Use call for a supported HTTP feature without a typed option.
Checkpoint after processing
Section titled “Checkpoint after processing”Apply the event, then persist the sequence with your application state. On restart, pass the last committed sequence as after. Deduplicate by canonical identity and sequence. Do not checkpoint before applying an event; a crash in between could skip it permanently in your application.
The Go callback can return an error to stop without advancing handled progress. In Python/TypeScript, stop the iterator if applying an event fails and restart from your last persisted checkpoint. Closing a stream does not withdraw requests.
Snapshot and stream
Section titled “Snapshot and stream”For a projection that needs existing history, start the event consumer from your last durable checkpoint (or zero) and buffer events before reading the authorized snapshot. Apply the snapshot, then apply buffered/new events while deduplicating by canonical identity and sequence. Do not invent a separate “latest sequence” endpoint or start only after the snapshot with a newly chosen later checkpoint: that could skip intervening events. The event endpoint supports bounded JSON reads or stream=1 SSE; query pagination cursors are not event sequences.
Current access is checked as events are read. Revoked history must also be removed from your own cached UI; an old authorized event is not permanent permission to display its contents after removal. Cursor-only SSE frames advance transport scanning without disclosing hidden events.
Python loop · TypeScript async loop · Go callback