Support AG-UI projection for Agent-as-Tool / nested agent runs

[duohelingdukele]

Proposal: Support AG-UI projection for Agent-as-Tool / nested agent runs

I’d like to discuss whether TanStack AI should provide a first-class way for an Agent used as a Tool to stream its internal state back to the outer AG-UI stream.

The use case is hierarchical / delegated agents:

Main Agent
└─ research_agent        toolCallId = call_A
   ├─ reasoning
   ├─ search_web         toolCallId = call_B
   └─ browser_agent      toolCallId = call_C
      └─ open_url        toolCallId = call_D

From the UI perspective, I’d like to render this as a nested execution tree rather than flattening all inner tool calls into the outer conversation.

For example:

Main Agent
└─ Research Agent
   ├─ thinking...
   ├─ search_web
   └─ Browser Agent
      └─ open_url

Current situation

Today this can be implemented manually with nested chat() calls.

A parent server tool can:

1. Start a child chat()
2. Consume the child stream
3. Normalize child chunks with middleware
4. Forward them through emitCustomEvent()
5. Maintain a separate trace sidecar on the client

Conceptually:

parent tool
  └─ child chat()
       ├─ REASONING_MESSAGE_CONTENT
       ├─ TOOL_CALL_START
       ├─ TOOL_CALL_RESULT
       └─ TEXT_MESSAGE_CONTENT
            ↓
       middleware / normalization
            ↓
       custom event
            ↓
       parent emitCustomEvent()
            ↓
       AG-UI

This works, but the difficult part is preserving the nested ownership relationship.

For a first-level child agent, the outer onCustomEvent(..., context.toolCallId) can associate the child trace with the parent tool call.

For recursive agents, however:

Main
└─ research_agent   call_A
   └─ browser_agent call_C
      └─ open_url   call_D

events from browser_agent may still be transported through the outer research_agent tool execution context.

So the client-visible transport toolCallId may still be call_A, while the actual parent of the browser run is call_C.

That means nested agent execution needs an explicit relationship such as:

{
  runId,
  parentRunId,
  parentToolCallId,
  agentId
}

or an equivalent built-in representation.

What I’d like to see

Something similar to an Agent-as-Tool API that preserves nested AG-UI events automatically.

For example, conceptually:

const researchTool = researchAgent.asTool({
  name: 'research_agent',
  streamNestedEvents: true,
})

Then the outer stream could expose the child run with enough context to reconstruct:

tool call_A
  └─ child run
      ├─ reasoning
      ├─ tool call_B
      └─ tool call_C
          └─ child run
              └─ tool call_D

I don’t think this necessarily requires inventing new variants of every AG-UI event.

A small envelope may be enough:

type NestedAgentEvent = {
  runId: string
  parentRunId?: string
  parentToolCallId: string
  agentId?: string
  event: StreamChunk
}

The important part is that the parent relationship is attached by the runtime, rather than reconstructed from event ordering on the client.

Relationship with @tanstack/ai-orchestration

The current Workflow-backed orchestration direction looks very promising because an agent call already has a stable Workflow step identity.

Internally, the current experimental implementation already emits something conceptually like:

{
  stepId,
  attempt,
  chunk,
}

for chunks produced by an agent step.

That seems very close to what is needed for UI ownership.

However, Workflow-managed agent steps and Agent-as-Tool delegation are slightly different use cases.

Workflow orchestration naturally represents:

Workflow
├─ Research Agent step
├─ SQL Agent step
└─ Review Agent step

while Agent-as-Tool needs to represent:

Main Agent
└─ research_agent tool call
   └─ child agent run
      └─ child tools

For autonomous hierarchical agents, the second relationship is important because the LLM itself chooses when to delegate.

Persistence / replay

If nested agent events are projected as normal AG-UI events, it would also simplify persistence considerably.

Ideally:

Agent Runtime
    ↓
nested AG-UI projection
    ↓
Durable Stream
    ↓
client reconnect / replay

Then applications would not need a second custom trace event log just to rebuild the sub-agent tree after reconnect.

For longer-term history, applications could still persist a projected execution snapshot rather than every reasoning/text delta.

Questions

Would the TanStack AI maintainers be open to first-class support for:

• Agent-as-Tool / delegated agents
• nested agent run identity
• linking a child agent run to the tool call that created it
• forwarding nested reasoning / tool / text events through AG-UI
• recursive nesting
• preserving enough relationship information for replay and UI reconstruction

I think this would complement the Workflow-backed orchestration work rather than compete with it:

• Workflow handles durable multi-step orchestration
• Agent-as-Tool handles autonomous hierarchical delegation inside an agent loop
• AG-UI provides a common projection model for both

For applications building a full agent execution UI, having this relationship represented by the runtime would remove a significant amount of custom middleware, CUSTOM event bridging, and client-side trace reconstruction.