# Spaces 作为智能体工具

每个 Gradio Space 都会暴露一个纯文本的 `agents.md`，编码智能体（Claude Code、Codex、OpenCode、Pi 等）可以直接调用它。您可以通过在 [huggingface.co/spaces](https://huggingface.co/spaces) 上进行语义搜索（例如搜索“audio transcription”）来找到它，如有需要可先在 UI 中试用，然后将您的智能体指向其 `agents.md`。响应内容将提供一次性调用该 Space 所需的所有信息：schema URL、调用和轮询模板、文件上传说明以及身份验证提示。

当结合**Spaces 链式调用**时，其能力更为强大。智能体可以通过调用 [`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 模型，从而将提示词转化为 3D 资产。无需客户端库，也无需硬编码集成。

您只需在环境中设置 [HF_TOKEN](https://huggingface.co/settings/tokens) 即可开始使用。

## 从 UI

每个兼容的 Space 页面头部都有一个 **Agents** 按钮。点击该按钮即可复制该 Space 的 `agents.md` 的 `curl` 命令，然后将其粘贴到您的 agent 中。

## 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) 上，该服务使用调用者的每日配额。Agent 应始终传入 `$HF_TOKEN`，以便调用费用计入您的账户，而不是被限制在匿名池中。访问私有 Spaces 也需要相同的令牌。请在 [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) 创建一个（`agents.md` 中的 auth 行直接链接到该页面）。

```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. Agent 通过 `curl` 请求该 Space 的 `/agents.md`。
2. 它会获取 `/gradio_api/info` 以了解端点名称和输入。
3. 对于文件输入，它会通过 POST 请求将文件发送到 `/gradio_api/upload`，并保留返回的路径。
4. 它向 `/gradio_api/call/v2/<endpoint>` 发送 POST 请求，然后 GET 轮询 URL 以流式获取结果。