에이전트 도구로서의 Spaces

에이전트 도구로서의 Spaces

모든 Gradio Space는 코딩 에이전트(Claude Code, Codex, OpenCode, Pi 등)가 직접 호출할 수 있는 평문 agents.md를 노출해요. huggingface.co/spaces에서 시맨틱 검색(예: "audio transcription")으로 찾고, 선택적으로 UI에서 먼저 시험해 본 다음, 에이전트를 해당 agents.md에 연결하면 돼요. 응답은 Space를 한 번에 호출하는 데 필요한 모든 것 — 스키마 URL, 호출·폴링 템플릿, 파일 업로드 지침, 인증 힌트 — 을 제공해요.

Spaces 체이닝으로 더 강력해져요. 에이전트는 black-forest-labs/flux-klein-9b-kv를 호출해 이미지를 만들고, 생성된 이미지를 microsoft/TRELLIS.2에 넘겨 3D 모델을 얻는 식으로 프롬프트를 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 "[email protected]", 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 ***" \
  https://microsoft-trellis-2.hf.space/gradio_api/upload \
  -F "[email protected]"
# → ["/tmp/gradio/.../chair.png"]

# 2. Reference the returned path as a FileData object in your call
curl -H "Authorization: Bearer ***" \
  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에서 실행돼요. 에이전트는 항상 $HF_TOKEN을 전달해서 호출이 스로틀링된 익명 풀이 아니라 내 계정으로 청구되도록 해야 해요. 같은 토큰은 비공개 Spaces에도 필요해요. huggingface.co/settings/tokens에서 생성해요(agents.md 인증 줄이 이 페이지에 직접 연결돼요).

curl -H "Authorization: Bearer ***" \
  https://microsoft-trellis-2.hf.space/gradio_api/call/v2/predict \
  -d '{"image": {"path": "https://example.com/chair.png"}}'

에이전트가 이것을 어떻게 사용하나요

  1. 에이전트가 Space의 /agents.md를 curl로 가져와요.
  2. /gradio_api/info를 가져와 엔드포인트 이름과 입력을 학습해요.
  3. 파일 입력은 파일을 /gradio_api/upload에 POST하고 반환된 경로를 유지해요.
  4. /gradio_api/call/v2/<endpoint>에 POST한 다음 폴링 URL을 GET해 결과를 스트리밍해요.

더 알아보기 (Learn more)

  • Gradio Space의 agents.md로 코딩 에이전트가 별도 라이브러리 없이 Space를 호출할 수 있어요.
  • 여러 Space를 체이닝해 이미지 → 3D 자산 같은 복합 파이프라인을 만들 수 있어요.
  • ZeroGPU 문서에서 Spaces GPU 할당량 동작을 확인해 보세요.