EN
Связаться
Глава 23

Трассируйте решения, вызовы и границы

Обычный application log не показывает, почему появился worker, какой context он получил и где выросла стоимость. Нужен связный trace всего run: он связывает run, planning step, worker, model call, tool call, handoff, guardrail, artifact write и evaluation. Для каждого span нужны status, timing, usage, model и версии prompt/tool; полный prompt content записывайте только при осознанной privacy policy.

TypeScript
import type { AgentId, TraceSpan } from "./types.js";

interface OpenSpan {
  readonly id: number;
  readonly taskId: string;
  readonly agentId: AgentId;
  readonly attempt: number;
  readonly startedAt: number;
}

export class TraceRecorder {
  readonly #spans: TraceSpan[] = [];
  readonly #clock: () => number;
  #nextId = 1;

  public constructor(clock: () => number = Date.now) {
    this.#clock = clock;
  }

  public start(taskId: string, agentId: AgentId, attempt: number): OpenSpan {
    return { id: this.#nextId++, taskId, agentId, attempt, startedAt: this.#clock() };
  }

  public end(open: OpenSpan, status: "ok" | "error", detail: string): TraceSpan {
    const span: TraceSpan = {
      ...open,
      endedAt: this.#clock(),
      status,
      detail
    };
    this.#spans.push(span);
    return span;
  }

  public spans(): readonly TraceSpan[] {
    return this.#spans.map((span) => ({ ...span }));
  }
}

Смысл трассы виден по вопросам, на которые она должна отвечать.

Signal · Пример вопроса

  • Topology - Кто и почему породил лишние workers?
  • Latency - Какая ветвь находилась на critical path?
  • Usage - Какой context повторно оплачивался?
  • Quality - Какой finding привел к reject?
  • Security - Кто запросил tool и какая identity его выполнила?

OpenAI Agents SDK включает tracing model generations, tool calls, handoffs, guardrails и custom events. OpenTelemetry поддерживает semantic conventions для GenAI, но их stability и расположение развиваются - проверяйте текущую спецификацию перед жёсткой привязкой схемы.

Observability не должна стать утечкой. Prompts, tool arguments и outputs могут содержать secrets и персональные данные. По умолчанию собирайте metadata, hashes и redacted previews; полный content включайте только для ограниченных debug-runs.

Трасса показывает, что происходило. Оценивать же качество надо отдельно - и итог, и взаимодействие.

Ссылки