Spaces as Agent Tools

Every Gradio Space exposes a plain-text agents.md that coding agents (Claude Code, Codex, OpenCode, Pi, etc.) can call directly. Find one via semantic search on huggingface.co/spaces (e.g. “audio transcription”), optionally try it in the UI first, then point your agent at its agents.md. The response is four lines: schema URL, call template, poll template, auth hint.

This gets even more powerful when chaining Spaces. An agent can turn a prompt into a 3D asset by calling black-forest-labs/flux-klein-9b-kv for an image, then passing the generated image into microsoft/TRELLIS.2 for the 3D model. No client library, no hardcoded integration.

All you need is an HF_TOKEN set in your environment to get started.

From the UI

Every compatible Space page has an Agents button in the header. Click it to copy the curl command for that Space’s agents.md, then paste it into your agent.

The agents.md endpoint

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

Example:

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

Returns:

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/{endpoint} {"data": [...]}
Poll result: GET https://microsoft-trellis-2.hf.space/gradio_api/call/{endpoint}/{event_id}
Auth: Bearer $HF_TOKEN

Authentication and ZeroGPU

Most popular Spaces run on ZeroGPU, which uses the caller’s daily quota. Agents should always pass an $HF_TOKEN so calls are billed to your account rather than a throttled anonymous pool. The same token is also required for private Spaces.

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

How agents will use this

1. The agent curls /agents.md for the Space.
2. It fetches /gradio_api/info to learn endpoint names and inputs.
3. It POSTs to /gradio_api/call/<endpoint>, then GETs the poll URL to stream the result.