# vercel/ai architecture

> Architecture diagram of the GitHub repository vercel/ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vercel/ai
- Repository: https://github.com/vercel/ai

## Overview

AI SDK is a provider-agnostic TypeScript toolkit for model calls, agents, and generative interfaces. The documented user workflow passes a prompt and model to generation APIs, optionally wraps the model in an agent or requests structured output, then streams results to a UI. The tree also shows broad modality APIs, provider implementations, shared provider utilities, and a DevTools viewer. Several subsystems are represented by their exact source directories because their implementation was not sampled; edges are limited to README statements and indexed references.

Main entry points: [`packages/ai/src/agent/tool-loop-agent.ts`](https://github.com/vercel/ai/blob/main/packages/ai/src/agent/tool-loop-agent.ts) (Tool-loop agents), [`packages/devtools/src/viewer/client/app.tsx`](https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/app.tsx) (Trace viewer), [`packages/devtools/src/viewer/client/components/step-card.tsx`](https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/components/step-card.tsx) (Step cards), [`packages/ai/src/generate-text/generate-text.ts`](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-text/generate-text.ts) (Text generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Model APIs"]
  node_text["Text generation<br/>[generate-text.ts]"]
  node_structured["Structured output<br/>[generate-object.ts]"]
  node_embedding["Embeddings<br/>[embed.ts]"]
  node_image["Image generation<br/>[generate-image.ts]"]
  node_speech["Speech generation<br/>[generate-speech.ts]"]
  node_transcription["Transcription<br/>[transcribe.ts]"]
  node_translation["Translation"]
  node_video["Video generation<br/>[generate-video.ts]"]
  node_rerank["Reranking<br/>[rerank.ts]"]
  node_realtime["Realtime sessions"]
end

subgraph group_interaction["Agents and UI"]
  node_agent["Tool-loop agents<br/>[tool-loop-agent.ts]"]
  node_agentstream["Agent UI stream"]
  node_uichat["Chat UI<br/>[chat.ts]"]
  node_uistream["UI message stream"]
end

subgraph group_providers["Providers and contracts"]
  node_providerapi["Provider contracts<br/>[provider.ts]"]
  node_gateway["AI Gateway"]
  node_alibaba["Alibaba provider"]
  node_alibabaembed["Alibaba embeddings"]
  node_cohere["Cohere provider"]
  node_cohereembed["Cohere embeddings"]
  node_perplexity["Perplexity provider"]
  node_perplexitycatalog["Perplexity catalog"]
  node_response["Response handling"]
  node_schema["Schema utilities<br/>[schema.ts]"]
  node_binaryscan["Binary field scan"]
end

subgraph group_operations["DevTools and harness"]
  node_devserver["DevTools server<br/>[server.ts]"]
  node_devdb[("Run database<br/>[db.ts]")]
  node_devapp["Trace viewer<br/>[app.tsx]"]
  node_devsteps["Step cards<br/>[step-card.tsx]"]
  node_devshared["Trace components"]
  node_devmessages["Message components"]
  node_devtimeline["Trace timeline<br/>[trace-timeline.tsx]"]
  node_codexclient["Codex app client"]
end

node_user(("Application developer"))

node_user -->|"calls"| node_text
node_user -->|"requests output"| node_structured
node_user -->|"configures"| node_agent
node_agent -->|"streams through"| node_agentstream
node_user -->|"uses chat hook"| node_uichat
node_text -.->|"uses model"| node_providerapi
node_agent -.->|"runs model"| node_text
node_agentstream -.->|"streams messages"| node_uistream
node_gateway -->|"implements"| node_providerapi
node_alibabaembed -->|"catalog reference"| node_alibaba
node_cohereembed -->|"catalog reference"| node_cohere
node_perplexity -->|"catalog reference"| node_perplexitycatalog
node_response -->|"compiles paths"| node_binaryscan
node_response -->|"validates responses"| node_schema
node_devserver -->|"queries and reloads"| node_devdb
node_devapp -->|"renders"| node_devshared
node_devapp -->|"renders"| node_devsteps
node_devapp -->|"renders"| node_devtimeline
node_devsteps -->|"uses components"| node_devshared
node_devsteps -->|"uses components"| node_devmessages
node_codexclient -.->|"harness integration"| node_agent

click node_text "https://github.com/vercel/ai/blob/main/packages/ai/src/generate-text/generate-text.ts"
click node_structured "https://github.com/vercel/ai/blob/main/packages/ai/src/generate-object/generate-object.ts"
click node_embedding "https://github.com/vercel/ai/blob/main/packages/ai/src/embed/embed.ts"
click node_image "https://github.com/vercel/ai/blob/main/packages/ai/src/generate-image/generate-image.ts"
click node_speech "https://github.com/vercel/ai/blob/main/packages/ai/src/generate-speech/generate-speech.ts"
click node_transcription "https://github.com/vercel/ai/blob/main/packages/ai/src/transcribe/transcribe.ts"
click node_video "https://github.com/vercel/ai/blob/main/packages/ai/src/generate-video/generate-video.ts"
click node_rerank "https://github.com/vercel/ai/blob/main/packages/ai/src/rerank/rerank.ts"
click node_realtime "https://github.com/vercel/ai/blob/main/packages/ai/src/realtime/realtime-session.ts"
click node_agent "https://github.com/vercel/ai/blob/main/packages/ai/src/agent/tool-loop-agent.ts"
click node_agentstream "https://github.com/vercel/ai/blob/main/packages/ai/src/agent/create-agent-ui-stream-response.ts"
click node_uichat "https://github.com/vercel/ai/blob/main/packages/ai/src/ui/chat.ts"
click node_uistream "https://github.com/vercel/ai/blob/main/packages/ai/src/ui-message-stream/create-ui-message-stream.ts"
click node_providerapi "https://github.com/vercel/ai/blob/main/packages/ai/src/types/provider.ts"
click node_gateway "https://github.com/vercel/ai/blob/main/packages/gateway/src/gateway-embedding-model.ts"
click node_alibaba "https://github.com/vercel/ai/blob/main/packages/alibaba/src/alibaba-model-catalog.ts"
click node_alibabaembed "https://github.com/vercel/ai/blob/main/packages/alibaba/src/alibaba-embedding-model-options.ts"
click node_cohere "https://github.com/vercel/ai/blob/main/packages/cohere/src/cohere-model-catalog.ts"
click node_cohereembed "https://github.com/vercel/ai/blob/main/packages/cohere/src/cohere-embedding-model-options.ts"
click node_perplexity "https://github.com/vercel/ai/blob/main/packages/perplexity/src/perplexity-language-model.ts"
click node_perplexitycatalog "https://github.com/vercel/ai/blob/main/packages/perplexity/src/perplexity-model-catalog.ts"
click node_response "https://github.com/vercel/ai/blob/main/packages/provider-utils/src/response-handler.ts"
click node_schema "https://github.com/vercel/ai/blob/main/packages/provider-utils/src/schema.ts"
click node_binaryscan "https://github.com/vercel/ai/blob/main/packages/provider-utils/src/json-binary-field-scanner.ts"
click node_devserver "https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/server.ts"
click node_devdb "https://github.com/vercel/ai/blob/main/packages/devtools/src/db.ts"
click node_devapp "https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/app.tsx"
click node_devsteps "https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/components/step-card.tsx"
click node_devshared "https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/components/shared-components.tsx"
click node_devmessages "https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/components/message-components.tsx"
click node_devtimeline "https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/components/trace-timeline.tsx"
click node_codexclient "https://github.com/vercel/ai/blob/main/packages/harness-codex/src/bridge/codex-app-server-client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_text,node_structured,node_embedding,node_image,node_speech,node_transcription,node_translation,node_video,node_rerank,node_realtime toneBlue
class node_agent,node_agentstream,node_uichat,node_uistream toneAmber
class node_providerapi,node_gateway,node_alibaba,node_alibabaembed,node_cohere,node_cohereembed,node_perplexity,node_perplexitycatalog,node_response,node_schema,node_binaryscan toneMint
class node_devserver,node_devdb,node_devapp,node_devsteps,node_devshared,node_devmessages,node_devtimeline,node_codexclient toneRose
class node_user toneIndigo
```

## Components

### Model APIs

- [Text generation](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-text/generate-text.ts): `packages/ai/src/generate-text/generate-text.ts`
- [Structured output](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-object/generate-object.ts): `packages/ai/src/generate-object/generate-object.ts`
- [Embeddings](https://github.com/vercel/ai/blob/main/packages/ai/src/embed/embed.ts): `packages/ai/src/embed/embed.ts`
- [Image generation](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-image/generate-image.ts): `packages/ai/src/generate-image/generate-image.ts`
- [Speech generation](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-speech/generate-speech.ts): `packages/ai/src/generate-speech/generate-speech.ts`
- [Transcription](https://github.com/vercel/ai/blob/main/packages/ai/src/transcribe/transcribe.ts): `packages/ai/src/transcribe/transcribe.ts`
- **Translation**
- [Video generation](https://github.com/vercel/ai/blob/main/packages/ai/src/generate-video/generate-video.ts): `packages/ai/src/generate-video/generate-video.ts`
- [Reranking](https://github.com/vercel/ai/blob/main/packages/ai/src/rerank/rerank.ts): `packages/ai/src/rerank/rerank.ts`
- [Realtime sessions](https://github.com/vercel/ai/blob/main/packages/ai/src/realtime/realtime-session.ts): `packages/ai/src/realtime/realtime-session.ts`

### Agents and UI

- [Tool-loop agents](https://github.com/vercel/ai/blob/main/packages/ai/src/agent/tool-loop-agent.ts): `packages/ai/src/agent/tool-loop-agent.ts`
- [Agent UI stream](https://github.com/vercel/ai/blob/main/packages/ai/src/agent/create-agent-ui-stream-response.ts): `packages/ai/src/agent/create-agent-ui-stream-response.ts`
- [Chat UI](https://github.com/vercel/ai/blob/main/packages/ai/src/ui/chat.ts): `packages/ai/src/ui/chat.ts`
- [UI message stream](https://github.com/vercel/ai/blob/main/packages/ai/src/ui-message-stream/create-ui-message-stream.ts): `packages/ai/src/ui-message-stream/create-ui-message-stream.ts`

### Providers and contracts

- [Provider contracts](https://github.com/vercel/ai/blob/main/packages/ai/src/types/provider.ts): `packages/ai/src/types/provider.ts`
- [AI Gateway](https://github.com/vercel/ai/blob/main/packages/gateway/src/gateway-embedding-model.ts): `packages/gateway/src/gateway-embedding-model.ts`
- [Alibaba provider](https://github.com/vercel/ai/blob/main/packages/alibaba/src/alibaba-model-catalog.ts): `packages/alibaba/src/alibaba-model-catalog.ts`
- [Alibaba embeddings](https://github.com/vercel/ai/blob/main/packages/alibaba/src/alibaba-embedding-model-options.ts): `packages/alibaba/src/alibaba-embedding-model-options.ts`
- [Cohere provider](https://github.com/vercel/ai/blob/main/packages/cohere/src/cohere-model-catalog.ts): `packages/cohere/src/cohere-model-catalog.ts`
- [Cohere embeddings](https://github.com/vercel/ai/blob/main/packages/cohere/src/cohere-embedding-model-options.ts): `packages/cohere/src/cohere-embedding-model-options.ts`
- [Perplexity provider](https://github.com/vercel/ai/blob/main/packages/perplexity/src/perplexity-language-model.ts): `packages/perplexity/src/perplexity-language-model.ts`
- [Perplexity catalog](https://github.com/vercel/ai/blob/main/packages/perplexity/src/perplexity-model-catalog.ts): `packages/perplexity/src/perplexity-model-catalog.ts`
- [Response handling](https://github.com/vercel/ai/blob/main/packages/provider-utils/src/response-handler.ts): `packages/provider-utils/src/response-handler.ts`
- [Schema utilities](https://github.com/vercel/ai/blob/main/packages/provider-utils/src/schema.ts): `packages/provider-utils/src/schema.ts`
- [Binary field scan](https://github.com/vercel/ai/blob/main/packages/provider-utils/src/json-binary-field-scanner.ts): `packages/provider-utils/src/json-binary-field-scanner.ts`

### DevTools and harness

- [DevTools server](https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/server.ts): `packages/devtools/src/viewer/server.ts`
- [Run database](https://github.com/vercel/ai/blob/main/packages/devtools/src/db.ts): `packages/devtools/src/db.ts`
- [Trace viewer](https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/app.tsx): `packages/devtools/src/viewer/client/app.tsx`
- [Step cards](https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/components/step-card.tsx): `packages/devtools/src/viewer/client/components/step-card.tsx`
- [Trace components](https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/components/shared-components.tsx): `packages/devtools/src/viewer/client/components/shared-components.tsx`
- [Message components](https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/components/message-components.tsx): `packages/devtools/src/viewer/client/components/message-components.tsx`
- [Trace timeline](https://github.com/vercel/ai/blob/main/packages/devtools/src/viewer/client/components/trace-timeline.tsx): `packages/devtools/src/viewer/client/components/trace-timeline.tsx`
- [Codex app client](https://github.com/vercel/ai/blob/main/packages/harness-codex/src/bridge/codex-app-server-client.ts): `packages/harness-codex/src/bridge/codex-app-server-client.ts`

### Other components

- **Application developer**

## Connections

- Application developer → Text generation: calls (evidence: `README.md`)
- Application developer → Structured output: requests output (evidence: `README.md`)
- Application developer → Tool-loop agents: configures (evidence: `README.md`)
- Tool-loop agents → Agent UI stream: streams through (evidence: `README.md`)
- Application developer → Chat UI: uses chat hook (evidence: `README.md`)
- Text generation → Provider contracts: uses model
- Tool-loop agents → Text generation: runs model
- Agent UI stream → UI message stream: streams messages
- AI Gateway → Provider contracts: implements (evidence: `packages/gateway/src/gateway-embedding-model.ts`)
- Alibaba embeddings → Alibaba provider: catalog reference (evidence: `packages/alibaba/src/alibaba-embedding-model-options.ts`)
- Cohere embeddings → Cohere provider: catalog reference (evidence: `packages/cohere/src/cohere-embedding-model-options.ts`)
- Perplexity provider → Perplexity catalog: catalog reference (evidence: `packages/perplexity/src/perplexity-embedding-model.ts`)
- Response handling → Binary field scan: compiles paths (evidence: `packages/provider-utils/src/response-handler.ts`)
- Response handling → Schema utilities: validates responses (evidence: `packages/provider-utils/src/response-handler.ts`)
- DevTools server → Run database: queries and reloads (evidence: `packages/devtools/src/viewer/server.ts`)
- Trace viewer → Trace components: renders (evidence: `packages/devtools/src/viewer/client/app.tsx`)
- Trace viewer → Step cards: renders (evidence: `packages/devtools/src/viewer/client/app.tsx`)
- Trace viewer → Trace timeline: renders (evidence: `packages/devtools/src/viewer/client/app.tsx`)
- Step cards → Trace components: uses components (evidence: `packages/devtools/src/viewer/client/components/step-card.tsx`)
- Step cards → Message components: uses components (evidence: `packages/devtools/src/viewer/client/components/step-card.tsx`)
- Codex app client → Tool-loop agents: harness integration
