> ## Documentation Index
> Fetch the complete documentation index at: https://thethirdpenco-feat-tool-lifecycle-events.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ai-query

> Python primitives for model calls, tools, and stateful agents

`ai-query` is a Python SDK for building AI features at three levels:

* direct model calls
* stateful agents
* live controllable runtimes

It is not one giant abstraction. It is a ladder.

## The Ladder

```python theme={null}
await generate_text(...)        # call a model
stream_text(...)                # stream a model response
await agent.chat(...)           # persistent conversation
await agent.run(...)            # structured result with steps and usage
agent.turn(...)                 # live events, abort, and steering
```

Start at the top. Move down only when your app needs the extra control.

## First Example

```python theme={null}
import asyncio

from ai_query.agents import Agent, SQLiteStorage
from ai_query.providers import openai


async def main():
    agent = Agent(
        "assistant",
        model=openai("gpt-4o"),
        storage=SQLiteStorage("agents.sqlite3"),
    )

    async with agent:
        print(await agent.chat("Hi, I'm Ada."))
        print(await agent.chat("What's my name?"))


asyncio.run(main())
```

## Learn In Order

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/tutorials/quickstart">
    Build from one model call to a stateful agent in a few minutes.
  </Card>

  <Card title="Concepts" icon="map" href="/core/overview">
    Understand the three layers: core generation, agents, and live turns.
  </Card>

  <Card title="Navigating ai-query" icon="signs-post" href="/core/navigating-ai-query">
    Choose the right primitive for your app.
  </Card>

  <Card title="Generating Text" icon="message" href="/core/generate-text">
    Learn the raw model call before adding state or servers.
  </Card>
</CardGroup>

## Core Building Blocks

<CardGroup cols={2}>
  <Card title="Streaming" icon="bolt" href="/core/streaming">
    Stream model output directly or through an agent.
  </Card>

  <Card title="Tools" icon="wrench" href="/core/tools">
    Expose typed Python functions to models.
  </Card>

  <Card title="Tool Loops" icon="rotate" href="/core/agents">
    Understand multi-step tool execution and stop conditions.
  </Card>

  <Card title="Providers" icon="plug" href="/core/providers">
    Configure OpenAI, Anthropic, Google, OpenRouter, and more.
  </Card>
</CardGroup>

## Stateful Agents

<CardGroup cols={2}>
  <Card title="Stateful Agents" icon="database" href="/core/stateful-agents">
    Add identity, storage, message history, and state.
  </Card>

  <Card title="Conversations" icon="messages" href="/core/conversations">
    Work with message history and multi-turn context.
  </Card>

  <Card title="Live Turns" icon="route" href="/core/live-turns">
    Build CLIs, UIs, SSE streams, and steerable runtimes.
  </Card>

  <Card title="Agent Server" icon="server" href="/core/agent-server">
    Route many users to persistent agents.
  </Card>
</CardGroup>

## Reference And Recipes

<CardGroup cols={2}>
  <Card title="API Reference" icon="brackets" href="/reference/agent">
    Look up classes, functions, types, transports, and providers.
  </Card>

  <Card title="Cookbook" icon="book" href="/how-to/index">
    Copy working patterns for RAG, tools, MCP, deployment, and workflows.
  </Card>
</CardGroup>