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

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

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

Для начала достаточно установить переменную окружения HF_TOKEN.

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

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

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

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

Пример:

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 и повторно используйте возвращённый путь:

# 1. Upload the file
curl -H "Authorization: Bearer $HF_TOKEN" \
  https://huggingface.co/proxy/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://huggingface.co/proxy/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, который использует ежедневную квоту вызывающего агента. Агенты всегда должны передавать $HF_TOKEN, чтобы вызовы тарифицировались по вашему аккаунту, а не по анонимному пулу с ограничением скорости. Тот же токен также требуется для частных Spaces. Создайте его на huggingface.co/settings/tokens (строка аутентификации в agents.md ведёт прямо на эту страницу).

curl -H "Authorization: Bearer $HF_TOKEN" \
  https://huggingface.co/proxy/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 опроса для получения результата потоком.