Spaces dưới dạng Công cụ cho Agent

Mọi Gradio Space đều cung cấp một tệp văn bản thuần túy agents.md mà các coding agent (Claude Code, Codex, OpenCode, Pi, v.v.) có thể gọi trực tiếp. Bạn có thể tìm một Space thông qua tìm kiếm ngữ nghĩa trên huggingface.co/spaces (ví dụ: “audio transcription”), tùy chọn thử trước trong giao diện UI, sau đó trỏ agent của bạn đến tệp agents.md của nó. Phản hồi sẽ cung cấp mọi thứ cần thiết để gọi Space trong một lần duy nhất: URL schema, mẫu gọi và mẫu poll, hướng dẫn tải tệp lên, và gợi ý xác thực.

Điều này trở nên mạnh mẽ hơn nữa khi chuỗi hóa các Spaces. Một agent có thể biến một prompt thành tài sản 3D bằng cách gọi black-forest-labs/flux-klein-9b-kv để tạo ảnh, sau đó truyền ảnh đã tạo vào microsoft/TRELLIS.2 để tạo mô hình 3D. Không cần thư viện client, không cần tích hợp cứng.

Bạn chỉ cần đặt HF_TOKEN trong môi trường của mình để bắt đầu.

Từ giao diện người dùng

Mọi trang Space tương thích đều có nút Agents trong phần tiêu đề. Nhấp vào nút này để sao chép lệnh curl cho agents.md của Space đó, sau đó dán vào agent của bạn.

Điểm cuối agents.md

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

Ví dụ:

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

Trả về:

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)

Đầu vào tệp

Khi một endpoint nhận một tệp (ảnh, âm thanh, video, v.v.), hãy tải tệp lên trước và tham chiếu đường dẫn được trả về trong lời gọi của bạn. Tải lên /gradio_api/upload và tái sử dụng đường dẫn mà nó trả về:

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

Các đầu vào chấp nhận một URL công khai (thay vì một tệp đã tải lên) có thể được truyền trực tiếp mà không cần bước tải lên.

Xác thực và ZeroGPU

Phần lớn các Spaces phổ biến chạy trên ZeroGPU, sử dụng hạn mức hàng ngày của người gọi. Các Agent luôn nên truyền $HF_TOKEN để các cuộc gọi được tính phí vào tài khoản của bạn thay vì một pool ẩn danh bị giới hạn tốc độ. Cùng một token này cũng được yêu cầu cho các Spaces riêng tư. Tạo một token tại huggingface.co/settings/tokens (dòng xác thực trong agents.md liên kết trực tiếp đến trang này).

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

Cách các tác nhân sẽ sử dụng điều này

1. Agent curl /agents.md cho Space.
2. Nó lấy /gradio_api/info để tìm hiểu tên endpoint và các đầu vào.
3. Với đầu vào là tệp, nó POST tệp đến /gradio_api/upload và giữ lại đường dẫn được trả về.
4. Nó POST đến /gradio_api/call/v2/<endpoint>, sau đó GET URL poll để stream kết quả.