Автономный AI-агент с нуля на Python

Модульный, расширяемый автономный AI-агент, разработанный с нуля без использования сторонних фреймворков (LangChain, CrewAI, AutoGen). В основе решения лежит архитектура ReAct (Reasoning + Acting), асинхронный бэкенд на FastAPI, строгая типизация Pydantic v2 и интеграция с локальными (Ollama) или облачными (OpenAI) LLM.

Архитектура системы

Агент работает по циклу ReAct:

1. Получает текстовую инструкцию от пользователя.
2. Отправляет контекст диалога и схему доступных инструментов в LLM.
3. Если модель решает вызвать инструмент, агент валидирует параметры, проверяет права доступа и выполняет функцию.
4. Результат выполнения инструмента добавляется в контекст диалога.
5. Шаги 2–4 повторяются до тех пор, пока модель не решит, что задача полностью выполнена.
6. Пользователю возвращается структурированный ответ.

Пользователь / HTTP-клиент
           │
           ▼
     FastAPI API            (POST /api/v1/agent/chat)
           │
           ▼
      AgentRunner           (Управление сессией и RAG-памятью)
           │
           ▼
       AgentLoop            (Основной ReAct-цикл)
     ┌─────┴───────────────────────────────────────┐
     │                                             │
     ▼                                             ▼
 LLM (OpenAI / Ollama)                    ToolRegistry
     │                                             │
     │ Решение о вызове инструмента                │ Выполнение инструмента
     └───────────────────► ToolResult ─────────────┘

Быстрый старт

1. Требования

• Python 3.11 или 3.12+
• Установленный Ollama (для локальной работы) или API-ключ OpenAI

2. Установка зависимостей

# Клонирование и переход в директорию проекта
cd ai-agent

# Создание конфигурационного файла
cp .env.example .env

# Установка проекта и dev-зависимостей в текущее окружение
pip install -e ".[dev]"

3. Настройка провайдера моделей (.env)

Вариант А: Локальный запуск через Ollama (бесплатно, без API-ключа)

1. Загрузите модель с поддержкой Function Calling:

   ollama run llama3.1
   # или
   ollama run qwen2.5
   

2. В файле .env укажите:

   OPENAI_BASE_URL=http://localhost:11434/v1
   OPENAI_MODEL=llama3.1
   OPENAI_API_KEY=ollama
   

Вариант Б: Использование OpenAI

В файле .env укажите:

OPENAI_BASE_URL=
OPENAI_MODEL=gpt-4o-mini
OPENAI_API_KEY=sk-...

4. Запуск сервера

uvicorn app.main:app --reload

• Документация Swagger UI: http://localhost:8000/docs
• Проверка работоспособности: http://localhost:8000/api/v1/agent/health

Запуск через Docker Compose

Для запуска полноценного стека с FastAPI, PostgreSQL и Redis выполните:

docker compose up --build

Примеры использования API

1. Синхронный запрос (POST /api/v1/agent/chat)

curl -X POST http://localhost:8000/api/v1/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Вычисли 17 * 23 + sqrt(144) и объясни результат."}'

Пример ответа:

{
  "response": "17 * 23 = 391, а квадратный корень из 144 равен 12. Сумма составляет 403.",
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "completed",
  "iterations": 2,
  "total_tokens": 312,
  "duration_ms": 1842.5
}

2. Продолжение диалога (сохранение контекста)

Передайте полученный session_id в следующем запросе:

curl -X POST http://localhost:8000/api/v1/agent/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Возведи полученное число в квадрат.",
    "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

3. Потоковый ответ (POST /api/v1/agent/chat/stream)

Эндпоинт передает события по протоколу Server-Sent Events (SSE):

curl -N -X POST http://localhost:8000/api/v1/agent/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Найди в интернете информацию о релизе Python 3.12."}'

Структура проекта

app/
├── main.py               # Точка входа FastAPI, инициализация и lifespan
├── api/
│   └── routes/
│       └── agent.py      # Маршруты API: /chat, /chat/stream, /tools, /health
├── agent/
│   ├── agent.py          # Фасад AgentRunner (управление сессиями и памятью)
│   ├── loop.py           # Основной цикл ReAct (вызовы LLM, обработка ошибок)
│   ├── planner.py        # Динамический генератор системного промпта
│   ├── state.py          # Pydantic-модели состояния агента и сессий
│   └── memory.py         # Менеджер 4-уровневой системы памяти
├── llm/
│   ├── client.py         # Асинхронный клиент OpenAI/Ollama с retry-логикой
│   └── schemas.py        # Провайдеро-независимые схемы сообщений и ответов
├── tools/
│   ├── base.py           # Декоратор @tool и автогенерация JSON Schema
│   ├── registry.py       # Центральный реестр инструментов и контроль прав
│   ├── calculator.py     # Инструмент математических вычислений (simpleeval)
│   ├── web_search.py     # Поиск в интернете через DuckDuckGo (без ключа)
│   ├── http_request.py   # HTTP GET/POST запросы с защитой от SSRF
│   ├── filesystem.py     # Чтение файлов и листинг директорий
│   └── shell.py          # Выполнение терминальных команд (DANGEROUS)
├── database/
│   ├── models.py         # SQLAlchemy 2.0 ORM-модели (сессии, память)
│   └── repository.py     # Асинхронный репозиторий для работы с PostgreSQL
└── core/
    ├── config.py         # Конфигурация через Pydantic Settings
    ├── logging.py        # Структурированное логирование (structlog)
    └── permissions.py    # Политика уровней доступа для инструментов

Уровни разрешений и безопасность

Каждый инструмент классифицируется по уровню доступа:

| Уровень | Описание | Инструменты | |---|---|---| | SAFE | Чистые вычисления без побочных эффектов. Разрешены всегда. | calculator | | RESTRICTED | Чтение данных или внешние запросы. Включены по умолчанию. | web_search, http_request, read_file, list_directory | | DANGEROUS | Потенциально деструктивные операции. Заблокированы по умолчанию. | shell_command |

Для включения опасных инструментов необходимо явно задать переменную окружения:

AGENT_ENABLE_DANGEROUS_TOOLS=true

Защитные механизмы:

• SSRF-фильтрация в http_request: блокировка обращений к localhost, 127.0.0.1, 169.254.x.x и приватным подсетям RFC1918 (10.x, 172.16.x, 192.168.x).
• Защита от Path Traversal в filesystem: пути проверяются относительно корня проекта, файлы .env и приватные ключи заблокированы.
• Белый список команд в shell_command: блокируются паттерны вроде rm -rf, sudo, curl | bash.

Архитектура памяти

Система разделяет память на 4 независимых уровня:

1. Оперативная память (RAM): Список сообщений AgentMessage текущего прогона, передаваемый в LLM на каждой итерации.
2. Кэш состояния сессии (Redis): Сериализованное состояние AgentSession с временем жизни (TTL 24 часа) для продолжения диалогов.
3. Долговременная память (PostgreSQL): Таблицы sessions и memory_entries для аудита и хранения извлеченных фактов.
4. Контекстная RAG-память: Перед запуском цикла агент ищет релевантные факты в базе данных и внедряет их в системный промпт.

При недоступности Redis или PostgreSQL агент продолжает работу в базовом режиме без сбоев.

Добавление нового инструмента

Для создания нового инструмента достаточно объявить асинхронную функцию с типизацией и декоратором @tool:

# app/tools/custom_tool.py
from app.tools.base import tool, ToolPermission
from app.tools.registry import registry

@tool(
    name="reverse_text",
    description="Переворачивает переданную строку задом наперед.",
    permission=ToolPermission.SAFE,
)
async def reverse_text(text: str) -> str:
    """
    Args:
        text: Исходный текст для переворота.
    """
    return text[::-1]

# Регистрация в глобальном реестре
registry.register(reverse_text)

Затем импортируйте модуль в функции lifespan файла app/main.py:

import app.tools.custom_tool  # noqa: F401

Запуск тестов

Тестовый набор включает модульные и интеграционные тесты с изоляцией и моками:

# Запуск всех тестов
pytest

# Запуск с подробным выводом
pytest -v

# Запуск с отчетом о покрытии кода
pytest --cov=app --cov-report=term-missing

Стек технологий

• Язык: Python 3.11+
• Веб-фреймворк: FastAPI + Uvicorn
• Валидация данных: Pydantic v2 + Pydantic Settings
• База данных: PostgreSQL + SQLAlchemy 2.0 (asyncpg)
• Кэширование: Redis (redis-py async)
• LLM-клиент: OpenAI Python SDK (совместим с Ollama, vLLM, OpenAI)
• Сетевой клиент: HTTPX
• Логирование: Structlog + Rich
• Повторные попытки: Tenacity
• Тестирование: Pytest + Pytest-Asyncio + Respx
• Контейнеризация: Docker + Docker Compose