Overview
El motor de políticas de Atlas Agent Engine permite a los administradores de la organización controlar la ejecución de los agentes en tiempo de ejecución. Los administradores crean políticas dentro del ámbito de la organización, del proyecto o de ambos. El plano de control combina las políticas aplicables a un proyecto en una única configuración efectiva, y el motor de orquestación (OE) aplica dicha configuración en cada ejecución.
Las políticas controlan las acciones que realiza un agente, como qué herramientas y modelos invoca y cuánto trabajo realiza en una sola ejecución. Las políticas se dividen en dos categorías:
Las listas de permisos restringen las herramientas y los modelos que el agente puede utilizar.
Lospresupuestos de ejecución limitan los recursos que puede consumir una sola ejecución, como el número de llamadas a herramientas, el número de llamadas a modelos de lenguaje grandes (LLM) y la duración de la ejecución.
Para controlar el contenido que pasa a través de un agente, consulte la sección "Usarmedidas de protección de contenido".
Tipos de directivas
Cada tipo de política tiene una clase que describe la forma del valor de la política. La clase determina cómo el Motor de políticas combina las políticas de la organización y del proyecto. Los siguientes tipos de políticas están disponibles:
Tipo de póliza | Kind | Descripción |
|---|---|---|
| Lista de permitidos | Conjunto de herramientas que el agente puede utilizar. El OE evalúa esta política antes de cada llamada a una herramienta. Si el agente llama a una herramienta que no figura en la lista, el OE detiene la ejecución y devuelve un error de denegación de política. |
| Lista de permitidos | El conjunto de modelos que el agente puede invocar. El OE evalúa esta política antes de cada llamada LLM. Si el agente invoca un modelo que no se encuentra en la lista, el OE detiene la ejecución y devuelve un error de denegación de política. |
| Numeric cap | Número máximo de llamadas a herramientas que un agente puede realizar en una sola ejecución. Si el agente intenta realizar una llamada a una herramienta después de que la ejecución alcance el límite, el OE detiene la ejecución y devuelve un error de denegación de política. |
| Numeric cap | Número máximo de llamadas LLM que un agente puede realizar en una sola ejecución. Si el agente intenta realizar una llamada LLM después de que la ejecución alcance el límite, el OE detiene la ejecución y devuelve un error de denegación de política. |
| Numeric cap | Tiempo máximo transcurrido en milisegundos para una sola ejecución. El OE comprueba el tiempo transcurrido antes de cada llamada a la herramienta y a LLM. Si la ejecución ha alcanzado el límite, el OE la detiene y devuelve un error de denegación de política. El OE no detiene una llamada que ya esté en curso. |
| Numeric cap | Número máximo de tokens LLM que puede consumir una sola ejecución. Si el agente intenta realizar una llamada LLM después de que la ejecución alcance el límite, el OE detiene la ejecución y devuelve un error de denegación de política. |
| Numeric cap | Número máximo de tokens LLM que una sesión puede consumir en todas las ejecuciones de dicha sesión. Si el agente intenta realizar una llamada LLM después de que la sesión alcance el límite, el OE detiene la ejecución y devuelve un error de denegación de política. |
Para obtener información sobre el error de denegación de políticas, consulte la sección de Aplicación de la normativa.
Los totales de tokens se acumulan después de cada respuesta del modelo, en lugar de antes de una llamada a LLM. Para obtener más información, consulte Limitaciones.
Si un agente delega una tarea a un agente secundario, este hereda la sesión raíz del agente principal, por lo que ambos agentes se ejecutan en la misma sesión. Sus tokens combinados se contabilizan para un total MAX_TOKENS_PER_SESSION en lugar de un total independiente para cada agente. Para obtener más información sobre la delegación entre agentes, consulte la sección "Uso de la comunicación entre agentes".
Coincidencia de herramientas y catálogos
Una entrada en la lista de permitidos AUTHORIZED_TOOLS coincide con el nombre de una herramienta o con el identificador del catálogo que la publica, como stripe/payments. Un identificador de catálogo incluye en la lista de permitidos todas las herramientas que publica el catálogo, incluidas las que añada posteriormente.
Las herramientas que no tienen identificador de catálogo, incluidas las herramientas personalizadas, solo se identifican por su nombre. Para permitir una de estas herramientas, añada su nombre a la lista de permitidas.
Alcance y herencia de la política
Puede crear una política dentro del ámbito de la organización o del proyecto. Una política de organización se aplica a todos los proyectos de la organización. Cada política de proyecto debe ser al menos tan restrictiva como la política de organización del mismo tipo. Cuando dos ámbitos definen el mismo tipo de política, el Motor de políticas las combina en un único valor efectivo para el proyecto.
La regla de fusión depende del tipo de política. La siguiente tabla enumera cada tipo de política y su regla de fusión correspondiente:
Tipo de póliza | Regla de fusión | Restricción del proyecto |
|---|---|---|
Lista de permitidos | El valor efectivo es la intersección de la lista de permisos de la organización y la lista de permisos del proyecto. | Un proyecto no puede añadir un valor que no esté incluido en la lista de permisos de la organización. |
Numeric cap | El valor efectivo es el menor entre el límite de la organización y el límite del proyecto. | Un proyecto no puede establecer un límite superior al límite de la organización. |
Si guarda una política de proyecto menos restrictiva que la política de organización del mismo tipo, el motor del agente de Atlas rechazará la solicitud. Para aumentar un límite o ampliar una lista de permisos para un proyecto, un administrador de la organización debe modificar primero la política de la organización.
Aplicación
El OE evalúa las políticas efectivas en puntos de control específicos durante cada ejecución:
punto de control | Políticas evaluadas |
|---|---|
Llamada previa a la herramienta |
|
Llamada previa al LLM |
|
Cuando falla una comprobación de política, el OE detiene la ejecución y devuelve un error de denegación de política al llamador. El error incluye un error_code de policy_denied y un mensaje con el formato Policy denied: <reason> que identifica el motivo de la denegación.
Nota
Cuando no se aplica ninguna política de un tipo determinado a una ejecución, el OE no restringe la acción correspondiente. Un proyecto sin políticas efectivas se ejecuta sin restricciones de políticas.
Propagación de políticas
Tras crear, actualizar o eliminar una política, el motor de agentes de Atlas aplica el cambio en aproximadamente un minuto. El motor de agentes de Atlas primero reconstruye la configuración efectiva para cada proyecto afectado y, a continuación, entrega esa configuración al OE que ejecuta los agentes del proyecto.
Cada ejecución toma una instantánea de las políticas vigentes al iniciarse y la utiliza durante toda su vida útil. Los cambios de política solo se aplican a las ejecuciones que se inician después de que se propague el cambio. Los cambios de política no afectan a las ejecuciones en curso.
Si el motor del agente de Atlas no puede entregar un cambio, el OE continúa aplicando la última configuración recibida. Para comprobar qué proyectos no han recibido un cambio, consulte la sección "Comprobar la implementación de la política de la organización".
Crear y editar políticas
Puede crear y editar políticas desde la interfaz de usuario de la plataforma o mediante la API REST.
Para administrar las políticas del proyecto, vaya a Manage > Policies en su proyecto. Para administrar las políticas de la organización, vaya a Policies en la configuración de su organización. Desde cualquiera de las dos páginas, puede crear, leer, actualizar y eliminar políticas para cada tipo de política. Puede habilitar o deshabilitar las políticas del proyecto desde la página Policies del proyecto. La interfaz de usuario de la plataforma no permite habilitar ni deshabilitar las políticas de la organización.
Nota
La API REST orientada al cliente expone las operaciones de políticas. Las solicitudes requieren autenticación de portador por parte de un usuario que posea el rol necesario para la operación. Para obtener más información sobre los roles de usuario en Atlas Agent Engine, consulte Administrar organizaciones, proyectos y espacios de trabajo y Ver organizaciones.
La siguiente tabla enumera los puntos finales del proyecto disponibles:
Método | Endpoint | Rol Requerido | Referencia |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
La siguiente tabla enumera los puntos de acceso de la organización disponibles:
Método | Endpoint | Rol Requerido | Referencia |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
Vista previa de la lista de permitidos de una organización
Dado que una lista de permitidos se fusiona como una intersección, eliminar valores de una lista de permitidos de una organización puede dejar un proyecto sin valores permitidos. Antes de guardar los cambios en una política de organización, llame al siguiente punto final con el rol ORG_OWNER:
POST /api/v1/organizations/{orgId}/policies/preview
La respuesta de la API identifica cada proyecto cuya lista de permisos efectiva queda vacía y muestra la lista de permisos que el proyecto aplica actualmente. Para obtener más información, consulte la vista previa de los proyectos afectados.
Habilitar y deshabilitar políticas
El motor del agente Atlas omite las políticas deshabilitadas al crear la configuración efectiva. Tanto las políticas de organización como las de proyecto tienen un indicador enabled. Para habilitar o deshabilitar una política, llame al punto final de la API PUT correspondiente al ámbito de la política y establezca el indicador enabled. También puede habilitar o deshabilitar las políticas de proyecto desde la interfaz de usuario de la plataforma. Para obtener más información, consulte Crear y editar políticas.
Al deshabilitar una política, el motor del agente de Atlas conserva la configuración y el historial de la misma. Si la vuelve a habilitar, el motor del agente de Atlas restaura la misma configuración.
Ver políticas efectivas
La vista efectiva muestra cómo se resuelven los alcances de la organización y del proyecto para un proyecto. Para recuperar la vista efectiva, utilice el siguiente punto final del proyecto con el rol de lectura del proyecto:
GET /api/v1/projects/{projectId}/policies/effective
La respuesta de la API enumera todos los tipos de directivas, el valor efectivo combinado que aplica el OE, el valor que define cada ámbito y el o los ámbitos vigentes. El motor del agente de Atlas lee los valores de la organización en su nombre, de modo que puede ver la línea base heredada sin necesidad de tener un rol en la organización. Para obtener más información, consulte la sección "Lista de directivas efectivas".
Verificar la implementación de la política de la organización
En Atlas Agent Engine, los proyectos reciben los cambios de política de uno en uno, en lugar de todos a la vez. Mientras se implementa una política de organización, algunos proyectos aplican la nueva política, mientras que otros siguen aplicando la anterior. Para ver el progreso de la implementación de una política de organización, utilice el siguiente punto final con el rol ORG_OWNER o ORG_READ_ONLY:
GET /api/v1/organizations/{orgId}/policies/rollout
La respuesta de la API identifica cada proyecto retrasado, el motivo por el cual el proyecto no se ha reconstruido ni ha recibido la configuración efectiva, y el número de intentos que el Motor del Agente Atlas ha realizado para reconstruir o recibir dicha configuración. La respuesta de la API omite el texto del error subyacente, que el Motor del Agente Atlas registra en sus registros. Para obtener más información, consulte el estado de implementación de la política de la organización.
Cuando un proyecto no recibe una política guardada, el motor del agente de Atlas intenta nuevamente entregar la política a ese proyecto y deja intactos los proyectos que ya recibieron el cambio. Si el fallo no se puede resolver reintentando la compilación, por ejemplo, debido a un valor de política no válido, el motor del agente de Atlas deja de intentar compilar ese proyecto inmediatamente. Si el fallo es transitorio, como un proyecto inaccesible, el motor del agente de Atlas intenta compilar el proyecto nuevamente con un retraso creciente entre intentos. El motor del agente de Atlas deja de intentar compilar el proyecto después de 10 intentos fallidos.
El contador de intentos se reinicia la próxima vez que un usuario edita la política. Si el motor del agente de Atlas deja de reintentar un proyecto, corrija la política y guárdela de nuevo para que el proyecto vuelva a la cola de implementación.
Monitorear las denegaciones de pólizas
La interfaz de usuario de la plataforma informa sobre la frecuencia con la que las políticas rechazan llamadas en su organización y proyectos. Para obtener información sobre cómo interpretar las métricas de la interfaz de usuario de la plataforma, consulte Ver rechazos de políticas.
Limitaciones
El motor de políticas tiene las siguientes limitaciones:
Una política nueva o actualizada tarda hasta un minuto en surtir efecto. Una política se aplica únicamente a las ejecuciones que se inician después de su propagación. Las medidas de seguridad entran en vigor casi de inmediato.
El OE puede superar un límite en una llamada. El OE verifica la duración y el uso del token antes de cada llamada. Si la llamada no ha alcanzado el límite
MAX_EXECUTION_DURATION_MSoMAX_TOKENS_PER_EXECUTION, realiza la siguiente llamada, incluso si la llamada supera estos límites.El OE puede exceder el límite de tokens de sesión en más de una llamada. Una sesión ejecuta varias operaciones simultáneamente. El motor del agente Atlas comprueba los límites de sesión solo después de que finalizan todas las llamadas en curso. El valor
MAX_TOKENS_PER_SESSIONpodría exceder el valor máximo configurado debido a la suma de los tokens de dichas llamadas.Los límites de tokens excluyen la extracción de memoria. Los tokens que consume la extracción de memoria no se tienen en cuenta para los valores
MAX_TOKENS_PER_EXECUTIONoMAX_TOKENS_PER_SESSION.Losrecuentos de denegaciones excluyen las denegaciones de modelos. La métrica View Policy Denials no contabiliza las denegaciones que se producen cuando un modelo solicitado no está definido en el tipo de política
AUTHORIZED_MODELS.Las herramientas sin catálogo coinciden únicamente por nombre. Una herramienta que no tiene identificador de catálogo, como una herramienta personalizada, coincide con las entradas de tipo de política
AUTHORIZED_TOOLSúnicamente por nombre de herramienta. Para obtener más información, consulte Coincidencia de herramientas y catálogos.La salida de red se gestiona de forma independiente. El motor de políticas no controla la salida de red. Para obtener información sobre cómo configurar las restricciones de salida de red, consulte la sección «Administrar políticas de salida de red».