Şema referansı · 14 fieldsA2A v1.0
Agent Card, A2A istemcilerine bir agent'ın kim olduğunu, nasıl ulaşılacağını, neler yapabildiğini ve erişimin nasıl güvence altına alındığını söyleyen standartlaştırılmış JSON belgesidir. Bu referans, tüm v1.0 alanlarını türler, gereksinimler, örnekler ve doğrulayıcıların en sık yakaladığı hatalarla ele alır.
Keşif nasıl çalışır
Bir A2A istemcisi Agent Card well-known URI'den alır, görevine göre skill'leri, yetenekleri ve güvenlik gereksinimlerini değerlendirir, ardından tercih edilen arayüzü — supportedInterfaces içindeki ilk girişi — çağırır. capabilities.extendedAgentCard true ise, kimliği doğrulanmış istemciler GetExtendedAgentCard işlemi aracılığıyla daha zengin bir Agent Card isteyebilir.
Spesifikasyon /.well-known/agent-card.json'ı standart konum olarak kaydeder. Daha eski v0.x dağıtımları /.well-known/agent.json kullanıyordu, bu nedenle doğrulayıcımız her ikisini de kontrol eder.
# Fetch a public Agent Card
GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
HTTP/1.1 200 OK
Content-Type: application/a2a+json
{
"name": "GeoSpatial Route Planner Agent",
"supportedInterfaces": [
{ "url": "https://georoute-agent.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
],
...
}Alan referansı
Zorunlu bayraklar, resmi spesifikasyondaki v1.0 protobuf tanımlarını takip eder. Çapa bağlantıları her alanı sorunlardan, incelemelerden ve CI çıktısından alıntılanabilir hale getirir.
Agent'ın insan tarafından okunabilir adı.
Pazar yeri listelerinde ve istemci arayüzlerinde gösterilir. Kısa ve spesifik tutun — istemciler aday agent'ları karşılaştırırken bunu birincil etiket olarak kullanır.
Yaygın hata: Yönlendirme sistemlerine ayırt edecek hiçbir şey vermeyen "AI Assistant" gibi genel bir ad kullanmak.
"name": "GeoSpatial Rota Planlayıcı Aracısı"
Agent'ın ne yaptığı ve başka bir agent'ın onu ne zaman çağırması gerektiği.
Bu, agent'ınızın bir göreve uygun olup olmadığına karar veren hem insan entegratörler hem de LLM tabanlı yönlendiriciler için ana serbest metin sinyalidir. Görev alanını, temel yetenekleri ve sınırları belirtin.
Yaygın hata: 20 karakterden kısa tek satırlık açıklamalar. Yönlendiriciler tanımlamadığınız şeyi eşleştiremez.
"description": "Gelişmiş rota planlama, trafik analizi ve özel harita oluşturma hizmetleri sağlar."
Uç noktaların ve protokol bağlamalarının sıralı listesi. İlk giriş tercih edilir.
v1.0'da yeni: eski üst düzey url, preferredTransport ve additionalInterfaces alanlarının yerini alır. Her giriş kendi url'sini, protocolBinding'ini (JSONRPC, GRPC, HTTP+JSON veya özel bir bağlama URI'si), protocolVersion'ını ve isteğe bağlı bir kiracı yönlendirme anahtarını bildirir — böylece bir agent birden fazla protokol sürümünü ve taşımasını aynı anda sunabilir.
Yaygın hata: Sunucunun o URL'de gerçekte sunmadığı bir bağlamayı bildirmek — spesifikasyon her girişin doğru olmasını gerektirir.
"supportedInterfaces": [
{ "url": "https://api.example.com/a2a/v1",
"protocolBinding": "JSONRPC",
"protocolVersion": "1.0" }
]Agent'ı kim işletiyor: kuruluş ve web sitesi.
Pazar yerleri ve kurumsal denetimler için güven sinyali. v1.0, name alanını organization olarak yeniden adlandırdı; mevcut olduğunda nesnenin içinde url zorunludur.
Yaygın hata: Hâlâ provider.name (v1.0 öncesi) kullanmak. v1.0 Agent Card okuyan doğrulayıcılar bunu tanımayacaktır.
"provider": {
"organization": "Örnek Geo Services Inc.",
"url": "https://www.examplegeoservices.com"
}Protokolün değil, agent'ın kendisinin sürümü.
İstemcilerin bir Agent Card önemli ölçüde değiştiğini algılamasına ve uyumluluğu yeniden değerlendirmesine olanak tanır. Kendi sürüm şemanızı, genellikle semver'i takip edin.
Yaygın hata: Bunu A2A protokol sürümüyle karıştırmak — o artık her supportedInterfaces girişinde yer alıyor.
"version": "1.2.0"
Agent için insan tarafından okunabilir belgelere bağlantı.
Entegratörlere, bir keşif belgesine ait olmayan tam API sözleşmesini, hız sınırlarını ve şartları okuyacakları bir yer sağlar.
Yaygın hata: Teknik belgeler yerine bir pazarlama ana sayfasına işaret etmek.
"documentationUrl": "https://docs.example.com/agent"
Protokol özellik bayrakları: streaming, pushNotifications, extensions, extendedAgentCard.
İstemciler bildirmediğiniz özellikleri ÇAĞIRMAMALIDIR — bildirilmemiş streaming çağrıları hata döndürür. extendedAgentCard: true, GetExtendedAgentCard işlemi aracılığıyla daha zengin, kimliği doğrulanmış bir Agent Card sunulduğunu duyurur. v1.0, stateTransitionHistory'yi kaldırdı.
Yaygın hata: Sunucunun streaming uç noktası olmadığında streaming: true bildirmek. İstemciler onu çağıracak ve başarısız olacaktır.
"capabilities": {
"streaming": true,
"pushNotifications": true,
"extendedAgentCard": false
}Adlandırılmış kimlik doğrulama şemaları: API anahtarı, HTTP kimlik doğrulama, OAuth 2.0, OpenID Connect, veya karşılıklı TLS.
Her adlandırılmış şema, somut bir şema nesnesini (apiKeySecurityScheme, httpAuthSecurityScheme, oauth2SecurityScheme, openIdConnectSecurityScheme, mtlsSecurityScheme) sarmalar. İstemciler buradan nasıl kimlik doğrulayacaklarını keşfeder — kimlik bilgilerinin kendisi her zaman bant dışı elde edilir.
Yaygın hata: Agent Card gerçek bir API anahtarı veya token gömmek. Bir Agent Card genel bir belgedir.
"securitySchemes": {
"google": {
"openIdConnectSecurityScheme": {
"openIdConnectUrl": "https://accounts.google.com/.well-known/openid-configuration"
}
}
}Agent'ı çağırmak için hangi bildirilen şemaların (ve kapsamların) gerekli olduğu.
Her giriş, securitySchemes'den bir şema adını ihtiyaç duyduğu kapsamlarla eşleştirir ve OpenAPI güvenlik gereksinimi düzenini yansıtır. Kasıtlı olarak genel agent'lar için her iki alanı da tamamen atlayın.
Yaygın hata: securitySchemes'i bildirmek ama security gereksinimleri olmadan, istemcilerin kimlik doğrulamanın zorunlu olup olmadığını tahmin etmesine bırakmak.
"security": [{ "google": ["openid", "profile", "email"] }]Agent'ın tüm skill'lerde kabul ettiği medya türleri.
text/plain, application/json, veya image/png gibi standart MIME türleri. Ayrı skill'ler kendi inputModes'ları ile geçersiz kılabilir.
Yaygın hata: Alanı atlamak. v1.0'da zorunludur — istemcilerin istekleri şekillendirmek için buna ihtiyacı vardır.
"defaultInputModes": ["application/json", "text/plain"]
Agent'ın tüm skill'lerde döndürdüğü medya türleri.
Çağıranlara düz metin, yapılandırılmış JSON, resimler, veya dosyalar mı bekleyeceklerini söyler. Skill'ler outputModes ile skill başına geçersiz kılabilir.
Yaygın hata: Agent aslında yapılandırılmış çıktılar döndürürken yalnızca text/plain'i listelemek.
"defaultOutputModes": ["application/json", "image/png"]
Agent'ın başarılı olması muhtemel somut yetenekler.
Her skill id, name, description, ve tags gerektirir; examples, skill başına modlar, ve skill başına güvenlik isteğe bağlıdır. Skill'ler keşfin birimidir — yönlendiriciler görevleri bunlara göre eşleştirir, bu yüzden her birini tek bir görev sınırıyla sınırlayın.
Yaygın hata: Etiketsiz skill'ler. Etiketler v1.0'da zorunlu hale geldi ve skill düzeyinde eşleştirmeyi yönlendirir.
"skills": [{
"id": "route-optimizer-traffic",
"name": "Trafiğe Duyarlı Rota Optimize Edici",
"description": "Gerçek zamanlı trafiği kullanarak en uygun sürüş rotalarını hesaplar...",
"tags": ["maps", "routing", "traffic"],
"examples": ["Ücretlerden kaçınarak A'dan B'ye bir rota planlayın."]
}]Agent Card sağlayıcı tarafından yayınlandığını kanıtlayan JSON Web İmzaları.
Her imza, RFC 8785 (JCS) ile kanonikleştirilmiş Agent Card üzerinden hesaplanan base64url korumalı bir JWS başlığı ve imza değeri taşır. İstemciler, açık web'den alınan bir Agent Card güvenmeden önce en az bir imzayı DOĞRULAMALIDIR.
Yaygın hata: Kartı imzalayıp ardından herhangi bir alanı düzenlemek — boşluk açısından önemsiz değer değişiklikleri bile JWS'yi geçersiz kılar.
"signatures": [{
"protected": "eyJhbGciOiJFUzI1NiIs...",
"signature": "QFdkNLNszlGj3z3u0YQ..."
}]Agent'ı temsil eden bir simgeye URL.
Kataloglar ve istemci arayüzleri tarafından kullanılır. Kararlı bir konumdan HTTPS üzerinden sunun.
Yaygın hata: Listelemenizin ardından değişebilecek, farklı ve güvenilmeyen bir alan adındaki bir simgeye bağlantı vermek.
"iconUrl": "https://agent.example.com/icon.png"
Sürüm geçişi
Agent Card hâlâ üst düzey bir url veya preferredTransport varsa, v1.0'dan öncedir. Doğrulayıcı bunların her birini otomatik olarak işaretler.
| v0.x alanı | v1.0 değişikliği | Neden değişti |
|---|---|---|
| url | supportedInterfaces[0].url | Tercih edilen uç nokta artık basitçe ilk arayüz girişidir. |
| preferredTransport | supportedInterfaces[] ordering | Tercih, ayrı bir alan yerine dizi sırasıyla ifade edilir. |
| additionalInterfaces | supportedInterfaces[] | Tüm arayüzler tek bir sıralı dizide bulunur. |
| protocolVersion (top level) | supportedInterfaces[].protocolVersion | Her arayüz kendi protokol sürümünü bildirir ve çoklu sürüm desteğini mümkün kılar. |
| supportsAuthenticatedExtendedCard | capabilities.extendedAgentCard | capabilities nesnesine taşındı; RPC, GetExtendedAgentCard olarak yeniden adlandırıldı. |
| provider.name | provider.organization | Netlik için yeniden adlandırıldı. |
| capabilities.stateTransitionHistory | — removed | v1.0'ın bir parçası değil; gerekirse eşdeğer davranışı bir uzantı olarak modelleyin. |
Şablon kod
Agent Card'ları tür güvenliğiyle ayrıştırmak ve üretmek için bu arayüzleri bir istemciye, sunucuya, veya CI kontrolüne yerleştirin. Bunlar, Agent Card yayınlandığı camelCase JSON biçiminde, resmi spesifikasyon deposundaki protobuf tanımlarını yansıtır.
Bunun yerine bir Agent Card elle mi oluşturuyorsunuz? Oluşturucu tam olarak bu şekli üretir.
// A2A v1.0 Agent Card — TypeScript definitions
export interface AgentCard {
name: string
description: string
supportedInterfaces: AgentInterface[]
provider?: AgentProvider
version: string
documentationUrl?: string
capabilities: AgentCapabilities
securitySchemes?: Record<string, SecurityScheme>
security?: Record<string, string[]>[]
defaultInputModes: string[]
defaultOutputModes: string[]
skills: AgentSkill[]
signatures?: AgentCardSignature[]
iconUrl?: string
}
export interface AgentInterface {
url: string
protocolBinding: 'JSONRPC' | 'GRPC' | 'HTTP+JSON' | (string & {})
protocolVersion: string
tenant?: string
}
export interface AgentProvider {
organization: string
url: string
}
export interface AgentCapabilities {
streaming?: boolean
pushNotifications?: boolean
extensions?: AgentExtension[]
extendedAgentCard?: boolean
}
export interface AgentExtension {
uri: string
description?: string
required?: boolean
params?: Record<string, unknown>
}
export interface AgentSkill {
id: string
name: string
description: string
tags: string[]
examples?: string[]
inputModes?: string[]
outputModes?: string[]
}
export interface AgentCardSignature {
protected: string
signature: string
header?: Record<string, unknown>
}
export type SecurityScheme =
| { apiKeySecurityScheme: { location: 'header' | 'query' | 'cookie'; name: string; description?: string } }
| { httpAuthSecurityScheme: { scheme: string; bearerFormat?: string; description?: string } }
| { oauth2SecurityScheme: { flows: Record<string, unknown>; oauth2MetadataUrl?: string; description?: string } }
| { openIdConnectSecurityScheme: { openIdConnectUrl: string; description?: string } }
| { mtlsSecurityScheme: Record<string, never> }Bütünlük
Agent Card'lar açık web'den alındığından, v1.0 imzalamayı resmileştirir: Agent Card (signatures alanı ve varsayılan değerler hariç) RFC 8785 JSON Canonicalization ile kanonikleştirilir, ardından JWS olarak imzalanır. İstemciler bir Agent Card üzerinde işlem yapmadan önce kid/jku başlığı veya güvenilir bir anahtar deposu aracılığıyla en az bir imzayı doğrulamalıdır. Birden fazla imza, anahtar rotasyonunu destekler.
Agent Card HTTPS üzerinden /.well-known/agent-card.json adresinde sunun.
Her supportedInterfaces girişi erişilebilir ve bildirilen bağlamayı konuşuyor.
Skill'lerin zorunlu etiketleri ve net görev sınırları olan açıklamaları var.
Bildirilen yetenekler sunucuyla eşleşiyor — bildirilmemiş özellikler hata döndürmeli, bildirilenler çalışmalıdır.
securitySchemes nasıl kimlik doğrulanacağını açıklar; Agent Card hiçbir yerinde kimlik bilgisi görünmez.
Agent Card içeriği her değiştiğinde version artırılır.
OAuth 2.0, streaming, ve push bildirimlerine sahip bir müşteri destek agent'ı — tüm gerekli alanlar mevcut. Daha fazla desen örnek kütüphanesinde bulunur.
{
"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"
]
}
]
}SSS
Bir Agent Card incelemeyi geçip geçmeyeceğine karar veren sürüm değişiklikleri, keşif alanları, ve yayınlama ayrıntıları.
v1.0, url, preferredTransport, ve additionalInterfaces'i her girişin kendi url, protocolBinding, ve protocolVersion'ını bildirdiği tek bir sıralı supportedInterfaces dizisinde birleştirdi. supportsAuthenticatedExtendedCard, capabilities.extendedAgentCard'a taşındı, provider.name, provider.organization oldu, skill etiketleri zorunlu hale geldi, ve JWS Agent Card imzaları RFC 8785 kanonikleştirmesiyle resmileştirildi.
Hayır. Agent Card, bir agent için bir keşif belgesidir. Kimliği, arayüzleri, yetenekleri, skill'leri, modları, sağlayıcıyı, ve güvenlik meta verilerini özetlerken, tam bir API şeması ayrıntılı istek ve yanıt şekillerini tanımlar. Bir hizmet için README veya OpenAPI genel bakışının oynadığı rolü oynar: onu çağırıp çağırmayacağınıza ve nasıl çağıracağınıza karar vermeye yeterli.
name, description, supportedInterfaces, skills (etiketlerle), defaultInputModes, defaultOutputModes, capabilities, provider, ve güvenlik meta verileri. Yönlendirme sistemleri görevleri description'ınıza ve skill etiketlerinize göre eşleştirir, ardından gerçek çağrıyı planlamak için arayüzleri ve yetenekleri kullanır.
Yalnızca kimliği doğrulanmamış keşif için güvenli olan skill'leri yayınlayın. Daha zengin bir özel Agent Card gerekiyorsa, capabilities.extendedAgentCard'ı true olarak ayarlayın ve hassas skill'leri kimliği doğrulanmış GetExtendedAgentCard işlemi aracılığıyla açığa çıkarın.
well-known URI'de https://{alan-adiniz}/.well-known/agent-card.json, application/a2a+json içerik türüyle sunulur (application/json da pratikte çalışır). Daha eski uygulamalar ayrıca /.well-known/agent.json'ı kontrol ediyordu, bu yüzden geçiş sırasında her ikisini de yayınlamak pragmatik bir seçimdir.
Şemayı işe koşun
Hizmet ayrıntılarınızdan v1.0 şeklinde bir Agent Card oluşturun, veya hangi alanların dikkat gerektirdiğini tam olarak görmek için mevcut bir Agent Card'ı doğrulayıcıya yapıştırın.