Utiliser l'enregistrement automatique

Agent Registry peut enregistrer des agents hébergés sur desGoogle Cloud runtimes compatibles sans que vous ayez à appeler manuellement l'API Agent Registry. Selon l'environnement d'exécution, ce processus d'enregistrement se produit automatiquement ou nécessite une étape de configuration d'activation lors du déploiement.

Ce document explique comment activer la découverte pour les agents sur les runtimes compatibles. Si vous hébergez un agent en externe ou sur un environnement d'exécution non compatible, consultez Utiliser l'enregistrement manuel.

Les métadonnées et les capacités indexées pour un agent lors de l'enregistrement dépendent de l'implémentation ou non du protocole Agent2Agent (A2A) par l'agent. Pour en savoir plus, consultez Enregistrer des agents.

Avant de commencer

Avant d'enregistrer des agents, configurez le registre d'agents. Vous avez besoin de l'ID de votre projet pour valider l'enregistrement.

Pour utiliser les commandes Google Cloud CLI de ce document, assurez-vous d'avoir configuré votre environnement gcloud CLI.

Enregistrer des agents à partir d'Agent Runtime

Si vous développez et déployez des agents avec Agent Runtime sur Gemini Enterprise Agent Platform, l'enregistrement dans Agent Registry est automatique.

Le protocole Agent2Agent (A2A) est une norme ouverte qui permet aux agents de déclarer leurs capacités et leur identité. L'exemple suivant montre comment déployer un agent implémentant le protocole A2A sur Agent Runtime. Pour en savoir plus, consultez Déployer un agent.

# Create and deploy the agent
# This action automatically registers the agent in Agent Registry
remote_agent = client.agent_engines.create(
    agent=my_a2a_agent, # Your defined A2A object
    config={
        "display_name": "my-support-agent",
        "description": "An agent that handles support tickets.",
        "requirements": ["google-cloud-aiplatform[agent_engines,langchain]"],
    },
)

Lorsque vous mettez à jour ou supprimez votre agent dans Agent Runtime, Agent Registry synchronise automatiquement ces modifications.

Enregistrer les agents Google intégrés

Les agents Google intégrés, tels que les agents Google Workspace et Gemini Enterprise, sont automatiquement enregistrés dans le registre des agents. Vous n'avez pas besoin d'effectuer d'étapes de configuration ni de déploiement. Ces agents sont ingérés et disponibles pour la découverte dans votre registre.

Enregistrer des agents à partir de GKE

Vous pouvez enregistrer les agents déployés sur Google Kubernetes Engine (GKE) en ajoutant le libellé registry.gke.io/functional-type: "AGENT" à vos déploiements. Ce libellé identifie le déploiement comme une charge de travail d'agent d'IA, ce qui indique au contrôleur d'exécution du cluster GKE d'effectuer une analyse d'introspection dans le cluster et d'enregistrer l'agent auprès du registre d'agents.

Pour activer la découverte automatique des compétences de l'agent, vous devez également fournir l'annotation a2a-protocol.org/agent-card. Le contrôleur d'ingestion GKE utilise cette annotation pour interroger la carte d'agent A2A.

L'exemple suivant montre un fichier manifeste de déploiement de l'agent GKE utilisant ces configurations. Pour en savoir plus, consultez Déployer et orchestrer des agents d'IA.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
  labels:
    # GKE takes this label and registers the agent to Agent Registry
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  selector:
    matchLabels:
      app: my-agent
  template:
    metadata:
      labels:
        app: my-agent
    spec:
      containers:
      - name: server
        image: gcr.io/my-project/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
apiVersion: v1
kind: Service
metadata:
  name: my-agent-service
  labels:
    app: my-agent
spec:
  type: ClusterIP
  ports:
  - port: 8080
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: my-agent

Lorsque le déploiement est appliqué, le contrôleur d'exécution du cluster GKE inspecte automatiquement le conteneur de charge de travail, interroge le point de terminaison de la fiche de l'agent déclaré dans l'annotation, puis synchronise les métadonnées et les compétences A2A de l'agent directement dans le modèle de données de l'Agent Registry.

Enregistrer des agents depuis Cloud Run

Vous pouvez enregistrer les agents déployés sur Cloud Run en spécifiant les indicateurs --functional-type=agent et --identity-type=agent-identity lors du déploiement. L'indicateur --functional-type=agent identifie la charge de travail Cloud Run comme un agent d'IA plutôt que comme une application conteneurisée standard, ce qui indique à Cloud Run d'enregistrer l'agent auprès d'Agent Registry.

Les charges de travail configurées avec --functional-type=agent doivent spécifier l'option --identity-type=agent-identity. Le déploiement avec tout autre type d'identité entraîne une erreur.

Vous pouvez déployer des agents en tant que services ou jobs Cloud Run. Pour savoir comment déployer un agent en tant que service ou job dans Cloud Run, consultez Configurer les fonctionnalités d'Agent Platform pour Cloud Run.

Lors de l'enregistrement, Cloud Run ajoute automatiquement le nom et le type de l'agent (AGENT) au registre. Pour en savoir plus sur le déploiement d'agents A2A sur Cloud Run, consultez Déployer des agents A2A sur Cloud Run.

L'enregistrement automatique ne détecte que les ressources déployées dans le même projetGoogle Cloud . Pour enregistrer des agents déployés dans différents projets, consultez la section Enregistrement manuel.

Valider l'enregistrement

Vous pouvez vérifier que le registre d'agents a bien enregistré vos agents en les listant :

Console

  1. Dans la console Google Cloud , accédez à Agent Registry :

    Accéder au registre d'agents

  2. Dans le sélecteur de projets, sélectionnez le projet Google Cloud dans lequel vous avez configuré Agent Registry.

  3. Sélectionnez l'onglet Agents.

    La page affiche la liste de tous les agents enregistrés et leurs détails, tels que le nom, l'identifiant, la description, le runtime et l'emplacement.

  4. Filtrez la liste par emplacement de l'agent ou par ressource d'exécution :

    • Pour filtrer par zone géographique, cliquez sur le menu Zone géographique, sélectionnez les zones géographiques à filtrer, puis cliquez sur Appliquer.
    • Pour filtrer par durée, cliquez sur le menu Durée, sélectionnez les durées que vous souhaitez filtrer, puis cliquez sur Appliquer.

    La page affiche une liste filtrée des agents enregistrés pour les conditions que vous avez sélectionnées.

gcloud

Vous pouvez filtrer la liste par métadonnées de l'agent. Assurez-vous d'avoir configuré votre environnement Google Cloud CLI pour Agent Registry, puis exécutez la commande suivante :

gcloud agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet.
  • REGION : région du registre.
  • FILTER_EXPRESSION : expression de filtre pour les agents que vous souhaitez filtrer. Par exemple, pour filtrer par nom à afficher, vous pouvez utiliser displayName='DISPLAY_NAME'. Pour filtrer par identifiant (URN) unique au niveau mondial, vous pouvez utiliser agentId='urn:agent:AGENT_URN'.

Les agents Google intégrés utilisent un format URN qui dépend de l'emplacement où l'agent est déployé. Par exemple, vous pouvez découvrir les agents Google Workspace intégrés en filtrant votre liste sur l'éditeur googleapis.com à l'aide de --filter="agentId:'urn:agent:googleapis.com:*'".

Terraform

Référencez votre agent enregistré dans d'autres configurations Terraform à l'aide de la source de données google_agent_registry_agent :

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}

Remplacez les éléments suivants :

  • REGION : région du registre.
  • DISPLAY_NAME : nom à afficher de l'agent, lisible par l'humain.