Cómo usar el registro manual

Necesitas registrar manualmente en Agent Registry los agentes alojados fuera deGoogle Cloud o que se ejecutan en tiempos de ejecución no compatibles. En este documento, se muestra cómo registrar agentes de forma manual en Agent Registry.

Antes de comenzar

Antes de comenzar, configura el registro de agentes. 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 el rol de IAM Editor de la API de Agent Registry (roles/agentregistry.editor) 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 a través de roles personalizados o cualquier otro rol predefinido.

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 disponibles del agente para su descubrimiento.

Sigue estos pasos para registrar el agente:

Console

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

    Ir a Agent Registry

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

  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 del agente desde la URL.
    • Para copiar y pegar el contenido de la tarjeta del 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 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: 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 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 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 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 que se puedan buscar, a menos que adopten el protocolo A2A.

Si deseas registrar un agente remoto que no implementa la especificación de 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 del agente.

Sigue estos pasos para registrar el agente:

Console

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

    Ir a Agent Registry

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

  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.
    • Endpoint: Ingresa el extremo en el que se aloja el agente.

  6. Haz clic en Guardar.

gcloud

De forma 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 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 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 el tipo agent_spec establecido en 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 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.

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

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

    Ir a Agent Registry

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

  3. Selecciona la pestaña Agentes.

    La página debe mostrar 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 quieres 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: 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 (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 en lenguaje natural.

¿Qué sigue?