Cómo usar el registro manual

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

Antes de comenzar

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

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

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 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 mediante roles personalizados o cualquier otro rol predefinido.

No necesitas permisos adicionales si se puede acceder al extremo o a la tarjeta de agente 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 Agent2Agent (A2A), dirige Agent Registry a la carga útil agent-card.json del agente. El registro sincroniza automáticamente la tarjeta de agente y, luego, indexa las habilidades A2A disponibles del agente para su descubrimiento.

Sigue estos pasos para registrar el agente:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ve a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. Selecciona la pestaña Agentes.

  4. Haz clic en Agregar agente.

  5. 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.

  6. Elige una de las siguientes opciones:

    • Para registrar el agente con su URI de recurso, selecciona la pestaña Desde URI y, luego, ingresa una URL válida en el campo URI. Luego, haz clic en Importar para obtener la tarjeta de agente de la URL.
    • Para copiar y pegar el contenido de la tarjeta de agente, selecciona la pestaña Pegar JSON y pega todo el contenido de tu archivo agent-card.json.

  7. Haz clic en Guardar.

gcloud

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

Reemplaza lo siguiente:

  • AGENT_NAME: El nombre que deseas asignarle 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 deseas usar una región específica, usa el valor global.
  • DISPLAY_NAME: El nombre legible que deseas asignarle a tu agente, por ejemplo, Support Agent.

Terraform

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 tu carga útil JSON de la 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: La región en la que registras el agente.
  • AGENT_NAME: El nombre único que deseas asignarle a tu agente, por ejemplo, my-support-agent.
  • DISPLAY_NAME: El nombre legible que deseas asignarle a tu agente, por ejemplo, Support Agent.

Registra un agente REST estándar

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

Si deseas registrar un agente remoto que no implementa la especificación A2A, como un extremo de API de REST o SaaS estándar, la API de Agent Registry crea un recurso Service sin especificación de protocolo de agente.

Sigue estos pasos para registrar el agente:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ve a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. Selecciona la pestaña Agentes.

  4. Haz clic en Agregar agente.

  5. En el panel Detalles del agente, ingresa los siguientes detalles:

    • Tipo: Selecciona Non-A2A.
    • Nombre: Ingresa un nombre visible legible 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.

  6. Haz clic en Guardar.

gcloud

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

Para registrar un agente 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 asignarle a tu agente, por ejemplo, my-remote-rest-agent.
  • PROJECT_ID: El ID del proyecto
  • REGION: La región del registro.
  • DISPLAY_NAME: El nombre legible que deseas asignarle a tu agente, por ejemplo, Remote REST Agent.
  • ENDPOINT_URL: La URL del extremo de API del agente, por ejemplo, https://api.remote-service.com/v1/agents/1234.
  • PROTOCOL: La vinculación de protocolo para el extremo. Los valores válidos son http-json, grpc o jsonrpc.

Terraform

Para registrar un agente 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 de 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: La región en la que registras el agente.
  • AGENT_NAME: El nombre único que deseas asignarle a tu agente, por ejemplo, my-remote-rest-agent.
  • DISPLAY_NAME: El nombre legible que deseas asignarle a tu agente, por ejemplo, Remote REST Agent.
  • ENDPOINT_URL: La URL del extremo de API del agente, por ejemplo, https://api.remote-service.com/v1/agents/1234.
  • PROTOCOL: La vinculación de 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 Google Cloud proyectos y usa una Agent Gateway central para controlar el tráfico de salida, puedes registrar agentes de proyectos de radios o de cargas de trabajo en el catálogo central de Agent Registry.

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

Consideraciones para el registro entre proyectos

Antes de registrar agentes en todos los proyectos, revisa lo siguiente:

  • Ubicaciones compatibles: La instancia de Agent Registry, la Agent Gateway y los extremos del agente deben residir en la misma región geográfica o la ubicación global.
  • Limitación de descubrimiento automático: No se admite el descubrimiento automático entre proyectos. Debes registrar de forma manual cada agente remoto.
  • Administración del ciclo de vida: Las entradas manuales en Agent Registry 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 agentes remotos.
  • Solo modo de salida: La administración entre proyectos con Agent Gateway solo se admite para las puertas de enlace de agente a cualquier lugar (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 de forma manual un agente de otro proyecto, sigue estos pasos:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ve a Agent Registry

  2. En el selector de proyectos, selecciona el proyecto de administración central Google Cloud en el que deseas registrar el agente.

  3. Selecciona la pestaña Agentes.

  4. Haz clic en Agregar agente.

  5. En el panel Detalles del agente, 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 tu puerta de enlace central y la implementación del agente remoto.

  6. 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.
    • Para los agentes que no son A2A, ingresa la URL del extremo del agente remoto.

  7. 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 REST: Para registrar un agente REST estándar de 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: El nombre de tu agente en el registro central, por ejemplo, remote-support-agent.
  • CENTRAL_PROJECT_ID: El ID del proyecto de administración central.
  • REGION: La región en la que registras el agente.
  • DISPLAY_NAME: El nombre legible para el agente, por ejemplo, Remote Support Agent.
  • REMOTE_ENDPOINT_URL: 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: La vinculación de 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: El ID del proyecto de administración central.
  • REGION: La región en la que registras el agente.
  • AGENT_NAME: El nombre único de tu agente en el registro, por ejemplo, remote-support-agent.
  • DISPLAY_NAME: El nombre legible para el agente, por ejemplo, Remote Support Agent.
  • REMOTE_PROJECT_ID: El ID del proyecto en el que se aloja el agente.
  • REMOTE_ENDPOINT_URL: La URL del extremo del agente que se ejecuta en el proyecto remoto.
  • PROTOCOL: La vinculación de 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 Agent Registry haya procesado correctamente el Service y creado el recurso Agent correspondiente:

Console

  1. En la Google Cloud consola, ve a Agent Registry:

    Ve a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. 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 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: El ID del proyecto
  • REGION: La región en la que deseas registrar el agente. Si no deseas usar una región específica, usa el valor global.
  • FILTER_EXPRESSION: 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 único global (URN), 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: La región del registro.
  • DISPLAY_NAME: El nombre visible legible del agente.

¿Qué sigue?