Events

Events

The agent communicates state transitions via an event bus. Every meaningful action emits an sdk.Event to all registered subscribers.

Subscribing

ag.Subscribe(func(e sdk.Event) {
    switch e.Type {
    case sdk.EventTextDelta:
        fmt.Print(e.Content)
    case sdk.EventToolCall:
        fmt.Printf("[tool: %s]\n", e.ToolCall.Name)
    case sdk.EventAgentEnd:
        fmt.Println("\ndone")
    }
})

Multiple subscribers are allowed. Each runs in its own goroutine. The EventBus is non-blocking — Publish enqueues to a 4096-item buffered channel per subscriber and returns immediately, so slow subscribers drop events rather than stalling the agent loop.

Event Reference

Type constant	Payload	Fired when
`EventAgentStart`	—	`Prompt()` called, agent loop begins
`EventAgentEnd`	—	Agent loop completes (all turns done)
`EventTurnStart`	—	An LLM request turn begins
`EventTurnEnd`	—	A turn’s tool calls finish
`EventMessageStart`	—	LLM starts streaming a response
`EventMessageEnd`	—	LLM response stream complete
`EventTextDelta`	`e.Content string`	Incremental response text chunk
`EventThinkingDelta`	`e.Content string`	Incremental extended-thinking chunk
`EventToolCall`	`e.ToolCall`	Tool invocation requested by LLM
`EventToolDelta`	`e.Content string`	Streaming partial output from a running tool
`EventToolOutput`	`e.ToolOutput`	Final tool result (success or error)

Event Flow Per Prompt

EventAgentStart
  EventTurnStart
    EventMessageStart
      EventTextDelta*
      EventThinkingDelta*
      EventToolCall*
    EventMessageEnd
    [per tool call]
      EventToolDelta*
      EventToolOutput
  EventTurnEnd
  [repeat if tool calls triggered another turn]
EventAgentEnd

Agent State Machine

The agent transitions through explicit states visible via EventAgentStart/EventAgentEnd and the ag.Idle() channel:

Idle → Thinking → Executing → Idle
           ↓
       Compacting → Idle
           ↓
         Aborting → Idle

ag.Idle() returns a channel that closes when the agent returns to Idle. Use it to block until a prompt completes:

ag.Prompt(ctx, "Refactor main.go")
<-ag.Idle()
// agent is idle, safe to call Prompt again