Visão geral
As grades de proteção do Atlas Agent Engine permitem que os administradores de projeto controlem o conteúdo que entra e sai das chamadas do modelo de um agente. Os administradores definem grades de proteção em um projeto e o mecanismo de orquestração (OE) impõe as grades de proteção bloqueando ou modificando o conteúdo correspondente de entrada e saída.
Para aplicar uma proteção a um ou mais espaços de trabalho, especifique os espaços de trabalho no campoworkspace_ids do proteção. Se você não especificar este campo, a proteção se aplicará a todos os espaços de trabalho do projeto.
As grades de proteção completam o mecanismo de políticas. As guardas controlam o conteúdo que entra e sai de um modelo, enquanto o Mecanismo de Políticas controla as ações que um agente pode adotar, como quais ferramentas e modelos ele pode chamar.
Tipos de guardrails
Cada guardrail tem um tipo, que determina qual conteúdo ele avalia, e uma ação, que determina o que acontece quando o guardrail aciona.
Atualmente, o Atlas Agent Engine é compatível apenas com o tipo de proteção output_validation. Você pode usar proteção desse tipo para avaliar o resultado de um agente em relação a um conjunto de padrões de expressão regular. Defina esses padrões no campoconfig.match_patterns do guardrail.
Cada proteção especifica uma das seguintes ações:
em ação | Descrição |
|---|---|
| Nega a chamada. A execução é interrompida e retorna um erro ao chamador. |
| Remove ou transforma o conteúdo correspondente e permite que a execução prossiga com o conteúdo modificado. |
| Registra que o guardrail acionou e permite que a execução prossiga com o conteúdo original. |
| Suspende a execução para revisão humana. A execução prossegue somente após a aprovação de um revisor. |
Estágios de guardrail
O filtro de estágio de uma grade de proteção determina se ela avalia o conteúdo que entra no modelo, que sai do modelo ou ambos. Uma proteção sem filtro de estágio se aplica a todos os estágios.
A tabela a seguir descreve os estágios disponíveis:
Estágio | Avalia o que | Acionado quando |
|---|---|---|
| O conteúdo do usuário alcançando o modelo | Antes de uma chamada de modelo |
| A resposta do modelo | Antes que a resposta retorne ao usuário |
Campos de guardrail
A tabela a seguir descreve os campos que definem uma grade de proteção. Você pode definir esses campos na interface do usuário da plataforma ou no corpo da solicitação JSON de uma solicitação de API create ou update.
Campo | Possible values | Descrição |
|---|---|---|
| Qualquer string | (Obrigatório) Nome de exibição do guardrail. |
| Qualquer string | Descrição da finalidade da grade de proteção. |
|
| (Obrigatório) Tipo de guardrail. |
|
| (Obrigatório) Ação a ser tomada quando o guardrail é acionado. |
|
| Se o Atlas Agent Engine aplica a proteção. O Atlas Agent Engine força grades de proteção cujo status é |
|
| Array dos estágios em que a proteção avalia o conteúdo. Para avaliar ambos os estágios, liste |
| Array de IDs de espaço de trabalho | Array dos espaços de trabalho aos quais a proteção se aplica. Para aplicar a proteção a todos os espaços de trabalho do projeto, deixe essa array vazia. |
| Array de padrões de regex | Array dos padrões contra os quais a proteção corresponde o conteúdo. Cada padrão define um |
|
| Comportamento a ser aplicado ao conteúdo que corresponde a um padrão. Este campo se aplica somente quando |
Para visualizar um exemplo de corpo de solicitação que define esses campos, consulte a guia REST API na seção a seguir.
Criar e editar grades de proteção
Você pode criar e editar grades de proteção usando a interface do usuário da plataforma ou a API REST. Para visualizar as instruções, selecione a guia do seu método preferido:
Navegue até Manage → Policies, e selecione a aba Guardrails.
Em seguida, crie um guardrail clicando no botão Create guardrail e configurando os campos na caixa de diálogo Create guardrail. Para atualizar uma proteção, clique no ícone Edit da proteção. Para excluir uma proteção, clique em seu ícone Delete.
Observação
A API REST voltada para o cliente expõe operações de proteção. As solicitações exigem autenticação do portador e permissões de projeto apropriadas. Para saber mais sobre funções de projeto , consulte Gerenciar organizações, projetos e espaços de trabalho.
A tabela a seguir lista os endpoints disponíveis:
Método | Endpoint | Referência |
|---|---|---|
|
| |
|
| |
|
| |
|
| |
|
|
Ao chamar os endpoints de criação e atualização, passe os campos da grade de proteção como um corpo de solicitação JSON. O exemplo de corpo da solicitação a seguir cria uma proteção que edita três dígitos consecutivos do conteúdo que chega ao modelo em um único workspace:
{ "name": "Test guardrail", "description": "Redacts three-digit sequences", "type": "output_validation", "action": "modify", "status": "active", "stage_filter": ["llm_input"], "workspace_ids": ["ws-6a885deac97e9d280fa88cf3"], "config": { "match_patterns": [ { "type": "regex", "value": "\\d{3}" } ], "on_fail": "fix" } }
Propagação de guard-rail
Depois de criar, atualizar ou excluir uma proteção, a alteração entra em vigor na próxima execução que o OE lida com. Uma gravação de grade de proteção recarrega as grades de proteção em cache do OE, para que a alteração entre em vigor na próxima solicitação.
As alterações de proteção não afetam as execuções a bordo.
Aplicação da
Durante cada execução, a OE avalia o conteúdo em cada estágio em relação às proteções que se aplicam ao projeto atual. A tabela a seguir descreve as etapas e o conteúdo avaliado correspondente:
Estágio | Conteúdo avaliado |
|---|---|
| O conteúdo do usuário é avaliado antes de uma chamada de modelo. |
| A resposta do modelo é avaliada antes de retornar ao usuário. |
Quando uma proteção com uma ação block é acionada, a OE interrompe a execução e retorna um erro ao chamador. O erro identifica a grade de proteção que causou o bloqueio. Quando uma proteção com uma ação modify é acionada, a execução prossegue com o conteúdo modificado.
Quando mais de uma proteção corresponde ao mesmo conteúdo, a ação mais restritiva se aplica. As ações são classificadas na seguinte ordem, da mais para a menos restritiva:
blockrequire_reviewmodifylog_only
Por exemplo, se um guardrail retornar modify e outro retornar block, o OE bloqueará a chamada.
Limitações
As grades de proteção têm as seguintes limitações:
Somente execuções futuras: as alterações de guardrail se aplicam somente às execuções que iniciam após a alteração entrar em vigor. As execuções já em andamento continuam com as grades de proteção com as quais começaram.
Somentecontroles de conteúdo: as grades de proteção controlam o conteúdo que entra e sai de um modelo. Para controlar as ações que um agente pode adotar, como quais ferramentas e modelos ele pode chamar, use o Mecanismo de políticas.