cacheplane
diff --git a/‎apps/website/content/blog/.gitkeep‎ b/‎apps/website/content/blog/.gitkeep‎
diff --git a/‎apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx‎
Lines changed: 337 additions & 0 deletions b/‎apps/website/content/blog/2026-05-17-build-a-streaming-chat-ui-in-angular-with-langgraph.mdx‎
Lines changed: 337 additions & 0 deletions
@@ -0,0 +1,337 @@
+---
+title: "Build a Streaming Chat UI in Angular with LangGraph"
+description: "Step-by-step tutorial for shipping a production streaming chat in Angular — signal-native, design-system-friendly, and wired to a LangGraph backend."
+date: 2026-05-17
+tags: [tutorial, streaming, langgraph, angular]
+author: brian
+featured: true
+---
+
+Most AI chat features still ship without streaming.
+They buffer the full response on the server, then drop it into the UI in one paste.
+
+That is the line between a demo and a production interface.
+
+Streaming is not a polish item.
+It is the difference between a user waiting two seconds and a user waiting eight.
+It is also the difference between an interface that feels alive and one that feels broken.
+
+This post is the tutorial I wish I had when I started shipping agentic chat in Angular.
+We are going to wire a real streaming chat UI — signal-native, design-system-friendly, and connected to a LangGraph backend — using `@ngaf/chat` and `@ngaf/langgraph`.
+
+No buffered responses.
+No hand-rolled SSE plumbing.
+No fork of someone's React component.
+
+## tl;dr
+
+- Streaming is the production-vs-demo line for chat. Buffered responses feel broken once a user has seen the alternative.
+- `@ngaf/chat` is a signal-native Angular chat UI. `@ngaf/langgraph` is the transport that wires it to a LangGraph backend.
+- The wiring is three lines: `provideAgent`, `agent()`, and `<chat [agent]="...">`.
+- The production work is not the chat. It is errors, threads, and generative UI fallbacks.
+- If you are building agentic features in Angular today, this stack is the shortest path to a real interface.
+
+## Why streaming matters
+
+A user reads at roughly 200 to 300 words per minute.
+A modern model produces tokens faster than that.
+
+If you stream, the user starts reading before the model has finished thinking.
+If you buffer, every response feels like a page load — except the user does not know how long the page will take.
+
+The numbers are not subtle.
+Buffered chat measurably loses users.
+Streaming chat measurably keeps them.
+The longer the response, the wider the gap.
+
+But the deeper reason is psychological.
+A response that appears one token at a time tells the user the system is working.
+A response that hangs for six seconds and then dumps a wall of text tells the user nothing — until it is too late to course-correct.
+
+Streaming also unlocks a second behavior most teams forget about: **interruption**.
+If the response is incremental, the user can stop a run that is going the wrong direction before it finishes burning tokens.
+That is not just a cost story. It is a trust story.
+A system that can be steered mid-thought feels collaborative.
+A system that has to be waited out feels like a slot machine.
+
+This is why streaming changes the conversation from "is it broken?" to "is this the answer I wanted?"
+That second question is the one your product actually needs the user to be asking.
+
+## The architecture in three boxes
+
+The wiring is simple once you see the seams.
+
+**LangGraph backend.**
+This is where your agent graph lives — nodes, edges, tools, interrupts.
+It exposes a streaming endpoint over SSE.
+You do not write the transport. LangGraph does.
+
+**`@ngaf/langgraph` adapter.**
+This is the Angular-side translator.
+It takes LangGraph's `ThreadState` and turns it into a signal-shaped `AgentCheckpoint` that the chat UI knows how to render.
+It also owns the run lifecycle — submit, cancel, retry — and the thread CRUD.
+
+**`@ngaf/chat` UI.**
+This is the rendering layer.
+Message list, input, suggestions, interrupt panels, tool-call cards, reasoning blocks.
+Every piece is a signal, every signal flows through OnPush change detection, and everything is themeable through CSS custom properties.
+
+The contract between the adapter and the UI is small on purpose.
+The chat does not know it is talking to LangGraph.
+The adapter does not know how messages get rendered.
+That separation is what lets you swap the backend, theme the UI, or replace a single component without touching the rest.
+
+It is also what makes the stack viable for teams that do not control the backend.
+If your backend is LangGraph, the adapter is what you reach for.
+If your backend is something else, the adapter is the only piece that changes.
+The chat — and every component, theme, and slot inside it — is the same.
+
+<ArchFlowDiagram />
+
+## Scaffold
+
+We will start with a fresh Angular 20 app. Three commands and three files.
+
+<Steps>
+<Step title="Install the packages">
+
+<Tabs items={["npm", "pnpm", "yarn"]}>
+<Tab label="npm">
+
+```bash
+npm install @ngaf/chat @ngaf/langgraph marked
+```
+
+</Tab>
+<Tab label="pnpm">
+
+```bash
+pnpm add @ngaf/chat @ngaf/langgraph marked
+```
+
+</Tab>
+<Tab label="yarn">
+
+```bash
+yarn add @ngaf/chat @ngaf/langgraph marked
+```
+
+</Tab>
+</Tabs>
+
+`marked` is the markdown renderer the chat uses for assistant messages.
+It is a peer dependency so you can swap it if you need to.
+
+</Step>
+<Step title="Wire the providers">
+
+```ts
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideAgent } from '@ngaf/langgraph';
+import { provideChat } from '@ngaf/chat';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAgent({ apiUrl: 'http://localhost:2024' }),
+    provideChat({ assistantName: 'Assistant' }),
+  ],
+};
+```
+
+`provideAgent` is the transport. `provideChat` is the UI configuration.
+They are independent on purpose — you can use one without the other.
+
+</Step>
+<Step title="Create the agent in your component">
+
+```ts
+// chat-page.component.ts
+import { Component, ChangeDetectionStrategy, signal } from '@angular/core';
+import { agent } from '@ngaf/langgraph';
+import { ChatComponent } from '@ngaf/chat';
+
+@Component({
+  selector: 'app-chat-page',
+  standalone: true,
+  imports: [ChatComponent],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `<div style="height: 100vh"><chat [agent]="chatAgent" /></div>`,
+})
+export class ChatPageComponent {
+  protected readonly chatAgent = agent({
+    assistantId: 'chat_agent',
+    threadId: signal(null),
+  });
+}
+```
+
+`agent()` is a factory.
+It returns a signal-shaped object that the chat reads from and writes to.
+`threadId` is a signal so the chat can swap threads without re-instantiating the agent.
+
+</Step>
+</Steps>
+
+That is the entire wiring.
+No global stylesheet to import. No PostCSS config. No Tailwind setup.
+The chat ships with its own design tokens and component-scoped styles.
+
+The one thing worth calling out is the `assistantId`.
+That is the name of your LangGraph graph — the entry point the run will execute against.
+If you have multiple graphs, you have multiple `agent()` instances, and you decide which one mounts where.
+A support graph in one route, a coding graph in another, the same chat shell rendering both.
+
+## Render the chat
+
+The `<chat>` component handles the standard surface — message list, input, send button, suggestion chips, scroll behavior, autosizing, the lot.
+
+```html
+<chat [agent]="chatAgent" />
+```
+
+That is the minimum.
+You will quickly want a welcome state, suggestions, and a header.
+
+```ts
+template: `
+  <div style="height: 100vh">
+    <chat [agent]="chatAgent">
+      <ng-template chatWelcome>
+        <h1>What can I help you ship today?</h1>
+        <p>Ask me about your repo, your roadmap, or the deploy that just failed.</p>
+      </ng-template>
+
+      <ng-template chatSuggestions>
+        <chat-suggestion (click)="ask('Summarize the open PRs')">
+          Summarize the open PRs
+        </chat-suggestion>
+        <chat-suggestion (click)="ask('Explain the last deploy')">
+          Explain the last deploy
+        </chat-suggestion>
+      </ng-template>
+    </chat>
+  </div>
+`,
+```
+
+The slot pattern is intentional.
+The chat does not opinion-set your welcome state.
+It does not pick your suggestions.
+It hands you the slots and gets out of the way.
+
+This is the thing I would not compromise on when picking a chat library.
+A chat component that owns its welcome copy, its suggestion list, and its empty states is a chat component that fights you the moment your product matures past the demo phase.
+A chat component that exposes those as slots is one you can grow with.
+
+Theming is a separate concern.
+The chat reads from CSS custom properties — `--chat-bg`, `--chat-fg`, `--chat-accent`, and a few dozen more.
+If you are already using a design system, you map your tokens onto theirs in a single stylesheet and the chat picks them up.
+
+## What is happening under the hood
+
+The adapter exposes a small contract.
+The chat consumes it.
+Everything else is implementation detail.
+
+The contract is roughly:
+
+- `messages` — a signal of the current thread's messages
+- `status` — a signal of `'idle' | 'loading' | 'streaming' | 'error'`
+- `submit(text)` — push a user message and start a run
+- `cancel()` — abort the current run
+- `retry()` — re-run the last user message
+
+Notice what is not in there.
+No event emitters. No observables to subscribe to. No imperative `subscribe(messages, render)` plumbing.
+
+Everything is a signal.
+The chat template reads `messages()` directly.
+OnPush change detection picks up the writes and re-renders only the components that depend on the changed signal.
+
+This matters more than it looks.
+Angular's signal model maps cleanly onto streaming because streaming is, at the data-shape level, a sequence of small writes to a growing list.
+Signals are a sequence of small writes to a growing list.
+The mental model and the runtime model are the same shape.
+
+That is why the chat does not need an internal store, a reducer, or a state machine.
+The agent is the state. The signal is the read. The template is the render.
+
+It also matters for testing.
+Because the contract is signals all the way down, you can mock the agent with a plain object — no harness, no fakes, no subscription bookkeeping.
+Write a signal, the chat re-renders. Write another signal, the chat re-renders again.
+That is the entire testing story for the UI layer.
+
+The transport story is the same shape one level down.
+The adapter reads from LangGraph's SSE stream and writes the parsed events into the agent's signals.
+You can swap the transport — a fake stream, a recorded fixture, a different backend entirely — and the chat does not know the difference.
+That is the boundary the contract was designed to enforce.
+
+## Production patterns
+
+The scaffold above gets you to a working chat in about ten minutes.
+The remaining ninety percent of the work is in three buckets.
+
+### 1. Errors and retries
+
+Models fail. Networks fail. Tools time out.
+The default behavior is to surface the error in the chat with a retry affordance, but most teams want more than the default.
+
+Two patterns I would always implement:
+
+- **Per-message retry**, so a failed assistant response can be re-run without resubmitting the user's message.
+- **Transport-level retry with backoff**, so transient SSE drops do not surface as errors at all.
+
+The adapter exposes both as configuration on `provideAgent`.
+A third pattern worth thinking about early: **graceful degradation when streaming is unavailable**.
+Some networks strip SSE. Some corporate proxies buffer it. The chat will fall back to a non-streaming render, but you should know that path exists before a customer finds it.
+The depth of what you can do here is in the [error handling guide](/docs/chat/guides/lifecycle).
+
+### 2. Threads and persistence
+
+A single-thread chat is a demo.
+A real product remembers conversations across sessions and across devices.
+
+LangGraph handles the persistence on the backend.
+The adapter exposes thread CRUD through `@langchain/langgraph-sdk` — list threads, create a thread, switch threads, delete a thread.
+
+The pattern is to bind your `threadId` signal to your router or your sidebar selection.
+When the signal changes, the chat re-reads from the new thread automatically. No manual unsubscribe. No race conditions.
+
+What you do with that capability is a product decision, not a framework one.
+Some teams scope threads to a project. Others scope them to a task. Others scope them to the user's session and let the agent's memory do the cross-session work.
+There is no right answer — but there is a wrong one, which is to ignore the question and ship a chat where every refresh starts from zero.
+
+If you are building a multi-thread sidebar, the [`<chat-sidebar>`](/docs/chat/components/chat-sidebar) primitive gives you the layout without locking you into a specific persistence model.
+
+### 3. Generative UI fallbacks
+
+Sometimes the model wants to do more than render text.
+Tool calls produce structured output. Interrupts ask for human input. Subagents return their own state.
+
+The chat handles each of these as a first-class message type.
+You do not need to write a custom renderer to get the default behavior — tool calls become cards, interrupts become panels, subagents become collapsible blocks.
+
+When you do need custom rendering — and you will — every one of these is a templatable slot.
+Pass a template, override the default, ship the variant you actually want.
+This is the seam where a generic chat becomes your chat.
+The branded card for your most important tool. The custom approval flow for your most sensitive interrupt. The product-specific summary block when a subagent finishes a long task.
+The [generative UI guide](/docs/chat/guides/generative-ui) walks through each surface in depth.
+
+## Where to go from here
+
+The scaffold above is the smallest possible production-shaped chat.
+It is not the whole story.
+
+Three places to look next:
+
+- The [cockpit chat example](/docs/chat/getting-started/quickstart) — a full multi-thread, multi-agent chat shell with real LangGraph graphs behind it.
+- The [persistence guide](/docs/chat/guides/lifecycle) — how to manage threads, runs, and resume state across sessions.
+- The [interrupts guide](/docs/chat/guides/streaming) — how to handle human-in-the-loop pauses without breaking the streaming model.
+
+<Callout type="info" title="Building this for an enterprise team?">
+If you are wiring `@ngaf/chat` into a regulated, multi-tenant, or design-system-heavy environment, we have a paid track for that. [Talk to us about the enterprise track →](/contact?source=blog_streaming_pillar&track=enterprise)
+</Callout>
+
+The interesting work in agentic software is not the chat itself.
+It is everything the chat lets you stop building so you can get back to the part that actually matters.