RepoTransAgent: мультиагентный подход к сложным задачам через специализированных агентов

АГЕНТ 1: RAG (Selective Retrieval)
├─ Проверка: функция простая? → пропустить RAG, экономим токены
└─ Multi-route retrieval:
 ├─ Поиск похожих функций (dense + sparse retrieval)
 ├─ Поиск по именам методов
 └─ Фильтрация — агент решает, какие примеры полезны

АГЕНТ 2: Context (Intelligent Gathering)
├─ Итерация 1: Базовый контекст (3 инструмента)
│ ├─ get_source_class_info → поля и методы класса-источника
│ ├─ get_target_class_info → поля и методы класса-цели
│ └─ find_target_imports → импорты целевого файла
├─ Итерации 2-N: Детальный контекст (по запросу агента)
│ ├─ find_target_class_info → информация о конкретном классе
│ └─ find_target_method_body → полный код метода
└─ Всё в JSON → понятно для LLM

АГЕНТ 3: Refine (Generate → Test → Reflect → Fix)
├─ ШАГ 1: Генерация кода + контекст от Агентов 1 и 2
├─ ШАГ 2: Выполнение тестов → сбор ошибок (4 типа: compilation, test failure, runtime, timeout)
├─ ШАГ 3: Рефлексия
│ ├─ Анализ: почему упало?
│ ├─ Стратегия: как исправить?
│ └─ Инструменты: какой контекст нужен?
├─ ШАГ 4: Сбор доп. контекста под ошибку
└─ ШАГ 5: Исправление → возврат к ШАГ 2 (до 5 итераций)

Все шаги выполняются в отдельных запросах. Каждый агент получает результаты предыдущих агентов через динамические промпты.

⚠️ Ограничения метода: Полная система требует инструментов (парсинг кода, векторные базы). Но принципы мультиагентности, динамических промптов и рефлексии применимы в чате для любых сложных задач.

Задача: Написать техническую статью про новую фичу в вашем продукте для разработчиков.

Промпт (адаптация мультиагентного подхода):

Ты будешь работать как три специализированных агента для написания технической статьи.

# АГЕНТ 1: Research Agent (Сбор контекста)

**Goals:** Собрать всю информацию, необходимую для написания статьи.

**Guidelines:**
- Сначала изучи базовый контекст: что такое фича, зачем нужна, кто целевая аудитория
- Затем собери детали: как работает, какие API, примеры использования
- Определи, какие смежные темы нужно упомянуть

**Input:** 
Фича: {новая система кеширования в нашем API}
Целевая аудитория: {бэкенд-разработчики, знакомые с REST API}

**Output Format:** JSON с секциями: overview, technical_details, use_cases, prerequisites, related_topics

Выполни роль Research Agent и выведи только JSON.

---

# АГЕНТ 2: Structure Agent (Планирование структуры)

**Goals:** На основе собранного контекста создать чёткую структуру статьи.

**Guidelines:**
- Начни с проблемы, которую решает фича
- Покажи решение через примеры
- Добавь advanced use cases
- Завершай troubleshooting

**Gathered Context:** 
{вставь JSON от Research Agent}

**Output Format:** Markdown с заголовками и краткими тезисами под каждым разделом (без полного текста)

Выполни роль Structure Agent и выведи только структуру.

---

# АГЕНТ 3: Writing Agent (Написание + Рефлексия)

**Goals:** Написать статью, провести self-review, улучшить.

**Guidelines:**
- Используй конкретные примеры кода
- Избегай маркетинговых фраз
- Технические термины объясняй в скобках
- После написания: проверь, всё ли понятно новичку в теме?

**Gathered Context:**
{вставь JSON от Research Agent}
{вставь структуру от Structure Agent}

**Reflection Questions:**
- Понятно ли с первого раза, что делает эта фича?
- Достаточно ли примеров кода?
- Есть ли gaps в объяснении?

**Output Format:** 
1. Черновик статьи
2. Reflection (ответы на вопросы выше)
3. Финальная версия (с учётом reflection)

Выполни роль Writing Agent.

Результат: Модель последовательно выполнит три роли. Research Agent соберёт информацию в структурированном виде. Structure Agent создаст логичный план статьи. Writing Agent напишет черновик, проведёт рефлексию (найдёт что примеров мало, термины не все объяснены), исправит и выдаст финальную версию. Вместо одного промпта "напиши статью" — специализация задач даёт более продуманный и полный результат.

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

Сильная сторона LLM: Модель отлично выполняет узкие специализированные задачи, если дать ей чёткую роль и понятные инструкции. Она хорошо следует структурированным промптам с явными Guidelines и конкретными Output Format. Модель умеет проводить рефлексию — если попросить проанализировать собственный output и найти слабые места, она это сделает.

Как метод использует сильные стороны: Мультиагентный подход разделяет когнитивную нагрузку. Каждый агент делает одно дело хорошо: Research собирает факты, Structure планирует, Writing пишет и улучшает. Динамические промпты дают каждому агенту нужный контекст (Gathered Context от предыдущих агентов) и чёткую роль (Goals + Guidelines). Рефлексия перед исправлением — вместо слепого "исправь ошибки", агент сначала анализирует причины ("не хватает примеров"), формирует стратегию ("добавить 2-3 code snippets"), собирает дополнительный контекст (если нужно), а затем исправляет осознанно.

Рычаги управления:

• Количество агентов → для простой задачи можно объединить Research + Structure в один промпт, экономия токенов
• Guidelines → детализируй для строгого соблюдения правил, упрости для креативности
• Reflection questions → меняй вопросы под свою задачу ("понятно ли новичку?" vs "всё ли корректно юридически?")
• Output Format → JSON для структурированных данных, Markdown для текста, код для исполняемых артефактов
• Gathered Context → добавляй только релевантное, не весь вывод предыдущих агентов — фильтруй шум

Базовая структура динамического промпта (используй для каждого агента):

# АГЕНТ {N}: {Название роли}

**Goals:** {Что должен сделать этот агент — одна чёткая цель}

**Tools:** {Список доступных инструментов, если есть}
- tool_name: описание + параметры

**Guidelines:** {Принципы работы — как использовать инструменты, на что обратить внимание}
- Сначала: {базовые действия}
- Затем: {итеративные или advanced действия}
- Обрати внимание на: {специфические нюансы задачи}

**Example:** {Конкретный пример — показать workflow}
Задача: {пример задачи}
Шаг 1: {что делаем}
Шаг 2: {что делаем}
Результат: {что получаем}

**Input:** {Данные для работы — это меняется для каждой задачи}
{специфичные данные задачи}

**Gathered Context:** {Что собрали на предыдущих шагах — это тоже динамическое}
{результаты от предыдущих агентов}

**Output Format:** {Строгий формат вывода}
Формат: {JSON / Markdown / код}
Поля: {список обязательных полей}
Пример: {показать как должен выглядеть вывод}

**Last Command:** {Что сделали в прошлый раз — для итеративных агентов}
Инструмент: {название}
Результат: {краткий вывод}

Выполни роль {Название агента} и выведи результат строго в указанном формате.
```

**Как заполнять плейсхолдеры:**

- `{N}` — порядковый номер агента (1, 2, 3...)
- `{Название роли}` — Research Agent, Context Agent, Refine Agent — кто этот агент?
- `{Что должен сделать}` — одна конкретная цель, например "собрать информацию о конкурентах"
- `{Input}` — данные конкретной задачи, например "название продукта: Tesla Model 3"
- `{Gathered Context}` — результаты предыдущих агентов, копируй JSON или текст
- `{Last Command}` — только для итеративных агентов, которые вызывают инструменты несколько раз

🚀 **Быстрый старт** — вставь в чат:
```
Вот шаблон мультиагентного промпта. Адаптируй под мою задачу: {твоя сложная задача}. 
Задавай вопросы, чтобы заполнить поля.

[вставить шаблон выше]
```

LLM спросит: сколько агентов нужно, какие роли, какие инструменты (если есть), какие Guidelines важны для твоей задачи. Она возьмёт структуру из шаблона и адаптирует под конкретную задачу — например, для анализа юридического документа создаст Legal Research Agent → Risk Assessment Agent → Recommendation Agent.

## Оригинал из исследования

**Контекст:** Исследователи использовали этот промпт для Context Agent, чтобы он собирал контекст для перевода кода. Вот структура оригинального промпта:
```
**Goals:**
You are an expert in repository-aware code translation. Your task is to gather the most relevant context to assist in translating a source function into a target function.

**Tools:**
1. get_source_class_info(source_function_name) → Returns field definitions and method signatures from the source class
2. get_target_class_info(target_function_name) → Returns field definitions and method signatures from the target class
3. find_target_imports(target_file_path) → Returns all imported classes in the target file
4. find_target_class_info(class_name) → Searches for a specific class and returns its fields and methods
5. find_target_method_body(class_name, method_name) → Returns the complete method implementation

**Guidelines:**
1. First, call get_source_class_info, get_target_class_info, and find_target_imports to establish basic context
2. Then, use find_target_class_info and find_target_method_body iteratively to gather detailed information
3. Pay attention to language-specific differences (e.g., C# Dictionary → Java Map)
4. Stop when you have sufficient context for accurate translation

**Example:**
Source Function: ConvertCamelToSnake(string input)
Target Signature: convertCamelToSnake(String input)

Step 1: get_source_class_info → Found: class StringUtils with fields logCount, methods convertCase
Step 2: get_target_class_info → Found: class StringUtils with fields logCount, methods convertCase
Step 3: find_target_imports → Found: import java.util.Map
Step 4: find_target_class_info("Logger") → Found Logger class with method log(String message)
STOP: Sufficient context gathered

**Input:**
Source Function: {source_function_body}
Target Signature: {target_function_signature}

**Gathered Context:** {context_collected_so_far}

**Output Format:**
{
 "id": 1,
 "name": "tool_name",
 "args": {"param": "value"}
}

**Last Command:** 
Tool: {last_tool_name}
Output: {last_tool_output}

Ключевые детали:

• Goals задаёт экспертизу агента — он специалист в repository-aware code translation
• Tools описывают каждый инструмент с параметрами и возвращаемым значением
• Guidelines показывают последовательность — сначала базовый контекст (3 инструмента), потом итеративный сбор деталей
• Example демонстрирует критерий остановки — "достаточно контекста"
• Gathered Context — это память агента, что уже собрано
• Last Command — напоминание о предыдущем шаге, чтобы избежать повторов

Мультиагентный подход RepoTransAgent идеален для работы с кодом в чате:

# АГЕНТ 1: Codebase Explorer
Роль: Изучить существующий код
Задача: Найди в проекте {название проекта}:
- Похожие функции (как reference)
- Используемые библиотеки и утилиты
- Паттерны кодирования (naming, structure)

# АГЕНТ 2: Context Gatherer
Роль: Собрать детали для задачи
Задача: На основе находок Агента 1, собери:
- API используемых библиотек
- Сигнатуры методов, которые будут нужны
- Примеры аналогичного кода из проекта

# АГЕНТ 3: Code Generator + Refiner
Роль: Написать код, протестировать, исправить
Задача:
1. Напиши код с учётом контекста
2. Reflection: соответствует ли паттернам проекта? Все ли edge cases покрыты?
3. Исправь на основе рефлексии

Пример: Вместо "напиши функцию для парсинга CSV" → три агента находят что в проекте используется библиотека Pandas, собирают примеры её использования из проекта, генерируют код в том же стиле.

Если задача нестандартная и пример из промпта может зациклить агента на конкретном паттерне:

Оригинал: Example показывает конкретный workflow

Изменение: Убери секцию Example, оставь только Guidelines

Эффект: Агент сам решает последовательность действий на основе Guidelines, не копируя пример слепо.

# До:
**Example:**
Step 1: get_source_class_info
Step 2: find_target_class_info("Logger")
STOP

# После:
**Guidelines:**
- Сначала собери базовый контекст
- Затем итеративно запрашивай детали
- Остановись когда достаточно для решения задачи

Для итеративных агентов критично задать явные критерии остановки, иначе они будут собирать контекст бесконечно:

**Stop Criteria:**
Останови сбор контекста когда:
- Собрано >= 3 примера использования класса
- ИЛИ найдены все методы из target signature
- ИЛИ сделано 5 итераций

Эффект: Агент не тратит токены на избыточный контекст.

Мультиагентность + CoT = каждый агент рассуждает вслух перед действием:

# АГЕНТ 2: Context Gatherer

**Before each tool call, think:**
1. Какую информацию я ищу?
2. Какой инструмент лучше всего подходит?
3. Что я уже знаю из Gathered Context?

**Then call the tool.**

**After tool output, reflect:**
1. Получил ли я то, что искал?
2. Достаточно ли этого для задачи?
3. Какой следующий шаг?

Эффект: Агент объясняет свои решения → проще отладить, если что-то пошло не так.

⚠️ Требует инфраструктуры для полной системы: Оригинальный RepoTransAgent работает с векторными базами, парсером кода и статическим анализом — это требует программирования. В чате можно использовать принципы (мультиагентность, динамические промпты, рефлексия), но не полную систему с инструментами.

⚠️ Не для простых задач: Мультиагентный подход оправдан для сложных задач с несколькими этапами. Для "напиши функцию сложения двух чисел" — это overkill. Используй, когда задача требует: (1) сбора контекста, (2) планирования, (3) генерации, (4) проверки и исправления.

⚠️ Токен-хеви: Каждый агент — отдельный запрос. Три агента = минимум три запроса к API (больше если итеративные). Для простых задач это дорого. Зато для сложных — качество выше, потому что каждый агент фокусируется на своей части.

⚠️ Требует больших моделей: На маленьких моделях (7B-8B) мультиагентность работает хуже — они плохо следуют сложным инструкциям и путают роли. RepoTransAgent показал существенный рост на 70B+ моделях, на маленьких даже ухудшение. Для чата используй GPT-4, Claude 3.5, Llama 70B+.

⚠️ Selective Retrieval требует опыта: RAG Agent решает, нужен ли вообще поиск примеров. Но если задать критерий неправильно — пропустит полезные примеры или потратит токены на ненужные. Начни без селективности, добавь когда поймёшь паттерны своих задач.

Команда взяла 6 популярных GitHub-проектов с реализациями на Java и C# (Lucene, Apache POI, JGit, iText, Quartz, RocketMQ) — всего 627 функций C#→Java и 655 функций Java→C#. Для каждой функции извлекли unit-тесты, убедились что они работают. Сравнивали RepoTransAgent с тремя baseline: UniTrans и PLTranslation (итеративные подходы с тест-кейсами) и No Agent (прямой перевод без рефлексии).

Измеряли compile rate (сколько скомпилировалось без ошибок) и pass rate (сколько прошло все тесты). RepoTransAgent выдал 55.34% compile rate и 45.84% pass rate против 26-30% compile и 18-28% pass у baseline. Удивительно: улучшение было не одинаковым по проектам — на jgit и rocketmq-clients pass rate вырос в несколько раз (с 9% до 35%, с 0% до 26%), а на Lucene скромнее (с 11% до 36%).

Почему так? Исследователи проанализировали ошибки — основная проблема была compilation errors (264 из 328 провалов в C#→Java), а конкретно "symbol not found" — когда класс или метод существует в Java-репозитории, но называется иначе или находится в другом пакете. RepoTransAgent умнее находил правильные маппинги через Context Agent. Пример из статьи: агент нашёл что C# Dictionary → Java Map, foreach → for, CellUtil.CalculateCount → CellPropertyType.collectCount (через семантический анализ имён методов!).

Инсайт для практики: Статический анализ (call graphs) даёт слишком много шума для LLM. Лучше дать агенту специализированные инструменты (поиск класса, поиск метода) и позволить самому решать что собирать. Это работает не только для code translation — везде, где нужен адаптивный сбор контекста.

Дополнительно: Проверили на разных моделях (Llama 3.1, Qwen2.5, GPT-4o-mini, DeepSeek V3). На больших моделях (70B+) RepoTransAgent давал стабильный буст, на маленьких (7B-8B) иногда хуже baseline. Разные модели переводили разные наборы функций — объединив выводы 4 моделей получили 355 успешных переводов вместо 104 общих для всех. Это показывает комплементарность моделей.

Статья: RepoTransAgent: Multi-Agent LLM Framework for Repository-Aware Code Translation

Авторы: Ziqi Guan, Xin Yin (Zhejiang University), Zhiyuan Peng (Shanghai Jiao Tong University), Chao Ni (Zhejiang University)

Дата: 2025

Ключевые ссылки:

• Dataset benchmark: Methods2Test (методология извлечения focal methods + test cases)
• Related: UniTrans, PLTranslation (baseline подходы с итеративным refinement)