Autenticación para agentes de IA

A menudo, los agentes de inteligencia artificial necesitan autenticarse en otros recursos para completar tareas. Por ejemplo, un agente implementado podría necesitar acceder a un índice de búsqueda vectorial para consultar datos no estructurados, un punto de conexión de servicio para llamar a un modelo de base o funciones de Catálogo de Unity para ejecutar lógica personalizada.

En esta página se tratan los métodos de autenticación de los agentes implementados en Databricks Apps. Para los agentes implementados en los endpoints de Model Serving, consulte Autenticación para agentes de IA (Model Serving).

Databricks Apps proporciona dos métodos de autenticación para agentes. Cada método sirve diferentes casos de uso:

Puede combinar ambos métodos en un solo agente. Por ejemplo, use la autorización de la aplicación para acceder a un índice de búsqueda vectorial compartido mientras usa la autorización de usuario para consultar tablas específicas del usuario.

Autorización de la aplicación

De forma predeterminada, Las aplicaciones de Databricks se autentican mediante la autorización de la aplicación. Azure Databricks crea automáticamente una entidad de servicio al crear la aplicación y actúa como identidad de la aplicación.

Todos los usuarios que interactúan con la aplicación comparten los mismos permisos definidos para la entidad de servicio. Este modelo funciona bien cuando desea que todos los usuarios vean los mismos datos o cuando la aplicación realiza operaciones compartidas no vinculadas a controles de acceso específicos del usuario.

Para obtener información detallada sobre la autorización de la aplicación, consulte Autorización de aplicaciones.

Concesión de permisos al experimento de MLflow

El agente necesita acceso a un experimento de MLflow para registrar seguimientos y resultados de evaluación.

Conceda permiso a la entidad de servicio Can Edit del experimento de MLflow.

1. Haga clic en Editar en la página principal de la aplicación.
2. Vaya al paso Configurar .
3. En la sección Recursos de la aplicación, agregue el recurso del experimento de MLflow.

Consulte Incorporación de un recurso de experimento de MLflow a una aplicación de Databricks.

Concesión de permisos a otros recursos de Databricks

Si el agente utiliza otros recursos de Databricks, como espacios de Genie, índices de Vector Search o almacenes SQL, conceda permisos a la entidad de servicio a través de la interfaz de usuario de Databricks Apps. Consulte Incorporación de recursos a una aplicación de Databricks para obtener la lista completa de los recursos admitidos y las instrucciones de configuración.

Para acceder al registro de mensajes, conceda permisos en CREATE FUNCTION, EXECUTE y MANAGE en el esquema del Catálogo de Unity para almacenar mensajes.

En la tabla siguiente se enumeran los permisos mínimos necesarios para que los agentes accedan a recursos comunes de Databricks:

Al conceder acceso a los recursos del catálogo de Unity, también debe conceder permisos a todos los recursos dependientes de nivel inferior. Por ejemplo, si concede acceso a un espacio de Genie, también debe conceder acceso a sus tablas subyacentes, almacenes de SQL y funciones de catálogo de Unity.

El usuario que agrega el recurso debe tener el Can Manage permiso tanto en el recurso como en la aplicación. Para obtener la lista completa de los recursos admitidos y todos los permisos disponibles, consulte tipos de recursos admitidos.

Para conocer los procedimientos recomendados para administrar la autorización de aplicaciones de forma segura, incluidos los principios de administración de credenciales y privilegios mínimos, consulte Autorización de aplicaciones.

Autorización de usuario

La autorización de usuario permite a un agente actuar con la identidad del usuario que realiza la solicitud. Esto proporciona:

• Acceso por usuario a datos confidenciales
• Controles de datos granulares implementados por Unity Catalog
• Registros de auditoría específicos del usuario
• Aplicación automática de filtros a nivel de fila y enmascaramiento de columnas

Use la autorización de usuario cuando el agente necesite acceder a los recursos mediante la identidad del usuario solicitante en lugar de la entidad de servicio de la aplicación.

Funcionamiento de la autorización de usuario

Al configurar la autorización de usuario para el agente:

1. Agregar ámbitos de API a la aplicación: defina a qué API de Databricks puede acceder la aplicación en nombre de los usuarios. Consulte Agregar ámbitos a una aplicación.
2. Las credenciales de usuario están limitadas: Azure Databricks toma las credenciales del usuario y las restringe solo a los ámbitos de API definidos.
3. Reenvío de tokens: El token con ámbito reducido está disponible para tu aplicación a través del x-forwarded-access-token encabezado HTTP.
4. MLflow AgentServer almacena el token: el servidor del agente almacena automáticamente este token por solicitud para un acceso cómodo en el código del agente.

Configure la autorización de usuario mediante la adición de ámbitos en la interfaz de usuario de Databricks Apps al crear o editar la aplicación, o mediante programación mediante la API. Consulte Agregar ámbitos a una aplicación para obtener instrucciones detalladas.

Los agentes con autorización de usuario pueden acceder a los siguientes recursos de Databricks:

• SQL Warehouse
• Espacio de Genie
• Archivos y directorios
• Modelo de puntos de conexión de servicio
• Índice de búsqueda vectorial
• Conexiones de catálogo de Unity
• Tablas de catálogo de Unity

Implementación de la autorización de usuario

Para implementar la autorización de usuario, debe agregar ámbitos de autorización a la aplicación. Los ámbitos restringen lo que la aplicación puede hacer en nombre del usuario.

1. En la interfaz de usuario de Databricks, vaya a la configuración de autorización de Aplicaciones de Databricks.
2. Haga clic en +Agregar ámbito y seleccione los ámbitos a los que desea acceder a los recursos en nombre del usuario.
3. Guarde los cambios.

Para configurar la autorización de usuario en el código del agente, recupere el encabezado de esta solicitud desde AgentServer y construya un cliente de área de trabajo con esas credenciales.

1. En el código del agente, importe la utilidad de autenticación:

   Si usa una de las plantillas proporcionadas de databricks/app-templates, importe la utilidad proporcionada:

   from databricks_app.utils import get_user_workspace_client
   

   De lo contrario, importe desde las utilidades del servidor de agentes:

   from agent_server.utils import get_user_workspace_client
   

   La get_user_workspace_client() función usa el servidor del agente para capturar el x-forwarded-access-token encabezado y construye un cliente del área de trabajo con esas credenciales de usuario, controlando la autenticación entre el usuario, la aplicación y el servidor del agente.

2. Inicialice el cliente del área de trabajo en el momento de la consulta, no durante el inicio de la aplicación:

   Importante

   Llame a get_user_workspace_client() dentro de los controladores invoke y stream, no en __init__ ni al inicio de la aplicación. Las credenciales de usuario solo están disponibles en el momento de la consulta cuando un usuario realiza una solicitud. Se producirá un error al inicializar durante el inicio de la aplicación porque aún no existe ningún contexto de usuario.

   # In your agent code (inside invoke or stream handler)
   user_client = get_user_workspace_client()
   
   
   # Use user_client to access Databricks resources with user permissions
   response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
   

Para obtener una guía completa sobre cómo agregar ámbitos y comprender la seguridad basada en el ámbito, consulte Seguridad basada en ámbito y escalación de privilegios.

Autenticación en servidores MCP de Databricks

Para autenticarse en servidores MCP de Databricks, especifique todos los recursos que necesita el agente en el databricks.yaml archivo. Otorgue al principal de servicio de la aplicación (o a los usuarios, si utiliza la autorización de usuario) acceso a todos los recursos dependientes.

Por ejemplo, si el agente usa las direcciones URL del servidor MCP que se enumeran a continuación, debe conceder acceso a todos los índices de búsqueda vectoriales en prod.customer_support y prod.billing, así como a todas las funciones de Unity Catalog en prod.billing:

• https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/customer_support
• https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/billing
• https://<your-workspace-hostname>/api/2.0/mcp/functions/prod/billing

Configuración de la autenticación con Conjuntos de recursos de Databricks

Puede configurar todas las opciones de autenticación mediante programación mediante conjuntos de recursos de Databricks en lugar de la interfaz de usuario de Aplicaciones de Databricks. En esta página se muestra la configuración basada en la interfaz de usuario para ilustrar qué recursos y permisos se necesitan, pero se puede definir la misma configuración en los archivos YAML de agrupación. Consulte Aplicaciones en agrupaciones para obtener la referencia de configuración de agrupación completa.

Pasos siguientes

• Creación de un agente de IA e implementación en Databricks Apps
• Configuración de la autorización en una aplicación de Databricks
• Adición de recursos a una aplicación de Databricks