Visão geral
O mecanismo de políticas do mecanismo de agentes do Atlas oferece aos administradores da organização controle de tempo de execução sobre a execução do agente . Os administradores criam políticas dentro do escopo da organização , do escopo do projeto ou de ambos. O plano de controle mescla as políticas que se aplicam a um projeto em uma única configuração efetiva, e o Mecanismo de Orquestração (OE) impõe essa configuração por execução.
As políticas controlam as ações que um agente executa, como quais ferramentas e modelos ele invoca e quanto trabalho uma única execução executa. As políticas se enquadram em duas categorias:
As listas de permissões restringem quais ferramentas e modelos o agente pode chamar.
Os orçamentos de execução limitam os recursos que uma única execução pode consumir, como o número de chamadas de ferramentas, o número de chamadas de grandes modelos de linguagem (LLM) e a duração da execução.
Para controlar o conteúdo que passa por um agente,consulte Usar proteção de conteúdo.
Tipos de política
Cada tipo de política tem um tipo, que descreve a forma do valor da política. O tipo determina como o Mecanismo de Políticas mescla as políticas da organização e do projeto . Os seguintes tipos de política estão disponíveis:
Tipo de política | Kind | Descrição |
|---|---|---|
| Lista de permissões | O conjunto de ferramentas que o agente pode chamar. A OE avalia esta política antes de cada chamada de ferramenta. Se o agente chamar uma ferramenta que a lista omite, a OE interromperá a execução e retornará um erro de negação de política. |
| Lista de permissões | O conjunto de modelos que o agente pode invocar. A OE avalia esta política antes de cada chamada LLM. Se o agente invocar um modelo que a lista omite, a OE interromperá a execução e retornará um erro de negação de política. |
| Numeric cap | O número máximo de chamadas de ferramentas que um agente pode fazer em uma única execução. Se o agente tentar uma chamada de ferramenta depois que a execução atingir o limite, a OE interromperá a execução e retornará um erro de negação de política. |
| Numeric cap | O número máximo de chamadas ao LLM que um agente pode fazer em uma única execução. Se o agente tentar uma chamada LLM depois que a execução atingir o limite, a OE interromperá a execução e retornará um erro de negação de política. |
| Numeric cap | O tempo máximo decorrido em milissegundos para uma única execução. A OE verifica o tempo decorrido antes de cada chamada de ferramenta e chamada LLM. Se a execução atingir o limite, a OE interromperá a execução e retornará um erro de negação de política. O OE não interrompe uma chamada que já esteja em andamento. |
| Numeric cap | O número máximo de tokens LLM que uma única execução pode consumir. Se o agente tentar uma chamada LLM depois que a execução atingir o limite, a OE interromperá a execução e retornará um erro de negação de política. |
| Numeric cap | O número máximo de tokens LLM que uma sessão pode consumir em cada execução nessa sessão. Se o agente tentar uma chamada LLM depois que a sessão atingir o limite, a OE interromperá a execução e retornará um erro de negação de política. |
Para saber mais sobre o erro de negação da política, consulte Aplicação.
Os totais de token se acumulam após cada resposta do modelo, e não antes de uma chamada LLM. Para obter mais informações, consulte Limitações.
Se um agente delegar uma tarefa a um agente filho, o filho herda a sessão raiz do pai, então ambos os agentes são executados na mesma sessão. Seus tokens combinados contam para um total de MAX_TOKENS_PER_SESSION em vez de um total separado por agente. Para saber mais sobre a delegação de agente para agente, consulte Usar comunicação de agente para agente.
Correspondência de Ferramentas e Catálogo
Uma entrada da lista de permissões AUTHORIZED_TOOLS corresponde ao nome de uma ferramenta ou ao identificador do catálogo que publica a ferramenta, como stripe/payments. Um identificador de catálogo lista todas as ferramentas que o catálogo publica, incluindo as ferramentas que o catálogo adiciona posteriormente.
As ferramentas que não carregam identificador de catálogo, incluindo ferramentas personalizadas, correspondem somente pelo nome da ferramenta. Para permitir uma dessas ferramentas, adicione seu nome à lista de permissões.
Escopo e herança da política
Você pode criar uma política dentro do escopo da organização ou do escopo do projeto . Uma política da organização se aplica a todos os projeto da organização. Cada política de projeto deve ser pelo menos tão restritiva quanto a política da organização do mesmo tipo. Quando dois escopos definem o mesmo tipo de política, o mecanismo de política os mescla em um valor efetivo para o projeto.
A regra de mesclagem depende do tipo de política. A tabela a seguir lista cada tipo de política e sua regra de mesclagem correspondente:
Tipo de Política | Regra de mesclagem | Restrição do projeto |
|---|---|---|
Lista de permissões | O valor efetivo é a interseção da lista de permissões da organização e da lista de permissões do projeto . | Um projeto não pode adicionar um valor que a lista de permissões da organização omita. |
Numeric cap | O valor efetivo é o menor entre o limite da organização e o limite do projeto . | Um projeto não pode definir um limite superior ao limite da organização . |
Se você salvar uma política de projeto menos restritiva do que a política da organização do mesmo tipo, o Atlas Agent Engine rejeitará a solicitação. Para aumentar um limite ou ampliar a lista de permissões de um projeto, o administrador da organização deve primeiro alterar a política da organização .
Aplicação da
O OE avalia as políticas eficazes em checkpoints específicos durante cada execução:
checkpoint | Políticas avaliadas |
|---|---|
Chamada pré-tool |
|
Pré-LLM-call |
|
Quando uma verificação de política falha, a OE interrompe a execução e retorna um erro de negação de política ao chamador. O erro inclui um error_code de policy_denied e uma mensagem no formato Policy denied: <reason> que identifica o motivo da negação.
Observação
Quando nenhuma política de determinado tipo se aplica a uma execução, a OE não restringe a ação correspondente. Um projeto sem políticas eficaz é executado sem restrições de políticas.
Propagação de políticas
Depois que você cria, atualiza ou exclui uma política, o Atlas Agent Engine aplica a alteração em aproximadamente um minuto. O Atlas Agent Engine primeiro reconstrói a configuração efetiva para cada projeto afetado e, em seguida, fornece essa configuração ao OE que executa os agentes do projeto.
Cada execução tira um snapshot das políticas efetivas quando é iniciada e usa esse snapshot por toda a vida útil. As alterações de política se aplicam apenas às execuções iniciadas após a propagação da alteração. As alterações de política não afetam as execuções a bordo.
Se o Atlas Agent Engine não puder fornecer uma alteração, o OE continuará a impor a última configuração recebida. Para verificar quais projetos não receberam uma alteração, consulte Verificar Implementação da Política da Organização.
Criar e Editar Políticas
Você pode criar e editar políticas a partir da interface do usuário da plataforma ou da API REST.
Para gerenciar as políticas do projeto , acesse Manage > Policies em seu projeto. Para gerenciar as políticas da organização , acesse Policies nas configurações da sua organização . Em qualquer página, você pode criar, ler, atualizar e excluir políticas para cada tipo de política. Você pode habilitar ou desabilitar as políticas do projeto na página Policies do projeto . A interface do usuário da plataforma não permite ativar ou desativar políticas da organização .
Observação
A API REST voltada para o cliente expõe operações de política. As solicitações exigem a autenticação do portador por um usuário que tenha a função necessária para a operação. Para saber mais sobre as funções de usuário no Atlas Agent Engine, consulte Gerenciar organizações, projetos e espaços de trabalho e Exibir organizações.
A tabela a seguir lista os endpoints do projeto disponíveis:
Método | Endpoint | Função necessária | Referência |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
A tabela a seguir lista os endpoints da organização disponíveis:
Método | Endpoint | Função necessária | Referência |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
Visualizar uma lista de permissões da organização
Como uma lista de permissões mescla como uma interseção, remover valores de uma lista de permissões da organização pode deixar um projeto sem valores permitidos. Antes de salvar as alterações em uma política da organização , chame o seguinte endpoint com a role ORG_OWNER:
POST /api/v1/organizations/{orgId}/policies/preview
A resposta da API nomeia cada projeto cuja lista de permissões efetivas fica vazia e mostra a lista de permissões que o projeto aplica atualmente. Para saber mais, consulte Visualizar projetos afetados.
Habilitar e desabilitar políticas
O Atlas Agent Engine ignora políticas desabilitadas quando cria a configuração efetiva. As políticas da organização e do projeto têm um sinalizador enabled. Para habilitar ou desabilitar uma política, chame o ponto de extremidade da API PUT para o escopo da política e defina o sinalizador enabled. Você também pode ativar ou desativar as políticas do projeto na interface do usuário da plataforma. Para saber mais, consulte Criar e editar políticas.
Quando você desabilita uma política, o Atlas Agent Engine preserva a configuração e o histórico da política. Se você reativar a política, o Atlas Agent Engine restaurará a mesma configuração.
Visualizar políticas eficazes
A exibição efetiva mostra como a organização e os escopos do projeto se resolvem para um projeto. Para recuperar a visualização efetiva, use o seguinte endpoint do projeto com o role de leitura do projeto :
GET /api/v1/projects/{projectId}/policies/effective
A resposta da API lista cada tipo de política, o valor efetivo mesclado que a OE impõe, o valor que cada escopo define e o escopo ou escopos em vigor. O Atlas Agent Engine lê os valores da organização em seu nome, para que você possa ver a linha de base herdada sem ter um role da organização . Para saber mais, consulte Listar políticas eficazes.
Verifique a Implementação da Política da Organização
No Atlas Agent Engine, os projetos recebem uma alteração de política um de cada vez, em vez de juntos. Enquanto a implementação de uma política da organização está em andamento, alguns projetos impõem a nova política, enquanto outros ainda impõem a anterior. Para ver o progresso da implementação de uma política da organização , use o seguinte endpoint com a função ORG_OWNER ou ORG_READ_ONLY:
GET /api/v1/organizations/{orgId}/policies/rollout
A resposta da API identifica cada projeto atrasado, o motivo pelo qual o projeto não foi reconstruído ou recebeu a configuração efetiva e o número de tentativas que o Atlas Agent Engine fez para reconstruir ou receber a configuração efetiva. A resposta da API omite o texto de erro subjacente, que o Atlas Agent Engine registra em seus logs. Para saber mais, consulte Ver status de distribuição da política da organização .
Quando um projeto não recebe uma política salva, o Atlas Agent Engine tenta novamente entregar a política para esse projeto e deixa os projetos que já receberam a alteração intocados. Se a falha não puder ser resolvida com uma nova tentativa de compilação, como um valor de política inválido, o Atlas Agent Engine interromperá imediatamente a tentativa de compilação desse projeto. Se a falha for transitória, como um projeto inacessível, o Atlas Agent Engine tentará criar o projeto novamente com um atraso crescente entre as tentativas. O Atlas Agent Engine para de tentar criar o projeto novamente após 10 tentativas fracassadas.
A contagem de tentativas é redefinida da próxima vez que um usuário edita a política. Se o Mecanismo do Agente Atlas parar de tentar novamente um projeto, corrija a política e salve-a novamente para retornar o projeto à fila de distribuição.
Monitorar negações de políticas
A interface do usuário da plataforma informa com que frequência as políticas negam chamadas em sua organização e projetos. Para saber como ler as métricas da interface do usuário da plataforma, consulte Visualizar negações de política.
Limitações
O Mecanismo de Políticas tem as seguintes limitações:
Uma política nova ou atualizada leva até um minuto para entrar em vigor. Uma política se aplica apenas às execuções que iniciam após sua propagação. As grades de proteção entram em vigor quase que imediatamente.
A OE pode exceder um limite em uma chamada. A OE verifica a duração e o uso do token antes de cada chamada. Se a chamada não tiver atingido o limite
MAX_EXECUTION_DURATION_MSouMAX_TOKENS_PER_EXECUTION, ela fará a próxima chamada, mesmo que a chamada exceda esses limites.O OE pode exceder um limite de token de sessão em mais de uma chamada. Uma sessão realiza várias execuções ao mesmo tempo. O Atlas Agent Engine verifica os limites de sessão somente após o término de todas as chamadas a bordo. O valor
MAX_TOKENS_PER_SESSIONpode exceder o valor máximo configurado pelos tokens combinados dessas chamadas.Os limites de token excluem a extração de memória. Os tokens que a extração de memória consome não contam para os valores
MAX_TOKENS_PER_EXECUTIONouMAX_TOKENS_PER_SESSION.Ascontagens de negação excluem negações de modelo. A métrica Visualizar negações de política não conta as negações de quando um modelo solicitado não está definido no tipo de política
AUTHORIZED_MODELS.As ferramentas sem catálogo correspondem apenas ao nome. Uma ferramenta que não carrega nenhum identificador de catálogo, como uma ferramenta personalizada, corresponde a entradas de tipo de política
AUTHORIZED_TOOLSsomente por nome de ferramenta. Para saber mais, consulte Correspondência de Ferramentas e Catálogo.A saída da rede é regida separadamente. O Mecanismo de Políticas não controla a saída de rede. Para saber como configurar restrições de saída de rede, consulte Gerenciar Políticas de Saída de Rede.