Ajan Araçları Olarak Spaces

Her Gradio Space, kodlama ajanlarının (Claude Code, Codex, OpenCode, Pi vb.) doğrudan çağırabileceği düz metin bir agents.md dosyası sunar. huggingface.co/spaces üzerinde anlamsal arama (ör. “audio transcription”) ile bir tane bulabilir, gerekirse önce arayüzde deneyebilir ve ardından ajanınızı ilgili agents.md dosyasına yönlendirebilirsiniz. Yanıt, Space'i tek seferde çağırmak için gereken her şeyi içerir: şema URL'si, çağrı ve sorgulama şablonları, dosya yükleme talimatları ve bir kimlik doğrulama ipucu.

Spaces zincirleme kullanıldığında bu özellik çok daha güçlü hale gelir. Bir ajan, bir istemciyi 3D varlığa dönüştürmek için önce bir görüntü oluşturmak üzere black-forest-labs/flux-klein-9b-kv çağrısını yapabilir, ardından oluşturulan görüntüyü 3D model için microsoft/TRELLIS.2 içine aktarabilir. İstemci kütüphanesi gerekmez, sabit kodlanmış entegrasyon gerekmez.

Başlamak için ortamınızda HF_TOKEN'ın ayarlanmış olması yeterlidir.

Arayüzden

Uyumluluğu olan her Space sayfasının başlığında bir Agents düğmesi bulunur. Bu düğmeye tıklayarak ilgili Space'in agents.md dosyası için curl komutunu kopyalayın, ardından komutu ajanınıza yapıştırın.

agents.md uç noktası

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

Örnek:

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

Dönüş:

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)

Dosya girdileri

Bir uç nokta dosya (görsel, ses, video vb.) alıyorsa, önce dosyayı yükleyin ve çağrınızda döndürülen yolu referans verin. /gradio_api/upload adresine yükleyin ve döndürdüğü yolu yeniden kullanın:

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

Yüklenen bir dosya yerine herkese açık bir URL kabul eden girdiler, yükleme adımından doğrudan geçirilebilir.

Kimlik Doğrulama ve ZeroGPU

En popüler Spaces, ZeroGPU üzerinde çalışır ve çağıranın günlük kota kullanımını dikkate alır. Agent'lar, çağrıların anonim ve kısıtlı bir havuz yerine hesabınıza faturalandırılmasını sağlamak için her zaman bir $HF_TOKEN geçirmelidir. Özel Spaces için de aynı token gereklidir. Bir token oluşturmak için huggingface.co/settings/tokens adresini kullanın (agents.md kimlik doğrulama satırı bu sayfaya doğrudan bağlantı verir).

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

Ajanların bunu nasıl kullanacağı

1. Ajan, Space için /agents.md dosyasını curl ile alır.
2. Uç nokta adlarını ve girdilerini öğrenmek için /gradio_api/info adresini alır.
3. Dosya girdileri için dosyayı /gradio_api/upload adresine POST eder ve döndürülen yolu saklar.
4. /gradio_api/call/v2/<endpoint> adresine POST gönderir, ardından sonucu akış olarak almak için poll URL'sine GET isteği gönderir.