# Агенты

Hugging Face предоставляет инструменты и протоколы, которые напрямую подключают ИИ-агентов к Hub. Независимо от того, общаетесь ли вы с Claude, работаете с Codex или разрабатываете собственных агентов, вы можете получить доступ к моделям, наборам данных, Spaces и инструментам сообщества. На этой странице описано, как подключить ваших [чат-агентов](#chat-with-hugging-face) и [агентов для написания кода](#coding-agents) к Hub.

| Страница | Описание |
| ---- | ----------- |
| [CLI](./agents-cli) | Дайте вашему агенту CLI `hf` со встроенным Skill |
| [Сервер MCP](./agents-mcp) | Подключите любой совместимый с MCP клиент к Hub |
| [Навыки](./agents-skills) | Руководство по задачам для рабочих процессов ИИ/МО |
| [SDK](./agents-sdk) | Создавайте агентов программно с помощью Python или JavaScript |
| [Локальные агенты](./agents-local) | Запуск полностью локальных агентов с помощью llama.cpp и Pi |
| [Слежки агентов](./agent-traces) | Просмотр сессий Claude Code, Codex и Pi на Hub |

## Чат с Hugging Face

Подключите вашего ИИ-ассистента напрямую к Hugging Face Hub с помощью Model Context Protocol (MCP). После подключения вы сможете искать модели, просматривать наборы данных, генерировать изображения и использовать инструменты сообщества — всё это прямо из интерфейса чата.

### Поддерживаемые ассистенты

Сервер HF MCP работает с любым клиентом, совместимым с MCP:
- **ChatGPT** (через плагины)
- **Claude Desktop**
- **Пользовательские MCP-клиенты**

### Настройка

#### 1. Откройте настройки MCP

![MCP Settings Example](https://huggingface.co/huggingface/documentation-images/resolve/main/agents-docs/mcp-settings.png)

Перейдите на [huggingface.co/settings/mcp](https://huggingface.co/settings/mcp), будучи вошедшим в систему.

#### 2. Выберите ваш клиент

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

#### 3. Настройка и перезапуск

Скопируйте фрагмент конфигурации в настройки MCP вашего клиента, сохраните изменения и перезапустите клиент.

> [!TIP]
> Страница настроек генерирует точную конфигурацию, которую ожидает ваш клиент. Используйте её, а не создавайте конфигурацию вручную.

### Что вы можете сделать

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

| Задача | Пример запроса |
| ---- | -------------- |
| Поиск моделей | Найдите квантованные версии Qwen 3 на Hugging Face |
| Ознакомьтесь с наборами данных | Показать наборы данных о временных рядах погоды |
| Поиск Spaces | Найдите Space, способный транскрибировать аудиофайлы |
| Генерация изображений | Создайте изображение 1024x1024 с котом в стиле Гибли |
| Поиск статей | «Найдите недавние статьи о моделях «зрение-язык»» |

Ваш ассистент вызывает MCP-инструменты, предоставляемые сервером Hugging Face, и возвращает результаты с метаданными, ссылками и контекстом.

### Добавить инструменты сообщества

Расширьте вашу конфигурацию с помощью совместимых с MCP Gradio Spaces:

1. Просмотр [Spaces с поддержкой MCP](https://huggingface.co/spaces?filter=mcp-server)
2. Добавьте их в ваши [настройки MCP](https://huggingface.co/settings/mcp)
3. Перезапустите клиент, чтобы применить новые инструменты

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

### Подробнее

- [Руководство по серверу MCP](./agents-mcp) — подробная настройка и конфигурация
- [Настройки HF MCP](https://huggingface.co/settings/mcp) — настройте ваш клиент
- [Совместимые с MCP Spaces](https://huggingface.co/spaces?filter=mcp-server) — инструменты сообщества

## Агенты для программирования

Интегрируйте Hugging Face в свой рабочий процесс программирования с помощью MCP Server и Skills. Получайте доступ к моделям, наборам данных и инструментам машинного обучения прямо из вашей IDE или кодинг-агента. Например, мы рассматриваем следующие кодинг-агенты и другие с использованием MCP и/или Skills:

| Агент для написания кода | Метод интеграции |
| ------------ | ------------------ |
| [Claude Code](https://code.claude.com/docs) | MCP Server + Skills |
| [OpenAI Codex](https://openai.com/codex/) | MCP Server + Skills |
| [Open Code](https://opencode.ai/) | MCP Server + Skills |
| [Cursor](https://www.cursor.com/) | MCP Server + Skills |
| [VS Code](https://code.visualstudio.com/) | MCP-сервер |
| [Gemini CLI](https://geminicli.com/) | MCP-сервер |
| [Zed](https://zed.dev/) | MCP-сервер |

### Быстрая настройка

#### MCP-сервер

MCP Server предоставляет вашему кодинг-агенту доступ к поиску по Hub, Spaces и инструментам сообщества.

**Cursor / VS Code / Zed:**

1. Перейдите на [huggingface.co/settings/mcp](https://huggingface.co/settings/mcp)
2. Выберите вашу IDE из списка
3. Скопируйте фрагмент конфигурации
4. Добавьте его в настройки MCP вашей IDE
5. Перезапустите IDE

**Код Claude:**

```bash
claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"
```

#### Навыки

Skills предоставляют специализированные инструкции для рабочих процессов в области ИИ/ML. Они могут использоваться совместно с MCP или автономно.

```bash
# start claude 
claude

# install the skills marketplace plugin
/plugin marketplace add huggingface/skills
```

Затем, чтобы установить спецификацию Skill:
```bash
/plugin install hf-cli@huggingface-skills
```

Список доступных навыков и примеры их использования приведены в [Руководстве по навыкам](./agents-skills).

### Что вы можете сделать

После настройки ваш агент для написания кода может:

| Возможность | Пример |
| ---------- | ------- |
| Поиск в Hub | Найдите модель генерации кода с числом параметров менее 7 млрд |
| Генерация изображений | Создайте схему архитектуры трансформера |
| Ознакомьтесь с наборами данных | Какие наборы данных доступны для анализа тональности? |
| Запуск Spaces | Используйте Whisper Space для транскрипции этого аудиофайла |
| Получить документацию | Как дообучить модель с помощью transformers? |

### Настройка окружения

#### Аутентификация

Установите токен Hugging Face в качестве переменной окружения:

```bash
export HF_TOKEN="hf_..."
```

Или выполните аутентификацию через [CLI](./agents-cli):

```bash
hf auth login
```

#### Добавление инструментов сообщества

Расширьте вашу конфигурацию с помощью совместимых с MCP Gradio Spaces:

1. Просмотр [Spaces с поддержкой MCP](https://huggingface.co/spaces?filter=mcp-server)
2. Добавьте их в ваши [настройки MCP](https://huggingface.co/settings/mcp)
3. Перезапустите IDE

### Пример рабочего процесса

```text
You: Find a text classification model that works well on short texts

Agent: [Searches Hugging Face Hub]
       Found several options:
       - distilbert-base-uncased-finetuned-sst-2-english (sentiment)
       - facebook/bart-large-mnli (zero-shot)
       ...

You: Show me how to use the first one

Agent: [Fetches documentation]
       Here's how to use it with transformers:
       
       from transformers import pipeline
       classifier = pipeline("sentiment-analysis", 
                            model="distilbert-base-uncased-finetuned-sst-2-english")
       result = classifier("I love this product!")
```

## Зарегистрируйте ваш агентный каркас

Hugging Face поддерживает публичный реестр агентских обвязок (agent harnesses), то есть кодинг-агентов и инструментов, взаимодействующих с Hub (Claude Code, Codex, Cursor и другие). Когда `huggingface_hub` обнаруживает, что выполняется внутри зарегистрированной обвязки, он сообщает об этом через user agent в запросах к Hub. Регистрация вашей обвязки означает, что эта активность будет приписываться вашему инструменту по имени, а вашему проекту будет присвоен удобный отображаемый ярлык, ссылки на документацию и репозиторий, а также место в публичном [наборе данных об использовании агентов](https://huggingface.co/datasets/huggingface/agent-usage) — незарегистрированные инструменты учитываются только в их общей доле `unknown`.

Чтобы зарегистрировать harness, создайте Pull Request с добавлением записи в [`agent-harnesses.ts`](https://github.com/huggingface/huggingface.js/blob/main/packages/tasks/src/agent-harnesses.ts) в пакете `@huggingface/tasks`:

- Идентификатор harness (ключ записи) должен быть в нижнем регистре и разделён дефисами (пример: `"claude-code"`).
- Установите `prettyLabel` с удобным для пользователя написанием (пример: `Claude Code`).
- (необязательно) задайте `repoUrl` со ссылкой на исходный код harness (обычно это репозиторий GitHub).
- (необязательно) задайте `docsUrl` со ссылкой на документацию или сайт harness.
- (необязательно) задайте `description` с кратким однострочным описанием harness.
- определяет, как ваш harness обнаруживается из окружения:
  - Если ваш harness устанавливает одну из стандартных переменных окружения (`AI_AGENT` или `AGENT`), её значение используется непосредственно в качестве идентификатора, и дополнительная конфигурация не требуется.
  - В противном случае задайте `envVars` для сопоставления имён переменных окружения с шаблонами значений. Используйте `"*"` для совпадения с любым непустым значением, точную строку для точного совпадения или `"<prefix>*"` для совпадения по префиксу.

И всё! После слияния PR трафик `huggingface_hub` (включая CLI `hf`) от вашего агентского harness будет приписываться к нему по имени, и он появится в [наборе данных об использовании агентов](https://huggingface.co/datasets/huggingface/agent-usage) начиная со следующего ежемесячного обновления.

## Дальнейшие шаги

- [CLI](./agents-cli) — интерфейс командной строки для операций с Hub
- [Сервер MCP](./agents-mcp) — Подключите любого совместимого с MCP ИИ-ассистента к Hub
- [Навыки](./agents-skills) — готовые возможности для агентов по написанию кода
- [SDK](./agents-sdk) — библиотеки Python и JavaScript для создания агентов