Отладка и паттерны ошибок агентов

Короткая версия

В 2026 главные классы agent bugs обычно такие:

1. Loop / stall failures
2. Tool-selection and tool-argument failures
3. Context and state bugs
4. Handoff / routing failures
5. Evaluation and policy failures
6. Silent quality regressions

Самая практичная модель debugging:

• включить traces по умолчанию;
• логировать tool inputs/outputs и run state;
• иметь stop conditions;
• хранить golden tasks и regression evals;
• разбирать failure не по “общему ощущению”, а по конкретному trace segment.

Агент три раза подряд вызывает один и тот же поиск, каждый раз без нового сигнала. Что это?

1. Trace-first debugging

Главный сдвиг 2026: агент debugging начинается не с промпта, а с trace.

Что должно быть видно в trace:

• user goal;
• active agent;
• tool calls;
• tool outputs;
• handoffs;
• guardrail decisions;
• evaluator verdicts;
• финальный result / stop reason.

OpenAI Agents SDK прямо делает tracing built-in и по умолчанию пишет:

• agent runs;
• LLM generations;
• function spans;
• handoff spans;
• guardrail spans;
• audio spans для voice pipelines.

LangSmith и Langfuse решают ту же инженерную задачу через более vendor-neutral observability stack.

2. Loop и stall failures

Это самый частый класс проблем.

Признаки:

• агент повторяет один и тот же tool call;
• agent alternates по схеме A -> B -> A -> B;
• run растёт по токенам, но не приближается к outcome;
• модель не умеет признать failure state.

Причины:

• нет stop conditions;
• нет явного state not_found / blocked / needs_user;
• tool outputs слишком шумные;
• agent не умеет переоценивать план.

Что помогает:

• max_steps;
• лимит по времени и токенам;
• repeat detection;
• state machine с terminal failure states;
• evaluator или policy step, который может остановить run.

3. Tool-selection failures

Модель выбрала не тот tool, либо выбрала правильный tool с неправильными аргументами.

Типовые причины:

• похожие по смыслу tools;
• неясные описания;
• плохой schema contract;
• слишком много tools в одном агенте.

Лучшие практики 2026:

• чёткие имена tools;
• строгие schema (strict / validation);
• bounded toolset для конкретного агента;
• pre-routing до выбора specialist agent;
• tool-level guardrails для risky actions.

4. Context и state bugs

Очень часто агент ломается не из-за reasoning, а из-за неправильного context assembly.

Типовые симптомы:

• потеря цели в середине run;
• забытые ограничения;
• duplicated context;
• retrieval noise;
• conflict между memory и текущим user input.

Это обычно не “модель тупит”, а одна из проблем:

• слишком длинный prompt;
• неудачная summazization;
• stale memory;
• неправильный handoff payload;
• плохая приоритизация контекста.

5. Handoff и routing failures

По мере роста multi-agent систем растёт и класс ошибок, связанных не с tool use, а с orchestration:

• роутер выбрал не того specialist;
• handoff случился слишком рано;
• manager держит слишком широкий prompt;
• specialist потерял часть состояния;
• следующий агент получил не тот task framing.

OpenAI Agents SDK полезен именно тем, что явно разводит:

• agents as tools;
• handoffs.

Это делает отладку проще: вы хотя бы видите, где был routing decision и кто стал owner следующего шага.

6. Evaluation failures

Многие системы падают не в основном agent loop, а на quality gate:

• evaluator слишком мягкий;
• evaluator слишком строгий;
• generator и evaluator конфликтуют по критериям;
• feedback не actionable;
• цикл improvement не ограничен.

Это production-версия старой проблемы “reflection ради reflection”.

Хороший evaluator loop:

• имеет чёткие rubric;
• ограничен по итерациям;
• пишет pass/fail outcome;
• логирует feedback в trace.

7. Silent regressions

Самые дорогие ошибки часто silent:

• успешный run technically completes;
• user gets answer;
• но quality, latency или cost становятся хуже.

Поэтому agent debugging нельзя отделять от evals и observability:

• golden tasks;
• regression dashboards;
• cost per successful run;
• average steps;
• escalation rate;
• tool error rate;
• final outcome quality.

8. Observability stack для агентов

Практический стек обычно включает:

LangSmith и Langfuse особенно полезны, когда нужна:

• trace inspection;
• datasets / feedback loops;
• dashboarding;
• alerts;
• experiment comparison.

9. Самые частые корни проблем

Большинство багов сходится к одному из пяти корней:

1. плохой orchestration pattern;
2. слабые tool contracts;
3. noisy context;
4. отсутствие terminal states;
5. отсутствие trace/eval loop.

То есть agent debugging почти всегда architectural, а не purely prompt-editing job.

Минимальная failure taxonomy

Полезно сразу размечать failures по типам:

from enum import Enum


class FailureType(str, Enum):
    LOOP = "loop"
    WRONG_TOOL = "wrong_tool"
    BAD_ARGS = "bad_args"
    CONTEXT_LOSS = "context_loss"
    HANDOFF = "handoff_failure"
    POLICY = "policy_failure"
    QUALITY = "quality_failure"

Это банально, но без такой taxonomy dashboard быстро превращается в шум.

Repeat detector

import json
import hashlib


class RepeatDetector:
    def __init__(self, threshold: int = 2):
        self.threshold = threshold
        self.seen = {}

    def check(self, tool_name: str, args: dict) -> bool:
        key = hashlib.sha256(
            f"{tool_name}:{json.dumps(args, sort_keys=True)}".encode()
        ).hexdigest()
        self.seen[key] = self.seen.get(key, 0) + 1
        return self.seen[key] >= self.threshold

Если агент дважды делает один и тот же бесполезный вызов, это уже сигнал не “дать ему ещё подумать”, а остановить run или перевести его в blocked / not_found.

Trace enrichment

def trace_metadata(task_id: str, user_id: str, workflow_name: str) -> dict:
    return {
        "task_id": task_id,
        "user_id": user_id,
        "workflow_name": workflow_name,
    }

Не храните только raw events. Привязывайте traces к business identifiers:

• task_id;
• customer_id или thread_id;
• workflow_name;
• experiment / prompt version.

Golden-task regression

def run_regression(agent_runner, tasks: list[dict]):
    results = []
    for task in tasks:
        outcome = agent_runner(task["input"])
        results.append({
            "task_id": task["id"],
            "success": task["expected_substring"] in outcome,
        })
    return results

Даже примитивный regression harness уже лучше, чем “кажется, после правок агент стал умнее”.

С чего начать отладку, если агент стал отвечать дольше и хуже после добавления ещё двух tools?

Проверьте себя