Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Cómo usar el registro manual

Necesitas el registro manual en Agent Registry para los agentes alojados fuera deGoogle Cloud, que se ejecutan en tiempos de ejecución no admitidos o que se implementan en diferentes proyectos de Google Cloud . En este documento, se muestra cómo registrar agentes de forma manual en Agent Registry.

Advertencia: Esta función no se admite en las ubicaciones multirregionales us y eu. Debes usar una región admitida o la ubicación global. Para obtener más información, consulta Ubicaciones del Registro de agentes.

Antes de comenzar

Antes de comenzar, configura Agent Registry. Necesitarás el ID del proyecto para realizar estas tareas.

Para usar los comandos de Google Cloud CLI en este documento, asegúrate de configurar tu entorno de gcloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para registrar agentes de forma manual en Agent Registry, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

Para registrar agentes en Agent Registry, haz lo siguiente: Editor de la API de Agent Registry (roles/agentregistry.editor)
Para el registro entre proyectos, accede a los metadatos del agente en un proyecto remoto: Visualizador de la API de Agent Registry (roles/agentregistry.viewer)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

No necesitas permisos adicionales si se puede acceder al extremo del agente o a la tarjeta del agente con URLs públicas estándar o si se autentica a través de credenciales preconfiguradas.

Registra un agente compatible con A2A

Si tu agente remoto implementa la especificación de Agent2Agent (A2A), dirige el Registro de agentes a la carga útil agent-card.json del agente. El registro sincroniza automáticamente la tarjeta de agente y, luego, indexa las habilidades de A2A disponibles del agente para su descubrimiento.

Sigue estos pasos para registrar el agente:

Console

En la consola de Google Cloud , ve a Agent Registry:

Ir a Agent Registry
En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.
Selecciona la pestaña Agentes.
Haz clic en Agregar agente.
En el panel Agent details, ingresa los siguientes detalles:
- Tipo: Selecciona A2A.
- Región: Selecciona la ubicación geográfica en la que deseas registrar el agente.
Elige una de las siguientes opciones:
- Para registrar el agente con la URL de su tarjeta de agente, selecciona la pestaña From URI y, luego, ingresa una URL válida en el campo URI. Luego, haz clic en Importar para obtener la tarjeta del agente desde la URL.
- Para copiar y pegar el contenido de la tarjeta del agente, selecciona la pestaña Pegar JSON y pega el contenido completo de tu archivo agent-card.json.
Haz clic en Guardar.

gcloud

Las marcas de especificación que usas determinan a qué colección de recursos pertenece tu servicio. Para obtener una asignación completa de las marcas a las colecciones de recursos, consulta Recursos de la API.

Para registrar un agente A2A, guarda la tarjeta de agente del agente como un archivo JSON local, por ejemplo, agent-card.json, y haz lo siguiente:

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

El tamaño máximo del archivo de especificaciones es de 10 KB.

Reemplaza lo siguiente:

AGENT_NAME: El nombre que deseas darle a tu agente, por ejemplo, my-support-agent.
PROJECT_ID: El ID del proyecto
REGION: La región en la que deseas registrar el agente. Si no quieres usar una región específica, usa el valor global.
DISPLAY_NAME: Es el nombre legible por humanos que deseas asignarle a tu agente, por ejemplo, Support Agent.

Terraform

El bloque de especificación que configuras, por ejemplo, agent_spec, determina a qué colección de recursos pertenece tu servicio. Para obtener una asignación completa de las especificaciones a las colecciones de recursos, consulta Recursos de API.

Para registrar un agente compatible con A2A, configura el recurso google_agent_registry_service. Especifica el bloque agent_spec con el tipo A2A_AGENT_CARD y el content que representa la carga útil JSON de tu tarjeta de agente:

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type    = "A2A_AGENT_CARD"
    content = jsonencode({
      schemaVersion = "v1"
      displayName   = "DISPLAY_NAME"
      description   = "A custom support agent registered using Terraform."
      skills = [
        {
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

Reemplaza lo siguiente:

REGION: Es la región en la que registras el agente.
AGENT_NAME: Es el nombre único que deseas asignarle a tu agente, por ejemplo, my-support-agent.
DISPLAY_NAME: Es el nombre legible por humanos que deseas asignarle a tu agente, por ejemplo, Support Agent.

Registra un agente de REST estándar

Los agentes REST estándar son detectables por nombre y descripción, pero no tienen habilidades de A2A que se puedan buscar, a menos que adopten el protocolo A2A.

Para registrar un agente remoto que no implementa la especificación de A2A, crea un recurso Service configurado con --agent-spec-type=no-spec. Luego, Agent Registry genera un recurso Agent correspondiente en la colección agents.

Usar --agent-spec-type=no-spec registra un agente, no un destino de API objetivo. Si deseas registrar un destino de API externo al que se conectan los agentes, debes registrar un extremo. Para obtener instrucciones, consulta Cómo registrar extremos.

Sigue estos pasos para registrar el agente:

Console

En la consola de Google Cloud , ve a Agent Registry:

Ir a Agent Registry
En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.
Selecciona la pestaña Agentes.
Haz clic en Agregar agente.
En el panel Agent details, ingresa los siguientes detalles:
- Tipo: Selecciona Non-A2A.
- Nombre: Ingresa un nombre visible legible por humanos para tu agente, como Travel Agent.
- Descripción: Ingresa una descripción de las capacidades del agente, como A test agent that plans travel itineraries..
- Región: Selecciona la ubicación geográfica en la que deseas registrar el agente.
- Endpoint: Ingresa el extremo en el que se aloja el agente.
Haz clic en Guardar.

gcloud

De manera opcional, puedes proporcionar la interfaz del extremo HTTP/JSON definida con la marca --interfaces para que el registro establezca una conexión con el agente.

Para registrar un agente de REST estándar, haz lo siguiente:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

Reemplaza lo siguiente:

AGENT_NAME: El nombre que deseas darle a tu agente, por ejemplo, my-remote-rest-agent.
PROJECT_ID: El ID del proyecto
REGION: Es la región del registro.
DISPLAY_NAME: Es el nombre legible por humanos que deseas asignarle a tu agente, por ejemplo, Remote REST Agent.
ENDPOINT_URL: Es la URL del extremo de API del agente, por ejemplo, https://api.remote-service.com/v1/agents/1234.
PROTOCOL: Es la vinculación del protocolo para el extremo. Los valores válidos son http-json, grpc o jsonrpc.

Terraform

Para registrar un agente de REST estándar, configura el recurso google_agent_registry_service con agent_spec establecido en el tipo NO_SPEC y define las conexiones de la interfaz del extremo:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

Reemplaza lo siguiente:

REGION: Es la región en la que registras el agente.
AGENT_NAME: Es el nombre único que deseas asignarle a tu agente, por ejemplo, my-remote-rest-agent.
DISPLAY_NAME: Es el nombre legible por humanos que deseas asignarle a tu agente, por ejemplo, Remote REST Agent.
ENDPOINT_URL: Es la URL del extremo de API del agente, por ejemplo, https://api.remote-service.com/v1/agents/1234.
PROTOCOL: Es la vinculación del protocolo para el extremo. Los valores válidos son HTTP_JSON, GRPC o JSONRPC.

Registra un agente de otro proyecto

Si tu organización implementa agentes en varios proyectos de Google Cloudy usa unaAgent Gatewaycentral para controlar el tráfico de salida, puedes registrar agentes de proyectos de radios o cargas de trabajo en el catálogo central de Agent Registry.

Dado que el registro automático solo descubre los recursos creados en el mismo proyecto, debes registrar manualmente cada agente remoto en el registro del proyecto de administración central.

Consideraciones para el registro entre proyectos

Antes de registrar agentes en varios proyectos, revisa lo siguiente:

Ubicaciones compatibles: La instancia de Agent Registry, el Agent Gateway y los Agent Endpoints deben residir en la misma región geográfica o en la ubicación global.
Limitación del descubrimiento automático: No se admite el descubrimiento automático entre proyectos. Debes registrar manualmente cada agente remoto.
Administración del ciclo de vida: Las entradas manuales en el Registro de agentes no se actualizan ni se borran automáticamente cuando se producen cambios en el proyecto remoto. Debes administrar el ciclo de vida de estas entradas en el registro central cuando se modifican o quitan los agentes remotos.
Solo modo de salida: La administración entre proyectos con Agent Gateway solo se admite para las puertas de enlace de Agent-to-Anywhere (salida). Las puertas de enlace de entrada de cliente a agente requieren que el agente y la puerta de enlace estén en el mismo proyecto.

Registra el agente remoto

Para registrar manualmente un agente de otro proyecto, sigue estos pasos:

Console

En la consola de Google Cloud , ve a Agent Registry:

Ir a Agent Registry
En el selector de proyectos, selecciona el proyecto de administración central Google Clouden el que deseas registrar el agente.
Selecciona la pestaña Agentes.
Haz clic en Agregar agente.
En el panel Agent details, ingresa los siguientes detalles:
- Tipo: Selecciona A2A si el agente remoto implementa el protocolo A2A o Non-A2A para un extremo REST estándar.
- Región: Selecciona la región que coincida con la implementación de tu puerta de enlace central y tu agente remoto.
Proporciona el extremo del agente:
- Para los agentes A2A, selecciona Desde URI y, luego, ingresa la URL de la tarjeta de agente del agente remoto o selecciona Pegar JSON y pega el contenido de agent-card.json.
- En el caso de los agentes que no son de A2A, ingresa la URL del extremo del agente remoto.
Haz clic en Guardar.

gcloud

Agente A2A: Para registrar un agente A2A de otro proyecto con la gcloud CLI, ejecuta el siguiente comando en el proyecto de administración central:

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

Agente de REST: Para registrar un agente de REST estándar desde otro proyecto, ejecuta el siguiente comando en el proyecto de administración central:

gcloud agent-registry services create AGENT_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL

Reemplaza lo siguiente:

AGENT_NAME: Es el nombre de tu agente en el registro central, por ejemplo, remote-support-agent.
CENTRAL_PROJECT_ID: Es el ID del proyecto de administración central.
REGION: Es la región en la que registras el agente.
DISPLAY_NAME: Es el nombre legible por humanos del agente, por ejemplo, Remote Support Agent.
REMOTE_ENDPOINT_URL: Es la URL del extremo del agente que se ejecuta en el proyecto remoto, por ejemplo, https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app.
PROTOCOL: Es la vinculación del protocolo para el extremo. Los valores válidos son http-json, grpc o jsonrpc.

Terraform

Para registrar un agente remoto en un proyecto de administración central con Terraform, configura el recurso google_agent_registry_service y especifica el proyecto central:

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project REMOTE_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "REMOTE_ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.remote_agent.registry_resource
}

Reemplaza lo siguiente:

CENTRAL_PROJECT_ID: Es el ID del proyecto de administración central.
REGION: Es la región en la que registras el agente.
AGENT_NAME: Es el nombre único de tu agente en el registro, por ejemplo, remote-support-agent.
DISPLAY_NAME: Es el nombre legible por humanos del agente, por ejemplo, Remote Support Agent.
REMOTE_PROJECT_ID: Es el ID del proyecto en el que se aloja el agente.
REMOTE_ENDPOINT_URL: Es la URL del extremo del agente que se ejecuta en el proyecto remoto.
PROTOCOL: Es la vinculación del protocolo para el extremo. Los valores válidos son HTTP_JSON, GRPC o JSONRPC.

Verifica el registro

Después de registrar tu agente, verifica que el Registro de agentes haya procesado correctamente el Service y haya creado el recurso Agent correspondiente:

Console

En la consola de Google Cloud , ve a Agent Registry:

Ir a Agent Registry
En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.
Selecciona la pestaña Agentes.

En la página, se muestra una lista de todos los agentes registrados y sus detalles.

gcloud

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

Si tienes varios agentes o quieres confirmar el registro de uno solo, puedes filtrar la lista por los metadatos del agente:

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

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto
REGION: La región en la que deseas registrar el agente. Si no quieres usar una región específica, usa el valor global.
FILTER_EXPRESSION: Es la expresión de filtro para los agentes que deseas filtrar. Por ejemplo, para filtrar por nombre visible, puedes usar displayName='DISPLAY_NAME'. Para filtrar por el identificador (URN) único a nivel global, puedes usar agentId='urn:agent:AGENT_URN'.

Terraform

Haz referencia a tu agente registrado en otras configuraciones de Terraform con la fuente de datos 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
}

Reemplaza lo siguiente:

REGION: Es la región del registro.
DISPLAY_NAME: Es el nombre visible del agente legible por humanos.

¿Qué sigue?

Obtén más información para administrar agentes registrados.
Obtén más información sobre el registro automático, el método recomendado para registrar agentes implementados en tiempos de ejecución administrados.

Cómo usar el registro manual Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Roles obligatorios

Registra un agente compatible con A2A

Console

gcloud

Terraform

Registra un agente de REST estándar

Console

gcloud

Terraform

Registra un agente de otro proyecto

Consideraciones para el registro entre proyectos

Registra el agente remoto

Console

gcloud

Terraform

Verifica el registro

Console

gcloud

Terraform

¿Qué sigue?

Cómo usar el registro manual