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

Usa el registro manual para los agentes

Agent Registry te permite registrar de forma manual agentes de REST estándar y compatibles con A2A que se alojan fuera de Google Cloud, se ejecutan en entornos de ejecución no compatibles o se implementan en diferentes proyectos de Google Cloud . Si creas un recurso Service para estos agentes, harás que sus extremos y capacidades se puedan descubrir en todo tu ecosistema de IA.

Agent Registry usa un proyecto de administración central Google Cloud. En este documento, el término remoto se refiere a los agentes alojados fuera del proyecto de administración, como en proyectos de Google Cloud independientes, entornos locales o nubes externas, o que se ejecutan en entornos de ejecución no compatibles. Debido a que el registro automático solo descubre los recursos compatibles implementados en el proyecto de administración en el que está habilitado el Registro de agentes, debes registrar manualmente los agentes remotos en el registro del proyecto de administración.

Tipos de agentes y limitaciones

Puedes registrar manualmente dos tipos de agentes:

Agentes compatibles con A2A: Son agentes que implementan la especificación de Agent2Agent (A2A) con el tipo A2A_AGENT_CARD. El registro analiza su extremo de agent-card.json tarjeta de agente para indexar sus habilidades de A2A.
Agentes de REST estándar: Son agentes remotos que no implementan la especificación de A2A y usan el tipo NO_SPEC, como los agentes que exponen un extremo de API de REST.

El registro manual 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 de Agent Registry.

Antes de comenzar

Configura el Registro de agentes.
Obtén el ID del proyecto para el proyecto de administración en el que está habilitado el Registro de agentes.
Para usar los comandos de Google Cloud CLI en este documento, configura tu entorno de gcloud CLI.

Roles obligatorios

Para obtener los permisos que necesitas para registrar agentes de forma manual en el Registro de agentes, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto de administración en el que está habilitado el Registro de agentes:

Para registrar agentes en Agent Registry: Editor de la API de Agent Registry (roles/agentregistry.editor)
Para el registro entre proyectos, accede a los metadatos del agente en otro proyecto de Google Cloud : 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 o a la tarjeta del agente con URLs públicas estándar o si se autentican con credenciales preconfiguradas.

Registra un agente compatible con A2A

Si tu agente remoto implementa la especificación de 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, además, indexa las habilidades de A2A disponibles del agente para que se puedan descubrir.

Sigue estos pasos para registrar el agente:

Console

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

Ir al registro de agentes
En el selector de proyectos, selecciona el proyecto de Google Cloud en el que configuraste el Registro de agentes.
Selecciona la pestaña Agentes.
Haz clic en Agregar agente.
En el panel Detalles del agente, 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 Desde el 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 componente. Para obtener una asignación completa de las marcas a las colecciones de recursos, consulta [Recursos de servicio y recursos de descubrimiento](/agent-registry/data-model#service-resources).

Para registrar un agente A2A, guarda la tarjeta de agente como un archivo JSON local, por ejemplo, agent-card.json, y, luego, ejecuta el comando gcloud agent-registry services create:

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 especificación es de 10 KB.

Reemplaza lo siguiente:

AGENT_NAME: Es el ID que deseas asignar a tu agente, por ejemplo, my-support-agent. El ID debe tener entre 4 y 63 caracteres y solo puede contener letras minúsculas, números y guiones.
PROJECT_ID: Es el ID del proyecto.
REGION: Es 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 darle a tu agente, por ejemplo, Support Agent.

Terraform

El bloque de especificación que configures determina a qué colección de recursos pertenece tu componente. Para obtener una asignación completa de las especificaciones a las colecciones de recursos, consulta [Recursos de servicio y recursos de descubrimiento](/agent-registry/data-model#service-resources).

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 de 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({
      name               = "AGENT_NAME"
      description        = "A custom support agent registered using Terraform."
      version            = "1.0.0"
      capabilities       = {}
      defaultInputModes  = ["text/plain"]
      defaultOutputModes = ["text/plain"]
      supportedInterfaces = [
        {
          url             = "https://api.example.com/v1/agents/support"
          protocolBinding = "JSONRPC"
          protocolVersion = "1.0"
        }
      ]
      skills = [
        {
          id          = "customer_lookup"
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
          tags        = ["support", "customer"]
        }
      ]
    })
  }
}

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 ID único que deseas asignarle a tu agente, por ejemplo, my-support-agent. El ID debe tener entre 4 y 63 caracteres y solo puede contener letras minúsculas, números y guiones.
DISPLAY_NAME: Es el nombre legible por humanos que deseas darle a tu agente, por ejemplo, Support Agent.

Registra un agente de REST estándar

Los agentes de REST estándar se pueden detectar 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 implemente la especificación de A2A, crea un recurso Service que no sea de A2A. Agent Registry genera un recurso Agent de solo lectura para el agente que no es A2A en la colección agents, incluida su URL de extremo, de modo que los agentes de organización, otros agentes y Agent Gateway puedan descubrir el agente y conectarse a él.

Si configuras el tipo de agente como No A2A en la consola de Google Cloud o usas la marca --agent-spec-type=no-spec en los comandos de gcloud CLI, se registra un agente de IA. No registres ese agente por separado como un recurso Endpoint. Solo registra un recurso Endpoint cuando quieras controlar las conexiones de salida del agente a una API de REST o un servicio web que no sea de agente, como una API de base de datos, una API de SaaS de terceros o las APIs de Google. Para obtener instrucciones sobre cómo registrar destinos de API que no sean de agentes, consulta Registra extremos.

Sigue estos pasos para registrar el agente:

Console

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

Ir al registro de agentes
En el selector de proyectos, selecciona el proyecto de Google Cloud en el que configuraste el Registro de agentes.
Selecciona la pestaña Agentes.
Haz clic en Agregar agente.
En el panel Detalles del agente, ingresa los siguientes detalles:
- Tipo: Selecciona No 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.
- Extremo: Ingresa el extremo en el que se aloja el agente.
Haz clic en Guardar.

gcloud

Para registrar un agente de REST estándar y especificar la URL del extremo en la que se aloja el agente, ejecuta el comando gcloud agent-registry services create con --agent-spec-type=no-spec y la marca --interfaces:

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: Es el ID que deseas asignar a tu agente, por ejemplo, my-remote-rest-agent. El ID debe tener entre 4 y 63 caracteres y solo puede contener letras minúsculas, números y guiones.
PROJECT_ID: Es el ID del proyecto.
REGION: Es la región del registro.
DISPLAY_NAME: Es el nombre legible por humanos que deseas darle a tu agente, por ejemplo, Remote REST Agent.
ENDPOINT_URL: Es la URL del extremo de API del agente, por ejemplo, https://api.example.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 ID único que deseas asignarle a tu agente, por ejemplo, my-remote-rest-agent. El ID debe tener entre 4 y 63 caracteres y solo puede contener letras minúsculas, números y guiones.
DISPLAY_NAME: Es el nombre legible por humanos que deseas darle a tu agente, por ejemplo, Remote REST Agent.
ENDPOINT_URL: Es la URL del extremo de API del agente, por ejemplo, https://api.example.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 Cloud y usa una Agent Gateway central en el modo de salida de agente a cualquier lugar para controlar el tráfico, debes registrar de forma manual cada agente remoto de esos otros proyectos de Google Cloud en el registro del proyecto de administración central. Para obtener más información sobre esta arquitectura, consulta Patrones de implementación de muestra.

Consideraciones para el registro entre proyectos

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

Ubicaciones compatibles: La instancia de Agent Registry, la Agent Gateway y los extremos de agente deben residir en la misma región geográfica o en la ubicación global.
Limitación de 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 borran automáticamente cuando se producen cambios en el otro proyecto deGoogle Cloud en el que se ejecuta el agente. 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 salida de agente a cualquier destino. 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 un agente remoto

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

Console

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

Ir al registro de agentes
En el selector de proyectos, elige el proyecto de administración central en el que quieres registrar el agente.
Selecciona la pestaña Agentes.
Haz clic en Agregar agente.
En el panel Detalles del agente, ingresa los siguientes detalles:
- Tipo: Selecciona A2A si el agente remoto implementa el protocolo A2A o No A2A para un extremo de REST estándar.
- Región: Selecciona la región que coincida con la implementación de la puerta de enlace central y el agente remoto.
Proporciona el extremo del agente:
- Para los agentes A2A, selecciona Desde el 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.
- Para los agentes que no son A2A, ingresa la URL del Extremo del agente remoto.
Haz clic en Guardar.

gcloud

Agente A2A: Para registrar un agente A2A de otro proyecto, ejecuta el comando gcloud agent-registry services create:

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 comando gcloud agent-registry services create:

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 ID de tu agente en el registro central, por ejemplo, remote-support-agent. El ID debe tener entre 4 y 63 caracteres, y solo puede contener letras minúsculas, números y guiones.
CENTRAL_PROJECT_ID: el ID del proyecto de administración central.
REGION: la región en la que registras el agente y en la que residen la puerta de enlace central y el agente remoto, por ejemplo, us-central1.
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 remoto que se ejecuta en el otro proyecto de Google Cloud , por ejemplo, https://remote-support-agent-abc123.us-central1.run.app o https://api.example.com/v1/agents/support.
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 AGENT_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: el ID del proyecto de administración central.
REGION: la región en la que registras el agente y en la que residen la puerta de enlace central y el agente remoto, por ejemplo, us-central1.
AGENT_NAME: Es el ID único de tu agente en el registro, por ejemplo, remote-support-agent. El ID debe tener entre 4 y 63 caracteres y solo puede contener letras minúsculas, números y guiones.
DISPLAY_NAME: Es el nombre legible por humanos del agente, por ejemplo, Remote Support Agent.
AGENT_PROJECT_ID: Es el ID del proyecto independiente Google Cloud en el que se aloja el agente remoto.
REMOTE_ENDPOINT_URL: Es la URL del extremo del agente remoto que se ejecuta en el otro proyecto de Google Cloud , por ejemplo, https://remote-support-agent-abc123.us-central1.run.app o https://api.example.com/v1/agents/support.
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 recurso Service y haya creado el recurso Agent de solo lectura correspondiente:

Console

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

Ir al registro de agentes
En el selector de proyectos, selecciona el proyecto de Google Cloud en el que configuraste el Registro de agentes.
Selecciona la pestaña Agentes.

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

gcloud

Enumera los agentes registrados en tu registro con el comando gcloud agent-registry agents list:

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

Si tienes varios agentes o si deseas confirmar el registro de un solo agente, 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: Es el ID del proyecto.
REGION: Es 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 de agente (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 legible por humanos del agente.

¿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 entornos de ejecución administrados.

Usa el registro manual para los agentes Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Tipos de agentes y limitaciones

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 un agente remoto

Console

gcloud

Terraform

Verifica el registro

Console

gcloud

Terraform

¿Qué sigue?

Usa el registro manual para los agentes