fastapi-agent 0.2.8

💬 Talk to your FastAPI app like it's a teammate.

FastAPI Agent integrates an AI Agent into your FastAPI application.
It allows you to interact with your API endpoints through a chat interface or directly via an API route using an LLM (Large Language Model).

⚙️ Installation:

To install the package, run:

# install with pip
pip install fastapi_agent

# install with uv
uv add fastapi_agent

🧪 Usage:

To use the FastAPI Agent, initialize it with your FastAPI app and AI model.
You can use the default agent routes or add custom ones to your FastAPI application to interact with the agent via a chat interface or API endpoint.

Here is a simple example of how to use the FastAPI Agent with your FastAPI application:

.env

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

app.py

import uvicorn
from dotenv import load_dotenv

from fastapi import FastAPI
from fastapi_agent import FastAPIAgent

# load OPENAI_API_KEY from .env
load_dotenv()

# set your FastAPI app
app = FastAPI(
    title="YOUR APP TITLE",
    version="0.1.0",
    description="SOME DESCRIPTION",
)

# add routes
@app.get("/")
async def root():
    """Welcome endpoint that returns basic API information"""
    return {"message": "Welcome to Test API"}

# add the FastAPI Agent + default routes
FastAPIAgent(
    app,
    model="openai:gpt-4.1-mini",
    base_url="http://localhost:8000",
    include_router=True,
)

# run FastAPI
uvicorn.run(app, host="0.0.0.0", port=8000)

🧭 Default Routes

FastAPI Agent provides two default routes:

1. /agent/query – Ask anything about your API using natural language. 🧠

curl -k -X POST "http://127.0.0.1:8000/agent/query" \
-H "Content-Type: application/json" \
-d '{"query": "show all endpoints"}'

2. /agent/chat – A simple web-based chat interface to interact with your API. 💬

💡 You can also add custom routes using agent.chat() method - Example

💬 AI Chat - Web UI

When you integrate FastAPI Agent into your FastAPI application, it automatically adds a new endpoint at /agent/chat, which provides a minimal chat interface to interact with your API.

🧩 Additional Arguments:

If your application routes use Authorizations Depends (e.g. Headers or Query String API key or HTTP_Bearer), you need to pass a dictionary of the authorizations.
The agent will use them to call your routes and also apply authorizations dependencies to /agent/query route. (see Additional Examples)

api_key = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

FastAPIAgent(
    app,
    model="openai:gpt-4.1-mini",
    base_url="https://localhost:8000",
    auth={"api-key": API_KEY} || {'Authorization': "Bearer API_KEY"},
    include_router=True,
)

You can control which routes the agent can access using the ignore_routes or allow_routes arguments:

• Use ignore_routes to exclude specific routes from being accessible to the agent.
• Use allow_routes to restrict the agent to only the specified routes.

Both ignore_routes and allow_routes must be a list of strings in the format: ["METHOD:/path"]

FastAPIAgent(
    app,
    model="openai:gpt-4.1-mini",
    base_url="https://localhost:8000",
    ignore_routes=["DELETE:/users/{user_id}"],
    include_router=True,
)

📁 Additional Examples:

Check out our examples for ai_agent, fastapi_discovery, and fastapi_agent.
All examples are available here.

If you're using Authorizations Depends in your routes, make sure to pass the required headers when calling the /agent/query endpoint like in the examples below:

python

import requests

res = requests.post(
    "http://127.0.0.1:8000/agent/query", 
    json={"query": "show all endpoints"},
    headers={"auth": '{"api-key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'}
    - OR - 
    headers={"auth": '{"Authorization": "Bearer 12345678"}'}
)
print(res.json())

curl

curl -k -X POST "http://127.0.0.1:8000/agent/query" \
  -H 'auth: {"api-key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}' \
  - OR -
  -H 'auth: {"Authorization": "Bearer 12345678"}' \
  -H "Content-Type: application/json" \
  -d '{"query": "show all endpoints"}'

🧪 Development & Testing

FastAPI Agent includes a comprehensive test suite to ensure reliability and quality.

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage report
pytest --cov=fastapi_agent --cov-report=term-missing

# Run specific test file
pytest tests/test_auth.py

# Generate HTML coverage report
pytest --cov=fastapi_agent --cov-report=html

Test Coverage

• 77 tests covering authentication detection, route discovery, and agent orchestration
• 79% overall coverage with critical components at 80%+ coverage
• All external dependencies (LLM calls, HTTP requests) are mocked for fast, reliable tests

📜 License

This project is licensed under the MIT License.