README.md

metadata

title: Spaces as Agent Tools
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.33.0
app_file: app.py
pinned: false
license: mit
tags:
  - agents
  - mcp
  - spaces-api
  - demo
short_description: Use any HF Space as a coding agent tool via agents.md

🤖 Spaces as Agent Tools

Every Gradio Space on Hugging Face exposes a plain-text agents.md that coding agents (Claude Code, Codex, OpenCode, Pi, etc.) can call directly — no client library, no hardcoded integration.

This Space is both a live demo you can use in the browser and a reference guide you can copy into your agent.

---

🖥️ Browser Walkthrough

What you need

• A free Hugging Face account
• A Hugging Face token (only for the Chain demo) — create one here

Step-by-step

1. Open the Space

Go to ▶ Open the demo in your browser.

You'll see three tabs at the top: 🔍 Explore a Space, ⛓️ Chain: Text → Image → 3D, and 📋 curl Reference.

---

2. 🔍 Explore a Space (works immediately — no token needed)

This tab lets you inspect any Gradio Space's agent interface.

1. The Space ID field is pre-filled with black-forest-labs/flux-klein-9b-kv
2. Click 🔍 Explore
3. You'll see three things:
   • agents.md — the exact 4-line text a coding agent reads to know how to call this Space
   • curl command — copy-paste this into Claude Code, Codex, or any terminal
   • API Endpoints — every function the Space exposes, with parameter names, types, and defaults

Try it: Click one of the example buttons below the input (e.g. microsoft/TRELLIS.2 or Qwen/Qwen3-ASR) to explore other Spaces.

Tip: You can type any Gradio Space ID here — not just the examples. Try one of your own Spaces!

---

3. ⛓️ Chain: Text → Image → 3D (requires one-time token setup)

This tab demonstrates chaining two Spaces — the same thing a coding agent does behind the scenes, but visible step by step.

One-time setup (2 minutes):

Since this demo calls GPU-powered Spaces on your behalf, it needs your Hugging Face token.

1. Create a token (if you don't have one):

   • Go to huggingface.co/settings/tokens
   • Click Create new token
   • Name it anything (e.g. "spaces-demo")
   • Type: Read is enough
   • Click Create token and copy it

2. Add the token to this Space:

   • Go to ⚙️ Space Settings
   • Scroll down to Variables and secrets
   • Click New secret
   • Name: HF_TOKEN
   • Value: paste your token
   • Click Save
   • The Space will restart automatically (takes ~30 seconds)

Using the chain demo:

1. Switch to the ⛓️ Chain: Text → Image → 3D tab
2. Type a prompt (or keep the default: "a glowing crystal dragon perched on a rocky mountain peak")
3. Click 🚀 Generate
4. Watch the pipeline log at the bottom as it:
   • Calls FLUX Klein 9B to generate an image from your text
   • Sends that image to TRELLIS.2 for background removal
   • Generates a 3D model from the image
   • Extracts a downloadable .GLB mesh
5. The generated image appears on the left, the 3D preview on the right, and the GLB download below

⏱️ The full pipeline takes about 1–3 minutes depending on queue times.

💡 This is the exact same REST protocol (POST → poll SSE) that a coding agent uses. The log shows you every step.

---

4. 📋 curl Reference (no token needed)

This tab is a full copy-paste cheatsheet. It covers:

• How to read any Space's agents.md
• How to inspect the API schema
• How to submit a job and poll for results
• How to chain FLUX → TRELLIS.2 end to end
• A Python gradio_client alternative
• Authentication tiers and quotas

For coding agent users: Copy the curl commands from this tab directly into your agent's context.

---

🔑 How agents.md works

Every Gradio Space automatically exposes a URL:

https://huggingface.co/spaces/{owner}/{name}/agents.md

The response is always 4 lines of plain text:

To use this application (owner/name: description):
API schema: GET https://owner-name.hf.space/gradio_api/info
Call endpoint: POST https://owner-name.hf.space/gradio_api/call/{endpoint} {"data": [...]}
Poll result: GET https://owner-name.hf.space/gradio_api/call/{endpoint}/{event_id}
Auth: Bearer $HF_TOKEN

A coding agent reads this, fetches the schema to learn the parameters, and then makes standard HTTP calls. That's it.

---

🔗 From any Space's UI

You don't need this demo to use agent tools. On any compatible Space page:

1. Look for the Agents button in the Space header
2. Click it → the curl command is copied to your clipboard
3. Paste it into your coding agent (Claude Code, Codex, OpenCode, etc.)

---

⛓️ Chaining — why this is powerful

An agent can compose Spaces like building blocks:

Step	Space	Input	Output
1	FLUX Klein 9B	text prompt	image
2	TRELLIS.2	image	3D model (.GLB)

The image URL from step 1 is passed directly as input to step 2. No file download, no SDK, no glue code — just HTTP.

Other possible chains:

• Text → Image → Video (FLUX → video generation Space)
• Audio → Text → Translation (ASR Space → translation Space)
• Image → Caption → Image (captioning Space → image gen Space)

---

📋 Popular Spaces to try

Space	What it does	Try it
FLUX Klein 9B	Text → Image	curl https://huggingface.co/spaces/black-forest-labs/flux-klein-9b-kv/agents.md
FLUX.2 Klein 9B	Text → Image (v2)	curl https://huggingface.co/spaces/black-forest-labs/FLUX.2-klein-9B/agents.md
TRELLIS.2	Image → 3D Model	curl https://huggingface.co/spaces/microsoft/TRELLIS.2/agents.md
Qwen3 ASR	Audio → Text	curl https://huggingface.co/spaces/Qwen/Qwen3-ASR/agents.md
Z-Image Turbo	Text → Image (fast)	curl https://huggingface.co/spaces/mrfakename/Z-Image-Turbo/agents.md

Find more on huggingface.co/spaces — any Gradio Space has an agents.md.

---

🔐 Authentication tiers

Tier	ZeroGPU quota	How to get it
No token	2 min/day	—
Free account	3.5 min/day	Sign up
PRO account	25 min/day	Upgrade

Get your token at: huggingface.co/settings/tokens