Какие ошибки делают команды, когда слишком рано превращают простой LLM workflow в агентскую систему?

Типичные ошибки при преждевременной агентификации

1. Агент там, где достаточно цепочки

Если задача детерминирована (всегда одна последовательность шагов), AgentExecutor добавляет недетерминизм, стоимость и сложность отладки без преимуществ. Правило: если можно нарисовать flowchart без ветвлений — нужна цепочка, не агент.

2. Нет ограничений на количество итераций

По умолчанию AgentExecutor не имеет жёсткого лимита. Агент может войти в цикл tool calls и израсходовать весь месячный бюджет за одну ночь.

# Правильно — всегда задавать max_iterations
executor = AgentExecutor(
    agent=agent,
    tools=tools,
    max_iterations=10,       # максимум 10 шагов
    max_execution_time=30.0, # максимум 30 секунд
    handle_parsing_errors=True,
)

3. Инструменты без схемы и описания

LLM выбирает инструмент по названию и docstring. Плохое описание → агент вызывает не тот инструмент или передаёт неверные аргументы.

# Плохо
@tool
def search(q): return results(q)

# Хорошо
@tool
def search_knowledge_base(query: str) -> str:
    """Ищет информацию в корпоративной базе знаний по ключевым словам или вопросу.
    Возвращает топ-3 релевантных документа. НЕ использовать для расчётов или кода."""
    return search_impl(query)

4. Нет обработки ошибок инструментов

Исключение внутри tool без handle_tool_errors=True падает в агента как строка ошибки, которую LLM пытается интерпретировать и часто зависает на ней.

executor = AgentExecutor(agent=agent, tools=tools, handle_tool_errors=True)

5. Отсутствие observability

Без трассировки невозможно понять, почему агент принял то или иное решение. Минимум — verbose=True в dev, LangSmith в production.

6. Агент вместо structured output

Если нужно извлечь структурированные данные из текста — используйте model.with_structured_output(MySchema), а не агента с инструментом-парсером. Это быстрее, дешевле и детерминировано.

7. Игнорирование параллелизма tool calls

GPT-4o может вызывать несколько инструментов параллельно. Если инструменты имеют побочные эффекты (запись в БД), параллельный вызов нарушит ожидаемый порядок. Отключите через parallel_tool_calls=False в bind_tools.

Подводные камни

• Недетерминизм агента делает воспроизводимые тесты сложными — мокайте LLM в юнит-тестах или используйте детерминированные fixture.
• Агентские системы дороже цепочек в 3–10 раз за счёт нескольких LLM-запросов — рассчитайте cost per request до перехода в production.
• AgentExecutor deprecated в пользу LangGraph — новые agentification-проекты лучше строить сразу на LangGraph с явным графом состояний.
• Многоагентные системы (несколько специализированных агентов) добавляют routing-проблему: как правильно передать задачу нужному агенту.
• Без memory агент не помнит предыдущие шаги между сессиями — для stateful диалогов нужен MemorySaver (LangGraph) или RunnableWithMessageHistory.

• Перечислять ошибки без объяснения причин
• Не отличать beginner mistakes от production failure modes
• Не предлагать процесс, который предотвращает повторение ошибок

• Знает типичные ошибки при работе с LangChain
• Понимает причины ошибок
• Предлагает практики prevention и early detection