toAgent()

toAgent() is the lower-level adapter function that wraps a raw AG-UI AbstractAgent into the runtime-neutral Agent contract used by @threadplane/chat components.

toAgent(source: AbstractAgent, options?: ToAgentOptions): AgUiAgent

Most applications should use provideAgent() instead — it constructs the HttpAgent source and calls toAgent() internally. Reach for toAgent() directly when you instantiate or customize the AbstractAgent yourself, for example to integrate a non-HTTP AG-UI transport.

import { HttpAgent } from '@ag-ui/client';
import { toAgent } from '@threadplane/ag-ui';
 
const source = new HttpAgent({ url: 'http://localhost:8000/my-agent' });
const agent = toAgent(source, { telemetry: myTelemetrySink });

#ToAgentOptions

#AgUiAgent

toAgent() returns an AgUiAgent, which extends the neutral Agent contract with one additional signal:

The standard Agent signals (messages, status, isLoading, error, toolCalls, state, interrupt) and actions (submit, stop, regenerate) are all present.

#CustomStreamEvent

CustomStreamEvent is the element type of AgUiAgent.customEvents:

interface CustomStreamEvent {
  /** Event name set by the backend (e.g. 'a2ui-partial', 'state_update'). */
  name: string;
  /** Arbitrary payload from the backend (JSON-string values are parsed). */
  data: unknown;
}

Custom events are surfaced from AG-UI CUSTOM protocol events whose name is not on_interrupt. The on_interrupt event is routed to the interrupt signal instead.

Read the accumulated events after a run by calling the signal — inside an effect, it re-runs as new events arrive:

import { effect } from '@angular/core';
import { HttpAgent } from '@ag-ui/client';
import { toAgent } from '@threadplane/ag-ui';
 
const agent = toAgent(new HttpAgent({ url: '/api/agent' }));
 
effect(() => {
  for (const e of agent.customEvents()) {
    console.log(e.name, e.data);
  }
});

#Lifecycle note

The returned AgUiAgent does not manage its own lifetime. When using DI via provideAgent(), the provider's destroy hook handles cleanup. When calling toAgent() directly, treat the returned agent's lifecycle as tied to the AbstractAgent instance you constructed.

#What's Next