Agents A2A

Scrydon prend en charge le protocole Agent2Agent (A2A) dans les deux sens :

• Publier un workflow en tant qu'agent A2A autonome.
• Utiliser le bloc A2A pour découvrir et appeler un agent externe.

Les interfaces A2A 1.0 prises en charge sont JSON-RPC et HTTP+JSON, y compris le streaming via SSE. Une compatibilité A2A 0.3 facultative est disponible pour les clients et agents existants. Scrydon n'annonce ni ne revendique la prise en charge de l'interface gRPC.

Publier un workflow en tant qu'agent

Chaque publication de workflow correspond à un agent A2A adressable indépendamment. Une organisation peut publier autant de workflows qu'elle le souhaite ; chacun reçoit son propre identifiant d'agent stable, sa propre Agent Card, son espace de noms de tâches, sa visibilité et sa version de déploiement épinglée.

Le panneau Deployments contient une seule section Agent endpoints par workflow — et non une par environnement. Un champ Serves environment dans la configuration A2A permet de choisir l'environnement dont le déploiement l'agent exécutera (par défaut, l'environnement le plus avancé dans le pipeline ; le brouillon de développement peut être sélectionné explicitement). Les agents publiés apparaissent sous forme de lignes dans Agent endpoints : A2A Agent · <visibilité> · serves <environnement>. Si aucun agent n'est encore publié, une ligne discrète avec un bouton Publish est affichée.

1. Ouvrez le workflow dans l'éditeur. Le workflow doit contenir un bloc Response activé.
2. Cliquez sur Deploy dans la barre d'outils de l'éditeur pour ouvrir le panneau Deployments. Le panneau affiche une progression verticale du pipeline — une ligne par environnement avec version, date, auteur et un bouton de promotion.
3. Si aucun déploiement n'existe encore pour l'environnement cible, cliquez sur le bouton Promote sur la ligne de l'environnement concerné.
4. Faites défiler jusqu'à la section Agent endpoints en bas du panneau et cliquez sur Publish (ou cliquez sur une ligne d'agent A2A existante pour la reconfigurer).
5. Dans la configuration A2A, choisissez le champ Serves environment, configurez l'Agent Card de base (et, si nécessaire, une Agent Card étendue), et choisissez l'authentification par clé API et/ou jeton bearer.
6. Conservez la visibilité Privé par défaut, ou rendez explicitement l'agent public et découvrable.
7. Enregistrez, puis copiez l'URL de l'Agent Card ou du point de terminaison de protocole affichée dans la vue.

La publication épingle toujours un instantané de déploiement immuable. Modifier le canevas du workflow ne change pas l'agent en cours d'exécution. Promouvez une version plus récente et mettez à jour le déploiement épinglé dans la configuration A2A lorsque vous souhaitez republier.

Icônes d'agent

Scrydon génère automatiquement une icône monogramme unique pour chaque agent publié. Cette icône apparaît dans l'Agent Card renvoyée aux clients A2A externes. Des URL d'icônes personnalisées peuvent toujours être définies par programmation via l'API de publication (basicCard.iconUrl), mais ne font plus partie de l'interface utilisateur.

Visibilité

La visibilité publique rend la découverte publique ; elle ne rend pas publiques l'exécution du workflow ni les données des tâches. Une Agent Card étendue authentifiée n'est jamais renvoyée par la découverte publique.

Le catalogue public de l'organisation est paginé à l'adresse suivante :

GET /api/a2a/catalog/{organizationId}?pageSize=25&pageToken=...

Le panneau A2A authentifié répertorie également les publications de l'organisation dans tous les environnements, y compris les agents désactivés et privés.

Agent Cards et points de terminaison

La vue de configuration A2A fournit les URL suivantes :

La carte de base décrit le nom, la version, le fournisseur, la documentation, les types de médias, les compétences, les mécanismes de sécurité, les interfaces et les capacités de l'agent. Activez la carte étendue lorsque les appelants authentifiés ont besoin d'une description plus riche que celle qui doit être exposée par la découverte publique.

Les cartes sont signées avec ES256 et incluent l'URL de leur ensemble JWK. Les cartes publiques prennent en charge ETag, Last-Modified et la revalidation du cache. Les cartes privées utilisent un cache privé avec no-store.

Authentification et isolation des tâches

Activez au moins un mécanisme d'authentification pour la publication :

• Clé API : envoyez la clé d'espace de travail liée à l'environnement dans X-API-Key.
• Bearer : envoyez un jeton OAuth/OIDC dans Authorization: Bearer …. Les opérations de lecture nécessitent workflows:read ; les mutations et l'exécution nécessitent workflows:write.

Chaque tâche est limitée à la publication et au principal authentifié. Un autre principal, une autre organisation, un autre espace de travail ou un autre environnement reçoit la même réponse « introuvable » que pour une tâche inexistante. Les identifiants de tâches ne peuvent donc pas servir à énumérer le travail d'un autre appelant.

Appeler l'agent

Chaque requête de protocole doit envoyer la version annoncée par l'interface sélectionnée :

curl -X POST 'https://scrydon.example/api/a2a/agents/AGENT_ID' \
  -H 'A2A-Version: 1.0' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_WORKSPACE_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": "request-1",
    "method": "SendMessage",
    "params": {
      "message": {
        "role": "ROLE_USER",
        "messageId": "message-1",
        "parts": [{ "text": "Create the quarterly summary", "mediaType": "text/plain" }]
      }
    }
  }'

L'appel HTTP+JSON équivalent utilise la même URL de base du protocole :

curl -X POST 'https://scrydon.example/api/a2a/agents/AGENT_ID/message:send' \
  -H 'A2A-Version: 1.0' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "messageId": "message-1",
      "parts": [{ "text": "Create the quarterly summary", "mediaType": "text/plain" }]
    }
  }'

SendMessage renvoie soit une tâche, soit un message direct de l'agent. Pour une tâche, interrogez GET /tasks/{taskId}, abonnez-vous avec POST /tasks/{taskId}:subscribe ou utilisez une configuration de notification push.

Prouver l'interopérabilité avec le SDK JavaScript officiel

Il s'agit du test indépendant le plus probant pour une publication privée : il découvre l'Agent Card, négocie une interface annoncée et envoie un message A2A 1.0 sans utiliser de cookie de session Scrydon.

1. Créez une clé API dans le même environnement d'espace de travail que la publication.
2. Copiez l'URL du protocole depuis la vue de configuration A2A.
3. Dans un répertoire vide, installez la version stable du SDK officiel :

bun add @a2a-js/sdk@1.0.0

4. Enregistrez le code suivant dans a2a-proof.mjs :

import { randomUUID } from "node:crypto";
import {
  Message,
  Role,
  SendMessageConfiguration,
  Task,
} from "@a2a-js/sdk";
import {
  ClientFactory,
  ClientFactoryOptions,
  DefaultAgentCardResolver,
  JsonRpcTransportFactory,
  RestTransportFactory,
} from "@a2a-js/sdk/client";

const agentUrl = process.env.A2A_AGENT_URL;
const apiKey = process.env.A2A_API_KEY;
if (!agentUrl || !apiKey) {
  throw new Error("Set A2A_AGENT_URL and A2A_API_KEY");
}

const authenticatedFetch = async (input, init) => {
  const original =
    input instanceof Request ? new Request(input, init) : new Request(input, init);
  const headers = new Headers(original.headers);
  headers.set("X-API-Key", apiKey);
  return fetch(new Request(original, { headers, redirect: "error" }));
};

const factory = new ClientFactory(
  ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
    cardResolver: new DefaultAgentCardResolver({
      fetchImpl: authenticatedFetch,
    }),
    transports: [
      new JsonRpcTransportFactory({ fetchImpl: authenticatedFetch }),
      new RestTransportFactory({ fetchImpl: authenticatedFetch }),
    ],
  }),
);

const client = await factory.createFromUrl(`${agentUrl.replace(/\/$/, "")}/`);
const card = await client.getAgentCard();
console.log(
  "Negotiated",
  client.protocolVersion,
  card.supportedInterfaces.map((item) => item.protocolBinding),
);

const result = await client.sendMessage({
  tenant: "",
  message: Message.fromJSON({
    messageId: randomUUID(),
    role: Role.ROLE_USER,
    parts: [
      {
        text: "Run the A2A interoperability proof",
        mediaType: "text/plain",
      },
    ],
  }),
  configuration: SendMessageConfiguration.fromJSON({
    acceptedOutputModes: ["application/json", "text/plain"],
    returnImmediately: false,
  }),
});

console.dir(
  "id" in result ? Task.toJSON(result) : Message.toJSON(result),
  { depth: null },
);

5. Exécutez-le :

A2A_AGENT_URL='https://scrydon.example/api/a2a/agents/AGENT_ID' \
A2A_API_KEY='YOUR_WORKSPACE_KEY' \
bun run a2a-proof.mjs

La première ligne doit indiquer le protocole 1.0 et les interfaces JSONRPC et HTTP+JSON annoncées. La valeur finale est soit une tâche A2A, soit un message direct de l'agent. Un workflow bloquant renvoie normalement une tâche dont l'état final est TASK_STATE_COMPLETED.

Invoquer des agents publiés depuis Cortex

Cortex peut découvrir et appeler directement les agents publiés par Scrydon. Il utilise l'espace de travail actif comme limite de découverte et l'environnement d'espace de travail actif comme limite d'appel ; il n'accepte pas d'URL A2A externes arbitraires.

1. Publiez un ou plusieurs workflows en tant qu'agents A2A Privés ou Publics. Les agents Désactivés sont exclus.
2. Dans Cortex, sélectionnez le même espace de travail. Les agents publiés pour n'importe quel environnement de cet espace de travail sont visibles.
3. Demandez à Cortex de trouver l'agent par son nom, sa description, sa compétence ou son étiquette et indiquez-lui l'action à effectuer. Par exemple :

Find the A2A agent named "Quarterly reporting" and ask it to create the Q2 summary.

4. Cortex exécute d'abord a2a_agent_search. Les agents appelables (servant l'environnement actif) apparaissent dans les résultats principaux. Les agents publiés pour d'autres environnements sont listés séparément sous elsewhere ; Cortex suggérera de changer d'environnement actif pour les atteindre.
5. Approuvez la confirmation a2a_agent_call. L'appel exécute le déploiement épinglé du workflow.
6. Consultez la tâche ou le message A2A renvoyé dans la conversation.

Cortex découvre les publications Privées et Publiques dans tous les environnements de l'espace de travail actif, car l'utilisateur connecté y est déjà autorisé. Seuls les agents dont la publication sert l'environnement d'espace de travail actif sont appelables ; les agents servant un environnement différent sont signalés mais ne peuvent pas être appelés tant que l'utilisateur n'a pas basculé vers cet environnement ou publié l'agent A2A du workflow pour l'environnement actuel depuis la feuille Déploiements du workflow. Cortex revalide l'identifiant d'agent sélectionné immédiatement avant chaque appel.

Opérations serveur prises en charge

Les deux interfaces utilisent les états de tâche, la pagination, le contrôle de l'historique, la continuation des messages, les artefacts, les paramètres de service, les extensions, les erreurs canoniques et les détails google.rpc.ErrorInfo d'A2A 1.0. Le streaming utilise text/event-stream et conserve l'enveloppe de réponse de l'interface.

Lorsque la compatibilité 0.3 est activée, l'Agent Card annonce également des interfaces JSON-RPC et HTTP+JSON compatibles et traduit les anciennes méthodes et charges utiles à l'aide du SDK officiel.

Entrée et sortie du workflow

Le workflow reçoit la requête normalisée sous a2a :

{
  "a2a": {
    "message": { "messageId": "message-1", "role": "ROLE_USER", "parts": [] },
    "configuration": {},
    "metadata": {}
  }
}

Le bloc Response sélectionné devient la réponse de l'agent :

• Une chaîne devient un message d'agent text/plain.
• Toute autre valeur JSON devient une partie de données application/json lorsque l'appelant l'accepte.
• Pour un contrôle complet, renvoyez { "a2a": { "message": ..., "artifacts": [...] } } comme données de la réponse.
• Un statut Response supérieur ou égal à 400 fait échouer la tâche sans exposer la sortie interne des nœuds.

Les pauses du workflow et les étapes de révision humaine sont projetées vers TASK_STATE_INPUT_REQUIRED. Continuez la même tâche en envoyant un autre message avec son taskId et le contextId correspondant. Les tâches terminales refusent les messages et abonnements ultérieurs avec l'erreur A2A canonique.

Les messages entrants et la sortie projetée passent par la politique DLP de l'organisation. L'exécution, l'annulation, les modifications de publication et de configuration push, ainsi que la livraison en lettre morte sont journalisées à des fins d'audit, sans corps de message ni identifiants.

Limites des charges utiles

Les parties de fichiers bruts sont transférées vers le stockage de fichiers d'exécution avant la planification durable et ne sont réhydratées que dans la portée autorisée de la tâche.

Notifications push

Les configurations push prennent en charge un jeton de rappel ou un mécanisme d'authentification avec ses identifiants. En production, les rappels doivent utiliser HTTPS. Scrydon résout et épingle les cibles DNS publiques, bloque les destinations privées, loopback, link-local et de métadonnées cloud, puis revalide les cibles de livraison afin d'empêcher le rebinding DNS.

La livraison conserve l'ordre par configuration, réessaie trois fois les échecs récupérables avec temporisation, puis marque la configuration comme lettre morte. Les secrets de rappel sont chiffrés au repos et n'apparaissent jamais dans les journaux d'audit.

Appeler des agents A2A externes

Ajoutez un bloc A2A à un workflow et choisissez l'une des mêmes opérations de découverte, de messagerie, de streaming, de tâche, d'abonnement, de push ou de carte étendue. Saisissez l'URL de base ou de protocole de l'agent ; Scrydon tente d'abord la découverte A2A 1.0 canonique, puis les emplacements de découverte 0.3 comme solutions de compatibilité.

L'authentification sortante prend en charge :

• les clés API dans un en-tête, un paramètre de requête ou un cookie ;
• HTTP Basic ;
• les jetons bearer ;
• les jetons d'accès OAuth 2.0 ;
• les jetons d'accès OpenID Connect.

Vous pouvez également exiger une Agent Card signée, définir un délai d'expiration de 100 ms à 300 s et envoyer des paramètres de service non réservés ainsi que des URI d'extension A2A. Le TLS mutuel est détecté et refusé avec une erreur d'authentification non prise en charge explicite.

En production, les appels sortants exigent HTTPS, sauf si l'opérateur active explicitement A2A_ALLOW_INSECURE_HTTP=true. Chaque URL de découverte, d'interface, de redirection et d'ensemble JWK est épinglée au DNS et contrôlée par rapport aux adresses privées et aux hôtes de métadonnées. Les identifiants et en-têtes de service personnalisés sont supprimés lors des redirections vers une autre origine.

Configuration opérateur

Les déploiements de production doivent configurer la signature des Agent Cards avec l'une des options suivantes :

• A2A_CARD_SIGNING_PRIVATE_JWKS : un ensemble JWK ou un tableau JSON. Cette option permet le chevauchement et la rotation des clés.
• A2A_CARD_SIGNING_PRIVATE_JWK : une seule clé JWK EC P-256 privée, pour la compatibilité.

Définissez A2A_CARD_SIGNING_KEY_ID pour sélectionner la clé privée active. Les clés marquées comme révoquées, expirées ou pas encore actives ne sont ni publiées ni sélectionnées. A2A_PAGE_TOKEN_SECRET peut être défini comme secret dédié d'au moins 32 caractères ; sinon, le secret d'authentification configuré pour la plateforme signe les jetons de page limités au catalogue et aux tâches.

Dépannage

Voir aussi

• Fournisseur Scrydon intégré
• Déclencheurs et environnements
• Exécution
• Gestion des secrets