Agent Builder — Подробное руководство
Полное, практическое руководство по созданию, тестированию, публикации и развертыванию многошаговых рабочих процессов агентов с помощью Agent Builder и Agents SDK.
Введение
Agent Builder — визуальная среда (canvas) для быстрой композиции, отладки и экспорта многошаговых агентных рабочих процессов. Она упрощает преобразование идей в готовые рабочие процессы: от шаблона — до публикации и встраивания в продукт через ChatKit или развёртывания на собственной инфраструктуре с помощью Agents SDK.
Это руководство объясняет принципы, термины, лучшие практики, примеры и контроль безопасности, чтобы вы могли: проектировать надёжные рабочие процессы, оценивать их и безопасно развертывать.
Ключевые понятия
- Workflow (рабочий процесс) — последовательность шагов (узлов), инструментов и логики контроля потока, которая описывает, как агент решает задачу.
- Node (узел) — атомарный строительный блок: старт, агент, поиск по файлам, MCP, guardrails, трансформ и т.д.
- Edge (ребро) — соединение между узлами; типизированный контракт данных между шагами.
- Trace (трасса) — лог исполнения рабочого процесса при прогоне (включает входы, выходы, вызовы инструментов, промежуточные данные и решения).
- Publish (публикация) — создание версии рабочего процесса с ID и версией, готовой к использованию в продуктах.
- Deploy (развёртывание) — интеграция опубликованного workflow в приложение (через ChatKit или SDK).
Когда использовать Agent Builder
Используйте Agent Builder если вам нужно:
- Составить сложную последовательность взаимодействий (несколько агентов, внешние вызовы, ветвления).
- Визуально видеть поток данных и типы между шагами.
- Быстро прототипировать шаблоны взаимодействия и тестировать с реальными/случайными данными.
- Подготовить рабочий процесс к встраиванию в продукт или экспорту кода.
Шаг за шагом: как строится рабочий процесс
1. Проектирование и запуск canvas
- Выберите шаблон или начните с пустого холста.
- Добавьте Start-узел и определите входные переменные (например, input_as_text, файлы, метаданные).
- Добавляйте последовательно узлы-агенты и инструментальные узлы (file search, MCP, guardrails и т.д.).
- Связывайте их ребрами и задавайте типы данных для контрактов между шагами.
Совет: для чат-рабочих процессов начинайте со Start-узла, который автоматически добавляет input_as_text в историю чата.
2. Конфигурирование agent-узлов
Каждый agent-узел содержит:
- Инструкции для модели (developer message / system prompt).
- Контекст (входы из предыдущих узлов, встраиваемые знания).
- Конфигурацию модели (например, использование GPT-5 / GPT-5-mini для повышенной дисциплины).
- Подключённые инструменты и проверки (guardrails, MCP).
- Требуемую структуру вывода (JSON-схема, enum, поля) — крайне рекомендуется для безопасности.
3. Добавление инструментов (tool nodes)
- File search — поиск по векторному хранилищу (vector store). Используйте для извлечения релевантных документов.
- MCP — подключение внешних сервисов (Gmail, Zapier, внутренние API). Всегда держите approvals/подтверждения если MCP делает запись/изменение.
- Guardrails — правила для входных данных: PII-детектор, jailbreak-детектор, формальные валидации.
4. Логика и контроль потока
- If/Else — ветвление на основе CEL-выражений.
- While — циклы по условию.
- Human approval — получение подтверждения от пользователя перед критическими операциями (чтение/запись).
5. Трансформации и состояние
- Transform — приведение типов, изменение структуры (object → array), фильтрация.
- Set state — глобальные переменные, доступные везде в workflow.
Практический пример: помощник по домашним заданиям
Цель: пользователь задаёт вопрос; система перенаправляет запросы к подходящему специализированному агенту и возвращает краткий, проверенный ответ.
Примерная последовательность:
- Start — получает input_as_text.
- Agent A — переписывает вопрос для улучшенной релевантности (рефрейминг).
- Agent B — классифицирует: Q&A | Поиск фактов | Сложный сценарий.
- If/Else — в зависимости от классификации:
- 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).
- SDK поддерживает: загрузку workflow, запуск трасс, получение логов, интеграции с внешними инструментами.
Примерный сценарий использования SDK:
- Загрузить/скачать опубликованный 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/печати.
Напишите, что добавить или уточнить — и я обновлю документ.
