recipe-embedded-app-agent

What problem does it solve?

This recipe shows how to embed a fully streaming AI agent into a Next.js application, enabling real-time responses, progressive disclosure of reasoning and tool usage, and robust server-side error and cost handling for interactive web clients.

Core Features & Use Cases

• Server-side streaming API route that builds an agent per-request and emits Server-Sent Events for live client updates.
• Client-side React hook that consumes the SSE stream, exposes text deltas, tool call events, run/cancel controls, and graceful cancellation.
• Progressive UI patterns to display reasoning steps and tool traces, plus production considerations like per-session budgeting, agent disposal, and required Node runtime configuration.
• Use cases include interactive chat widgets with tool integrations, live diagnostics that show tool-call progress, and background one-shot processing when streaming is unnecessary.

Quick Start

Build a Next.js POST API route that constructs an agent, streams AgentStream.toSSE from agent.runStream, and consume it in a client component with useAgentStream to display incremental text and tool events.