agui

package
v0.228.0 Latest Latest
Warning

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

 Go to latest Published: Oct 9, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

README

agui

What - the AG-UI protocol as a general-purpose package: a writer for the events of one run, and a localhost WebSocket binding with both of its ends. Why - external orchestrators and clients need a stable published event schema carried over a transport that does not care who connects, and the rest of the CLI needs one place that knows the protocol. How - Run writes one run as newline-delimited AG-UI JSON, one event per Write, and guarantees exactly one terminal RUN_FINISHED or RUN_ERROR. Binding owns the listener, the Origin check, the token handshake, the connections and their pings, and hands every frame to its Handler. Dial is the client end and hands the frames it receives to a Handler too.

What it does not know

This package names no client kind, no context and no host. Its only internal import is the logger. Everything else imports it:

  • Run takes text, tool calls, snapshots and CUSTOM events as plain values. Which agent event becomes which AG-UI event is decided by the caller.
  • A Conn carries the client kind its hello declared as an opaque string. What a kind means is the handler's business. It also answers HelloAttr with every other field the hello declared, minus the token, which the binding never interprets either - the browser relay logs the extension's extension_version from there.
  • The handshake frame names, the token, the port and the accepted origins come in through BindingConfig and DialConfig, whose HelloAttrs are the other hello fields a dialing client declares and the host can read back with HelloAttr. BindingConfig.Routes registers optional non-WebSocket HTTP handlers, e.g. static files, under the same loopback listener as /ws. They may serve files and know about clients, the binding does not.
  • The AG-UI SDK stays confined here. Message, Role, ToolCall and FunctionCall are the types a caller builds a MESSAGES_SNAPSHOT from.

Dependencies

The import list is closed. depguard (agui-imports-are-closed in .golangci.yml, strict mode) rejects any import that is not recorded here, in the package and in its tests alike. Adding one means changing the rule and this table in the same change.

Import Used for
Go standard library everything else
github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/core/events the AG-UI events Run writes
github.com/ag-ui-protocol/ag-ui/sdks/community/go/pkg/core/types the MESSAGES_SNAPSHOT message types
github.com/google/uuid message and tool result ids
github.com/gorilla/websocket the socket of Binding and Dial
github.com/inference-gateway/cli/internal/platform/logger logging
github.com/inference-gateway/cli/internal/protocols/agui tests only, the package under test
github.com/inference-gateway/cli/tests/mocks/agui tests only, the generated Handler fake

How it plugs in

  • internal/presentation/headless owns the mapping from agent chat events to a Run (RunEncoder) and the panel units a --serve worker answers panel requests with (Panel).
  • internal/computer returns the CustomEvents it publishes for its own chat events.
  • internal/browser builds the extension relay and client on Binding and Dial.
  • cmd/daemon hosts the one Binding and puts the browser relay and the sessions thread registry behind its handler.

Documentation

Index

Constants

View Source 
const (
	InputContentTypeText  = aguitypes.InputContentTypeText
	InputContentTypeImage = aguitypes.InputContentTypeImage
)

The content part types of a run input message.

View Source 
const (
	ResumeStatusResolved  = aguitypes.ResumeStatusResolved
	ResumeStatusCancelled = aguitypes.ResumeStatusCancelled
)

The statuses a resume entry answers an interrupt with.

View Source 
const (
	InterruptToolCall      = "tool_call"
	InterruptInputRequired = "input_required"
)

The interrupt reasons this CLI raises. AG-UI leaves reason open ended.

View Source 
const (
	StateTodos           = "todos"
	StateUsage           = "usage"
	StateBackgroundTasks = "backgroundTasks"
	StateScreenRecording = "screenRecording"
)

The state keys a run publishes. The state is one object: Start seeds every key, so a STATE_SNAPSHOT always carries all of them, and a change patches one key through STATE_DELTA instead of replacing the others.

View Source 
const OutcomeCancelled = aguievents.RunFinishedOutcomeType("cancelled")

OutcomeCancelled is the cancelled variant of the 1.0 outcome set: a run its caller stopped before it completed, with nothing waited for. The Go SDK names success and interrupt; this names the third variant the spec defines.

Variables

This section is empty.

Functions

func TokenCount added in v0.221.0 

func TokenCount(count int64) *int64

TokenCount returns a pointer to a count, for populating a TokenUsage.

func WriteCustom added in v0.221.0 

func WriteCustom(w io.Writer, name string, value any)

WriteCustom writes one CUSTOM event outside any run - the extension point for what the protocol has no event for, today the approval prompt of a panel-initiated tool request. Run-scoped events never take this path.

func WriteMessagesSnapshot added in v0.221.0 

func WriteMessagesSnapshot(w io.Writer, messages []Message)

WriteMessagesSnapshot writes one MESSAGES_SNAPSHOT outside any run: the conversation-wide answer to a panel's new_session or resume_conversation, which arrives between runs. A run's own restore goes through Run.Snapshot.

func WriteRunError added in v0.221.0 

func WriteRunError(w io.Writer, message string)

WriteRunError writes one RUN_ERROR for a failure outside any run: a refused frame or a process failure before the run starts. No run exists to carry a run id, so the event carries none.

Types

type Binding added in v0.219.0 

type Binding struct {
	// contains filtered or unexported fields
}

Binding hosts the localhost AG-UI WebSocket binding. It owns the listener, the Origin check, the token handshake and the connections, and hands every frame to its Handler.

func NewBinding added in v0.219.0 

func NewBinding(cfg BindingConfig, handler Handler) *Binding

NewBinding builds the binding over its handler.

func (*Binding) Addr added in v0.219.0 

func (b *Binding) Addr() string

Addr returns the actual listen address (useful with port 0 in tests).

func (*Binding) Close added in v0.219.0 

func (b *Binding) Close()

Close shuts the server and every connection down. Each read loop then ends and detaches its connection.

func (*Binding) Start added in v0.219.0 

func (b *Binding) Start() error

Start listens on 127.0.0.1:<port> and serves the /ws endpoint.

type BindingConfig added in v0.219.0 

type BindingConfig struct {
	Port        int
	Token       string
	Handshake   Handshake
	AllowOrigin func(origin string) bool
	Routes      map[string]http.Handler
}

BindingConfig configures the listening end. AllowOrigin decides over requests that carry an Origin header, and without it only requests without one pass. Routes registers optional non-WebSocket HTTP handlers, e.g. static files, which serve under the same loopback listener as /ws.

type Conn added in v0.219.0 

type Conn struct {
	// contains filtered or unexported fields
}

Conn is one authenticated connection, on either end of the binding.

func Dial added in v0.219.0 

func Dial(ctx context.Context, cfg DialConfig, handler Handler) (*Conn, error)

Dial connects to a binding, performs the handshake and hands every frame the binding sends to handler until the connection dies.

func (*Conn) Close added in v0.219.0 

func (c *Conn) Close()

Close closes the connection. Its read loop then ends and detaches it.

func (*Conn) Deliver added in v0.219.0 

func (c *Conn) Deliver(frame []byte)

Deliver queues one frame for the connection's writer, so a stalled peer never holds back the others. An overflow closes the connection, since it means the peer stopped reading its socket. A closed connection drops the frame.

func (*Conn) HelloAttr added in v0.219.0 

func (c *Conn) HelloAttr(key string) string

HelloAttr is one other field the hello declared, empty when the hello omitted it.

func (*Conn) Kind added in v0.219.0 

func (c *Conn) Kind() string

Kind is the client kind the hello declared. The binding never interprets it.

func (*Conn) Send added in v0.219.0 

func (c *Conn) Send(frame []byte) error

Send writes one frame and reports the write's failure.

type DialConfig added in v0.219.0 

type DialConfig struct {
	Addr       string
	Token      string
	Kind       string
	HelloAttrs map[string]string
	Handshake  Handshake
}

DialConfig configures the dialing end. Kind is the client kind the hello declares, and HelloAttrs the other fields it declares, e.g. a version the host reports on.

type FunctionCall added in v0.219.0 

type FunctionCall = aguitypes.FunctionCall

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

type Handler added in v0.219.0 

type Handler interface {
	Attach(conn *Conn)
	Handle(conn *Conn, frame []byte)
	Detach(conn *Conn)
}

Handler receives what happens on a binding's connections. Attach runs once a connection authenticated and before its first frame, Handle once per frame, and Detach after the connection died.

type Handshake added in v0.219.0 

type Handshake struct {
	Hello string
	Ack   string
}

Handshake names the first frame a client sends and the frame that acks it.

type InputContent added in v0.221.0 

type InputContent = aguitypes.InputContent

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

type Interrupt added in v0.221.0 

type Interrupt = aguitypes.Interrupt

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

type Message added in v0.219.0 

type Message = aguitypes.Message

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

type Published added in v0.221.0 

type Published struct {
	StateKey     string
	StateValue   any
	ActivityType string
	MessageID    string
	Content      any
}

Published is what an owning context renders into the run for one of its own chat events: a key patch of the run's state object or an ACTIVITY_SNAPSHOT entry. An event that deserves neither reports false on the publish seam and the run drops it.

type ResumeEntry added in v0.221.0 

type ResumeEntry = aguitypes.ResumeEntry

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

type ResumeStatus added in v0.221.0 

type ResumeStatus = aguitypes.ResumeStatus

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

type Role added in v0.219.0 

type Role = aguitypes.Role

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

type Run added in v0.219.0 

type Run struct {
	// contains filtered or unexported fields
}

Run writes one AG-UI run as newline-delimited events: RUN_STARTED at Start, the events its methods name, and exactly one terminal RUN_FINISHED or RUN_ERROR at Finish. Every event lands within the run, one Write per event, so a transport can map one Write to one frame.

func NewContinuationRun added in v0.221.0 

func NewContinuationRun(w io.Writer, carried map[string]any) *Run

NewContinuationRun builds the writer of a run that continues a suspended one: its STATE_SNAPSHOT seeds the state the suspended run left.

func NewRun added in v0.219.0 

func NewRun(w io.Writer) *Run

NewRun builds the writer of one run over w.

func (*Run) Activity added in v0.221.0 

func (r *Run) Activity(messageID, activityType string, content any)

Activity writes ACTIVITY_SNAPSHOT, the progress or notice of one item of work a client keeps as its own entry: a local agent starting up or a judge verdict. messageId carries the stable identity that replaces the entry.

func (*Run) CloseMessage added in v0.219.0 

func (r *Run) CloseMessage()

CloseMessage ends any open text or reasoning framing, so the next delta starts a fresh message. Safe to call when nothing is open.

func (*Run) Fail added in v0.219.0 

func (r *Run) Fail(err error)

Fail records the failure the run ends with. A later failure replaces it.

func (*Run) Finish added in v0.219.0 

func (r *Run) Finish(result map[string]any, usage []TokenUsage) error

Finish writes the run's one terminal event and returns the failure: a cancelled run ends with outcome cancelled, a failed one with RUN_ERROR, both carrying usage, and a clean run with outcome success carrying the result. Suspend already wrote the terminal, so an interrupted run writes nothing here. A run that failed before it started writes only a RUN_ERROR.

func (*Run) Message added in v0.221.0 

func (r *Run) Message(role Role, content string)

Message writes a complete message with the role it has in the conversation: a note the agent queued or a user message rendered over the run.

func (*Run) PatchState added in v0.221.0 

func (r *Run) PatchState(key string, value any)

PatchState updates one key of the run's state object and writes STATE_DELTA patching exactly that key, so state changes never replace the siblings.

func (*Run) Reasoning added in v0.219.0 

func (r *Run) Reasoning(delta string)

Reasoning writes a reasoning delta, opening the turn's reasoning message on the first one. Reasoning precedes text within one assistant message, so reasoning arriving while text is open closes the previous message first.

func (*Run) Snapshot added in v0.219.0 

func (r *Run) Snapshot(messages []Message)

Snapshot writes MESSAGES_SNAPSHOT.

func (*Run) Start added in v0.219.0 

func (r *Run) Start(threadID, runID string)

Start writes RUN_STARTED and seeds the run's state object, so the first STATE_SNAPSHOT of every run carries all state keys.

func (*Run) State added in v0.219.0 

func (r *Run) State() map[string]any

State returns the run's one state object, live, or nil before Start.

func (*Run) Suspend added in v0.221.0 

func (r *Run) Suspend(interrupts []Interrupt)

Suspend ends the run the AG-UI interrupt way: one terminal RUN_FINISHED whose outcome carries the interrupts the run is waiting on. The caller answers with resume entries on the next run, which continues where this one left off.

func (*Run) Text added in v0.219.0 

func (r *Run) Text(delta string)

Text writes a text delta, opening the turn's assistant message on the first one. It closes an open reasoning block, which precedes text.

func (*Run) ToolCall added in v0.219.0 

func (r *Run) ToolCall(id, name, args string)

ToolCall writes one complete tool call: its start, its arguments when it has any, and its end.

func (*Run) ToolResult added in v0.219.0 

func (r *Run) ToolResult(toolCallID, content string)

ToolResult writes the result of the tool call toolCallID.

type RunAgentInput added in v0.221.0 

type RunAgentInput = aguitypes.RunAgentInput

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

type TokenUsage added in v0.221.0 

type TokenUsage = aguievents.TokenUsage

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

type ToolCall added in v0.219.0 

type ToolCall = aguitypes.ToolCall

The messages of a MESSAGES_SNAPSHOT and the run input and interrupt types a caller bridges between the CLI and the wire.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.