automagik-agents


Nameautomagik-agents JSON
Version 0.1.2 PyPI version JSON
download
home_pageNone
SummaryAutomagik agents templates
upload_time2025-02-23 03:04:42
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseMIT
keywords ai agents pydantic fastapi notion
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 1.51684s