Documentation
¶
Overview ¶
Package agui provides types and helpers for the Agent GUI (AG-UI) event protocol used by Genie to stream agent state to UIs (TUI, web, external systems).
It solves the problem of standardizing how agent events (run started, tool calls, thinking, errors) are represented and forwarded. Events can be wrapped in CloudEvents v1.0 envelopes for integration with event buses, audit pipelines, and observability stacks that expect CloudEvents.
Key types: AgentThinkingMsg, WrapInCloudEvent. The TUI and TCP listener consume raw AG-UI events; external systems receive CloudEvents-wrapped payloads.
Index ¶
- Constants
- func ChannelFor(ctx context.Context) chan<- interface{}
- func Deregister(origin messenger.MessageOrigin)
- func Emit(ctx context.Context, event interface{})
- func EmitAgentMessage(ctx context.Context, sender, message string)
- func EmitCompletion(ctx context.Context, success bool, message string, outputDir string)
- func EmitError(ctx context.Context, err error, context_ string)
- func EmitStageProgress(ctx context.Context, stage string, stageIndex, totalStages int)
- func EmitThinking(ctx context.Context, agentName, message string)
- func IsSuppressEmit(ctx context.Context) bool
- func Register(origin messenger.MessageOrigin, ch chan<- interface{})
- func RunIDFromContext(ctx context.Context) string
- func ThreadIDFromContext(ctx context.Context) string
- func WithRunID(ctx context.Context, runID string) context.Context
- func WithSuppressEmit(ctx context.Context) context.Context
- func WithThreadID(ctx context.Context, threadID string) context.Context
- type AGUIEvent
- type AgentChatMessage
- type AgentCompleteMsg
- type AgentErrorMsg
- type AgentReasoningMsg
- type AgentStreamChunkMsg
- type AgentThinkingMsg
- type AgentToolCallMsg
- type AgentToolResponseMsg
- type BGWorker
- type ClarificationRequestMsg
- type CloudEvent
- type EventRequest
- type EventType
- type HealthResult
- type LogEntry
- type LogLevel
- type LogMsg
- type StageProgressMsg
- type TextMessageEndMsg
- type TextMessageStartMsg
- type ToolApprovalRequestMsg
- type ToolCallArgsMsg
- type ToolCallEndMsg
- type UserInputMsg
Constants ¶
const ( EventRunStarted = "RUN_STARTED" EventRunFinished = "RUN_FINISHED" EventRunError = "RUN_ERROR" EventTextMessageStart = "TEXT_MESSAGE_START" EventTextMessageContent = "TEXT_MESSAGE_CONTENT" EventTextMessageEnd = "TEXT_MESSAGE_END" EventReasoningMessageContent = "REASONING_MESSAGE_CONTENT" EventToolCallStart = "TOOL_CALL_START" EventToolCallArgs = "TOOL_CALL_ARGS" EventToolCallEnd = "TOOL_CALL_END" EventToolCallResult = "TOOL_CALL_RESULT" EventStepStarted = "STEP_STARTED" EventStepFinished = "STEP_FINISHED" // Not currently used but good for completeness EventCustom = "CUSTOM" EventToolApprovalRequest = "TOOL_APPROVAL_REQUEST" EventClarificationRequest = "CLARIFICATION_REQUEST" )
Event types for AG-UI wire format (SSE)
Variables ¶
This section is empty.
Functions ¶
func ChannelFor ¶
ChannelFor returns the event channel for the context's MessageOrigin, or nil if none is registered. Useful when callers need the raw channel (e.g. for blocking sends without the default drop behavior).
func Deregister ¶
func Deregister(origin messenger.MessageOrigin)
Deregister removes the channel for a MessageOrigin. Must be called (typically via defer) when the request completes, before the eventChan is closed, to prevent sends to a closed channel.
func Emit ¶
Emit sends an event to the channel registered for the context's MessageOrigin. If no channel is registered (e.g. background tasks, non-AGUI messengers), the event is silently dropped.
This is the primary API. Any code that has a context.Context can emit events without needing an explicit channel reference.
func EmitAgentMessage ¶
EmitAgentMessage sends a chat message to the UI via the event bus. It assigns a new MessageID so SSE TEXT_MESSAGE_CONTENT events have a messageId for the client to associate with a message bubble.
func EmitCompletion ¶
EmitCompletion is a helper to emit completion events.
func EmitStageProgress ¶
EmitStageProgress is a helper to emit stage progress events.
func EmitThinking ¶
EmitThinking is a helper to emit thinking/processing events.
func IsSuppressEmit ¶
IsSuppressEmit reports whether the context has suppress-emit set.
func Register ¶
func Register(origin messenger.MessageOrigin, ch chan<- interface{})
Register stores the event channel for a request's MessageOrigin. Must be called at the request entry point (e.g. AG-UI handleRun). The origin string is used as the map key for O(1) lookup.
func RunIDFromContext ¶
RunIDFromContext returns the RunID stored in the context by the AG-UI handler.
func ThreadIDFromContext ¶
ThreadIDFromContext returns the ThreadID stored in the context by the AG-UI handler.
func WithRunID ¶
WithRunID stores the RunID in context so nested tools (e.g. create_agent) can propagate it to sub-agent tool wrappers for HITL correlation.
func WithSuppressEmit ¶
WithSuppressEmit returns a context that causes Emit to be a no-op for that subtree. Use this when generating front-desk responses (e.g. salutation) that should not appear in the AG-UI chat panel.
Types ¶
type AGUIEvent ¶
type AGUIEvent interface {
AGUIType() string
}
AGUIEvent is a common interface for all AG-UI events.
type AgentChatMessage ¶
AgentChatMessage is a complete chat message (non-streaming).
func (AgentChatMessage) AGUIType ¶
func (m AgentChatMessage) AGUIType() string
type AgentCompleteMsg ¶
AgentCompleteMsg indicates the run has finished.
func (AgentCompleteMsg) AGUIType ¶
func (m AgentCompleteMsg) AGUIType() string
type AgentErrorMsg ¶
type AgentErrorMsg struct {
Type string
Error error
Context string // e.g., "init", "run", "tool_execution"
}
AgentErrorMsg indicates an error occurred.
func (AgentErrorMsg) AGUIType ¶
func (m AgentErrorMsg) AGUIType() string
type AgentReasoningMsg ¶
AgentReasoningMsg carries reasoning content (Chain of Thought).
func (AgentReasoningMsg) AGUIType ¶
func (m AgentReasoningMsg) AGUIType() string
type AgentStreamChunkMsg ¶
AgentStreamChunkMsg carries a chunk of text content.
func (AgentStreamChunkMsg) AGUIType ¶
func (m AgentStreamChunkMsg) AGUIType() string
type AgentThinkingMsg ¶
AgentThinkingMsg indicates the agent is starting work or thinking.
func (AgentThinkingMsg) AGUIType ¶
func (m AgentThinkingMsg) AGUIType() string
type AgentToolCallMsg ¶
AgentToolCallMsg indicates a tool call is starting.
func (AgentToolCallMsg) AGUIType ¶
func (m AgentToolCallMsg) AGUIType() string
type AgentToolResponseMsg ¶
type AgentToolResponseMsg struct {
Type string
ToolCallID string
ToolName string
Response string
Error error
}
AgentToolResponseMsg carries the result of a tool execution.
func (AgentToolResponseMsg) AGUIType ¶
func (m AgentToolResponseMsg) AGUIType() string
type BGWorker ¶
type BGWorker interface {
Start(ctx context.Context) error
HealthCheck(ctx context.Context) []HealthResult
Stop() error
}
BGWorker is an interface for background workers that can be started and stopped. Implementations include the cron scheduler (pkg/cron).
type ClarificationRequestMsg ¶
type ClarificationRequestMsg struct {
Type string
RequestID string
Question string
Context string // optional: why the LLM needs this information
}
ClarificationRequestMsg asks the user a clarifying question.
func (ClarificationRequestMsg) AGUIType ¶
func (m ClarificationRequestMsg) AGUIType() string
type CloudEvent ¶
type CloudEvent struct {
// SpecVersion is the CloudEvents specification version (always "1.0").
SpecVersion string `json:"specversion"`
// ID is a unique identifier for this event (UUID v4).
ID string `json:"id"`
// Source identifies the context in which the event happened, e.g.
// "genie/reactree/stage-2" or "genie/orchestrator".
Source string `json:"source"`
// Type is the CloudEvents type, e.g. "ai.genie.agui.RUN_STARTED".
Type string `json:"type"`
// Time is the timestamp when the event was produced.
Time time.Time `json:"time"`
// Data is the AG-UI event payload.
Data interface{} `json:"data"`
}
CloudEvent wraps an AG-UI event payload in a CloudEvents v1.0 envelope. See https://cloudevents.io for the specification.
This is used when forwarding agent events to external systems (event buses, audit pipelines, observability stacks) that expect CloudEvents. The TUI and TCP listener continue to use raw AG-UI events internally.
func WrapInCloudEvent ¶
func WrapInCloudEvent(evt interface{}, source string) CloudEvent
WrapInCloudEvent wraps an AGUIEvent in a CloudEvents v1.0 envelope. The source parameter identifies where the event originated (e.g. "genie/reactree/stage-2"). If the event does not implement AGUIEvent, the type is set to "ai.genie.agui.CUSTOM".
type EventRequest ¶
type EventRequest struct {
Type EventType `json:"type"`
Source string `json:"source"` // e.g., "github", "cron"
Payload json.RawMessage `json:"payload,omitempty"` // Flexible payload
}
EventRequest represents the payload for an event. Used by cron dispatcher, background worker, and event gateway.
type EventType ¶
type EventType string
EventType defines the type of event (e.g., webhook, heartbeat).
type HealthResult ¶
type HealthResult struct {
Healthy bool `json:"healthy"`
LastError string `json:"last_error,omitempty"`
FailureCount int `json:"failure_count"`
Name string `json:"name"`
}
HealthResult reports the health status of a background worker or subsystem. Used by cron scheduler health checks and heartbeat diagnostics.
type StageProgressMsg ¶
type StageProgressMsg struct {
Type string
Stage string
Progress float64
StageIndex int
TotalStages int
}
StageProgressMsg indicates progress in a multi-stage workflow.
func (StageProgressMsg) AGUIType ¶
func (m StageProgressMsg) AGUIType() string
type TextMessageEndMsg ¶
TextMessageEndMsg indicates the end of a text message block.
func (TextMessageEndMsg) AGUIType ¶
func (m TextMessageEndMsg) AGUIType() string
type TextMessageStartMsg ¶
TextMessageStartMsg indicates the start of a text message block.
func (TextMessageStartMsg) AGUIType ¶
func (m TextMessageStartMsg) AGUIType() string
type ToolApprovalRequestMsg ¶
type ToolApprovalRequestMsg struct {
Type string
ApprovalID string
ToolName string
Arguments string
Justification string // why the LLM is making this tool call
AutoApproved bool // true if this tool call was automatically approved (skip human challenge)
}
ToolApprovalRequestMsg requests user approval for a tool call.
func (ToolApprovalRequestMsg) AGUIType ¶
func (m ToolApprovalRequestMsg) AGUIType() string
type ToolCallArgsMsg ¶
ToolCallArgsMsg carries streaming arguments for a tool call.
func (ToolCallArgsMsg) AGUIType ¶
func (m ToolCallArgsMsg) AGUIType() string
type ToolCallEndMsg ¶
ToolCallEndMsg indicates a tool call definition is complete.
func (ToolCallEndMsg) AGUIType ¶
func (m ToolCallEndMsg) AGUIType() string
type UserInputMsg ¶
type UserInputMsg struct {
Content string
}
UserInputMsg represents input from the user (e.g. from stdin).
func (UserInputMsg) AGUIType ¶
func (m UserInputMsg) AGUIType() string