Observability для AI-агентів: моніторинг агентних систем

Ідея за 30 секунд

Observability для AI-агентів показує, що відбувається під час виконання одного run.

Агент може зробити десятки кроків: reasoning, tool calls, повторні виклики LLM.

Observability робить ці кроки видимими через трейсинг, логи і метрики.

Основна проблема

У класичному бекенді один HTTP-запит виконує передбачуваний код:

request → handler → database → response

Кількість кроків відома наперед, а поведінку легко відстежити через звичайні логи.

У системах з AI-агентами все працює інакше: один запит може перетворитися на run із кількома reasoning-кроками, викликами інструментів і повторними ітераціями.

Агент може зробити 2 кроки або 20. Може викликати кілька інструментів, повторити reasoning кілька разів і витратити більше токенів, ніж очікувалося.

Без observability складно відповісти навіть на базові питання:

• Чому запит обробляється повільно?
• Чому витрати токенів різко зросли?
• Чому агент викликає інструмент десятки разів?
• На якому кроці виникла помилка?

Для таких систем звичайних логів недостатньо. Observability потрібна, щоб бачити повний шлях виконання агента і швидко знаходити проблемні кроки під час debugging.

Як це працює

Observability для AI-агентів базується на трьох типах сигналів: трейси, логи і метрики. Разом вони дозволяють бачити як окремі запити, так і загальний стан системи.

Існують спеціалізовані інструменти для observability агентів (наприклад LangSmith, Langfuse, Arize Phoenix), але базові принципи однакові незалежно від інструмента.

Трейсинг

Трейсинг показує повний шлях виконання одного run агента. Кожен крок записується як подія: reasoning моделі, виклик інструмента або отримання результату. Трейс складається зі спанів (spans). Трейс — це весь шлях виконання (run), а спан — один крок усередині нього, наприклад виклик інструмента або reasoning.

run_id: 9fd2

step 1 — search_docs       420ms
step 2 — summarize         110ms
step 3 — generate_answer   890ms

Трейсинг показує, які інструменти викликав агент і скільки кроків він зробив. Також видно, де виникла помилка або затримка.

Як виглядає трейс агента

Найпростіше зрозуміти трейсинг на прикладі одного реального запиту.

Приклад трейсу одного запиту:

run_id: 9fd2
user_query: "Find recent research about battery recycling"

step 1  llm_reasoning        320ms
        thought: need to search research papers

step 2  tool_call: search    410ms
        query: battery recycling research 2024

step 3  llm_reasoning        180ms
        thought: summarize the most relevant papers

step 4  tool_call: fetch     260ms
        source: arxiv

step 5  llm_generate         720ms
        output: final answer

Такий трейс дозволяє швидко зрозуміти:

• які кроки виконав агент
• які інструменти були викликані
• скільки часу зайняв кожен крок
• де виникла затримка або помилка

У production системах трейс часто містить додаткову інформацію:

• run_id і trace_id для кореляції подій
• latency кожного кроку
• token usage LLM
• stop reason (completed, max_steps, tool_error)

Трейси корисні не лише для debugging. Вони також потрібні для evaluations. Без запису проміжних кроків важко автоматично перевірити, чи агент правильно діяв під час run, а не лише чи дав фінальну відповідь.

Логування

Логи фіксують події під час виконання агента:

• початок і завершення run
• виклики інструментів із параметрами
• помилки та винятки
• причина зупинки агента (stop reason)

Логи відповідають на питання «що сталося». Трейсинг — «як саме це сталося».

Метрики

Метрики показують загальний стан системи, а не один конкретний запит. Типові production-метрики для агентів:

Метрики потрібні для моніторингу системи та налаштування алертів у production. Метрики дозволяють швидко побачити аномалії: наприклад, раптове зростання token usage, latency або кількості tool calls.

Більшість LLM-провайдерів (OpenAI, Anthropic) повертають token usage у відповіді, тому це зазвичай не потрібно рахувати вручну — достатньо логувати ці поля.

Коли використовувати

Observability не завжди потрібна.

Для простих сценаріїв зазвичай вистачає базового логування. Наприклад, коли є один виклик LLM без tools і без циклу виконання.

Але як тільки з'являється run із кількома кроками — reasoning, tool calls, повторні ітерації — без observability стає складно дебажити систему, контролювати витрати і пояснювати її поведінку.

Приклад реалізації

Нижче — спрощений приклад instrumentation в agent runtime. У реальних системах ці події зазвичай відправляють у систему трейсингу або observability-платформу. У більшості runtime-систем кожен крок виконання представлений як step: це може бути reasoning моделі або виклик інструмента. Такий цикл (agent.iter) використовується у фреймворках на кшталт LangGraph, CrewAI і у власних runtime-реалізаціях.

import logging
import time
import uuid

logger = logging.getLogger("agent")

def run_agent(agent, task):
    run_id = str(uuid.uuid4())

    logger.info("agent_run_started", extra={
        "run_id": run_id,
        "task": task,
    })

    steps = []

    for step in agent.iter(task):  # step: reasoning або tool execution
        step_start = time.time()
        result = step.execute()
        latency = time.time() - step_start

        step_event = {
            "run_id": run_id,
            "step_type": step.type,  # reasoning | tool_call | llm_generate
            "tool": getattr(step, "tool_name", None),
            "latency": latency,
        }

        logger.info("agent_step", extra=step_event)
        steps.append(step_event)

        if result.is_final:
            break

    logger.info("agent_run_finished", extra={
        "run_id": run_id,
        "steps": len(steps),
    })

Інструменти можна обгорнути в wrapper і логувати як успішні виклики, так і помилки:

def traced_tool(tool_fn):
    def wrapper(*args, **kwargs):
        start = time.time()

        try:
            result = tool_fn(*args, **kwargs)
            logger.info(
                "tool_call",
                extra={
                    "tool": tool_fn.__name__,
                    "latency": time.time() - start,
                    "status": "ok",
                },
            )
            return result
        except Exception as error:
            logger.error(
                "tool_call_failed",
                extra={
                    "tool": tool_fn.__name__,
                    "latency": time.time() - start,
                    "error": str(error),
                },
            )
            raise

    return wrapper

Приклад вище показує базову логіку instrumentation. У production системах її зазвичай доповнюють кількома практиками:

• trace_id для кожного run
• структуровані логи (JSON)
• метрики latency і token usage
• інтеграцію з системами моніторингу

Наприклад, один запис структурованого логу може виглядати так:

{
  "timestamp": "2026-03-21T15:17:00Z",
  "level": "INFO",
  "event": "tool_call",
  "run_id": "9fd2...",
  "tool": "search_docs",
  "latency_ms": 410,
  "status": "ok"
}

У реальних системах run_id і trace_id потрібно прокидати через увесь ланцюг викликів. У Python для цього часто використовують contextvars, щоб не передавати ідентифікатор аргументом у кожну функцію.

Це допомагає бачити повний шлях виконання агента і швидко знаходити проблемні кроки.

Типові помилки

Навіть коли observability вже додано, системи з агентами часто залишаються складними для діагностики. Найчастіше через типові помилки нижче.

Логування лише фінальної відповіді

Якщо система записує лише фінальний результат, неможливо зрозуміти, як агент до нього прийшов. Тому важливо логувати кроки reasoning, виклики інструментів і stop reason. Без цього навіть прості інциденти після релізу важко розібрати.

Відсутність трейсів для викликів інструментів

Інструменти часто є найповільнішою частиною системи. Якщо виклики інструментів не потрапляють у трейсинг, складно зрозуміти:

• який tool дає затримку
• де саме виникає помилка
• чи агент викликає той самий tool повторно

У production це часто маскує спам інструментами або ранній етап каскадних збоїв.

Відсутність метрик витрат

Агенти можуть непомітно збільшувати витрати через довгі reasoning-цикли, повторні виклики LLM або зайві tool calls. Без метрик витрат це часто помічають лише після відчутного зростання рахунків. У результаті система може швидко перейти в дорогий і нестабільний режим роботи.

Логування сирих prompt-ів

Prompt-и можуть містити персональні дані, секрети або внутрішню інформацію. Перед записом у логи їх варто редагувати або анонімізувати. Інакше під час інцидентів у логах можуть опинитися чутливі дані.

Самоперевірка

Нижче — короткий checklist базової observability для production.

FAQ

Q: Чим відрізняються трейсинг, логи і метрики?
A: Трейсинг показує шлях одного run крок за кроком. Логи фіксують події та помилки. Метрики показують загальну картину за період (latency, error rate, token usage).

Q: Що впроваджувати першим, якщо observability ще немає?
A: Почни з мінімуму: run_id, структуровані логи і latency кожного кроку. Далі додай трейсинг викликів інструментів і ключові метрики (token usage, tool calls per run, error rate).

Q: Які поля найважливіші для debugging проблемного run?
A: Мінімум: run_id/trace_id, тип кроку, викликаний інструмент, latency кроку, stop reason, помилка (якщо була). Цього досить, щоб відтворити ланцюг подій.

Q: Чи обов'язково одразу використовувати зовнішні observability-інструменти?
A: Ні. Можна почати з власного instrumentation і структурованих логів. Спеціалізовані платформи мають сенс, коли зростає обсяг run'ів, кількість команд і потреба в централізованому аналізі.

Пов'язані сторінки

Далі за темою:

• Трейсинг агента — як відстежувати виконання одного run.
• Розподілений трейсинг агентів — трейсинг між кількома агентами.
• Метрики агентів — які показники вимірювати.
• Алерти збоїв агентів — як виявляти проблеми у production.
• Дебаг запусків агентів — як розбирати проблемні запити.