Harness Engineering: как улучшить производительность coding-агента на 25% с помощью self-verification и трейсинга в LangSmith

Странная правда о coding-агентах

Ты взял GPT-5.2-Codex — одну из самых способных моделей для генерации кода на 2026 год. Настроил промпт по всем канонам. Запустил. А он выдает ерунду. Падает на простых задачах. Генерирует код, который даже не компилируется.

Знакомая картина? Ты не одинок.

Большинство разработчиков бросаются менять модель, усложнять промпт, искать волшебную библиотеку. А проблема почти всегда не в модели. Проблема в обвязке — в том, как ты заставляешь модель думать, проверять себя и учиться на ошибках.

Конкретная математика: от 52.8 до 66.5

Возьмем конкретный измеримый случай — бенчмарк Terminal Bench 2.0 (актуальная версия на март 2026).

25.9% — не теоретический прирост. Это разница между агентом, который стыдно показать, и инструментом, который реально экономит время. И достигнуто это без смены модели, только за счет инженерии окружения.

Почему агент глупее модели внутри него?

Модель типа GPT-5.2-Codex тренирована на триллионах токенов кода. Она знает синтаксис, паттерны, даже лучшие практики. Но когда ты заворачиваешь ее в агента, происходят три вещи:

• Контекстная слепота: агент видит задачу разово, без цикла обратной связи. Написал код — отправил. Ошибка? Не его проблемы.
• Отсутствие рефлексии: у модели нет встроенного механизма «проверь, что ты только что сгенерировал, на очевидные косяки».
• Черный ящик исполнения: ты не видишь, как агент принимает решения. Почему он выбрал именно эту библиотеку? Почему не увидел edge case? Без трейсинга ты гадаешь на кофейной гуще.

Рецепт улучшения вытекает из проблем: добавь self-verification и сделай процесс наблюдаемым через трейсинг.

1 Устанавливаем стенд: LangSmith и базовый агент

LangSmith на 2026 год — это не просто дашборд для трейсов. Это полноценная платформа для отладки, оценки и итеративного улучшения агентов. Без нее ты летишь вслепую.

# Установка LangSmith SDK (актуальная версия на март 2026)
pip install langsmith langchain langchain-openai

# Экспорт ключа API (бери из настроек проекта в LangSmith Cloud)
export LANGCHAIN_API_KEY="lsv2_pt_..."
export LANGCHAIN_TRACING_V2=true

Базовый агент на LangChain (используем актуальный `langchain==0.3.0` стиль):

from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate
from langchain_community.tools import ShellTool

# Модель — берем самую свежую для кода на март 2026
llm = ChatOpenAI(model="gpt-5.2-codex", temperature=0)

# Инструмент — выполнение команд в shell (основа Terminal Bench)
shell_tool = ShellTool()
tools = [shell_tool]

# Промпт — минимальный, zero-shot
prompt = ChatPromptTemplate.from_messages([
    ("system", "Ты — coding агент. Выполняй задачи, используя shell."),
    ("human", "{input}"),
])

# Сборка агента
agent = create_tool_calling_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=False)

# Запуск
result = agent_executor.invoke({"input": "Создай файл test.txt с текстом 'hello'"})
print(result["output"])

Этот агент даст тебе те самые ~52.8 балла. Он работает, но часто ошибается. Теперь начинается инженерия.

2 Добавляем Self-Verification: заставляем агента проверять себя

Self-verification — это не магия. Это простой принцип: «прежде чем сказать, что задача выполнена, проверь результат». В кодинге это значит: сгенерировал код → проверь его на наличие очевидных ошибок → если есть, исправь.

Реализуем это как дополнительный шаг в цикле агента. Не через сложные рекурсивные промпты, а через отдельный инструмент верификации.

from langchain_core.tools import tool
from langchain_core.prompts import ChatPromptTemplate

@tool
def verify_and_fix_code(initial_code: str, task_description: str) -> str:
    """Проверь предоставленный код на соответствие задаче и исправь очевидные ошибки."""
    verification_prompt = ChatPromptTemplate.from_messages([
        ("system", "Ты — опытный инженер. Проверь код на: 1. Синтаксические ошибки. 2. Логическое соответствие задаче. 3. Очевидные уязвимости. Если код идеален, верни его как есть. Если есть проблемы, исправь и верни исправленную версию."),
        ("human", f"Задача: {task_description}\n\nКод для проверки:\n\n{initial_code}\n"),
    ])
    verification_chain = verification_prompt | llm
    response = verification_chain.invoke({})
    return response.content

# Добавляем инструмент верификации в список инструментов агента
tools.append(verify_and_fix_code)

# Обновляем промпт агента, явно просим использовать верификацию
prompt_with_verification = ChatPromptTemplate.from_messages([
    ("system", "Ты — тщательный coding агент. Всегда после генерации кода используй инструмент 'verify_and_fix_code', чтобы проверить и исправить его перед выполнением."),
    ("human", "{input}"),
])

# Пересобираем агента
agent_with_verification = create_tool_calling_agent(llm, tools, prompt_with_verification)
agent_executor_verified = AgentExecutor(agent=agent_with_verification, tools=tools, verbose=False, handle_parsing_errors=True)

Этот шаг уже дает прирост до ~59 баллов. Агент перестает выдавать откровенный брак. Но мы все еще не знаем, КАК он думает. Для этого нужен трейсинг.

3 Включаем детальный трейсинг и идем в LangSmith

LangSmith по умолчанию логирует вызовы. Но для отладки нужно больше деталей. Включаем максимально подробное логирование и используем LangSmith Fetch CLI, чтобы смотреть трейсы из терминала.

# В коде инициализации агента добавляем параметры для детального трейсинга
agent_executor_verified = AgentExecutor(
    agent=agent_with_verification,
    tools=tools,
    verbose=False,
    handle_parsing_errors=True,
    return_intermediate_steps=True,  # Ключевой параметр!
)

Запускаем несколько задач из Terminal Bench 2.0. Каждый запуск создает трейс в LangSmith с полной хронологией: какие инструменты вызывались, какие промпты отправлялись модели, что она отвечала.

А теперь самое важное: анализ паттернов ошибок.

Открываешь LangSmith UI, смотришь на трейсы неудачных выполнений. И видишь, например:

• Агент 4 раза подряд вызывает `ls`, вместо того чтобы прочитать файл.
• Инструмент верификации пропускает синтаксические ошибки в Python-коде.
• Агент не понимает, когда задача уже выполнена, и зацикливается.

Это — сырая золотая жила для оптимизации. Ты больше не гадаешь. Ты видишь.

4 Итеративное улучшение на основе данных из трейсов

Вот как превращаешь наблюдения в конкретные правки:

Проблема 1: Агент зацикливается на вызове `ls`.
Из трейса видно, что промпт не дает четкого критерия остановки. Фикс: Добавляем в системный промпт правило: "После успешного выполнения команды, проверь результат. Если результат соответствует условию задачи, НЕМЕДЛЕННО завершай работу, выдав итоговый ответ".

Проблема 2: Верификация пропускает ошибки.
Смотрим промпт внутри инструмента `verify_and_fix_code`. Он слишком общий. Фикс: Делаем его конкретнее под задачи Terminal Bench: "Проверь, что код: 1. Выполняет ровно то, что просили в задаче. 2. Не содержит команд rm -rf / или подобных деструктивных действий. 3. Использует наиболее эффективную команду для задачи (например, grep вместо комбинации cat и awk)."

Проблема 3: Агент плохо работает с путями.
Трейсы показывают, что он часто ошибается с относительными путями. Фикс: Добавляем в контекст перед выполнением задачи инструмент `pwd` и явно указываем: "Все пути должны быть либо абсолютными, либо относительными от текущей директории, которую ты знаешь."

После каждой правки — запускаешь набор тестов из Terminal Bench 2.0. Сравниваешь баллы. Смотришь, исчезли ли проблемные трейсы. Это цикл: трейсинг → анализ → гипотеза → изменение → валидация.

Где спрятаны грабли: частые ошибки при настройке

• Self-verification, который ничто не верифицирует: Слишком мягкий промпт для проверки. Он должен быть педантичным и скептичным. Лучше перепроверить, чем пропустить ошибку.
• Трейсинг без анализа: Получаешь тысячи трейсов, но не смотришь на них. Выделяй время раз в неделю на review ошибок. Или используй автоматические бенчмарки для постоянной оценки.
• Оптимизация под бенчмарк, а не под реальные задачи: Terminal Bench — отличный полигон. Но убедись, что правки, которые повышают баллы в бенчмарке, не ухудшают работу на твоих продакшен-задачах. Всегда тестируй на своем наборе.
• Игнорирование стоимости: Self-verification и детальный трейсинг удваивают количество вызовов LLM. Считай токены. Иногда проще позволить агенту ошибиться в 5% случаев, чем проверять все и платить в 2 раза больше.

Вопросы, которые ты хотел задать, но стеснялся

Самое большое заблуждение — думать, что производительность агента определяется в первую очередь моделью. На самом деле, качество обвязки часто важнее. Модель — это двигатель. Harness Engineering — это система управления, тормоза и рулевое. Можно поставить лучший двигатель в раздолбанную телегу, но ехать быстрее не станешь.

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

Подписаться на канал