# Automagik Agents
A collection of AI agents powered by Pydantic AI and exposed through FastAPI endpoints. This project provides a flexible framework for deploying and interacting with different types of AI agents through a RESTful API.
## Features
- **Multiple Agent Support**:
- Simple Agent: Handles basic queries and time-related operations
- Notion Agent: Manages Notion databases and workspaces
- **FastAPI Integration**: RESTful API endpoints for agent interaction
- **Health Monitoring**: Built-in health check endpoint with version tracking
- **Message History**: Maintains conversation context across interactions
- **Structured Responses**: Standardized response format using Pydantic models
- **Security**: API key authentication for protected endpoints
- **CORS Support**: Configurable CORS middleware for cross-origin requests
- **CLI Tools**: Command-line interface for creating new agents and managing the API server
## Technical Architecture
### Core Components
1. **FastAPI Application**
- Health check endpoint (`/health`)
- Agent endpoints (`/agent/{agent_type}/run`)
- Standardized request/response models
2. **Agent Framework**
- Base agent implementation with common functionality
- Specialized agents (Simple, Notion) with specific capabilities
- Message history management
- Tool registration system
3. **Response Models**
- `AgentBaseResponse`: Standard response format
- `HistoryModel`: Message history serialization
- `MessageModel`: Individual message representation
### Dependencies
- `fastapi`: Web framework for building APIs
- `pydantic-ai`: Core AI agent framework
- `notion-client`: Official Notion API client (for Notion agent)
- `uvicorn`: ASGI server for running the API
- `typer`: CLI interface builder
### CLI Commands
The package provides a command-line interface with the following commands:
1. **Create a New Agent**
```bash
automagik-agents create-agent --name your_agent_name
```
This command creates a new agent by cloning the simple agent template and setting up the necessary files.
2. **Start the API Server**
```bash
automagik-agents api start [OPTIONS]
```
Options:
- `--host`, `-h`: Host to bind the server to (overrides AM_HOST from .env)
- `--port`, `-p`: Port to bind the server to (overrides AM_PORT from .env)
- `--reload`: Enable auto-reload on code changes
- `--workers`, `-w`: Number of worker processes
## Usage
1. Set up environment variables:
```bash
# Copy the example environment file
cp .env-example .env
# Edit .env and set your values
AM_API_KEY=your_api_key_here # Required for authentication
NOTION_TOKEN=your_notion_integration_token # Only needed for Notion agent
AM_HOST=0.0.0.0 # Host to bind the server to
AM_PORT=8000 # Port to bind the server to
```
2. Install dependencies:
```bash
uv venv
source .venv/bin/activate ## or .venv\Scripts\activate if on Windows
uv sync
```
3. Create a new agent (optional):
```bash
automagik-agents create-agent --name my_custom_agent
```
4. Start the API server:
```bash
# Start with default settings from .env
automagik-agents api start
# Or start with custom settings
automagik-agents api start --host 127.0.0.1 --port 8080 --reload
```
5. Interact with the agents:
Health Check (no authentication required):
```bash
curl http://localhost:8000/health
```
Simple Agent (requires API key):
```bash
curl -X POST http://localhost:8000/agent/simple/run \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{"message_input": "What time is it?", "context": {}}'
```
Notion Agent (requires API key):
```bash
curl -X POST http://localhost:8000/agent/notion/run \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{"message_input": "List my databases", "context": {}}'
```
## Development
### Agent Implementation
Each agent follows a standard structure:
- Initialization with configuration
- Tool registration
- Message processing
- Response generation
### Response Processing
All agent responses are processed through:
1. Message history management
2. Response serialization
3. Error handling
4. Tool output collection
### Security
The API uses API key authentication for protected endpoints:
- API key must be provided in the `X-API-Key` header
- Key is configured via `AM_API_KEY` environment variable
- Health check endpoint remains public
- Invalid or missing API keys return 401 Unauthorized
## Future Enhancements
- Additional agent types
- Enhanced tool management system
- Authentication and rate limiting
- Response caching
- Batch operation support
Raw data
{
"_id": null,
"home_page": null,
"name": "automagik-agents",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, agents, pydantic, fastapi, notion",
"author": null,
"author_email": "Cezar Vasconcelos <cezar@namastex.ai>",
"download_url": "https://files.pythonhosted.org/packages/5f/85/981bbaf005f1f4247af5db5fba892a3cda15584fb94b32fe1343d8a3aae8/automagik_agents-0.1.2.tar.gz",
"platform": null,
"description": "# Automagik Agents\n\nA collection of AI agents powered by Pydantic AI and exposed through FastAPI endpoints. This project provides a flexible framework for deploying and interacting with different types of AI agents through a RESTful API.\n\n## Features\n\n- **Multiple Agent Support**: \n - Simple Agent: Handles basic queries and time-related operations\n - Notion Agent: Manages Notion databases and workspaces\n- **FastAPI Integration**: RESTful API endpoints for agent interaction\n- **Health Monitoring**: Built-in health check endpoint with version tracking\n- **Message History**: Maintains conversation context across interactions\n- **Structured Responses**: Standardized response format using Pydantic models\n- **Security**: API key authentication for protected endpoints\n- **CORS Support**: Configurable CORS middleware for cross-origin requests\n- **CLI Tools**: Command-line interface for creating new agents and managing the API server\n\n## Technical Architecture\n\n### Core Components\n\n1. **FastAPI Application**\n - Health check endpoint (`/health`)\n - Agent endpoints (`/agent/{agent_type}/run`)\n - Standardized request/response models\n\n2. **Agent Framework**\n - Base agent implementation with common functionality\n - Specialized agents (Simple, Notion) with specific capabilities\n - Message history management\n - Tool registration system\n\n3. **Response Models**\n - `AgentBaseResponse`: Standard response format\n - `HistoryModel`: Message history serialization\n - `MessageModel`: Individual message representation\n\n### Dependencies\n\n- `fastapi`: Web framework for building APIs\n- `pydantic-ai`: Core AI agent framework\n- `notion-client`: Official Notion API client (for Notion agent)\n- `uvicorn`: ASGI server for running the API\n- `typer`: CLI interface builder\n\n### CLI Commands\n\nThe package provides a command-line interface with the following commands:\n\n1. **Create a New Agent**\n ```bash\n automagik-agents create-agent --name your_agent_name\n ```\n This command creates a new agent by cloning the simple agent template and setting up the necessary files.\n\n2. **Start the API Server**\n ```bash\n automagik-agents api start [OPTIONS]\n ```\n Options:\n - `--host`, `-h`: Host to bind the server to (overrides AM_HOST from .env)\n - `--port`, `-p`: Port to bind the server to (overrides AM_PORT from .env)\n - `--reload`: Enable auto-reload on code changes\n - `--workers`, `-w`: Number of worker processes\n\n## Usage\n\n1. Set up environment variables:\n ```bash\n # Copy the example environment file\n cp .env-example .env\n \n # Edit .env and set your values\n AM_API_KEY=your_api_key_here # Required for authentication\n NOTION_TOKEN=your_notion_integration_token # Only needed for Notion agent\n AM_HOST=0.0.0.0 # Host to bind the server to\n AM_PORT=8000 # Port to bind the server to\n ```\n\n2. Install dependencies:\n ```bash\n uv venv\n source .venv/bin/activate ## or .venv\\Scripts\\activate if on Windows\n uv sync\n ```\n\n3. Create a new agent (optional):\n ```bash\n automagik-agents create-agent --name my_custom_agent\n ```\n\n4. Start the API server:\n ```bash\n # Start with default settings from .env\n automagik-agents api start\n\n # Or start with custom settings\n automagik-agents api start --host 127.0.0.1 --port 8080 --reload\n ```\n\n5. Interact with the agents:\n\n Health Check (no authentication required):\n ```bash\n curl http://localhost:8000/health\n ```\n\n Simple Agent (requires API key):\n ```bash\n curl -X POST http://localhost:8000/agent/simple/run \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your_api_key_here\" \\\n -d '{\"message_input\": \"What time is it?\", \"context\": {}}'\n ```\n\n Notion Agent (requires API key):\n ```bash\n curl -X POST http://localhost:8000/agent/notion/run \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your_api_key_here\" \\\n -d '{\"message_input\": \"List my databases\", \"context\": {}}'\n ```\n\n## Development\n\n### Agent Implementation\n\nEach agent follows a standard structure:\n- Initialization with configuration\n- Tool registration\n- Message processing\n- Response generation\n\n### Response Processing\n\nAll agent responses are processed through:\n1. Message history management\n2. Response serialization\n3. Error handling\n4. Tool output collection\n\n### Security\n\nThe API uses API key authentication for protected endpoints:\n- API key must be provided in the `X-API-Key` header\n- Key is configured via `AM_API_KEY` environment variable\n- Health check endpoint remains public\n- Invalid or missing API keys return 401 Unauthorized\n\n## Future Enhancements\n\n- Additional agent types\n- Enhanced tool management system\n- Authentication and rate limiting\n- Response caching\n- Batch operation support\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automagik agents templates",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/namastexlabs/automagik-agents",
"Issues": "https://github.com/namastexlabs/automagik-agents/issues",
"Repository": "https://github.com/namastexlabs/automagik-agents"
},
"split_keywords": [
"ai",
" agents",
" pydantic",
" fastapi",
" notion"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ed390d467de3ee1c162769b004a603687c1cd13f1aff3711050ba5359329889f",
"md5": "8eec6c836e1b44aeaa57a212033bbf67",
"sha256": "f9339391505db32e0a0511d265a50cdbc600fdf6e95977f85d6e5ab7a664418f"
},
"downloads": -1,
"filename": "automagik_agents-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8eec6c836e1b44aeaa57a212033bbf67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10875,
"upload_time": "2025-02-23T03:04:41",
"upload_time_iso_8601": "2025-02-23T03:04:41.138457Z",
"url": "https://files.pythonhosted.org/packages/ed/39/0d467de3ee1c162769b004a603687c1cd13f1aff3711050ba5359329889f/automagik_agents-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5f85981bbaf005f1f4247af5db5fba892a3cda15584fb94b32fe1343d8a3aae8",
"md5": "eac2d9960c7d9504dc0a0b41ff94c55b",
"sha256": "efdb44e69c4db9c6c38bc125865530ea5222265cd69e05bb116581567fb4f9fd"
},
"downloads": -1,
"filename": "automagik_agents-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "eac2d9960c7d9504dc0a0b41ff94c55b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 9499,
"upload_time": "2025-02-23T03:04:42",
"upload_time_iso_8601": "2025-02-23T03:04:42.454494Z",
"url": "https://files.pythonhosted.org/packages/5f/85/981bbaf005f1f4247af5db5fba892a3cda15584fb94b32fe1343d8a3aae8/automagik_agents-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-23 03:04:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "namastexlabs",
"github_project": "automagik-agents",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "automagik-agents"
}
JSON
