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 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 específicas de los usuarios.
  • Comunicación de agente a agente: En un sistema multiagente, es posible que un agente deba 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 la 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á 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 = google_vertex_ai_reasoning_engine.my_engine.name
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.
  • 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 de FastAPI del agente. Las garantías de seguridad están determinadas por el código del agente receptor.

  • Frontend de confianza: La mayoría de los agentes del ADK predeterminados operan desde un frontend de confianza. El agente confía en los comandos del frontend, lo que le da al frontend 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 son de confianza si implementan su propia autenticación y autorización. El entorno de ejecución del agente solo proporciona un control de acceso general a la interfaz del agente.