Practical notes: минимально жизнеспособная платформа для экспериментов с ИИ-агентами

В следующих заметках описывается практический подход к созданию «минимальной жизнеспособной платформы для экспериментов с ИИ-агентами». Основное внимание уделяется контрактам, проверкам и местам для вставки кода, а не мотивирующим аспектам. На этапе обзора сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.

agent runtime
memory and retrieval
system prompt
model
tools
guardrails
application logic

should version B replace version A?

Определение того, что такое B на самом деле

Наиболее эффективно этот этап определения того, что представляет собой B, работает при рассмотрении его как измеримой поверхности. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым объектам, определите критерии успешного выполнения и не соглашайтесь на молчаливое частичное завершение работы. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов.

A = agent-v17
B = agent-v18

pipeline:
  name: support-agent
  version: 18

components:

  runtime:
    artifact: agent-runtime@sha256:...

  memory:
    artifact: memory-service@sha256:...
    configuration:
      strategy: hybrid
      top_k: 8

  model:
    route: support
    model: provider/model-x

  prompt:
    artifact: sha256:...

  tools:
    - artifact: customer-lookup@sha256:...
    - artifact: refund-tool@sha256:...

model X vs model Y

memory top_k=5 vs top_k=8

Задание не является (еще одной) производственной зависимостью

Задание не является ещё одним этапом работы — оно лучше всего рассматривается как измеримая структура. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте время выполнения, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить возобновление работы после прерываний.

request
user
session
workflow_instance

workflow_instance = migration-8291
variant           = B
pipeline          = agent-v18

Задание — это не элемент экспозиции

Подход «The Assignment is not exposure stage» работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Сохраняйте состояние графа простым и типизированным. Вложенные структуры скрывают информацию о том, какой узел записал какое поле, и мешают возобновлению работы после прерываний. Подход «The Assignment is not exposure stage» работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций.

ASSIGNMENT
user-18271 → B

EXPOSURE
memory-v2 retrieval started

assigned          10,428
exposed            8,912
exposure rate      85.46%

assigned_variant = B
realized_model   = X
fallback_reason  = provider_unavailable

Трейсы объясняют, что произошло

Для этапа «Трейсы» необходимо объяснить, что произошло, определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными данными. Дайте названия результатам работы, определите критерии успеха и не допускайте молчаливого частичного завершения. Внедряйте утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не эквивалентно полноте обработки в бизнес-процессах.

experiment.id
experiment.version
experiment.variant
experiment.assignment_id

pipeline.id
pipeline.version

execution.purpose

B has a lower task completion rate

show failed B traces

assignment
exposure
outcome
feedback
evaluation

Офлайн-оценка использует ту же схему обработки

Для офлайн-оценки необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат заранее предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Необходимо ввести человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты функционала в бизнес-среде.

prompt
expected answer

scenario:
  id: duplicate-charge-001

input:
  message: >
    I was charged twice for order 9811.

environment:
  fixture: duplicate-charge-customer

expected:
  refund_count: 1
  ticket_status: resolved

limits:
  max_turns: 15
  max_tool_calls: 20
  max_cost: 0.50

REPLAY_DIVERGED

Теневое выполнение сокращает разрыв между офлайн- и производственной средами

Для реализации Shadow Execution Bridges необходимо заранее определить этапы выполнения, входные данные, ответственного за шаг и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Вводите человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты бизнес-логики. Для реализации Shadow Execution Bridges необходимо заранее определить этапы выполнения, входные данные, ответственного за шаг и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретную причину, а не на целый комплекс факторов.

угловатый трубопровод.

latency
cost
tool usage
model fallbacks
guardrail failures
judge scores
trajectory differences

Не всему нужен судья в виде LLM

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

refund_count == 1
ticket_status == resolved

helpfulness
clarity
tone
quality of explanation

evaluator
evaluator version
judge model
judge prompt
rubric

О! Что касается статистики

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

A/B allocation
binary metrics
continuous metrics
95% confidence intervals
sample ratio mismatch detection
fixed-horizon analysis

Experiment
support-agent-v18

Randomization
user

Primary metric
ticket resolution

A       81.4%
B       85.1%

Difference
+3.7 percentage points

95% CI
[...]

Experiment health
SRM PASS

4 model calls

47 model calls

max cost / execution
max tokens / execution
max agent turns
max tool calls
max variant spend / hour

Variant B

SRM                PASS
Error rate         PASS
Cost / request     +312%

Circuit breaker    TRIPPED
New exposure       PAUSED

Что создавать в первую очередь

При работе над этапом «Что сначала создать» сначала запишите условия работы системы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Храните конфигурацию отдельно от кода приложения. Файлы с настройками окружения, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Создавайте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова оплачивать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг. При работе над этапом «Что сначала создать» сначала запишите условия работы системы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Воздерживайтесь от использования обширных скриптов в пользу небольших, тестируемых единиц кода. При сбое какого-либо шага причина неудачи должна указывать на конкретную ответственность, а не на запутанную структуру обработки данных.

assignment
exposure
outcome
feedback
evaluation

what was randomized
what treatment was assigned
what treatment actually ran
what pipeline version produced the execution
what outcome was measured
how that outcome was evaluated

What exactly did we run?
What happened when we ran it?
Did assigning users to B improve the outcome we care about?

Чек-лист операционной работы

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

Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами, добавляемыми позже.

Внедряйте утверждение человеком для операций, связанных с тратой денег или изменением производственных данных. Настройки, выполняемые во время компиляции, не гарантируют полноты функционала продукта.

Напишите краткое руководство: как обновлять ключи, как опустошать очередь, как откатить последнюю загрузку данных.

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

Внедряйте человеческое утверждение для операций, связанных с тратой средств или изменением производственных данных. Компиляционная настройка не гарантирует полноты функционала бизнес-приложения.

Перед внедрением всей стек-технологии заморозьте версии, сохраните эталонные записи для критически важных этапов и уточните шаги отката. В совместных средах необходимы ограничения на частоту запросов, проверки принадлежности пользователя и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, чем креативные одноразовые демонстрации.

Примечание для версии 35a4ad1bbf8c: не храните ключи поставщика в репозитории, установите лимит токенов на сессию и сохраняйте записи рядом с фикстурами для оценки, чтобы последующие замены моделей оставались сопоставимыми.

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

Деталь усиления безопасности 0/952: измерьте время выполнения, класс ошибки и расход токенов для данной записки, затем решите, следует ли сохранять изменение на основе фиксированного набора критериев, а не на основе устных оценок.

Этап 1 записки по усилению безопасности лучше всего работает, если рассматривать его как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.

Подробности усиления безопасности 1/952: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.

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

Подробности усиления безопасности 2/952: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.

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

Подробность усиления безопасности 3/952: измеряйте время выполнения, класс ошибки и расход токенов для данной инструкции, затем принимайте решение о сохранении изменений на основе определенного набора критериев, а не на основе устных замечаний.

Четвертый этап инструкций по усилению безопасности лучше всего работает, если рассматривать его как измеримую область. Соберите один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. Когда какой-то шаг не срабатывает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.

Подробности усиления безопасности 4/952: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных случаев.

На этапе 5 записи о усилении безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды.

Подробности усиления безопасности 5/952: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных случаев.