provideAgent()

provideAgent() registers the singleton agent configuration for every injectAgent() call in an Angular application. Call it once in bootstrapApplication or an ApplicationConfig to wire up the LangGraph API URL, assistant id, thread persistence, and transport.

injectAgent() itself takes no arguments — all configuration flows through provideAgent().

import { bootstrapApplication } from '@angular/platform-browser';
import {
  provideAgent,
  MockAgentTransport,
} from '@threadplane/langgraph';
import { AppComponent } from './app/app.component';
 
bootstrapApplication(AppComponent, {
  providers: [
    provideAgent({
      apiUrl: 'http://localhost:2024',
      assistantId: 'my-agent',
      transport: environment.testMode
        ? new MockAgentTransport()
        : undefined,
    }),
  ],
});

#Configuration options

Option	Type	Description
`apiUrl`	`string`	LangGraph Platform API base URL.
`assistantId`	`string`	LangGraph assistant id to bind to.
`threadId`	`Signal<string \| null> \| string \| null`	Thread ID to connect to. Pass a Signal for reactive thread switching.
`onThreadId`	`(id: string) => void`	Called when a new thread is auto-created by the transport.
`initialValues`	`Partial<T>`	Initial state values before the first stream response arrives.
`throttle`	`number \| false`	Throttle signal updates in milliseconds. `false` to disable. (default 16)
`toMessage`	`(msg: unknown) => BaseMessage`	Custom message deserializer for non-standard message formats.
`transport`	`AgentTransport`	Optional transport instance. Defaults to `FetchStreamTransport` when omitted.
`clientOptions`	`LangGraphClientOptions`	LangGraph SDK client tuning (e.g. `maxRetries`). See Client tuning below.
`telemetry`	`AgentRuntimeTelemetrySink \| false`	Optional app-owned telemetry sink. No telemetry is emitted unless this is provided.
`filterSubagentMessages`	`boolean`	When true, subagent messages are filtered from the main messages signal.
`subagentToolNames`	`string[]`	Tool names that indicate a subagent invocation.

#Singleton model

A single provideAgent({...}) call configures the entire application. Every injectAgent() call resolves to the same configured agent.

provideAgent({
  apiUrl: 'https://api.example.com',
  assistantId: 'support-agent',
});
 
// Elsewhere, inside an injection context:
const chat = injectAgent();

#Test transports

transport is an object that implements AgentTransport, not an Angular class token. Create an instance before passing it to provideAgent().

const transport = new MockAgentTransport();
 
TestBed.configureTestingModule({
  providers: [
    provideAgent({
      apiUrl: '',
      assistantId: 'test-agent',
      transport,
    }),
  ],
});

Test transports

Swap out the live transport for MockAgentTransport in tests by changing only the transport field on provideAgent(). injectAgent() call sites stay unchanged across environments.

#Client tuning (retry budget)

The LangGraph SDK retries connection failures — including the run stream — before throwing. With the defaults, a hard connection failure can take several seconds (multiple retries) to surface as an error, which delays your error UI. Tune the retry budget with clientOptions:

provideAgent({
  apiUrl: 'https://api.example.com',
  assistantId: 'support-agent',
  clientOptions: { maxRetries: 0 }, // fail fast — surface connection errors immediately
});

To configure it once for the whole app, provide the LANGGRAPH_CLIENT_OPTIONS token. Both the default FetchStreamTransport and the LangGraphThreadsAdapter read it, so the retry budget is set in one place:

import { LANGGRAPH_CLIENT_OPTIONS } from '@threadplane/langgraph';
 
bootstrapApplication(AppComponent, {
  providers: [
    provideAgent({ apiUrl: '…', assistantId: 'support-agent' }),
    { provide: LANGGRAPH_CLIENT_OPTIONS, useValue: { maxRetries: 0 } },
  ],
});

Precedence (first defined wins, whole-object — no per-field merge):

A call-site agent({ clientOptions })
The per-agent provideAgent({ clientOptions })
The app-wide LANGGRAPH_CLIENT_OPTIONS token
The SDK default

Diagnosing slow error surfacing

If a dropped connection takes ~15s to show an error, the SDK is exhausting its retry budget. Set maxRetries: 0 to fail fast, or a small number to keep a few retries with quicker surfacing. The resulting failure is classified as a retryable connection AgentError.

#Typed state via AgentRef

By default injectAgent() returns an agent typed as Record<string, unknown>. To thread a concrete state shape through Angular DI without restating the generic at every call site, create a typed AgentRef with createAgentRef<TState>() and pass it as the first argument to both provideAgent() and injectAgent():

import { createAgentRef } from '@threadplane/chat';
import { provideAgent, injectAgent } from '@threadplane/langgraph';
 
interface TripState {
  day: number;
  places: string[];
}
 
// Module scope — one typed handle, shared by providers and components.
export const TRIP = createAgentRef<TripState>('trip');
 
// app.config.ts
provideAgent(TRIP, { assistantId: 'trip' });
 
// component
const agent = injectAgent(TRIP); // LangGraphAgent<TripState>
agent.state().places;            // string[] — fully typed, no cast

The optional debugName ('trip' above) is surfaced in Angular DI error messages. AgentRef is exported from @threadplane/chat, so the same typed handle works across adapters.