agui

package
v0.1.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 10, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

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

View Source
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

func ChannelFor(ctx context.Context) chan<- interface{}

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

func Emit(ctx context.Context, event interface{})

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

func EmitAgentMessage(ctx context.Context, sender, message string)

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

func EmitCompletion(ctx context.Context, success bool, message string, outputDir string)

EmitCompletion is a helper to emit completion events.

func EmitError

func EmitError(ctx context.Context, err error, context_ string)

EmitError is a helper to emit error events.

func EmitStageProgress

func EmitStageProgress(ctx context.Context, stage string, stageIndex, totalStages int)

EmitStageProgress is a helper to emit stage progress events.

func EmitThinking

func EmitThinking(ctx context.Context, agentName, message string)

EmitThinking is a helper to emit thinking/processing events.

func IsSuppressEmit

func IsSuppressEmit(ctx context.Context) bool

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

func RunIDFromContext(ctx context.Context) string

RunIDFromContext returns the RunID stored in the context by the AG-UI handler.

func ThreadIDFromContext

func ThreadIDFromContext(ctx context.Context) string

ThreadIDFromContext returns the ThreadID stored in the context by the AG-UI handler.

func WithRunID

func WithRunID(ctx context.Context, runID string) context.Context

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

func WithSuppressEmit(ctx context.Context) context.Context

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.

func WithThreadID

func WithThreadID(ctx context.Context, threadID string) context.Context

WithThreadID stores the ThreadID in context so nested tools (e.g. create_agent) can propagate it to sub-agent tool wrappers for HITL correlation.

Types

type AGUIEvent

type AGUIEvent interface {
	AGUIType() string
}

AGUIEvent is a common interface for all AG-UI events.

type AgentChatMessage

type AgentChatMessage struct {
	Type      string
	MessageID string
	Sender    string
	Message   string
}

AgentChatMessage is a complete chat message (non-streaming).

func (AgentChatMessage) AGUIType

func (m AgentChatMessage) AGUIType() string

type AgentCompleteMsg

type AgentCompleteMsg struct {
	Type      string
	Success   bool
	Message   string
	OutputDir string
}

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

type AgentReasoningMsg struct {
	Type    string
	Content string
	Delta   bool
}

AgentReasoningMsg carries reasoning content (Chain of Thought).

func (AgentReasoningMsg) AGUIType

func (m AgentReasoningMsg) AGUIType() string

type AgentStreamChunkMsg

type AgentStreamChunkMsg struct {
	Type      string
	MessageID string
	Content   string
	Delta     bool
}

AgentStreamChunkMsg carries a chunk of text content.

func (AgentStreamChunkMsg) AGUIType

func (m AgentStreamChunkMsg) AGUIType() string

type AgentThinkingMsg

type AgentThinkingMsg struct {
	Type      string
	AgentName string
	Message   string
}

AgentThinkingMsg indicates the agent is starting work or thinking.

func (AgentThinkingMsg) AGUIType

func (m AgentThinkingMsg) AGUIType() string

type AgentToolCallMsg

type AgentToolCallMsg struct {
	Type       string
	ToolName   string
	Arguments  string
	ToolCallID string
}

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).

const (
	EventTypeWebhook   EventType = "webhook"
	EventTypeHeartbeat EventType = "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 LogEntry

type LogEntry struct {
	Timestamp time.Time
	Level     LogLevel
	Message   string
	Source    string
}

LogEntry represents a single log entry with timestamp.

type LogLevel

type LogLevel int

LogLevel defines the severity of a log entry.

const (
	LogDebug LogLevel = iota
	LogInfo
	LogWarn
	LogError
)

func (LogLevel) String

func (l LogLevel) String() string

type LogMsg

type LogMsg struct {
	Type    string
	Level   LogLevel
	Message string
	Source  string
}

LogMsg carries a log entry.

func (LogMsg) AGUIType

func (m LogMsg) AGUIType() string

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

type TextMessageEndMsg struct {
	Type      string
	MessageID string
}

TextMessageEndMsg indicates the end of a text message block.

func (TextMessageEndMsg) AGUIType

func (m TextMessageEndMsg) AGUIType() string

type TextMessageStartMsg

type TextMessageStartMsg struct {
	Type      string
	MessageID string
}

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

type ToolCallArgsMsg struct {
	Type       string
	ToolCallID string
	Delta      string
}

ToolCallArgsMsg carries streaming arguments for a tool call.

func (ToolCallArgsMsg) AGUIType

func (m ToolCallArgsMsg) AGUIType() string

type ToolCallEndMsg

type ToolCallEndMsg struct {
	Type       string
	ToolCallID string
}

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

Directories

Path Synopsis
Code generated by counterfeiter.
Code generated by counterfeiter.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL