@genui/a3-create 0.1.36

package/template/docs/CUSTOM_STORES.md

@@ -0,0 +1,228 @@
+# Creating a Custom Session Store
+
+This guide walks you through implementing a custom `SessionStore` so A3 can persist sessions to any backend — DynamoDB, Redis, PostgreSQL, or anything else.
+
+## When to Create a Custom Store
+
+Create a custom store when you need:
+
+1. **Production persistence** — sessions that survive process restarts (the built-in `MemorySessionStore` doesn't)
+1. **Shared storage** — multiple server instances reading/writing the same sessions (e.g. behind a load balancer)
+1. **TTL / expiration** — automatic cleanup of stale sessions
+1. **Audit or compliance** — durable session records with timestamps
+
+## The SessionStore Interface
+
+Every store implements the `SessionStore` interface from `@genui/a3`:
+
+```typescript
+import { SessionData, BaseState, BaseChatContext } from '@genui/a3'
+
+interface SessionStore<
+  TState extends BaseState = BaseState,
+  TContext extends BaseChatContext = BaseChatContext,
+> {
+  /** Load session data, returns null if not found */
+  load(sessionId: string): Promise<SessionData<TState, TContext> | null>
+
+  /** Save session data */
+  save(sessionId: string, data: SessionData<TState, TContext>): Promise<void>
+
+  /** Delete a session (optional) */
+  delete?(sessionId: string): Promise<void>
+}
+```
+
+| Method | Required | Description |
+|---|---|---|
+| `load(sessionId)` | Yes | Retrieve session data by ID. Return `null` if no session exists. |
+| `save(sessionId, data)` | Yes | Persist the full `SessionData` object. Called after every turn. |
+| `delete(sessionId)` | No | Remove a session. Useful for cleanup, logout, or TTL expiration. |
+
+## SessionData Structure
+
+`SessionData` is the object your store serializes and deserializes:
+
+```typescript
+interface SessionData<
+  TState extends BaseState = BaseState,
+  TContext extends BaseChatContext = BaseChatContext,
+> {
+  sessionId: string
+  messages: Conversation         // Array of Message objects (full chat history)
+  conversationHistory?: Conversation  // Previous messages when re-authenticating
+  activeAgentId: AgentId | null  // Currently active agent
+  state: TState                  // Shared state across all agents
+  chatContext: TContext           // Context variables for the current session
+}
+```
+
+| Field | Description |
+|---|---|
+| `sessionId` | Unique identifier for the session |
+| `messages` | Full conversation history (user and assistant messages) |
+| `conversationHistory` | Optional backup of previous messages (used during re-authentication flows) |
+| `activeAgentId` | The agent that will handle the next user message, or `null` |
+| `state` | Shared typed state flowing across all agents — your `TState` extension of `BaseState` |
+| `chatContext` | Session-level context — your `TContext` extension of `BaseChatContext` |
+
+## Implementing a Custom Store
+
+### Step 1: Implement `load`
+
+Retrieve the session from your backend and deserialize it.
+Return `null` if the session doesn't exist.
+
+```typescript
+async load(sessionId: string): Promise<SessionData<TState, TContext> | null> {
+  const raw = await this.client.get(sessionId)
+  return raw ? JSON.parse(raw) : null
+}
+```
+
+### Step 2: Implement `save`
+
+Serialize the `SessionData` and write it to your backend.
+This is called after every turn, so it must handle both inserts and updates.
+
+```typescript
+async save(sessionId: string, data: SessionData<TState, TContext>): Promise<void> {
+  await this.client.set(sessionId, JSON.stringify(data))
+}
+```
+
+### Step 3: Implement `delete` (optional)
+
+Remove a session from your backend.
+If your backend supports TTL natively, you may not need this.
+
+```typescript
+async delete(sessionId: string): Promise<void> {
+  await this.client.delete(sessionId)
+}
+```
+
+## Example: DynamoDB Store
+
+A complete, copy-pasteable implementation using the AWS SDK v3:
+
+```typescript
+import { GetCommand, PutCommand, DeleteCommand } from '@aws-sdk/lib-dynamodb'
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'
+import type { SessionStore, SessionData, BaseState, BaseChatContext } from '@genui/a3'
+
+export class DynamoSessionStore<
+  TState extends BaseState = BaseState,
+  TContext extends BaseChatContext = BaseChatContext,
+> implements SessionStore<TState, TContext> {
+  private tableName: string
+  private client: DynamoDBDocumentClient
+
+  constructor(client: DynamoDBDocumentClient, tableName: string) {
+    this.client = client
+    this.tableName = tableName
+  }
+
+  async load(sessionId: string): Promise<SessionData<TState, TContext> | null> {
+    const result = await this.client.send(
+      new GetCommand({
+        TableName: this.tableName,
+        Key: { id: sessionId },
+      }),
+    )
+
+    if (!result.Item?.data) {
+      return null
+    }
+
+    return JSON.parse(result.Item.data as string) as SessionData<TState, TContext>
+  }
+
+  async save(sessionId: string, data: SessionData<TState, TContext>): Promise<void> {
+    await this.client.send(
+      new PutCommand({
+        TableName: this.tableName,
+        Item: {
+          id: sessionId,
+          data: JSON.stringify(data),
+          updatedAt: new Date().toISOString(),
+        },
+      }),
+    )
+  }
+
+  async delete(sessionId: string): Promise<void> {
+    await this.client.send(
+      new DeleteCommand({
+        TableName: this.tableName,
+        Key: { id: sessionId },
+      }),
+    )
+  }
+}
+```
+
+## Using Your Store
+
+Pass your store to `ChatSession` via the `store` option:
+
+```typescript
+import { ChatSession } from '@genui/a3'
+import { createBedrockProvider } from '@genui/a3-bedrock'
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb'
+import { DynamoSessionStore } from './dynamoSessionStore'
+
+const dynamoClient = DynamoDBDocumentClient.from(new DynamoDBClient({}))
+
+const session = new ChatSession({
+  sessionId: 'user-123',
+  store: new DynamoSessionStore(dynamoClient, 'my-sessions-table'),
+  initialAgentId: 'greeting',
+  provider: createBedrockProvider({ models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'] }),
+})
+
+const result = await session.send({ message: 'Hello!' })
+```
+
+## Gotchas and Tips
+
+### Serialization
+
+`SessionData` contains plain objects and arrays — `JSON.stringify` / `JSON.parse` works for most backends.
+If your state includes `Date` objects, `Map`, `Set`, or class instances, you'll need a custom serializer (e.g. `superjson`).
+
+### TTL and Expiration
+
+A3 doesn't manage TTL.
+Use your backend's native TTL feature (e.g. DynamoDB TTL, Redis `EXPIRE`) and set it in `save`.
+
+### Concurrency
+
+`save` is called after every turn.
+If a user sends rapid messages, two `save` calls may race.
+For most backends (Redis `SET`, DynamoDB `PutItem`) last-write-wins is fine.
+If you need stronger guarantees, use conditional writes or optimistic locking.
+
+### Typing
+
+`SessionStore` is generic over `TState` and `TContext`.
+Type your store class to match your application's state:
+
+```typescript
+const store = new DynamoSessionStore<MyAppState, MyAppContext>(client, 'sessions')
+```
+
+### Store is Optional
+
+`ChatSession` works without a store — sessions live only in the `ChatSession` instance's memory.
+If you omit `store`, session data is never persisted and is lost when the instance is garbage collected.
+
+## Reference
+
+| File | Description |
+|---|---|
+| `src/types/storage.ts` | `SessionStore` interface |
+| `src/types/session.ts` | `SessionData`, `BaseState`, `BaseChatContext` interfaces |
+| `src/stores/memoryStore.ts` | `MemorySessionStore` — built-in in-memory implementation |
+| `src/core/chatSession.ts` | `ChatSession` — where stores are consumed |

package/template/docs/PROVIDER-ANTHROPIC.md

@@ -0,0 +1,45 @@
+# @genui/a3-anthropic
+
+Anthropic provider for the [A3 agentic framework](https://www.npmjs.com/package/@genui/a3).
+
+## Install
+
+```bash
+npm install @genui/a3-anthropic @genui/a3
+```
+
+## Quick Start
+
+```typescript
+import { createAnthropicProvider } from '@genui/a3-anthropic'
+
+const provider = createAnthropicProvider({
+  models: ['claude-sonnet-4-5-20250929', 'claude-haiku-4-5-20251001'],
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional, defaults to ANTHROPIC_API_KEY env var
+})
+```
+
+## Configuration
+
+`createAnthropicProvider(config)` communicates with the Anthropic Messages API using the [Vercel AI SDK](https://sdk.vercel.ai/providers/ai-sdk-providers/anthropic) (`@ai-sdk/anthropic`) for structured output.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `models` | `string[]` | Yes | Model IDs in preference order (first = primary, rest = fallbacks) |
+| `apiKey` | `string` | No | API key. Defaults to `ANTHROPIC_API_KEY` env var |
+| `baseURL` | `string` | No | Custom base URL for the Anthropic API |
+| `resilience` | `ResilienceConfig` | No | Retry, backoff, and timeout settings. Uses defaults if omitted |
+
+## Behaviour
+
+- Uses the Vercel AI SDK's `Output.object()` for structured output — Zod schema conversion and partial JSON parsing handled internally
+- **Streaming** yields text deltas in real-time via partial object tracking, then emits a validated tool-call result at the end
+- **Appends a `"Continue"` user message** if the last message has an assistant role, to satisfy the alternating-role requirement
+
+## Prerequisites
+
+An Anthropic API key, either passed directly or set as `ANTHROPIC_API_KEY`.
+
+## Documentation
+
+See the [Providers documentation](https://github.com/generalui/a3/blob/main/docs/PROVIDERS.md) for model fallback, per-agent overrides, the provider interface, and more.

package/template/docs/PROVIDER-BEDROCK.md

@@ -0,0 +1,45 @@
+# @genui/a3-bedrock
+
+AWS Bedrock provider for the [A3 agentic framework](https://www.npmjs.com/package/@genui/a3).
+
+## Install
+
+```bash
+npm install @genui/a3-bedrock @genui/a3
+```
+
+## Quick Start
+
+```typescript
+import { createBedrockProvider } from '@genui/a3-bedrock'
+
+const provider = createBedrockProvider({
+  models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'],
+  region: 'us-east-1', // optional, defaults to AWS SDK default
+})
+```
+
+## Configuration
+
+`createBedrockProvider(config)` communicates with AWS Bedrock via the [Converse API](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html).
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `models` | `string[]` | Yes | Model IDs in preference order (first = primary, rest = fallbacks) |
+| `region` | `string` | No | AWS region. Defaults to AWS SDK default |
+| `resilience` | `ResilienceConfig` | No | Retry, backoff, and timeout settings. Uses defaults if omitted |
+
+## Behaviour
+
+- Uses **tool-based JSON extraction** (`structuredResponse` tool) for reliable structured output
+- **Streaming** yields text deltas in real-time, then emits a validated tool-call result at the end
+- **Merges sequential same-role messages** to satisfy Bedrock's alternating-role requirement
+- **Prepends an initial user message** (`"Hi"`) so the conversation always starts with a user turn
+
+## Prerequisites
+
+AWS credentials configured via environment variables, IAM role, or AWS profile — the same setup the AWS SDK expects.
+
+## Documentation
+
+See the [Providers documentation](https://github.com/generalui/a3/blob/main/docs/PROVIDERS.md) for model fallback, per-agent overrides, the provider interface, and more.

package/template/docs/PROVIDER-OPENAI.md

@@ -0,0 +1,47 @@
+# @genui/a3-openai
+
+OpenAI provider for the [A3 agentic framework](https://www.npmjs.com/package/@genui/a3).
+
+## Install
+
+```bash
+npm install @genui/a3-openai @genui/a3
+```
+
+## Quick Start
+
+```typescript
+import { createOpenAIProvider } from '@genui/a3-openai'
+
+const provider = createOpenAIProvider({
+  models: ['gpt-4o', 'gpt-4o-mini'],
+  apiKey: process.env.OPENAI_API_KEY, // optional, defaults to OPENAI_API_KEY env var
+})
+```
+
+## Configuration
+
+`createOpenAIProvider(config)` communicates with the OpenAI Chat Completions API using [structured output](https://platform.openai.com/docs/guides/structured-outputs) (`response_format: json_schema`).
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `models` | `string[]` | Yes | Model IDs in preference order (first = primary, rest = fallbacks) |
+| `apiKey` | `string` | No | API key. Defaults to `OPENAI_API_KEY` env var |
+| `baseURL` | `string` | No | Custom base URL for Azure OpenAI or compatible endpoints |
+| `organization` | `string` | No | OpenAI organization ID |
+| `resilience` | `ResilienceConfig` | No | Retry, backoff, and timeout settings. Uses defaults if omitted |
+
+## Behaviour
+
+- Uses **structured output** (`response_format` with `json_schema`) — no tool calls required
+- **Enforces strict schemas** automatically (`additionalProperties: false`, all properties `required`)
+- **Streaming** extracts `chatbotMessage` text progressively from the JSON response via a character-level state machine, yielding text deltas in real-time
+- Detects **truncated responses** (`finish_reason: length`) and surfaces them as errors
+
+## Prerequisites
+
+An OpenAI API key, either passed directly or set as `OPENAI_API_KEY`.
+
+## Documentation
+
+See the [Providers documentation](https://github.com/generalui/a3/blob/main/docs/PROVIDERS.md) for model fallback, per-agent overrides, the provider interface, and more.

package/template/docs/PROVIDERS.md

@@ -0,0 +1,124 @@
+# Providers
+
+LLM provider implementations for the A3 agentic framework.
+
+A provider is a thin adapter that connects A3 to an LLM API.
+Its job is to convert A3's provider-agnostic request format into the LLM's API format, send the request, and convert the response back into A3's expected format (JSON string for blocking, AG-UI events for streaming).
+
+A3 ships with **AWS Bedrock**, **Anthropic**, and **OpenAI** providers out of the box.
+All three support blocking and streaming modes, model fallback, and structured output via Zod schemas.
+
+For information on specific providers, please see their documentation:
+
+- [AWS Bedrock (`@genui/a3-bedrock`)](https://www.npmjs.com/package/@genui/a3-bedrock)
+- [Anthropic (`@genui/a3-anthropic`)](https://www.npmjs.com/package/@genui/a3-anthropic)
+- [OpenAI (`@genui/a3-openai`)](https://www.npmjs.com/package/@genui/a3-openai)
+
+To connect A3 to an LLM that isn't covered by the built-in providers, see [Creating a Custom Provider](./CUSTOM_PROVIDERS.md).
+
+## Use with A3
+
+```typescript
+import { ChatSession, MemorySessionStore } from '@genui/a3'
+
+const session = new ChatSession({
+  sessionId: 'user-123',
+  store: new MemorySessionStore(),
+  initialAgentId: 'greeting',
+  initialState: {},
+  provider, // any provider from above
+})
+
+// Blocking
+const response = await session.send({ message: 'Hello!' })
+
+// Streaming
+for await (const event of session.send({ message: 'Hello!', stream: true })) {
+  console.log(event)
+}
+```
+
+## Model Fallback
+
+All providers support automatic model fallback.
+List models in order of preference:
+
+```typescript
+const provider = createBedrockProvider({
+  models: [
+    'us.anthropic.claude-sonnet-4-5-20250929-v1:0',  // primary
+    'us.anthropic.claude-haiku-4-5-20251001-v1:0',   // fallback
+  ],
+})
+```
+
+If the primary model fails, the provider automatically retries with the next model in the list.
+If all models fail, the last error is thrown.
+
+All providers include built-in resilience: automatic retries with exponential backoff, per-request and total timeouts, and model fallback.
+See the [Resilience documentation](./RESILIENCE.md) for configuration options and defaults.
+
+## Per-Agent Provider Override
+
+Each agent can override the session-level provider:
+
+```typescript
+import { createOpenAIProvider } from '@genui/a3-openai'
+import { createBedrockProvider } from '@genui/a3-bedrock'
+
+// Session uses Bedrock by default
+const session = new ChatSession({
+  provider: createBedrockProvider({ models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'] }),
+  // ...
+})
+
+// This agent uses OpenAI instead
+const premiumAgent = {
+  id: 'premium',
+  description: 'Handles premium tier requests using GPT-4o',
+  provider: createOpenAIProvider({ models: ['gpt-4o'] }),
+  // ...
+}
+```
+
+## Provider Interface
+
+All providers implement the `Provider` interface from `@genui/a3`:
+
+| Member | Description |
+|---|---|
+| `sendRequest(request)` | Blocking request → `Promise<ProviderResponse>` |
+| `sendRequestStream(request)` | Streaming request → `AsyncGenerator<StreamEvent>` |
+| `name` | Human-readable name (`'bedrock'`, `'anthropic'`, or `'openai'`) |
+
+To create a custom provider, implement this interface and pass it to `ChatSession` or an individual agent.
+See [Creating a Custom Provider](./CUSTOM_PROVIDERS.md) for a step-by-step guide.
+
+## Packages
+
+Each provider is a separate npm package.
+Install the one(s) you need:
+
+```bash
+npm install @genui/a3-bedrock @genui/a3
+npm install @genui/a3-openai @genui/a3
+npm install @genui/a3-anthropic @genui/a3
+```
+
+| Package | Export | Description |
+|---|---|---|
+| `@genui/a3-bedrock` | `createBedrockProvider` | Factory function returning a Bedrock `Provider` |
+| `@genui/a3-bedrock` | `BedrockProviderConfig` | TypeScript config interface |
+| `@genui/a3-anthropic` | `createAnthropicProvider` | Factory function returning an Anthropic `Provider` |
+| `@genui/a3-anthropic` | `AnthropicProviderConfig` | TypeScript config interface |
+| `@genui/a3-openai` | `createOpenAIProvider` | Factory function returning an OpenAI `Provider` |
+| `@genui/a3-openai` | `OpenAIProviderConfig` | TypeScript config interface |
+
+## Requirements
+
+- Node.js 20.19.0+
+- TypeScript 5.9+
+- `@genui/a3` (peer dependency)
+- **Bedrock**: AWS credentials configured in the environment
+- **Anthropic**: `ANTHROPIC_API_KEY` environment variable or `apiKey` config option
+- **OpenAI**: `OPENAI_API_KEY` environment variable or `apiKey` config option

package/template/docs/QUICK-START-EXAMPLES.md

@@ -0,0 +1,197 @@
+# Quick Start
+
+The fastest way to get started with A3 is using the interactive CLI. It scaffolds a full Next.js application, configures your LLM providers, and installs dependencies.
+
+```bash
+npx @genui/a3-create@latest
+```
+
+Follow the prompts to name your project and provide your API keys. Once finished:
+
+```bash
+cd your-project-name
+npm run dev
+```
+
+For more details on the CLI, see the [@genui/a3-create README](https://www.npmjs.com/package/@genui/a3-create).
+
+---
+
+## Manual Installation
+
+If you are adding A3 to an existing project or prefer a manual setup, follow these steps.
+
+### Install
+
+```bash
+npm install @genui/a3
+```
+
+## Define an agent
+
+```typescript
+import { z } from 'zod'
+import { Agent, BaseState } from '@genui/a3'
+
+interface State extends BaseState {
+  userName?: string
+}
+
+export const greetingAgent: Agent<State> = {
+  id: 'greeting',
+  name: 'Greeting Agent',
+  description: 'Greets the user and collects their name',
+  prompt: async () => `
+    You are a friendly greeting agent. Your goal is to greet the user
+    and learn their name. Once you have their name, set goalAchieved to true.
+  `,
+  outputSchema: z.object({
+    userName: z.string().optional(),
+  }),
+  // `transition` is optional. When omitted, the agent stays active by default
+}
+```
+
+## Register and run
+
+```typescript
+import { AgentRegistry, ChatSession, MemorySessionStore } from '@genui/a3'
+import { createBedrockProvider } from '@genui/a3-bedrock'
+
+const registry = AgentRegistry.getInstance<State>()
+registry.register(greetingAgent)
+
+const provider = createBedrockProvider({
+  models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'],
+})
+
+const session = new ChatSession<State>({
+  sessionId: 'demo',
+  store: new MemorySessionStore(),
+  initialAgentId: 'greeting',
+  initialState: { userName: undefined },
+  provider,
+})
+
+const response = await session.send({ message: 'Hi there!' })
+console.log(response.responseMessage)
+// => "Hello! I'd love to get to know you. What's your name?"
+```
+
+That's it.
+One agent, one session, one function call.
+
+## Multi-Agent Example
+
+Here's a pattern with three agents that route between each other, demonstrating how state flows across agent boundaries.
+
+### Define the agents
+
+```typescript
+import { z } from 'zod'
+import { Agent, BaseState } from '@genui/a3'
+
+interface AppState extends BaseState {
+  userName?: string
+  isAuthenticated: boolean
+  issueCategory?: string
+}
+
+// Agent 1: Greeting -- collects the user's name, then routes to auth
+const greetingAgent: Agent<AppState> = {
+  id: 'greeting',
+  name: 'Greeting Agent',
+  description: 'Greets the user and collects their name',
+  prompt: async () => `
+    Greet the user warmly. Ask for their name.
+    Once you have it, set goalAchieved to true.
+  `,
+  outputSchema: z.object({ userName: z.string().optional() }),
+  transition: (_state, goalAchieved) =>
+    goalAchieved ? 'auth' : 'greeting',
+}
+
+// Agent 2: Auth -- verifies identity, then routes to support
+const authAgent: Agent<AppState> = {
+  id: 'auth',
+  name: 'Auth Agent',
+  description: 'Verifies user identity',
+  prompt: async ({ sessionData }) => `
+    The user's name is ${sessionData.state.userName}.
+    Ask them to confirm their email to verify identity.
+    Set goalAchieved to true once verified.
+  `,
+  outputSchema: z.object({ isAuthenticated: z.boolean() }),
+  transition: (_state, goalAchieved) =>
+    goalAchieved ? 'support' : 'auth',
+}
+
+// Agent 3: Support -- handles the user's issue
+const supportAgent: Agent<AppState> = {
+  id: 'support',
+  name: 'Support Agent',
+  description: 'Helps resolve user issues',
+  prompt: async ({ sessionData }) => `
+    The user ${sessionData.state.userName} is authenticated.
+    Help them with their issue. Categorize it.
+    Set goalAchieved when resolved.
+  `,
+  outputSchema: z.object({
+    issueCategory: z.string().optional(),
+  }),
+  // `transition` is optional. If omitted, the flow of the interaction will stay in this agent.
+}
+```
+
+### Wire them up
+
+```typescript
+import { AgentRegistry, ChatSession, MemorySessionStore } from '@genui/a3'
+import { createBedrockProvider } from '@genui/a3-bedrock'
+
+const registry = AgentRegistry.getInstance<AppState>()
+registry.register([greetingAgent, authAgent, supportAgent])
+
+const provider = createBedrockProvider({
+  models: ['us.anthropic.claude-sonnet-4-5-20250929-v1:0'],
+})
+
+const session = new ChatSession<AppState>({
+  sessionId: 'user-456',
+  store: new MemorySessionStore(),
+  initialAgentId: 'greeting',
+  initialState: { isAuthenticated: false },
+  provider,
+})
+```
+
+### Conversation flow
+
+```typescript
+// Turn 1: User greets, greeting agent responds
+await session.send({ message: 'Hello!' })
+// => Greeting agent asks for name
+
+// Turn 2: User provides name, greeting agent completes and chains to auth
+await session.send({ message: "I'm Alex" })
+// => Auth agent asks for email verification
+// (greeting → auth happened automatically in one request)
+
+// Turn 3: User verifies, auth completes and chains to support
+await session.send({ message: 'alex@example.com' })
+// => Support agent asks how it can help
+// State now: { userName: 'Alex', isAuthenticated: true }
+
+// Turn 4: Support agent handles the issue
+await session.send({ message: 'I need help with my billing' })
+// => Support agent resolves the issue
+// State: { userName: 'Alex', isAuthenticated: true, issueCategory: 'billing' }
+```
+
+Notice that:
+
+- **State persists across agents**: `userName` set by the greeting agent is available to auth and support
+- **Agent chaining is automatic**: when greeting completes, auth starts in the same request
+- **Each agent has its own prompt and schema**: they extract different data but share the same state
+
+For non-deterministic routing (LLM-driven agent selection), see [Transitions](./TRANSITIONS.md#non-deterministic-agentid).