blog/prakticheskoe-rukovodstvo-po-sozdaniyu-agentov.md

Практическое руководство по созданию цифровых агентов для автоматизации процессов

Практическое руководство по созданию агентов

17.4.2025

Практическое руководство по созданию агентов

💡 Это официальный документ от OpenAI, переведённый на русский язык.

‍Источник

5 минут

‍Практическое руководство по созданию агентов

Введение

Большие языковые модели (LLM) становятся всё более способными выполнять сложные, многошаговые задачи. Прогресс в рассуждении, мультимодальности и использовании инструментов открыл новую категорию LLM-систем — агенты.

Это руководство предназначено для продуктовых и инженерных команд, создающих своих первых агентов. В нём собраны практические рекомендации и лучшие практики: как выявить подходящие кейсы, спроектировать логику и оркестрацию агента, и как обеспечить его безопасность и предсказуемость.

После прочтения вы получите базовые знания, необходимые для уверенного старта.

Что такое агент?

Обычное ПО помогает автоматизировать задачи, но агенты выполняют эти задачи самостоятельно от имени пользователя.

Агент — это система, которая самостоятельно выполняет рабочие процессы с высокой степенью автономии.

Примеры рабочих процессов: решение вопроса клиента, бронирование ресторана, коммит в репозиторий, создание отчёта.

Важно: если LLM не управляет выполнением процесса, а лишь обрабатывает отдельные шаги (например, чат-бот, классификатор), это не агент.

Характеристики агента:

Использует LLM для принятия решений и управления процессом. Понимает завершённость задачи, может исправить действия или вернуть контроль человеку при ошибке.
Имеет доступ к инструментам (API, UI) и выбирает подходящие в зависимости от текущего состояния задачи, действуя в рамках защитных механизмов (guardrails).

Когда стоит создавать агента?

Создание агентов — это переосмысление того, как системы принимают решения и справляются со сложностью.

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

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

Идеальные кейсы для агентов:

Сложные решения: работа с неоднозначностями (например, возвраты в поддержке).
Сложные правила: системы с громоздкими условиями (например, проверка поставщиков).
Неструктурированные данные: понимание текста, диалога, документов (например, страховые заявления).

‍ {{cta}}

Основы проектирования агентов

Базовые компоненты агента:

Модель — LLM, принимающая решения.
Инструменты — API, функции, UI-действия.
Инструкции — описание поведения и ограничений.

Пример (Python):

python

CopyEdit

weather_agent = Agent(
   name="Weather agent",
   instructions="You are a helpful agent who can talk to users about the weather.",
   tools=[get_weather],
)

‍

Выбор моделей

Разные модели подходят для разных задач: не всегда нужна самая “умная”.

Подход:

Постройте прототип на самой сильной модели.
Потом пробуйте заменить задачи на менее дорогие модели.

Принципы:

Запускайте eval-тесты.
Используйте лучшие модели для важной логики.
Оптимизируйте стоимость и задержку, снижая модель, где возможно.

Руководство по выбору моделей OpenAI

Определение инструментов

Инструменты — это API и функции, которые агент может вызывать.

Если API нет, используйте UI-интеракции, как делает человек.

Типы инструментов:

Тип	Назначение	Примеры
Данные	Получение контекста	Поиск в базе, PDF, интернет
Действия	Изменение состояния	Email, обновление CRM
Оркестрация	Вызов других агентов как инструментов	агент-писатель, агент-исследователь

Пример:

python

CopyEdit

@function_tool
def save_results(output):
    db.insert({"output": output, "timestamp": datetime.time()})
    return "File saved"

search_agent = Agent(
    name="Search agent",
    instructions="Help the user search the internet and save results if asked.",
    tools=[WebSearchTool(), save_results],
)

‍

Настройка инструкций

Чёткие инструкции — залог успеха. Чем конкретнее — тем меньше ошибок.

Лучшие практики:

Используйте существующие регламенты и инструкции.
Разбивайте задачи на пошаговые действия.
Определяйте чёткие действия и результаты.
Учитывайте исключения и варианты (например, если пользователь не дал данные).

Пример генерации инструкций:

text

CopyEdit

“Вы эксперт по написанию инструкций для LLM-агента. Преобразуйте следующий документ из базы знаний в пошаговые инструкции в виде списка. Убедитесь, что всё чётко и без двусмысленностей.”

Оркестрация

Оркестрация — это структура выполнения задач агентом или группой агентов.

Варианты:

Одиночный агент — выполняет весь процесс.
Множественные агенты — делят обязанности и вызывают друг друга.

Одиночный агент

Управляет всеми инструментами и логикой. Работает в цикле до завершения задачи.

python

CopyEdit

Agents.run(agent, [UserMessage(“What’s the capital of the USA?”)])

‍

Можно использовать шаблоны:

python

CopyEdit

“You are a call center agent talking to {{user_first_name}}. Their complaints are about {{user_complaint_categories}}…”

‍

Когда делить на несколько агентов:

Сложная логика (много условий).
Перегрузка инструментов.
Разделение по задачам (поиск, генерация, верификация и т.п.)

Множественные агенты

Шаблоны:

Менеджер — центральный агент вызывает подчинённых.
Децентрализация — агенты передают друг другу контроль.

Паттерн менеджера

python

CopyEdit

manager_agent = Agent(
    name="Manager",
    instructions="If asked for multiple translations, call the relevant tools.",
    tools=[
        spanish_agent.as_tool(tool_name="translate_to_spanish", tool_description="..."),
        french_agent.as_tool(tool_name="translate_to_french", tool_description="..."),
        italian_agent.as_tool(tool_name="translate_to_italian", tool_description="..."),
    ],
)

await Runner.run(manager_agent, "Translate 'hello' to Spanish, French and Italian for me!")

‍

Децентрализованный паттерн

python

CopyEdit

triage_agent = Agent(
    name="Triage Agent",
    instructions="Assess the query and direct to appropriate agent.",
    handoffs=[technical_support_agent, sales_assistant_agent, order_management_agent],
)

await Runner.run(triage_agent, "Could you provide an update on the delivery?")
triage_agent = Agent(
    name="Triage Agent",
    instructions="Assess the query and direct to appropriate agent.",
    handoffs=[technical_support_agent, sales_assistant_agent, order_management_agent],
)

await Runner.run(triage_agent, "Could you provide an update on the delivery?")

‍

Защитные механизмы (Guardrails)

Guardrails — это меры для обеспечения безопасности, конфиденциальности и корректности.

Типы защит:

Классификатор релевантности — отклоняет не по теме.
Фильтр безопасности — защищает от prompt injection.
PII фильтр — проверяет на утечку персональных данных.
Модерация — фильтрует токсичный контент.
Оценка риска инструментов — при высоком риске — подтверждение от человека.
Фильтры и блоклисты — регулярные выражения, ограничения по длине.
Валидация ответа — проверка соответствия бренду и тону общения.

Пример Guardrail на отток клиента:

python

CopyEdit

class ChurnDetectionOutput(BaseModel):
    is_churn_risk: bool
    reasoning: str

@input_guardrail
async def churn_detection_tripwire(ctx: RunContextWrapper, agent: Agent, input: str):
    result = await Runner.run(churn_detection_agent, input, context=ctx.context)
    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_churn_risk,
    )

customer_support_agent = Agent(
    name="Customer support agent",
    instructions="You help customers with their questions.",
    input_guardrails=[
        Guardrail(guardrail_function=churn_detection_tripwire),
    ],
)