Полное, практическое руководство по созданию, тестированию, публикации и развертыванию многошаговых рабочих процессов агентов с помощью Agent Builder и Agents SDK.
Введение
Agent Builder — визуальная среда (canvas) для быстрой композиции, отладки и экспорта многошаговых агентных рабочих процессов. Она упрощает преобразование идей в готовые рабочие процессы: от шаблона — до публикации и встраивания в продукт через ChatKit или развёртывания на собственной инфраструктуре с помощью Agents SDK.
Это руководство объясняет принципы, термины, лучшие практики, примеры и контроль безопасности, чтобы вы могли: проектировать надёжные рабочие процессы, оценивать их и безопасно развертывать.
Ключевые понятия
Workflow (рабочий процесс) — последовательность шагов (узлов), инструментов и логики контроля потока, которая описывает, как агент решает задачу.
Node (узел) — атомарный строительный блок: старт, агент, поиск по файлам, MCP, guardrails, трансформ и т.д.
Edge (ребро) — соединение между узлами; типизированный контракт данных между шагами.
Trace (трасса) — лог исполнения рабочого процесса при прогоне (включает входы, выходы, вызовы инструментов, промежуточные данные и решения).
Publish (публикация) — создание версии рабочего процесса с ID и версией, готовой к использованию в продуктах.
Deploy (развёртывание) — интеграция опубликованного workflow в приложение (через ChatKit или SDK).
Q&A → Agent C (короткие ответы, knowledge base lookup)
Поиск фактов → File Search + Agent D (сбор доказательств)
Сложный сценарий → Human approval → MCP (если нужно действие)
Transform → собрать финальную структуру ответа (summary, citations, confidence).
Set state → сохранить основные факты в глобальное состояние (для последующих диалогов).
Важный момент: между агентами используйте структурированные выходы — это уменьшает риск prompt injection.
Отладка и предпросмотр
Agent Builder предоставляет Preview — интерактивный режим исполнения рабочего процесса:
Прогон с реальными/sample данными.
Пошаговая оглядка трассы исполнения (trace), включая входы/выходы каждого узла.
Поддержка прикрепления файлов и проверки поиска по векторным хранилищам.
Используйте preview для:
Поиска логических ошибок в ветвлениях и трансформациях.
Проверки типизации данных и контрактов между узлами.
Настройки guardrails и human approval flows.
Публикация и версионирование
Agent Builder автоматически сохраняет промежуточную работу, но когда вы готовы — публикуйте workflow. Публикация создаёт снимок (major version) с уникальным ID, который можно передать в ChatKit или скачать в виде SDK-кода.
Поддерживаются множественные версии — вы можете указать конкретную версию при вызове API.
Встраивание и развертывание
Два основных пути развертывания:
1. ChatKit (рекомендуется)
Самый простой путь встраивания: подключите ChatKit и передайте ID опубликованного workflow.
ChatKit обрабатывает UI, историю чат-сессий и фронтенд-интеграции.
2. Advanced integration (Agents SDK)
Скачайте код из Agent Builder → Code.
Используйте Agents SDK (Python или TypeScript) для запуска workflow на ваших серверах.
Подходит для более тонкой кастомизации, интеграции со внутренними системами и соблюдения корпоративных политик.
Пример (псевдокод) — вызов опубликованного workflow через SDK:
# Псевдопример — концепция
from openai_agents import AgentsClient
client = AgentsClient(api_key="YOUR_KEY")
result = client.run_workflow(
workflow_id="your-workflow-id",
version="v1",
inputs={"input_as_text": "Как решить задачу по физике про наклонную плоскость?"}
)
print(result.outputs)
Оценка качества: trace graders и evals
Trace grading — запустить оценку на конкретных трассах, чтобы автоматически подсчитать метрики и получить аннотации в местах ошибок.
Evals — использовать для более глубинного тестирования моделей и рабочих процессов.
Регулярно запускайте оценки при изменениях в workflow: это помогает обнаружить регрессии и непредвиденные побочные эффекты.
Безопасность и риски
Разработка агентных рабочих процессов порождает новые риски. Ниже — обзор типов угроз и рекомендации по снижению рисков.
Основные риски
Prompt injection — вредоносные или неконтролируемые данные, встраиваемые в контекст, которые могут переопределить инструкции и заставить модель выполнить нежелательные действия.
Протечка приватных данных — случайная или злонамеренная передача конфиденциальной информации в внешние инструменты (особенно через MCP).
Непредусмотренные действия — модели могут принимать решения (например, отправка писем, удаление данных), которые выходят за рамки допустимого.
Митигирующие меры (практики)
Не вставляйте недоверенные переменные в developer messages.
Передавайте пользовательский ввод как user message.
Используйте структурированные выходы.
Ограничьте свободу генерации модели: JSON-схемы, enums, обязательные поля.
Включайте guardrails.
Проставляйте проверки на PII, jailbreak и формальные валидации.
Держите tool approvals включёнными для MCP.
Пользователь должен подтверждать любые операции записи или критические чтения.
Выделяйте критические шаги за human approval.
Например, отправка писем, массовые удаление, операции с финансами.
Разделяйте привилегии и минимизируйте доступ.
Давайте агентам только ресурсы, которые им действительно нужны.
Используйте более строгие модели (GPT-5, GPT-5-mini)
Эти модели, как правило, лучше придерживаются инструкций и устойчивее к jailbreak-атакам.
Регулярно запускать trace graders и evals.
Автоматическое тестирование и ручные ревью.
Архитектурные рекомендации
Проектируйте рабочие процессы так, чтобы недоверенные данные никогда напрямую не определяли поведение критических узлов.
Экстрагируйте только проверенные/валидированные поля (enum/числа) для управляющих решений.
Логируйте каждый вызов MCP и делайте аудит доступа.
Руководство по лучшим практикам (checklist)
Перед публикацией рабочего процесса пройдите этот чеклист:
Все agent-узлы имеют чёткие инструкции и ожидаемые типы вывода.
Между узлами определены строгие схемы (JSON / enums).
Guardrails настроены на входящих и исходящих данных.
Для всех MCP-вызовов есть human approval (если изменение/чтение чувствительных данных).
Протестировали сценарии с краевыми и злонамеренными вводами.
Запустили trace grading на репрезентативных трассах.
Версионировали публикацию и документировали изменения.
Частые ошибки и способы их избежать
Ошибка: Использование свободного текста из пользователя прямо в system/developer message.
Как избежать: Всегда передавайте пользовательский ввод как user message, а developer message держите только для инструкций и правил.
Ошибка: Отсутствие структурированных выходов.
Как избежать: Требуйте JSON-схемы с проверяемыми полями; используйте Transform для коррекции формата.
Ошибка: MCP-вызовы без подтверждения.
Как избежать: Включите human approval и логирование.
Примеры расширений и интеграций
Автоматическая генерация ответов поддержки: классификация, поиск в базе знаний, формирование шаблона ответа, human approval для спорных кейсов.
Ассистент задач (task automation): agent генерирует черновик письма → human approval → MCP (Gmail API) для отправки.
Проверка контента / модерация: guardrails для PII/токсичности + transform для удаления чувствительной информации.
Agents SDK — быстрый путеводитель
Agents SDK предоставляет програмный интерфейс для создания и запуска рабочих процессов вне UI. Доступны реализации на Python и TypeScript.
Репозитории: openai/openai-agents-python и openai/openai-agents-js (документация на developers.openai.com в разделе agents).
Загрузить/скачать опубликованный workflow (ID + version).
Передать входные данные и опциональные файлы.
Подождать завершения трассы и прочитать outputs и trace.
Сохранять trace для последующей оценки и аудита.
FAQ (коротко)
Нужно ли использовать ChatKit?
ChatKit удобен и быстр для встраивания. Если вам нужен полный контроль и вы хотите хостить всё сами — используйте Agents SDK.
Как защищать данные пользователей?
Используйте guardrails, human approvals, минимальный доступ и структурированные форматы. Логируйте и проверяйте вызовы MCP.
Можно ли отменить публикацию?
Публикация создаёт версию. Вы можете публиковать новые версии и указывать, какую версию использовать. Политики удаления/архивации зависят от платформы/аккаунта.
Заключение и дальнейшие шаги
Agent Builder — мощный инструмент, который ускоряет создание сложных агентных процессов, но требует дисциплины в проектировании, безопасности и тестировании. Начните с простых шаблонов, добавляйте guardrails и trace grading на ранних стадиях, и постепенно усложняйте ваши рабочие процессы.
Рекомендации:
Начните с существующих шаблонов и постепенно расширяйте узлы.
Всегда требуйте структурированные выходы.
Интегрируйте human approval в критические места.
Автоматизируйте тестирование с помощью trace graders и evals.
Если хотите, я могу:
Добавить готовые примеры JSON-схем для структурированных выходов;
Включить более детальные примеры кода для Python/TypeScript (Agents SDK);
Подготовить чеклист для аудита безопасности в формате PDF/печати.
Напишите, что добавить или уточнить — и я обновлю документ.