# FastAPI AgentRouter
[](https://github.com/chanyou0311/fastapi-agentrouter/actions/workflows/ci.yml)
[](https://badge.fury.io/py/fastapi-agentrouter)
[](https://pypi.org/project/fastapi-agentrouter/)
[](https://hub.docker.com/r/chanyou0311/fastapi-agentrouter)
[](https://opensource.org/licenses/MIT)
Simplified AI Agent integration for FastAPI with Slack support.
## Features
- 🚀 **Simple Integration** - Just 2 lines to add agent to your FastAPI app
- 🤖 **Vertex AI Support** - Native support for Google's Vertex AI Agent Builder
- 💬 **Slack Integration** - Built-in Slack Bolt integration
- 🎯 **Protocol-Based** - Works with any agent implementing the `AgentProtocol`
- ⚡ **Async & Streaming** - Full async support with streaming responses
- 🧩 **Dependency Injection** - Leverage FastAPI's DI system
- 📁 **Modular Architecture** - Clean separation of concerns
## Installation
```bash
# Basic installation
pip install fastapi-agentrouter
# With Slack support
pip install "fastapi-agentrouter[slack]"
# With Vertex AI ADK support
pip install "fastapi-agentrouter[vertexai]"
# All extras
pip install "fastapi-agentrouter[all]"
```
## Quick Start
### With Vertex AI Agent Builder
```python
from fastapi import FastAPI
import fastapi_agentrouter
app = FastAPI()
# Two-line integration!
app.dependency_overrides[fastapi_agentrouter.get_agent] = (
fastapi_agentrouter.get_vertex_ai_agent_engine
)
app.include_router(fastapi_agentrouter.router)
```
### With Custom Agent Implementation
```python
from fastapi import FastAPI
from fastapi_agentrouter import router, get_agent, AgentProtocol
# Your agent implementation
class MyAgent:
def create_session(self, *, user_id=None, **kwargs):
return {"id": "session-123"}
def list_sessions(self, *, user_id=None, **kwargs):
return {"sessions": []}
def stream_query(self, *, message: str, user_id=None, session_id=None, **kwargs):
# Process the message and yield responses
yield {"content": f"Response to: {message}"}
app = FastAPI()
# Two-line integration!
app.dependency_overrides[get_agent] = lambda: MyAgent()
app.include_router(router)
```
That's it! Your agent is now available at:
- `/agent/slack/events` - Handle all Slack events and interactions (when Slack is configured)
## Configuration
### Vertex AI Configuration
When using Vertex AI Agent Builder, configure these environment variables:
```bash
# Required for Vertex AI
export VERTEXAI__PROJECT_ID="your-project-id"
export VERTEXAI__LOCATION="us-central1"
export VERTEXAI__STAGING_BUCKET="your-staging-bucket"
export VERTEXAI__AGENT_NAME="your-agent-name"
```
The library automatically warms up the agent engine during router initialization to ensure fast response times.
### Slack Configuration
To enable Slack integration, set these environment variables:
```bash
# Required for Slack integration
export SLACK__BOT_TOKEN="xoxb-your-bot-token"
export SLACK__SIGNING_SECRET="your-signing-secret"
```
Note: Slack integration is only enabled when both `SLACK__BOT_TOKEN` and `SLACK__SIGNING_SECRET` are configured. If not set, Slack endpoints will return 404.
### Slack Setup
1. Create a Slack App at https://api.slack.com/apps
2. Get your Bot Token and Signing Secret from Basic Information
3. Set environment variables:
```bash
export SLACK__BOT_TOKEN="xoxb-your-bot-token"
export SLACK__SIGNING_SECRET="your-signing-secret"
```
4. Configure Event Subscriptions URL: `https://your-domain.com/agent/slack/events`
5. Subscribe to bot events:
- `app_mention` - When your bot is mentioned
- `message.im` - Direct messages to your bot (optional)
6. For interactive components and slash commands, use the same URL: `https://your-domain.com/agent/slack/events`
## Agent Protocol
Your agent must implement the `AgentProtocol` interface with these methods:
```python
from typing import Any, Generator
class AgentProtocol:
def create_session(
self,
*,
user_id: str | None = None,
**kwargs: Any,
) -> dict[str, Any]:
"""Create a new session for the agent.
Returns a dictionary containing at least the session 'id'.
"""
...
def list_sessions(
self,
*,
user_id: str | None = None,
**kwargs: Any,
) -> dict[str, Any]:
"""List sessions for a given user.
Returns a dictionary with a 'sessions' key containing a list of
session dictionaries.
"""
...
def stream_query(
self,
*,
message: str,
user_id: str | None = None,
session_id: str | None = None,
**kwargs: Any
) -> Generator[dict[str, Any], Any, None]:
"""Stream responses from the agent."""
...
```
The `stream_query` method should yield response events as dictionaries.
## API Reference
### Core Components
#### `fastapi_agentrouter.router`
Pre-configured APIRouter with automatic agent integration:
- `/agent/slack/events` - Slack event handler (when Slack is configured)
#### `fastapi_agentrouter.get_agent`
Dependency function that should be overridden with your agent:
```python
app.dependency_overrides[fastapi_agentrouter.get_agent] = your_get_agent_function
```
#### `fastapi_agentrouter.get_vertex_ai_agent_engine`
Pre-configured function to get Vertex AI Agent Engine:
```python
app.dependency_overrides[fastapi_agentrouter.get_agent] = (
fastapi_agentrouter.get_vertex_ai_agent_engine
)
```
#### `fastapi_agentrouter.AgentProtocol`
Protocol class that defines the interface for agents.
#### `fastapi_agentrouter.Settings`
Pydantic settings class for configuration management.
### Environment Variables
The library uses [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) for configuration management:
**Slack Configuration:**
- `SLACK__BOT_TOKEN` - Slack Bot User OAuth Token
- `SLACK__SIGNING_SECRET` - Slack Signing Secret
**Vertex AI Configuration:**
- `VERTEXAI__PROJECT_ID` - GCP Project ID
- `VERTEXAI__LOCATION` - GCP Location (e.g., us-central1)
- `VERTEXAI__STAGING_BUCKET` - GCS Bucket for staging
- `VERTEXAI__AGENT_NAME` - Display name of the Vertex AI Agent
## Examples
See the [examples](examples/) directory for complete examples:
- [basic_usage.py](examples/basic_usage.py) - Basic Vertex AI integration example
## Docker
Docker images are available on [Docker Hub](https://hub.docker.com/r/chanyou0311/fastapi-agentrouter):
```bash
# Pull the latest image
docker pull chanyou0311/fastapi-agentrouter:latest
# Run with environment variables
docker run -p 8000:8000 \
-e VERTEXAI__PROJECT_ID=your-project-id \
-e VERTEXAI__LOCATION=us-central1 \
-e VERTEXAI__STAGING_BUCKET=your-bucket \
-e VERTEXAI__AGENT_NAME=your-agent-name \
chanyou0311/fastapi-agentrouter:latest
```
## Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/chanyou0311/fastapi-agentrouter.git
cd fastapi-agentrouter
# Install with uv (recommended)
uv sync --all-extras --dev
# Or with pip
pip install -e ".[all,dev,docs]"
# Install pre-commit hooks
pre-commit install
```
### Run Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=src --cov-report=html
# Run specific tests
pytest tests/test_router.py
```
### Build Documentation
```bash
# Serve docs locally
mkdocs serve
# Build docs
mkdocs build
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- [Documentation](https://chanyou0311.github.io/fastapi-agentrouter)
- [PyPI Package](https://pypi.org/project/fastapi-agentrouter)
- [Docker Hub](https://hub.docker.com/r/chanyou0311/fastapi-agentrouter)
- [GitHub Repository](https://github.com/chanyou0311/fastapi-agentrouter)
- [Issue Tracker](https://github.com/chanyou0311/fastapi-agentrouter/issues)
Raw data
{
"_id": null,
"home_page": null,
"name": "fastapi-agentrouter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agent, ai, discord, fastapi, slack, webhook",
"author": null,
"author_email": "Yu Nakamura <chanyou0311@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8d/90/4331f51275290bb0e8bd4f2f856cd59b0760bea2eb6d90215138bb9e98f2/fastapi_agentrouter-0.6.1.tar.gz",
"platform": null,
"description": "# FastAPI AgentRouter\n\n[](https://github.com/chanyou0311/fastapi-agentrouter/actions/workflows/ci.yml)\n[](https://badge.fury.io/py/fastapi-agentrouter)\n[](https://pypi.org/project/fastapi-agentrouter/)\n[](https://hub.docker.com/r/chanyou0311/fastapi-agentrouter)\n[](https://opensource.org/licenses/MIT)\n\nSimplified AI Agent integration for FastAPI with Slack support.\n\n## Features\n\n- \ud83d\ude80 **Simple Integration** - Just 2 lines to add agent to your FastAPI app\n- \ud83e\udd16 **Vertex AI Support** - Native support for Google's Vertex AI Agent Builder\n- \ud83d\udcac **Slack Integration** - Built-in Slack Bolt integration\n- \ud83c\udfaf **Protocol-Based** - Works with any agent implementing the `AgentProtocol`\n- \u26a1 **Async & Streaming** - Full async support with streaming responses\n- \ud83e\udde9 **Dependency Injection** - Leverage FastAPI's DI system\n- \ud83d\udcc1 **Modular Architecture** - Clean separation of concerns\n\n## Installation\n\n```bash\n# Basic installation\npip install fastapi-agentrouter\n\n# With Slack support\npip install \"fastapi-agentrouter[slack]\"\n\n# With Vertex AI ADK support\npip install \"fastapi-agentrouter[vertexai]\"\n\n# All extras\npip install \"fastapi-agentrouter[all]\"\n```\n\n## Quick Start\n\n### With Vertex AI Agent Builder\n\n```python\nfrom fastapi import FastAPI\nimport fastapi_agentrouter\n\napp = FastAPI()\n\n# Two-line integration!\napp.dependency_overrides[fastapi_agentrouter.get_agent] = (\n fastapi_agentrouter.get_vertex_ai_agent_engine\n)\napp.include_router(fastapi_agentrouter.router)\n```\n\n### With Custom Agent Implementation\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi_agentrouter import router, get_agent, AgentProtocol\n\n# Your agent implementation\nclass MyAgent:\n def create_session(self, *, user_id=None, **kwargs):\n return {\"id\": \"session-123\"}\n\n def list_sessions(self, *, user_id=None, **kwargs):\n return {\"sessions\": []}\n\n def stream_query(self, *, message: str, user_id=None, session_id=None, **kwargs):\n # Process the message and yield responses\n yield {\"content\": f\"Response to: {message}\"}\n\napp = FastAPI()\n\n# Two-line integration!\napp.dependency_overrides[get_agent] = lambda: MyAgent()\napp.include_router(router)\n```\n\nThat's it! Your agent is now available at:\n- `/agent/slack/events` - Handle all Slack events and interactions (when Slack is configured)\n\n## Configuration\n\n### Vertex AI Configuration\n\nWhen using Vertex AI Agent Builder, configure these environment variables:\n\n```bash\n# Required for Vertex AI\nexport VERTEXAI__PROJECT_ID=\"your-project-id\"\nexport VERTEXAI__LOCATION=\"us-central1\"\nexport VERTEXAI__STAGING_BUCKET=\"your-staging-bucket\"\nexport VERTEXAI__AGENT_NAME=\"your-agent-name\"\n```\n\nThe library automatically warms up the agent engine during router initialization to ensure fast response times.\n\n### Slack Configuration\n\nTo enable Slack integration, set these environment variables:\n\n```bash\n# Required for Slack integration\nexport SLACK__BOT_TOKEN=\"xoxb-your-bot-token\"\nexport SLACK__SIGNING_SECRET=\"your-signing-secret\"\n```\n\nNote: Slack integration is only enabled when both `SLACK__BOT_TOKEN` and `SLACK__SIGNING_SECRET` are configured. If not set, Slack endpoints will return 404.\n\n### Slack Setup\n\n1. Create a Slack App at https://api.slack.com/apps\n2. Get your Bot Token and Signing Secret from Basic Information\n3. Set environment variables:\n ```bash\n export SLACK__BOT_TOKEN=\"xoxb-your-bot-token\"\n export SLACK__SIGNING_SECRET=\"your-signing-secret\"\n ```\n4. Configure Event Subscriptions URL: `https://your-domain.com/agent/slack/events`\n5. Subscribe to bot events:\n - `app_mention` - When your bot is mentioned\n - `message.im` - Direct messages to your bot (optional)\n6. For interactive components and slash commands, use the same URL: `https://your-domain.com/agent/slack/events`\n\n## Agent Protocol\n\nYour agent must implement the `AgentProtocol` interface with these methods:\n\n```python\nfrom typing import Any, Generator\n\nclass AgentProtocol:\n def create_session(\n self,\n *,\n user_id: str | None = None,\n **kwargs: Any,\n ) -> dict[str, Any]:\n \"\"\"Create a new session for the agent.\n\n Returns a dictionary containing at least the session 'id'.\n \"\"\"\n ...\n\n def list_sessions(\n self,\n *,\n user_id: str | None = None,\n **kwargs: Any,\n ) -> dict[str, Any]:\n \"\"\"List sessions for a given user.\n\n Returns a dictionary with a 'sessions' key containing a list of\n session dictionaries.\n \"\"\"\n ...\n\n def stream_query(\n self,\n *,\n message: str,\n user_id: str | None = None,\n session_id: str | None = None,\n **kwargs: Any\n ) -> Generator[dict[str, Any], Any, None]:\n \"\"\"Stream responses from the agent.\"\"\"\n ...\n```\n\nThe `stream_query` method should yield response events as dictionaries.\n\n## API Reference\n\n### Core Components\n\n#### `fastapi_agentrouter.router`\n\nPre-configured APIRouter with automatic agent integration:\n- `/agent/slack/events` - Slack event handler (when Slack is configured)\n\n#### `fastapi_agentrouter.get_agent`\n\nDependency function that should be overridden with your agent:\n```python\napp.dependency_overrides[fastapi_agentrouter.get_agent] = your_get_agent_function\n```\n\n#### `fastapi_agentrouter.get_vertex_ai_agent_engine`\n\nPre-configured function to get Vertex AI Agent Engine:\n```python\napp.dependency_overrides[fastapi_agentrouter.get_agent] = (\n fastapi_agentrouter.get_vertex_ai_agent_engine\n)\n```\n\n#### `fastapi_agentrouter.AgentProtocol`\n\nProtocol class that defines the interface for agents.\n\n#### `fastapi_agentrouter.Settings`\n\nPydantic settings class for configuration management.\n\n### Environment Variables\n\nThe library uses [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) for configuration management:\n\n**Slack Configuration:**\n- `SLACK__BOT_TOKEN` - Slack Bot User OAuth Token\n- `SLACK__SIGNING_SECRET` - Slack Signing Secret\n\n**Vertex AI Configuration:**\n- `VERTEXAI__PROJECT_ID` - GCP Project ID\n- `VERTEXAI__LOCATION` - GCP Location (e.g., us-central1)\n- `VERTEXAI__STAGING_BUCKET` - GCS Bucket for staging\n- `VERTEXAI__AGENT_NAME` - Display name of the Vertex AI Agent\n\n## Examples\n\nSee the [examples](examples/) directory for complete examples:\n- [basic_usage.py](examples/basic_usage.py) - Basic Vertex AI integration example\n\n## Docker\n\nDocker images are available on [Docker Hub](https://hub.docker.com/r/chanyou0311/fastapi-agentrouter):\n\n```bash\n# Pull the latest image\ndocker pull chanyou0311/fastapi-agentrouter:latest\n\n# Run with environment variables\ndocker run -p 8000:8000 \\\n -e VERTEXAI__PROJECT_ID=your-project-id \\\n -e VERTEXAI__LOCATION=us-central1 \\\n -e VERTEXAI__STAGING_BUCKET=your-bucket \\\n -e VERTEXAI__AGENT_NAME=your-agent-name \\\n chanyou0311/fastapi-agentrouter:latest\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/chanyou0311/fastapi-agentrouter.git\ncd fastapi-agentrouter\n\n# Install with uv (recommended)\nuv sync --all-extras --dev\n\n# Or with pip\npip install -e \".[all,dev,docs]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Run Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=src --cov-report=html\n\n# Run specific tests\npytest tests/test_router.py\n```\n\n### Build Documentation\n\n```bash\n# Serve docs locally\nmkdocs serve\n\n# Build docs\nmkdocs build\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [Documentation](https://chanyou0311.github.io/fastapi-agentrouter)\n- [PyPI Package](https://pypi.org/project/fastapi-agentrouter)\n- [Docker Hub](https://hub.docker.com/r/chanyou0311/fastapi-agentrouter)\n- [GitHub Repository](https://github.com/chanyou0311/fastapi-agentrouter)\n- [Issue Tracker](https://github.com/chanyou0311/fastapi-agentrouter/issues)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI Agent interface library for FastAPI with multi-platform support",
"version": "0.6.1",
"project_urls": {
"Bug Tracker": "https://github.com/chanyou0311/fastapi-agentrouter/issues",
"Changelog": "https://github.com/chanyou0311/fastapi-agentrouter/releases",
"Documentation": "https://chanyou0311.github.io/fastapi-agentrouter",
"Homepage": "https://github.com/chanyou0311/fastapi-agentrouter",
"Repository": "https://github.com/chanyou0311/fastapi-agentrouter"
},
"split_keywords": [
"agent",
" ai",
" discord",
" fastapi",
" slack",
" webhook"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "127e5ead231c54f46b9b03fc36aea6fbc207df42b7368bd9aa2a0bcf98fc7fb4",
"md5": "058fc5cacf01b48827daab4f13410424",
"sha256": "896b705383f47befae1028d56ab591ee1dbe9ec83e9de1f1e49bce1d361fd39a"
},
"downloads": -1,
"filename": "fastapi_agentrouter-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "058fc5cacf01b48827daab4f13410424",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13859,
"upload_time": "2025-08-19T16:19:46",
"upload_time_iso_8601": "2025-08-19T16:19:46.437694Z",
"url": "https://files.pythonhosted.org/packages/12/7e/5ead231c54f46b9b03fc36aea6fbc207df42b7368bd9aa2a0bcf98fc7fb4/fastapi_agentrouter-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8d904331f51275290bb0e8bd4f2f856cd59b0760bea2eb6d90215138bb9e98f2",
"md5": "cbe0ad018d14b6ec90a82823f8c86c28",
"sha256": "daee3f903c9dd587b677872f49420b772b40f5c327640efa23ba5b714dba3844"
},
"downloads": -1,
"filename": "fastapi_agentrouter-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "cbe0ad018d14b6ec90a82823f8c86c28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 17620,
"upload_time": "2025-08-19T16:19:47",
"upload_time_iso_8601": "2025-08-19T16:19:47.498723Z",
"url": "https://files.pythonhosted.org/packages/8d/90/4331f51275290bb0e8bd4f2f856cd59b0760bea2eb6d90215138bb9e98f2/fastapi_agentrouter-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 16:19:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chanyou0311",
"github_project": "fastapi-agentrouter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fastapi-agentrouter"
}
JSON
