experimental-a2 0.17.0 → 0.18.0

package/docs/agents/01-introduction.mdx

@@ -0,0 +1,257 @@
+---
+title: Introduction
+description: Build an AI SDK agent whose messages, streaming, tools, and recovery live in an A2 event log.
+---
+
+## Install
+
+```bash
+pnpm add experimental-a2 ai zod
+```
+
+## Define the agent
+
+```ts server/assistant.ts
+import { agent } from 'experimental-a2/ai/server'
+
+export const assistant = agent({
+  name: 'support-agent',
+  model: 'openai/gpt-5.6-terra',
+  instructions: 'Help the customer. Be concise.',
+})
+```
+
+`agent()` is the whole server: the AI protocol, the agent's loop, and A2's
+store, scheduler, and handlers. `name` is its identity. The loop is the
+agent's `harness`. By default it's `{ type: 'ai-sdk' }`: each response runs as
+durable one-step `streamText()` generations, tuned with `harness.generation`
+and `maxSteps`, listed under [`agent()`](/reference/ai#agentoptions). The same
+agent can run [FX's or Pi's loop](/agents/harnesses) instead.
+
+## Expose the route
+
+```ts app/api/agent/route.ts
+import { assistant } from '@/server/assistant'
+
+export const GET = assistant.fetch
+export const POST = assistant.fetch
+```
+
+`GET` streams events and `POST` accepts the browser's pushes. The route never
+calls the model: `fetch` accepts user messages and controls, and rejects every
+server-authored event with `400`. The route is where you'd do auth, or any
+other checks, before `assistant.fetch(request, { authorize })` applies
+per-operation policy.
+
+## Render the conversation
+
+Fold the initial state on the server and hand it to a client component:
+
+```tsx app/agent/[sessionId]/page.tsx
+import { assistant } from '@/server/assistant'
+import { Chat } from './chat'
+
+export default async function AgentPage({
+  params,
+}: {
+  params: Promise<{ sessionId: string }>
+}) {
+  const { sessionId } = await params
+  const initial = await assistant.session(sessionId).state()
+  return <Chat sessionId={sessionId} initial={initial} />
+}
+```
+
+An empty session folds to the initial `AIState`; its log is created when the
+first message is pushed. `useAgent()` keeps that state live and returns the
+actions a chat needs:
+
+```tsx app/agent/[sessionId]/chat.tsx
+'use client'
+import type { FormEvent } from 'react'
+import { useState } from 'react'
+import type { StateSnapshot } from 'experimental-a2'
+import type { AIState } from 'experimental-a2/ai'
+import { useAgent } from 'experimental-a2/ai/react'
+import type { assistant } from '@/server/assistant'
+
+const indicatorLabel = {
+  starting: 'Starting…',
+  thinking: 'Thinking…',
+  compacting: 'Compacting…',
+}
+
+export function Chat({
+  sessionId,
+  initial,
+}: {
+  sessionId: string
+  initial: StateSnapshot<AIState>
+}) {
+  const { messages, status, indicator, sendMessage } =
+    useAgent<typeof assistant>({ api: '/api/agent', id: sessionId, initial })
+  const [draft, setDraft] = useState('')
+  const [error, setError] = useState<string | null>(null)
+
+  async function send(event: FormEvent<HTMLFormElement>): Promise<void> {
+    event.preventDefault()
+    const text = draft.trim()
+    if (!text) return
+    setDraft('')
+    setError(null)
+    try {
+      await sendMessage(text)
+    } catch (cause) {
+      setDraft(text)
+      setError(cause instanceof Error ? cause.message : String(cause))
+    }
+  }
+
+  return (
+    <main>
+      <section aria-label="Conversation">
+        {messages.map((message) => (
+          <article key={message.id}>
+            <strong>{message.role === 'user' ? 'You' : 'Agent'}</strong>
+            {message.parts.map((part, index) =>
+              part.type === 'text' ? <p key={index}>{part.text}</p> : null,
+            )}
+          </article>
+        ))}
+        {indicator ? (
+          <p role="status">{indicatorLabel[indicator]}</p>
+        ) : null}
+      </section>
+
+      <form onSubmit={send}>
+        <input
+          aria-label="Message"
+          value={draft}
+          onChange={(event) => setDraft(event.currentTarget.value)}
+        />
+        <button disabled={!draft.trim() || status === 'closed'}>Send</button>
+      </form>
+
+      {error ? <p role="alert">{error}</p> : null}
+    </main>
+  )
+}
+```
+
+The `import type` keeps server code out of the bundle. The hook returns the
+session's state plus `messages`, `status`, `indicator`, and actions; see
+[`useAgent()`](/reference/ai#useagentoptions).
+
+`sendMessage()` takes a string, sent as one text part with a fresh message ID,
+or a complete `UIMessage`. Every action returns the same result as `push()`: it
+resolves once the command events are stored, and `.confirmed` resolves when the
+stream delivers them back.
+
+Pass `{ generate: false }` to add a user message without starting a turn, as in
+`sendMessage('Order #4411 shipped this morning.', { generate: false })`. The
+next generating user message includes earlier passive messages in its model
+context; passive messages sent after it wait for the next one.
+
+## Start a session from another page
+
+Wait for the durable append before navigating, so the destination's server
+render sees the message. `createAgentClient()` is the same client outside React:
+
+```ts app/agent/client.ts
+'use client'
+import { createAgentClient } from 'experimental-a2/ai/client'
+import type { assistant } from '@/server/assistant'
+
+export const assistantClient = createAgentClient<typeof assistant>({
+  api: '/api/agent',
+})
+```
+
+```ts app/agent/open-agent.ts
+'use client'
+import { inputs } from 'experimental-a2/ai'
+import { assistantClient } from './client'
+
+export async function openAgent({
+  sessionId,
+  text,
+  router,
+}: {
+  sessionId: string
+  text: string
+  router: { push(href: string): void }
+}): Promise<void> {
+  await assistantClient.session(sessionId).push(
+    ...inputs.message({
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text }],
+    }),
+  )
+  router.push(`/agent/${sessionId}`)
+}
+```
+
+Pass the same client to the destination's hook,
+`useAgent<typeof assistant>({ client: assistantClient, id: sessionId, initial })`,
+so it picks up the live session the push created and reconciles the server
+render without replacing it. Idle client session objects expire after five
+minutes by default; set `gcTime` on `createAgentClient()` to change that.
+
+## Choose the model
+
+`model` is an AI Gateway model ID, under every harness, or `ModelSettings` to
+choose its reasoning level and speed with it:
+
+```ts server/fast-assistant.ts
+import { agent } from 'experimental-a2/ai/server'
+
+export const fastAssistant = agent({
+  name: 'fast-support',
+  model: { model: 'openai/gpt-5.6-terra', reasoning: 'low', speed: 'fast' },
+})
+```
+
+`speed: 'fast'` prefers AI Gateway's faster tier when the model offers one.
+`reasoningLevels` from `experimental-a2/ai` lists the levels for a picker. See
+[`ModelSettings`](/reference/ai#modelsettings). A resolver can also choose the
+model for each generation from your app's state, such as a plan; see
+[Add your own events and state](/agents/conversations#add-your-own-events-and-state).
+
+## What happens after a send
+
+One generating user message becomes a durable sequence:
+
+```text
+browser  ai.control.requested           durable input command
+server   ai.message.created             input admitted
+server   ai.control.committed           accepted state changes
+server   ai.control.decided             command receipt
+server   ai.generation.requested         scheduled from durable facts
+server   ai.generation.started
+server   ai.generation.progress          batched UIMessageChunk[]
+server   ai.tool.called                  when present
+server   ai.approval.requested           when present
+server   ai.tool.result                  after concurrent execution or denial
+server   ai.generation.completed         closes this model step
+server   ai.generation.requested         after all sibling tools are terminal
+         ...                             another one-step generation
+server   ai.message.completed
+server   ai.generation.requested         next queued user turn, when present
+```
+
+Tool results and generation completion can arrive in either order; the next
+step waits for both. The SSE stream delivers these events to the same reducer,
+which applies the streamed chunks to the current `UIMessage`; the exported
+`deriveUIMessages()` does the same over a raw history.
+
+Model calls for a session never overlap. A message sent while a response is
+active enters the durable log immediately, but its turn waits until that
+response, including every tool step and approval, finishes. Inbox order is
+arrival order and can be edited; see
+[Inbox and turn controls](/agents/conversations#inbox-and-turn-controls).
+
+The hook's actions read [`AIState`](/reference/ai#aistate)'s ownership
+bookkeeping, such as `activeGeneration` and `activeRequestId`, for you; the
+lower-level `inputs` builders need it explicitly. A2-generated IDs use the
+reserved `a2.ai:` namespace; treat them as opaque.

package/docs/agents/02-tools.mdx

@@ -0,0 +1,247 @@
+---
+title: Tools and approvals
+description: "Give an agent tools, ask for approval before they run, and interrupt or retry a turn."
+---
+
+## Add tools and approval
+
+```ts server/with-tools.ts
+import { tool } from 'ai'
+import { z } from 'zod'
+import { agent } from 'experimental-a2/ai/server'
+
+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 toolsAssistant = agent({
+  name: 'support-tools',
+  model: 'openai/gpt-5.6-terra',
+  tools,
+  harness: {
+    type: 'ai-sdk',
+    generation: {
+      toolApproval: {
+        closeTicket: 'user-approval',
+      },
+    },
+  },
+})
+```
+
+Tools are ordinary AI SDK `tool()` definitions, passed through untouched.
+Approval policy lives in `harness.generation.toolApproval`, beside the other
+per-step settings. Later examples that import `assistant` use the agent from
+[Agents](/agents/introduction#define-the-agent).
+
+### Read the handler context
+
+```ts server/set-reminder.ts
+import { tool } from 'ai'
+import { handlerContext, inputs } from 'experimental-a2/ai'
+import { z } from 'zod'
+
+export const setReminder = tool({
+  description: 'Set a reminder for yourself',
+  inputSchema: z.object({
+    delaySeconds: z.number().int().min(1).max(6 * 24 * 60 * 60),
+    reminder: z.string(),
+  }),
+  execute: async ({ delaySeconds, reminder }, { toolCallId }) => {
+    const ctx = handlerContext()
+    await ctx.session.schedule(
+      `reminder:${toolCallId}`,
+      { delay: `${delaySeconds}s` },
+      ...inputs.message({
+        id: `reminder:${ctx.event.id}`,
+        role: 'user',
+        parts: [{ type: 'text', text: `Reminder: ${reminder}` }],
+      }),
+    )
+
+    return { scheduled: true, delaySeconds }
+  },
+})
+```
+
+`handlerContext()` returns the running tool's durable handler context: `event`,
+`attempt`, `session`, and `signal`. It works anywhere below `execute`, including
+awaited helpers, and throws outside a tool execution. Pass a shared
+`agentContract()` to type application events; A2 checks it against the
+executing agent. See [`handlerContext()`](/reference/ai#handlercontextcontract)
+for the event payload.
+
+This tool schedules a reminder as a new user message. `ctx.session` belongs to
+the executing agent, so `schedule()` uses that agent's scheduler: add
+`setReminder` to its `tools` and configure a [scheduler](/server/production).
+Naming the timer after `toolCallId` and the message after the triggering
+event's ID makes a retry converge on the same timer and message, even if a
+provider reuses tool-call IDs. The six-day maximum is Vercel Queues'
+[delay limit](/server/timers#provider-limits); adjust it for your scheduler. A
+transient or ambiguous scheduler failure retries the handler with the same
+identity and target time; a deterministic rejection or a missing scheduler is
+an ordinary tool error.
+
+To test a context-reading tool, call it inside `runWithHandlerContext(ctx, fn)`
+from `experimental-a2/ai/server`; within `fn`, `handlerContext()` returns `ctx`.
+
+### Answer approvals
+
+```tsx app/tools/[sessionId]/approval-controls.tsx
+'use client'
+import { useAgent } from 'experimental-a2/ai/react'
+import type { toolsAssistant } from '@/server/with-tools'
+
+export function ApprovalControls({ sessionId }: { sessionId: string }) {
+  const { state, approve, deny } = useAgent<typeof toolsAssistant>({
+    api: '/api/tools',
+    id: sessionId,
+  })
+
+  return state.pendingApprovals.map((approval) => (
+    <div key={approval.approvalId}>
+      <span>Allow tool call {approval.toolCallId}?</span>
+      <button onClick={() => void approve(approval)}>Allow</button>
+      <button
+        onClick={() => void deny(approval, { reason: 'Denied by the user' })}
+      >
+        Deny
+      </button>
+    </div>
+  ))
+}
+```
+
+Instead of running a tool that needs approval, A2 records the AI SDK's approval
+request as `ai.approval.requested`, and the reducer adds it to
+`state.pendingApprovals`. `approve()` and `deny()` copy
+the request, message, generation, and approval IDs from it, so a delayed click
+cannot authorize a later model step. The decision updates the approval part in
+the message, and a built-in handler then runs the approved tool or records the
+denied result.
+
+A policy can also be a function that returns `'user-approval'` or
+`'approved'` from the validated input. It runs during the model step and again
+on recovery for the same call, so keep it deterministic over the input; an
+impure predicate can fork one call's flow.
+
+`state.pendingInputs` works the same way for application-defined input: answer
+one with `respond(input, value)`. The value stays in raw history and
+`state.pendingInputs`; to make it model context, resolve `instructions`
+dynamically or replace `generate`.
+
+### How tools run
+
+Validation errors, execution errors, denials, and preliminary and final outputs
+all become durable `ai.tool.result` events; a preliminary output keeps the tool
+`running` until the final one. Dynamic-tool, provider-executed, provider
+metadata, and tool metadata fields carry through to the message. Independent
+tools run concurrently as soon as their inputs and authorization are ready,
+with no fixed limit. Set `toolLane: 'tools'` when local tools must run one at a
+time, for example because they share a sandbox. The next model step starts
+once the current one closes and every sibling tool has a success, error, or
+denied result.
+
+An approved provider-executed call can satisfy that join through its response. A
+provider tool with deferred-result support waits for its provider result: your
+authenticated callback submits it from trusted server code with
+`inputs.toolResult(result)`, and the controller checks it against the admitted
+call. Browser pushes reject it.
+
+## Interrupt and retry
+
+```tsx app/agent/[sessionId]/turn-controls.tsx
+'use client'
+import { useAgent } from 'experimental-a2/ai/react'
+import type { assistant } from '@/server/assistant'
+
+export function TurnControls({ sessionId }: { sessionId: string }) {
+  const { state, status, stop, retry } = useAgent<typeof assistant>({
+    api: '/api/agent',
+    id: sessionId,
+  })
+
+  if (status === 'failed')
+    return <button onClick={() => void retry()}>Retry</button>
+  return state.active ? (
+    <button onClick={() => void stop()}>Stop</button>
+  ) : null
+}
+```
+
+`stop()` sends the log frontier the rendered state showed, not whatever arrived
+before the click was handled. The client previews Stop at once (a rejection
+restores the turn), and the response rewinds to that frontier, keeping the
+partial text the user saw. Tools completed by then stay completed, and accepted
+tools still awaiting completion become `output-error`. Tool calls whose
+arguments were still streaming are drafts: they leave the conversation and later
+prompts, while their progress stays in the raw log. Later events cannot
+reactivate a stopped response.
+
+Once Stop is persisted, A2 aborts the turn's running model and tool work.
+Cancellation is cooperative: tools must honor their abort signal. A Stop for an
+older turn cannot cancel its successor.
+
+`retry()` reruns the failed model call with a fresh `retryId` for each click:
+resending one retry is safe, and a later retry stays distinct. Earlier
+completed steps, their tool results, and the committed compaction summary
+remain; the failed call's uncommitted step leaves the prompt and response.
+Later user messages stay queued until the failed response is retried or
+interrupted. Conversation forks and edit-and-resend of admitted messages are
+yours to build.
+
+The lower-level `inputs.interrupt()` takes exactly one owner, so a delayed
+interruption cannot stop later work. Before the generation starts, pass
+`activeRequestId` as `requestId` and `activeResponseMessageId` as `messageId`.
+Once `activeGeneration` exists, pass its `generationId` and `responseMessageId`
+instead. After the generation completes, copy the owner from a pending approval,
+pending input, or running tool while the response waits.
+
+## Append from the server
+
+Webhooks, jobs, and other backends start turns with the same inputs and
+`append()`:
+
+```ts server/append-message.ts
+import { inputs } from 'experimental-a2/ai'
+import { assistant } from './assistant'
+
+export async function appendServerMessage(sessionId: string, text: string) {
+  await assistant.session(sessionId).append(
+    ...inputs.message({
+      id: crypto.randomUUID(),
+      role: 'user',
+      parts: [{ type: 'text', text }],
+    }),
+  )
+}
+```
+
+A connected browser still receives the events over SSE, without an optimistic
+overlay for an interaction that began elsewhere.
+
+## The built-in inputs
+
+The hook's actions build their commands with `inputs`, the same pure,
+isomorphic builders you pass to raw `push()` and server `append()`:
+`message()` and the passive `seed()` for messages; `approval()`,
+`input()`, and `requestInput()` for pending requests; `retry()`, `stop()`,
+`steer()`, `interrupt()`, `pause()`, and `resume()` for turns; `queue.edit()`,
+`queue.move()`, `queue.remove()`, and `queue.sendNow()` for the inbox; and
+`toolResult()` for deferred provider results. See
+[`inputs`](/reference/ai#inputs) for each signature, ID rules, and payloads.
+
+Browser pushes accept user messages, approval and input responses,
+interruptions, and retries. `inputs.requestInput()`, `inputs.toolResult()`, and
+non-user `inputs.seed()` messages are for trusted server appends. `inputs` has
+no session lifecycle methods: the log begins with the first append, and apps
+that use `ai.session.created` or `ai.session.closed` append them from trusted
+server code.