Foundations Overview
Purpose and Scope
The foundations section gives you the mental model for building with the AI SDK before you choose a framework, provider, or agent runtime. The repository documentation separates three surfaces that often appear together in an application: AI SDK Core for model calls, AI SDK UI for frontend interaction patterns, and AI SDK Harnesses for complete agent runtimes. Reading these foundations first helps you decide whether a feature belongs in a direct model call, a UI stream, a tool loop, or a harness session rather than mixing those concerns accidentally.
Sources: content/docs/03-ai-sdk-core/01-overview.mdx, content/docs/04-ai-sdk-ui/01-overview.mdx, content/docs/03-ai-sdk-harnesses/01-overview.mdx
AI SDK Core is the lower-level surface. Its overview defines large language models as programs that understand and generate human language, then frames the SDK’s job as standardizing integration so application code can focus on product behavior instead of provider-specific request mechanics. Core functions such as generateText and streamText are the starting points for text generation, tool calls, prompts, settings, and structured output. That makes Core the place to learn the vocabulary of models, prompts, settings, streams, and typed results.
AI SDK UI is the application-facing layer for interactive experiences. Its overview describes a framework-agnostic toolkit for chat, completion, and assistant applications, with hooks that manage the repetitive frontend work around inputs, messages, loading state, errors, and streamed updates. This is important because streaming is not only a transport detail: it shapes how users perceive progress, how message state is represented, and how server responses are converted into interface updates across React, Svelte, Vue, Angular, and other supported environments.
Harnesses occupy a different layer from both Core and UI. The harness overview defines a harness as a complete agent runtime, such as Claude Code, Codex, or Pi, that owns capabilities larger than one model call: workspace access, built-in coding tools, native session state, compaction, permission flows, runtime configuration, and sandboxed execution. The key foundation is that providers expose models to Core functions, while harness adapters expose agent runtimes to HarnessAgent. Those abstractions can interoperate through compatible streams, but they should not be treated as the same thing.
Relevant Source Files
content/docs/03-ai-sdk-core/01-overview.mdx— Defines AI SDK Core, its provider-agnostic role, and the main generation functions that foundation concepts build on.content/docs/04-ai-sdk-ui/01-overview.mdx— Defines AI SDK UI, its framework-agnostic hooks, supported frameworks, and the frontend problems solved by streaming abstractions.content/docs/03-ai-sdk-harnesses/01-overview.mdx— Defines harnesses,HarnessAgent, sessions, compatible streams, and when a complete agent runtime is preferable to direct model calls.
Core Primitives
A model is the capability you call to generate text, structured data, reasoning, tool calls, or other modality-specific outputs. A provider is the package or gateway surface that supplies those models behind a common AI SDK interface. This separation is foundational: application code should usually depend on the AI SDK’s standardized call shapes, while provider selection determines model names, credentials, model-specific options, and supported capabilities. Provider options therefore sit at the boundary between portable application logic and provider-specific behavior.
Sources: content/docs/03-ai-sdk-core/01-overview.mdx
A prompt is the input you send to a model. In Core, prompts and settings are presented as standardized parts of the same workflow, so text generation, structured generation, and tool usage can be described consistently across providers. For simple automation, generateText is the natural primitive because it returns a completed result for tasks such as drafting, summarizing, or running an agentic tool loop to completion. For interactive applications, streamText is the natural primitive because it exposes incremental text and tool-call progress as the model works.
Tools are callable capabilities that extend a model beyond text prediction. The foundation docs point readers from the Core overview to tool usage, and the official terminology distinguishes function tools, dynamic tools, and provider-defined tools. Function tools are application-defined and portable; dynamic tools are useful when the schema is discovered at runtime, such as from MCP servers; provider-defined tools use schemas and descriptions supplied by a provider but execute on the application side. The practical rule is to model tools as explicit capabilities with schemas, execution boundaries, and approval or sandbox requirements where needed.
Streams connect the server-side generation lifecycle to the user experience. Core streaming produces model output and tool-call progress; UI streaming turns that server-side flow into state that components can render. AI SDK UI’s useChat, useCompletion, and useObject hooks each specialize that pattern for a different interaction: multi-message chat, prompt-to-completion text, and streamed JSON objects. The hooks reduce boilerplate, but the underlying foundation remains the same: a stream is a sequence of meaningful parts that must be transported, rendered, and reconciled with application state.
System-to-Code Mapping
The foundations map cleanly onto the three overview documents. AI SDK Core explains the provider-agnostic model-call layer and names the functions that most lower-level pages expand: generateText, streamText, and structured output via the output property, including object and array modes. AI SDK UI explains how those outputs are consumed in applications through hooks and framework packages. AI SDK Harnesses explains when the unit of work is not a model call at all, but a session owned by a runtime that can preserve workspace state and native conversation history.
Sources: content/docs/03-ai-sdk-core/01-overview.mdx, content/docs/04-ai-sdk-ui/01-overview.mdx, content/docs/03-ai-sdk-harnesses/01-overview.mdx
Use Core when you need direct control over model settings, prompts, structured output, tool choice, provider options, telemetry, middleware, or a custom tool loop. Use UI when the main problem is delivering an interactive frontend that stays synchronized with streamed server output. Use a harness when an existing runtime should own the task, especially coding-agent workflows that need a sandboxed workspace, built-in tools, session state, permission flows, and runtime-native behavior. This distinction keeps architecture decisions explicit and prevents a UI hook from becoming responsible for runtime policy or a harness from being treated like a stateless completion endpoint.
The stream compatibility described by the harness overview is the bridge between these surfaces. HarnessAgent.generate() returns an AI SDK GenerateTextResult, while HarnessAgent.stream() returns an AI SDK StreamTextResult. That lets familiar consumers handle fields such as text, stream parts, steps, usage, and response messages, and it allows harness streams to be projected into UI message streams. The compatibility is intentionally pragmatic: text, reasoning, tool calls, tool results, usage, and finish reasons use common shapes where possible, while harness-specific events can surface as dynamic provider-executed tool parts.
Execution Flow
A typical foundations-level workflow starts by choosing the unit of work. If the application needs a single server-side operation, start with AI SDK Core and decide whether the response should be complete text, streamed text, typed structured output, or a tool-using loop. Define the prompt, settings, model, and any tools at that boundary. Provider options should be introduced only when the selected model needs provider-specific configuration; keeping them localized makes later provider changes easier.
If the application is interactive, the next decision is how the client consumes the server result. AI SDK UI is designed for this layer, so a chat interface should begin with useChat, a text-completion interface with useCompletion, and a structured streaming interface with useObject. These hooks do not replace Core concepts; they package them for frontend state management. They help handle inputs, messages, loading, errors, and streamed updates so product code can focus on the user experience rather than rebuilding stream reconciliation.
If the application needs an established agent runtime, the workflow changes again. Create or configure a HarnessAgent, create a session, run generate or stream against that session, and destroy or persist the session according to the server route’s lifecycle. The harness documentation emphasizes that a session owns runtime state, sandbox, working directory, native conversation history, and pending approvals. That makes session handling a foundation concept for harness-backed applications, not an implementation detail to defer until production.
Next Steps
After this overview, read the foundations pages in the order that matches your task. For direct model calls, continue to providers and models, prompts and messages, tools, streaming, and provider options. For applications, move from streaming foundations into the UI overview and chatbot flow. For agentic systems, read the agents overview before building tool loops, approvals, memory, subagents, or harness-backed workflows. If your tools execute commands or code, pay special attention to sandbox boundaries: an experimental sandbox only runs operations explicitly delegated to it, while application tool code still runs in your application environment.