---
title: "Quickstart"
description: "Get started with ai-query in minutes"
---

## Installation

Install ai-query using your preferred package manager:

<CodeGroup>

```bash pip
pip install ai-query
```

```bash uv
uv add ai-query
```

```bash poetry
poetry add ai-query
```

</CodeGroup>


## Generate Your First Response

```python
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())
```

## Switch Providers Instantly

The same code works with any provider:

<CodeGroup>

```python OpenAI
from ai_query import generate_text
from ai_query.providers import openai

result = await generate_text(
    model=openai("gpt-4o"),
    prompt="Hello, world!"
)
```

```python Anthropic
from ai_query import generate_text
from ai_query.providers import anthropic

result = await generate_text(
    model=anthropic("claude-sonnet-4-20250514"),
    prompt="Hello, world!"
)
```

```python Google
from ai_query import generate_text
from ai_query.providers import google

result = await generate_text(
    model=google("gemini-2.0-flash"),
    prompt="Hello, world!"
)
```

</CodeGroup>

## Stream Responses

For real-time output:

```python
from ai_query import stream_text
from ai_query.providers import openai

async for chunk in stream_text(
    model=openai("gpt-4o"),
    prompt="Write a haiku about programming."
):
    print(chunk, end="", flush=True)
```

## Add Tools

Give your AI the ability to call functions:

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

@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 72°F 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)
```

## Build a Stateful Agent

Create an agent that remembers conversations:

```python
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?"))  # Remembers: "Alice"
```

## Add Persistence

Make your agent remember across restarts:

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

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

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

# Later, in a new process...
async with agent:
    print(await agent.chat("What's my favorite color?"))  # "blue"
```

## Cancel Operations

Use abort signals for timeouts and cancellation:

```python
from ai_query import generate_text
from ai_query.providers import openai, AbortSignal

result = await generate_text(
    model=openai("gpt-4o"),
    prompt="Write a long essay",
    signal=AbortSignal.timeout(30)  # Auto-cancel after 30s
)
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Providers" icon="server" href="/providers">
    Configure and customize AI providers
  </Card>
  <Card title="Tool Calling" icon="wrench" href="/core/tools">
    Build powerful tools with type safety
  </Card>
  <Card title="Streaming" icon="bolt" href="/core/streaming">
    Learn advanced streaming patterns
  </Card>
  <Card title="Stateful Agents" icon="robot" href="/core/stateful-agents">
    Build persistent AI agents
  </Card>
  <Card title="Abort/Cancellation" icon="circle-stop" href="/core/abort">
    Control long-running operations
  </Card>
  <Card title="Embeddings" icon="cube" href="/core/embeddings">
    Generate vector embeddings
  </Card>
</CardGroup>
