# AgentRoute Documentation

> Documentation for the AgentRoute Python SDK — build, run, and ship AI agents with tools, memory, history, and structured output on any OpenAI-compatible model.

## Getting started
- [Introduction](https://docs.agentroute.ai/getting-started/introduction): What the AgentRoute SDK is and how its layered API works.
- [Installation](https://docs.agentroute.ai/getting-started/installation): Install the AgentRoute Python SDK, configure an OpenRouter API key, and run your first agent.
- [Quickstart](https://docs.agentroute.ai/getting-started/quickstart): Install AgentRoute, set your API key, and go from a three-line agent to a tool-calling agent in minutes.
- [Your first agent](https://docs.agentroute.ai/getting-started/first-agent): Build a complete AgentRoute agent end to end — define it, give it tools, run it with dependencies, and read back the output and usage.

## Concepts
- [Agents](https://docs.agentroute.ai/concepts/agents): The Agent is the central object you configure in AgentRoute — its model, tools, output, memory, and limits — and run to drive the agentic loop.
- [Tools](https://docs.agentroute.ai/concepts/tools): Give an agent abilities by registering plain Python functions the model can call, with schemas auto-derived from type hints and docstrings.
- [Context & Usage](https://docs.agentroute.ai/concepts/context-and-usage): How AgentRoute injects dependencies into tools with Context, and how it tracks tokens and cost with Usage across a run.
- [Memory](https://docs.agentroute.ai/concepts/memory): Give an agent durable conversation history, persistent facts, and free-text recall — in RAM by default or backed by SQLite with FTS5 search.
- [History](https://docs.agentroute.ai/concepts/history): Compact a growing conversation to fit the context window with sliding-window, truncation, or summarization policies.
- [Structured output](https://docs.agentroute.ai/concepts/structured-output): Get a typed Pydantic model back from an agent instead of free-form text, and validate it with output validators that can ask the model to retry.
- [Models & providers](https://docs.agentroute.ai/concepts/models): How AgentRoute resolves a model string to a provider, infers vendors, and finds your API key — plus Ollama, custom endpoints, and the low-level message types.
- [Errors & retries](https://docs.agentroute.ai/concepts/errors-and-retries): How AgentRoute signals runtime failures with the ErrorAgent exception hierarchy, and how Retry asks the model to try again with a hint.
- [Results](https://docs.agentroute.ai/concepts/results): What agent.run and arun return — the Result object, its output, usage, and message transcript, plus the forthcoming streaming events.

## Guides
- [Building a tool-using agent](https://docs.agentroute.ai/guides/tool-using-agent): A hands-on walkthrough of giving an agent several tools — sync, async, and dependency-reading — and watching the loop pick the right one each turn.
- [Persisting memory with SQLite](https://docs.agentroute.ai/guides/persisting-memory): Give your agent durable, cross-restart memory by swapping the in-RAM store for MemorySQLite, including FTS5-backed fact recall.
- [Managing long conversations](https://docs.agentroute.ai/guides/long-conversations): Keep multi-turn agent conversations inside the context window with sliding-window, truncation, and summarization history policies.
- [Getting structured, validated output](https://docs.agentroute.ai/guides/validated-output): Return typed Pydantic objects from an agent and enforce business rules with a self-correcting validator loop.
- [Using local and custom models](https://docs.agentroute.ai/guides/local-and-custom-models): Run AgentRoute agents against Ollama on localhost or any OpenAI-compatible endpoint, and understand how model strings resolve to a provider.
- [Controlling cost and turns](https://docs.agentroute.ai/guides/cost-and-turn-budgets): Cap how long an agent runs and how much it spends, read back usage, and handle the errors raised when a budget is exceeded.
- [Async and concurrency](https://docs.agentroute.ai/guides/async-and-concurrency): Run agents asynchronously with await agent.arun, and fan out many prompts concurrently using asyncio.gather over one shared agent.
- [Production checklist](https://docs.agentroute.ai/guides/production-checklist): A pragmatic pre-flight list for taking an AgentRoute agent from prototype to production — keys, budgets, retries, persistence, history, error handling, and cost tracking.

## SDK reference
- [SDK reference](https://docs.agentroute.ai/sdk): The complete AgentRoute Python SDK surface — every public class, function, and exception, organized by module.
- [Agent](https://docs.agentroute.ai/sdk/agent): Full API reference for the Agent class — construct an agent, run it, register tools and output validators, and inspect its configuration.
- [tool & Tool](https://docs.agentroute.ai/sdk/tools): Reference for the tool decorator and the Tool dataclass — how AgentRoute turns a Python function into a model-callable tool.
- [Context & Usage](https://docs.agentroute.ai/sdk/context): API reference for Context, the dependency-injection container auto-injected into tools, and Usage, the per-run token and cost tracker.
- [Memory](https://docs.agentroute.ai/sdk/memory): Reference for the Memory protocol and its in-RAM and SQLite-backed implementations — conversation history, persistent facts, and recall.
- [History](https://docs.agentroute.ai/sdk/history): Conversation compaction policies — the History protocol plus the sliding-window, truncate, and summarize strategies for keeping a transcript inside the context window.
- [Models](https://docs.agentroute.ai/sdk/models): Reference for resolve_model, the Model protocol, and the Message, LLMRequest, and LLMResponse message types.
- [Results & events](https://docs.agentroute.ai/sdk/results): API reference for Result, Event, and ResultDeploy — the values agent runs return today and the streaming and deployment types coming in later phases.
- [Exceptions](https://docs.agentroute.ai/sdk/exceptions): The AgentRoute exception hierarchy — ErrorAgent and its subclasses for runtime failures, plus Retry, the control-flow signal that asks the model to try again.

## CLI reference
- [CLI reference](https://docs.agentroute.ai/cli): Install and authenticate the agentroute command-line tool for deploying, listing, and tailing the logs of your hosted agents.
- [Commands](https://docs.agentroute.ai/cli/commands): Full reference for every agentroute CLI command — login, deploy, logs, list, and the global version flag.

## Examples
- [Examples](https://docs.agentroute.ai/examples): A gallery of runnable AgentRoute agents, from a one-file hello world to multi-agent orchestration, each built on the real SDK.
- [Minimal agent](https://docs.agentroute.ai/examples/minimal): The smallest useful AgentRoute agent — one Agent, one tool, one run call.
- [Intent classifier](https://docs.agentroute.ai/examples/intent-classifier): Classify free-text into a structured intent label, confidence score, and category using a typed Pydantic output model.
- [Email composer](https://docs.agentroute.ai/examples/email-composer): Compose and rewrite professional emails as typed drafts using structured output.
- [Content moderator](https://docs.agentroute.ai/examples/content-moderator): A two-stage agent that classifies user content against moderation guidelines and flags PII, returning typed verdicts via structured output.
- [Data transformer](https://docs.agentroute.ai/examples/data-transformer): Convert data between JSON, CSV, and YAML with a typed result, then transform many payloads concurrently with asyncio.gather.
- [Code reviewer](https://docs.agentroute.ai/examples/code-reviewer): A code-review agent that returns a structured verdict — overall score, summary, typed issues, and strengths — using a Pydantic output model.
- [Document Q&A](https://docs.agentroute.ai/examples/doc-qa): Answer questions and summarize over a document you pass in the prompt, returning a typed answer with confidence and grounded source passages.
- [Web researcher](https://docs.agentroute.ai/examples/web-researcher): A research agent that searches the web through a tool and answers with cited source URLs.
- [API integrator](https://docs.agentroute.ai/examples/api-integrator): An agent that calls live REST APIs with a single httpx-backed tool and reasons over the responses in a natural ReAct loop.
- [Knowledge base builder](https://docs.agentroute.ai/examples/knowledge-base-builder): Turn raw documents into structured Q&A pairs and topic summaries, then process a whole corpus concurrently.
- [Workflow orchestrator](https://docs.agentroute.ai/examples/workflow-orchestrator): Chain a planner, a researcher, and a writer into a single multi-step workflow using plain Python async orchestration.

## Resources
- [Changelog](https://docs.agentroute.ai/resources/changelog): Release notes for the AgentRoute Python SDK, newest first.
- [FAQ](https://docs.agentroute.ai/resources/faq): Quick answers to common questions about models, keys, sync vs async, memory, cost control, structured output, and what ships today.
- [Platform & roadmap](https://docs.agentroute.ai/resources/platform-roadmap): An honest snapshot of what the AgentRoute SDK ships today and what is still on the roadmap.