Hub documentation
Spaces를 에이전트 도구로
Spaces를 에이전트 도구로
모든 Gradio Space는 코딩 에이전트(Claude Code, Codex, OpenCode, Pi 등)가 직접 호출할 수 있는 평문 agents.md를 노출합니다. huggingface.co/spaces에서 의미 기반 검색(예: “audio transcription”)으로 해당 Space를 찾고, 필요에 따라 먼저 UI에서 사용해 본 후 에이전트를 해당 Space의 agents.md로 지정하세요. 응답에는 Space를 한 번에 호출하는 데 필요한 모든 정보가 포함됩니다: 스키마 URL, 호출 및 폴링 템플릿, 파일 업로드 지침, 인증 힌트.
Spaces 체이닝을 사용하면 이 기능이 더욱 강력해집니다. 에이전트는 black-forest-labs/flux-klein-9b-kv를 호출하여 이미지를 생성한 후, 생성된 이미지를 microsoft/TRELLIS.2로 전달하여 3D 모델을 만들 수 있습니다. 클라이언트 라이브러리나 하드코딩된 통합이 필요하지 않습니다.
시작하려면 환경에 HF_TOKEN만 설정하면 됩니다.
UI에서
호환되는 모든 Space 페이지의 헤더에 Agents 버튼이 있습니다. 이 버튼을 클릭하면 해당 Space의 agents.md에 대한 curl 명령이 복사되며, 이를 에이전트에 붙여넣으세요.
agents.md 엔드포인트
https://huggingface.co/spaces/<namespace>/<repo>/agents.md예:
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로 업로드하고 반환된 경로를 재사용하세요:
# 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에서 실행됩니다. Agent는 항상 $HF_TOKEN을 전달해야 하며, 이를 통해 호출 비용이 제한된 익명 풀이 아닌 사용자의 계정에 청구됩니다. 동일한 토큰은 비공개 Spaces에도 필요합니다. huggingface.co/settings/tokens에서 토큰을 생성할 수 있습니다(agents.md의 인증 라인이 이 페이지로 직접 연결됩니다).
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"}}'에이전트가 이를 사용하는 방법
- 에이전트가 Space의
/agents.md를curl합니다. /gradio_api/info를 가져와서 엔드포인트 이름과 입력을 확인합니다.- 파일 입력의 경우, 파일을
/gradio_api/upload로 POST하고 반환된 경로를 유지합니다. /gradio_api/call/v2/<endpoint>으로 POST 요청을 보낸 다음, poll URL을 GET 요청하여 결과를 스트리밍합니다.