<p align="center">
<img src=".github/images/automagik_logo.png" alt="AutoMagik Logo" width="600"/>
</p>
## 🚀 AI Agents from Ideas to Production in Minutes
Automagik Agents is a powerful deployment layer over Pydantic AI that accelerates your AI agent development from concept to production. Born from our daily work at Namastex Labs, it provides a reliable, tested foundation for rapidly building, deploying, and managing AI agents with advanced capabilities like persistent memory and tool integration.
We built Automagik because we needed to save time while creating high-quality, production-ready agents. By focusing on standardized patterns, best practices, and reusable components, Automagik lets you create sophisticated AI assistants in minutes instead of days.
## ⚠️ **Important: Requires API Keys**
Agents need LLM provider keys to function. Examples: `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ANTHROPIC_API_KEY`. Get them from [OpenAI](https://platform.openai.com/api-keys), [Google AI Studio](https://makersuite.google.com/app/apikey), or [Anthropic](https://console.anthropic.com/).
## 🌟 What Makes Automagik Special
- **🤖 Extensible Agent System**: Template-based creation, automatic tool registration, and easy CLI for new agents
- **💾 Advanced Memory System**: Persistent conversations with dynamic `{{variable}}` templating that automatically injects context
- **🔧 Production-Ready API**: FastAPI endpoints with authentication, session management, and health monitoring
- **🧠 Knowledge Graph Integration**: Built-in Neo4j/Graphiti support for semantic understanding and complex reasoning
- **🔗 Multiple LLM Support**: Works with OpenAI, Gemini, Claude, Groq, and more - switch providers easily
- **📦 Zero-Config Deployment**: Docker and local installation with automated dependency management
## 🚀 Quick Start
```bash
git clone https://github.com/namastexlabs/automagik-agents.git
cd automagik-agents
# Show all available commands
make help
# Quick installation and startup
make install-dev # Install development environment
make dev # Start development mode
# Check status and logs
make status # PM2-style status of all instances
make logs # View colorized logs
```
**Auto-Install Prerequisites:**
```bash
# Install system dependencies (all platforms)
make install-prerequisites
# Quick environment setup
make install # Auto-detects best installation mode
```
**Installation Modes:**
```bash
# Development (local Python + venv)
make install-dev
# Docker development
make install-docker
# Production Docker
make install-prod
# Systemd service
make install-service
```
## 📦 Pip Installation
You can also install Automagik as a Python package:
```bash
# Install from local directory
pip install -e /path/to/automagik-agents
# Or from git (coming soon)
# pip install git+https://github.com/namastexlabs/automagik-agents.git
```
**After pip installation:**
```bash
# Start server with default settings
automagik-server
# Start on custom port
automagik-server --port 38881
# Specify external agents directory
automagik-server --agents-dir /path/to/my/agents
# Or use environment variables
export AUTOMAGIK_API_PORT=38881
export AUTOMAGIK_EXTERNAL_AGENTS_DIR=/path/to/my/agents
automagik-server
```
**Default External Agents Directory:** `./automagik_agents`
This is where you can place custom agents that will be automatically discovered when the server starts. The directory is created relative to your current working directory. Each agent should be in its own subdirectory with an `agent.py` file containing a `create_agent` factory function.
**Creating an External Agent:**
```python
# ./automagik_agents/my_custom_agent/agent.py
from typing import Dict, Optional
from automagik.agents.models.automagik_agent import AutomagikAgent
from automagik.agents.models.dependencies import AutomagikAgentsDependencies
def create_agent(config: Optional[Dict[str, str]] = None) -> AutomagikAgent:
"""Factory function to create your custom agent."""
return MyCustomAgent(config or {})
class MyCustomAgent(AutomagikAgent):
def __init__(self, config: Dict[str, str]):
super().__init__(config)
self._code_prompt_text = "Your agent prompt here"
self.dependencies = AutomagikAgentsDependencies(
model_name=config.get("model", "openai:gpt-4o-mini"),
model_settings={},
api_keys={},
tool_config={}
)
self.tool_registry.register_default_tools(self.context)
@property
def model_name(self) -> str:
return self.dependencies.model_name or "openai:gpt-4o-mini"
```
## 📝 Post-Installation
1. **Add your API keys:**
```bash
nano .env
# Add: OPENAI_API_KEY=sk-your-actual-key
# Default API Key: namastex888 (unless AUTOMAGIK_API_KEY is set)
```
2. **Start and monitor:**
```bash
make dev # Start development mode
make status # Show PM2-style status table
make logs-f # Follow logs in real-time
```
3. **Test it:**
```bash
curl http://localhost:${AUTOMAGIK_API_PORT}/health
```
## 🎯 Usage
### Make Commands
```bash
# 🚀 Quick Start
make help # Show all available commands
make install-dev # Install development environment
make dev # Start development mode
# 📊 Monitoring & Status
make status # PM2-style status table of all instances
make status-quick # Quick one-line status summary
make health # Check health of all services
make logs # View colorized logs (auto-detect source)
make logs-f # Follow logs in real-time
# 🎛️ Service Management
make start # Start services (auto-detect mode)
make stop # Stop all services
make restart # Restart services
make docker # Start Docker development stack
make prod # Start production Docker stack
# 🗄️ Database
make db-init # Initialize database
make db-migrate # Run database migrations
# 🛠️ Development
make test # Run test suite
make lint # Run code linting
make format # Format code with ruff
```
**Force Mode for Conflicts:**
```bash
make dev FORCE=1 # Stop existing services and start dev
make docker FORCE=1 # Force start Docker stack
```
### API Examples
```bash
# Test agent (using default API key)
curl -X POST http://localhost:${AUTOMAGIK_API_PORT}/api/v1/agent/simple/run \
-H "X-API-Key: namastex888" \
-H "Content-Type: application/json" \
-d '{"message_content": "Hello!", "session_name": "test"}'
# Create memory that auto-injects into prompts
curl -X POST http://localhost:${AUTOMAGIK_API_PORT}/api/v1/memories \
-H "X-API-Key: namastex888" \
-H "Content-Type: application/json" \
-d '{"name": "personality", "content": "friendly and helpful", "agent_id": 1}'
```
## Useful Endpoints
* **API Docs:** `http://localhost:${AUTOMAGIK_API_PORT}/docs`
* **Health Check:** `http://localhost:${AUTOMAGIK_API_PORT}/health`
* **List Agents:** `http://localhost:${AUTOMAGIK_API_PORT}/api/v1/agents`
## 🛠️ Create Custom Agents
```bash
# Create new agent
make create-agent name=my_agent type=simple
# Or use CLI
automagik agents create -n my_agent -t simple
# Customize: src/agents/simple/my_agent/
```
## 🔧 Configuration
Edit `.env` with your keys:
```bash
# LLM Providers (choose one or more)
OPENAI_API_KEY=sk-your-key
GEMINI_API_KEY=your-key
ANTHROPIC_API_KEY=your-key
# Platform Integrations (optional)
DISCORD_BOT_TOKEN=your-token
NOTION_TOKEN=your-token
```
## 🗺️ Roadmap
- **Graph Agents**: Advanced agent orchestration and workflows
- **Heartbeat Mode**: Keep agents alive 24/7 doing autonomous tasks
- **MCP Integration**: Model Context Protocol for easier tool reusing
- **Support for Other Agent Frameworks**: Expand compatibility beyond Pydantic AI
- **Smart Context Management**: Optimal handling of large context windows
## 📄 License
MIT License - see [LICENSE](LICENSE) file.
---
<p align="center">
<b>Part of the AutoMagik Ecosystem</b><br>
<a href="https://github.com/namastexlabs/automagik">AutoMagik</a> |
<a href="https://github.com/namastexlabs/automagik-agents">AutoMagik Agents</a> |
<a href="https://github.com/namastexlabs/automagik-ui">AutoMagik UI</a>
</p>
**Automagik Agents is and will always be open source.** Since this is our daily work tool at Namastex Labs, we provide high priority maintenance and regular updates. We built this because we believe AI agent development should be fast, reliable, and production-ready from day one.
Raw data
{
"_id": null,
"home_page": null,
"name": "automagik",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.12",
"maintainer_email": null,
"keywords": "ai, agents, pydantic, fastapi, agno, generative-ai, langgraph, memory",
"author": null,
"author_email": "Felipe Rosa <felipe@namastex.ai>, Cezar Vasconcelos <cezar@namastex.ai>",
"download_url": "https://files.pythonhosted.org/packages/21/43/503e0cee90d8e5950a4dfd06802de819d0a781813ebd0b78ad832533f4d8/automagik-0.5.6.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\".github/images/automagik_logo.png\" alt=\"AutoMagik Logo\" width=\"600\"/>\n</p>\n\n## \ud83d\ude80 AI Agents from Ideas to Production in Minutes\n\nAutomagik Agents is a powerful deployment layer over Pydantic AI that accelerates your AI agent development from concept to production. Born from our daily work at Namastex Labs, it provides a reliable, tested foundation for rapidly building, deploying, and managing AI agents with advanced capabilities like persistent memory and tool integration.\n\nWe built Automagik because we needed to save time while creating high-quality, production-ready agents. By focusing on standardized patterns, best practices, and reusable components, Automagik lets you create sophisticated AI assistants in minutes instead of days.\n\n## \u26a0\ufe0f **Important: Requires API Keys**\n\nAgents need LLM provider keys to function. Examples: `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ANTHROPIC_API_KEY`. Get them from [OpenAI](https://platform.openai.com/api-keys), [Google AI Studio](https://makersuite.google.com/app/apikey), or [Anthropic](https://console.anthropic.com/).\n\n## \ud83c\udf1f What Makes Automagik Special\n\n- **\ud83e\udd16 Extensible Agent System**: Template-based creation, automatic tool registration, and easy CLI for new agents\n- **\ud83d\udcbe Advanced Memory System**: Persistent conversations with dynamic `{{variable}}` templating that automatically injects context\n- **\ud83d\udd27 Production-Ready API**: FastAPI endpoints with authentication, session management, and health monitoring\n- **\ud83e\udde0 Knowledge Graph Integration**: Built-in Neo4j/Graphiti support for semantic understanding and complex reasoning\n- **\ud83d\udd17 Multiple LLM Support**: Works with OpenAI, Gemini, Claude, Groq, and more - switch providers easily\n- **\ud83d\udce6 Zero-Config Deployment**: Docker and local installation with automated dependency management\n\n## \ud83d\ude80 Quick Start\n\n```bash\ngit clone https://github.com/namastexlabs/automagik-agents.git\ncd automagik-agents\n\n# Show all available commands\nmake help\n\n# Quick installation and startup\nmake install-dev # Install development environment\nmake dev # Start development mode\n\n# Check status and logs\nmake status # PM2-style status of all instances\nmake logs # View colorized logs\n```\n\n**Auto-Install Prerequisites:**\n```bash\n# Install system dependencies (all platforms)\nmake install-prerequisites\n\n# Quick environment setup\nmake install # Auto-detects best installation mode\n```\n\n**Installation Modes:**\n```bash\n# Development (local Python + venv)\nmake install-dev\n\n# Docker development\nmake install-docker\n\n# Production Docker\nmake install-prod\n\n# Systemd service\nmake install-service\n```\n\n## \ud83d\udce6 Pip Installation\n\nYou can also install Automagik as a Python package:\n\n```bash\n# Install from local directory\npip install -e /path/to/automagik-agents\n\n# Or from git (coming soon)\n# pip install git+https://github.com/namastexlabs/automagik-agents.git\n```\n\n**After pip installation:**\n```bash\n# Start server with default settings\nautomagik-server\n\n# Start on custom port\nautomagik-server --port 38881\n\n# Specify external agents directory\nautomagik-server --agents-dir /path/to/my/agents\n\n# Or use environment variables\nexport AUTOMAGIK_API_PORT=38881\nexport AUTOMAGIK_EXTERNAL_AGENTS_DIR=/path/to/my/agents\nautomagik-server\n```\n\n**Default External Agents Directory:** `./automagik_agents`\n\nThis is where you can place custom agents that will be automatically discovered when the server starts. The directory is created relative to your current working directory. Each agent should be in its own subdirectory with an `agent.py` file containing a `create_agent` factory function.\n\n**Creating an External Agent:**\n```python\n# ./automagik_agents/my_custom_agent/agent.py\nfrom typing import Dict, Optional\nfrom automagik.agents.models.automagik_agent import AutomagikAgent\nfrom automagik.agents.models.dependencies import AutomagikAgentsDependencies\n\ndef create_agent(config: Optional[Dict[str, str]] = None) -> AutomagikAgent:\n \"\"\"Factory function to create your custom agent.\"\"\"\n return MyCustomAgent(config or {})\n\nclass MyCustomAgent(AutomagikAgent):\n def __init__(self, config: Dict[str, str]):\n super().__init__(config)\n self._code_prompt_text = \"Your agent prompt here\"\n self.dependencies = AutomagikAgentsDependencies(\n model_name=config.get(\"model\", \"openai:gpt-4o-mini\"),\n model_settings={},\n api_keys={},\n tool_config={}\n )\n self.tool_registry.register_default_tools(self.context)\n \n @property\n def model_name(self) -> str:\n return self.dependencies.model_name or \"openai:gpt-4o-mini\"\n```\n\n## \ud83d\udcdd Post-Installation\n\n1. **Add your API keys:**\n```bash\nnano .env\n# Add: OPENAI_API_KEY=sk-your-actual-key\n# Default API Key: namastex888 (unless AUTOMAGIK_API_KEY is set)\n```\n\n2. **Start and monitor:**\n```bash\nmake dev # Start development mode\nmake status # Show PM2-style status table\nmake logs-f # Follow logs in real-time\n```\n\n3. **Test it:**\n```bash\ncurl http://localhost:${AUTOMAGIK_API_PORT}/health\n```\n\n## \ud83c\udfaf Usage\n\n### Make Commands\n\n```bash\n# \ud83d\ude80 Quick Start\nmake help # Show all available commands\nmake install-dev # Install development environment \nmake dev # Start development mode\n\n# \ud83d\udcca Monitoring & Status\nmake status # PM2-style status table of all instances\nmake status-quick # Quick one-line status summary\nmake health # Check health of all services\nmake logs # View colorized logs (auto-detect source)\nmake logs-f # Follow logs in real-time\n\n# \ud83c\udf9b\ufe0f Service Management \nmake start # Start services (auto-detect mode)\nmake stop # Stop all services\nmake restart # Restart services\nmake docker # Start Docker development stack\nmake prod # Start production Docker stack\n\n# \ud83d\uddc4\ufe0f Database\nmake db-init # Initialize database\nmake db-migrate # Run database migrations\n\n# \ud83d\udee0\ufe0f Development\nmake test # Run test suite\nmake lint # Run code linting\nmake format # Format code with ruff\n```\n\n**Force Mode for Conflicts:**\n```bash\nmake dev FORCE=1 # Stop existing services and start dev\nmake docker FORCE=1 # Force start Docker stack\n```\n\n### API Examples\n```bash\n# Test agent (using default API key)\ncurl -X POST http://localhost:${AUTOMAGIK_API_PORT}/api/v1/agent/simple/run \\\n -H \"X-API-Key: namastex888\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"message_content\": \"Hello!\", \"session_name\": \"test\"}'\n\n# Create memory that auto-injects into prompts\ncurl -X POST http://localhost:${AUTOMAGIK_API_PORT}/api/v1/memories \\\n -H \"X-API-Key: namastex888\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"personality\", \"content\": \"friendly and helpful\", \"agent_id\": 1}'\n```\n\n## Useful Endpoints\n\n* **API Docs:** `http://localhost:${AUTOMAGIK_API_PORT}/docs`\n* **Health Check:** `http://localhost:${AUTOMAGIK_API_PORT}/health`\n* **List Agents:** `http://localhost:${AUTOMAGIK_API_PORT}/api/v1/agents`\n\n## \ud83d\udee0\ufe0f Create Custom Agents\n\n```bash\n# Create new agent\nmake create-agent name=my_agent type=simple\n\n# Or use CLI\nautomagik agents create -n my_agent -t simple\n# Customize: src/agents/simple/my_agent/\n```\n\n## \ud83d\udd27 Configuration\n\nEdit `.env` with your keys:\n```bash\n# LLM Providers (choose one or more)\nOPENAI_API_KEY=sk-your-key\nGEMINI_API_KEY=your-key \nANTHROPIC_API_KEY=your-key\n\n# Platform Integrations (optional)\nDISCORD_BOT_TOKEN=your-token\nNOTION_TOKEN=your-token\n```\n\n## \ud83d\uddfa\ufe0f Roadmap\n\n- **Graph Agents**: Advanced agent orchestration and workflows \n- **Heartbeat Mode**: Keep agents alive 24/7 doing autonomous tasks\n- **MCP Integration**: Model Context Protocol for easier tool reusing\n- **Support for Other Agent Frameworks**: Expand compatibility beyond Pydantic AI\n- **Smart Context Management**: Optimal handling of large context windows\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n---\n\n<p align=\"center\">\n <b>Part of the AutoMagik Ecosystem</b><br>\n <a href=\"https://github.com/namastexlabs/automagik\">AutoMagik</a> |\n <a href=\"https://github.com/namastexlabs/automagik-agents\">AutoMagik Agents</a> |\n <a href=\"https://github.com/namastexlabs/automagik-ui\">AutoMagik UI</a>\n</p>\n\n**Automagik Agents is and will always be open source.** Since this is our daily work tool at Namastex Labs, we provide high priority maintenance and regular updates. We built this because we believe AI agent development should be fast, reliable, and production-ready from day one.\n",
"bugtrack_url": null,
"license": null,
"summary": "Automagik agents templates",
"version": "0.5.6",
"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",
" agno",
" generative-ai",
" langgraph",
" memory"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "52c00eac093a1fe95d095404cdf55413fc6ee7a5b2b57a6e292ca406304908d4",
"md5": "bba35386d02c805c713cb8a5f150b42c",
"sha256": "a7ac090c70d2e24ab1988beedf7d3b70c07216c747240c8ca1bd4d7813c981bd"
},
"downloads": -1,
"filename": "automagik-0.5.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bba35386d02c805c713cb8a5f150b42c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.12",
"size": 791581,
"upload_time": "2025-07-09T22:47:22",
"upload_time_iso_8601": "2025-07-09T22:47:22.316828Z",
"url": "https://files.pythonhosted.org/packages/52/c0/0eac093a1fe95d095404cdf55413fc6ee7a5b2b57a6e292ca406304908d4/automagik-0.5.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2143503e0cee90d8e5950a4dfd06802de819d0a781813ebd0b78ad832533f4d8",
"md5": "8f840247bdf92018c0b8159f306b683e",
"sha256": "f250aef8e5df094d8d593fe80a572c8500ec3a6bad7035ad2726bfcf01fc9d37"
},
"downloads": -1,
"filename": "automagik-0.5.6.tar.gz",
"has_sig": false,
"md5_digest": "8f840247bdf92018c0b8159f306b683e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.12",
"size": 627852,
"upload_time": "2025-07-09T22:47:24",
"upload_time_iso_8601": "2025-07-09T22:47:24.134890Z",
"url": "https://files.pythonhosted.org/packages/21/43/503e0cee90d8e5950a4dfd06802de819d0a781813ebd0b78ad832533f4d8/automagik-0.5.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 22:47:24",
"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"
}
JSON
