---
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.
* 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.tool` exposes Python functions to models.
* `Agent` runs the stream -> tool -> stream loop.
* `ai.hook` pauses a workflow for external input.

## Recommended learning path

Read providers, messages, streaming, tools, and agents first. Then add custom
loops, subagents, human-in-the-loop workflows, and UI integration when your app
needs those control points.

## Example map

Focused samples live in `examples/samples/`:

* `stream.py` streams text from a model.
* `tools_schema.py` passes a schema-only tool to a model.
* `agent_simple.py` runs the default agent loop.
* `agent_custom_loop.py` overrides `Agent.loop`.
* `streaming_tool.py` streams partial output from a tool.
* `agent_nested.py` runs a subagent as a tool.

End-to-end demos live in `examples/fastapi-vite`,
`examples/multiagent-textual`, and `examples/temporal-direct`.


---

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

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