Лабораторные работы по AI-агентам

Этот репозиторий содержит лабораторные работы и примеры интеграций, посвященные разработке и развертыванию AI-агентов и MCP-серверов в продукте AI Agents на платформе Evolution. Также включены примеры ботов для интеграции A2A агентов в популярные мессенджеры (Mattermost и Telegram).

Документация продукта

Попробовать самому

Содержание

• Лабораторная работа 1: Создание MCP-сервера для расчета кредитов и вкладов
• Лабораторная работа 2: Запуск агента из Docker-образа в AI Agents (Google ADK)
• Лабораторная работа 3: LangChain Agent
• Лабораторная работа 4: SmolAgents Agent
• Лабораторная работа 5: CrewAI Agent
• Лабораторная работа 6: Strands Agents с Meta-Tooling
• Mattermost Bot для A2A агента
• Telegram Bot для A2A агента

О продукте AI Agents

Лабораторные работы предназначены для освоения возможностей продукта AI Agents на платформе Evolution. AI Agents позволяет создавать и управлять искусственным интеллектом для автоматизации бизнес-процессов.

Вы можете попробовать продукт самостоятельно в облаке cloud.ru.

Лабораторная работа 1: Создание MCP-сервера для расчета кредитов и вкладов

Расположение: lab1-mcp-finance-lab/

В этой лабораторной работе вы создадите MCP-сервер, предоставляющий инструменты для расчета графиков выплат по кредитам и вкладам. Вы освоите основы разработки MCP-сервисов с использованием фреймворка FastMCP, подготовите Docker-образ и развернете его в облаке cloud.ru.

Функциональность

MCP-сервер предоставляет три инструмента для финансовых расчетов:

1. Аннуитетный кредит (loan_schedule_annuity) - расчет фиксированного ежемесячного платежа и помесячного графика
2. Дифференцированный кредит (loan_schedule_differential) - расчет платежей с постоянной частью тела и уменьшающимися процентами
3. Вклад с капитализацией (deposit_schedule_compound) - расчет графика вклада с ежемесячной капитализацией и взносами

Технологии

• Python 3.12
• FastMCP фреймворк
• Docker для контейнеризации
• Poetry для управления зависимостями

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

lab1-mcp-finance-lab/
├── src/
│   ├── main.py          # Основной файл с определением MCP-инструментов
│   ├── calculations.py  # Реализация алгоритмов расчетов
│   ├── validators.py    # Валидация входных данных
│   ├── utils.py         # Вспомогательные функции
│   └── config.py        # Конфигурационные параметры
├── Dockerfile           # Определение Docker-образа
├── pyproject.toml       # Зависимости проекта
└── README.md            # Подробное описание лабораторной работы

Лабораторная работа 2: Запуск агента из Docker-образа в AI Agents (Google ADK)

Расположение: lab2-adk-agent/

Этот гайд описывает пошаговый процесс упаковки и запуска собственного агента в платформе AI Agents с использованием Docker и google-adk.

Особенности

1. Без файловой системы в рантайме - агенты не должны работать с файловой системой во время выполнения. Все необходимые файлы и зависимости нужно упаковывать на этапе сборки Docker-образа.
2. Автоматические переменные окружения - AI Agents автоматически прокидывает готовые переменные окружения в контейнер.

Технологии

• Python 3.12
• Google ADK (Agent Development Kit)
• A2A SDK
• Docker для контейнеризации
• Poetry для управления зависимостями

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

lab2-adk-agent/
├── src/
│   ├── a2a_agent.py           # Реализация A2A агента
│   ├── agent_task_manager.py  # Менеджер задач агента
│   ├── agent.py               # Определение агента
│   └── start_a2a.py           # Точка входа приложения
├── Dockerfile                 # Определение Docker-образа
├── pyproject.toml             # Зависимости проекта
└── README.md                  # Подробное описание лабораторной работы

Лабораторная работа 3: LangChain Agent

Расположение: lab3-langchain-agent/

В этой лабораторной работе вы создадите агента на базе LangChain - одного из самых популярных фреймворков для создания AI-агентов. Вы освоите интеграцию LangChain агента с MCP-серверами и развернете его в платформе AI Agents через протокол A2A.

Особенности

1. LangChain AgentExecutor - использование стандартного подхода LangChain для создания агентов
2. Интеграция с MCP - преобразование MCP инструментов в LangChain Tools
3. Streaming поддержка - потоковая передача ответов через A2A
4. Телеметрия - интеграция с OpenInference для отслеживания работы агента

Технологии

• Python 3.12
• LangChain (>=0.3.0) - фреймворк для создания агентов
• LangChain OpenAI - интеграция с OpenAI-совместимыми моделями
• A2A SDK (>=0.3.4) - протокол Agent-to-Agent
• LiteLLM - унификация доступа к LLM
• Docker для контейнеризации

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

lab3-langchain-agent/
├── src/
│   ├── agent.py              # Определение LangChain агента
│   ├── a2a_wrapper.py        # Обертка для A2A протокола
│   ├── agent_task_manager.py  # Интеграция с A2A executor
│   └── start_a2a.py          # Точка входа приложения
├── Dockerfile                 # Определение Docker-образа
├── pyproject.toml            # Зависимости проекта
└── README.md                  # Подробное описание лабораторной работы

Лабораторная работа 4: SmolAgents Agent

Расположение: lab4-smolagents-agent/

В этой лабораторной работе вы создадите легковесного агента на базе SmolAgents от Hugging Face. SmolAgents - это минималистичный фреймворк с акцентом на простоту и эффективность, идеально подходящий для быстрого прототипирования.

Особенности

1. Легковесность - минимальные зависимости и простой API
2. Code Agents - агент может писать и выполнять Python код
3. Эффективность - уменьшает количество шагов и вызовов LLM на ~30%
4. Простота интеграции - легкая интеграция с A2A протоколом

Технологии

• Python 3.12
• SmolAgents (>=0.1.0) - легковесный фреймворк от Hugging Face
• A2A SDK (>=0.3.4) - протокол Agent-to-Agent
• LiteLLM - унификация доступа к LLM
• Docker для контейнеризации

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

lab4-smolagents-agent/
├── src/
│   ├── agent.py              # Определение SmolAgents агента
│   ├── a2a_wrapper.py        # Обертка для A2A протокола
│   ├── agent_task_manager.py  # Интеграция с A2A executor
│   └── start_a2a.py          # Точка входа приложения
├── Dockerfile                 # Определение Docker-образа
├── pyproject.toml            # Зависимости проекта
└── README.md                  # Подробное описание лабораторной работы

Лабораторная работа 5: CrewAI Agent

Расположение: lab5-crewai-agent/

В этой лабораторной работе вы создадите мульти-агентную команду (crew) на базе CrewAI. CrewAI позволяет создавать команды AI-агентов, которые работают вместе для решения сложных задач, распределяя работу между специализированными агентами.

Особенности

1. Мульти-агентность - несколько агентов работают вместе
2. Распределение задач - автоматическое распределение задач между агентами
3. Delegation - агенты могут делегировать задачи друг другу
4. Структурированность - четкое разделение ролей и задач

Технологии

• Python 3.12
• CrewAI (>=0.80.0) - фреймворк для мульти-агентных команд
• CrewAI Tools - инструменты для агентов
• A2A SDK (>=0.3.4) - протокол Agent-to-Agent
• LiteLLM - унификация доступа к LLM
• Docker для контейнеризации

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

lab5-crewai-agent/
├── src/
│   ├── agents.py            # Определение агентов в crew
│   ├── tasks.py             # Определение задач
│   ├── crew.py              # Определение crew
│   ├── a2a_wrapper.py       # Обертка для A2A протокола
│   ├── agent_task_manager.py # Интеграция с A2A executor
│   └── start_a2a.py         # Точка входа приложения
├── Dockerfile               # Определение Docker-образа
├── pyproject.toml           # Зависимости проекта
└── README.md                # Подробное описание лабораторной работы

Лабораторная работа 6: Strands Agents с Meta-Tooling

Расположение: lab6-strands-agent/

В этой лабораторной работе вы создадите агента на базе Strands Agents с возможностью meta-tooling - создания инструментов на лету. Это уникальная возможность, которая позволяет агенту динамически расширять свои возможности без изменения кода.

Особенности

1. Meta-Tooling - создание новых инструментов во время выполнения
2. Динамическое расширение - агент может расширять свои возможности самостоятельно
3. Гибкость - адаптация к новым задачам без изменения кода агента
4. Инструменты для создания инструментов - load_tool, editor, shell

Технологии

• Python 3.12
• Strands Agents (>=0.3.0) - фреймворк с поддержкой meta-tooling
• A2A SDK (>=0.3.4) - протокол Agent-to-Agent
• LiteLLM - унификация доступа к LLM
• Docker для контейнеризации

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

lab6-strands-agent/
├── src/
│   ├── agent.py              # Определение Strands агента с meta-tooling
│   ├── a2a_wrapper.py       # Обертка для A2A протокола
│   ├── agent_task_manager.py # Интеграция с A2A executor
│   └── start_a2a.py         # Точка входа приложения
├── tools/                    # Директория для динамически создаваемых инструментов
├── Dockerfile                # Определение Docker-образа
├── pyproject.toml           # Зависимости проекта
└── README.md                 # Подробное описание лабораторной работы

Mattermost Bot для A2A агента

Расположение: mattermost-bot-for-a2a/

Бот для Mattermost, интегрированный с A2A агентом, с поддержкой streaming ответов, команд и полной OpenInference телеметрией.

Функциональность

Бот позволяет интегрировать A2A агента в Mattermost, обеспечивая:

1. Ответы на упоминания бота - бот отвечает на упоминания (@bot_name) в каналах
2. Обработку прямых сообщений - поддержка приватных диалогов с ботом
3. Поддержку команд - команды /a2a help, /a2a status и другие
4. Streaming ответы - потоковая передача ответов от A2A агента
5. Полную телеметрию - интеграция с OpenInference и OpenTelemetry

Технологии

• Python 3.8+
• uv - быстрый менеджер пакетов Python
• mattermostdriver - клиент для Mattermost API
• a2a SDK - интеграция с A2A агентами
• OpenTelemetry/OpenInference - телеметрия

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

mattermost-bot-for-a2a/
├── bot.py                 # Основной файл бота
├── a2a_client.py          # Обертка для A2A клиента с телеметрией
├── mattermost_handler.py  # Обработчики Mattermost событий
├── commands.py            # Обработка команд бота
├── telemetry.py           # Настройка OpenInference телеметрии
├── config.py              # Загрузка конфигурации из env
├── pyproject.toml         # Конфигурация проекта и зависимости
├── requirements.txt       # Зависимости
├── .env.example           # Пример конфигурации
└── README.md              # Подробное описание

Telegram Bot для A2A агента

Расположение: telegram-bot-for-a2a/

Небольшой и удобный бот на базе aiogram 3 для взаимодействия с агентами по URL. Поддерживает быстрое подключение к агентной системе, переподключение и механизм повторных попыток при ошибках.

Функциональность

Бот позволяет интегрировать A2A агента в Telegram, обеспечивая:

1. Старт и меню - удобное меню с разделами «Начать работу», «Помощь», «Подключиться по URL»
2. Подключение к агенту по URL - вводите URL — и бот подключится к вашему агенту
3. Общение с агентом - пересылайте текстовые запросы и получайте ответы
4. Обработку голосовых сообщений - поддержка транскрипции голосовых сообщений
5. Повтор запроса (Retry) - в случае ошибки можно быстро повторить запрос
6. История ошибок - краткая сводка последних ошибок для отладки

Технологии

• Python 3.13
• aiogram 3 - Telegram Bot API
• Poetry - управление зависимостями
• pydantic-settings - конфигурация через .env
• httpx - HTTP-клиент
• a2a SDK - интеграция с агентами
• opentelemetry - телеметрия

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

telegram-bot-for-a2a/
├── main.py                 # Точка входа бота
├── Dockerfile              # Docker образ
├── docker-compose.yaml     # Docker Compose конфигурация
├── pyproject.toml          # Конфигурация проекта и зависимости
├── poetry.lock            # Lock файл зависимостей
├── .env.example            # Пример конфигурации
├── README.md              # Подробное описание
└── src/
   ├── config/              # Конфигурация
   ├── handlers/            # Обработчики команд и сообщений
   ├── keyboards/           # Клавиатуры для меню
   ├── services/            # Интеграция с A2A агентом
   └── utils/               # Утилиты (команды, сессии, голос)