Caso de uso
Gate de risco para tool calls
Pontue uma tool call proposta pelo agente antes de ela tocar dados de produção.
O problema
Agentes inventam SQL e deleções de arquivos que parecem plausíveis e são catastróficos.
O que seu código faz com a resposta
Bloqueie ou confirme qualquer chamada cujo score de risco fique acima do seu threshold.
Lendo a resposta do guardrail
Três sinais em uma chamada: needs_confirmation e matches_intent como probabilidades sim/não, e risk como um score ao longo de Harmless → Recoverable → Irreversible data loss. O exemplo acima é propositalmente feio — um pedido de "limparo staging" cuja tool call derruba uma tabela de produção. O risk sobe até o topo e o match de intenção cai abaixo da confiança, que é o que o seu wrapper transforma em block-and-log.
Onde o gate entra no seu loop
Chame o gate exatamente uma vez, depois de o agente propor uma chamada e antes da execução. Passe a requisição original do usuário e a chamada proposta como state — nada mais precisa estar lá. Mantenha as linhas de política em código (bloquear em score ≥ 1.5 ou intenção abaixo de 0.8; confirmar no meio), e filtre apenas as ferramentas cujo raio de explosão justifica um round trip de 400–600 ms: SQL, filesystem, deploys, e-mail. Chamadas somente leitura podem passar sem gate.
Pitfalls específicos de gates de ferramentas
Nunca mande ao gate apenas a tool call: sem a requisição original do usuário, o match de intenção não tem contra o que comparar e degenera em um gate só de score de destruição. Não filtre toda ferramenta desde o primeiro dia — comece com as poucas cujas falhas são no máximo recuperáveis, e revise conforme os thresholds estabilizam. Por fim: trate um timeout desta chamada como "pergunte a uma pessoa", não "prossiga e torça".
O formato da requisição
Esta é a requisição completa que o playground envia para este preset — o mesmo JSON que o seu servidor envia para /v1/systemone com uma chave Bearer.
curl https://jevai.website/api/v1/systemone \
-H "Authorization: Bearer $JEV_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"state": {
"user_request": "Clean up the old test data in the staging database.",
"proposed_tool_call": {
"tool": "sql.execute",
"args": {
"query": "DROP TABLE customers;"
},
"environment": "production"
}
},
"questions": {
"needs_confirmation": {
"type": "noul",
"instructions": "Should a human confirm this tool call before it runs?"
},
"matches_intent": {
"type": "noul",
"instructions": "Does `proposed_tool_call` match what `user_request` asked for?"
},
"risk": {
"type": "score",
"instructions": "How destructive is this action if it is wrong?",
"criteria": [
"Harmless",
"Recoverable",
"Irreversible data loss"
]
}
}
}'FAQ sobre este caso de uso
- O gate atrasa toda tool call?
- Apenas as que você mandar para ele. A maioria das equipes filtra as escritas e deixa as leituras passar; os round trips se concentram em 400–600 ms em medições reais, então leituras abaixo de 100 ms preferem não pagar isso.
- O modelo pode ver o meu codebase inteiro?
- Não — ele só vê o state que você envia. Inclua o ambiente (staging vs produção) e a intenção do chamador; esses dois fatos decidem a maioria dos gates.
- Uma probabilidade só basta para confiar?
- Nenhum número sozinho basta em uma ação irreversível. É por isso que o preset envolve três perguntas — match de intenção, confirmação humana e score de destruição — cada uma com um threshold diferente na sua política.