πŸš€ Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more β†’
Socket
Book a DemoInstallSign in
Socket

fastapi-agents

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

fastapi-agents

A FastAPI extension for integrating common AI agent frameworks.

0.1.28
PyPI
Maintainers
1

FastAPI Agents

FastAPI Agents is the ultimate FastAPI extension for integrating AI agents into your applications. With just a few lines of code, you can create, manage, and secure AI-powered endpoints, enabling you to build smarter, more interactive apps effortlessly. Whether you're a seasoned developer or just exploring AI integrations, FastAPI Agents has you covered! πŸŽ‰

✨ Features at a Glance

  • πŸ€– Easy Agent Management: Register, organize, and interact with multiple AI agents seamlessly.
  • πŸ” Built-In Security: Easily add API key, OAuth2, cookie, or OpenID authentication to your endpoints.
  • πŸ“š Agent Framework Support: Compatible with agent frameworks like PydanticAI, Llama-Index, HuggingFace Smolagents and CrewAI.
  • 🐳 Pre-Built Containers: Easily deploy agents in your favourite framework with ready made containers.
  • πŸ”Œ OpenAI Compatibility: Use your APIs with other AI tooling including the OpenAI SDK itself. (Experimental)
  • πŸ› οΈ Extensibility: Support additional agent frameworks by extending the BaseAgent class.
  • 🧩 Dynamic Dependencies: Inject and resolve request-specific configurations effortlessly.
  • πŸš€ Performance Optimized: Leverage FastAPI's high performance and scalability for AI agent interactions.
  • πŸ“– Auto-Generated API Documentation: OpenAPI integration for your registered agents, out of the box!

See Releases for the latest updates at and Roadmap for what's coming.

πŸ’– Sponsors

You can support the ongoing development of FastAPI Agents by becoming a sponsor:

Sponsor FastAPI Agents

πŸ“š Documentation

For further documentation, including detailed API documentation for the available agent frameworks, visit the FastAPI Agents Documentation.

πŸš€ Installation

Install FastAPI Agents using pip, poetry or uv:

pip install fastapi-agents
poetry add fastapi-agents
uv add fastapi-agents

Install optional extras for your chosen agent frameworks:

pip install 'fastapi-agents[pydantic-ai]'
poetry add fastapi-agents -E pydantic-ai
uv add fastapi-agents --extra pydantic-ai

For available extras, replace pydantic-ai with the desired agent framework (e.g. smolagents or llama-index). See pyproject.toml for the full list of extras.

That's it! You're all set to start integrating AI agents into your FastAPI applications. πŸŽ‰

🏁 Quick Start

Registering Agents

Here’s how to get started with a basic PydanticAI agent:

from fastapi import FastAPI
from fastapi_agents import FastAPIAgents
from fastapi_agents.pydantic_ai import PydanticAIAgent
from pydantic_ai import Agent

app = FastAPI()
agents = FastAPIAgents(path_prefix="/agents")

# Initialize and register the agent
agent = Agent("openai:gpt-4o-mini")
agents.register("pydanticai", PydanticAIAgent(agent))

# Include the router
app.include_router(agents)

Adding Security

Secure your endpoints with API Key authentication in just a few steps:

from fastapi.security import APIKeyHeader
from fastapi_agents import FastAPIAgents

# Define API Key validation
def validate_api_key(api_key: str = Depends(APIKeyHeader(name="X-API-Key"))):
    if api_key != "my-secret-api-key":
        raise HTTPException(status_code=403, detail="Invalid API Key")

# Secure the agents
agents = FastAPIAgents(path_prefix="/agents", security_dependency=validate_api_key)

πŸ‘‰ See Security Examples for more details.

Running the Application

Run your FastAPI application with the registered agents:

uvicorn --reload <module>:app

Replace <module> with the name of the Python module containing your FastAPI application.

That's it! You're all set to start building smarter, more secure FastAPI applications with AI agents. πŸš€

🀝 Supported Agents

FastAPI Agents supports a variety of agent frameworks, including:

  • PydanticAI: AI agents powered by Pydantic AI. Examples
  • Llama Index: OpenAI agents with Llama Index integration. Examples
  • HuggingFace Smolagents: Lightweight and efficient AI agents. Examples
  • CrewAI: Multi-agent Framework to create Crews. Examples

🐳 Using Docker

Pre-Built Images

The simplest way to containerise your agents!

Pre-built Docker images for FastAPI Agents are available on GitHub Container Registry (GHCR):

Repository: ghcr.io/blairhudson/fastapi-agents

Tags:

  • Framework-specific: pydantic-ai, smolagents, llama-index, crewai
  • Version-specific: <framework>-<version>

To pull a specific image:

docker pull ghcr.io/blairhudson/fastapi-agents:pydantic-ai

See all available images and tags in Versions.

Currently pre-built images support only one agent per container. If you are creating containers that can serve multiple agents, it is recommended to define your own containers.

Environment Variables

The pre-built images support the following environment variables for customisation:

VariableExample ValueDescription
AGENT_FRAMEWORKpydantic-aiSpecifies the agent framework to use.
AGENT_MODULEagent.pydantic_aiPath to the agent module.
AGENT_CLASSagentClass name for the agent.
SECURITY_MODULEagent.pydantic_aiSpecifies the security module for the agent.
SECURITY_CLASSvalidate_tokenClass name for the security depdency.
API_ENDPOINTpydantic-aiAPI endpoint path for the agent.
API_PREFIX/agentsPrefix for all agent-related API endpoints.
API_MODEsimpleChanges how endpoints are registered. openai changes to OpenAI-compatible endpoints.
PORT8080Port the application runs on within the container.

To customize these values, pass them as -e arguments to docker run or define them in an .env file.

Volume Mounting

Agents are expected to be volume-mounted at /app/agent. You can mount your agent directory as follows:

docker run -p 8000:8080 \
  -v $(pwd)/agent:/app/agent \
  ghcr.io/blairhudson/fastapi-agents:pydantic-ai

If a requirements.txt file is present in the mounted directory, it will be automatically installed at container startup.

Building Custom Containers

For production deployments, it is recommended to build your container with dependencies included. Here’s an example Dockerfile starting from one of the pre-built base images:

FROM ghcr.io/blairhudson/fastapi-agents:pydantic-ai

# Copy your agent source code
COPY ./agent /app/agent

# Install dependencies
RUN pip install --no-cache-dir -r /app/agent/requirements.txt

Build and run the custom image:

docker build -t my-custom-agent .
docker run -p 8000:8080 my-custom-agent

This approach ensures all dependencies are baked into the image, improving startup performance and reliability.

πŸ’‘ Examples

Explore real-world examples for implementing FastAPI Agents in different scenarios:

🀝 Contributing

We welcome contributions! To contribute:

  • Fork the repository.
  • Create a feature branch.
  • Add any new tests and ensure they pass. i.e. uv run pytest.
  • Submit a pull request.

For any questions or feature requests including additional agent frameworks, open an issue in the repository.

πŸ“„ Citation

If you use FastAPI Agents in your work, please consider citing it using the metadata in the CITATION.cff file:

DOI

This DOI represents all versions of the project. For version-specific DOIs, refer to the Zenodo project page.

Alternatively, you can use the following BibTeX entry:

@software{fastapi_agents,
  author = {Blair Hudson},
  title = {FastAPI Agents},
  year = {2025},
  version = {0.1},
  doi = {10.5281/zenodo.14635504},
  url = {https://github.com/blairhudson/fastapi-agents},
  orcid = {https://orcid.org/0009-0007-4216-4555},
  abstract = {FastAPI Agents is the ultimate FastAPI extension for integrating AI agents into your applications.}
}

πŸ“œ License

This project is licensed under the MIT License. See the LICENSE file for more details.

Keywords

agents

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts