Generatore di Agent Card per JSON A2A

Cosa crea un generatore di Agent Card per il tuo agente IA

Un Agent Card è la descrizione dell'interfaccia pubblica di un agente A2A. Prima che un altro agente possa decidere se chiamare il tuo servizio, ha bisogno di più di un URL: ha bisogno di un resoconto affidabile dello scopo dell'agente, del suo contratto tecnico, delle sue skill e dei suoi requisiti di accesso.

Questo generatore di Agent Card trasforma quei dettagli implementativi in JSON leggibile e conforme alla forma A2A v1.0, mantenendo il processo decisionale vicino al modulo. Usalo dopo aver costruito la logica principale dell'agente e prima di distribuirlo o pubblicarlo — il punto in cui un file JSON scritto a mano di solito si rompe.

Rendi il tuo agente rilevabile

Un Agent Card chiaro fornisce ai client A2A un punto di partenza affidabile: a chi appartiene l'agente, dove risiede, e quali binding di protocollo e versioni parla.

Descrivi un'interfaccia utilizzabile

Cattura l'interfaccia preferita, le modalità di contenuto, il comportamento di streaming e il supporto per le notifiche push di cui un altro agente ha bisogno prima di effettuare una chiamata.

Stabilisci le aspettative di accesso

Documenta se il servizio è pubblico, usa una chiave API, o richiede OAuth 2.0, così le integrazioni possono scegliere il flusso di autenticazione corretto — senza mai inserire una credenziale nella Agent Card.

Trasforma le skill in contratti chiari

Nomina il lavoro che il tuo agente può svolgere, aggiungi i tag richiesti da v1.0 più esempi utili, e rendi i suoi confini comprensibili a persone, marketplace e client IA.

Come funziona il Generatore di Agent Card

Dai dettagli del servizio a un Agent Card pubblicabile

Il Generatore di Agent Card trasforma i dettagli del servizio in un documento JSON chiaro e pubblicabile. Segui questo breve flusso di lavoro prima di inviare l'Agent Card in produzione.

1
Inizia dal servizio reale
Aggiungi l'endpoint A2A pubblico, il binding di protocollo, i dettagli del provider, la versione dell'agente, e i tipi di contenuto che il tuo server accetta e restituisce.
2
Definisci i confini di capacità e skill
Seleziona solo le capacità supportate dalla tua implementazione, poi descrivi una skill rappresentativa in un linguaggio semplice e specifico.
3
Rivedi il JSON generato
Usa l'anteprima live per individuare campi mancanti, URL segnaposto, o descrizioni che non riflettono accuratamente il servizio distribuito.
4
Convalida e pubblica
Fai passare la Agent Card nel validatore, poi posiziona il documento rivisto in /.well-known/agent-card.json sul dominio del tuo servizio.

Chi usa il Generatore di Agent Card

Pensato per chiunque crei, pubblichi o revisioni Agent Card

Il Generatore di Agent Card aiuta builder, team di piattaforma e revisori a creare metadati di agenti A2A coerenti senza partire da un file JSON vuoto.

Parti invece da un esempio

Sviluppatori IA e indipendenti

Sostituisci un agent-card.json scritto a mano con un punto di partenza completo e conforme alla specifica quando lanci un agente compatibile con A2A.

Prompt engineer e product manager

Redigi un documento di scoperta credibile a partire da una descrizione del servizio senza toccare la sintassi JSON, poi consegnalo all'ingegneria per la revisione.

Team di piattaforma e DevOps

Standardizza il modo in cui gli agenti interni descrivono endpoint, autenticazione e skill prima che entrino in un catalogo di agenti aziendale o in una pipeline CI.

Publisher di marketplace

Prepara metadati del provider, tag delle skill e dichiarazioni di sicurezza che revisori e sistemi di ranking possano effettivamente analizzare.

FAQ

Domande sul generatore di Agent Card

Sistema gli elementi essenziali prima che un client A2A trovi il tuo endpoint.

Cos'è un A2A Agent Card?

Un A2A Agent Card è un documento di scoperta JSON per un agente IA. Comunica identità, informazioni sul provider, interfacce supportate, capacità, skill, modalità di contenuto accettate, e requisiti di sicurezza ai potenziali client — l'equivalente agente-ad-agente di un README più una panoramica dell'API.

Perché usare un generatore di Agent Card invece di scrivere JSON a mano?

Le Agent Card scritte a mano spesso hanno campi obbligatori mancanti, nomi di campo precedenti a v1.0, o errori di sintassi. Il generatore produce la forma A2A v1.0 attuale — supportedInterfaces, provider.organization, tag delle skill obbligatori — e valida mentre digiti, così gli errori strutturali non raggiungono mai la produzione.

A quale versione A2A punta la Agent Card generata?

Il generatore emette la struttura A2A v1.0: un array ordinato supportedInterfaces con protocolBinding e protocolVersion per interfaccia, una version dell'agente di primo livello, e capabilities incluso extendedAgentCard. Le Agent Card con campi url o preferredTransport di primo livello sono precedenti a v1.0.

Il JSON generato necessita di revisione prima della produzione?

Sì. Il generatore crea un documento di partenza pratico, non un sostituto del tuo contratto distribuito. Conferma che endpoint, binding di protocollo, skill e autenticazione corrispondano al servizio che gli utenti raggiungeranno realmente.

Dove pubblico un Agent Card?

Pubblica il JSON rivisto sullo stesso dominio del tuo servizio A2A su https://tuo-dominio/.well-known/agent-card.json, il percorso well-known registrato dalla specifica A2A. Molte integrazioni più datate controllano anche /.well-known/agent.json, quindi servire entrambi è una strategia di transizione sicura.

Pronto a pubblicare

Torna al Generatore di Agent Card prima di pubblicare.

Completa i dettagli, rivedi il JSON generato, e usa la validazione live prima di pubblicare il tuo Agent Card.

Apri il Generatore di Agent Card Valida il JSON

Dal blog

Guide pratiche alla discovery A2A, scritte sulla specifica v1.0.

Tutti gli articoli

How-to

Gli articoli sono pubblicati in inglese.