Getting Started

The AI SDK for Python is a toolkit for building large language model (LLM) applications and agent loops. It gives you composable primitives: models, messages, streams, tools, agents, and hooks. You wire them together with plain async Python.

Prerequisites

• Python 3.12 or later.
• uv, pip, or another Python dependency manager.

Install

uv add ai

AI Gateway is the default route for unprefixed model IDs. Configure the gateway key before running the examples:

export AI_GATEWAY_API_KEY="your_access_token_here"

Then import the package in Python:

import ai

Your first agent

This example defines one tool and lets the default agent loop run it:

import asyncio
import ai


@ai.tool
async def contact_mothership(query: str) -> str:
    """Contact the mothership for important decisions."""
    return "Soon."


async def main() -> None:
    model = ai.get_model("anthropic/claude-sonnet-4")
    agent = ai.Agent(tools=[contact_mothership])

    messages = [
        ai.system_message(
            "Use the contact_mothership tool when asked about the future."
        ),
        ai.user_message("When will the robots take over?"),
    ]

    async with agent.run(model, messages) as stream:
        async for event in stream:
            if isinstance(event, ai.events.TextDelta):
                print(event.chunk, end="", flush=True)


if __name__ == "__main__":
    asyncio.run(main())

Run the file:

uv run hello_agent.py

The agent streams text to the terminal. When the model requests contact_mothership, the default loop executes the tool, appends the tool result to the message history, and continues until the model returns a final assistant message.

Streaming without an agent

If you want the model response without a tool-execution loop, call ai.stream directly:

import asyncio
import ai


async def main() -> None:
    model = ai.get_model("anthropic/claude-sonnet-4")
    messages = [
        ai.system_message("Be concise."),
        ai.user_message("Explain why the robots keep asking about batteries."),
    ]

    async with ai.stream(model, messages) as s:
        async for event in s:
            if isinstance(event, ai.events.TextDelta):
                print(event.chunk, end="", flush=True)


if __name__ == "__main__":
    asyncio.run(main())

After iteration, s.message, s.text, s.tool_calls, s.output, and s.usage are populated.

What's next

• Basics: Learn the main workflows for providers, messages, streams, tools, agents, hooks, and UI integrations.
• Reference: Look up public APIs by the names you import and call.
• Examples: Focused, single-file examples live in the agents, media, and models directories under examples/.
• End-to-end demos: web_agent (web chat with human-in-the-loop approval), coding_agent (coding agent), durable_agent_temporal (durable agent runs with Temporal), durable_agent_workflows (durable agent runs with Workflows), and slack_agent (Slack agent).