# Integrations

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/integrations.html

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:

```ruby
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](https://docs.ag-ui.com/concepts/events) 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:

```ruby
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.

Your tracing backend may expect its own attributes, such as an OpenInference
span kind. Add them with `enrich:`, a callable that receives each lifecycle
phase, notification name, and attributes and returns a Hash to add:

```ruby
LittleGhost.configure do |config|
  config.instrument LittleGhost::Tracing::OpenTelemetry.new(
    enrich: ->(phase, name, attributes) {
      {"openinference.span.kind" => (name == :tool) ? "TOOL" : "CHAIN"}
    },
    payload_limiter: LittleGhost::Tracing::PayloadLimiter.new(max_bytes: 64_000)
  )
end
```

Captured conversations grow with every turn, and many exporters reject or drop
large attributes. `PayloadLimiter` shortens any string attribute over its
budget. Message histories keep their most recent messages, model output keeps
its leading messages, and a Tool call stays paired with its result. Each
shortened attribute is recorded under `telemetry_truncation` in the `metadata`
attribute, so a reader can tell a preview from the full value. The limiter only
shortens content you chose to capture; it doesn't scrub it.

Attribute names follow the evolving [OpenTelemetry GenAI semantic
conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) where they
apply. If the tracing backend buffers data, flush or shut down
`LittleGhost::Instrumentation` before the application exits.

See [Running in Production](production.md) for startup, shutdown, and
observability, [MCP](mcp.md) for operations published by remote servers,
and [Workspaces and Sandboxes](sandboxing.md) for child processes and files.
