---
title: Basics
description: Build applications with the AI SDK for Python.
type: guide
summary: Learn the main workflows for models, messages, streams, tools, agents, and UI integrations.
---

# Basics



The AI SDK for Python is built around a small set of primitives. Each primitive
does one job and uses regular Python values where possible, so you can combine
the SDK with your own application code instead of moving your code into a
framework-specific shape.

## What you can build

Start with the model call, then add the pieces your app needs:

* Stream text or structured JSON from a model.
* Generate images, video, and speech with dedicated models.
* Embed text, transcribe audio, and rerank documents.
* Send images, audio, documents, and generated files through messages.
* Define Python tools and let an agent execute them.
* Pause tools for approval with hooks.
* Run subagents as tools and stream their output.
* Bridge agent streams to AI SDK UI clients over Server-Sent Events (SSE).

## Main primitives

* `Model` identifies the provider model to call.
* `Message` carries conversation history as typed parts.
* `ai.stream` yields model events and aggregates the assistant message.
* `ai.ops` runs dedicated model operations that return standalone values.
* `@ai.tool` exposes Python functions to models.
* `Agent` runs the stream -> tool -> stream loop.
* `ai.hook` pauses a workflow for external input.

## Example map

Focused samples live in category directories under `examples/`:

* `examples/models/stream.py` streams text from a model.
* `examples/models/generate.py` returns a buffered model response.
* `examples/media/image_generation.py` generates images.
* `examples/media/embeddings.py` embeds text.
* `examples/media/transcription.py` transcribes audio.
* `examples/media/reranking.py` reranks documents.
* `examples/agents/basic.py` runs the default agent loop.
* `examples/agents/custom_loop.py` overrides `Agent.loop`.
* `examples/agents/streaming_tool.py` streams partial output from a tool.
* `examples/agents/subagent.py` runs a subagent as a tool.

End-to-end demos live in
[`examples/apps/web_agent`](https://github.com/vercel-labs/ai-python/tree/main/examples/apps/web_agent),
[`examples/apps/coding_agent`](https://github.com/vercel-labs/ai-python/tree/main/examples/apps/coding_agent),
[`examples/apps/durable_agent_temporal`](https://github.com/vercel-labs/ai-python/tree/main/examples/apps/durable_agent_temporal),
[`examples/apps/durable_agent_workflows`](https://github.com/vercel-labs/ai-python/tree/main/examples/apps/durable_agent_workflows),
and [`examples/apps/slack_agent`](https://github.com/vercel-labs/ai-python/tree/main/examples/apps/slack_agent).


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)