# Spaces в качестве инструментов агентов

Каждое Gradio Space предоставляет текстовый файл `agents.md`, к которому кодинг-агенты (Claude Code, Codex, OpenCode, Pi и др.) могут обращаться напрямую. Найти нужный Space можно через семантический поиск на [huggingface.co/spaces](https://huggingface.co/spaces) (например, по запросу «audio transcription»), при необходимости сначала протестировать его в интерфейсе, а затем указать вашему агенту путь к его `agents.md`. Ответ содержит всё необходимое для однократного вызова Space: URL схемы, шаблоны вызова и опроса, инструкции по загрузке файлов и подсказку по аутентификации.

Это становится ещё мощнее при **сочетании Spaces**. Агент может превратить промпт в 3D-ассет, вызвав [`black-forest-labs/flux-klein-9b-kv`](https://huggingface.co/spaces/black-forest-labs/flux-klein-9b-kv) для генерации изображения, а затем передав полученное изображение в [`microsoft/TRELLIS.2`](https://huggingface.co/spaces/microsoft/TRELLIS.2) для создания 3D-модели. Никаких клиентских библиотек, никаких жёстко закодированных интеграций.

Для начала достаточно установить переменную окружения [HF_TOKEN](https://huggingface.co/settings/tokens).

## Из интерфейса

На каждой совместимой странице Space в шапке есть кнопка **Agents**. Нажмите на неё, чтобы скопировать команду `curl` для файла `agents.md` этого Space, а затем вставьте её в вашего агента.

## Конечная точка agents.md

```
https://huggingface.co/spaces/<namespace>/<repo>/agents.md
```

Пример:

```bash
curl https://huggingface.co/spaces/microsoft/TRELLIS.2/agents.md
```

Возвращает:

```
To use this application (microsoft/TRELLIS.2: Create 3D model from a single image):
API schema: GET https://microsoft-trellis-2.hf.space/gradio_api/info
Call endpoint: POST https://microsoft-trellis-2.hf.space/gradio_api/call/v2/{endpoint} {"param_name": value, ...}
Poll result: GET https://microsoft-trellis-2.hf.space/gradio_api/call/{endpoint}/{event_id}
File inputs: POST https://microsoft-trellis-2.hf.space/gradio_api/upload -F "files=@file.ext", use as: {"path": "<returned-path>", "meta": {"_type": "gradio.FileData"}, "orig_name": "file.ext"}
Auth: Bearer $HF_TOKEN (https://huggingface.co/settings/tokens)
```

## Файловые входные данные

Если конечная точка принимает файл (изображение, аудио, видео и т. д.), сначала загрузите его и укажите возвращённый путь в вашем вызове. Загрузите файл в `/gradio_api/upload` и повторно используйте возвращённый путь:

```bash
# 1. Upload the file
curl -H "Authorization: Bearer $HF_TOKEN" \
  https://microsoft-trellis-2.hf.space/gradio_api/upload \
  -F "files=@chair.png"
# → ["/tmp/gradio/.../chair.png"]

# 2. Reference the returned path as a FileData object in your call
curl -H "Authorization: Bearer $HF_TOKEN" \
  https://microsoft-trellis-2.hf.space/gradio_api/call/v2/predict \
  -d '{"image": {"path": "/tmp/gradio/.../chair.png", "meta": {"_type": "gradio.FileData"}, "orig_name": "chair.png"}}'
```

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

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

Большинство популярных Spaces работают на [ZeroGPU](./spaces-zerogpu), который использует ежедневную квоту вызывающего агента. Агенты всегда должны передавать `$HF_TOKEN`, чтобы вызовы тарифицировались по вашему аккаунту, а не по анонимному пулу с ограничением скорости. Тот же токен также требуется для частных Spaces. Создайте его на [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) (строка аутентификации в `agents.md` ведёт прямо на эту страницу).

```bash
curl -H "Authorization: Bearer $HF_TOKEN" \
  https://microsoft-trellis-2.hf.space/gradio_api/call/v2/predict \
  -d '{"image": {"path": "https://example.com/chair.png"}}'
```

## Как агенты будут использовать это

1. Агент выполняет `curl` для `/agents.md` Space.
2. Он запрашивает `/gradio_api/info`, чтобы узнать имена конечных точек и входные данные.
3. Для файловых входных данных он отправляет файл методом POST на `/gradio_api/upload` и сохраняет возвращённый путь.
4. Оно отправляет POST-запрос на `/gradio_api/call/v2/<endpoint>`, затем выполняет GET-запрос к URL опроса для получения результата потоком.