Agents A2A

Guide d'exploitation : configurer, déployer et observer la passerelle. Ce que fait la capacité côté produit : guide produit ; l'appeler : guide développeur.

Objectif : faire passer le trafic entre agents (A2A v1.0) par la passerelle - sous un quota, un audit et une identité vérifiée - sans qu'elle termine le protocole. Disponible depuis 1.2.0 ; la vérification des cartes amont, la carte publiée re-signée, la délégation d'agent à agent et le registre sont prévus en 1.9.0.

Ce que fait la passerelle, et ce qu'elle ne fait pas. Elle route, authentifie, tient le tenant, compte, garde les cibles push, relaie sans tampon et audite sans contenu. Elle ne garde aucune tâche et ne délivre aucun webhook : c'est l'agent amont qui lie chaque tâche à l'identité qu'il reçoit - une exigence pour l'équipe de l'agent (un autre appelant doit recevoir « tâche introuvable »).

Déclarer un agent. Sa carte d'agent v1.0 est un contrat versionné en Git, listé dans contracts.a2a ; ses supportedInterfaces portent les adresses de la passerelle (JSONRPC, HTTP+JSON - gRPC refusé) ; x-flexway-a2a dit ce qui est à Flexway et n'est pas publié. L'amont est protocol: a2a et déclare token_exchange - refusé au chargement sinon. Chaque schéma de sécurité de la carte doit correspondre à un mécanisme configuré (openIdConnectSecurityScheme -> la découverte d'un émetteur de auth.issuers). Tant que la vérification des cartes amont n'est pas livrée (prévue en 1.9.0), verify: none est obligatoire : la carte de l'amont n'est pas vérifiée, et le diff le dit. Exemple complet : Agent A2A derrière la passerelle.

Quotas et flux. Écrire coûte (write), lire une tâche est gratuit (free : ni seau, ni quota de tenant) ; x-flexway-a2a.methods change la classe d'une méthode. SendStreamingMessage et SubscribeToTask prennent une place de max_streams (par appelant et par réplique) et durent au plus max_task_duration - au-delà, le flux se termine ; une tâche plus longue se suit par GetTask.

Notifications push. Fermé par défaut : sans agents.a2a.push.allowed_hosts, aucune. Avec : https seul, un nom de la liste (ou sous un *.domaine), jamais une adresse, sous aucune forme. La passerelle ne résout pas le nom : qu'un nom permis pointe ensuite vers l'intérieur reste à surveiller par l'agent qui délivre.

La carte publiée. GET <chemin de la première interface>/.well-known/agent-card.json : la carte déclarée sans x-flexway-a2a, anonyme, avec ETag. Donnez cette URL aux agents appelants. Non signée avant 1.9.0. La carte étendue est relayée, aux adresses de la passerelle, jamais en cache.

Vérifier.

• la carte publiée répond, sans x-flexway-a2a ;
• un SendMessage en JSON-RPC puis un GetTask en HTTP+JSON répondent, avec A2A-Version: 1.0 ;
• l'agent amont reçoit un jeton de son audience, jamais celui de l'appelant ;
• /config (administration) montre a2a.agents : liaisons, méthodes et classes ;
• flexway_a2a_calls_total compte par agent, méthode, liaison et issue.