---
title: "Introduction"
description: "Build stateful AI agents in Python"
---

**ai-query** is a Python SDK for building stateful AI agents that persist across requests, emit real-time events, and scale from prototype to production.

## Why ai-query?

- **Stateful by Design** - Agents remember conversations, maintain state, and resume after restarts
- **Real-time Events** - Emit events during work with automatic replay on reconnection
- **Durable Identity** - Persist every event and agent state for robust connection recovery
- **Built-in Server** - WebSocket, SSE, and REST endpoints with one line: `agent.serve()`
- **Multi-Provider** - Same interface for OpenAI, Anthropic, Google, and more
- **Production Ready** - Storage, multi-user routing, serverless support

## Quick Example

A stateful agent with persistent memory and real-time streaming:

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

class ResearchAgent(Agent):
    enable_event_log = True  # Enable event replay on reconnect

    def __init__(self):
        @tool(description="Search the web")
        async def search(query: str = Field(description="Search query")) -> str:
            await self.emit("status", {"text": f"Searching: {query}"})
            return f"Results for: {query}"

        super().__init__(
            "researcher",
            model=openai("gpt-4o"),
            storage=SQLiteStorage("agent.db"),
            tools={"search": search}
        )

# Start server with WebSocket, SSE, and REST endpoints
ResearchAgent().serve(port=8080)
```

```bash
# Chat via REST
curl -X POST http://localhost:8080/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Research quantum computing"}'

# Stream events via SSE
curl http://localhost:8080/events
```

## Get Started

<CardGroup cols={2}>
  <Card
    title="Quickstart"
    icon="rocket"
    href="/quickstart"
  >
    Install ai-query and build your first agent.
  </Card>
  <Card
    title="Stateful Agents"
    icon="database"
    href="/core/stateful-agents"
  >
    Persistence, state management, and lifecycle hooks.
  </Card>
  <Card
    title="Agent Events"
    icon="bolt"
    href="/api-reference/agent#emit"
  >
    Real-time events with automatic replay on reconnection.
  </Card>
  <Card
    title="Agent Server"
    icon="server"
    href="/core/agent-server"
  >
    Multi-agent routing and production deployment.
  </Card>
</CardGroup>

## Core Building Blocks

<CardGroup cols={2}>
  <Card
    title="Generate Text"
    icon="message"
    href="/core/generate-text"
  >
    One-off completions without agent overhead.
  </Card>
  <Card
    title="Tools"
    icon="wrench"
    href="/core/tools"
  >
    Type-safe function calling with automatic execution.
  </Card>
  <Card
    title="Streaming"
    icon="water"
    href="/core/streaming"
  >
    Stream responses chunk by chunk.
  </Card>
  <Card
    title="Providers"
    icon="plug"
    href="/providers"
  >
    OpenAI, Anthropic, Google, and OpenAI-compatible APIs.
  </Card>
</CardGroup>

## Cookbook

<CardGroup cols={2}>
  <Card
    title="Profile Research Agent"
    icon="user-secret"
    href="/cookbook/profile-research-agent"
  >
    OSINT agent with durable SSE streaming and event replay.
  </Card>
  <Card
    title="FastAPI Integration"
    icon="bolt"
    href="/cookbook/fastapi-integration"
  >
    Custom endpoints, middleware, and serverless patterns.
  </Card>
  <Card
    title="Stateless Generation"
    icon="function"
    href="/cookbook/stateless-generation"
  >
    Use generate_text and stream_text directly.
  </Card>
  <Card
    title="Browse All Recipes"
    icon="book"
    href="/cookbook/index"
  >
    Chatbots, task planners, multi-agent workflows, and more.
  </Card>
</CardGroup>
