Cómo compartir un agente

En esta página, se describe cómo compartir un solo agente en tu proyecto otorgando permisos de Identity and Access Management (IAM) a usuarios o cuentas de servicio.

Para compartir un agente, debes otorgar el permiso aiplatform.reasoningEngines.query en el recurso de agente específico.

Cuándo compartir un agente

Compartir un agente permite que varios usuarios o sistemas automatizados consulten el agente. Entre las situaciones comunes para compartir un agente, se incluyen las siguientes:

  • Colaboración: Comparte un agente con otros miembros de tu equipo o de la organización para que lo usen en sus tareas.
  • Integración de aplicaciones: Otorga acceso a una cuenta de servicio para que una aplicación personalizada, como un chatbot interno o un portal de atención al cliente, pueda llamar al agente para controlar solicitudes de usuarios específicas.
  • Comunicación entre agentes: En un sistema multiagente, es posible que un agente necesite llamar a otro para obtener información o delegar una subtarea.
  • Acceso a la información: Proporciona a los usuarios acceso controlado a los datos a través de una interfaz conversacional sin otorgarles acceso directo a las fuentes de datos subyacentes. Por ejemplo, comparte un agente conectado a una base de conocimiento (como políticas de RR.HH. o documentación técnica) con todos los empleados.

Antes de comenzar

  1. Identifica el agente que deseas compartir. Necesitas el ID del proyecto y el ID del motor de razonamiento del agente.
  2. Identifica los usuarios o las cuentas de servicio a los que deseas otorgar acceso.

Paso 1: Crea un rol personalizado

Para seguir el principio de privilegio mínimo, crea un rol personalizado que contenga solo el permiso aiplatform.reasoningEngines.query.

gcloud

Para crear un rol personalizado en el proyecto, ejecuta el siguiente comando:

gcloud iam roles create ROLE_ID  --project=PROJECT_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

Como alternativa, para crear el rol para toda la organización, haz lo siguiente:

gcloud iam roles create ROLE_ID --organization=ORGANIZATION_ID \
  --title="ROLE_TITLE" \
  --description="ROLE_DESCRIPTION" \
  --permissions=aiplatform.reasoningEngines.query

Reemplaza lo siguiente:

  • ROLE_ID: El ID del rol, como agentUser.
  • ROLE_TITLE: Un título para el rol, como Agent Runtime user.
  • ROLE_DESCRIPTION: Una breve descripción del rol, como Allows querying agents.
  • PROJECT_ID: El ID del proyecto
  • ORGANIZATION_ID: El ID de organización.

Terraform

Para crear el rol personalizado con Terraform, usa el recurso google_project_iam_custom_role:

resource "google_project_iam_custom_role" "reasoning_engine_query" {
role_id     = "ROLE_ID"
title       = "ROLE_TITLE"
project     = "PROJECT_ID"
permissions = ["aiplatform.reasoningEngines.query"]
}

Reemplaza lo siguiente:

  • ROLE_ID: El ID del rol, como agentUser.
  • ROLE_TITLE: Un título para el rol, como Agent Runtime user.
  • PROJECT_ID: El ID del proyecto

El nombre del rol personalizado será projects/PROJECT_ID/roles/ROLE_ID o organizations/ORGANIZATION_ID/roles/ROLE_ID.

Paso 2: Otorga el rol en el agente

Una vez que se crea el rol, vincúlalo a un agente y especifica el usuario o la cuenta de servicio a los que se otorgará el permiso.

Python

Para otorgar el rol con Python, usa la biblioteca google-cloud-aiplatform:

from google.cloud.aiplatform_v1 import ReasoningEngineServiceClient
from google.api_core.client_options import ClientOptions

# Initialize the client
client = ReasoningEngineServiceClient(
  client_options=ClientOptions(api_endpoint="LOCATION-aiplatform.googleapis.com")
)

# Define the resource path
resource = "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID"

# Get the current IAM policy and add the new binding
policy = client.get_iam_policy(request={"resource": resource})
binding = policy.bindings.add()
binding.role = "projects/PROJECT_ID/roles/ROLE_ID"
binding.members.append("USER_OR_SA")

# Update the IAM policy on the resource
client.set_iam_policy(request={"resource": resource, "policy": policy})

Reemplaza lo siguiente:

  • LOCATION: La región en la que se implementa el agente, como us-central1.
  • PROJECT_ID: El ID del proyecto
  • REASONING_ENGINE_ID: El ID del motor de razonamiento del agente.
  • ROLE_ID: El ID del rol, como agentUser.
  • USER_OR_SA: El correo electrónico del usuario o la cuenta de servicio, como user:someone@example.com o serviceAccount:my-sa@my-project.iam.gserviceaccount.com.

Terraform

Para otorgar el rol con Terraform, usa el recurso google_vertex_ai_reasoning_engine_iam_member:

resource "google_vertex_ai_reasoning_engine_iam_member" "example" {
project          = "PROJECT_ID"
region           = "REGION"
reasoning_engine = "REASONING_ENGINE_ID"
role             = google_project_iam_custom_role.reasoning_engine_query.name
member           = "USER_OR_SA"
}

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto
  • REGION: La región
  • REASONING_ENGINE_ID: El ID del motor de razonamiento del agente.
  • USER_OR_SA: El usuario o la cuenta de servicio

Consideraciones de seguridad

Otorgar acceso al agente proporciona acceso directo para enviar mensajes al extremo del agente. Los controles de seguridad se determinan según el código del agente receptor.

  • Frontend de confianza: La mayoría de los agentes predeterminados del Kit de desarrollo de agentes (ADK) operan desde un frontend de confianza. El agente confía en los comandos del frontend, lo que le otorga al frontend el control total de las sesiones y los usuarios. En estos casos, no otorgues acceso directo al agente a entidades que no sean de confianza.
  • Agentes A2A: Otros agentes, como los agentes Agent2Agent (A2A), pueden exponerse a entidades que no sean de confianza si implementan su propia autenticación y autorización. Agent Runtime solo proporciona un control de acceso general a la interfaz del agente.

¿Qué sigue?