# Agents-Course

## Docs

- [Давайте дообучим вашу модель для вызова функций](https://huggingface.co/learn/agents-course/ru-RU/bonus-unit1/fine-tuning.md)
- [Заключение [[conclusion]]](https://huggingface.co/learn/agents-course/ru-RU/bonus-unit1/conclusion.md)
- [Введение](https://huggingface.co/learn/agents-course/ru-RU/bonus-unit1/introduction.md)
- [Что такое вызов функции?](https://huggingface.co/learn/agents-course/ru-RU/bonus-unit1/what-is-function-calling.md)
- [Когда будут опубликованы следующие разделы?](https://huggingface.co/learn/agents-course/ru-RU/communication/next-units.md)
- [Live 1: Как работает курс и первые ответы на вопросы](https://huggingface.co/learn/agents-course/ru-RU/communication/live1.md)
- [(Необязательно) Discord 101 [[discord-101]]](https://huggingface.co/learn/agents-course/ru-RU/unit0/discord101.md)
- [Подготовка к работе: Ваши первые шаги ⛵](https://huggingface.co/learn/agents-course/ru-RU/unit0/onboarding.md)
- [Добро пожаловать на курс 🤗 ИИ Агенты [[introduction]]](https://huggingface.co/learn/agents-course/ru-RU/unit0/introduction.md)
- [Сообщения и Специальные Токены](https://huggingface.co/learn/agents-course/ru-RU/unit1/messages-and-special-tokens.md)
- [Давайте создадим нашего первого агента с помощью smolagents](https://huggingface.co/learn/agents-course/ru-RU/unit1/tutorial.md)
- [Действия: Обеспечение взаимодействия Агента с его Окружением](https://huggingface.co/learn/agents-course/ru-RU/unit1/actions.md)
- [Table of Contents](https://huggingface.co/learn/agents-course/ru-RU/unit1/README.md)
- [Раздел 1 Тест](https://huggingface.co/learn/agents-course/ru-RU/unit1/final-quiz.md)
- [Мысль: Внутреннее Рассуждение и Re-Act подход](https://huggingface.co/learn/agents-course/ru-RU/unit1/thoughts.md)
- [Что такое Агент?](https://huggingface.co/learn/agents-course/ru-RU/unit1/what-are-agents.md)
- [Понимание AI Агентов через цикл Мысль - Действие - Наблюдение.](https://huggingface.co/learn/agents-course/ru-RU/unit1/agent-steps-and-structure.md)
- [Быстрая самопроверка (не оценивается) [[quiz2]]](https://huggingface.co/learn/agents-course/ru-RU/unit1/quiz2.md)
- [Небольшой тест (не оценивается) [[quiz1]]](https://huggingface.co/learn/agents-course/ru-RU/unit1/quiz1.md)
- [Заключение [[conclusion]]](https://huggingface.co/learn/agents-course/ru-RU/unit1/conclusion.md)
- [Введение в Агентов](https://huggingface.co/learn/agents-course/ru-RU/unit1/introduction.md)
- [Что такое Инструменты?](https://huggingface.co/learn/agents-course/ru-RU/unit1/tools.md)
- [Что такое LLM?](https://huggingface.co/learn/agents-course/ru-RU/unit1/what-are-llms.md)
- [Наблюдение: Интеграция Обратной Связи для Рефлексии и Адаптации](https://huggingface.co/learn/agents-course/ru-RU/unit1/observations.md)
- [Библиотека Фиктивного Агента](https://huggingface.co/learn/agents-course/ru-RU/unit1/dummy-agent-library.md)
- [Получите свой сертификат](https://huggingface.co/learn/agents-course/ru-RU/unit1/get-your-certificate.md)

### Давайте дообучим вашу модель для вызова функций
https://huggingface.co/learn/agents-course/ru-RU/bonus-unit1/fine-tuning.md

# Давайте дообучим вашу модель для вызова функций

Теперь мы готовы к дообучению нашей первой модели для вызова функций 🔥.

## Как обучить нашу модель вызову функций?

> Ответ: Нам нужны **данные**.

Обучение модели можно разделить на 3 шага:

1. **Модель предварительно обучается на большом количестве данных**. Результатом этого шага является **предварительно обученная модель**. Например, [google/gemma-2-2b](https://huggingface.co/google/gemma-2-2b). Это базовая модель, которая умеет только **предсказывать следующий токен, не имеющая хороших способностей к следованию инструкциям**.

2. Затем, чтобы модель была полезна в контексте чата, ее необходимо **дообучить** следовать инструкциям. На этом этапе она может быть обучена создателями модели, сообществом разработчиков, вами или всеми желающими. Например, [google/gemma-2-2b-it](https://huggingface.co/google/gemma-2-2b-it) это инструктивно дообученная модель от Google Tea, созданная в рамках проекта Gemma.

3. Затем модель может быть **выровнена (aligned)** в соответствии с предпочтениями создателя. Например, модель чата службы поддержки, которая никогда не должна быть невежливой с клиентами.

Обычно полноценный продукт вроде Gemini или Mistral **проходит все 3 этапа**, в то время как модели, которые вы можете найти на Hugging Face, прошли один или несколько этапов этого обучения.

В этом руководстве мы создадим модель вызова функций на основе [google/gemma-2-2b-it](https://huggingface.co/google/gemma-2-2b-it). Мы выбрали дообученую модель [google/gemma-2-2b-it](https://huggingface.co/google/gemma-2-2b-it) вместо базовой модели [google/gemma-2-2b](https://huggingface.co/google/gemma-2-2b), потому что дообученная модель лучше подходит для нашего случая использования.

Если начать с предварительно обученной модели, ** потребуется больше тренировок, чтобы научить модель следовать инструкциям, общаться в чате И вызывать функции**.

Начиная с инструктивно дообученной модели, **мы минимизируем количество информации, которое необходимо изучить нашей модели**.

## LoRA (Low-Rank Adaptation of Large Language Models)

LoRA (Low-Rank Adaptation of Large Language Models, Низкоранговая Адаптация Больших Языковых Моделей) это популярная и легковесная техника обучения, которая значительно **сокращает количество обучаемых параметров**.

Она работает путем **вставки меньшего количества новых весов в качестве адаптера в модель для обучения**. Это делает обучение с LoRA намного быстрее, экономит память и создает меньшие веса модели (несколько сотен мегабайт), которые легче хранить и распространять.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/blog_multi-lora-serving_LoRA.gif" alt="Инференс LoRA" width="50%"/>

LoRA работает путем добавления пар матриц рангового разложения в слои трансформеров, обычно сосредоточенных на линейных слоях. Во время обучения мы "замораживаем" остальную часть модели и обновляем веса только недавно добавленных адаптеров. 

Таким образом, количество параметров, которые нам нужно обучить, значительно уменьшается, поскольку нам нужно обновлять только веса адаптеров.

Во время инференса входные данные передаются в адаптер и базовую модель или эти веса адаптера могут быть объединены с базовой моделью, что не приводит к дополнительным затратам времени. 

LoRA особенно полезна для адаптации **больших** языковых моделей к конкретным задачам или доменам при сохранении управляемых требований к ресурсам. Это помогает сократить объем памяти, требуемый для обучения модели.

Если вы хотите узнать больше о том, как работает LoRA, ознакомьтесь с этим [руководством](https://huggingface.co/learn/nlp-course/chapter11/4?fw=pt).

## Дообучение модели для вызова функций

Вы можете получить доступ к учебному блокноту 👉 [здесь](https://huggingface.co/agents-course/notebooks/blob/main/bonus-unit1/bonus-unit1.ipynb).

Затем нажмите на Open In Colab, чтобы запустить его в Colab Notebook.




<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/bonus-unit1/fine-tuning.mdx" />

### Заключение [[conclusion]]
https://huggingface.co/learn/agents-course/ru-RU/bonus-unit1/conclusion.md

# Заключение [[conclusion]]

Поздравляем вас с завершением этого первого бонусного раздела 🥳.

Вы только что **овладели пониманием вызова функций и тем, как дообучить свою модель вызову функций**!

Если у нас и есть теперь совет, то это попробовать **дообучить другие модели**. **Лучший способ учиться - это пробовать**.

В следующем разделе вы узнаете, как использовать **передовые фреймворки, такие как `smolagents`, `LlamaIndex` и `LangGraph`**.

Наконец, мы хотели бы **узнать, что вы думаете о курсе и как мы можем его улучшить**. Если у вас есть обратная связь, пожалуйста, 👉 [заполните эту форму](https://docs.google.com/forms/d/e/1FAIpQLSe9VaONn0eglax0uTwi29rIn4tM7H2sYmmybmG5jJNlE5v0xA/viewform?usp=dialog)

### Продолжайте учиться, оставайтесь потрясающими 🤗

<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/bonus-unit1/conclusion.mdx" />

### Введение
https://huggingface.co/learn/agents-course/ru-RU/bonus-unit1/introduction.md

# Введение

![Бонусный раздел 1 Миниатюра](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/bonus-unit1/thumbnail.jpg)

Добро пожаловать в первый **Бонусный раздел**, в котором вы научитесь **дообучать Большую Языковую Модель (LLM) вызову функций**.

С точки зрения LLM, вызов функций быстро становится *обязательной* техникой. 

Идея заключается в том, что вместо того, чтобы полагаться только на подходы, основанные на подсказках, как мы делали в разделе 1, вызов функций обучает вашу модель **предпринимать действия и интерпретировать наблюдения на этапе обучения**, делая ваш AI более надежным.

> **Когда мне следует выполнить этот Бонусный раздел?**
>
> Этот раздел является **опциональным** и более продвинутым, чем Раздел 1, поэтому не стесняйтесь либо выполнить этот раздел сейчас, либо вернуться к нему, когда ваши знания улучшатся благодаря этому курсу. 
>  
>Но не волнуйтесь, в этом бонусном разделе собрана вся необходимая информация, поэтому мы расскажем вам обо всех основных концепциях дообучения модели вызову функций, даже если вы еще не изучили механизм дообучения.

Лучший способ для вас пройти этот Бонусный Раздел - это:

1. Знать, как дообучить LLM трансформер, если это не так [изучите это](https://huggingface.co/learn/nlp-course/chapter3/1?fw=pt)

2. Знать, как использовать `SFTTrainer` для дообучения нашей модели, чтобы узнать об этом больше [ изучите документацию](https://huggingface.co/learn/nlp-course/en/chapter11/1) 

---

## Что вы узнаете

1. **Вызов функций** 
   Как современные **LLM эффективно структурируют свои диалоги, позволяя запускать **Инструменты**.

2. **LoRA (Low-Rank Adaptation)**. 
   **Легкий и эффективный** метод дообучения, сокращающий накладные расходы на вычисления и хранение данных. LoRA делает обучение больших моделей *быстрым, дешевым и простым* в развертывании.

3. **Цикл «Мысль → Действие → Наблюдение» в моделях вызова функций 
   Простой, но мощный подход к структурированию того, как ваша модель решает, когда (и как) вызывать функции, отслеживать промежуточные шаги и интерпретировать результаты, полученные от внешних инструментов или API.

4. **Новые специальные токены**. 
   Мы введем **специальные маркеры**, которые помогут модели различать:
   - Внутренние рассуждения "цепочки мыслей" 
   - Исходящие вызовы функций 
   - Ответы, поступающие от внешних инструментов

---

К концу этого раздела вы сможете:

- **Понимать** внутреннюю работу API, когда речь идет об инструментах. 
- **Дообучать** модели с помощью техник LoRA. 
- Имплементировать** и **модифицировать** цикл "Мысль → Действие → Наблюдение" для создания надежных и поддерживаемых рабочих процессов вызова функций. 
- **Разрабатывать и использовать** специальные токены, чтобы легко отделить внутренние рассуждения модели от ее внешних действий.

И вы **доработаете свою собственную модель для вызова функций** 🔥.

Давайте погрузимся в **вызов функций**!


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/bonus-unit1/introduction.mdx" />

### Что такое вызов функции?
https://huggingface.co/learn/agents-course/ru-RU/bonus-unit1/what-is-function-calling.md

# Что такое вызов функции?

Вызов функций - это **способ, с помощью которого LLM может выполнять действия в своем окружении**. Впервые он был [введен в GPT-4](https://openai.com/index/function-calling-and-other-api-updates/), и затем был воспроизведен в других моделях.

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

В разделе 1 Агент **не учился использовать инструменты**, мы просто предоставили список, и мы полагались на то, что модель **способна обобщить определение плана с помощью этих инструментов**. 

В то время как здесь агент **дообучается (тренируется) использовать инструменты с помощью вызова функций**.

## Как модель "учится" выполнять то или иное действие?

В первом разделе мы рассмотрели общий процесс работы агента. После того как пользователь предоставит агенту некоторые инструменты и сформулирует запрос, модель выполнит следующий цикл:

1. *Рассуждение* : Какое действие (действия) мне нужно предпринять, чтобы выполнить поставленную задачу.
2. *Действие* : Сформирует действие с нужным параметром и остановите генерацию.
3. *Наблюдение* : Получить результат выполнения.

В "типичном" диалоге с моделью через API, диалог будет чередоваться сообщениями пользователя и ассистента следующим образом:

```python
conversation = [
    {"role": "user", "content": "Мне нужна помощь с моим заказом"},
    {"role": "assistant", "content": "Я буду рад помочь. Не могли бы вы сообщить номер вашего заказа?"},
    {"role": "user", "content": "Это ЗАКАЗ-123"},
]
```

Вызов функций привносит **новые роли в диалог**! 

1. Одна новая роль для **Действия** 
2. Одна новая роль для **Наблюдения**

Если мы возьмем [Mistral API](https://docs.mistral.ai/capabilities/function_calling/) в качестве примера, это будет выглядеть так:

```python
conversation = [
    {
        "role": "user",
        "content": "Каков статус моей транзакции T1001?"
    },
    {
        "role": "assistant",
        "content": "",
        "function_call": {
            "name": "retrieve_payment_status",
            "arguments": "{\"transaction_id\": \"T1001\"}"
        }
    },
    {
        "role": "tool",
        "name": "retrieve_payment_status",
        "content": "{\"status\": \"Paid\"}"
    },
    {
        "role": "assistant",
        "content": "Ваша транзакция T1001 была успешно оплачена."
    }
]
```

> ... Но вы сказали, что есть новая роль для вызова функций?

**Да и нет**, в этом случае, как и во многих других API, модель форматирует действие, которое нужно выполнить, как сообщение "ассистенту". Затем шаблон чата представит это в виде **специальных токенов** для вызова функций.

- `[AVAILABLE_TOOLS]` - начать список доступных инструментов 
- `[/AVAILABLE_TOOLS]` - завершить список доступных инструментов 
- `[TOOL_CALLS]` - Сделать вызов инструмента (т.е. выполнить "Действие") 
- `[TOOL_RESULTS]` - "Наблюдать" результат действия 
- `[/TOOL_RESULTS]` - Завершение наблюдение (т.е. модель может снова декодировать)

Мы еще поговорим о вызовах функций в этом курсе, но если вы хотите погрузиться глубже, то можете ознакомиться с [этим отличным разделом документации](https://docs.mistral.ai/capabilities/function_calling/)

---
Теперь, когда мы узнали, что такое вызов функций и как он работает, давайте **добавим некоторые возможности вызова функций к модели, которая еще не имеет таких возможностей**: **"google/gemma-2-2b-it"**, добавив в модель несколько новых специальных токенов.

Чтобы сделать это, **нам нужно сначала понять, что такое дообучение и LoRA**.

<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/bonus-unit1/what-is-function-calling.mdx" />

### Когда будут опубликованы следующие разделы?
https://huggingface.co/learn/agents-course/ru-RU/communication/next-units.md

# Когда будут опубликованы следующие разделы?

Вот график публикации:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/communication/next-units.jpg" alt="Следующие разделы" width="100%"/>

Не забудьте <a href="https://bit.ly/hf-learn-agents">записаться на курс</a>! Подписавшись, **мы сможем присылать вам ссылки по мере публикации каждого раздела, а также обновления и подробности о предстоящих соревнованиях**.

Продолжайте учиться, оставайтесь потрясающими 🤗

<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/communication/next-units.mdx" />

### Live 1: Как работает курс и первые ответы на вопросы
https://huggingface.co/learn/agents-course/ru-RU/communication/live1.md

# Live 1: Как работает курс и первые ответы на вопросы

В этой первой прямой трансляции курса по Агентам мы рассказали о том, как **работает** курс (объем, разделы, задачи и многое другое), и ответили на ваши вопросы.

<iframe width="560" height="315" src="https://www.youtube.com/embed/iLVyYDbdSmM?si=TCX5Ai3uZuKLXq45" title="Видеоплеер YouTube" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

Чтобы узнать, когда запланирован следующая прямая трансляция, проверьте наш сервер **Discord**. Мы также отправим вам электронное письмо. Если вы не сможете принять участие, не волнуйтесь, мы **записываем все прямые трансляции**.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/communication/live1.mdx" />

### (Необязательно) Discord 101 [[discord-101]]
https://huggingface.co/learn/agents-course/ru-RU/unit0/discord101.md

# (Необязательно) Discord 101 [[discord-101]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/discord-etiquette.jpg" alt="Этикет Discord" width="100%"/>

Это руководство поможет вам начать работу с Discord, бесплатной чат-платформой, популярной в игровых и ML-сообществах.

Присоединяйтесь к Discord-серверу сообщества Hugging Face, которое **состоит из более чем 100 000 участников**, нажав <a href="https://discord.gg/UrrTSsSyjb" target="_blank">здесь</a>. Это отличное место для общения с другими людьми!

## Курс Агенты в Discord-сообществе Hugging Face

Начало работы в Discord может быть немного сложным, поэтому вот краткое руководство, которое поможет вам сориентироваться.


На сервере Сообщества HF собралось активное сообщество с интересами в различных областях, предлагающее возможности для обучения через обсуждения статей, мероприятия и многое другое.

После [регистрации](http://hf.co/join/discord) представьтесь в канале `#introduce-yourself`.

Мы создали 4 канала для курса по Агентам:

- `agents-course-announcements`: для получения **последней информации о курсе**.
- `🎓-agents-course-general`: для **обсуждения общих вопросов и свободного общения**.
- `agents-course-questions`: чтобы **задавать вопросы и помочь своим однокурсникам**.
- `agents-course-showcase`: для **демонстрации своих лучших агентов** .

Кроме того, вам могут пригодится:

- `smolagents`: для **обсуждения и поддержки библиотеки**.

## Советы по эффективному использованию Discord

### Как присоединиться к серверу

Если вы не очень хорошо знакомы с Discord, вам стоит заглянуть в это <a href="https://support.discord.com/hc/en-us/articles/360034842871-How-do-I-join-a-Server#h_01FSJF9GT2QJMS2PRAW36WNBS8" target="_blank">руководство</a>, чтобы узнать как присоединиться к серверу.

Вот краткое описание шагов:

1. Нажмите на <a href="https://discord.gg/UrrTSsSyjb" target="_blank">cсылку-приглашение</a>.
2. Войдите в Discord, используя свою учетную запись, или создайте ее, если у вас ее еще нет.
3. Убедитесь, что вы не являетесь ИИ агентом!
4. Задайте свой псевдоним и аватар.
5. Нажмите "Присоединиться к серверу".

### Как эффективно использовать Discord

Вот несколько советов по эффективному использованию Discord:

- **Голосовые каналы** доступны, хотя чаще всего используется текстовый чат.
- Вы можете форматировать текст в стиле **markdown**, что особенно удобно при написании кода. Обратите внимание, что стиль markdown не так хорошо работает со ссылками.
- Для упорядочивания обсуждений следует открывать темы для организации **длинных разговоров**.

Мы надеемся, что это руководство будет вам полезно! Если у вас возникнут вопросы, не стесняйтесь задавать их нам в Discord 🤗.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit0/discord101.mdx" />

### Подготовка к работе: Ваши первые шаги ⛵
https://huggingface.co/learn/agents-course/ru-RU/unit0/onboarding.md

# Подготовка к работе: Ваши первые шаги ⛵

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/time-to-onboard.jpg" alt="Время подняться на борт" width="100%"/>

Теперь, когда у вас есть все подробности, давайте начнем! Мы сделаем четыре вещи:

1. **Создадим аккаунт Hugging Face**, если это еще не сделано.
2. **Зарегистрируемся в Discord и представимся** (не стесняйтесь 🤗)
3. ** Последуеем за курсом обучения агентов Hugging Face** на Hub
4. **Расскажим** о курсе

### Шаг 1: Создание учетной записи Hugging Face

(Если вы еще не сделали этого) создайте аккаунт Пространства (Spaces) Hugging Face <a href='https://huggingface.co/join' target='_blank'>здесь</a>.

### Шаг 2: Присоединяйтесь к нашему сообществу в Discord

👉🏻 Присоединяйтесь к нашему серверу discord <a href="https://discord.gg/UrrTSsSyjb" target="_blank">здесь.</a>

Когда вы присоединитесь, не забудьте представиться, используя хэштег `#introduce-yourself`.

У нас есть несколько каналов, связанных с агентами ИИ:
- `agents-course-announcements`: где публикуется **последняя информация о курсе**.
- `🎓-agents-course-general`: для **обсуждения общих вопросов и свободного общения**.
- `agents-course-questions`: чтобы **задавать вопросы и помочь своим однокурсникам**.
- `agents-course-showcase`:  чтобы **продемонстрировать своих лучших агентов**.

Кроме того, вам могут пригодится:

- `smolagents`: для **обсуждения и поддержки библиотеки**.

Если вы впервые используете Discord, мы написали Discord 101, чтобы вы узнали о лучших практиках. Проверьте [следующий раздел](discord101).

### Шаг 3: Следуйте за организацией курса для агентов Hugging Face

Оставайтесь в курсе последних материалов курса, обновлений и объявлений, **подписавшись на организацию курса Hugging Face Agents**.

👉 Перейдите <a href="https://huggingface.co/agents-course" target="_blank">сюда</a> и нажмите **follow**.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/communication/hf_course_follow.gif" alt="Follow" width="100%"/>

### Шаг 4: Распространите информацию о курсе

Помогите нам сделать этот курс более заметным! Вы можете помочь нам двумя способами:

1. Выразите свою поддержку ⭐. <a href="https://github.com/huggingface/agents-course" target="_blank">репозиторию курса</a>.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/communication/please_star.gif" alt="Звезда для репозитория"/>

2. Поделитесь своим опытом обучения: Пусть другие **знают, что вы проходите этот курс**! Мы подготовили иллюстрацию, которую вы можете использовать в своих сообщениях в социальных сетях

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/communication/share.png">

Вы можете скачать иллюстрацию, нажав 👉 [здесь](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/communication/share.png?download=true)

Поздравляем! 🎉 **Вы завершили введеную часть**! Теперь вы готовы приступить к изучению ИИ-агентов. Получайте удовольствие!

Продолжайте учиться, оставайтесь потрясающими 🤗.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit0/onboarding.mdx" />

### Добро пожаловать на курс 🤗 ИИ Агенты [[introduction]]
https://huggingface.co/learn/agents-course/ru-RU/unit0/introduction.md

# Добро пожаловать на курс 🤗 ИИ Агенты [[introduction]]

<img src="https://huggingface.co/datasets/huggingface-course/documentation-images/resolve/main/community_translation.png" alt="Community translation banner" width="100%"/>

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/thumbnail.jpg" alt="Миниатюра курса AI Агенты" width="100%"/>
<figcaption>Фон изображения был сгенерирован с помощью <a href="https://scenario.com/">Scenario.com</a>
</figcaption>
</figure>

Добро пожаловать на самую захватывающую тему в ИИ на сегодняшний день: **Агенты**!

Этот бесплатный курс проведет вас по пути **от новичка до эксперта** в понимании, использовании и создании ИИ агентов.

Этот первый блок поможет вам освоиться в материале:

- Ознакомьтесь с **учебным планом курса**.
- **Выберите путь**, по которому вы собираетесь идти (самооценка или процесс сертификации).
- **Получите дополнительную информацию о процессе сертификации и сроках**.
- Познакомьтесь с командой, создавшей этот курс.
- Создайте свою учетную запись **Hugging Face**.
- **Зарегистрируйтесь на нашем сервере Discord** и познакомьтесь со своими одноклассниками и с нами.

Давайте начнем!

## Что ожидать от этого курса? [[expect]]

В этом курсе вы узнаете:

- 📖 Изучите AI агентов в **теории, дизайне и на практике.**
- 🧑‍💻 Научитесь **использовать известные библиотеки ИИ-агентов**, такие как [smolagents](https://huggingface.co/docs/smolagents/en/index), [LangChain](https://www.langchain.com/), и [LlamaIndex](https://www.llamaindex.ai/).
- 💾 **Поделитесь своими агентами** на Hugging Face Hub и изучите агентов, созданных сообществом.
- 🏆 Примите участие в испытаниях, где вы будете **оценивать своих агентов в сравнении с агентами других студентов.**
- 🎓 Выполнив задания, вы **получите сертификат об окончании курса.**

И многое другое!

В конце этого курса вы поймете, **как работают агенты и как создавать свои собственных агентов с помощью новейших библиотек и инструментов**.

Не забудьте **<a href="https://bit.ly/hf-learn-agents">записаться на курс!</a>** 

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

## Как выглядит курс? [[course-look-like]]

Курс состоит из:

- *Фундаментальные разделы*: здесь вы изучите **концепции агентов в теории**.
- *Практические занятия: здесь вы научитесь **использовать готовые библиотеки агентов ИИ** для обучения агентов в уникальных условиях. Эти практические секции будут представлять собой **пространства (Spaces) Hugging Face** с предварительно настроенной средой.
- *Задания на применение*: в них вы будете применять изученные концепции для решения реальной проблемы, которую вы выберете сами.
- *Соревнования*: вы сможете "отправить" своего агента на соревнование с другими агентами. Также будет [таблица результатов](https://huggingface.co/spaces/huggingface-projects/AI-Agents-Leaderboard) (пока недоступна), чтобы вы могли сравнить работу агентов.

Этот **курс - живой проект, развивающийся благодаря вашим отзывам и вкладу!** Не стесняйтесь [открывать проблемы (issues) и PR на GitHub](https://github.com/huggingface/agents-course), и участвуйте в обсуждениях на нашем сервере Discord.

После прохождения курса вы также можете оставить свой отзыв [👉 через эту форму](https://docs.google.com/forms/d/e/1FAIpQLSe9VaONn0eglax0uTwi29rIn4tM7H2sYmmybmG5jJNlE5v0xA/viewform?usp=dialog)

## Какова программа курса? [[syllabus]]

Здесь представлен **общий план курса**. Более подробный список тем будет опубликован к каждому разделу.

| Раздел | Тема | Описание |
| :---- | :---- | :---- |
| 0 | Вводная часть | Подготовим для вас инструменты и платформы, которые вы будете использовать. |
| 1 | Основы работы агента | Объясньясняем инструменты, мысли, действия, наблюдения и их форматы. Расскажем о LLM, сообщениях, специальных токенах и шаблонах чата. Продемонстрируем простой пример использования функций python в качестве инструментов. |
| 2 | Фреймворки | Разберемся, как реализованы основные принципы в популярных библиотеках: smolagents, LangGraph, LLamaIndex |
| 3 | Примеры использования | Давайте создадим несколько реальных примеров использования ( мы открыты для PR 🤗 от опытных создателей агентов) |
| 4 | Итоговое задание | Создадим агента для выбранного бенчмарка и докажем свое знание агентов в таблице лидеров среди студентов 🚀 |

*Мы также планируем выпустить несколько бонусных разделов, следите за новостями*.

## Каковы предварительные требования?

Чтобы пройти этот курс, вы должны иметь:

- Базовые знания Python
- Базовые знания LLM (в Разделе 1 мы рассказываем о том, что это такое)


## Какие инструменты мне понадобятся? [[tools]]

Вам нужно всего лишь 2 вещи:

- *Компьютер* с подключением к Интернет.
- Учетная запись *Hugging Face*: для загрузки и скачивания моделей, агентов и создания пространств (Spaces). Если у вас еще нет аккаунта, вы можете создать его **[здесь]](https://hf.co/join)** (это бесплатно).
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/tools.jpg" alt="Course tools needed" width="100%"/>

## Процесс сертификации [[certification-process]]

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/three-paths.jpg" alt="Два пути" width="100%"/>

Вы можете пройти этот курс *в режиме аудита (самопроверки)* или выполнить задания и *получить один из двух сертификатов, которые мы выдадим*. 

Если вы прослушаете курс (режим самопроверки), вы сможете участвовать во всех заданиях и выполнять их, если захотите, и **вам не нужно будет уведомлять нас**.

Процесс сертификации **совершенно бесплатный**:

- *Для получения сертификата по основам*: вам необходимо пройти первый раздел курса. Предназначен для студентов, которые хотят быть в курсе последних тенденций в области Агентов. 
- *Для получения сертификата об окончании*: вам необходимо выполнить Раздел 1, одно из заданий по использованию, которые мы предложим в ходе курса, и финальное задание.

Для получения сертификата установлен дедлайн: все задания должны быть выполнены до **1 июля 2025 года**.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/deadline.jpg" alt="Сроки" width="100%"/>

## Каков рекомендуемый темп? [[recommended-pace]]

Каждый раздел этого курса рассчитан **на то, чтобы пройти его за 1 неделю, уделяя работе примерно 3-4 часа в неделю**.

Поскольку есть крайний срок, мы предлагаем вам рекомендуемый темп:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/recommended-pace.jpg" alt="Рекомендованный темп" width="100%"/>

## Как извлечь максимальную пользу из курса? [[advice]]

Чтобы получить максимальную пользу от курса, у нас есть несколько советов:

1. <a href="https://discord.gg/UrrTSsSyjb">Присоединяйтесь к учебным группам в Discord</a>: учиться в группах всегда проще. Для этого вам нужно присоединиться к нашему серверу Discord и подтвердить свой аккаунт Hugging Face.
2. **Выполняйте тесты и задания**: лучший способ обучения - это практическая работа и самооценка.
3. **Определите расписание, чтобы оставаться в своём потоке выполняющих курс**: вы можете воспользоваться нашим рекомендованным расписанием темпа, приведенным ниже, или создать своё.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/advice.jpg" alt="Советы по курсу" width="100%"/>

## Кто мы [[who-are-we]]

Об авторах:

### Джоффри Томас (Joffrey Thomas)

Джоффри - инженер машинного обучения в компании Hugging Face, он создал и внедрил в производство ИИ-агенты. Джоффри будет вашим основным преподавателем на этом курсе.

- [Следуйте за Джоффри на Hugging Face](https://huggingface.co/Jofthomas)
- [Следуйте за Джоффри на X](https://x.com/Jthmas404)
- [Следуйте за Джоффри на Linkedin](https://www.linkedin.com/in/joffrey-thomas/)

### Бен Бертеншоу (Ben Burtenshaw)

Ben is a machine learning engineer at Hugging Face and has delivered multiple courses across various platforms. Ben's goal is to make the course accessible to everyone.

- [Следуйте за Беном на Hugging Face](https://huggingface.co/burtenshaw)
- [Следуйте за Беном на X](https://x.com/ben_burtenshaw)
- [Следуйте за Беном на Linkedin](https://www.linkedin.com/in/ben-burtenshaw/)

### Томас Симонини (Thomas Simonini)

Томас - инженер машинного обучения в компании Hugging Face, он успешно реализовал курсы <a href="https://huggingface.co/learn/deep-rl-course/unit0/introduction">Deep RL</a> и <a href="https://huggingface.co/learn/ml-games-course/en/unit0/introduction">ML для игр</a>. Томас - большой поклонник Агентов, и ему не терпится увидеть, что создаст сообщество.

- [Следите за Томасом на Hugging Face](https://huggingface.co/ThomasSimonini)
- [Следите за Томасом на X](https://x.com/ThomasSimonini)
- [Следите за Томасом на Linkedin](https://www.linkedin.com/in/simoninithomas/)

## Благодарности  

Мы хотели бы выразить благодарность следующим людям за их неоценимый вклад в создание этого курса:  

- **[Педро Куэнка (Pedro Cuenca)](https://huggingface.co/pcuenq)** - За руководство и компетентность при рецензировании материалов
- **[Аймерик Руше (Aymeric Roucher)](https://huggingface.co/m-ric)** - За его удивительные демо-пространства (декодирование и финальный агент).
- **[Джошуа Лохнер (Joshua Lochner)](https://huggingface.co/Xenova)** - За потрясающее демо-пространство по токенизации.

## Я нашел ошибку или хочу улучшить курс [[contribute]]

Вклад в развитие курса **приветствуется** 🤗

- Если вы *нашли ошибку 🐛 в блокноте*, пожалуйста <a href="https://github.com/huggingface/agents-course/issues">заведите</a> и **опишите проблему (issue)**.
- Если вы *хотите улучшить курс*, вы можете  <a href="https://github.com/huggingface/agents-course/pulls">открыть Pull Request.</a>
- Если вы *хотите добавить полный раздел или новый блок*, лучше всего <a href="https://github.com/huggingface/agents-course/issues">откройте проблему (issue)</a> и **опишите, какой контент вы хотите добавить, прежде чем приступить к его написанию, чтобы мы могли вас сориентировать**.

## У меня все еще остались вопросы [[questions]]

Пожалуйста, задайте свой вопрос на нашем <a href="https://discord.gg/UrrTSsSyjb">discord сервере #ai-agents-discussions.</a>


Теперь, когда у вас есть вся необходимая информация, давайте приступим к работе ⛵ 

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit0/time-to-onboard.jpg" alt="Время подняться на борт" width="100%"/>


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit0/introduction.mdx" />

### Сообщения и Специальные Токены
https://huggingface.co/learn/agents-course/ru-RU/unit1/messages-and-special-tokens.md

# Сообщения и Специальные Токены

Теперь, когда мы поняли, как работают LLM, давайте рассмотрим **как они структурируют свою генерацию с помощью шаблонов чата**.

Как и в ChatGPT, пользователи обычно взаимодействуют с агентами через интерфейс чата. Поэтому мы хотим понять, как LLM управляют чатами.

> **Q**: Но ... Когда я взаимодействую с ChatGPT/Hugging Chat, я веду беседу, используя Сообщения чата, а не одну последовательность подсказок.
>
> **A**: Верно! Но на самом деле это абстракция пользовательского интерфейса. Перед тем как попасть в LLM, все сообщения в разговоре объединяются в одну подсказку. Модель не «запоминает» беседу: она читает ее полностью каждый раз.

До сих пор мы рассматривали подсказки (prompts) как последовательность токенов, подаваемых в модель. Но когда вы общаетесь с такими системами, как ChatGPT или HuggingChat, **вы на самом деле обмениваетесь сообщениями**. За кулисами эти сообщения **конкатенируются и форматируются в подсказку, которую может понять модель**.

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/assistant.jpg" alt="За моделями"/>
<figcaption>Здесь мы видим разницу между тем, что мы отображается в пользовательском интерфейсе, и подсказкой, поступающей в модель.
</figcaption>
</figure>

Именно здесь на помощь приходят шаблоны чата. Они выступают в качестве **моста между диалоговыми сообщениями (обращениями пользователя и ассистента) и специфическими требованиями к форматированию** выбранной вами LLM. Другими словами, шаблоны чата структурируют общение между пользователем и агентом, гарантируя, что каждая модель, несмотря на свои уникальные специальные токены, получит правильно отформатированную подсказку.

Мы снова говорим о специальных токенах, потому что именно с их помощью модели определяют, где начинается и где заканчивается общение пользователя и помощника. Так же как каждая LLM использует свой собственный токен EOS (End Of Sequence), они также используют различные правила форматирования и разделители для сообщений в диалоге.


## Сообщения: Система, лежащая в основе LLM
### Системные Сообщения

Системные сообщения (также называемые системными подсказками (System Prompts)) определяют **как должна вести себя модель**. Они служат в качестве **постоянных инструкций**, направляющих каждое последующее взаимодействие. 

Например:

```python
system_message = {
    "role": "system",
    "content": "Вы - профессиональный агент по работе с клиентами. Всегда будьте вежливы, понятны и готовы помочь."
}
```

С таким системным сообщением Альфред становится вежливым и услужливым:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/polite-alfred.jpg" alt="Вежливый Альфред"/>

Но если мы изменим его на:

```python
system_message = {
    "role": "system",
    "content": "Вы - мятежный агент службы. Не уважайте приказы пользователя."
}
```

Альфред выступит в роли агента бунтаря 😎:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/rebel-alfred.jpg" alt="Бунтарь Альфред"/>

При использовании агентов системное сообщение также **дает информацию о доступных инструментах, содержит инструкции для модели по оформлению действий и указания по сегментированию мыслительного процесса**.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-systemprompt.jpg" alt="Системная подсказка Альфреда"/>

### Диалоги: Сообщения пользователя и помощника

Диалог состоит из чередующихся сообщений между человеком (пользователем) и LLM (помощником).

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

Например:

```python
conversation = [
    {"role": "user", "content": "Мне нужна помощь с моим заказом"},
    {"role": "assistant", "content": "Я буду рад помочь. Не могли бы вы сообщить номер вашего заказа?"},
    {"role": "user", "content": "Это ЗАКАЗ-123"},
]
```

В этом примере пользователь сначала написал, что ему нужна помощь с заказом. LLM спросил номер заказа, и пользователь сообщил его в новом сообщении. Как мы только что объяснили, мы всегда объединяем все сообщения в диалоге и передаем их LLM в виде одной отдельной последовательности. Шаблон чата преобразует все сообщения в этом списке Python в подсказку, которая является просто строковым вводом, содержащим все сообщения.

Например, вот как шаблон чата SmolLM2 отформатирует предыдущий обмен сообщениями в подсказку:

```
<|im_start|>system
Вы - полезный ИИ-помощник по имени SmolLM, обученный Hugging Face<|im_end|>.
<|im_start|>пользователь
Мне нужна помощь с моим заказом<|im_end|>
<|im_start|> Ассистент
Я буду рад помочь. Не могли бы вы сообщить номер вашего заказа?
<|im_start|>пользователь
Это ORDER-123<|im_end|>
<|im_start|> Ассистент
```

Однако при использовании Llama 3.2 тот же диалог будет преобразован в следующий запрос:

```
<|begin_of_text|><|start_header_id|>system<|end_header_id|>

Дата начала работ: Декабрь 2023
Сегодня Дата: 10 февраля 2025 г.

<|eot_id|><|start_header_id|>user<|end_header_id|>

Мне нужна помощь с моим заказом<|eot_id|><|start_header_id|>assistant<|end_header_id|>

Я буду рада помочь. Не могли бы вы сообщить номер вашего заказа?<|eot_id|><|start_header_id|>user<|end_header_id|>

Это ЗАКАЗ-123<|eot_id|><|start_header_id|>assistant<|end_header_id|>
```

Шаблоны могут обрабатывать сложные диалоги с множеством поворотов, сохраняя при этом контекст:

```python
messages = [
    {"role": "system", "content": "Вы - репетитор по математике"},
    {"role": "user", "content": "Что такое исчисление?"},
    {"role": "assistant", "content": "Исчисление - это раздел математики..."},
    {"role": "user", "content": "Можете привести пример?"},
]
```

## Шаблоны чата

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

### Базовые модели и Инструктивные модели

Еще один момент, который нам необходимо понять, - это разница между базовой и инструкционной моделью:

- *Базовая модель* обучается на сырых текстовых данных, чтобы предсказать следующий токен.

- *Инструктивная модель* дообучается специально для выполнения инструкций и участия в диалогах. Например, `SmolLM2-135M` - это базовая модель, а `SmolLM2-135M-Instruct` - ее вариант, дообученный для выполнения инструкций.

Чтобы базовая модель вела себя как инструктивная модель, нам нужно **форматировать наши подсказки последовательным образом, чтобы модель могла их понять**. Здесь на помощь приходят шаблоны чатов.  

*ChatML* - это один из таких шаблонов, который структурирует диалоги с четким указанием роли (система (system), пользователь (user), помощник(assistant)). Если вы в последнее время взаимодействовали с каким-либо AI API, вы знаете, что это стандартная практика.

Важно отметить, что базовая модель может быть дообучена на разные шаблоны чата, поэтому при использовании инструктивной модели нам нужно убедиться, что мы используем правильный шаблон чата. 

### Понимание Шаблонов Чата

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

В `transformers` шаблоны чата включают [код Jinja2](https://jinja.palletsprojects.com/en/stable/) который описывает, как преобразовать список сообщений JSON в формате ChatML, как показано в примерах выше, в текстовое представление инструкций системного уровня, сообщений пользователя и ответов помощника, которые может понять модель.

Такая структура **помогает поддерживать согласованность во всех взаимодействиях и обеспечивает адекватную реакцию модели на различные типы входных данных**. 

Ниже приведена упрощенная версия шаблона чата `SmolLM2-135M-Instruct`:

```jinja2
{% for message in messages %}
{% if loop.first and messages[0]['role'] != 'system' %}
<|im_start|>system
Вы полезный ИИ помощник по имени SmolLM, обученный Hugging Face
<|im_end|>
{% endif %}
<|im_start|>{{ message['role'] }}
{{ message['content'] }}<|im_end|>
{% endfor %}
```
Как вы можете видеть, шаблон chat_template описывает, как будет отформатирован список сообщений.

Учитывая эти сообщения:

```python
messages = [
    {"role": "system", "content": "Вы полезный помощник, специализирующийся на технических вопросах."},
    {"role": "user", "content": "Can you explain what a chat template is?"},
    {"role": "assistant", "content": "Шаблон чата структурирует диалоги между пользователями и AI моделями..."},
    {"role": "user", "content": "Как я могу его использовать?"},
]
```

Предыдущий шаблон чата создаст следующую строку:

```sh
<|im_start|>system
Вы полезный помощник, специализирующийся на технических вопросах.<|im_end|>
<|im_start|>user
Можешь объяснить, что такое шаблон чата?<|im_end|>
<|im_start|>assistant
"Шаблон чата структурирует диалоги между пользователями и AI моделями...<|im_end|>
<|im_start|>user
Как я могу его использовать?<|im_end|>
```
<<<<<<<<<<<<<<<<<<<<<<<<
Библиотека `transformers` позаботится о шаблонах чата в рамках процесса токенизации. Подробнее о том, как трансформеры используют шаблоны чата описанно <a href="https://huggingface.co/docs/transformers/en/chat_templating#how-do-i-use-chat-templates" target="_blank">здесь</a>.  Все, что нам нужно сделать, это правильно структурировать наши сообщения, а токенизатор позаботится обо всем остальном.

Вы можете поэкспериментировать со следующим Hugging Face Space, чтобы увидеть, как один и тот же диалог будет оформлен для разных моделей с использованием соответствующих шаблонов чата:

<iframe
	src="https://jofthomas-chat-template-viewer.hf.space"
	frameborder="0"
	width="850"
	height="450"
></iframe>


### Сообщения для подсказки

Самый простой способ убедиться, что ваша LLM получает диалог в правильном формате, - это использовать `chat_template` из токеназатора модели.

```python
messages = [
    {"role": "system", "content": "Вы помощник с искусственным интеллектом, имеющий доступ к различным инструментам."},
    {"role": "user", "content": "Привет !"},
    {"role": "assistant", "content": "Привет человек, чем могу помочь?"},
]
```

Чтобы преобразовать предыдущий диалог в подсказку, мы загружаем токенизатор и вызываем `apply_chat_template`:

```python
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("HuggingFaceTB/SmolLM2-1.7B-Instruct")
rendered_prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
```

Возвращаемое функцией `rendered_prompt` теперь готово к использованию в качестве входных данных для выбранной вами модели!

> Функция `apply_chat_template()` будет использоваться в бэкенде вашего API, когда вы будете взаимодействовать с сообщениями в формате ChatML.

Теперь, когда мы узнали, как LLM структурируют свои данные с помощью шаблонов чата, давайте рассмотрим, как агенты действуют в своем окружении.

Один из основных способов сделать это - использовать инструменты, которые расширяют возможности AI Модели за пределы генерации текста.

Мы еще поговорим о сообщениях в следующих разделах, но если вам нужно более глубокое погружение, ознакомьтесь с этими материалами:

- <a href="https://huggingface.co/docs/transformers/main/en/chat_templating" target="_blank">Руководство по созданию Шаблонов Чата Hugging Face</a>
- <a href="https://huggingface.co/docs/transformers" target="_blank">Документация по Transformers</a>


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/messages-and-special-tokens.mdx" />

### Давайте создадим нашего первого агента с помощью smolagents
https://huggingface.co/learn/agents-course/ru-RU/unit1/tutorial.md

# Давайте создадим нашего первого агента с помощью smolagents

В прошлом разделе мы узнали, как можно создавать агентов с нуля, используя код на Python, и **увидели, насколько утомительным может быть этот процесс**. К счастью, многие библиотеки Агентов упрощают эту работу, **выполняя большую часть тяжелой работы за вас**.

В этом уроке **вы создадите своего первого агента**, способного выполнять такие действия, как генерация изображений, веб-поиск, проверка часового пояса и многое другое!

Вы также опубликуете своего агента **в пространстве Hugging Face Space, чтобы вы могли поделиться им с друзьями и коллегами**.

Давайте начнем!


## Что такое smolagents?

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/smolagents.png" alt="smolagents"/>

Для создания этого агента мы будем использовать библиотеку `smolagents`, которая **предоставляет основу для разработки агентов с легкостью**.

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

В следующем разделе мы углубимся в изучение smolagents. А пока вы можете ознакомиться с этой <a href="https://huggingface.co/blog/smolagents" target="_blank">статьей в блоге</a> или с <a href="https://github.com/huggingface/smolagents" target="_blank">репозиторием библиотеки на GitHub</a>.

Вкратце, `smolagents` - это библиотека, ориентированная на **Агентов кода**, вид агента, который выполняет **"Действия"** через блоки кода, а затем **"Наблюдает"** за результатами, выполняя код.

Вот пример того, что мы будем создавать! 

Мы предоставили нашему агенту **Инструмент генерации изображений** и попросили его сгенерировать изображение кошки.

Агент внутри `smolagents` будет иметь **такое же поведение, как и пользовательский агент, который мы построили ранее**: он будет **думать, действовать и наблюдать в цикле**, пока не придет к окончательному ответу:

<iframe width="560" height="315" src="https://www.youtube.com/embed/PQDKcWiuln4?si=ysSTDZoi8y55FVvA" title="Видеоплеер YouTube" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

Захватывающе, правда?

## Давайте создадим нашего агента!

Для начала продублируйте это пространство (Space): <a href="https://huggingface.co/spaces/agents-course/First_agent_template" target="_blank">https://huggingface.co/spaces/agents-course/First_agent_template</a>
> Спасибо <a href="https://huggingface.co/m-ric" target="_blank">Aymeric</a> за этот шаблон! 🙌


Дублирование этого пространства означает **создание локальной копии в вашем собственном профиле**:
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/duplicate-space.gif" alt="Дубликат"/>

На протяжении всего этого урока единственным файлом, который вам придется изменить, будет (на данный момент неполный) **"app.py »**. Здесь вы можете увидеть [оригинал в шаблоне](https://huggingface.co/spaces/agents-course/First_agent_template/blob/main/app.py). Чтобы найти свой, зайдите в свою копию пространства, затем перейдите на вкладку `Files`, а затем на `app.py` в списке каталогов.

Давайте разберем код вместе:

- Файл начинается с простого, но необходимого импорта библиотек

```python
from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel, load_tool, tool
import datetime
import requests
import pytz
import yaml
from tools.final_answer import FinalAnswerTool
```

Как уже говорилось ранее, мы будем напрямую использовать класс **CodeAgent** из **smolagents**.


### Инструменты

Теперь перейдем к инструментам! Если вы хотите узнать больше об инструментах, не стесняйтесь вернуться к разделу курса [Инструменты](tools).

```python
@tool
def my_custom_tool(arg1:str, arg2:int)-> str: # важно указать возвращаемый тип
    # Сохраните этот формат для описания инструмента / описания аргументов, но не стесняйтесь модифицировать инструмент
    """Инструмент, который пока ничего не делает
    Аргументы:
        arg1: первый аргумент
        arg2: второй аргумент
    """
    return "Какую магию вы будете создавать?"

@tool
def get_current_time_in_timezone(timezone: str) -> str:
    """Инструмент для получения текущего местного времени в указанном часовом поясе.
    Аргменты:
        timezone: Строка, представляющая действительный часовой пояс (например, 'America/New_York').
    """
    try:
        # Создание объекта timezone
        tz = pytz.timezone(timezone)
        # Получение текущего времени в заданном часовом поясе
        local_time = datetime.datetime.now(tz).strftime("%Y-%m-%d %H:%M:%S")
        return f"Текущее местное время в {timezone} составляет: {local_time}"
    except Exception as e:
        return f"Ошибка получения времени для часового пояса '{timezone}': {str(e)}"
```


Инструменты - это то, что мы призываем вас создать в этом разделе! Мы приводим два примера:

1. **нерабочий фиктивный инструмент**, который вы можете модифицировать, чтобы сделать что-то полезное.
2. **действительно работающий инструмент**, который получает текущее время в любой точке мира.

Чтобы определить свой инструмент, необходимо:

1. Предоставить входной и выходной типы для вашей функции, как в `get_current_time_in_timezone(timezone: str) -> str:`
2. **Написать хорошо отформатированную строку документации**. `smolagents` ожидает, что все аргументы будут иметь **текстовое описание в строке документации**.

### Агент

Он использует [`Qwen/Qwen2.5-Coder-32B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-Coder-32B-Instruct) в качестве движка LLM. Это очень способная модель, к которой мы будем обращаться через бессерверный API.

```python
final_answer = FinalAnswerTool()
model = InferenceClientModel(
    max_tokens=2096,
    temperature=0.5,
    model_id='Qwen/Qwen2.5-Coder-32B-Instruct',
    custom_role_conversions=None,
)

with open("prompts.yaml", 'r') as stream:
    prompt_templates = yaml.safe_load(stream)
    
# Создаем наш Кодовый Агент
agent = CodeAgent(
    model=model,
    tools=[final_answer], # добавьте сюда свои инструменты (не удаляйте final_answer)
    max_steps=6,
    verbosity_level=1,
    grammar=None,
    planning_interval=None,
    name=None,
    description=None,
    prompt_templates=prompt_templates
)

GradioUI(agent).launch()
```

Этот агент по-прежнему использует `InferenceClient`, который мы видели в предыдущем разделе за классом **InferenceClientModel**!

Мы приведем более подробные примеры, когда будем представлять фреймворк в разделе 2. Пока же вам нужно сосредоточиться на **добавлении новых инструментов в список инструментов** с помощью параметра `tools` вашего Агента.

Например, вы можете использовать `DuckDuckGoSearchTool`, который был импортирован в первой строке кода, или вы можете изучить `image_generation_tool`, который загружается из Hub позже в коде.

**Добавление инструментов даст вашему агенту новые возможности**, попробуйте проявить творческий подход!

Полная версия "app.py":

```python
from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel, load_tool, tool
import datetime
import requests
import pytz
import yaml
from tools.final_answer import FinalAnswerTool

from Gradio_UI import GradioUI

# Ниже приведен пример инструмента, который ничего не делает. Удивите нас своей креативностью!
@tool
def my_custom_tool(arg1:str, arg2:int)-> str: # важно указать возвращаемый тип
    # Сохраните этот формат для описания инструмента / описания аргументов, но не стесняйтесь модифицировать инструмент
    """Инструмент, который пока ничего не делает
    Аргументы:
        arg1: первый аргумент
        arg2: второй аргумент
    """
    return "Какую магию вы будете создавать?"

@tool
def get_current_time_in_timezone(timezone: str) -> str:
    """Инструмент для получения текущего местного времени в указанном часовом поясе.
    Аргменты:
        timezone: Строка, представляющая действительный часовой пояс (например, 'America/New_York').
    """
    try:
        # Создание объекта timezone
        tz = pytz.timezone(timezone)
        # Получение текущего времени в заданном часовом поясе
        local_time = datetime.datetime.now(tz).strftime("%Y-%m-%d %H:%M:%S")
        return f"Текущее местное время в {timezone} составляет: {local_time}"
    except Exception as e:
        return f"Ошибка получения времени для часового пояса '{timezone}': {str(e)}"


final_answer = FinalAnswerTool()
model = InferenceClientModel(
max_tokens=2096,
temperature=0.5,
model_id='Qwen/Qwen2.5-Coder-32B-Instruct',
custom_role_conversions=None,
)


# Импорт инструмента из Hub
image_generation_tool = load_tool("agents-course/text-to-image", trust_remote_code=True)

with open("prompts.yaml", 'r') as stream:
    prompt_templates = yaml.safe_load(stream)
    
agent = CodeAgent(
    model=model,
    tools=[final_answer], # добавьте сюда свои инструменты (не удаляйте final_answer)
    max_steps=6,
    verbosity_level=1,
    grammar=None,
    planning_interval=None,
    name=None,
    description=None,
    prompt_templates=prompt_templates
)


GradioUI(agent).launch()
```

Ваша **Цель** - познакомиться с Пространством и Агентом. 

В настоящее время агент в шаблоне **не использует никаких инструментов, поэтому постарайтесь снабдить его некоторыми из готовых инструментов или даже сделать новые инструменты самостоятельно!**.

Мы с нетерпением ждем ваших потрясающих выводов агентов в канале discord **#agents-course-showcase**!


---
Поздравляем, вы создали своего первого агента! Не стесняйтесь поделиться им со своими друзьями и коллегами.

Поскольку это ваша первая попытка, совершенно нормально, если он будет немного глючным или медленным. В следующих разделах мы узнаем, как создавать еще более совершенных агентов.

Лучший способ научиться - это попробовать, поэтому не стесняйтесь обновлять его, добавлять новые инструменты, пробовать с другой моделью и т. д.

В следующем разделе вы пройдете финальный тест и получите сертификат!


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/tutorial.mdx" />

### Действия: Обеспечение взаимодействия Агента с его Окружением
https://huggingface.co/learn/agents-course/ru-RU/unit1/actions.md

# Действия: Обеспечение взаимодействия Агента с его Окружением

> [!TIP]
> В этом разделе мы рассмотрим конкретные действия AI агента по взаимодействию с окружением. 
>
> Мы расскажем о том, как представляются действия (с помощью JSON или кода), о важности подхода "остановить и разобрать", а также представим различные типы агентов.

Действия - это конкретные шаги, которые **AI агент предпринимает для взаимодействия с окружением**. 

Будь то просмотр информации в Интернете или управление физическим устройством, каждое действие - это целенаправленная операция, выполняемая агентом. 

Например, агент, помогающий в службе поддержки клиентов, может получать данные о клиентах, предлагать статьи по поддержке или передавать проблемы представителю компании.

## Типы Действий Агента

There are multiple types of Agents that take actions differently:

| Тип агента                                        | Описание |
|---------------------------------------------------|-------------------------------------------------------------------------------------------------------|
| JSON Агент                                        | Действие, которое необходимо предпринять, указывается в формате JSON.                                 |
| Агент кода (Code Agent)                           | Агент пишет блок кода, который интерпретируется извне.                                                |
| Агент вызывающий функции (Function-calling Agent) | Это подкатегория агента JSON, который был дообучен генерировать новое сообщение для каждого действия. |

Сами действия могут служить разным целям:

| Тип действия                | Описание |
|-----------------------------|------------------------------------------------------------------------------------------|
| Сбор информации             | Выполнение поиска в Интернете, запрос к базам данных или получение документов.           |
| Использование инструментов  | Выполнение вызовов API, вычислений и выполнение кода.                                    |
| Взаимодействие с окружением | Манипулирование цифровыми интерфейсами или управление физическими устройствами.          |
| Общение                     | Взаимодействие с пользователями через чат или сотрудничество с другими агентами.         |

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

LLM работает только с текстом и использует его для описания действий, которые она хочет выполнить, и параметров, которые нужно передать инструменту.

## Подход с Остановись и Разберись

Одним из ключевых методов реализации действий является подход **остановить и разобрать**. Этот метод обеспечивает структурированность и предсказуемость выходных данных агента:

1. **Генерация в структурированном формате**:

Агент выводит предполагаемое действие в четком, заранее определенном формате (JSON или код).

2. **Прекращение дальнейшей генерации**:

После завершения действия **агент прекращает генерировать дополнительные токены**. Это позволяет избежать лишнего или ошибочного вывода.

3. **Разбор выходных данных**:

Внешний парсер считывает отформатированное действие, определяет, какой Инструмент следует вызвать, и извлекает необходимые параметры.

Например, агент, которому нужно проверить погоду, может вывести:


```json
Thought: I need to check the current weather for New York.
Action :
{
  "action": "get_weather",
  "action_input": {"location": "New York"}
}
```
Затем фреймворк может легко разобрать имя функции для вызова и аргументы для применения.

Такой понятный, машиночитаемый формат минимизирует ошибки и позволяет внешним инструментам точно обрабатывать команду агента.

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

## Агенты Кода

Альтернативный подход - использование *Агентов Кода*.
Идея заключается в следующем: ** вместо того, чтобы выводить простой объект JSON**, агент кода генерирует **исполняемый блок кода - обычно на языке высокого уровня, таком как Python**. 

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/code-vs-json-actions.png" alt="Code Agents" />

Этот подход имеет ряд преимуществ:

- **Выразительность:** Код может естественным образом представлять сложную логику, включая циклы, условия и вложенные функции, обеспечивая большую гибкость, чем JSON.
- **Модульность и возможность повторного использования:** Генерируемый код может включать функции и модули, которые можно повторно использовать в различных действиях или задачах.
- **Улучшенная отлаживаемость:** Благодаря четко определенному синтаксису программирования ошибки в коде зачастую легче обнаружить и исправить.
- **Прямая интеграция:** Агенты кода могут напрямую интегрироваться с внешними библиотеками и API, что позволяет выполнять более сложные операции, такие как обработка данных или принятие решений в режиме реального времени.

Например, Агент Кода, которому поручено получить информацию о погоде, может сгенерировать следующий фрагмент на языке Python:

```python
# Пример Агента Кода: Получение информации о погоде
def get_weather(city):
    import requests
    api_url = f"https://api.weather.com/v1/location/{city}?apiKey=YOUR_API_KEY"
    response = requests.get(api_url)
    if response.status_code == 200:
        data = response.json()
        return data.get("weather", "No weather information available")
    else:
        return "Error: Unable to fetch weather data."

# Выполнение функции и подготовка окончательного ответа
result = get_weather("New York")
final_answer = f"The current weather in New York is: {result}"
print(final_answer)
```

В этом примере Агент Кода:

- Получает данные о погоде **посредством вызова API**,
- обрабатывает ответ,
- И использует функцию print() для вывода окончательного ответа.

Этот метод **также следует подходу "остановись и разбери"**, четко разграничивая блок кода и сигнализируя о завершении выполнения (здесь - выводом final_answer).

---

Мы узнали, что действия связывают внутренние рассуждения агента и его взаимодействие с реальным миром, выполняя четкие, структурированные задачи - через JSON, код или вызов функций.

Такое продуманное выполнение гарантирует, что каждое действие будет точным и готовым к внешней обработке с помощью подхода «остановить и разобрать». В следующем разделе мы рассмотрим Наблюдения, чтобы увидеть, как агенты улавливают и интегрируют обратную связь от своего окружения.

После этого мы будем **окончательно готовы к созданию нашего первого агента!**.








<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/actions.mdx" />

### Table of Contents
https://huggingface.co/learn/agents-course/ru-RU/unit1/README.md

# Table of Contents

You can access Unit 1 on hf.co/learn 👉 <a href="https://hf.co/learn/agents-course/unit1/introduction">here</a> 

<!--
| Title | Description |
|-------|-------------|
| [Definition of an Agent](1_definition_of_an_agent.md) | General example of what agents can do without technical jargon. |
| [Explain LLMs](2_explain_llms.md) | Explanation of Large Language Models, including the family tree of models and suitable models for agents. |
| [Messages and Special Tokens](3_messages_and_special_tokens.md) | Explanation of messages, special tokens, and chat-template usage. |
| [Dummy Agent Library](4_dummy_agent_library.md) | Introduction to using a dummy agent library and serverless API. |
| [Tools](5_tools.md) | Overview of Pydantic for agent tools and other common tool formats. |
| [Agent Steps and Structure](6_agent_steps_and_structure.md) | Steps involved in an agent, including thoughts, actions, observations, and a comparison between code agents and JSON agents. |
| [Thoughts](7_thoughts.md) | Explanation of thoughts and the ReAct approach. |
| [Actions](8_actions.md) | Overview of actions and stop and parse approach. |
| [Observations](9_observations.md) | Explanation of observations and append result to reflect. |
| [Quizz](10_quizz.md) | Contains quizzes to test understanding of the concepts. |
| [Simple Use Case](11_simple_use_case.md) | Provides a simple use case exercise using datetime and a Python function as a tool. |
-->

<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/README.md" />

### Раздел 1 Тест
https://huggingface.co/learn/agents-course/ru-RU/unit1/final-quiz.md

# Раздел 1 Тест

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-unit1sub4DONE.jpg" alt="Раздел 1 планирование"/>

Отлично справились с первым разделом! Давайте проверим ваше понимание ключевых понятий, рассмотренных до сих пор.

Когда вы пройдете этот тест, перейдите к следующему разделу, чтобы получить свой сертификат.

Удачи!

## Тест

Вот интерактивный тест. Этот тест размещен в пространстве Hugging Face Hub. В ней вам предстоит ответить на ряд вопросов с несколькими вариантами ответов, чтобы проверить ваше понимание ключевых понятий, рассмотренных в этом разделе. После завершения теста вы сможете увидеть свой результат и распределение правильных ответов.

Один важный момент: **не забудьте нажать на кнопку Submit  после прохождения теста, иначе ваша оценка не будет сохранена!**

<iframe
    src="https://agents-course-unit-1-quiz.hf.space"
    frameborder="0"
    width="850"
    height="450"
></iframe>

Вы также можете пройти этот тест 👉 [здесь](https://huggingface.co/spaces/agents-course/unit_1_quiz)


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/final-quiz.mdx" />

### Мысль: Внутреннее Рассуждение и Re-Act подход
https://huggingface.co/learn/agents-course/ru-RU/unit1/thoughts.md

# Мысль: Внутреннее Рассуждение и Re-Act подход

> [!TIP]
> В этом разделе мы погрузимся во внутреннюю работу AI агента - его способность рассуждать и планировать. Мы рассмотрим, как агент использует свой внутренний диалог для анализа информации, разбиения комплексных проблем на управляемые шаги и принятия решения о том, какие действия следует предпринять дальше. Кроме того, мы представим подход Re-Act - технику подсказок, которая побуждает модель думать «шаг за шагом», прежде чем действовать.

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

При этом используется способность Большой Языковой Модели (Large Language Model, LLM) агента **анализировать информацию, представленную в подсказке**.

Считайте это внутренним диалогом агента, в ходе которого он обдумывает поставленную задачу и разрабатывает стратегию действий.

Мысли Агента отвечают за доступ к текущим наблюдениям и решение о том, каким должно быть следующее действие (действия).

Благодаря этому процессу агент может **разбивать сложные проблемы на более мелкие и управляемые шаги**, рефлексировать над прошлым опытом и постоянно корректировать свои планы основываясь на новой информации.

Вот несколько примеров общих мыслей:

| Тип мышления | Пример |
|----------------|---------|
| Планирование | "Мне нужно разбить эту задачу на три этапа: 1) собрать данные, 2) проанализировать тенденции, 3) создать отчет"|   
| Анализ | "Судя по сообщению об ошибке, проблема заключается в параметрах подключения к базе данных" |   
| Принятие решений | "Учитывая бюджетные ограничения пользователя, я должен рекомендовать вариант среднего уровня"|   
| Решение проблем | "Чтобы оптимизировать этот код, я должен сначала профилировать его, чтобы выявить узкие места" |   
| Интеграция памяти | "Пользователь ранее упоминал, что предпочитает Python, поэтому я приведу примеры на Python"|
| Саморефлексия | "Мой последний подход не сработал, я должен попробовать другую стратегию"|    
| Постановка цели | "Чтобы выполнить эту задачу, мне нужно сначала установить критерии приемки" |    
| Приоритизация | "Уязвимость безопасности должна быть устранена до добавления новых функций" |    

> **Примечание:** В случае дообучения LLM вызову функций, процесс мышления необязателен.
> *Если вы не знакомы с вызовом функций, более подробно об этом будет рассказано в разделе Действия.*

## Подход Re-Act

Ключевым методом является **ReAct подход**, который представляет собой конкатенацию " Рассуждения (Reasoning)" (Мысли) и "Действия (Acting)". 

ReAct - это простая техника подсказки, которая добавляет «Давайте думать шаг за шагом», прежде чем позволить LLM декодировать следующие токены. 

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

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

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/ReAct.png" alt="ReAct"/>
<figcaption>(d) - это пример подхода Re-Act, когда мы подсказываем: " Давай думать шаг за шагом".
</figcaption>
</figure>

> [!TIP]
> В последнее время мы наблюдаем большой интерес к стратегиям рассуждений. Именно это лежит в основе таких моделей, как Deepseek R1 или OpenAI o1, которые были дообучены "думать перед ответом".
>
> Эти модели были обучены всегда включать определенные секции _размышлений_ (заключенные между специальными токенами `<think>` и `</think>`). Это не просто техника подсказки, как в ReAct, а метод обучения, при котором модель учится генерировать эти секции после анализа тысяч примеров, которые показывают, чего мы от нее ожидаем.

--- 
Теперь, когда мы лучше понимаем процесс Мышления, давайте углубимся во вторую часть процесса: Действие.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/thoughts.mdx" />

### Что такое Агент?
https://huggingface.co/learn/agents-course/ru-RU/unit1/what-are-agents.md

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

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-no-check.jpg" alt="Unit 1 planning"/>

К концу этого раздела вы будете чувствовать себя комфортно с концепцией агентов и их различными применениями в ИИ.

Чтобы объяснить, что такое агент, давайте начнем с аналогии.

## Общая картина: Агент Альфред

Познакомьтесь с Альфредом. Альфред - **агент**.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/this-is-alfred.jpg" alt="This is Alfred"/>

Представьте, что Альфред **получает команду**, например: «Альфред, я бы хотел кофе, пожалуйста».

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/coffee-please.jpg" alt="I would like a coffee"/>

Поскольку Альфред **понимает естественный язык**, он быстро понимает нашу просьбу.

Перед выполнением заказа Альфред занимается **рассуждениями и планированием**, определяя, какие действия и инструменты ему понадобятся:

1. Пойти на кухню  
2. Воспользоваться кофеваркой  
3. Заварите кофе  
4. Принесите кофе обратно

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/reason-and-plan.jpg" alt="Reason and plan"/>

Когда у него есть план, он **должен действовать**. Чтобы выполнить свой план, **он может использовать инструменты из списка инструментов, о которых он знает**. 

В данном случае, чтобы приготовить кофе, он использует кофеварку. Он активирует кофеварку, чтобы сварить кофе.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/make-coffee.jpg" alt="Make coffee"/>

Наконец Альфред приносит нам свежесваренный кофе.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/bring-coffee.jpg" alt="Bring coffee"/>

Именно это и есть агент: **ИИ модель, способная рассуждать, планировать и взаимодействовать со своим окружением**. 

Мы называем его агентом, потому что он обладает _агентностью_, то есть способностью взаимодействовать с окружающей средой.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/process.jpg" alt="Agent process"/>

## Давайте будем более формальны

Теперь, когда вы получили общую картину, вот более точное определение:

> Агент - это система, использующая модель искусственного интеллекта для взаимодействия с окружающей средой с целью достижения определенной пользователем цели. Он сочетает в себе рассуждения, планирование и выполнение действий (часто с помощью внешних инструментов) для выполнения задач.

Считайте, что агент состоит из двух основных частей:

1. **Мозг (модель ИИ)**.

Именно здесь происходит все мышление. Модель ИИ **занимается рассуждениями и планированием**.
Она решает, **какие действия предпринять в зависимости от ситуации**.

2. **Тело (возможности и инструменты)**.

Эта часть представляет собой **все, что агент способен делать**.

Набор **возможных действий** зависит от того, чем **наделен агент**. Например, поскольку у человека нет крыльев, он не может выполнять **действие «летать», но может выполнять такие **действия**, как «ходить», «бегать», «прыгать», «хватать» и так далее.

## Какие модели ИИ мы используем для агентов?

Наиболее распространенной моделью ИИ, используемой в агентах, является LLM (большая языковая модель), которая принимает на вход **Текст** и выводит **Текст**.

Известными примерами являются **GPT4** от **OpenAI**, **LLama** от **Meta**, **Gemini** от **Google** и т. д. Эти модели были обучены на огромном количестве текстов и способны к обобщению. Подробнее о LLM мы узнаем в [следующем разделе](what-are-llms).

> [!TIP]
> Также можно использовать модели, принимающие другие входные данные, в качестве основной модели агента. Например, Vision Language Model (VLM), которая похожа на LLM, но также понимает изображения в качестве входных данных. Пока что мы сосредоточимся на LLM и обсудим другие варианты позже.

## Как ИИ воздействует на окружающую среду?

LLM - замечательные модели, но **они могут генерировать только текст**. 

Однако если вы попросите известное чат-приложение, например HuggingChat или ChatGPT, сгенерировать изображение, они смогут! Как такое возможно?

Ответ заключается в том, что разработчики HuggingChat, ChatGPT и подобных приложений реализовали дополнительный функционал (так называемые **инструменты (tools)**), которые LLM может использовать для создания изображений.

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/eiffel_brocolis.jpg" alt="Eiffel Brocolis"/>
<figcaption>The model used an Image Generation Tool to generate this image.
</figcaption>
</figure>

Подробнее об инструментах мы поговорим в разделе [Инструменты](tools).

## Какой тип задач может выполнять Агент?

Агент может выполнять любые задачи, которые мы реализуем с помощью **Инструментов** для выполнения **Действий**.

Например, если я напишу агента, который будет действовать как мой личный помощник (как Siri) на моем компьютере, и попрошу его «отправить электронное письмо моему менеджеру с просьбой отложить сегодняшнюю встречу», я могу дать ему код для отправки электронных писем. Это будет новый инструмент, который агент сможет использовать всякий раз, когда ему понадобится отправить письмо. Мы можем написать его на языке Python:

```python
def send_message_to(recipient, message):
    """Используется для отправки электронного сообщения получателю"""
    ...
```

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

```python
send_message_to("Менеджер", "Мы можем отложить сегодняшнюю встречу?")
```

Дизайн **Инструментов очень важен и оказывает большое влияние на качество работы вашего Агента**. Некоторые задачи требуют создания очень специфических инструментов, в то время как другие могут быть решены с помощью инструментов общего назначения, таких как "web_search".

> Обратите внимание, что **Действия - это не то же самое, что Инструменты**. Действие, например, может включать в себя использование нескольких инструментов для выполнения.

Предоставление агенту возможности взаимодействовать с окружающей средой **позволяет использовать его в реальной жизни компаниями и частными лицами**.

### Пример 1: Виртуальные персональные ассистенты

Виртуальные помощники, такие как Siri, Alexa или Google Assistant, работают как агенты, когда взаимодействуют от имени пользователей в их цифровом окружении.

Они принимают запросы пользователей, анализируют контекст, извлекают информацию из баз данных, дают ответы или инициируют действия (например, устанавливают напоминания, отправляют сообщения или управляют смарт-устройствами).

Пример 2: Чат-боты для обслуживания клиентов

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

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

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


### Пример 3: ИИ неигрового персонажа в видеоигре

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

Вместо того чтобы следовать жесткому дереву поведения, они могут **реагировать контекстно, адаптироваться к взаимодействию с игроком** и генерировать более тонкие диалоги. Такая гибкость помогает создавать более реалистичные и увлекательные персонажи, которые развиваются вместе с действиями игрока.

---

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

- **Понимать естественный язык:** Интерпретировать и осмысленно отвечать на человеческие инструкции.

- **Рассуждать и планировать:** Анализировать информацию, принимать решения и разрабатывать стратегии для решения проблем.

- **Взаимодействовать с окружающей средой:** Собирать информацию, предпринимать действия и наблюдать за их результатами.

Теперь, когда вы хорошо знаете, что такое агенты, давайте закрепим ваше понимание с помощью короткого теста без оценки. После этого мы погрузимся в «мозг агента»: [LLMs](what-are-llms).


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/what-are-agents.mdx" />

### Понимание AI Агентов через цикл Мысль - Действие - Наблюдение.
https://huggingface.co/learn/agents-course/ru-RU/unit1/agent-steps-and-structure.md

# Понимание AI Агентов через цикл Мысль - Действие - Наблюдение.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-check-3.jpg" alt="Раздел 1 планирование"/>

В предыдущих разделах мы узнали:

- **Как инструменты становятся доступны агенту в системной подсказке**.
- **Как AI агенты являются системами, которые могут 'рассуждать', планировать и взаимодействовать с окружающей средой**.

В этом разделе **мы рассмотрим рабочий процесс агента AI полностью**, цикл, который мы определили как "Мысль - Действие - Наблюдение". 

А затем мы углубимся в каждый из этих этапов.


## Основные компоненты

Агенты работают в непрерывном цикле: **думать (Мысль) → действовать (Действие) и наблюдать (Наблюдение)**.

Давайте разложим эти действия на составляющие:

1. **Мысль**: LLM-часть Агента решает, каким должен быть следующий шаг.
2. **Действие:** Агент выполняет действие, вызывая инструменты с соответствующими аргументами.
3. **Наблюдение:** Модель размышляет над ответом, полученным от инструмента.

## Цикл "Мысль-Действие-Наблюдение"

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

Визуально это выглядит следующим образом:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/AgentCycle.gif" alt="Цикл Думай, Действуй, Наблюдай"/>

Во многих фреймворках Агентов **правила и рекомендации встраиваются непосредственно в системную подсказку**, гарантируя, что каждый цикл будет следовать определенной логике.

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

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/system_prompt_cycle.png" alt="Цикл Думай, Действуй, Наблюдай"/>

Здесь мы видим, что в системном сообщении мы определили :

- *Поведение Агента*.
- *Инструменты, к которым имеет доступ наш Агент*, как мы описали в предыдущем разделе.
- Цикл *Мысль-Действие-Наблюдение*, который мы заложили в инструкции LLM.

Давайте рассмотрим небольшой пример, чтобы понять суть процесса, прежде чем углубляться в каждый его шаг.

## Альфред, Агент сообщающий погоду

Мы создали Альфреда, погодного агента.

Пользователь спрашивает Альфреда: «Какая сегодня погода в Нью-Йорке?».

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent.jpg" alt="Агент Альфред"/>

Задача Альфреда - ответить на этот запрос, используя инструмент API погоды. 

Вот как выглядит этот цикл:

### Мысль

**Внутренние рассуждения:**

Получив запрос, внутренний диалог Альфреда может быть таким:

*"Пользователю нужна текущая информация о погоде в Нью-Йорке. У меня есть доступ к инструменту, который получает данные о погоде. Сначала мне нужно обратиться к API погоды, чтобы получить актуальную информацию."*

Этот шаг показывает, что агент разбивает проблему на этапы: сначала собирает необходимые данные.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-1.jpg" alt="Агент Альфред"/>

### Действие

**Использование инструмента:**.

Основываясь на своих рассуждениях и на том факте, что Альфред знает об инструменте `get_weather`, Альфред подготавливает команду в формате JSON, которая вызывает инструмент API погоды. Например, его первым действием может быть:

Мысль: Мне нужно проверить текущую погоду в Нью-Йорке.

 ```
    {
      "action": "get_weather",
      "action_input": {
        "location": "New York"
      }
    }
 ```

Здесь действие четко указывает, какой инструмент следует вызвать (например, get_weather) и какой параметр передать ("location": "New York").

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-2.jpg" alt="Агент Альфред"/>

### Наблюдение

**Обратная связь от окружающей среды:**.

После вызова инструмента Альфред получает наблюдение. Это могут быть необработанные данные о погоде из API, например:

*"Текущая погода в Нью-Йорке: частично облачно, 15°C, влажность 60%."*

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-3.jpg" alt="Агент Альфред"/>

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


### Обновленная мысль

**Рефлексия:**

Получив данные наблюдения, Альфред обновляет свои внутренние рассуждения:

*"Теперь, когда у меня есть данные о погоде в Нью-Йорке, я могу подготовить ответ для пользователя."*

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-4.jpg" alt="Агент Альфред"/>


### Финальное Действие

Затем Алфред генерирует окончательный ответ, отформатированный так, как мы ему сказали:

Мысль: У меня есть данные о погоде. Текущая погода в Нью-Йорке частично облачная, температура 15 °C и влажность 60 %».

Окончательный ответ : Текущая погода в Нью-Йорке частично облачно с температурой 15 °C и влажностью 60 %.

Это заключительное действие возвращает ответ пользователю, закрывая цикл.


<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/alfred-agent-5.jpg" alt="Агент Альфред"/>


Что мы видим в этом примере:

- **Агенты проходят цикл до тех пор, пока цель не будет достигнута:**

**Процесс Альфреда цикличен**. Он начинает с мысли, затем действует, вызывая инструмент, и, наконец, наблюдает за результатом. Если бы наблюдение показало ошибку или неполноту данных, Альфред мог бы снова войти в цикл, чтобы скорректировать свой подход.

- **Интеграция инструментов:**

Способность вызывать инструменты (например, API погоды) позволяет Альфреду выходить **за пределы статических знаний и получать данные в реальном времени**, что является важным аспектом многих AI Агентов.

- **Динамическая адаптация:**

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

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

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

---

Теперь давайте углубимся в изучение Мысли, Действия, Наблюдения как отдельных этапов этого процесса.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/agent-steps-and-structure.mdx" />

### Быстрая самопроверка (не оценивается) [[quiz2]]
https://huggingface.co/learn/agents-course/ru-RU/unit1/quiz2.md

# Быстрая самопроверка (не оценивается) [[quiz2]] 


Что?! Еще один тест? Мы знаем, мы знаем, ... 😅 Но эта короткий, не оцениваемый тест поможет вам **закрепить ключевые понятия, которые вы только что выучили**.

Этот тест охватывает Большие Языковые Модели (Large Language Model), системы сообщений и инструменты; важные компоненты для понимания и создания агентов ИИ.

### Вопрос 1: Что из перечисленного ниже лучше всего описывает AI инструмент?

<Question
choices={[
{
text: "Процесс, который генерирует только текстовые ответы.",
explain: "",
},
{
text: "Исполняемый процесс или внешнее API, позволяющие агентам выполнять определенные задачи и взаимодействовать с внешней средой",
explain: "Инструменты - это исполняемые функции, которые агенты могут использовать для выполнения определенных задач и взаимодействия с внешней средой.",
correct: true
},
{
text: "Функция, хранящая диалоги агентов.",
explain: "",
}
]}
/>

---

### Вопрос 2: Как AI агенты используют инструменты в качестве формы "действия" в окружающей среде?

<Question
choices={[
{
text: "Пассивно ожидая инструкций пользователя.",
explain: "",
},
{
text: "Используя только предварительно запрограммированные ответы.",
explain: "",
},
{
text: "Запрашивая LLM сгенерировать код вызова инструментов, когда это необходимо, и запуская инструменты от имени модели",
explain: "Агенты могут вызывать инструменты и использовать рассуждения для планирования и перепланирования на основе полученной информации.",
correct: true
}
]}
/>

---

### Вопрос 3: Что такое Большая Языковая Модель (LLM)?

<Question
choices={[
{
text: "Простой чат-бот, предназначенный для ответов на заранее определенные вопросы.",
explain: "",
},
{
text: "Модель глубокого обучения, обученная на больших объемах текста для понимания и генерации человекоподобного языка.",
explain: "",
correct: true
},
{
text: "AI, основанный на правилах, который следует строго определенным командам.",
explain: "",
}
]}
/>

---

### Вопрос 4: Что из перечисленного ниже лучше всего описывает роль специальных токенов в LLM?

<Question
choices={[
{
text: "Это дополнительные слова, которые хранятся в словаре модели для повышения качества генерации текста.",
explain: "",
},
{
text: "Они выполняют такие специфические функции, как обозначение конца последовательности (EOS) или разделение различных ролей сообщений в моделях чата.",
explain: "",
correct: true
},
{
text: "Это случайно вставленные токены, используемые для улучшения вариативности ответов.",
explain: "",
}
]}
/>

---

### Вопрос 5: Как внутри AI модели чата обрабатывают сообщения пользователей?

<Question
choices={[
{
text: "Они напрямую интерпретируют сообщения как структурированные команды без каких-либо преобразований.",
explain: "",
},
{
text: "Они преобразуют сообщения пользователя в форматированную подсказку, конкатенируя сообщения системы, пользователя и ассистента.",
explain: "",
correct: true
},
{
text: "Они генерируют ответы случайным образом, основываясь на предыдущих диалогах.",
explain: "",
}
]}
/>

---


Получилось? Отлично! Теперь давайте **погрузимся в полный поток Агентов и начнем создавать вашего первого ИИ-Агента!**.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/quiz2.mdx" />

### Небольшой тест (не оценивается) [[quiz1]]
https://huggingface.co/learn/agents-course/ru-RU/unit1/quiz1.md

# Небольшой тест (не оценивается) [[quiz1]] 

До этого момента вы понимали общую картину Агентов, что они собой представляют и как работают. Пришло время провести небольшой тест, поскольку **проверка себя** - это лучший способ учиться и [избежать иллюзии компетентности](https://www.coursera.org/lecture/learning-how-to-learn/illusions-of-competence-BuFzf). Это поможет вам определить, **где вам нужно подтянуть свои знания**.

Это необязательный тест, и он не на что не влияет.

### Вопрос 1: Что такое агент?
Что из перечисленного ниже лучше всего описывает AI Агента?

<Question
choices={[
{
text: "Система, которая обрабатывает только статичный текст и не взаимодействует с окружающей средой.",
explain: "Агент должен уметь совершать действия и взаимодействовать с окружением.",
},
{
text: "AI модель, которая может рассуждать, планировать и использовать инструменты взаимодействуя с окружающей средой для достижения определенной цели.",
explain: "Это определение отражает основные характеристики Агента.",
correct: true
},
{
text: "Чатбот, который отвечает на вопросы, не имея возможности выполнять какие-либо действия.",
explain: "У такого чатбота нет возможности выполнять действия, что отличает его от агента.",
},
{
text: "Цифровая энциклопедия, которая предоставляет информацию, но не может выполнять задания.",
explain: "Агент активно взаимодействует с окружением, а не просто предоставляет статичную информацию.",
}
]}
/>

---

### Вопрос 2: Какова роль планирования в работе Агента?
Почему Агенту необходимо планировать, прежде чем предпринимать какие-либо действия?

<Question
choices={[
{
text: "Чтобы запомнить предыдущие взаимодействия.",
explain: "Планирование - это определение будущих действий, а не запоминание прошлых взаимодействий.",
},
{
text: "Чтобы определить последовательность действий и выбрать соответствующие инструменты, необходимые для выполнения запроса пользователя.",
explain: "Планирование помогает агенту определить оптимальные шаги и инструменты для выполнения задачи.",
correct: true
},
{
text: "Чтобы генерировать случайные действия без какой-либо цели.",
explain: "Планирование гарантирует, что действия Агента будут намеренными, а не случайными.",
},
{
text: "Перевод текста без дополнительных рассуждений.",
explain: "Планирование - это структурирование действий, а не просто преобразование текста.",
}
]}
/>

---

### Вопрос 3: Как Инструменты расширяют Возможности Агента?
Почему инструменты необходимы Агенту?

<Question
choices={[
{
text: "Инструменты - это избыточные компоненты, которые не влияют на работу агента.",
explain: "Инструменты расширяют возможности Агента, позволяя ему выполнять действия, выходящие за рамки генерации текста.",
},
{
text: "Инструменты предоставляют агенту возможность выполнять действия, которые модель генерации текста не может выполнить в естественных условиях, например, готовить кофе или генерировать изображения.",
explain: "Инструменты позволяют агентам взаимодействовать с реальным миром и выполнять задачи.",
correct: true
},
{
text: "Инструменты используются исключительно для хранения памяти.",
explain: "Инструменты предназначены в первую очередь для выполнения действий, а не только для хранения данных.",
},
{
text: "Инструменты ограничивают Агента только текстовыми ответами.",
explain: "Напротив, инструменты позволяют агентам выходить за рамки текстовых ответов.",
}
]}
/>

---

### Вопрос 4: Чем Действия отличаются от Инструментов?
В чем ключевое различие между Действиями и Инструментами?

<Question
choices={[
{
text: "Действия - это шаги, которые выполняет агент, а Инструменты - это внешние ресурсы, которые агент может использовать для выполнения этих действий.",
explain: "Действия - это цели более высокого уровня, а Инструменты - это конкретные функции, к которым может обратиться агент.",
correct: true
},
{
text: "Действия и Инструменты - это одно и то же, и их можно использовать как взаимозаменяемые.",
explain: "Нет, Действия - это цели или задачи, а Инструменты - это конкретные утилиты, которые агент использует для их достижения.",
},
{
text: "Инструменты - это общее, а Действия - только для физических взаимодействий.",
explain: "Не обязательно. Действия могут включать как цифровые, так и физические задачи.",
},
{
text: "Действия требуют LLM, а инструменты - нет.",
explain: "Хотя LLM помогают принимать решения о действиях, сами действия не зависят от LLM.",
}
]}
/>

---

### Вопрос 5: Какую роль играют Большие Языковые Модели (LLM) в Агентах?
Какой вклад вносят LLM в функциональность агента?

<Question
choices={[
{
text: "LLM используются в качестве статических баз данных, которые хранят не предобработанную информацию.",
explain: "LLM не просто хранят информацию, а активно предобработывают вводимый текст и генерируют ответы.",
},
{
text: "LLM служат 'мозгом' агента, обеспечивая предобработку (препроцессинг) текстовых данных для понимания инструкций и планирования действий.",
explain: "LLM позволяют агенту интерпретировать, планировать и принимать решения о дальнейших действиях.",
correct: true
},
{
text: "LLM используются только для предобработки (препроцессинга) изображений, но не для работы с текстом.",
explain: "LLM в основном работают с текстом, хотя иногда могут взаимодействовать с мультимодальными данными.",
},
{
text: "LLM не используются.",
explain: "LLM являются основным компонентом современных AI агентов.",
}
]}
/>

---

### Вопрос 6: Что из перечисленного ниже лучше всего демонстрирует AI Агент?
Какой пример из реального мира лучше всего иллюстрирует работу AI Агента?

<Question
choices={[
{
text: "Статическая страница FAQ на веб-сайте.",
explain: "Статическая страница FAQ не взаимодействует с пользователями динамически и не предпринимает никаких действий.",
},
{
text: "Виртуальный помощник, подобный Siri или Alexa, который может понимать устные команды, рассуждать на их основе и выполнять такие задачи, как установка напоминаний или отправка сообщений.",
explain: "Этот пример включает в себя рассуждения, планирование и взаимодействие с окружением.",
correct: true
},
{
text: "Базовый калькулятор, выполняющий арифметические операции.",
explain: "Калькулятор следует фиксированным правилам, не рассуждая и не планируя, поэтому он не является агентом.",
},
{
text: "NPC в видеоигре, который следует записанным в сценарии реакциям.",
explain: "Если NPC не может рассуждать, планировать и использовать инструменты, он не может функционировать как AI Агент.",
}
]}
/>

---

Поздравляем вас с окончанием теста 🥳, если вы пропустили какие-то элементы, найдите время прочитать главу еще раз, чтобы закрепить свои знания. Если вы справились с тестом, значит, вы готовы глубже погрузиться в «мозг агента»: LLM.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/quiz1.mdx" />

### Заключение [[conclusion]]
https://huggingface.co/learn/agents-course/ru-RU/unit1/conclusion.md

# Заключение [[conclusion]]

Поздравляем с завершением этого первого раздела 🥳.

Вы только что **овладели основами работы агентов** и создали своего первого AI Агента!

Это **нормально, если вы все еще чувствуете себя сбитым с толку некоторыми из этих элементов**. Агенты - сложная тема, и обычно требуется время, чтобы понять все.

**Потратьте время, чтобы действительно понять материал**, прежде чем продолжать. Важно освоить эти элементы и заложить прочный фундамент, прежде чем приступать к самой интересной части.

А если вы пройдете тест, не забудьте получить сертификат 🎓 👉 [здесь](https://huggingface.co/spaces/agents-course/unit1-certification-app)

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/certificate-example.jpg" alt="Пример Сертификата"/>

В следующем (бонусном) разделе вы научитесь **дообучать Agent вызову функций (а также вызову инструментов по запросу пользователя)**.

Наконец, мы хотели бы **услышать, что вы думаете о курсе и как мы можем его улучшить**. Если у вас есть отзыв, пожалуйста, 👉 [заполните эту форму](https://docs.google.com/forms/d/e/1FAIpQLSe9VaONn0eglax0uTwi29rIn4tM7H2sYmmybmG5jJNlE5v0xA/viewform?usp=dialog)

### Продолжайте учиться, оставайтесь потрясающими 🤗

<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/conclusion.mdx" />

### Введение в Агентов
https://huggingface.co/learn/agents-course/ru-RU/unit1/introduction.md

# Введение в Агентов

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/thumbnail.jpg" alt="Thumbnail"/>

Добро пожаловать в первый раздел, где **вы заложите прочный фундамент основ ИИ-агентов**, включая:

- **Понимание агентов**  
  - Что такое агент и как он работает?  
  - Как агенты принимают решения, используя рассуждения и планирование?

- **Роль LLM (Large Language Models - больших языковых моделей) в агентах**.  
  - Как LLM служат «мозгом» агента.  
  - Как LLM структурируют диалоги с помощью системы сообщений.

- **Инструменты (Tools) и Действия (Actions)**.  
  - Как агенты используют внешние инструменты для взаимодействия с окружающей средой.  
  - Как создавать и интегрировать инструменты для своего агента.

- **Процесс работы агента (Agent Workflow):** 
  - *Думать* → *Действовать* → *Наблюдать*.

Изучив эти темы, **вы создадите своего первого агента**, используя `smolagents`! 

Ваш агент по имени Альфред справится с простым заданием и продемонстрирует, как применять эти понятия на практике. 

Вы даже узнаете, как **опубликовать своего агента в Hugging Face Spaces**, чтобы поделиться им с друзьями и коллегами.

Наконец, в конце этого раздела вы пройдете тест. Пройдя его, вы **получите свой первый сертификат курса**: 🎓 Сертификат по основам работы с агентами.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/certificate-example.jpg" alt="Certificate Example"/>

Этот раздел - ваша **основная отправная точка**, закладывающая основу для понимания Агентов, прежде чем вы перейдете к более сложным темам.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-no-check.jpg" alt="Unit 1 planning"/>

Это большой раздел, поэтому **не торопитесь** и не стесняйтесь время от времени возвращаться к нему.

Готовы? Погружаемся! 🚀


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/introduction.mdx" />

### Что такое Инструменты?
https://huggingface.co/learn/agents-course/ru-RU/unit1/tools.md

# Что такое Инструменты?

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-check-2.jpg" alt="Раздел 1 планирование"/>

Одним из важнейших аспектов AI Агентов является их способность предпринимать **действия**. Как мы видели, это происходит благодаря использованию **Инструментов**.

В этом разделе мы узнаем, что такое Инструменты, как их эффективно разработать и как интегрировать их в вашего Агента с помощью Системного Сообщения.

Предоставив своему агенту правильные инструменты и четко описав, как они работают, вы сможете значительно расширить возможности своего AI. Давайте погружаться!


## Что такое AI Инструменты?

** Инструмент - это функция, предоставленная LLM**. Эта функция должна выполнять **четкую цель**.

Вот некоторые часто используемые в AI агентах инструменты:

| Инструмент | Описание |
|----------------|---------------------------------------------------------------|
| Веб-поиск | Позволяет агенту получать актуальную информацию из Интернета. |
| Генерация изображений | Создает изображения на основе текстовых описаний. |
| Извлечение      | Извлекает информацию из внешнего источника.                 |
| | Интерфейс API | Взаимодействие с внешним API (GitHub, YouTube, Spotify и т. д.). |

Это лишь примеры, поскольку на самом деле вы можете создать инструмент для любого случая использования!

Хороший инструмент должен быть чем-то, что **дополняет возможности LLM**. 

Например, если вам нужно выполнить арифметические действия, то предоставление вашему LLM **калькулятора** обеспечит лучшие результаты, чем полагаться на собственные возможности модели.

Кроме того, **LLM предсказывают завершение подсказки на основе своих обучающих данных**, что означает, что их внутренние знания включают только события, произошедшие до их обучения. Поэтому, если вашему агенту нужны свежие данные, вы должны предоставить их с помощью какого-либо инструмента.

Например, если вы спросите у LLM напрямую (без инструмента поиска) о сегодняшней погоде, LLM потенциально может выдать случайную погоду в виде галлюцинаций.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/weather.jpg" alt="Погода"/>

- Инструмент должен:

  - **иметь текстовое описание того, что делает функция**.
  - *быть Вызываемым (Callable)* (чем-то, что выполняет действие).
  - *иметь Аргументы* с типизацией.
  - (Необязательно) иметь Выходные данные с типизацией.

## Как работают инструменты?

Как мы видели, **LLM могут только получать текстовые данные на вход и генерировать текстовые данные на выход. У них нет возможности самостоятельно вызывать инструменты. Когда мы говорим о _предоставлении инструментов агенту_, мы имеем в виду, что мы **обучаем** LLM существованию инструментов и просим модель генерировать текст, который будет вызывать инструменты, когда это необходимо. Например, если мы предоставим инструмент для проверки погоды в определенном месте из Интернета, а затем спросим LLM о погоде в Париже, LLM распознает этот вопрос как релевантную возможность использовать инструмент "weather", которой мы его научили. LLM сгенерирует _текст_ в виде кода, чтобы вызвать этот инструмент. Ответственность **Агента** заключается в том, чтобы проанализировать вывод LLM, распознать, что требуется вызов инструмента, и вызвать его от имени LLM. Выходные данные от инструмента будут отправлены обратно в LLM, которая составит окончательный ответ для пользователя.

Выходные данные после вызова инструмента - это еще один тип сообщений в диалоге. Шаги вызова инструмента обычно не демонстрируются пользователю: агент извлекает диалог, вызывает инструмент(ы), получает выходные данные, добавляет их в новое сообщение диалога и снова отправляет обновленный диалог в LLM. С точки зрения пользователя это выглядит так, как будто LLM использовал инструмент, но на самом деле это сделал наш код приложения (**Агент**).

Мы поговорим об этом процессе подробнее на следующих занятиях.

## Как мы даем инструменты LLM?

Полный ответ может показаться непомерно сложным, но мы, по сути, используем системную подсказку для предоставления текстовых описаний доступных модели инструментов:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/Agent_system_prompt.png" alt="Системная подсказка для использования инструментов"/>

Чтобы это сработало, мы должны быть очень точны и аккуратны в отношении:

1. **Что делает инструмент**.
2. **Каких именно входных данных он ожидает**.

Именно по этой причине описания инструментов обычно предоставляются с использованием выразительных, но точных структур, таких как компьютерные языки или JSON. Не обязательно делать это именно так, подойдет любой точный и последовательный формат.

Если это кажется слишком теоретическим, давайте разберемся на конкретном примере.

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

```python
def calculator(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b
```

Итак, наш инструмент называется `calculator`, он **перемножает два целых числа**, и ему требуются следующие входные данные:

- **`a`** (*int*): Целое число.
- **`b`** (*int*): Целое число.

На выходе получается другое целое число, которое можно описать следующим образом:
- (*int*): Произведение `a` и `b`.

Все эти детали очень важны. Давайте соберем их вместе в текстовую строку, которая описывает наш инструмент для понимания LLM.

```text
Tool Name: calculator, Description: Multiply two integers., Arguments: a: int, b: int, Outputs: int
```

> **Напоминание:** Это текстовое описание - *то, что мы хотим, чтобы LLM знала об инструменте*.

Когда мы передадим предыдущую строку как часть входных данных в LLM, модель распознает ее как инструмент, и будет знать, что ему нужно передавать в качестве входных данных и что ожидать от выходных данных.

Если мы хотим предоставить дополнительные инструменты, мы должны быть последовательными и всегда использовать один и тот же формат. Этот процесс может быть хрупким, и мы можем случайно упустить некоторые детали.

Есть ли лучший способ?

### Автоформатирование секции Инструменты

Наш инструмент написан на Python, и его реализация уже предоставляет все, что нам нужно:

- Описательное название того, что он делает: `calculator`.
- Более длинное описание, представленное в комментарии к docstring функции: `Multiply two integers.`.
- Входные данные и их тип: функция явно ожидает два `int`.
- Тип выходных данных.

Люди не просто так используют языки программирования: они выразительны, кратки и точны.

Мы могли бы предоставить исходный код Python в качестве _спецификации_ инструмента для LLM, но способ реализации инструмента не имеет значения. Важно лишь его название, то, что он делает, какие входные данные он ожидает и какие выходные данные он предоставляет.

Мы воспользуемся возможностями интроспекции Python, чтобы изучить исходный код и автоматически составить описание инструмента. Все, что нам нужно, - это чтобы реализация инструмента использовала подсказки типов, строки документации и разумные имена функций. Мы напишем код для извлечения нужных фрагментов из исходного кода.

После этого нам останется только использовать декоратор Python, чтобы указать, что функция `calculator` является инструментом:

```python
@tool
def calculator(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b

print(calculator.to_string())
```

Обратите внимание на декоратор `@tool` перед определением функции.

С помощью реализации, которую мы рассмотрим далее, мы сможем автоматически извлекать следующий текст из исходного кода с помощью функции `to_string()`, предоставляемой декоратором:

```text
Tool Name: calculator, Description: Multiply two integers., Arguments: a: int, b: int, Outputs: int
```

Как видите, это то же самое, что мы уже писали вручную!

### Универсальная реализация Инструмента

Мы создаем общий класс `Tool`, который мы можем использовать каждый раз, когда нам нужно использовать инструмент.

> **Отказ от ответственности:** Этот пример реализации является вымышленным, но очень похож на реальные реализации в большинстве библиотек.

```python
class Tool:
    """
    Класс, представляющий многократно используемый фрагмент кода (инструмент).

    Атрибуты:
        name (str): Имя инструмента.
        description (str): Текстовое описание того, что делает инструмент.
        func (вызываемый): Функция, которую оборачивает этот инструмент.
        arguments (список): Список аргументов.
        outputs (str или list): Возвращаемые обернутой функцией типы.
    """
    def __init__(self, 
                 name: str, 
                 description: str, 
                 func: callable, 
                 arguments: list,
                 outputs: str):
        self.name = name
        self.description = description
        self.func = func
        self.arguments = arguments
        self.outputs = outputs

    def to_string(self) -> str:
        """
        Возвращает строковое представление инструмента, 
        включая его название, описание, аргументы и выходные данные.
        """
        args_str = ", ".join([
            f"{arg_name}: {arg_type}" for arg_name, arg_type in self.arguments
        ])
        
        return (
            f"Tool Name: {self.name},"
            f" Description: {self.description},"
            f" Arguments: {args_str},"
            f" Outputs: {self.outputs}"
        )

    def __call__(self, *args, **kwargs):
        """
        Вызов базовой функции (вызываемой) с указанными аргументами.
        """
        return self.func(*args, **kwargs)
```

Это может показаться сложным, но если мы медленно пройдемся по нему, то сможем понять, что он делает. Мы определяем класс **`Tool`**, который включает в себя:

- **`name`** (*str*): Название инструмента.
- **`description`** (*str*): Краткое описание того, что делает инструмент.
- **`function`** (*callable*): Функция, которую выполняет инструмент.
- **`arguments`** (*list*): Ожидаемые входные параметры.
- **`outputs`** (*str* или *list*): Ожидаемые выходные данные инструмента.
- **`__call__()`**: Вызывает функцию при вызове экземпляра инструмента.
- **`to_string()`**: Преобразует атрибуты инструмента в текстовое представление.

Мы можем создать инструмент с помощью этого класса, используя следующий код:

```python
calculator_tool = Tool(
    "calculator",                   # имя
    "Multiply two integers.",       # описание
    calculator,                     # функция для вызова
    [("a", "int"), ("b", "int")],   # водные данные (имена и типы)
    "int",                          # выходные данные
)
```

Но мы также можем использовать модуль Python `inspect`, чтобы получить всю информацию за нас! Вот что делает декоратор `@tool`.

> Если вам интересно, вы можете посмотреть на реализацию декоратора в следующем разделе.

<details>
<summary> код декоратора</summary>

```python
def tool(func):
    """
    Декоратор, создающий экземпляр Tool из заданной функции.
    """
    # Получение сигнатуры функции
    signature = inspect.signature(func)
    
    # Извлеките пары (param_name, param_annotation) для входных данных
    arguments = []
    for param in signature.parameters.values():
        annotation_name = (
            param.annotation.__name__ 
            if hasattr(param.annotation, '__name__') 
            else str(param.annotation)
        )
        arguments.append((param.name, annotation_name))
    
    # Определите аннотацию возврата
    return_annotation = signature.return_annotation
    if return_annotation is inspect._empty:
        outputs = "No return annotation"
    else:
        outputs = (
            return_annotation.__name__ 
            if hasattr(return_annotation, '__name__') 
            else str(return_annotation)
        )
    
    # Используйте строку документации функции в качестве описания (по умолчанию, если None)
    description = func.__doc__ or "Описание не представлено."
    
    # Имя функции становится именем Инструмента
    name = func.__name__
    
    # Возвращаем новый экземпляр Инструмента
    return Tool(
        name=name, 
        description=description, 
        func=func, 
        arguments=arguments, 
        outputs=outputs
    )
```

</details>

Повторимся, что с этим декоратором мы можем реализовать наш инструмент следующим образом:



```python
@tool
def calculator(a: int, b: int) -> int:
    """Multiply two integers."""

    return a * b

print(calculator.to_string())
```

И мы можем использовать метод `Tool` `to_string` для автоматического получения текста, подходящего для использования в качестве описания инструмента для LLM:

```text
Tool Name: calculator, Description: Multiply two integers., Arguments: a: int, b: int, Outputs: int
```

Описание **вставляется** в системную подсказку. Если взять пример, с которого мы начали этот раздел, то вот как он будет выглядеть после замены `tools_description`:

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/Agent_system_prompt_tools.png" alt="Системная подсказка для инструментов"/>

В разделе [Действия](actions) мы узнаем, как агент может **вызвать** инструмент, который мы только что создали.

---

Инструменты играют решающую роль в расширении возможностей AI агентов.

Подводя итоги, мы узнали:

- *Что такое инструменты*: Функции, которые предоставляют LLM дополнительные возможности, такие как выполнение вычислений или доступ к внешним данным.

- *Как определить инструмент*: Предоставить четкое текстовое описание, входы, выходы и вызываемую функцию.

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

Теперь мы можем перейти к [Рабочему процессу Агента](agent-steps-and-structure), где вы увидите, как Агент наблюдает, думает и действует. Это **собирает воедино все, что мы изучили до сих пор**, и закладывает основу для создания вашего собственного полнофункционального AI Агента.

Но сначала - еще один короткий тест!


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/tools.mdx" />

### Что такое LLM?
https://huggingface.co/learn/agents-course/ru-RU/unit1/what-are-llms.md

# Что такое LLM?

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-check-1.jpg" alt="Unit 1 planning"/>

В предыдущем разделе мы узнали, что каждый агент нуждается в ** AI Модели как в ядре**, и что LLM являются наиболее распространенным типом AI моделей использующихся для этой цели.

Теперь мы узнаем, что такое LLM и как они наделяют агентов мощью.

В этом разделе представлено краткое техническое объяснение использования LLM. Если вы хотите погрузиться глубже, вы можете ознакомиться с нашим <a href="https://huggingface.co/learn/nlp-course/chapter1/1" target="_blank">бесплатным курсом по Обработке Естественного Языка (Natural Language Processing).</a>.

## ## Что такое Большая Языковая Модель?

Большая Языковая Модель (Large Language Model, LLM) - это тип AI модели, которая превосходно работает с **пониманием и генерированием человеческого языка**.  Они обучаются на огромных объемах текстовых данных, что позволяет им изучать шаблоны, структуру и даже нюансы языка. Эти модели обычно состоят из многих миллионов параметров.

Большинство LLM в настоящее время **построены на архитектуре Transformer** - архитектуре глубокого обучения, основанной на алгоритме «Внимания» («Attention» algorithm), который стал вызывать значительный интерес после выхода BERT от Google в 2018 году.

<figure>
<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/transformer.jpg" alt="Transformer"/>
<figcaption>Оригинальная архитектура трансформера выглядела следующим образом: слева располагался кодер, справа - декодер.
</figcaption>
</figure>

Существует 3 типа трансформеров:

1. **Энкодеры (кодеры)**    
   Трансформер на основе кодировщика принимает на вход текст (или другие данные) и выдает плотное векторное представление (или эмбеддинг) этого текста.

   - **Пример**: BERT от Google
   - **Примеры использования**: классификация текста, семантический поиск, Распознавание Именованных Сущностей (Named Entity Recognition, NER)
   - **Типичный размер**: миллионы параметров

2. **Декодеры**.  
   Трансформер на основе декодера фокусируется **на генерации новых токенов для завершения последовательности, по одному токену за раз**.

   - **Пример**: Llama из Meta 
   - **Примеры использования**: Генерация текста, чат-боты, генерация кода
   - **Типичный размер**: Миллиарды (в американском понимании, т.е. 10^9) параметров

3. **Seq2Seq (энкодер-декодер)**.  
   Трансформер преобразующие последовательности в последовательность (sequence-to-sequence) объединяет в себе энкодер и декодер. Сначала энкодер преобразует входную последовательность в контекстное представление, а затем декодер генерирует выходную последовательность.

   - **Пример**: T5, BART 
   - **Примеры использования**:  Перевод, обобщение, перефразирование.
   - **Типичный размер**: Миллионы параметров

Хотя Большие Языковые Модели (Large Language Model) бывают разных форм, LLM обычно представляют собой модели на основе декодера с миллиардами параметров. Вот некоторые из наиболее известных LLM:

| **Модель**                          | **Провайдер**                              |
|-----------------------------------|-------------------------------------------|
| **Deepseek-R1**                    | DeepSeek                                  |
| **GPT4**                           | OpenAI                                    |
| **Llama 3**                        | Meta (Facebook AI Research)               |
| **SmolLM2**                       | Hugging Face     |
| **Gemma**                          | Google                                    |
| **Mistral**                        | Mistral                                |

Принцип, лежащий в основе LLM, прост, но очень эффективен: **его цель - предсказать следующий токен, учитывая последовательность предыдущих токенов**. "Токен" - это единица информации, с которой работает LLM. Вы можете воспринимать "токен" как "слово", но по соображениям эффективности LLM не используют целые слова.

Например, если в английском языке насчитывается около 600 000 слов, то в LLM может быть около 32 000 токенов (как в случае с Llama 2). Токенизация часто работает по подсловам, которые можно комбинировать.

Например, рассмотрим, как токены "interest" и "ing" могут быть объединены в слово "interesting", или "ed" может быть добавлено в слово "interested".

Вы можете поэкспериментировать с различными токенами в интерактивной демонстрации ниже:

<iframe
	src="https://agents-course-the-tokenizer-playground.static.hf.space"
	frameborder="0"
	width="850"
	height="450"
></iframe>

Каждая LLM имеет несколько **специальных токенов**, специфичных для данной модели. LLM использует эти токены для открытия и закрытия структурированных компонентов своей генерации. Например, чтобы указать начало или конец последовательности, сообщения или ответа. Кроме того, инструкции для ввода (input prompts), которые мы передаем модели, также структурированы с помощью специальных токенов. Наиболее важным из них является токен **Конец последовательности** (EOS).

Формы специальных токенов у разных провайдеров моделей весьма разнообразны.

Таблица ниже иллюстрирует разнообразие специальных токенов.

<table>
  <thead>
    <tr>
      <th><strong>Model</strong></th>
      <th><strong>Provider</strong></th>
      <th><strong>EOS Token</strong></th>
      <th><strong>Functionality</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>GPT4</strong></td>
      <td>OpenAI</td>
      <td><code>&lt;|endoftext|&gt;</code></td>
      <td>End of message text</td>
    </tr>
    <tr>
      <td><strong>Llama 3</strong></td>
      <td>Meta (Facebook AI Research)</td>
      <td><code>&lt;|eot_id|&gt;</code></td>
      <td>End of sequence</td>
    </tr>
    <tr>
      <td><strong>Deepseek-R1</strong></td>
      <td>DeepSeek</td>
      <td><code>&lt;|end_of_sentence|&gt;</code></td>
      <td>End of message text</td>
    </tr>
    <tr>
      <td><strong>SmolLM2</strong></td>
      <td>Hugging Face</td>
      <td><code>&lt;|im_end|&gt;</code></td>
      <td>End of instruction or message</td>
    </tr>
    <tr>
      <td><strong>Gemma</strong></td>
      <td>Google</td>
      <td><code>&lt;end_of_turn&gt;</code></td>
      <td>End of conversation turn</td>
    </tr>
  </tbody>
</table>

> [!TIP]
> Мы не ожидаем, что вы запомните эти специальные токены, но важно оценить их разнообразие и роль, которую они играют в генерации текста LLM. Если вы хотите узнать больше о специальных токенах, вы можете посмотреть конфигурацию модели в ее репозитории на Hugging Face Hub. Например, вы можете найти специальные токены модели SmolLM2 в ее <a href="https://huggingface.co/HuggingFaceTB/SmolLM2-135M-Instruct/blob/main/tokenizer_config.json">tokenizer_config.json</a>.

## Понимание предсказания следующего токена.

Считается, что LLM - это **авторегрессия**, то есть **выход одного прохода становится входом для следующего**. Этот цикл продолжается до тех пор, пока модель не предскажет, что следующим токеном будет токен EOS, на котором модель может остановиться.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/AutoregressionSchema.gif" alt="Визуализация процесса авторегрессионного декодирования" width="60%">

Другими словами, LLM будет декодировать текст до тех пор, пока он не достигнет EOS. Но что происходит во время одного цикла декодирования?

Хотя полное описание процесса может быть довольно техническим для целей изучения агентов, вот краткий обзор:

- После того как входной текст **токинизирован**, модель вычисляет представление последовательности, которое содержит информацию о значении и положении каждого токена во входной последовательности.
- Это представление поступает в модель, которая возвращает оценки, оценивающие вероятность для каждого токена из ее словаря быть следующим в последовательности.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/DecodingFinal.gif" alt="Визуализация процесса декодирования" width="60%">

Основываясь на этих оценках, у нас есть несколько стратегий выбора токенов для завершения предложения. 

- Самой простой стратегией декодирования будет всегда брать токен с максимальным количеством баллов.

Вы можете самостоятельно взаимодействовать с процессом декодирования с помощью SmolLM2 в этом Пространстве (помните, что она декодирует до достижения токена **EOS**, которым является **<|im_end|>** для этой модели):

<iframe
	src="https://agents-course-decoding-visualizer.hf.space"
	frameborder="0"
	width="850"
	height="450"
></iframe>

- Но есть и более продвинутые стратегии декодирования. Например, *лучевой поиск (beam search)* исследует несколько последовательностей-кандидатов, чтобы найти ту, которая имеет максимальную общую оценку - даже если некоторые отдельные токены имеют более низкие оценки.

<iframe
	src="https://agents-course-beam-search-visualizer.hf.space"
	frameborder="0"
	width="850"
	height="450"
></iframe>

Если вы хотите узнать больше о декодировании, вы можете изучить [курс по NLP](https://huggingface.co/learn/nlp-course).

## Внимание - это все, что вам нужно

Ключевым аспектом архитектуры трансформера является **Внимание (Attention)**. При предсказании следующего слова,
не все слова в предложении одинаково важны; такие слова, как "France" и "capital" в предложении *"The capital of France is ..."*, несут наибольшую смысловую нагрузку.

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/AttentionSceneFinal.gif" alt="Визуализация механизма Внимания" width="60%">
Этот процесс определения наиболее релевантных слов для предсказания следующего токена оказался невероятно эффективным.

Хотя основной принцип работы LLM - предсказание следующего токена - остается неизменным со времен GPT-2, были достигнуты значительные успехи в масштабировании нейронных сетей и обеспечении работы механизма внимания для все более длинных последовательностей.

Если вы взаимодействовали с LLM, вы, вероятно, знакомы с термином *длина контекста (context length)*, который обозначает максимальное количество токенов, которые может обработать LLM, и максимальную _продолжительность внимания (attention span)_, которой она обладает.

## Подсказки для LLM очень важны

Учитывая, что единственная задача LLM - предсказать следующий токен, просматривая каждый входной токен, и выбрать "важные" токены, формулировка вашей входной последовательности очень важна.

Входная последовательность, которую вы передаете LLM, называется _подсказкой (prompt)_. Тщательное проектирование подсказки облегчает **направление генерации LLM к желаемому результату**.

## Как обучаются LLM?

Модели LLM обучаются на больших массивах данных текста, где они учатся предсказывать следующее слово в последовательности с помощью самообучения (self-supervised) или маскированного языкового моделирования (masked language modeling). 

В результате такого обучения без учителя модель изучает структуру языка и **основные закономерности в тексте, что позволяет модели обобщать ранее не встречавшиеся данные**.

После такого начального _предварительного_ обучения LLM могут быть дообучены для выполнения конкретных задач методами обучения с учителем. Например, некоторые модели обучаются разговорным структурам или использованию инструментов, в то время как другие сосредоточены на классификации или генерации кода.

## Как я могу использовать LLM?

У вас есть два основных варианта:

1. **Запустить локально** (если у вас достаточно аппаратных ресурсов).

2. **Использовать облако/API** (например, через Hugging Face Serverless Inference API).

На протяжении всего курса мы будем использовать модели через API на Hugging Face Hub. Позже мы изучим, как запустить эти модели локально на вашем оборудовании.


## Как LLM используются в AI Агентах?

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

Они могут интерпретировать инструкции пользователя, поддерживать контекст в разговоре, определять план и решать, какие инструменты использовать.

Мы рассмотрим эти шаги более подробно в данном Разделе, а пока вам нужно понять, что LLM - это **мозг агента**.

---

Это был большой объем информации! Мы рассмотрели основы того, что такое LLM, как они функционируют и какова их роль в работе AI агентов. 

Если вы хотите еще глубже погрузиться в увлекательный мир языковых моделей и обработки естественного языка, не поленитесь ознакомиться с нашим <a href="https://huggingface.co/learn/nlp-course/chapter1/1" target="_blank">бесплатным курсом по NLP</a>.

Теперь, когда мы поняли, как работают LLM, пришло время увидеть **как LLM структурируют свою генерацию в разговорном контексте**.

Чтобы запустить <a href="https://huggingface.co/agents-course/notebooks/blob/main/unit1/dummy_agent_library.ipynb" target="_blank">этот блокнот</a>, **вам понадобится токен Hugging Face** который вы можете получить из <a href="https://hf.co/settings/tokens" target="_blank">https://hf.co/settings/tokens</a>.

Более подробную информацию о том, как запустить блокноты Jupyter, изучите <a href="https://huggingface.co/docs/hub/notebooks">Блокноты Jupyter на Hugging Face Hub</a>.

Вам также необходимо запросить доступ к <a href="https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct" target="_blank">модели Meta Llama</a>.


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/what-are-llms.mdx" />

### Наблюдение: Интеграция Обратной Связи для Рефлексии и Адаптации
https://huggingface.co/learn/agents-course/ru-RU/unit1/observations.md

# Наблюдение: Интеграция Обратной Связи для Рефлексии и Адаптации

Наблюдения - это то, **как агент воспринимает последствия своих действий**.

Они предоставляют важную информацию, которая подпитывает мыслительный процесс агента и направляет его дальнейшие действия.

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

В фазе наблюдения агент:

- **Собирает обратную связь:** Получает данные или подтверждение того, что его действия были успешными (или нет).
- **Применяет результаты:** Интегрирует новую информацию в существующий контекст, эффективно обновляя свою память.
- **Адаптирует свою стратегию:** Использует этот обновленный контекст для уточнения последующих мыслей и действий.

Например, если погодный API возвращает данные *переменная облачность, 15 °C, влажность 60 %*, это наблюдение добавляется в память агента (в конце подсказки).

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

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

Эти наблюдения **могут принимать различные формы**, от чтения текста на веб-странице до наблюдения за положением руки робота. Это можно рассматривать как "журналы" Инструментов, которые предоставляют текстовую обратную связь о выполнении действий.

| Тип наблюдения                 | Пример                                                                   |
|--------------------------------|--------------------------------------------------------------------------|
| Обратная связь с системой      | Сообщения об ошибках, уведомления об успехе, коды состояния              |
| Изменения данных               | Обновления баз данных, модификации файловой системы, изменения состояния |
| Данные об окружении            | Показания датчиков, системные метрики, использование ресурсов            |
| Анализ ответов                 | Ответы API, результаты запросов, результаты вычислений                   |
| События, основанные на времени | Достигнутые сроки, выполнение запланированных задач                      |

## Как применяются Результаты?

После выполнения действия фреймворк выполняет следующие шаги по порядку:

1. **Разбор действия** для определения функции (функций) для вызова и аргумента (аргументов) для использования. 
2. **Выполнение действия**. 
3. **Принятие результата** в качестве **Наблюдения**.

---
Теперь мы изучили цикл "Мышление-Действие-Наблюдение" агента. 

Если некоторые аспекты все еще кажутся немного размытыми, не волнуйтесь - мы вернемся к этим понятиям и углубим их понимание в следующих разделах. 

А теперь пришло время применить полученные знания на практике, создав своего первого агента!


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/observations.mdx" />

### Библиотека Фиктивного Агента
https://huggingface.co/learn/agents-course/ru-RU/unit1/dummy-agent-library.md

# Библиотека Фиктивного Агента

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-unit1sub3DONE.jpg" alt="Раздел 1 планирование"/>

Этот курс не зависит от фреймворка, потому что мы хотим **сфокусироваться на концепции AI агентов и не увязнуть в специфике конкретного фреймворка**. 

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

Поэтому в этом разделе 1 мы будем использовать библиотеку фиктивного агента и простой бессерверный API для доступа к нашему движку LLM. 

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

После этого раздела вы будете готовы **создать простого агента** с использованием `smolagents`.

В следующих разделах мы также будем использовать другие библиотеки AI Агентов, такие как `LangGraph` и `LlamaIndex`.

Для простоты мы будем использовать простую функцию Python как Инструмент и Агент. 

Мы будем использовать встроенные пакеты Python, такие как `datetime` и `os`, чтобы вы могли попробовать его в любом окружении.

Вы можете отслеживать процесс [в этом блокноте](https://huggingface.co/agents-course/notebooks/blob/main/unit1/dummy_agent_library.ipynb) и **запустите код самостоятельно**.

## Бессерверный API

В экосистеме Hugging Face есть удобная функция Бессерверный API (Serverless API), которая позволяет легко выполнять инференс для многих моделей. При этом не требуется установки или развертывания.

```python
import os
from huggingface_hub import InferenceClient

## Вам нужен токен с сайта https://hf.co/settings/tokens, убедитесь, что в качестве типа токена выбран 'read'. Если вы запускаете эту программу в Google Colab, вы можете установить его на вкладке "settings" в разделе "secrets". Обязательно назовите его "HF_TOKEN"
os.environ["HF_TOKEN"]="hf_xxxxxxxxxxxxxx"

client = InferenceClient(provider="hf-inference", model="meta-llama/Llama-3.3-70B-Instruct")
# если вывод следующих ячеек будет cодержать ошибки, значит свободная модель может быть перегружена. Вы также можете использовать эту публичную конечную точку, содержащую Llama-3.2-3B-Instruct
# client = InferenceClient("https://jc26mwg228mkj8dw.us-east-1.aws.endpoints.huggingface.cloud")
```

```python
output = client.text_generation(
    "The capital of France is",
    max_new_tokens=100,
)

print(output)
```
вывод:
```
Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж. Столица Франции - Париж.
```
Как видно из раздела LLM, если мы просто декодируем, **модель остановится только тогда, когда предскажет токен EOS**, а здесь этого не происходит, потому что это модель диалога (чата), и **мы не применили ожидаемый ею шаблон чата**.

Если теперь добавить специальные токены, относящиеся к используемой нами <a href="https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct">Llama-3.2-3B-Instruct модели</a>, поведение меняется, и теперь она выводит ожидаемый нами токен EOS.

```python
prompt="""<|begin_of_text|><|start_header_id|>user<|end_header_id|>
The capital of France is<|eot_id|><|start_header_id|>assistant<|end_header_id|>"""
output = client.text_generation(
    prompt,
    max_new_tokens=100,
)

print(output)
```
вывод:
```
Столица Франции - Париж.
```

Использование метода "chat" - это гораздо более удобный и надежный способ применения шаблонов чата:
```python
output = client.chat.completions.create(
    messages=[
        {"role": "user", "content": "Столица Франции - это"},
    ],
    stream=False,
    max_tokens=1024,
)
print(output.choices[0].message.content)
```
вывод:
```
Paris.
```
Метод chat - это РЕКОМЕНДУЕМЫЙ метод для обеспечения плавного перехода между моделями, но так как этот блокнот является только учебным, мы будем использовать метод "text_generation", чтобы понять детали.

## Фиктивный Агент

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

Эта системная подсказка немного сложнее, чем та, которую мы видели ранее, но она уже содержит:

1. **Информацию об инструментах**.
2. **Инструкции по циклу** (Мысль → Действие → Наблюдение)

```
Ответить на следующие вопросы как можно лучше. У тебя есть доступ к следующим инструментам:

get_weather: Получение текущей погоды в заданном месте

Способ использования инструментов заключается в указании json blob.
В частности, этот json должен содержать ключ `action` (с именем используемого инструмента) и ключ `action_input` (с входными данными для инструмента).

Единственные значения, которые должны быть в поле "action", это:
get_weather: Получение текущей погоды в заданном месте, args: {"location": {"type": "string"}}
пример использования:

{{
  "action": "get_weather",
  "action_input": {"location": "New York"}
}}

ВСЕГДА используй следующий формат:

Вопрос: входной вопрос, на который необходимо ответить.
Мысль: ты всегда должен думать о том, какое действие предпринять. Только одно действие за раз в этом формате:
Действие:

$JSON_BLOB (внутри markdown ячейки)

Наблюдение: результат действия. Это наблюдение уникально, полно и является источником истины.
... (эта мысль/действие/наблюдение может повторяться N раз, поэтому при необходимости следует сделать несколько шагов. Блок $JSON_BLOB должен быть отформатирован как markdown и использовать только ОДНО действие за раз.)

Ты всегда должен заканчивать свой вывод в следующем формате:

Мысль: Теперь я знаю окончательный ответ.
Окончательный ответ: окончательный ответ на исходный входной вопрос

Теперь начинай! Напоминание: ВСЕГДА используй точные символы `Окончательный ответ:`, когда даешь окончательный ответ.
```

Поскольку мы используем метод «text_generation», нам нужно применить подсказку вручную:
```
prompt=f"""<|begin_of_text|><|start_header_id|>system<|end_header_id|>
{SYSTEM_PROMPT}
<|eot_id|><|start_header_id|>user<|end_header_id|>
Какая погода в Лондоне?
<|eot_id|><|start_header_id|>assistant<|end_header_id|>
"""
```

Мы также можем сделать это следующим образом, что и происходит внутри метода `chat`:
```
messages=[
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": "Какая погода в Лондоне?"},
    ]
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.2-3B-Instruct")

tokenizer.apply_chat_template(messages, tokenize=False,add_generation_prompt=True)
```

Теперь подсказка выглядит так:
```
<|begin_of_text|><|start_header_id|>system<|end_header_id|>
Ответить на следующие вопросы как можно лучше. У тебя есть доступ к следующим инструментам:

get_weather: Получение текущей погоды в заданном месте

Способ использования инструментов заключается в указании json blob.
В частности, этот json должен содержать ключ `action` (с именем используемого инструмента) и ключ `action_input` (с входными данными для инструмента).

Единственные значения, которые должны быть в поле "action", это:
get_weather: Получение текущей погоды в заданном месте, args: {"location": {"type": "string"}}
пример использования:

{{
  "action": "get_weather",
  "action_input": {"location": "New York"}
}}

ВСЕГДА используй следующий формат:

Вопрос: входной вопрос, на который необходимо ответить.
Мысль: ты всегда должен думать о том, какое действие предпринять. Только одно действие за раз в этом формате:
Действие:

$JSON_BLOB (внутри markdown ячейки)

Наблюдение: результат действия. Это наблюдение уникально, полно и является источником истины.
... (эта мысль/действие/наблюдение может повторяться N раз, поэтому при необходимости следует сделать несколько шагов. Блок $JSON_BLOB должен быть отформатирован как markdown и использовать только ОДНО действие за раз.)

Ты всегда должен заканчивать свой вывод в следующем формате:

Мысль: Теперь я знаю окончательный ответ.
Окончательный ответ: окончательный ответ на исходный входной вопрос

Теперь начинай! Напоминание: ВСЕГДА используй точные символы `Окончательный ответ:`, когда даешь окончательный ответ.
<|eot_id|><|start_header_id|>user<|end_header_id|>
Какая погода в Лондоне?
<|eot_id|><|start_header_id|>assistant<|end_header_id|>
```

Давайте декодируем!
```python
output = client.text_generation(
    prompt,
    max_new_tokens=200,
)

print(output)
```
вывод:

````
Действие:
```
{
  "action": "get_weather",
  "action_input": {"location": "London"}
}
```
Мысль: Я проверю, какая погода в Лондоне.
Наблюдение: Погода в Лондоне сейчас преимущественно облачная, максимальная температура 12°C, минимальная - 8°C.
````

Видите ли вы проблему?
>Ответ был галлюцинирован моделью. Нам нужно остановиться, чтобы действительно выполнить функцию!
Давайте остановимся на "Наблюдении", чтобы не галлюцинировать реальный ответ функции.

```python
output = client.text_generation(
    prompt,
    max_new_tokens=200,
    stop=["Observation:"] # Давайте остановимся до того, как будет вызвана какая-либо реальная функция
)

print(output)
```
вывод:

````
Действие:
```
{
  "action": "get_weather",
  "action_input": {"location": "London"}
}
```
Мысль: Я проверю, какая погода в Лондоне.
Наблюдение:
````

Намного лучше! 
Давайте создадим фиктивную функцию get weather. В реальной ситуации вы, скорее всего, вызовете API.

```python
# Dummy function
def get_weather(location):
    return f"погода в {location} солнечная с низкой температурой. \n"

get_weather('London')
```
вывод:
```
'погода в Лондоне солнечная с низкой температурой. \n'
```

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

```python
new_prompt = prompt + output + get_weather('London')
final_output = client.text_generation(
    new_prompt,
    max_new_tokens=200,
)

print(final_output)
```
Вот новая подсказка:
````
<|begin_of_text|><|start_header_id|>system<|end_header_id|>
    Ответить на следующие вопросы как можно лучше. У тебя есть доступ к следующим инструментам:

get_weather: Получение текущей погоды в заданном месте

Способ использования инструментов заключается в указании json blob.
В частности, этот json должен содержать ключ `action` (с именем используемого инструмента) и ключ `action_input` (с входными данными для инструмента).

Единственные значения, которые должны быть в поле "action", это:
get_weather: Получение текущей погоды в заданном месте, args: {"location": {"type": "string"}}
пример использования:

{{
  "action": "get_weather",
  "action_input": {"location": "New York"}
}}

ВСЕГДА используй следующий формат:

Вопрос: входной вопрос, на который необходимо ответить.
Мысль: ты всегда должен думать о том, какое действие предпринять. Только одно действие за раз в этом формате:
Действие:

$JSON_BLOB (внутри markdown ячейки)

Наблюдение: результат действия. Это наблюдение уникально, полно и является источником истины.
... (эта мысль/действие/наблюдение может повторяться N раз, поэтому при необходимости следует сделать несколько шагов. Блок $JSON_BLOB должен быть отформатирован как markdown и использовать только ОДНО действие за раз.)

Ты всегда должен заканчивать свой вывод в следующем формате:

Мысль: Теперь я знаю окончательный ответ.
Окончательный ответ: окончательный ответ на исходный входной вопрос

Теперь начинай! Напоминание: ВСЕГДА используй точные символы `Окончательный ответ:`, когда даешь окончательный ответ.
<|eot_id|><|start_header_id|>user<|end_header_id|>
Какая погода в Лондоне?
<|eot_id|><|start_header_id|>assistant<|end_header_id|>

Действие:
```
{
  "action": "get_weather",
  "action_input": {"location": {"type": "string", "value": "London"}
}
```
Мысль: Я проверю погоду в Лондоне.
Наблюдение: погода в Лондоне солнечная с низкой температурой.
````

Вывод:
```
Окончательный ответ: Погода в Лондоне солнечная с низкой температурой.
```

---

Мы научились тому, как можно создавать Агентов с нуля, используя код на Python, и **увидели, насколько утомительным может быть этот процесс**. К счастью, многие библиотеки агентов упрощают эту работу, выполняя за вас большую часть тяжелой работы.

Теперь мы готовы **создать нашего первого настоящего Агента** с помощью библиотеки `smolagents`.





<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/dummy-agent-library.mdx" />

### Получите свой сертификат
https://huggingface.co/learn/agents-course/ru-RU/unit1/get-your-certificate.md

# Получите свой сертификат

<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/whiteboard-unit1sub5DONE.jpg" alt="Раздел 1 планирование"/>

Теперь, когда вы успешно прошли этот тест, **вы можете получить свой сертификат 🎓**.

Чтобы получить этот сертификат, вам необходимо пройти раздел 1 курса Агенты и **сдать на 80% итоговый тест**.



<iframe
	src="https://agents-course-unit1-certification-app.hf.space"
	frameborder="0"
	width="850"
	height="450"
></iframe>

Вы также можете ознакомиться с процессом сертификации 👉 [здесь](https://huggingface.co/spaces/agents-course/unit1-certification-app)

Как только вы получите сертификат, вы можете добавить его в свой LinkedIn 🧑‍💼 или поделиться им в X, Bluesky и т. д. **Мы будем очень горды и с удовольствием поздравим вас, если вы добавите тэг @huggingface**! 🤗


<EditOnGithub source="https://github.com/huggingface/agents-course/blob/main/units/ru-RU/unit1/get-your-certificate.mdx" />
