agenttrace-ag-ui

AG-UI protocol adapter for agenttrace-react — visualise AG-UI agent execution traces, tool calls, and human-in-the-loop approval gates as a live React UI.

Install

npm install agenttrace-react agenttrace-ag-ui
# or
pnpm add agenttrace-react agenttrace-ag-ui

Use cases

• Rendering a live execution trace for any AG-UI protocol-compatible agent
• Visualising tool calls and steps as they stream in over SSE
• Surfacing CUSTOM approval events as human-in-the-loop gates
• Building oversight UIs for agents using the AG-UI standard (supported by Google, Microsoft, AWS, LangChain, and others)

Peer dependencies

• agenttrace-react
• react

Exports

• useAgUiTrace(agentUrl) — connects to an AG-UI SSE endpoint and returns a live AgentRun
• agUiToTraceEvent(event) — maps a single AG-UI event to a TraceEvent

Usage

import { TraceProvider, TraceTree, TraceNode, ApprovalGate } from 'agenttrace-react'
import { useAgUiTrace } from 'agenttrace-ag-ui'

export function AgUiTraceView({ onApproval }) {
  const run = useAgUiTrace('/api/agent/stream')

  return (
    <TraceProvider run={run} onApprovalAction={onApproval}>
      <TraceTree>
        {({ node }) => (
          <TraceNode node={node}>
            {({ name, status, type }) => (
              <div data-status={status} data-type={type}>
                {name}: {status}
                <ApprovalGate>
                  {({ approve, reject, context }) => (
                    <div>
                      <p>{context.description}</p>
                      <button onClick={approve}>Approve</button>
                      <button onClick={reject}>Reject</button>
                    </div>
                  )}
                </ApprovalGate>
              </div>
            )}
          </TraceNode>
        )}
      </TraceTree>
    </TraceProvider>
  )
}

Supported AG-UI events

| Event | Mapped to | |-------|-----------| | RUN_STARTED | RunStarted | | RUN_FINISHED | finalises the run | | RUN_ERROR | NodeFailed | | STEP_STARTED | NodeStarted (type: agent) | | STEP_FINISHED | NodeCompleted (type: agent) | | TOOL_CALL_START | NodeStarted (type: tool) | | TOOL_CALL_END | NodeCompleted (type: tool) | | CUSTOM | ApprovalRequested or ApprovalResolved |

How it works

• Connects to any AG-UI-compatible agent endpoint via EventSource (SSE)
• Parses and maps all AG-UI event types to agenttrace-react trace events
• Infers approval events from CUSTOM event names and payload shape
• Returns a live AgentRun compatible with agenttrace-react's TraceProvider
• Handles SSE connection errors gracefully with a NodeFailed trace event

Related packages

• agenttrace-react — core headless primitives
• agenttrace-langgraph — LangGraph adapter
• agenttrace-ai-sdk — Vercel AI SDK adapter

Repository

github.com/nedbpowell/agenttrace-react

License

MIT