Enregistrer un agent ADK personnalisé

Agent Registry vous permet d'enregistrer des agents personnalisés que vous créez avec l'Agent Development Kit (ADK) et que vous hébergez sur votre propre infrastructure, afin que d'autres développeurs et agents d'orchestration puissent les découvrir. En exposant une carte d'agent conforme au protocole Agent2Agent (A2A) et en enregistrant manuellement le point de terminaison de l'agent, vous rendez ses compétences A2A détectables dans le registre d'agents.

Avant de commencer

  1. Configurer le registre d'agents.

  2. Pour une configuration à projet unique, obtenez l'ID de projet du projet de gouvernance où le registre d'agents est activé. Si vous avez configuré une limite de gestion pour plusieurs projets, utilisez l'ID de votre projet de gestion pour la découverte et l'enregistrement à l'échelle de la limite, ou spécifiez l'ID d'un projet membre pour les opérations sur un seul projet.

  3. Pour utiliser les commandes de la Google Cloud CLI dans ce document, configurez votre environnement gcloud CLI.

Rôles requis

Pour obtenir les autorisations nécessaires pour enregistrer des agents ADK personnalisés dans Agent Registry, demandez à votre administrateur de vous accorder le rôle IAM Éditeur de l'API Agent Registry (roles/agentregistry.editor) sur le projet de gouvernance où Agent Registry est activé. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Le point de terminaison Agent Card

Pour que le registre d'agents puisse indexer les capacités de votre agent personnalisé, celui-ci doit exposer ses métadonnées et ses compétences A2A disponibles à l'aide du protocole Agent2Agent (A2A).

La spécification A2A exige que les agents diffusent une carte d'agent, qui est un document JSON décrivant l'identité et les outils de l'agent, à un point de terminaison spécifique, généralement /.well-known/agent-card.json.

Lorsque vous utilisez les plug-ins ou modules de serveur A2A spécifiques d'ADK pour enregistrer votre agent, le framework peut générer et diffuser automatiquement cette fiche d'agent en fonction de la définition Agent et de tools que vous fournissez dans votre code.

Enregistrer l'agent exposé

Une fois que vous avez déployé l'agent ADK dans votre environnement d'hébergement et qu'il diffuse correctement ses points de terminaison REST, demandez à Agent Registry de le découvrir.

Étant donné que les déploiements personnalisés nécessitent un enregistrement manuel, vous devez créer une ressource Service dans le registre. Enregistrez la fiche d'agent générée pour votre agent sous forme de fichier JSON local, par exemple agent-card.json.

Utilisez gcloud CLI pour enregistrer l'agent avec la commande gcloud agent-registry services create, en veillant à spécifier le type de spécification a2a-agent-card, puis importez votre fichier local à l'aide de l'option --agent-spec-content :

gcloud agent-registry services create AGENT_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=a2a-agent-card \
    --agent-spec-content=agent-card.json

La taille maximale du fichier de spécification est de 10 Ko.

Remplacez les éléments suivants :

  • AGENT_NAME : nom que vous souhaitez attribuer à votre agent, par exemple my-custom-agent.
  • PROJECT_ID : ID du projet.
  • LOCATION : emplacement ou région du registre.
  • DISPLAY_NAME : nom lisible par l'humain de votre agent.

Une fois la ressource Service créée, le registre d'agents analyse la carte d'agent, crée une ressource Agent en lecture seule et indexe les compétences A2A définies dans votre code Python ADK afin que d'autres développeurs puissent les rechercher.