Spaces como Ferramentas de Agentes

Todo Gradio Space expõe um agents.md em texto puro que agentes de código (Claude Code, Codex, OpenCode, Pi, etc.) podem chamar diretamente. Encontre um por meio de busca semântica em huggingface.co/spaces (por exemplo, “audio transcription”), se deseje, teste-o primeiro na interface e, em seguida, aponte seu agente para o agents.md correspondente. A resposta fornece tudo o que é necessário para chamar o Space de uma só vez: URL do esquema, modelos de chamada e consulta, instruções de upload de arquivo e uma dica de autenticação.

Isso fica ainda mais poderoso ao encadear Spaces. Um agente pode transformar um prompt em um ativo 3D chamando black-forest-labs/flux-klein-9b-kv para gerar uma imagem e, em seguida, passando a imagem gerada para microsoft/TRELLIS.2 para o modelo 3D. Sem biblioteca de cliente, sem integração codificada.

Tudo o que você precisa é de um HF_TOKEN definido no seu ambiente para começar.

A partir da interface

Toda página de Space compatível tem um botão Agents no cabeçalho. Clique nele para copiar o comando curl do agents.md daquele Space e, em seguida, cole-o no seu agente.

O endpoint agents.md

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

Exemplo:

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

Retorna:

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)

Entradas de arquivo

Quando um endpoint recebe um arquivo (imagem, áudio, vídeo, etc.), faça o upload primeiro e referencie o caminho retornado na sua chamada. Faça o upload para /gradio_api/upload e reutilize o caminho que ele retorna:

# 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"}}'

Inputs que aceitam uma URL pública (em vez de um arquivo enviado) podem ser passados diretamente, sem a etapa de upload.

Autenticação e ZeroGPU

A maioria dos Spaces populares roda em ZeroGPU, que utiliza a cota diária do chamador. Os agentes devem sempre passar um $HF_TOKEN para que as chamadas sejam cobradas na sua conta, em vez de um pool anônimo com limitação de taxa. O mesmo token também é obrigatório para Spaces privados. Crie um em huggingface.co/settings/tokens (a linha de autenticação do agents.md faz link diretamente para essa página).

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"}}'

Como os agentes usarão isso

1. O agente faz um curl em /agents.md para o Space.
2. Ele busca /gradio_api/info para conhecer os nomes dos endpoints e as entradas.
3. Para entradas de arquivo, ele faz um POST do arquivo para /gradio_api/upload e mantém o caminho retornado.
4. Ele faz um POST para /gradio_api/call/v2/<endpoint> e, em seguida, faz um GET na URL de polling para transmitir o resultado.