Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Utiliser l'enregistrement automatique pour les agents

Le registre d'agents vous permet de configurer l'enregistrement automatique des agents sur les environnements d'exécution Google Cloud compatibles afin que les développeurs et les agents d'orchestration puissent les découvrir sans créer manuellement de ressources de registre. Selon l'environnement d'exécution, l'enregistrement s'effectue par défaut ou via une étape de déploiement d'activation, et les métadonnées indexées dépendent du protocole d'implémentation.

L'enregistrement automatique ne découvre que les ressources compatibles déployées dans le projet de gouvernance où Agent Registry est activé. Pour enregistrer des agents distants déployés dans d'autres projetsGoogle Cloud , consultez Enregistrer un agent depuis un autre projet. Pour les agents distants hébergés en externe ou sur des environnements d'exécution non compatibles, consultez Utiliser l'enregistrement manuel pour les agents.

Métadonnées indexées automatiquement

Les métadonnées et les fonctionnalités indexées pour un agent lors de l'enregistrement automatique dépendent de l'implémentation ou non du protocole Agent2Agent (A2A) par l'agent :

Agents implémentant le protocole A2A : Agent Registry interroge la fiche d'agent de l'agent pour extraire automatiquement ses compétences A2A et ses capacités annoncées dans Agent Registry./.well-known/agent-card.json
Agents n'implémentant pas le protocole A2A : Agent Registry enregistre l'agent, mais ne peut pas capturer automatiquement les métadonnées telles que l'URL du point de terminaison où l'agent est hébergé, l'identité de l'agent et les compétences A2A. Il s'agit d'agents qui exposent, par exemple, des points de terminaison REST ou gRPC standards. Pour associer des capacités à des agents non A2A, utilisez l'enregistrement manuel ou l'enregistrement des compétences.

Avant de commencer

Configurer le registre d'agents.
Obtenez l'ID du projet pour le projet de gouvernance dans lequel Agent Registry est activé.
Pour utiliser les commandes de la Google Cloud CLI dans ce document, configurez votre environnement gcloud CLI.

Enregistrer des agents depuis 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.

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 des 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 Agent Registry. Vous n'avez pas besoin d'effectuer d'étapes de configuration ou de déploiement. Ces agents sont ingérés et disponibles pour la découverte dans votre registre.

Enregistrer des agents depuis GKE

Pour enregistrer des agents déployés sur Google Kubernetes Engine (GKE), ajoutez les libellés et annotations Kubernetes requis à votre fichier manifeste de déploiement. L'exemple suivant montre un fichier manifeste GKE qui définit un objet Deployment Kubernetes et un objet Service Kubernetes configurés pour l'enregistrement automatique :

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
      annotations:
        # Agent Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
    spec:
      containers:
      - name: server
        image: gcr.io/PROJECT_ID/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
# Kubernetes Service for in-cluster network routing to the agent pod
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

Remplacez PROJECT_ID par l'ID du projet Google Cloud .

Pour configurer et appliquer le fichier manifeste de déploiement, procédez comme suit :

Dans metadata.labels de votre fichier manifeste Deployment, ajoutez l'étiquette registry.gke.io/functional-type: "AGENT". Cette étiquette identifie le déploiement en tant que charge de travail d'agent IA, ce qui indique au contrôleur d'exécution du cluster GKE d'inspecter la charge de travail et d'enregistrer l'agent auprès d'Agent Registry.

Remarque : GKE est également compatible avec l'annotation apphub.cloud.google.com/functional-type: "AGENT" pour assurer la rétrocompatibilité. Toutefois, utilisez l'étiquette registry.gke.io/functional-type: "AGENT" pour vos déploiements GKE.
Dans metadata.annotations de votre fichier manifeste Deployment, activez la découverte automatique des compétences A2A de l'agent en fournissant l'annotation a2a-protocol.org/agent-card. Le contrôleur d'ingestion GKE utilise cette annotation pour interroger la carte d'agent A2A.
Dans spec.template.metadata.annotations du modèle de pod, activez la communication authentifiée en configurant l'identité de l'agent avec l'annotation iam.gke.io/spiffe-identity-type: agent-identity.
Appliquez le fichier manifeste de déploiement à votre cluster. Pour en savoir plus, consultez Déployer et orchestrer des agents IA.

Lorsque vous appliquez le déploiement, le contrôleur d'exécution du cluster GKE inspecte automatiquement le conteneur de charge de travail et interroge le point de terminaison de la fiche d'agent déclaré dans l'annotation. Il synchronise ensuite les métadonnées de l'agent et les compétences A2A directement dans une ressource de découverte Agent en lecture seule dans Agent Registry.

Enregistrer des agents depuis Cloud Run

Vous pouvez enregistrer automatiquement des agents lorsque vous les déployez en tant que services ou jobs Cloud Run en spécifiant les options --functional-type=agent et --identity-type=agent-identity. L'option --functional-type=agent identifie le service ou le job Cloud Run comme un agent IA plutôt que comme une charge de travail conteneurisée standard, ce qui indique à Cloud Run d'enregistrer l'agent auprès d'Agent Registry. Lors de l'enregistrement, Cloud Run ajoute automatiquement le nom de l'agent et le type AGENT au registre.

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.

Pour configurer l'enregistrement automatique sur un service ou un job Cloud Run nouveau ou existant, consultez Configurer les fonctionnalités de Gemini Enterprise Agent Platform pour Cloud Run. Pour préparer, conteneuriser et déployer un agent compatible avec A2A sur Cloud Run, consultez Déployer des agents A2A sur Cloud Run.

Vérifier l'enregistrement

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

Console

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

Accéder au registre d'agents
Dans le sélecteur de projets, sélectionnez le projet Google Cloud dans lequel vous avez configuré le registre d'agents.
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.
Filtrez la liste par emplacement de l'agent ou par ressource 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 que vous avez sélectionnées.

gcloud

Vous pouvez filtrer la liste en fonction des métadonnées de l'agent. Assurez-vous d'avoir configuré votre environnement gcloud CLI pour Agent Registry, puis exécutez la commande gcloud agent-registry agents list :

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 d'agent unique (URN), vous pouvez utiliser agentId='urn:agent:AGENT_URN'.

Les agents Google intégrés utilisent un format d'identifiant d'agent (URN) qui dépend de l'emplacement de déploiement de l'agent. 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
}