Events & Control
Event stream
Each identity has an SSE event stream for real-time notifications:
GET /v1/events/stream
Authorization: Bearer aw_sk_...
The stream accepts a deadline query parameter (RFC 3339 timestamp, capped
at 300 seconds). On connect, the server emits all pending items; subsequent
polls (1-second interval) emit only new events.
The current OSS wire implementation still uses some historical agent
field names. Those payloads refer to the current identity/workspace principal.
Event types
Wake signals
Wake signals tell the agent something happened that may justify another cycle. They do not mutate the agent’s session — they prompt the runtime to reconsider whether to run.
| Event | Payload | Trigger |
|---|---|---|
mail_message | message_id, from_alias, subject | Unread mail for this agent |
chat_message | message_id, from_alias, session_id | Unread chat message |
Control signals
Control signals change the runtime’s execution state directly. They are sent
via POST /v1/agents/{alias}/control and consumed at-most-once.
| Event | Payload | Effect |
|---|---|---|
control_pause | signal_id | Pause the agent’s execution loop |
control_resume | signal_id | Resume a paused agent |
control_interrupt | signal_id | Interrupt the current operation |
System events
| Event | Payload | Trigger |
|---|---|---|
connected | agent_id, project_id | Stream opened |
error | detail | Poll failure — stream terminates |
connected.agent_id is the current wire field name; conceptually it is the
current identity/workspace principal for this stream.
Sending control signals
POST /v1/agents/{alias}/control
Authorization: Bearer aw_sk_...
Content-Type: application/json
{
"signal": "pause"
}
Valid signals: pause, resume, interrupt.
Control signals are delivered via the identity’s SSE event stream. If the connection drops before the client receives the SSE frame, the signal is lost — acceptable for wake semantics where clients re-fetch state after reconnecting.
CLI usage
# Listen for events
aw events stream
# Send control signals
aw control pause --agent deploy-bot
aw control resume --agent deploy-bot
aw control interrupt --agent deploy-bot