Quickstart

Build from a model call to a stateful agent

This guide teaches the product in the same order you should use it:

1. call a model
2. stream a response
3. add a tool
4. create an agent
5. persist state
6. inspect a structured turn
7. build a live turn

Install

pip

pip install ai-query

uv add ai-query

poetry add ai-query

1. Call A Model

Use generate_text() when you do not need state.

import asyncio

from ai_query import generate_text
from ai_query.providers import openai


async def main():
    result = await generate_text(
        model=openai("gpt-4o"),
        prompt="Explain quantum computing in one sentence.",
    )
    print(result.text)


asyncio.run(main())

What you learned:

• providers create models
• generate_text() runs one model loop
• the result contains text, usage, finish reason, and steps

2. Stream A Response

Use stream_text() for raw streaming.

from ai_query import stream_text
from ai_query.providers import openai


result = stream_text(
    model=openai("gpt-4o"),
    prompt="Write a haiku about programming.",
)

async for chunk in result.text_stream:
    print(chunk, end="", flush=True)

Use core streaming for scripts and simple UIs. Use Agent.turn() later when you need events and steering.

3. Add A Tool

Tools are typed Python functions the model can call.

from ai_query import Field, generate_text, tool
from ai_query.providers import openai


@tool(description="Get the current weather for a location")
async def get_weather(
    location: str = Field(description="The city name"),
) -> str:
    return f"The weather in {location} is 72F and sunny."


result = await generate_text(
    model=openai("gpt-4o"),
    prompt="What's the weather like in Tokyo?",
    tools={"get_weather": get_weather},
)

print(result.text)

What you learned:

• @tool turns a Python function into a model-callable tool
• tool arguments are described with type hints and Field
• ai-query handles the tool-call loop

4. Create An Agent

Use Agent when you want memory, state, or persistence.

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


agent = Agent("assistant", model=openai("gpt-4o"))

async with agent:
    print(await agent.chat("My name is Alice."))
    print(await agent.chat("What's my name?"))

What changed:

• the agent has an identity: assistant
• message history is stored on the agent
• chat() appends the user message and assistant response

5. Persist Agent History

Use SQLiteStorage when you want history to survive restarts.

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


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

async with agent:
    print(await agent.chat("Remember: my favorite color is blue."))

Later, recreate the same agent ID with the same storage file:

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

async with agent:
    print(await agent.chat("What's my favorite color?"))

6. Get A Structured Result

Use run() when your app needs more than final text.

result = await agent.run("Investigate why the tests are failing.")

print(result.text)
print(result.finish_reason)
print(result.usage.total_tokens if result.usage else None)
print(len(result.steps))

Use chat() for user-facing responses. Use run() when your application logic needs the metadata.

7. Build A Live Turn

Use turn() for CLIs, web UIs, SSE streams, and controllable runtimes.

turn = agent.turn("Fix the failing test")

async for event in turn.events():
    if event.type == "text.delta":
        print(event.text, end="", flush=True)
    elif event.type == "step.started":
        print(f"\nstep {event.step_number}")

result = await turn.result()

Steer a live turn at the next safe step boundary:

await turn.send("Change direction: inspect database migrations first.")

Abort a live turn:

turn.abort("user cancelled")

What To Read Next

Concepts

Learn the mental model behind the framework.

Navigating ai-query

Choose the right API for your use case.

Stateful Agents

Go deeper on storage, state, and conversations.

Live Turns

Build interactive runtimes with events and steering.