A2A (Agent-to-Agent) protokolü Google'ın 2025'te açtığı standart — bir ajanın diğer ajanın yeteneklerini, kimliğini ve skill kataloğunu keşfetmesini sağlıyor. AIDE'nin proto-a2a-agent-card kontrolü bu manifestoyu sitenizin keşfedilebilirlik puanına katıyor.
Bağlam: AIDE bu kontrolde tam olarak neye bakıyor?
proto-a2a-agent-card aşağıdakileri sırayla doğrular:
https://<domain>/.well-known/agent.jsonHTTP 200 dönüyor mu?- JSON şeması A2A v0.2 spec'ine uygun mu? (
name,url,version,capabilities,skills) skillsarray'inde en az birid+descriptionçifti var mı?endpointURL'i tarama anında erişilebilir mi?
Üçüncü ve dördüncü adımlar proto-agent-skills kontrolünü besler — biri olmadan diğeri tam puan vermez.
Minimum Agent Card
{
"name": "AIDE Scan Agent",
"description": "AI hazırlık taraması yapan ve skor döndüren agent.",
"url": "https://api.aide.tr",
"version": "1.0.0",
"documentationUrl": "https://aide.tr/docs",
"provider": {
"organization": "AIDE",
"url": "https://aide.tr"
},
"capabilities": {
"streaming": true,
"pushNotifications": true,
"stateTransitionHistory": true
},
"authentication": {
"schemes": ["bearer"]
},
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["application/json"],
"skills": [
{
"id": "scan_url",
"name": "Site tara",
"description": "Bir URL'i 25+ standardı ile dener ve 0-100 arası AI hazırlık skoru döndürür.",
"tags": ["seo", "ai-readiness", "audit"],
"examples": [
"https://example.com için tarama yap",
"stripe.com siteyi AI ajanlarına nasıl uyumlu skor ne?"
],
"inputModes": ["text/plain"],
"outputModes": ["application/json"]
}
]
}
Kritik alanlar:
| Alan | Neden gerek? | AIDE etkisi |
|---|---|---|
| name + description | Ajan dispatcher'ı bu yazıdan amacınızı anlar | Eksikse parse hatası → FAIL |
| url | A2A endpoint base URL | HTTP olmamalı (HTTPS), yoksa WARNING |
| capabilities.streaming | Uzun süren işler için akış desteği | proto-agent-skills puanını etkiler |
| authentication.schemes | Hangi auth mekanizması bekleniyor | Bilinmeyen scheme → WARNING |
| skills[].id + description | Ajanlar bu çifti vector embedding'e koyup hangi skill'in işine yarayacağını seçer | Boşsa skill keşfedilemez |
Adım adım kurulum
1. JSON dosyasını üret
Static bir dosya olarak public/.well-known/agent.json koymak en hızlı yol. Ama version + skills sık değişeceği için template-driven üretim daha temiz:
# scripts/gen_agent_card.py
import json
from pathlib import Path
CARD = {
"name": "AIDE Scan Agent",
"description": "AI hazırlık taraması yapan ve skor döndüren agent.",
"url": "https://api.aide.tr",
"version": "1.0.0",
"capabilities": {"streaming": True, "pushNotifications": True, "stateTransitionHistory": True},
"authentication": {"schemes": ["bearer"]},
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["application/json"],
"skills": [...], # ayrı bir skills.yaml'dan yükleyin
}
Path("apps/web/public/.well-known/agent.json").write_text(
json.dumps(CARD, indent=2, ensure_ascii=False)
)
CI'da bunu build adımına ekleyin — skills değiştiğinde manifest tutarsız olmaz.
2. Caddy/Nginx ile yayınlayın
Next.js public/ dizinini doğal olarak serve eder; well-known da bunun altında olabilir. Ama bazı framework'ler public/.well-known yolunu reservedir varsayar. Caddy katmanından emin olmak için:
aide.tr {
handle_path /.well-known/* {
root * /opt/aide/apps/web/public/.well-known
file_server
header Content-Type application/json
header Cache-Control "public, max-age=300"
}
# ... diğer handler'lar
}
Cache 5 dakika — agent dispatcher'lar manifestoyu sık çekmiyor, ama yenilemeyi de geciktirmek istemiyorsunuz.
3. İçerik tipi + CORS
A2A manifesto CORS izinleri olmalı — uzaktaki ajanlar tarayıcıdan da çekebilir:
header /.well-known/agent.json Access-Control-Allow-Origin "*"
header /.well-known/agent.json Access-Control-Allow-Methods "GET, OPTIONS"
Content-Type kesinlikle application/json, text/plain değil.
Skills tasarımı: yaygın hatalar
| Hata | Belirti | Çözüm |
|---|---|---|
| Tek bir mega-skill (do_anything) | Ajan dispatcher hangi durumda çağıracağını bilemiyor | Skill'leri görev odaklı parçala (scan_url, get_score_history, compare_sites) |
| examples boş ya da çok soyut | Embedding match zayıf, skill çağrılmıyor | En az 3 somut user-language örnek koy ("X sitesini taratabilir misin?") |
| tags rastgele | Discovery filtreleri tutmuyor | Standardize edilmiş tag taksonomisi kullan (seo, audit, accessibility, security) |
| inputModes listesinde sadece JSON | Voice agents kullanamıyor | text/plain ekle, gerekirse audio/wav |
Authentication: scheme seçimi
A2A v0.2 üç scheme tanıyor:
none— Public read-only API'lar için. AIDE bunu PASS sayar ama production'da nadir.bearer— Standart API key veya OAuth access token. En yaygın.oauth2— Tam OAuth flow.proto-oauth-discoverykontrolü ile birlikte kullanın — bir agent dispatcher OAuth dance'ini yapabiliyor.
AIDE üçünü de eşit puanlar; sadece scheme bildirilmiş ve gerçekten o scheme zorlanıyor olmalı. Manifesto bearer diyor ama endpoint anonymous'a da cevap veriyorsa → WARNING.
A2A vs MCP: hangisi?
İki protokol birbirinin alternatifi değil:
- MCP = bir ajan araç çağırır (function call benzeri). Yarı-imperatif.
- A2A = bir ajan başka bir ajanı görevlendirir (delegate). Tam-otonom, yarı-asenkron.
Çoğu ürün ikisini de yayınlar:
- MCP server → Claude Desktop / IDE entegrasyonları için
- Agent Card → Diğer agent'ların sizi keşfetmesi için (Google Vertex AI Agent Builder, OpenAI Swarm vb.)
AIDE her ikisini ayrı ayrı puanlar — biri eksikse "aiready" skoru tam olmaz.
Doğrulama
Yayından sonra:
curl -s https://siteniz.com/.well-known/agent.json | jq '.skills | length'
En az 1 dönmeli. Sonra AIDE taraması:
curl -X POST https://api.aide.tr/v1/scans \
-H 'Content-Type: application/json' \
-d '{"url":"https://siteniz.com","profile":"ai_ready"}'
proto-a2a-agent-card ve proto-agent-skills ikisi de PASS gelmeli.
İlgili kaynaklar
- A2A Protocol Spec
- Agent Card Schema
- AIDE check detayları:
/learn/proto-a2a-agent-card,/learn/proto-agent-skills - AIDE Agent hazırlığı genel:
/learn/ai-agent-hazirligi-nedir