Создание агента: первые шаги

Как вы поняли из прошлого урока, простейший агент — это большая языковая модель. Она снабжена историей переписки, дополнительными знаниями и инструментами. Сегодня вы узнаете, как реализовать простейшего агента на Responses API в облаке Yandex Cloud.

В этом уроке вы начнёте проект по созданию своего агента с помощью библиотеки OpenAI и Responses API.

Вы также можете создать более простого агента прямо в интерфейcе AI Studio — вам поможет лабораторная работа «Агент-Аналитик рынка ИИ».💻 В данном и последующих уроках приводятся фрагменты кода. Мы рекомендуем по ходу изучения материала, собирать единый сквозной пример своего ассистента.📚 Если вы столкнётесь со сложностями, то полный пример реализации ассистента можно найти в GitHub-репозитории.

Начало работы с языковыми моделями в облаке

Yandex AI Studio поддерживает различные языковые модели для работы с текстом: YandexGPT, GPT-OSS и Qwen. Все эти модели доступны через соответствующие облачные API: нативный для Yandex AI Studio или OpenAI-совместимый.Для работы с моделями в Python рекомендуется использовать стандартную библиотеку OpenAI. В неё можно передать эндпоинт для обращения к моделям Yandex AI Studio.Облако поддерживает два типа API: классический Completion API и современный Responses API, который вы рассмотрите в этом курсе.С моделями Yandex AI Studio можно работать и через другие инструменты, совместимые с API OpenAI:

• OpenAI Agents SDK;
• LangChain;
• LlamaIndex.

Кроме Responses API, в Yandex AI Studio доступны дополнительные сервисы:

• Асинхронный и пакетный запуск моделей. Эти режимы редко используют для разговорных ассистентов, но они подходят для обработки текстов. В пакетном режиме доступно больше моделей, а стоимость отложенной обработки ниже.
• Синтез и распознавание речи через Yandex SpeechKit.
• Распознавание текста через Yandex Vision OCR.

Для работы с этими и другими сервисами существует Yandex AI Studio SDK — удобная библиотека для работы с сервисами Yandex Cloud, включая большие языковые модели.📚 Исходный код и примеры доступны на GitHub — там показано, как использовать библиотеку для разных задач.В этом примере используется библиотека OpenAI и современный Responses API. Для начала установите библиотеку через pip:

pip install openai
 

Для работы с библиотекой используется Python-объект OpenAI. Как его создать:

from openai import OpenAI

folder_id = "<идентификатор каталога>"
api_key = "<API-ключ>"

client = OpenAI(
   base_url = "https://ai.api.cloud.yandex.net/v1",
   api_key = api_key,
   project = folder_id
)
 

В примере указан base_url для LLM-моделей в Yandex AI Studio. Это означает, что все вызовы будут направлены в Yandex AI Studio. Также для доступа необходимы:

• Идентификатор каталога в Yandex Cloud folder_id.
• API-ключ сервисного аккаунта с доступом к языковым моделям. Если вы создаёте ключ api_key через интерфейс Yandex AI Studio, он автоматически получает необходимые права. При создании ключа через интерфейс Yandex Cloud нужно назначить аккаунту соответствующие роли, например ai.editor или serverless.mcpGateways.anonymousInvoker.

💡 Ключ api_key требует особой защиты, так как открывает доступ к языковым моделям и позволяет расходовать средства с баланса облака. Не указывайте ключ в коде напрямую; в учебных целях это допустимо, но в реальных проектах параметры доступа, такие как folder_id и api_key, обычно хранят в переменных окружения или в файле .env, который можно загрузить с помощью библиотеки[dotenv](https://pypi.org/project/python-dotenv/).После создания объекта client все операции выполняются через него.

Использование LLM

Главная возможность OpenAI SDK — работа с фундаментальными моделями, доступными в Yandex AI Studio. Имя модели включает её название и идентификатор каталога folder_id.Как использовать последнюю версию YandexGPT:

model = f"gpt://{folder_id}/yandexgpt/rc"  

Как использовать более мощную многоязычную модель Qwen3:

model = f"gpt://{folder_id}/qwen3-235b-a22b-fp8/latest" 

📚 В примере мы рекомендуем использовать Qwen3-235B, поскольку она хорошо справляется со всеми агентскими задачами, такими, как вызов инструментов, а также хорошо пишет на русском языке. При этом в облаке доступны и другие модели; актуальный список можно найти в документации.Для вызова модели нужен метод client.responses.create:

res = client.responses.create(
    model = model,
    input = "Как тренироваться, чтобы сбросить вес?"
)
print(res.output_text) 

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

• system или developer — системный промт.
• user — сообщения пользователя.
• assistant — ответы модели.

Системный промпт всегда идёт первым. После него должны чередоваться реплики пользователя и ответы ассистента.Пример вызова модели с системным промптом:

res = client.responses.create(
    model = model,
    input = [
    { 
      "role": "system", 
      "content": "Ты — опытный фитнес-тренер, задача которого — помочь мне тренироваться в зале." 
    },
    { 
      "role": "user", 
      "content": "Привет! С чего ты порекомендуешь начать тренировки в зале?" 
    }
])
 

Чтобы продолжить переписку, добавьте полученное сообщение в историю со значением role=assistant и передайте обновлённую историю при следующем вызове, начиная с системного промпта.В примере выше промпт передавался отдельным сообщением, но для простоты кода рекомендуется использовать параметр instructions.

res = client.responses.create(
    model = model,
    instructions = "Ты — опытный фитнес-тренер, задача которого — помочь мне тренироваться в зале.",
    input = "Привет! С чего ты порекомендуешь начать тренировки в зале?" 
)
 

Responses API и история переписки

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

• Клиенту не нужно отправлять всю переписку при каждом запросе.
• Модель использует кэш ранее обработанных токенов, что ускоряет работу и снижает стоимость.
• Один и тот же диалог можно продолжать на разных устройствах, передавая только идентификатор переписки.

В Responses API есть несколько способов организации хранения истории переписки на стороне облака:

• Использование специального объекта conversation для явного хранения переписки.
• Передавать идентификатор предыдущего ответа модели через параметр previous_response_id. При этом нужно убедиться, что store=True (переписка сохранена на стороне облака). По умолчанию это значение уже установлено.

В этом курсе будет использован второй способ. Пример:

instructions = """
Ты — профессиональный фитнес-ассистент. Отвечай как энергичный молодой 
человек со спортивным задором.
"""

res = client.responses.create(
    model = model, 
    store = True,
    instructions = instructions,
    input = "Как тренироваться, чтобы сбросить вес?"
)
 

В данном примере системный промпт задан с помощью параметра instructions.Теперь можно продолжить беседу и передать идентификатор предыдущего ответа в параметре previous_response_id:

res = client.responses.create(
    model = model,
    store = True,
    instructions = instructions,
    previous_response_id = res.id,
    input = "Мне нужен пошаговый план тренировки. Мой рост — 180, вес — 75 кг."
)
 

💡 При повторном вызове системный промпт передаётся через параметр instructions. История переписки содержит только сообщения пользователя и ответы ассистента. Системный промпт в неё не включается, поэтому его можно менять в ходе диалога.

💻 Практика. Создание фитнес-ассистента

❗️Практическая часть курса предполагает использование облачных ресурсов, которые вы оплачиваете самостоятельно. Курс разработан так, чтобы расходы были минимальными, — часть из них покроет стартовый грант. Чтобы избежать лишних трат: — останавливайте ВМ в перерывах между практиками (это не снизит потребление до нуля, но заметно сократит расходы); — настройте бюджет и уведомления в разделе Биллинг; — удаляйте ресурсы после завершения курса; — необязательно выполнять все практики — сосредоточьтесь на релевантных.В этом и следующих уроках вы рассмотрите пример создания ассистента для фитнес-клуба. Для полного усвоения материала рекомендуем параллельно собирать собственный пример ассистента — на тему фитнеса или другую, близкую по интересам.📚 Если возникнут сложности, полный пример реализации доступен в GitHub-репозитории.

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

1️⃣ Создание класса для ассистента

Чтобы ассистент поддерживал диалог, нужно каждый раз сохранять идентификатор предыдущего сообщения. Удобно создать класс, который будет хранить этот идентификатор внутри себя. Кроме того, в классе хранится системный промпт и используемая модель.Чтобы ассистент общался с несколькими пользователями сразу, важно для каждого из них хранить персональный идентификатор последнего сообщения. Для этого подходит идентификатор сессии session_id, который помогает различать пользователей. Отображение сессий на идентификаторы последних сообщений хранится в словаре previous_response_id_map.

class Assistant:
    def __init__(self, instructions, model=model):
        self.model = model
        self.instructions = instructions
        self.previous_response_id_map = {}

    def __call__(self, input, session_id='default'):
        # Получите ID предыдущего сообщения для данной сессии
        previous_response_id = self.previous_response_id_map.get(session_id, None)

        # Сформируйте ответ модели
        res = client.responses.create(
            model = self.model,
            store = True,
            previous_response_id = previous_response_id,
            instructions = self.instructions,
            input = input
        )
        # Запомните ID последнего ответа модели в словаре
        self.previous_response_id_map[session_id] = res.id
        return res.output_text
 

💡 В этом коде model и client — переменные, созданные ранее в уроке. Название модели можно передать в конструктор класса, чтобы гибко выбирать, какая языковая модель будет лежать в основе ассистента. От этого зависит баланс между интеллектом ассистента и его стоимостью.

2️⃣ Задание системного промпта и создание ассистента

Чтобы пообщаться с ассистентом, создайте объект Assistant и передайте в него системный промпт:

instructions = """
Ты — профессиональный фитнес-ассистент. Отвечай как энергичный молодой человек 
со спортивным задором. Говори как человек, короткими фразами, избегая 
перечислений и списков.
"""

assistant = Assistant(instructions)
 

3️⃣ Общение с ассистентом

Теперь можно начать общаться с ассистентом:

print(assistant("Привет! С чего ты порекомендуешь начать тренировки в зале?"))
 

В примере выше может получиться такой ответДля продолжения диалога посылайте агенту сообщения аналогичным образом:

print(assistant("Я хочу похудеть!"))
 

Агент автоматически учитывает историю переписки, которая хранится в облаке.

Дополнительные задания

Попробуйте расширить приведённый выше код и добавить ассистенту новые возможности:1️⃣ Хранение истории переписки. Получить доступ к переписке в облаке сложно, её нужно дублировать локально. Вы рассмотрите, как решается такая задача в следующих уроках. А пока что попробуйте решить её самостоятельно.

2️⃣ Изменение системного промпта. Настройте ассистента так, чтобы он отказывался обсуждать темы, не связанные с фитнесом.Практики много не бывает! Поэтому предлагаем вам пройти небольшой тест для лучшего закрепления материала.

Какие действия по созданию интеллектуальных ассистентов позволяет сделать Responses API? Выберите два верных ответа.

Правильный ответ

Использовать большие языковые модели в Yandex CloudДа, Responses API содержит удобные абстракции для работы с языковыми моделями

Неправильный ответ

Использовать локально размещённые большие языковые моделиНет, Yandex Cloud Responses API — это облачное SDK, которое позволяет работать с моделями в Yandex Cloud. Для использования локальных моделей необходимо использовать специализированые инструменты

Правильный ответ

Хранить историю перепискиДа, Responses API позволяет хранить историю перепискиСоздавать интерфейс ассистентов в Telegram

Неправильный ответ

Создавать веб-интерфейс ассистентовНет, Responses API не содержит функций для создания интерфейсовКак вам задача?

Укажите способы, которыми можно передать модели системный промт. Выберите два верных ответа.Правильный ответ

В параметре instructions при вызове client.responses.create

Правильно

Тоже правильный ответ

В списке сообщений отдельным сообщением, у которого role = system

Правильно

Неправильный ответ

Специальным вызовом client.responses.set_system_promptНет, специального вызова для установки системного промта не существует

Через префикс <system>Системный промпт</system> в начале сообщенияКак вам задача?

Теперь вы знаете, как Responses API упрощает создание ассистентов на основе LLM! Более того — он сохраняет историю переписки. Дальше будет ещё интереснее, увидимся в следующем уроке!❗Не забудьте остановить ресурсы, чтобы избежать лишних трат.

Источник на материал : https://practicum.yandex.ru/trainer/yc-ml-aiagents/lesson/6f589a6d-4fb6-4675-8ae4-06d9b3a1f47f/