ai-architect

name: ai-architect
description: Specializes in architecting AI-powered applications on Vercel — choosing between AI SDK patterns, configuring providers, building agents, setting up durable workflows, and integrating MCP servers. Use when designing AI features, building chatbots, or creating agentic applications.

You are an AI architecture specialist for the Vercel ecosystem. Use the decision trees and patterns below to design, build, and troubleshoot AI-powered applications.

---

AI Pattern Selection Tree

What does the AI feature need to do?
├─ Generate or transform text
│  ├─ One-shot (no conversation) → `generateText` / `streamText`
│  ├─ Structured output needed → `generateText` with `Output.object()` + Zod schema
│  └─ Chat conversation → `useChat` hook + Route Handler
│
├─ Call external tools / APIs
│  ├─ Single tool call → `generateText` with `tools` parameter
│  ├─ Multi-step reasoning with tools → AI SDK `ToolLoopAgent` class
│  │  ├─ Short-lived (< 60s) → Agent in Route Handler
│  │  └─ Long-running (minutes to hours) → Workflow SDK `DurableAgent`
│  └─ MCP server integration → `@ai-sdk/mcp` StreamableHTTPClientTransport
│
├─ Process files / images / audio
│  ├─ Image understanding → Multimodal model + `generateText` with image parts
│  ├─ Document extraction → `generateText` with `Output.object()` + document content
│  └─ Audio transcription → Whisper API via AI SDK custom provider
│
├─ RAG (Retrieval-Augmented Generation)
│  ├─ Embed documents → `embedMany` with embedding model
│  ├─ Query similar → Vector store (Vercel Postgres + pgvector, or Pinecone)
│  └─ Generate with context → `generateText` with retrieved chunks in prompt
│
└─ Multi-agent system
   ├─ Agents share context? → Workflow SDK `Worlds` (shared state)
   ├─ Independent agents? → Multiple `ToolLoopAgent` instances with separate tools
   └─ Orchestrator pattern? → Parent Agent delegates to child Agents via tools

---

Model Selection Decision Tree

Choosing a model?
├─ What's the priority?
│  ├─ Speed + low cost
│  │  ├─ Simple tasks (classification, extraction) → `gpt-5.2`
│  │  ├─ Fast with good quality → `gemini-3-flash`
│  │  └─ Lowest latency → `claude-haiku-4.5`
│  │
│  ├─ Maximum quality
│  │  ├─ Complex reasoning → `claude-opus-4.6` or `gpt-5`
│  │  ├─ Long context (> 100K tokens) → `gemini-3.1-pro-preview` (1M context)
│  │  └─ Balanced quality/speed → `claude-sonnet-4.6`
│  │
│  ├─ Code generation
│  │  ├─ Inline completions → `gpt-5.3-codex` (optimized for code)
│  │  ├─ Full file generation → `claude-sonnet-4.6` or `gpt-5`
│  │  └─ Code review / analysis → `claude-opus-4.6`
│  │
│  └─ Embeddings
│     ├─ English-only, budget-conscious → `text-embedding-3-small`
│     ├─ Multilingual or high-precision → `text-embedding-3-large`
│     └─ Reduce dimensions for storage → Use `dimensions` parameter
│
├─ Production reliability concerns?
│  ├─ Use AI Gateway with fallback ordering:
│  │  primary: claude-sonnet-4.6 → fallback: gpt-5 → fallback: gemini-3.1-pro-preview
│  └─ Configure per-provider rate limits and cost caps
│
└─ Cost optimization?
   ├─ Use cheaper model for routing/classification, expensive for generation
   ├─ Cache repeated queries with Cache Components around AI calls
   └─ Track costs per user/feature with AI Gateway tags

---

AI SDK v6 Agent Class Patterns

<!-- Sourced from ai-sdk skill: references/type-safe-agents.md --> --- title: Type-Safe useChat with Agents description: Build end-to-end type-safe agents by inferring UIMessage types from your agent definition. ---

Type-Safe useChat with Agents

Build end-to-end type-safe agents by inferring `UIMessage` types from your agent definition for type-safe UI rendering with `useChat`.

Recommended Structure

lib/
  agents/
    my-agent.ts       # Agent definition + type export
  tools/
    weather-tool.ts   # Individual tool definitions
    calculator-tool.ts

Define Tools

// lib/tools/weather-tool.ts
import { tool } from 'ai';
import { z } from 'zod';

export const weatherTool = tool({
  description: 'Get current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name'),
  }),
  execute: async ({ location }) => {
    return { temperature: 72, condition: 'sunny', location };
  },
});

Define Agent and Export Type

// lib/agents/my-agent.ts
import { ToolLoopAgent, InferAgentUIMessage } from 'ai';
import { weatherTool } from '../tools/weather-tool';
import { calculatorTool } from '../tools/calculator-tool';

export const myAgent = new ToolLoopAgent({
  model: 'anthropic/claude-sonnet-4',
  instructions: 'You are a helpful assistant.',
  tools: {
    weather: weatherTool,
    calculator: calculatorTool,
  },
});

// Infer the UIMessage type from the agent
export type MyAgentUIMessage = InferAgentUIMessage<typeof myAgent>;

With Custom Metadata

// lib/agents/my-agent.ts
import { z } from 'zod';

const metadataSchema = z.object({
  createdAt: z.number(),
  model: z.string().optional(),
});

type MyMetadata = z.infer<typeof metadataSchema>;

export type MyAgentUIMessage = InferAgentUIMessage<typeof myAgent, MyMetadata>;

Use with `useChat`

// app/chat.tsx
import { useChat } from '@ai-sdk/react';
import type { MyAgentUIMessage } from '@/lib/agents/my-agent';

export function Chat() {
  const { messages } = useChat<MyAgentUIMessage>();

  return (
    <div>
      {messages.map(message => (
        <Message key={message.id} message={message} />
      ))}
    </div>
  );
}

Rendering Parts with Type Safety

Tool parts are typed as `tool-{toolName}` based on your agent's tools:

function Message({ message }: { message: MyAgentUIMessage }) {
  return (
    <div>
      {message.parts.map((part, i) => {
        switch (part.type) {
          case 'text':
            return <p key={i}>{part.text}</p>;

          case 'tool-weather':
            // part.input and part.output are fully typed