# theagentrouter

> LiteLLM's API with Agent Router underneath: the SDK alone, for use with a remote gateway. pip install theagentrouter adds the local gateway.

LiteLLM's API (`completion`, `acompletion`, `embedding`, LiteLLM's errors and `Router`) in a small install. Model names are `provider/model`; keys come from the provider's environment variable. Fallbacks, retries and request limits are routes served by the local gateway (Agent Router).

## Docs

- [README.md](https://github.com/theagentrouter/agent-router-python/blob/main/README.md): install, a first call, fallbacks and retries, frameworks
- [docs/usage.md](https://github.com/theagentrouter/agent-router-python/blob/main/docs/usage.md): every function, parameter, response field, error, embeddings, gateways and routes
- [docs/coming-from-litellm.md](https://github.com/theagentrouter/agent-router-python/blob/main/docs/coming-from-litellm.md): what changes when moving from LiteLLM, and what is missing
- [docs/frameworks.md](https://github.com/theagentrouter/agent-router-python/blob/main/docs/frameworks.md): Google ADK, the OpenAI Agents SDK and other frameworks
- [docs/install.md](https://github.com/theagentrouter/agent-router-python/blob/main/docs/install.md): installing, with and without the local gateway
- [docs/local-gateway.md](https://github.com/theagentrouter/agent-router-python/blob/main/docs/local-gateway.md): how the local gateway works and what it can and cannot do

## Examples

- [00_two_liner.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/00_two_liner.py): The smallest program: one call, one answer. Needs OPENAI_API_KEY.
- [01_hello_world.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/01_hello_world.py): A text reply and what it cost. Needs ANTHROPIC_API_KEY (or change the model and key).
- [02_multi_provider.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/02_multi_provider.py): The same call to several providers: only the model name changes.
- [03_streaming.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/03_streaming.py): Stream a reply as it is written. Needs OPENAI_API_KEY.
- [04_tool_use.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/04_tool_use.py): A tool call and the answer that uses its result. Needs ANTHROPIC_API_KEY.
- [05_async.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/05_async.py): Several calls at once with acompletion. Needs OPENAI_API_KEY.
- [06_structured_output.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/06_structured_output.py): A reply that follows a JSON schema, with response_format. Needs OPENAI_API_KEY.
- [07_fallback.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/07_fallback.py): A route with a fallback: when the primary fails, the next model answers.
- [08_retry.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/08_retry.py): A route that retries: the local gateway tries the model again on rate limits and server errors.
- [09_model_alias.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/09_model_alias.py): Names of your own for models, so code says "fast" or "smart" and the choice lives in one place.
- [10_share_traffic.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/10_share_traffic.py): Two models share the traffic of one route: each call goes to one of them at random.
- [11_from_litellm.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/11_from_litellm.py): A typical LiteLLM script, moved to theagentrouter by changing one import.
- [12_litellm_router.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/12_litellm_router.py): LiteLLM's Router, unchanged apart from the import: model groups with fallbacks and retries.
- [13_handling_errors.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/13_handling_errors.py): Errors keep LiteLLM's names, so the same except clauses work. Needs OPENAI_API_KEY.
- [14_cost.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/14_cost.py): What a call cost, and what a model can do, from the bundled model list. Needs OPENAI_API_KEY.
- [15_through_a_gateway.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/15_through_a_gateway.py): Send every call through a gateway your team or company runs, instead of the local gateway.
- [16_adk_agent.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/16_adk_agent.py): A Google ADK agent on theagentrouter, with no LiteLLM installed.
- [17_openai_agents.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/17_openai_agents.py): An OpenAI Agents SDK agent on theagentrouter, with no LiteLLM installed.
- [18_local_gateway.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/18_local_gateway.py): The local gateway: Agent Router on this computer, started by the first call.
- [19_embeddings.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/19_embeddings.py): Embeddings with LiteLLM's arguments: one vector per text, and what the call cost. Needs OPENAI_API_KEY.
- [20_request_limit.py](https://github.com/theagentrouter/agent-router-python/blob/main/examples/20_request_limit.py): A route with a request limit: the local gateway lets 3 requests a minute through and answers the rest with 429.

## Agent skills

- [skills/theagentrouter/SKILL.md](https://github.com/theagentrouter/agent-router-python/blob/main/skills/theagentrouter/SKILL.md): Write Python code that calls AI models with theagentrouter, the Agent Router SDK (LiteLLM's API in a small install). Use when code calls OpenAI, Anthropic or other model providers through theagentrouter, or needs fallbacks, retries, request limits, embeddings or the local gateway.
- [skills/migrate-from-litellm/SKILL.md](https://github.com/theagentrouter/agent-router-python/blob/main/skills/migrate-from-litellm/SKILL.md): Move a Python project from LiteLLM to theagentrouter, the Agent Router SDK. Use when the user asks to replace LiteLLM, drop the litellm dependency, or switch an agent framework (Google ADK, OpenAI Agents SDK) off LiteLLM.

## Optional

- [llms-full.txt](https://github.com/theagentrouter/agent-router-python/blob/main/llms-full.txt): all of the above in one file
