Добро пожаловать в команду AI Agenta

Мы рады, что вы присоединились к разработке агентов для нашей платформы. Этот документ содержит всё необходимое для старта работы: доступы, стандарты разработки, процесс сдачи задач и условия сотрудничества.

Прочитайте его полностью перед началом работы и сохраните для последующего использования.

О платформе

AI Agenta — платформа управления ИИ-агентами для малого и среднего бизнеса. Клиенты подключают агентов через личный кабинет: запускают, настраивают триггеры, отслеживают результаты и платят за использование.

Вы создаёте агентов, которые работают на этой платформе. Каждый агент — это отдельный сервис, интегрированный в нашу инфраструктуру через Agent Template.

---

1. Доступы и окружение

Что вы получаете при онбординге

Ресурс	Описание
GitHub	Доступ к репозиторию github.com/aashmyrin/aiagenta (ветка для вашей задачи)
Staging API	https://api.aiagenta.ru (staging-порт) — для тестирования агентов
Agent Template	Базовый шаблон агента в папке /agent_template репозитория
Staging Dashboard	Доступ к тестовому личному кабинету для проверки агента в интерфейсе
Telegram-канал	Рабочий чат команды для вопросов и обновлений

Важные правила доступа

warning

• Доступ к production-серверу не предоставляется — только к staging
• Не храните .env файлы и API-ключи в репозитории
• Не делитесь доступами с третьими лицами
• При завершении сотрудничества доступы отзываются в течение 24 часов

---

2. Agent Template — стандарт разработки

Все агенты на платформе AI Agenta разрабатываются на основе единого Agent Template. Это обязательное требование, не рекомендация.

Структура шаблона

agent_template/
  app/
    main.py        — FastAPI приложение, эндпоинты /health и /run
    runner.py      — Agentic loop (Claude API + tool use)
    metrics.py     — Отправка метрик в оркестратор
    models.py      — Pydantic модели (TaskRequest, TaskResponse)
    config.py      — Настройки через .env
    logger.py      — Структурированный логгер
  tools/
    __init__.py    — TOOL_REGISTRY (регистрация инструментов)
    example_tools.py — Примеры: time, calculator, web_search stub
  tests/
    test_agent.py
  Dockerfile
  requirements.txt
  .env.example

API агента

Каждый агент обязан реализовать два эндпоинта:

POST /run — запуск задачи

// Запрос:
{
  "task_id": "uuid",
  "input": "текст задачи для агента",
  "config": {
    "system_prompt": "Вы — финансовый аналитик.",
    "max_tokens": 2048,
    "enabled_tools": ["calculator", "web_search"]
  }
}

// Ответ:
{
  "task_id": "uuid",
  "status": "success",
  "output": "результат работы агента",
  "metrics": {
    "duration_sec": 1.24,
    "input_tokens": 312,
    "output_tokens": 48,
    "steps": 2
  }
}

GET /health — проверка работоспособности

{ "status": "ok", "agent_id": "agent-001", "agent_name": "my-agent" }

Технические требования к агенту

Требование	Описание
LLM-бэкенд	Только Claude API (claude-sonnet модель) через Anthropic SDK
Язык	Python 3.11+
Фреймворк	FastAPI (из шаблона)
Контейнеризация	Обязательно Docker + docker-compose
Тесты	Минимум 3 теста через pytest, покрытие /run и /health
Логирование	Использовать logger.py из шаблона
Метрики	Заполнять поле metrics в ответе /run
Переменные окружения	Все секреты только через .env (не хардкодить)

Как добавить инструмент агенту

1. Создайте файл tools/my_tool.py с определением инструмента
2. Зарегистрируйте его в tools/__init__.py в словаре TOOL_REGISTRY
3. Добавьте обработчик handle_my_tool(params) в файл инструмента
4. Напишите тест в tests/test_agent.py

---

3. Процесс разработки и сдачи задач

Git-процесс

1. Получите задачу и создайте ветку: feature/agent-name от develop
2. Разрабатывайте агента строго по Agent Template
3. Создайте Pull Request в ветку develop с описанием агента
4. Пройдите code review (обычно 1–2 дня)
5. После апрува — деплой в staging, тестирование
6. После успешного тестирования — выплата и мерж в main

Требования к Pull Request

• Название PR: [AgentName] краткое описание
• Описание: что делает агент, какие инструменты использует, как тестировать
• Все тесты проходят (pytest)
• Нет захардкоженных секретов и ключей
• Dockerfile корректно собирается
• README.md для агента заполнен

Чеклист перед сдачей

• Агент создан на базе Agent Template
• Реализованы /run и /health
• Все переменные окружения в .env.example
• Написаны тесты (минимум 3)
• Dockerfile собирается без ошибок
• Агент запускается в staging и отвечает на /health
• README.md заполнен: описание, параметры запуска, примеры вызова
• Нет print с секретными данными

Критерии приёмки

Критерий	Описание
Функциональность	Агент выполняет заявленную задачу по ТЗ
Стандарт	Соответствует Agent Template (структура, API, логирование)
Качество кода	Читаемый код, нет дублирования, понятные названия
Тесты	Все тесты зелёные, покрывают основные сценарии
Документация	README.md содержит описание и инструкцию запуска
Безопасность	Нет секретов в коде, корректная обработка ошибок

---

4. Направления работы

4.1. Клиентские агенты

Разработка агента под конкретного клиента по техническому заданию. Это проектная работа с фиксированным объёмом.

Параметр	Условия
Оплата	Фиксированная сумма за агента, согласованная до старта работ
ТЗ	Предоставляет AI Agenta перед началом работы
Срок	Фиксируется в задаче, стандарт — 5–10 рабочих дней
Приёмка	По чеклисту + успешная работа в staging
Права	Агент переходит в собственность AI Agenta и клиента

4.2. Агенты для маркетплейса

Разработка агента для публичного каталога платформы. Клиенты подключают таких агентов через интерфейс и платят подписку.

Параметр	Условия
Оплата	Revenue share — процент от выручки с подписок на агента
Идея агента	Согласовывается с AI Agenta до разработки
Контроль качества	Повышенные требования — агент используется многими клиентами
Поддержка	Разработчик обеспечивает обновления агента при необходимости
Права	Агент размещается на платформе AI Agenta

Подробнее — в документе Revenue Share.

---

5. Коммуникация и поддержка

Как задавать вопросы

• Технические вопросы по платформе — в рабочий Telegram-чат
• Уточнения по ТЗ — до начала разработки, не в процессе
• Статус задачи — обновляйте в PR или в чате раз в 2 дня
• Проблемы с дедлайном — сообщайте заранее, не в день сдачи

Чего мы ожидаем от вас

• Соблюдение стандарта Agent Template без исключений
• Соблюдение согласованных сроков или своевременное предупреждение
• Самостоятельное тестирование перед сдачей
• Честная обратная связь о проблемах и сложностях

Чего вы можете ожидать от нас

• Чёткое ТЗ перед стартом работ
• Обратная связь по PR в течение 2 рабочих дней
• Оплата в течение 3 рабочих дней после приёмки
• Помощь с техническими вопросами по платформе

---

6. Контакты

Контакт	Данные
Сайт	aiagenta.ru
Email	info@aiagenta.ru
Телефон	+7 921 940-51-70
Telegram	@AndreyShmyrin