Genel ajan keşfi
Başka bir A2A istemcisinin, ajanınızın bir görevi tamamlayıp tamamlayamayacağına karar vermeden önce aldığı JSON'ı şekillendirmek için bu örnekleri kullanın.
6 kopyalamaya hazır JSON şablonu · A2A v1.0
A2A Agent Card Örnekleri
Pratik A2A v1.0 şablonlarına göz atın, tasarım kararlarını anlayın, ardından herhangi bir örneği kendi ajanınız için uyarlayın.
Pazar yeri gönderimi
Sağlayıcı, skill, etiket, yetenek, ve güvenlik meta verilerini uyarlayarak incelemecilerin ajanın ne yaptığını ve kimin işlettiğini anlamasını sağlayın.
Dahili ajan katalogları
Ekipler onları iş akışlarına entegre etmeden önce dahili ajanlar arasında uç nokta, kimlik doğrulama, ve skill açıklamalarını standartlaştırın.
JSON şablonları
Destek, rezervasyon, alışveriş, kodlama, araştırma, ve iş akışı ajanları için örnek Agent Card'lar.
Filtrele
Müşteri Destek Ajanı
Ürün sorularını, sipariş sorgulamalarını, iadeleri, ve eskalasyon devirlerini ele alır.
Neden bu şekilde oluşturuldu
- OAuth 2.0 istemci kimlik bilgileri sipariş verilerini korur: Agent Card, token URL'sini ve scope'u bildirir, böylece istemciler bant dışı belge olmadan kimlik doğrulayabilir.
- Destek konuşmaları uzun sürdüğü ve çözüm güncellemeleri asenkron olarak geldiği için streaming ve pushNotifications her ikisi de true'dur.
- Tek skill, belirsiz bir "müşterilere yardım et" açıklaması yerine tek bir görev sınırına (sınıflandır, çöz, yükselt) sınırlandırılmıştır, böylece yönlendiriciler onu tam olarak eşleştirebilir.
{
"name": "Müşteri Destek Ajanı",
"description": "Müşteri desteği sorularını yanıtlar, sipariş içeriğini alır ve çözülmemiş sorunları bir insan ekibine iletir.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/customer-support",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Örnek A.Ş.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "resolve-customer-support-request",
"name": "Müşteri desteği talebini çözümleyin",
"description": "Bir müşteri destek talebini sınıflandırır, gerekli bağlamı toplar, bir çözüm önerir ve güven düşük olduğunda üst kademeye iletir.",
"tags": [
"support",
"orders",
"returns"
],
"examples": [
"Siparişimi iade etmeme yardım edin."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/customer-support/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Rezervasyon Ajanı
Uygun randevu zaman dilimlerini bulur ve rezervasyon onaylarını hazırlar.
Neden bu şekilde oluşturuldu
- Bir başlıkta bir API anahtarı burada yeterlidir: rezervasyonlar kiracı kapsamlıdır ancak OAuth'un çözdüğü yetkilendirilmiş kullanıcı onayı sorununu taşımaz.
- defaultOutputModes yalnızca application/json'dır ve çağıranların düzyazı yerine yapılandırılmış rezervasyon önerileri aldığını gösterir.
- pushNotifications true'dur, böylece ajan, istemci yoklama yapmadan, slotu tutan arka uç yerleştikten sonra bir rezervasyonu onaylayabilir.
{
"name": "Rezervasyon Ajanı",
"description": "Uygunluğu araştırır, rezervasyon seçeneklerini önerir ve randevu rezervasyonlarını onaya hazırlar.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/booking",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Örnek A.Ş.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "find-and-prepare-booking",
"name": "Rezervasyonu bulun ve hazırlayın",
"description": "Kaynak kullanılabilirliğini kontrol eder, rezervasyon aralıklarını karşılaştırır ve yapılandırılmış bir rezervasyon teklifi döndürür.",
"tags": [
"booking",
"calendar",
"availability"
],
"examples": [
"Yarın öğleden sonra 30 dakikalık bir randevu bulun."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Alışveriş Ajanı
Ürünleri, uygunluğu, fiyatları, ve satın alma kısıtlamalarını karşılaştırır.
Neden bu şekilde oluşturuldu
- Sıralanmış öneriler hesaplandıkça akış olarak gelir, bu nedenle streaming true iken pushNotifications false kalır — yanıt tamamlandıktan sonra hiçbir şey olmaz.
- Skill açıklaması, ödünleşimler ve gerekçe döndürmeyi taahhüt eder, bu da orkestratörlere bu ajanın sadece ürünleri listelemek yerine sıralamaları açıkladığını söyler.
- OAuth scope'ları satın almayla ilgili verileri kısıtlar; genel bir alışveriş demosu güvenliği tamamen kaldırabilir ve geçerli bir Agent Card olarak kalabilir.
{
"name": "Alışveriş Ajanı",
"description": "Ürünleri kullanıcı kısıtlamalarıyla karşılaştırır ve sıralanmış satın alma seçeneklerini ödünlerle birlikte döndürür.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/shopping",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Örnek A.Ş.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "compare-shopping-options",
"name": "Alışveriş seçeneklerini karşılaştırın",
"description": "Aday ürünleri değerlendirir, kısıtlamalara göre filtreler ve sıralanmış önerileri mantıklı bir şekilde döndürür.",
"tags": [
"shopping",
"commerce",
"recommendations"
],
"examples": [
"1.200 doların altındaki hafif dizüstü bilgisayarları karşılaştırın."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/shopping/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Kodlama Ajanı
Kod görevlerini inceler, yamalar önerir, ve uygulama kararlarını açıklar.
Neden bu şekilde oluşturuldu
- extendedAgentCard true'dur: genel Agent Card genel bir "kod değişikliği uygula" skill'ini listeler, depoya özgü skill'ler ise yalnızca GetExtendedAgentCard aracılığıyla kimliği doğrulanmış istemcilere gösterilir.
- Ajan, makine tarafından uygulanabilir yamalarla birlikte insan tarafından okunabilir açıklamalar döndürdüğü için hem text/plain hem de application/json çıktıları bildirilir.
- Uzun derleme-ve-test döngüleri için akış önemlidir; istemciler sessiz, çok dakikalık bir çağrı yerine ara ilerlemeyi görür.
{
"name": "Kodlama Ajanı",
"description": "Kodu analiz ederek, değişiklik önererek ve uygulama notlarını geri göndererek yazılım mühendisliği görevlerine yardımcı olur.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/coding",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Örnek A.Ş.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"text/plain",
"application/json"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "implement-code-change",
"name": "Kod değişikliğini uygulayın",
"description": "Bir kodlama isteğini okur, ilgili dosyaları inceler, bir yama teklifi döndürür ve doğrulama adımlarını özetler.",
"tags": [
"coding",
"review",
"patches"
],
"examples": [
"Kullanıcı API'sine sayfalandırma ekleyin."
]
}
],
"securitySchemes": {
"apiKey": {
"apiKeySecurityScheme": {
"location": "header",
"name": "X-API-Key"
}
}
},
"security": [
{
"apiKey": []
}
]
}Araştırma Ajanı
Kaynakları toplar, kanıt çıkarır, ve yapılandırılmış araştırma notları döndürür.
Neden bu şekilde oluşturuldu
- Hiç securitySchemes yok: uç nokta kasıtlı olarak herkese açıktır ve alanı atlamak bunu belirtmenin doğru yoludur — boş bir şema haritası belirsiz olurdu.
- Girdi yalnızca text/plain'dir, çünkü araştırma özetleri doğal dil sorularıyla başlar; yapılandırılmış çıktı application/json notları olarak gelir.
- Bu, minimum düzeyde kullanışlı bir v1.0 Agent Card: kimlik, bir arayüz, yetenekler, modlar, ve iyi etiketlenmiş bir skill.
{
"name": "Araştırma Ajanı",
"description": "Kaynak materyali toplar, kanıtları çıkarır ve alıntılarla birlikte yapılandırılmış araştırma notları üretir.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/research",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Örnek A.Ş.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": true,
"pushNotifications": false,
"extendedAgentCard": false
},
"defaultInputModes": [
"text/plain"
],
"defaultOutputModes": [
"text/plain",
"application/json"
],
"skills": [
{
"id": "prepare-research-brief",
"name": "Araştırma özetini hazırlayın",
"description": "Onaylanmış kaynakları arar, iddiaları ve kanıtları çıkarır ve kısa bir araştırma özeti sunar.",
"tags": [
"research",
"evidence",
"citations"
],
"examples": [
"Yenilenebilir enerji politikası hakkında alıntı yapılan bir özet hazırlayın."
]
}
]
}Dahili İş Akışı Ajanı
Onayları, durum kontrollerini, ve arka ofis iş akışı güncellemelerini koordine eder.
Neden bu şekilde oluşturuldu
- application/json tek giriş ve çıkış modudur: bu ajan diğer sistemler tarafından çağrılır, asla düzyazı yazan insanlar tarafından çağrılmaz.
- OAuth 2.0 artı extendedAgentCard kurumsal denetimlere uyar — güvenlik ekipleri kimlik doğrulama gereksinimlerini herkese açık olarak görebilirken hassas iş akışı skill'leri kimlik doğrulamanın arkasında kalır.
- Onay zincirleri saatler veya günler sürdüğü için pushNotifications esastır; webhook'lar durum değişiklikleri için yoklamanın yerini alır.
{
"name": "Dahili İş Akışı Ajanı",
"description": "Dahili onayları koordine eder, sistem durumunu kontrol eder ve operasyon ekipleri için iş akışı güncellemelerini hazırlar.",
"supportedInterfaces": [
{
"url": "https://api.example.com/a2a/workflow",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0"
}
],
"provider": {
"organization": "Örnek A.Ş.",
"url": "https://example.com"
},
"version": "1.0.0",
"capabilities": {
"streaming": false,
"pushNotifications": true,
"extendedAgentCard": true
},
"defaultInputModes": [
"application/json"
],
"defaultOutputModes": [
"application/json"
],
"skills": [
{
"id": "coordinate-internal-workflow",
"name": "Dahili iş akışını koordine edin",
"description": "İş akışı amacını alır, politika gereksinimlerini kontrol eder, onayları toplar ve son durumu raporlar.",
"tags": [
"workflow",
"operations",
"approval"
],
"examples": [
"Bordro güncellemesini dağıtmak için onay isteyin."
]
}
],
"securitySchemes": {
"oauth2": {
"oauth2SecurityScheme": {
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.example.com/a2a/workflow/oauth/token",
"scopes": {
"agent.invoke": "Invoke agent skills"
}
}
}
}
}
},
"security": [
{
"oauth2": [
"agent.invoke"
]
}
]
}Güvenle uyarlayın
Bir Agent Card örneği nasıl uyarlanır
Her Agent Card örneği, kopyalanacak kadar kasıtlı olarak eksiksizdir, ancak Agent Card değiştirilmeden yayınlanmamalıdır. Bunu kendi A2A sunucunuz için bir alan haritası olarak ele alın: kimlik, uç nokta, sağlayıcı, kimlik doğrulama, yetenekler, modlar, ve skill ayrıntılarını üretim değerleriyle değiştirin.
En güçlü Agent Card'lar, ajanın görev sınırını hem sade bir dille hem de makine tarafından okunabilir meta verilerle açıklar. Bir istemci, ajanın ne yapabileceğini, ne yapamayacağını, hangi URL'yi çağıracağını, ve kimlik bilgilerinin gerekip gerekmediğini anlayabilmelidir.
Yayınlamadan önce
Her example.com URL'sini dağıtılan A2A uç noktanız ve sağlayıcı web sitenizle değiştirin.
Skill adını, açıklamayı, etiketleri (v1.0'da zorunlu), ve örnekleri gerçek görev sınırı için yeniden yazın.
provider.organization'ı ayarlayın ve Agent Card içeriği her değiştiğinde üst düzey version'ı artırın.
Kimlik doğrulama alanlarını yalnızca uç nokta kasıtlı olarak herkese açık olduğunda kaldırın.
defaultInputModes ve defaultOutputModes'u sunucunuzun gerçekte kabul ettiği ve döndürdüğü şeyle uyumlu tutun.
Son JSON'ı doğrulayın ve hizmet alanınızdaki /.well-known/agent-card.json'da yayınlayın.
İnşa etmeye hazır
Bir örnekle başlayın, ardından kendinize özgü hale getirin.
Agent Card Oluşturucu'da herhangi bir deseni açın, JSON'ı inceleyin, ve yayınlamadan önce doğrulayın.