experimental-a2 0.0.0

package/docs/guides/06-ai-agents.mdx

@@ -0,0 +1,659 @@
+---
+title: Durable AI agents
+description: Build an AI SDK agent whose messages, streaming progress, tools, approvals, and recovery live in an A2 event log.
+---
+
+## Install
+
+Install A2, the AI SDK, and Zod for the examples below:
+
+```bash
+pnpm add experimental-a2 ai zod
+```
+
+The examples use the AI SDK's default global provider, AI Gateway. Add its key
+to your environment:
+
+```bash .env.local
+AI_GATEWAY_API_KEY=your_api_key
+```
+
+## Define the agent
+
+`agent()` defines an isomorphic event contract and its standard `AIState`
+reducer. The same value types the server, server-rendered state, and optimistic
+client updates.
+
+```ts assistant.ts
+import { agent } from 'experimental-a2/ai'
+
+export const assistant = agent({
+  name: 'support-agent',
+})
+```
+
+Keep this module isomorphic. Model providers, secrets, tools, and storage belong
+in the server module.
+
+## Connect the model
+
+`createAgentServer()` adds the AI SDK runner and A2's ordinary storage,
+recovery, telemetry, and handler machinery:
+
+```ts server/assistant.ts
+import { createAgentServer } from 'experimental-a2/ai/server'
+import { assistant } from '../assistant'
+
+export const assistantServer = createAgentServer({
+  agent: assistant,
+  model: 'openai/gpt-5.6-terra',
+  instructions: 'Help the customer. Be concise.',
+  generation: {
+    temperature: 0.2,
+    maxOutputTokens: 2_000,
+  },
+})
+```
+
+A string model id uses the AI SDK's global provider, which is AI Gateway by
+default. `model` also accepts any AI SDK `LanguageModel`, such as a provider
+model returned by `openai('gpt-5.6-terra')`, or an async resolver that chooses a
+model for each generation.
+
+`generation` accepts the remaining AI SDK `ToolLoopAgent` settings: sampling,
+token limits, stop conditions, provider options, step callbacks, and tool
+approval policy. Individual providers decide which settings they support.
+
+`experimental-a2/ai/server` is server-only. The isomorphic `experimental-a2/ai` entry point contains the
+contract, reducer, schemas, and pure inputs; it never imports a model provider
+or backend.
+
+## Expose the event stream
+
+One HTTP route gives the browser a read and write path. `GET` streams events;
+`POST` accepts optimistic pushes:
+
+```ts app/api/agent-events/route.ts
+import { A2Error } from 'experimental-a2'
+import { errorResponse, parsePushBody, sseResponse } from 'experimental-a2/http'
+import { assistantServer } from '@/server/assistant'
+
+export async function GET(req: Request): Promise<Response> {
+  const { searchParams } = new URL(req.url)
+  const sessionId = searchParams.get('sessionId')
+  const startAt = Number(searchParams.get('index')) || 0
+
+  if (!sessionId) {
+    return errorResponse(new A2Error('INVALID_PAYLOAD', 'missing sessionId'))
+  }
+
+  // here's where you'd do auth, or any other checks
+
+  return sseResponse(assistantServer.session(sessionId).stream({ startAt }))
+}
+
+export async function POST(req: Request): Promise<Response> {
+  try {
+    const { sessionId, events } = await parsePushBody(req)
+
+    // here's where you'd do auth, or any other checks
+
+    const appended = await assistantServer.session(sessionId).append(...events)
+    return Response.json(appended)
+  } catch (error) {
+    return errorResponse(error)
+  }
+}
+```
+
+The route never calls the model directly. Appending
+`ai.generation.requested` wakes the built-in handler, which runs the AI SDK on
+the server and appends progress back to the same log.
+
+## Bind the reducer to React
+
+Create the typed provider and hook in a client module:
+
+```tsx app/agent/session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { assistant } from '@/assistant'
+
+export const assistantClient = createClient({
+  reducer: assistant.reducer,
+  api: '/api/agent-events',
+})
+
+export const { SessionProvider, useSession } = createReact({
+  client: assistantClient,
+})
+```
+
+Fold the initial state on the server, then let the provider resume the event
+stream from that exact index:
+
+```tsx app/agent/[sessionId]/page.tsx
+import { assistant } from '@/assistant'
+import { assistantServer } from '@/server/assistant'
+import { AgentClient } from './agent-client'
+import { SessionProvider } from '../session'
+
+export default async function AgentPage({
+  params,
+}: {
+  params: Promise<{ sessionId: string }>
+}) {
+  const { sessionId } = await params
+  const session = assistantServer.session(sessionId)
+  const { state, index } = await session.state(assistant.reducer)
+  const initialEvents = (await session.history()).filter(
+    (event) => event.index <= index,
+  )
+
+  return (
+    <SessionProvider
+      sessionId={sessionId}
+      initialState={state}
+      initialIndex={index}
+      initialEvents={initialEvents}
+    >
+      <AgentClient />
+    </SessionProvider>
+  )
+}
+```
+
+An empty session folds to the initial `AIState`. Its log is created lazily when
+the first message is pushed.
+
+Start the session from the previous route, but wait for its durable append
+before navigating. The destination server render then sees the message and its
+events in one complete response instead of racing the `POST`:
+
+```tsx app/agent/new-agent-session.tsx
+'use client'
+import type { UIMessage } from 'ai'
+import { inputs } from 'experimental-a2/ai'
+import { assistantClient } from './session'
+
+export async function openAgent(
+  sessionId: string,
+  message: UIMessage,
+  router: { push(href: string): void },
+): Promise<void> {
+  await assistantClient.session(sessionId).push(
+    {
+      type: 'ai.session.created',
+      payload: { metadata: {} },
+    },
+    ...inputs.message(message),
+  )
+  router.push(`/agent/${sessionId}`)
+}
+```
+
+The draft clears immediately while the append is in flight and can be restored
+if it fails. Once navigation begins, SSR already has a durable frontier and
+event history. When the destination provider mounts, it resolves the same live
+session and reconciles that server render without replacing the object. Idle
+session objects expire after five minutes by default; configure `gcTime` on
+`createClient` when a different lifetime fits the app.
+
+## Send messages from the client
+
+Build the message inline and pass the resulting events straight to `push()`:
+
+```tsx app/agent/[sessionId]/agent-client.tsx
+'use client'
+import type { FormEvent } from 'react'
+import { useState } from 'react'
+import { inputs } from 'experimental-a2/ai'
+import { useSession } from '../session'
+
+export function AgentClient() {
+  const { state, push } = useSession()
+  const [draft, setDraft] = useState('')
+  const [error, setError] = useState<string | null>(null)
+
+  const canSend = state.status === 'idle' || state.status === 'failed'
+  const lastMessage = state.messages.at(-1)
+  const lastText =
+    lastMessage?.parts
+      .flatMap((part) => (part.type === 'text' ? [part.text] : []))
+      .join('\n') ?? ''
+  const showThinking =
+    state.status === 'generating' &&
+    (lastMessage?.role !== 'assistant' || lastText.length === 0)
+
+  async function send(event: FormEvent<HTMLFormElement>): Promise<void> {
+    event.preventDefault()
+    const previousDraft = draft
+    const text = previousDraft.trim()
+    if (!text || !canSend) return
+
+    setDraft('')
+    setError(null)
+
+    try {
+      await push(
+        ...inputs.message({
+          id: crypto.randomUUID(),
+          role: 'user',
+          parts: [{ type: 'text', text }],
+        }),
+      )
+    } catch (cause) {
+      setDraft(previousDraft)
+      setError(cause instanceof Error ? cause.message : String(cause))
+    }
+  }
+
+  return (
+    <main>
+      <section aria-label="Conversation">
+        {state.messages.map((message) => {
+          const text = message.parts
+            .flatMap((part) => (part.type === 'text' ? [part.text] : []))
+            .join('\n')
+          if (!text) return null
+
+          return (
+            <article key={message.id}>
+              <strong>{message.role === 'user' ? 'You' : 'Agent'}</strong>
+              <p>{text}</p>
+            </article>
+          )
+        })}
+
+        {showThinking ? (
+          <article aria-live="polite">
+            <strong>Agent</strong>
+            <p>Thinking…</p>
+          </article>
+        ) : null}
+      </section>
+
+      <form onSubmit={send}>
+        <input
+          aria-label="Message"
+          value={draft}
+          onChange={(event) => setDraft(event.currentTarget.value)}
+        />
+        <button disabled={!draft.trim() || !canSend}>Send</button>
+      </form>
+
+      {error ? <p role="alert">{error}</p> : null}
+    </main>
+  )
+}
+```
+
+There is no separate message state to reconcile. `push()` folds
+`ai.message.created` and `ai.generation.requested` locally before starting the
+request. The user message and generating state appear immediately. If the
+request fails, A2 removes both optimistic events; the component only restores
+the draft.
+
+The form gives Enter its normal submit behavior. The thinking row is also
+derived from `AIState`: it appears with the Agent label as soon as the
+optimistic generation request folds, then the first visible assistant content
+replaces it. Empty stream-start messages never create a blank conversation row.
+
+## What happens after `push()`
+
+One user interaction becomes a durable sequence:
+
+```text
+browser  ai.message.created             optimistic, then durable
+browser  ai.generation.requested         optimistic, then durable
+server   ai.generation.started
+server   ai.generation.progress          batched UIMessageChunk[]
+server   ai.tool.called                  when present
+server   ai.tool.result                  when present
+server   ai.approval.requested           when present
+server   ai.generation.completed
+server   ai.message.completed
+```
+
+The SSE connection delivers the server events to the same reducer. Progress
+stores every AI SDK chunk once. The reducer and the exported
+`deriveUIMessages()` apply those chunks synchronously to produce the current
+`UIMessage`; cumulative message snapshots are not duplicated in the log.
+
+`AIState` exposes `messages`, `status`, `activeGeneration`, `activeProjection`,
+`pendingApprovals`, `pendingInputs`, `tools`, `compaction`, per-generation
+`usage`, and the last generation `error`. `activeProjection` is the temporary
+indexed chunk/tool frontier used for exact interruption and becomes `null` at
+a terminal event.
+
+## The built-in inputs
+
+`inputs` contains pure, isomorphic builders for protocol interactions:
+
+| Input | Events |
+| --- | --- |
+| `inputs.message(message)` | records a message and requests generation when its role is `user` |
+| `inputs.seed(message)` | records a message without requesting generation |
+| `inputs.approval(response)` | records an approval decision and requests continuation |
+| `inputs.input(response)` | records application input and requests continuation |
+| `inputs.requestInput(request)` | records an application-defined input request |
+| `inputs.retry(options)` | requests a fresh attempt after a failed partial response |
+| `inputs.interrupt(options)` | interrupts an active response |
+
+The builders hide stable event ids, so the same interaction is safe to resend.
+They return plain values accepted by both browser `push()` and server
+`append()`.
+
+`inputs` deliberately has no session lifecycle methods. The A2 log begins with
+the first append. Apps that use explicit `ai.session.created` or
+`ai.session.closed` lifecycle events push those ordinary contract events
+directly.
+
+## Add tools and approval
+
+Pass ordinary AI SDK tools to the server. Approval policy belongs in
+`generation`, beside the other `ToolLoopAgent` settings:
+
+```ts server/with-tools.ts
+import { tool } from 'ai'
+import { z } from 'zod'
+import { createAgentServer } from 'experimental-a2/ai/server'
+import { assistant } from '../assistant'
+
+const tools = {
+  closeTicket: tool({
+    description: 'Close a resolved support ticket',
+    inputSchema: z.object({ ticketId: z.string() }),
+    execute: async ({ ticketId }, { toolCallId }) => {
+      // your side effect; toolCallId makes a stable idempotency key:
+      // await closeTicket(ticketId, { idempotencyKey: toolCallId })
+      return { ticketId, closed: true }
+    },
+  }),
+}
+
+export const assistantServerWithTools = createAgentServer({
+  agent: assistant,
+  model: 'openai/gpt-5.6-terra',
+  tools,
+  generation: {
+    toolApproval: {
+      closeTicket: 'user-approval',
+    },
+  },
+})
+```
+
+The AI SDK emits an approval request instead of executing the tool. A2 records
+it as `ai.approval.requested`, and the reducer adds it to
+`state.pendingApprovals`. Respond from the same optimistic client path:
+
+```tsx app/agent/[sessionId]/approval-controls.tsx
+'use client'
+import { inputs } from 'experimental-a2/ai'
+import { useSession } from '../session'
+
+export function ApprovalControls() {
+  const { state, push } = useSession()
+
+  return state.pendingApprovals.map((approval) => (
+    <div key={approval.approvalId}>
+      <span>Allow tool call {approval.toolCallId}?</span>
+      <button
+        onClick={() =>
+          void push(
+            ...inputs.approval({
+              messageId: approval.messageId,
+              approvalId: approval.approvalId,
+              approved: true,
+            }),
+          )
+        }
+      >
+        Allow
+      </button>
+      <button
+        onClick={() =>
+          void push(
+            ...inputs.approval({
+              messageId: approval.messageId,
+              approvalId: approval.approvalId,
+              approved: false,
+              reason: 'Denied by the user',
+            }),
+          )
+        }
+      >
+        Deny
+      </button>
+    </div>
+  ))
+}
+```
+
+`inputs.approval()` updates the approval part in the projected `UIMessage` and
+requests another model turn. The server then executes the approved tool or
+returns the denial to the model.
+
+Tool activity follows the full AI SDK chunk lifecycle. Input validation errors,
+execution errors, denials, and preliminary and final outputs become durable
+`ai.tool.result` events. Preliminary outputs keep the tool `running`; a final
+output completes it. Each result has its own event id, so a preliminary result
+cannot deduplicate the final one. Dynamic-tool, provider-executed, provider
+metadata, and tool metadata fields are preserved in the projection.
+
+`inputs.input()` provides the same durable request/response shape for
+application-defined input. Its value stays in raw history and
+`state.pendingInputs`; resolve instructions dynamically or replace `generate`
+when the value should become model context.
+
+## Interrupt and retry
+
+Interrupt the active response from the client:
+
+```tsx app/agent/[sessionId]/stop-button.tsx
+'use client'
+import { inputs } from 'experimental-a2/ai'
+import { useSession } from '../session'
+
+export function StopButton() {
+  const { state, push, index } = useSession()
+  const active = state.activeGeneration
+
+  if (!active) return null
+
+  return (
+    <button
+      onClick={() =>
+        void push(
+          ...inputs.interrupt({
+            messageId: active.responseMessageId,
+            generationId: active.generationId,
+            reason: 'Stopped by the user',
+            lastSeenIndex: index,
+          }),
+        )
+      }
+    >
+      Stop
+    </button>
+  )
+}
+```
+
+The optimistic event updates the UI immediately and reaches A2's cancellation
+channel. `lastSeenIndex` is the exact confirmed log frontier visible when the
+user clicked. The reducer rewinds chunk and tool projections to that frontier,
+keeps the partial response the user actually saw, and turns incomplete visible
+tools into `output-error`. Progress, completion, or failure from that generation
+cannot reactivate it after the interruption.
+
+After a failed model call, `inputs.retry({ messageId, responseMessageId,
+retryId })` starts a fresh attempt. `retryId` identifies the user's action, so
+resending one retry is safe while a later retry remains distinct. Failed
+partial progress remains in raw history but is excluded from the new prompt.
+
+## Append from the server
+
+Browser interactions should use `push()` for instant state. Server-originated
+turns use the same inputs with `append()`:
+
+```ts server/append-message.ts
+import { inputs } from 'experimental-a2/ai'
+import { assistantServer } from './assistant'
+
+export async function appendServerMessage(sessionId: string, text: string) {
+  await assistantServer.session(sessionId).append(
+    ...inputs.message({
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text }],
+    }),
+  )
+}
+```
+
+This path fits webhooks, jobs, and other backend sources. A connected browser
+still receives the events over SSE, but it has no optimistic overlay for an
+interaction that began elsewhere.
+
+## Compact long conversations
+
+Compaction is optional application policy. A2 records both the decision and
+replacement messages, so later prompts remain explainable from history:
+
+```ts server/compacted.ts
+import type { UIMessage } from 'ai'
+import { createAgentServer } from 'experimental-a2/ai/server'
+import { assistant } from '../assistant'
+
+export const compactedAssistantServer = createAgentServer({
+  agent: assistant,
+  model: 'openai/gpt-5.6-terra',
+  compaction: {
+    shouldCompact: ({ messages }) => messages.length > 40,
+    compact: async ({ messages }) => {
+      const summary = {
+        id: crypto.randomUUID(),
+        role: 'user',
+        parts: [{ type: 'text', text: 'Summary of the earlier conversation.' }],
+      } satisfies UIMessage
+
+      return [summary, ...messages.slice(-10)]
+    },
+  },
+})
+```
+
+The callback can call another model, create a deterministic summary, or retain
+selected messages. A2 owns only when the result enters the log and how later
+generations consume it.
+
+## Extend the assembly
+
+The convenience API is ordinary A2 parts:
+
+- `events` and `createEvents()` export the built-in schemas.
+- `createReducer({ contract })` builds the standard `AIState` projection for a
+  compatible contract.
+- `agent()` combines the built-in protocol, application events, and reducer.
+- `createHandlers({ agent, ... })` returns the AI handler table.
+- `createAgentServer()` combines those handlers with `createServer()`.
+
+Use the lower-level pieces when an application needs more handlers or a
+different server assembly:
+
+```ts server/custom.ts
+import { z } from 'zod'
+import { agent } from 'experimental-a2/ai'
+import { createHandlers } from 'experimental-a2/ai/server'
+import { createServer } from 'experimental-a2/server'
+
+const supportAgent = agent({
+  name: 'extended-support-agent',
+  events: {
+    'ticket.linked': z.object({ ticketId: z.string() }),
+  },
+})
+
+const aiHandlers = createHandlers({
+  agent: supportAgent,
+  model: 'openai/gpt-5.6-terra',
+})
+
+export const customAssistantServer = createServer({
+  contract: supportAgent.contract,
+  handlers: {
+    ...aiHandlers,
+    'ticket.linked': async ({ event }) => {
+      // your side effect; event.id makes a stable idempotency key:
+      // await indexTicket(event.payload.ticketId, { idempotencyKey: event.id })
+    },
+  },
+})
+```
+
+Application events stay fully typed. The standard AI reducer ignores unknown
+events, so another reducer can project application state without forking the AI
+protocol.
+
+### Replace generation, not durability
+
+The default generator uses the AI SDK `ToolLoopAgent`. Replace only that
+model-facing step for fixtures, provider routing, or a different AI SDK
+assembly:
+
+```ts server/custom-generation.ts
+import { ToolLoopAgent, createAgentUIStream } from 'ai'
+import { createAgentServer } from 'experimental-a2/ai/server'
+import { assistant } from '../assistant'
+
+export const customGenerationServer = createAgentServer({
+  agent: assistant,
+  model: 'openai/gpt-5.6-terra',
+  generate: async ({
+    messages,
+    model,
+    tools,
+    instructions,
+    generation,
+    generationId,
+    responseMessageId,
+    signal,
+  }) => {
+    const sdkAgent = new ToolLoopAgent<never, typeof tools>({
+      ...generation,
+      id: generationId,
+      model,
+      tools,
+      ...(instructions === undefined ? {} : { instructions }),
+    })
+
+    return createAgentUIStream({
+      agent: sdkAgent,
+      uiMessages: messages,
+      generateMessageId: () => responseMessageId,
+      abortSignal: signal,
+    })
+  },
+})
+```
+
+`generate` receives compacted messages, resolved model and instructions, tools,
+generation settings, durable request identity, current state and history, and
+the abort signal. It returns one `ReadableStream<UIMessageChunk>`. A2 still
+records progress, tool and approval events, completion, interruption, and
+failure.
+
+## Delivery semantics
+
+Model calls and tools run inside an at-least-once A2 handler. Durable event ids
+make lifecycle appends effectively once, and A2 marks an incomplete attempt
+`superseded` before starting its replacement. Model providers and external tool
+side effects remain outside the log. Give side-effecting tools their own
+idempotency strategy, normally keyed by the AI SDK tool call id.
+
+Configure [production recovery](/guides/production) exactly as for any other A2
+server. Recovery wakes an interrupted generation after the original serverless
+invocation disappears.