agui

package
v0.220.0 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2026 License: Apache-2.0 Imports: 17 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. 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

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 CustomEvent added in v0.219.0 

type CustomEvent struct {
	Name    string
	Value   any
	Resumes bool
}

CustomEvent is one AG-UI CUSTOM event. Resumes marks a run that carries on after an interruption, which discards the failure the interruption left.

type DialConfig added in v0.219.0 

type DialConfig struct {
	Addr      string
	Token     string
	Kind      string
	Handshake Handshake
}

DialConfig configures the dialing end. Kind is the client kind the hello declares.

type FunctionCall added in v0.219.0 

type FunctionCall = aguitypes.FunctionCall

The messages of a MESSAGES_SNAPSHOT.

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 Message added in v0.219.0 

type Message = aguitypes.Message

The messages of a MESSAGES_SNAPSHOT.

type Role added in v0.219.0 

type Role = aguitypes.Role

The messages of a MESSAGES_SNAPSHOT.

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 is written with exactly one Write, so a transport can map one Write to one frame.

func NewRun added in v0.219.0 

func NewRun(w io.Writer) *Run

NewRun builds the writer of one run over w. The methods that need no run, such as Custom and Snapshot, also work on a run that never starts.

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) Custom added in v0.219.0 

func (r *Run) Custom(name string, value any)

Custom writes one CUSTOM event.

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

Finish closes open framing and writes the run's one terminal event: RUN_FINISHED carrying result, RUN_FINISHED with outcome cancelled for a cancelled run, or RUN_ERROR for a failed one. It returns the failure.

func (*Run) Publish added in v0.219.0 

func (r *Run) Publish(event CustomEvent)

Publish writes a CUSTOM event and lets it resume the run.

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.

func (*Run) State added in v0.219.0 

func (r *Run) State(snapshot any)

State writes STATE_SNAPSHOT.

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.

func (*Run) UserMessage added in v0.219.0 

func (r *Run) UserMessage(content string)

UserMessage writes a complete user message as its own text message, closing anything the assistant had open first.

type ToolCall added in v0.219.0 

type ToolCall = aguitypes.ToolCall

The messages of a MESSAGES_SNAPSHOT.

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.