Utiliser l'enregistrement automatique

Agent Registry peut enregistrer des agents hébergés sur desenvironnements d'exécution pris en charge Google Cloud sans que vous ayez à appeler manuellement l'API Agent Registry. Selon l'environnement d'exécution, ce processus d'enregistrement est automatique ou nécessite une étape de configuration d'activation lors du déploiement.

Ce document explique comment activer la détection des agents sur les environnements d'exécution pris en charge. Si vous hébergez un agent en externe ou sur un environnement d'exécution non pris en charge, consultez Utiliser l'enregistrement manuel.

Les métadonnées et les compétences extraites d'un agent lors de son enregistrement dépendent du protocole de l'agent. Pour en savoir plus, consultez Enregistrer des agents.

Avant de commencer

Avant d'enregistrer des agents, configurez Agent Registry. 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 dans 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 des agents Google intégrés

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

Enregistrer des agents à partir de GKE

Vous pouvez enregistrer des agents déployés sur Google Kubernetes Engine (GKE) en ajoutant l'étiquette registry.gke.io/functional-type: "AGENT" à vos déploiements. Cette étiquette identifie le déploiement comme un agent d'IA, ce qui permet à Agent Registry d'effectuer une analyse d'introspection.

Pour activer la détection automatisée des compétences de l'agent, vous devez également fournir l'annotation a2a-protocol.org/agent-card. Le contrôleur d'ingestion utilise cette annotation pour interroger la carte d'agent A2A. De plus, configurez Workload Identity à l'aide de l'annotation iam.gke.io/spiffe-identity-type: agent-identity pour faciliter la communication authentifiée sécurisée.

L'exemple suivant montre un fichier manifeste de déploiement d'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:
      annotations:
        # Workload Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
      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 cluster GKE tente automatiquement d'extraire les métadonnées de l'agent et les synchronise directement dans le modèle de données Agent Registry.

Valider l'enregistrement

Vous pouvez vérifier qu'Agent Registry a bien enregistré vos agents en les listant :

Console

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

    Accéder à Agent Registry

  2. Dans le sélecteur de projets, sélectionnez le Google Cloud projet 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, l'environnement d'exécution et l'emplacement.

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

    • Pour filtrer par emplacement, cliquez sur le menu Emplacement, sélectionnez les emplacements que vous souhaitez filtrer, puis cliquez sur Appliquer.
    • Pour filtrer par environnement d'exécution, cliquez sur le menu Environnement d'exécution, sélectionnez les environnements d'exécution que vous souhaitez filtrer, puis cliquez sur Appliquer.

    La page affiche une liste filtrée des agents enregistrés pour les conditions 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 l' identifiant unique global (URN), vous pouvez utiliser agentId='urn:agent:AGENT_URN'.

Les agents Google intégrés utilisent un format URN qui dépend de l'endroit où l'agent est déployé. Par exemple, vous pouvez découvrir les agents Google Workspace intégrés en filtrant votre liste pour 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 lisible de l'agent.