Практическое руководство по созданию агентов
Введение
Большие языковые модели (LLM) становятся всё более способными выполнять сложные, многошаговые задачи. Прогресс в рассуждении, мультимодальности и использовании инструментов открыл новую категорию LLM-систем — агенты.
Это руководство предназначено для продуктовых и инженерных команд, создающих своих первых агентов. В нём собраны практические рекомендации и лучшие практики: как выявить подходящие кейсы, спроектировать логику и оркестрацию агента, и как обеспечить его безопасность и предсказуемость.
После прочтения вы получите базовые знания, необходимые для уверенного старта.
Что такое агент?
Обычное ПО помогает автоматизировать задачи, но агенты выполняют эти задачи самостоятельно от имени пользователя.
Агент — это система, которая самостоятельно выполняет рабочие процессы с высокой степенью автономии.
Примеры рабочих процессов: решение вопроса клиента, бронирование ресторана, коммит в репозиторий, создание отчёта.
Важно: если LLM не управляет выполнением процесса, а лишь обрабатывает отдельные шаги (например, чат-бот, классификатор), это не агент.
Характеристики агента:
- Использует LLM для принятия решений и управления процессом. Понимает завершённость задачи, может исправить действия или вернуть контроль человеку при ошибке.
- Имеет доступ к инструментам (API, UI) и выбирает подходящие в зависимости от текущего состояния задачи, действуя в рамках защитных механизмов (guardrails).
Когда стоит создавать агента?
Создание агентов — это переосмысление того, как системы принимают решения и справляются со сложностью.
В отличие от классической автоматизации, агенты полезны там, где правило-подобные системы не справляются.
Пример: традиционная система выявляет мошенничество по шаблонам, а агент анализирует контекст, улавливает нетипичные сигналы и действует как "опытный следователь".
Идеальные кейсы для агентов:
- Сложные решения: работа с неоднозначностями (например, возвраты в поддержке).
- Сложные правила: системы с громоздкими условиями (например, проверка поставщиков).
- Неструктурированные данные: понимание текста, диалога, документов (например, страховые заявления).
Основы проектирования агентов
Базовые компоненты агента:
- Модель — 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-интеракции, как делает человек.
Типы инструментов:
Пример:
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),
],
)
Вмешательство человека
Иногда агент не справляется — нужен человек. Это особенно важно вначале, для сбора ошибок и улучшения.
Когда вмешиваться:
- Превышен лимит попыток.
- Высокий риск действия (например, возврат денег).
Заключение
Агенты — это новый этап автоматизации, где системы:
- Рассуждают,
- Действуют через инструменты,
- Выполняют сложные задачи с высокой автономией.
Советы:
- Начинайте с одного агента и постепенно расширяйтесь.
- Обеспечьте безопасность с помощью guardrails.
- Используйте модели, инструменты и инструкции с умом.
- Ориентируйтесь на итерации и улучшения.
