AI SDK Core Overview
Purpose and Scope
AI SDK Core is the lower-level application layer for making provider-agnostic model calls. It exists for developers who want direct control over prompts, model settings, tool loops, streaming, structured output, and the response objects that come back from language models. The Core overview defines the problem in product terms: large language models can understand and generate language, but applications need a standardized integration surface so teams can focus on user-facing AI features instead of provider-specific plumbing. Sources: content/docs/03-ai-sdk-core/01-overview.mdx
The most important mental model is that Core is not a chatbot framework and not a complete coding-agent runtime. It is the shared model-call surface used by higher-level experiences. You use Core when you want to call a model directly, stream partial output, validate structured data, execute tools, or compose your own agent behavior. The official API reference also groups adjacent primitives here, including embeddings, reranking, media generation, file uploads, middleware, provider registries, telemetry, testing helpers, stream utilities, and schema helpers.
Core sits beside, rather than inside, AI SDK UI and AI SDK Harnesses. UI is a framework-agnostic frontend toolkit for chat, completion, object streaming, and assistant interfaces. Harnesses are experimental integrations for established agent runtimes such as coding agents that own sessions, workspaces, permissions, and sandboxed execution. Core is the direct-call foundation underneath many of those experiences, while UI and harness packages add state management, transport, rendering, or runtime orchestration. Sources: content/docs/03-ai-sdk-harnesses/01-overview.mdx, content/docs/04-ai-sdk-ui/01-overview.mdx
Relevant Source Files
- content/docs/03-ai-sdk-core/01-overview.mdx — Defines AI SDK Core as the standardized LLM integration layer and names the primary Core function families for text generation, structured data generation, tool usage, prompts, settings, and API reference discovery.
- content/docs/03-ai-sdk-harnesses/01-overview.mdx — Explains how harnesses differ from providers and Core model calls, including the role of HarnessAgent, sessions, sandboxed runtimes, and stream compatibility with AI SDK response types.
- content/docs/04-ai-sdk-ui/01-overview.mdx — Describes AI SDK UI as the framework-agnostic layer for interactive chat, completion, and object-generation experiences built around hooks and streamed frontend state.
Core Primitives
The Core overview names generateText and streamText as the first two functions to understand. generateText is for non-interactive work such as summarization, drafting, automation, and agent steps that may include tool calls. streamText is for interactive use cases where partial model output should be delivered as it is produced, such as chatbots and content streaming. Both functions use standardized prompts and settings, which is what allows the same application-level call shape to work across different providers and models. Sources: content/docs/03-ai-sdk-core/01-overview.mdx
Structured output is part of the same Core model rather than a separate product area. The Core overview states that both generateText and streamText support structured output through the output property, with examples such as Output.object() and Output.array(). That means a developer can ask for typed, schema-validated results for extraction, classification, synthetic data generation, or streamed generated UI patterns without abandoning the same provider-agnostic call structure. This is the bridge between natural-language generation and application data contracts.
Tools are another Core primitive because real applications often need the model to request actions rather than only produce text. The overview groups tool usage with text and structured data generation, and the broader reference surface includes tool, dynamicTool, tool filtering, loop-finish predicates, MCP client helpers, and sandbox-related types. At the Core level, a tool is a controlled capability exposed to the model with a schema and execution behavior; higher-level agents can build loops around those tool calls, but the base contract belongs to Core.
System-to-Code Mapping
The source documentation separates three layers that are easy to confuse. Providers expose models to Core functions. Core functions perform direct model-oriented work such as generation, streaming, structured output, and tool calls. UI packages consume streams and manage frontend state through hooks such as useChat, useCompletion, and useObject. Harnesses expose complete agent runtimes through HarnessAgent, with sessions and sandboxed workspaces, while projecting their output into familiar AI SDK stream and response shapes where possible. Sources: content/docs/03-ai-sdk-core/01-overview.mdx, content/docs/03-ai-sdk-harnesses/01-overview.mdx, content/docs/04-ai-sdk-ui/01-overview.mdx
| Reader goal | Start with | Why |
|---|---|---|
| Make a direct model call | generateText | Returns generated text and can include tool calls for non-interactive tasks. |
| Stream text to a user | streamText | Produces incremental output for chatbots, completion UIs, and other live experiences. |
| Produce typed data | output with Output.object() or Output.array() | Adds schema-validated structured output to text or streaming calls. |
| Build a frontend chat UI | AI SDK UI hooks | useChat, useCompletion, and useObject manage frontend state and streamed updates. |
| Run an established coding-agent runtime | AI SDK Harnesses | HarnessAgent wraps a full runtime with sessions, workspace access, permissions, and sandboxing. |
Execution Flow
A typical Core-first flow starts with choosing a provider or gateway model identifier, then calling a Core function with a prompt and settings. The official overview example uses generateText from the ai package with a model string and a prompt, returning a text field. In a production application, that same call shape can be expanded with system messages, model settings, tool definitions, output schemas, provider options, telemetry, lifecycle callbacks, and error handling depending on the task.
When the user experience requires progressive output, the flow changes from a single generated result to a stream. streamText keeps the same conceptual inputs but returns stream-oriented results that can be consumed by server responses, UI transports, or custom stream processing. AI SDK UI exists to reduce the frontend complexity around those streams: its hooks abstract message state, inputs, loading, errors, completion text, and streamed JSON consumption. This lets backend Core calls and frontend UI state remain connected without turning every app into a custom streaming protocol implementation. Sources: content/docs/04-ai-sdk-ui/01-overview.mdx
Harness execution is different because a harness session owns state. The harness overview emphasizes that a harness is a complete agent runtime with workspace access, built-in tools, native session state, compaction, permission flows, runtime-specific configuration, and sandboxed execution. HarnessAgent.generate() and HarnessAgent.stream() return AI SDK-compatible result types, but the underlying runtime is not merely a language model call. Use this distinction when deciding whether to assemble behavior with Core tools or delegate the task to an existing runtime. Sources: content/docs/03-ai-sdk-harnesses/01-overview.mdx
API Components
The Core API reference is broad, but the overview gives the entry-point hierarchy. Text generation starts with generateText and streamText. Structured data is available through generation functions and the output property, including object and array output helpers. Tool calling is represented by tool definitions, dynamic tools, active-tool filtering, loop-control helpers such as step-count and tool-call predicates, and repair or approval patterns covered in the deeper tool-calling pages. Schema helpers such as jsonSchema, zodSchema, and valibotSchema support typed validation at the model boundary.
Beyond text and tools, Core also includes embeddings and reranking for retrieval-style workflows, media generation functions for image, audio, video, transcription, speech, and uploads, realtime helpers for session-oriented realtime models, and middleware/provider-management APIs such as custom providers, provider registries, and model wrapping. The reference surface also includes telemetry registration, DevTools-oriented inspection, testing utilities such as simulated streams, ID generators, smoothing transforms, and reasoning extraction middleware. Treat this page as the map; use the focused reference pages when you need exact signatures and options.
Choosing the Right Layer
Choose AI SDK Core when your main problem is expressing a model interaction precisely. That includes prompt engineering, model settings, provider options, schemas, tools, embeddings, reranking, media calls, middleware, telemetry, or custom orchestration. Choose AI SDK UI when the main problem is frontend interaction: rendering chat messages, consuming streamed completions, reading streamed objects, or using supported framework packages for React, Svelte, Vue, Angular, and related ecosystems. The UI overview explicitly frames this layer as a way to reduce the complexity of managing chat streams and UI updates. Sources: content/docs/04-ai-sdk-ui/01-overview.mdx
Choose AI SDK Harnesses when you want an existing agent runtime to drive the work. The harness overview recommends this path for coding agents that inspect or modify a sandboxed workspace, runtimes with their own built-in tools and permission model, multi-turn sessions where the runtime owns conversation history, and workflows that should preserve native harness behavior. If you instead want direct control over the model call, tool loop, settings, structured output, or custom agent architecture, stay with providers, models, and Core functions. Sources: content/docs/03-ai-sdk-harnesses/01-overview.mdx
Next Steps
Start with generateText if you are learning the Core result shape, then move to streamText when you need live output. After that, read the focused pages for structured data generation, tool calling, runtime and tool context, settings and reasoning, embeddings and reranking, media generation, realtime models, middleware and provider management, telemetry, testing, and DevTools. If your application is user-facing, pair the Core streaming pages with the AI SDK UI overview. If your application is an agent runtime or coding workflow, compare Core tool loops with HarnessAgent sessions before choosing an architecture.