En el Registro de agentes, las vinculaciones permiten que tus agentes de organización se conecten a agentes downstream, servidores de MCP y endpoints sin codificar de forma fija los detalles de conexión o autenticación en tu código. Puedes crear, ver, actualizar y borrar vinculaciones en el Registro de agentes para administrar las conexiones de recursos y los permisos delegados.
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.
Registra los componentes de origen y destino. Para obtener más información, consulta Modelos de registro.
Si deseas configurar vinculaciones para permisos delegados, crea un proveedor de autenticación con el administrador de autenticación de Agent Identity. Para obtener más información, consulta Autentica en herramientas y recursos.
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 administrar vinculaciones 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:
-
Crea, actualiza y borra vinculaciones:
Administrador de la API de Agent Registry (
roles/agentregistry.admin) -
Vinculaciones de vistas:
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.
Situaciones de vinculación
Puedes usar vinculaciones para conectar recursos y delegar permisos. Por ejemplo, puedes usar vinculaciones en las siguientes situaciones:
- Conexiones de recursos: Vinculan un agente de origen a un recurso de destino, como otro agente, un servidor de MCP o un extremo. Esta situación te permite planificar flujos de trabajo de varios agentes en los que un agente de organización principal delega tareas a herramientas o agentes secundarios especializados.
- Permisos delegados: asocia un agente a un proveedor de autenticación para permitir que tu agente se conecte a destinos externos o herramientas personalizadas con sus propias credenciales o en nombre de un usuario individual. Esta vinculación es obligatoria si tu agente necesita autenticarse en servidores de MCP o herramientas remotas con tokens de OAuth o claves de API. Con las vinculaciones, no tienes que definir manualmente los proveedores de autenticación en tu código. Para obtener instrucciones detalladas, consulta Crea una vinculación de proveedor de autenticación en este documento.
Crea una vinculación
Crea una vinculación para conectar un agente de origen a un recurso de destino:
gcloud
Ejecuta el comando gcloud agent-registry bindings create:
gcloud agent-registry bindings create BINDING_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--source-identifier="SOURCE_ID" \
--target-identifier="TARGET_ID"
Reemplaza lo siguiente:
BINDING_NAME: Es el nombre que deseas asignar a la vinculación, por ejemplo,my-custom-binding.PROJECT_ID: Es el ID del proyecto.REGION: Es la región del registro.DISPLAY_NAME: Es el nombre legible por humanos que deseas asignar a tu vinculación, por ejemplo,My Custom Binding.SOURCE_ID: Es el identificador del agente de origen en formato de nombre de recurso uniforme (URN).TARGET_ID: Es el identificador de registro del recurso de destino en formato URN, como un identificador de agente, un identificador de servidor de MCP o un identificador de extremo.
Terraform
Para crear una vinculación entre un agente de origen y un recurso de destino, configura un
recurso google_agent_registry_binding. Una vinculación requiere el bloque target:
resource "google_agent_registry_binding" "agent_binding" {
location = "REGION"
binding_id = "BINDING_NAME"
display_name = "DISPLAY_NAME"
description = "Connects a source agent to a target resource."
source {
identifier = "SOURCE_ID"
}
target {
identifier = "TARGET_ID"
}
}
Reemplaza lo siguiente:
REGION: Es la región del registro.BINDING_NAME: Es el nombre único que deseas asignar a la vinculación.DISPLAY_NAME: Es el nombre legible por humanos de la vinculación.SOURCE_ID: Es el identificador del agente de origen en formato URN.TARGET_ID: Es el identificador de registro del recurso de destino en formato URN.
Crea una vinculación de proveedor de autenticación
Puedes asociar un agente con un proveedor de autenticación para obtener permisos delegados. Antes de crear esta vinculación, primero debes crear el proveedor de autenticación con el administrador de autenticación. Para obtener más información, consulta Autentica en herramientas y recursos.
Cuando especifiques el nombre del recurso --auth-provider-binding, debes usar el ID del proyecto:
gcloud
Ejecuta el
comando gcloud agent-registry bindings create
con la marca --auth-provider-binding:
gcloud agent-registry bindings create BINDING_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--source-identifier="SOURCE_ID" \
--target-identifier="TARGET_ID" \
--auth-provider-binding="projects/PROJECT_ID/locations/REGION/authProviders/AUTH_PROVIDER_ID"
Reemplaza lo siguiente:
BINDING_NAME: Es el nombre único que deseas asignar a la vinculación.PROJECT_ID: Es el ID del proyecto.REGION: Es la región del registro.DISPLAY_NAME: Es el nombre legible por humanos de la vinculación.SOURCE_ID: Es el identificador del agente de origen en formato URN.TARGET_ID: Es el identificador de registro del recurso de destino en formato URN.AUTH_PROVIDER_ID: Es el ID de tu proveedor de autenticación.
Terraform
Para configurar una vinculación de proveedor de autenticación en Terraform, especifica el
bloque auth_provider_binding con el nombre del recurso de tu proveedor de autenticación,
junto con sus permisos y el URI de continuación:
resource "google_agent_registry_binding" "auth_binding" {
location = "REGION"
binding_id = "BINDING_NAME"
display_name = "DISPLAY_NAME"
source {
identifier = "SOURCE_ID"
}
target {
identifier = "TARGET_ID"
}
auth_provider_binding {
auth_provider = "projects/PROJECT_ID/locations/REGION/authProviders/AUTH_PROVIDER_ID"
scopes = [SCOPES]
continue_uri = "CONTINUE_URI"
}
}
Reemplaza lo siguiente:
REGION: Es la región del registro.BINDING_NAME: Es el nombre único que deseas asignar a la vinculación.DISPLAY_NAME: Es el nombre legible por humanos de la vinculación.SOURCE_ID: Es el identificador del agente de origen en formato URN.TARGET_ID: Es el identificador de registro del recurso de destino en formato URN.PROJECT_ID: Es el ID del proyecto.AUTH_PROVIDER_ID: Es el ID del proveedor de autenticación.SCOPES: Es una lista separada por comas de permisos de OAuth 2.0, por ejemplo,"https://www.googleapis.com/auth/cloud-platform".CONTINUE_URI: Es el URI de continuación del proveedor de autenticación, por ejemplo,https://example.com/continue.
Para ver ejemplos de cómo usar estas vinculaciones en el código de tu agente, consulta Resuelve vinculaciones en el código del Kit de desarrollo de agentes (ADK).
Mostrar lista de vinculaciones
Enumera todas las vinculaciones en una ubicación específica ejecutando el comando
gcloud agent-registry bindings list:
gcloud agent-registry bindings list \
--project=PROJECT_ID \
--location=REGION
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto.REGION: Es la región del registro.
Ver detalles de vinculación
Ejecuta el comando
gcloud agent-registry bindings describe
para recuperar los detalles de una sola vinculación:
gcloud agent-registry bindings describe BINDING_NAME \
--project=PROJECT_ID \
--location=REGION
Reemplaza lo siguiente:
BINDING_NAME: el nombre de la vinculación.PROJECT_ID: Es el ID del proyecto.REGION: Es la región del registro.
Actualiza una vinculación
Actualiza los parámetros de una vinculación existente, como su nombre visible o su descripción:
gcloud
Ejecuta el comando gcloud agent-registry bindings update:
gcloud agent-registry bindings update BINDING_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="NEW_DISPLAY_NAME"
Reemplaza lo siguiente:
BINDING_NAME: Es el nombre de la vinculación que deseas actualizar.PROJECT_ID: Es el ID del proyecto.REGION: Es la región del registro.NEW_DISPLAY_NAME: Es el nuevo nombre legible por humanos para la vinculación.
Terraform
Para actualizar el nombre visible o la descripción de una vinculación con Terraform, modifica
el recurso google_agent_registry_binding existente en tu configuración
y ejecuta terraform apply.
Borra una vinculación
Para quitar una conexión entre recursos, borra la vinculación:
gcloud
Ejecuta el comando gcloud agent-registry bindings delete:
gcloud agent-registry bindings delete BINDING_NAME \
--project=PROJECT_ID \
--location=REGION
Reemplaza lo siguiente:
BINDING_NAME: Es el nombre de la vinculación que quieres borrar.PROJECT_ID: Es el ID del proyecto.REGION: Es la región del registro.
Terraform
Quita el recurso google_agent_registry_binding que representa la vinculación
de tu configuración de Terraform y, luego, ejecuta terraform apply.
¿Qué sigue?
- Obtén información para autenticarte en herramientas y recursos con vinculaciones de proveedores de autenticación.
- Aprende a resolver endpoints y crear coordinadores con el ADK.