Connect Runs to interfaces and tracing

Use AG-UI to stream Run events to an interactive client. Use OpenTelemetry to publish traces to the backend your application already uses. Neither changes the Agent that produced the Run.

Send a Run stream through AG-UI

The AG-UI adapter converts LittleGhost events into protocol event hashes:

require "json"
require "little_ghost/ag_ui"

source = CustomerSupportAgent.stream_ask(
  question,
  actor_id: authenticated_user.id,
  context: {account_id: authenticated_user.account_id}
)

events = LittleGhost::AGUI::Adapter.new.stream(
  source,
  thread_id: conversation.id,
  run_id: request.request_id
)

events.each { |event| websocket.write(JSON.generate(event)) }

The adapter translates Run lifecycle and final outcomes, plus selected Agent progress such as model output, Tool activity, and retries. By default, it selects only the root Agent: agent_path == "/root" with an empty assembly_path. Nested Agent progress is not forwarded. The adapter reads Agent progress from :agent_stream and reports aggregate usage separately.

Pass source_filter: to LittleGhost::AGUI::Adapter.new to select other participants. This application-owned callable receives an AgentStreamSource and returns a truthy value only for sources the client may see. Match the enclosing assembly path as well as the Agent identity when selecting a nested participant. Computed assembly answers arrive in RUN_FINISHED‘s result, not as synthetic text deltas.

The adapter does not keep state between calls. Your application owns the connection, backpressure, disconnect behavior, and any request state its callbacks need.

LittleGhost may emit event types beyond the core AG-UI set. Decide whether the client preserves or ignores types it does not recognize. See the AG-UI event documentation when implementing the client.

Safety note: A Run stream can include model output, Tool arguments and results, errors, and participant activity. Source selection controls which Agent progress is forwarded; it does not redact that progress or filter the final Run result. Check that the connected user may see those values, and filter sensitive fields before sending or storing events.

Calling each drives the source stream on the caller’s fiber or thread. When a client disconnects, stop enumerating and decide whether the application should cancel the Run. Closing the socket cannot undo Tool work that already ran.

Trace Runs with OpenTelemetry

Configure an OpenTelemetry SDK and exporter in the application, then register the LittleGhost subscriber before the first Agent call:

LittleGhost.configure do |config|
  config.instrument LittleGhost::Tracing::OpenTelemetry.new
end

LittleGhost includes the opentelemetry-api integration. Your application chooses the SDK, processor, and exporter. The subscriber emits spans and events for Runs, model calls, Tools, assemblies, sessions, usage, and failures, and it can propagate W3C traceparent and tracestate fields.

Prompts, messages, responses, Tool arguments, and exception content are omitted by default. If you intentionally need some of that content, install a LittleGhost::Support::ContentCapture with a scrubber before enabling capture. Avoid putting raw user, order, session, or request IDs in span attributes.

Attribute names follow the evolving OpenTelemetry GenAI semantic conventions where they apply. If the tracing backend buffers data, flush or shut down LittleGhost::Instrumentation before the application exits.

See Running in Production for startup, shutdown, and observability, MCP for operations published by remote servers, and Workspaces and Sandboxes for child processes and files.