AgentCard

Un manifest autodescrittivo per un agente. Fornisce metadati essenziali, tra cui l'identità, le funzionalità, le competenze, i metodi di comunicazione supportati e i requisiti di sicurezza dell'agente. ID successivo: 20

Rappresentazione JSON 
{
  "name": string,
  "description": string,
  "supportedInterfaces": [
    {
      object (AgentInterface)
    }
  ],
  "provider": {
    object (AgentProvider)
  },
  "version": string,
  "capabilities": {
    object (AgentCapabilities)
  },
  "securitySchemes": {
    string: {
      object (SecurityScheme)
    },
    ...
  },
  "securityRequirements": [
    {
      object (SecurityRequirement)
    }
  ],
  "defaultInputModes": [
    string
  ],
  "defaultOutputModes": [
    string
  ],
  "skills": [
    {
      object (AgentSkill)
    }
  ],
  "signatures": [
    {
      object (AgentCardSignature)
    }
  ],
  "documentationUrl": string,
  "iconUrl": string
}
Campi
name

string

Obbligatorio. Un nome leggibile per l'agente. Esempio: "Agente di ricette"
description

string

Obbligatorio. Una descrizione dell'agente leggibile da una persona, che aiuta gli utenti e gli altri agenti a comprenderne lo scopo. Esempio: "Agente che aiuta gli utenti con ricette e cucina".
supportedInterfaces[]

object (AgentInterface)

Obbligatorio. Elenco ordinato delle interfacce supportate. Viene preferita la prima voce.
provider

object (AgentProvider)

Il fornitore di servizi dell'agente.
version

string

Obbligatorio. La versione dell'agente. Esempio: "1.0.0"
capabilities

object (AgentCapabilities)

Obbligatorio. Set di funzionalità A2A supportato dall'agente.
securitySchemes

map (key: string, value: object (SecurityScheme))

I dettagli dello schema di sicurezza utilizzati per l'autenticazione con questo agente.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
securityRequirements[]

object (SecurityRequirement)

Requisiti di sicurezza per contattare l'agente.
defaultInputModes[]

string

Obbligatorio. protolint:enable REPEATED_FIELD_NAMES_PLURALIZED L'insieme delle modalità di interazione supportate dall'agente in tutte le skill. Questa impostazione può essere ignorata per ogni skill. Definiti come tipi di media.
defaultOutputModes[]

string

Obbligatorio. I tipi di contenuti multimediali supportati come output da questo agente.
skills[]

object (AgentSkill)

Obbligatorio. Le skill rappresentano le capacità di un agente. Si tratta in gran parte di un concetto descrittivo, ma rappresenta un insieme più mirato di comportamenti in cui l'agente ha maggiori probabilità di riuscire.
signatures[]

object (AgentCardSignature)

Firme web JSON calcolate per questo AgentCard.
documentationUrl

string

Un URL che fornisce documentazione aggiuntiva sull'agente.
iconUrl

string

Facoltativo. Un URL a un'icona per l'agente.

AgentInterface

Dichiara una combinazione di URL di destinazione, trasporto e versione del protocollo per l'interazione con l'agente. Ciò consente agli agenti di esporre la stessa funzionalità su più meccanismi di binding del protocollo.

Rappresentazione JSON 
{
  "url": string,
  "protocolBinding": string,
  "tenant": string,
  "protocolVersion": string
}
Campi
url

string

Obbligatorio. L'URL in cui è disponibile questa interfaccia. Deve essere un URL HTTPS assoluto valido nell'ambiente di produzione. Esempio: "https://api.example.com/a2a/v1", "https://grpc.example.com/a2a"
protocolBinding

string

Obbligatorio. Il binding del protocollo supportato a questo URL. Si tratta di una stringa di formato aperto, facilmente estendibile per altri binding di protocollo. Quelli principali supportati ufficialmente sono JSONRPC, GRPC e HTTP+JSON.
tenant

string

Facoltativo. Una stringa opaca utilizzata per indirizzare le richieste a un agente o un tenant specifico quando più agenti vengono serviti dietro un singolo endpoint A2A. Se impostato, i client DEVONO includere questo valore nel campo tenant di tutti i messaggi di richiesta inviati a questa interfaccia. Il server è responsabile dell'interpretazione del valore e dell'instradamento delle richieste di conseguenza; il protocollo non definisce il formato o la semantica.
protocolVersion

string

Obbligatorio. La versione del protocollo A2A esposta da questa interfaccia. Utilizza l'ultima versione secondaria supportata per ogni versione principale. Esempi: "0.3", "1.0"

AgentProvider

Rappresenta il fornitore di servizi di un agente.

Rappresentazione JSON 
{
  "url": string,
  "organization": string
}
Campi
url

string

Obbligatorio. Un URL per il sito web del fornitore dell'agente o la documentazione pertinente. Esempio: "https://ai.google.dev"
organization

string

Obbligatorio. Il nome dell'organizzazione del fornitore dell'agente. Esempio: "Google"

AgentCapabilities

Definisce le funzionalità facoltative supportate da un agente.

Rappresentazione JSON 
{
  "extensions": [
    {
      object (AgentExtension)
    }
  ],
  "streaming": boolean,
  "pushNotifications": boolean,
  "extendedAgentCard": boolean
}
Campi
extensions[]

object (AgentExtension)

Un elenco delle estensioni del protocollo supportate dall'agente.
streaming

boolean

Indica se l'agente supporta le risposte in streaming.
pushNotifications

boolean

Indica se l'agente supporta l'invio di notifiche push per gli aggiornamenti delle attività asincrone.
extendedAgentCard

boolean

Indica se l'agente supporta la fornitura di una scheda dell'agente estesa dopo l'autenticazione.

AgentExtension

Una dichiarazione di un'estensione del protocollo supportata da un agente.

Rappresentazione JSON 
{
  "uri": string,
  "description": string,
  "required": boolean,
  "params": {
    object
  }
}
Campi
uri

string

L'URI univoco che identifica l'estensione.
description

string

Una descrizione leggibile di come questo agente utilizza l'estensione.
required

boolean

Se il valore è vero, il client deve comprendere e rispettare i requisiti dell'estensione.
params

object (Struct format)

Facoltativo. Parametri di configurazione specifici dell'estensione.

SecurityScheme

Definisce uno schema di sicurezza che può essere utilizzato per proteggere gli endpoint di un agente. Si tratta di un tipo di unione discriminata basato sull'oggetto schema di sicurezza OpenAPI 3.2. Vedi: https://spec.openapis.org/oas/v3.2.0.html#security-scheme-object

Rappresentazione JSON 
{

  // Union field scheme can be only one of the following:
  "apiKeySecurityScheme": {
    object (APIKeySecurityScheme)
  },
  "httpAuthSecurityScheme": {
    object (HTTPAuthSecurityScheme)
  },
  "oauth2SecurityScheme": {
    object (OAuth2SecurityScheme)
  },
  "openIdConnectSecurityScheme": {
    object (OpenIdConnectSecurityScheme)
  },
  "mtlsSecurityScheme": {
    object (MutualTlsSecurityScheme)
  }
  // End of list of possible types for union field scheme.
}
Campi

Campo unione scheme.

scheme può essere solo uno dei seguenti tipi:
apiKeySecurityScheme

object (APIKeySecurityScheme)

Autenticazione basata su chiave API.
httpAuthSecurityScheme

object (HTTPAuthSecurityScheme)

Autenticazione HTTP (Basic, Bearer e così via).
oauth2SecurityScheme

object (OAuth2SecurityScheme)

Autenticazione OAuth 2.0.
openIdConnectSecurityScheme

object (OpenIdConnectSecurityScheme)

Autenticazione OpenID Connect.
mtlsSecurityScheme

object (MutualTlsSecurityScheme)

Autenticazione TLS reciproca.

APIKeySecurityScheme

Definisce uno schema di sicurezza utilizzando una chiave API.

Rappresentazione JSON 
{
  "description": string,
  "location": string,
  "name": string
}
Campi
description

string

Una descrizione facoltativa dello schema di sicurezza.
location

string

Obbligatorio. La posizione della chiave API. I valori validi sono "query", "header" o "cookie".
name

string

Obbligatorio. Il nome del parametro di intestazione, query o cookie da utilizzare.

HTTPAuthSecurityScheme

Definisce uno schema di sicurezza utilizzando l'autenticazione HTTP.

Rappresentazione JSON 
{
  "description": string,
  "scheme": string,
  "bearerFormat": string
}
Campi
description

string

Una descrizione facoltativa dello schema di sicurezza.
scheme

string

Obbligatorio. Il nome dello schema di autenticazione HTTP da utilizzare nell'intestazione Authorization, come definito in RFC7235 (ad es. "Bearer"). Questo valore deve essere registrato nel registro degli schemi di autenticazione IANA.
bearerFormat

string

Un suggerimento al client per identificare il formato del token di autenticazione (ad es. "JWT"). Principalmente a scopo di documentazione.

OAuth2SecurityScheme

Definisce uno schema di sicurezza utilizzando OAuth 2.0.

Rappresentazione JSON 
{
  "description": string,
  "flows": {
    object (OAuthFlows)
  },
  "oauth2MetadataUrl": string
}
Campi
description

string

Una descrizione facoltativa dello schema di sicurezza.
flows

object (OAuthFlows)

Obbligatorio. Un oggetto contenente le informazioni di configurazione per i flussi OAuth 2.0 supportati.
oauth2MetadataUrl

string

URL dei metadati del server di autorizzazione OAuth2 RFC 8414. TLS è obbligatorio.

OAuthFlows

Definisce la configurazione per i flussi OAuth 2.0 supportati.

Rappresentazione JSON 
{

  // Union field flow can be only one of the following:
  "authorizationCode": {
    object (AuthorizationCodeOAuthFlow)
  },
  "clientCredentials": {
    object (ClientCredentialsOAuthFlow)
  },
  "implicit": {
    object (ImplicitOAuthFlow)
  },
  "password": {
    object (PasswordOAuthFlow)
  },
  "deviceCode": {
    object (DeviceCodeOAuthFlow)
  }
  // End of list of possible types for union field flow.
}
Campi

Campo unione flow.

flow può essere solo uno dei seguenti tipi:
authorizationCode

object (AuthorizationCodeOAuthFlow)

Configurazione per il flusso del codice di autorizzazione OAuth.
clientCredentials

object (ClientCredentialsOAuthFlow)

Configurazione per il flusso delle credenziali client OAuth.
implicit
(deprecated)

object (ImplicitOAuthFlow)

Obsoleto: utilizza invece il codice di autorizzazione + PKCE.
password
(deprecated)

object (PasswordOAuthFlow)

Obsoleto: utilizza il codice di autorizzazione + PKCE o il codice dispositivo.
deviceCode

object (DeviceCodeOAuthFlow)

Configurazione del flusso del codice dispositivo OAuth.

AuthorizationCodeOAuthFlow

Definisce i dettagli di configurazione per il flusso del codice di autorizzazione OAuth 2.0.

Rappresentazione JSON 
{
  "authorizationUrl": string,
  "tokenUrl": string,
  "refreshUrl": string,
  "scopes": {
    string: string,
    ...
  },
  "pkceRequired": boolean
}
Campi
authorizationUrl

string

Obbligatorio. L'URL di autorizzazione da utilizzare per questo flusso.
tokenUrl

string

Obbligatorio. L'URL del token da utilizzare per questo flusso.
refreshUrl

string

L'URL da utilizzare per ottenere i token di aggiornamento.
scopes

map (key: string, value: string)

Obbligatorio. Gli ambiti disponibili per lo schema di sicurezza OAuth2.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
pkceRequired

boolean

Indica se per questo flusso è richiesto PKCE (RFC 7636). PKCE deve essere sempre utilizzato per i client pubblici ed è consigliato per tutti i client.

ClientCredentialsOAuthFlow

Definisce i dettagli di configurazione per il flusso delle credenziali client OAuth 2.0.

Rappresentazione JSON 
{
  "tokenUrl": string,
  "refreshUrl": string,
  "scopes": {
    string: string,
    ...
  }
}
Campi
tokenUrl

string

Obbligatorio. L'URL del token da utilizzare per questo flusso.
refreshUrl

string

L'URL da utilizzare per ottenere i token di aggiornamento.
scopes

map (key: string, value: string)

Obbligatorio. Gli ambiti disponibili per lo schema di sicurezza OAuth2.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

ImplicitOAuthFlow

Obsoleto: utilizza invece il codice di autorizzazione + PKCE.

Rappresentazione JSON 
{
  "authorizationUrl": string,
  "refreshUrl": string,
  "scopes": {
    string: string,
    ...
  }
}
Campi
authorizationUrl

string

L'URL di autorizzazione da utilizzare per questo flusso. DEVE essere nel formato di un URL. Lo standard OAuth2 richiede l'utilizzo di TLS
refreshUrl

string

L'URL da utilizzare per ottenere i token di aggiornamento. DEVE essere nel formato di un URL. Lo standard OAuth2 richiede l'utilizzo di TLS.
scopes

map (key: string, value: string)

Gli ambiti disponibili per lo schema di sicurezza OAuth2. Una mappatura tra il nome dell'ambito e una breve descrizione. La mappa POTREBBE essere vuota.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

PasswordOAuthFlow

Obsoleto: utilizza il codice di autorizzazione + PKCE o il codice dispositivo.

Rappresentazione JSON 
{
  "tokenUrl": string,
  "refreshUrl": string,
  "scopes": {
    string: string,
    ...
  }
}
Campi
tokenUrl

string

L'URL del token da utilizzare per questo flusso. DEVE essere nel formato di un URL. Lo standard OAuth2 richiede l'utilizzo di TLS.
refreshUrl

string

L'URL da utilizzare per ottenere i token di aggiornamento. DEVE essere nel formato di un URL. Lo standard OAuth2 richiede l'utilizzo di TLS.
scopes

map (key: string, value: string)

Gli ambiti disponibili per lo schema di sicurezza OAuth2. Una mappatura tra il nome dell'ambito e una breve descrizione. La mappa POTREBBE essere vuota.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

DeviceCodeOAuthFlow

Definisce i dettagli di configurazione per il flusso del codice dispositivo OAuth 2.0 (RFC 8628). Questo flusso è progettato per dispositivi con limitazioni di input come i dispositivi IoT e gli strumenti CLI in cui l'utente esegue l'autenticazione su un dispositivo separato.

Rappresentazione JSON 
{
  "deviceAuthorizationUrl": string,
  "tokenUrl": string,
  "refreshUrl": string,
  "scopes": {
    string: string,
    ...
  }
}
Campi
deviceAuthorizationUrl

string

Obbligatorio. L'URL dell'endpoint di autorizzazione del dispositivo.
tokenUrl

string

Obbligatorio. L'URL del token da utilizzare per questo flusso.
refreshUrl

string

L'URL da utilizzare per ottenere i token di aggiornamento.
scopes

map (key: string, value: string)

Obbligatorio. Gli ambiti disponibili per lo schema di sicurezza OAuth2.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

OpenIdConnectSecurityScheme

Definisce uno schema di sicurezza utilizzando OpenID Connect.

Rappresentazione JSON 
{
  "description": string,
  "openIdConnectUrl": string
}
Campi
description

string

Una descrizione facoltativa dello schema di sicurezza.
openIdConnectUrl

string

Obbligatorio. L'URL Discovery OpenID Connect per i metadati del provider OIDC.

MutualTlsSecurityScheme

Definisce uno schema di sicurezza utilizzando l'autenticazione mTLS.

Rappresentazione JSON 
{
  "description": string
}
Campi
description

string

Una descrizione facoltativa dello schema di sicurezza.

SecurityRequirement

Definisce i requisiti di sicurezza per un agente.

Rappresentazione JSON 
{
  "schemes": {
    string: {
      object (StringList)
    },
    ...
  }
}
Campi
schemes

map (key: string, value: object (StringList))

Una mappatura degli schemi di sicurezza agli ambiti richiesti.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

StringList

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED A list of strings.

Rappresentazione JSON 
{
  "list": [
    string
  ]
}
Campi
list[]

string

I singoli valori di stringa.

AgentSkill

Rappresenta una funzionalità o una funzione distinta che un agente può eseguire.

Rappresentazione JSON 
{
  "id": string,
  "name": string,
  "description": string,
  "tags": [
    string
  ],
  "examples": [
    string
  ],
  "inputModes": [
    string
  ],
  "outputModes": [
    string
  ],
  "securityRequirements": [
    {
      object (SecurityRequirement)
    }
  ]
}
Campi
id

string

Obbligatorio. Un identificatore univoco per la competenza dell'agente.
name

string

Obbligatorio. Un nome leggibile per la competenza.
description

string

Obbligatorio. Una descrizione dettagliata della skill.
tags[]

string

Obbligatorio. Un insieme di parole chiave che descrivono le funzionalità della skill.
examples[]

string

Esempi di prompt o scenari che questa skill può gestire.
inputModes[]

string

Il set di tipi di contenuti multimediali di input supportati per questa skill, che sostituisce i valori predefiniti dell'agente.
outputModes[]

string

L'insieme dei tipi di contenuti multimediali di output supportati per questa skill, che sostituiscono i valori predefiniti dell'agente.
securityRequirements[]

object (SecurityRequirement)

Schemi di sicurezza necessari per questa skill.

AgentCardSignature

AgentCardSignature rappresenta una firma JWS di una scheda dell'agente. Segue il formato JSON di una firma web JSON (JWS) RFC 7515.

Rappresentazione JSON 
{
  "protected": string,
  "signature": string,
  "header": {
    object
  }
}
Campi
protected

string

Obbligatorio. Obbligatorio. L'intestazione JWS protetta per la firma. Si tratta sempre di un oggetto JSON con codifica base64url.
signature

string

Obbligatorio. La firma calcolata, con codifica base64url.
header

object (Struct format)

I valori dell'intestazione JWS non protetta.