Serving Agents over AG-UI

The pkg/agui package serves your agents over the AG-UI protocol — the same wire format CopilotKit and @ag-ui/client speak. You get streaming assistant text, reasoning, tool calls, conversation threads, and human-in-the-loop approvals over a single SSE endpoint, plus an optional embedded chat UI so you can talk to an agent in the browser without building a frontend. There are three layers, from highest to lowest level:

Use	Function
Ship a browser chat UI with zero frontend work	`web.Serve` / `web.Handler` (`pkg/agui/web`)
Expose every registered agent to external AG-UI clients	`agui.NewHandler` (`pkg/agui`)
Mount a single agent’s run endpoint on your own mux	`agui.AgentHandler` (`pkg/agui`)

*hastekit.AgentRegistry satisfies the agui.Registry interface (Agent(name) + AgentNames()), so you pass one to any of these. Agents register into a package-global registry when you create them with hastekit.NewAgent, so a zero-value &hastekit.AgentRegistry{} already sees every agent.

Embedded chat UI

The fastest way to interact with an agent. web.Serve mounts a ready-made CopilotKit chat client and the AG-UI protocol endpoints on the same address:

package main

import (
	"log"
	"os"

	hastekit "github.com/hastekit/hastekit-sdk-go"
	"github.com/hastekit/hastekit-sdk-go/pkg/agui/web"
)

func main() {
	client := hastekit.NewLLMClient([]hastekit.ProviderConfig{
		{
			ProviderName: hastekit.ProviderOpenAI,
			ApiKeys: []*hastekit.APIKeyConfig{
				{Name: "Key 1", APIKey: os.Getenv("OPENAI_API_KEY")},
			},
		},
	})

	hastekit.NewAgent(&hastekit.AgentConfig{
		Name:        "Assistant",
		Instruction: hastekit.NewPrompt("You are a helpful assistant."),
		LLM:         client.Model("OpenAI/gpt-4.1-mini"),
	})

	// Serves the chat UI and the AG-UI endpoints on :8080.
	if err := web.Serve(":8080", &hastekit.AgentRegistry{}); err != nil {
		log.Fatal(err)
	}
}

Open http://localhost:8080. The default UI lists registered agents, shows a sidebar of prior conversations to resume, streams assistant text / reasoning / tool calls live, and renders approval cards inline for human-in-the-loop pauses. web.Handler(registry, opts...) returns the same surface as an http.Handler for mounting into an existing server. It serves:

Path	Description
`GET /`	Embedded CopilotKit chat UI
`GET /basic.html`	Offline, zero-dependency fallback UI (no CDN)
`GET /api/agui/agents`	Registered agent names
`POST /api/agui/agents/{name}/run`	AG-UI run endpoint (SSE)
`GET /api/agui/agents/{name}/threads`	Conversation list
`GET /api/agui/agents/{name}/threads/{thread}/messages`	Thread history

The protocol endpoints are mounted under /api/agui (exported as web.APIPrefix), so external AG-UI clients can target them too — the embedded UIs are just two more consumers.

Protocol handler

If you have your own frontend (CopilotKit’s HttpAgent, raw @ag-ui/client, or a custom SSE consumer), serve just the protocol with agui.NewHandler:

import "github.com/hastekit/hastekit-sdk-go/pkg/agui"

// ... create the client and register agents with hastekit.NewAgent ...

http.ListenAndServe(":8080", agui.NewHandler(&hastekit.AgentRegistry{}))

Routes

Method & Path	Description
`GET /agents`	List registered agent names
`POST /agents/{agent}/run`	Run the agent; SSE stream of AG-UI events from a `RunAgentInput` body
`GET /agents/{agent}/threads`	Stored conversation threads, newest first
`GET /agents/{agent}/threads/{thread}/messages`	Thread history as AG-UI messages

The threads endpoints power conversation pickers. Listing requires the agent’s persistence adapter to implement history.ThreadLister (the SDK’s in-memory and file adapters do); when it doesn’t, the listing endpoint answers 501 so clients can hide the picker. See Conversation History for persistence setup.

Single agent

To mount one agent’s run endpoint on an existing mux, use agui.AgentHandler, which runs the agent for every POST regardless of path:

mux.Handle("POST /my-agent/run", agui.AgentHandler(agent))

Request body

The run endpoint accepts the canonical AG-UI RunAgentInput body (camelCase field names):

type RunAgentInput struct {
	ThreadID       string         `json:"threadId"`       // required
	RunID          string         `json:"runId,omitempty"`
	State          any            `json:"state,omitempty"`
	Messages       []Message      `json:"messages"`
	Tools          []InputTool    `json:"tools,omitempty"`
	Context        []InputContext `json:"context,omitempty"`
	ForwardedProps any            `json:"forwardedProps,omitempty"`
}

Each Message follows the AG-UI message shape:

type Message struct {
	ID         string     `json:"id"`
	Role       string     `json:"role"`              // "user", "assistant", ...
	Content    string     `json:"content,omitempty"`
	Name       string     `json:"name,omitempty"`
	ToolCalls  []ToolCall `json:"toolCalls,omitempty"`
	ToolCallID string     `json:"toolCallId,omitempty"`
}

A request must have a threadId and at least one of messages or an approval decision (see Human-in-the-loop below).

curl -N -X POST "http://localhost:8080/agents/Assistant/run" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "thread-1",
    "messages": [
      { "id": "m1", "role": "user", "content": "Hello!" }
    ]
  }'

By default the handler extracts only the new trailing turn from messages and relies on the SDK’s conversation persistence for prior history. Use WithFullHistory if the client owns history and the agent has no persistence.

Grounding context

context entries are flattened into the run’s RunContext so prompt templates can reference them. A {description, value} pair becomes {{Context.<description>}}, while state and forwardedProps are available as {{State.x}} and {{ForwardedProps.y}}.

Event stream

The run endpoint responds with Content-Type: text/event-stream and emits canonical AG-UI events. It always starts with RUN_STARTED and always ends with RUN_FINISHED (or RUN_ERROR), synthesising the terminal event if the stream closes early so clients never hang. The main event types:

Group	Events
Run lifecycle	`RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`
Steps	`STEP_STARTED`, `STEP_FINISHED`
Assistant text	`TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END`, `TEXT_MESSAGE_CHUNK`
Reasoning	`REASONING_START`, `REASONING_MESSAGE_CONTENT`, `REASONING_END`, …
Tool calls	`TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`, `TOOL_CALL_RESULT`, `TOOL_CALL_CHUNK`
State / messages	`STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT`
Escape hatches	`RAW`, `CUSTOM`

Right after RUN_STARTED, the handler also emits a CUSTOM event carrying the broker streamId, runId, and threadId so a client can correlate the AG-UI run with the SDK’s streaming surface.

Correlation headers

The response sets these headers before the first event:

X-Stream-Id — the broker stream id (matches handle.StreamID)
X-Agui-Run-Id — the AG-UI run id (echoed from runId, or generated)
X-Agui-Thread-Id — the thread id from the request

An idle connection receives a keep-alive SSE comment every 15 seconds (configurable) so reverse proxies don’t reap it.

Options

All three entry points (web.Serve, web.Handler, agui.NewHandler, agui.AgentHandler) accept the same options:

agui.WithNamespace(ns) — Conversation namespace (default "default").
agui.WithSenderID(id) — Sender attribution for messages POSTed by AG-UI clients (default "user").
agui.WithFullHistory() — Forward the client’s complete message list into the run instead of only the trailing turn. Use this when the agent has no conversation persistence and the client owns history; with persistence enabled (the SDK default) it would duplicate prior turns in the thread on every POST.
agui.WithKeepalive(d) — SSE keep-alive comment interval (default 15s).

Human-in-the-loop

When an agent pauses on an approval-gated tool, the run ends with a RUN_FINISHED in a paused state and the client renders an approval card. To resume, the client POSTs back to the same threadId with the decision under forwardedProps.command.resume (CopilotKit’s useInterrupt shape) — no new messages are required:

{
  "threadId": "thread-1",
  "messages": [],
  "forwardedProps": {
    "command": {
      "resume": {
        "decisions": [
          { "toolCallId": "call_xyz", "approved": true }
        ]
      }
    }
  }
}

A flat forwardedProps.hastekitApprovals array with the same {toolCallId, approved} entries is also accepted for simpler clients. The handler maps these decisions onto the SDK’s approval resume flow and continues the paused run.

SDK

LLM Gateway

Agents

Workflows

Serving Agents over AG-UI

Embedded chat UI

Protocol handler

Routes

Single agent

Request body

Grounding context

Event stream

Correlation headers

Options

Human-in-the-loop

​Embedded chat UI

​Protocol handler

​Routes

​Single agent

​Request body

​Grounding context

​Event stream

​Correlation headers

​Options

​Human-in-the-loop

Embedded chat UI

Protocol handler

Routes

Single agent

Request body

Grounding context

Event stream

Correlation headers

Options

Human-in-the-loop