Ganchos de agente no Agente SRE do Azure

Ganchos são pontos de verificação personalizados que interceptam e controlam o comportamento do agente em momentos-chave. Use os ganchos para aplicar portões de qualidade em respostas do agente, auditar e controlar o uso de ferramentas, bloquear operações perigosas por meio da imposição de política e impedir a conclusão antecipada da tarefa, validando a saída do agente.

O problema

Seu agente executa tarefas de forma autônoma – investigando incidentes, executando ferramentas e gerando respostas. Mas a autonomia sem supervisão cria risco:

Respostas incompletas: o agente diz "concluído" antes de abordar tudo o que você pediu.
Uso de ferramenta não auditado: você não tem visibilidade de quais ferramentas o agente chama ou quais resultados ele obtém.
Nenhuma imposição de política: operações perigosas (comandos destrutivos, alterações não autorizadas) prosseguem sem controle.
Lacunas de qualidade: as respostas perdem informações críticas porque não há nenhuma etapa de validação.

Você precisa de uma maneira de interceptar o comportamento do agente em momentos-chave sem retardá-lo ou remover totalmente sua autonomia.

Como os ganchos de agente funcionam

Hooks são pontos de verificação personalizados que você associa a eventos específicos do agente. Quando um evento é acionado, o gancho avalia a situação e decide se deseja permitir ou bloquear a ação.

Agent about to stop → Stop hook evaluates response → Allow or reject
Agent uses a tool   → PostToolUse hook checks result → Allow, block, or inject context

No momento, há suporte para dois eventos de gancho:

Acontecimento	Dispara quando	O que você pode fazer
Parar	O agente está prestes a retornar uma resposta final	Validar a completude, rejeitar e forçar o agente a continuar
PostToolUse	Uma ferramenta termina de ser executada com êxito	Auditar o uso, bloquear resultados, injetar contexto extra

Dois níveis de ganchos

Os ganchos operam em dois níveis:

Nível	Onde configurar	Scope
Nível do agente	Construtor → Ganchos no portal	Aplica-se a todo o agente, incluindo todos os threads e todos os agentes personalizados
Nível de agente personalizado	Agent Canvas → agente personalizado → Gerenciar Hooks ou por meio da API REST v2	Aplica-se somente quando esse agente personalizado específico é executado

Ambos os níveis podem coexistir. Se um gancho no nível do agente e um gancho de nível de agente personalizado corresponderem ao mesmo evento, ambos são executados. No nível do agente, os ganchos são disparados primeiro.

Tipos de execução

Você pode implementar ganchos usando uma LLM ou um script de shell:

Tipo	Como funciona	Mais adequado para
Rápido	Um LLM avalia seu prompt e retorna um resultado em JSON	Validação com nuances ("Esta resposta está concluída?")
Command	Um script bash ou Python é executado em um ambiente em área restrita	Verificações determinísticas, imposição de política, auditoria

Ganchos de prompt são poderosos para a avaliação subjetiva, como verificar se uma resposta resolve todas as preocupações do usuário ou verificar se uma investigação foi completa o suficiente. Eles usam o $ARGUMENTS espaço reservado para receber o contexto de gancho completo. Se $ARGUMENTS não estiver presente no prompt, o contexto será acrescentado automaticamente. Quando a transcrição de uma conversação está disponível, os ganchos de prompt também recebem ReadFile e GrepSearch as ferramentas quando uma transcrição de conversa está disponível, o que permite o LLM considerar o histórico completo da conversa.

Ganchos de comando são melhores para verificações determinísticas, como validar que uma resposta contém marcadores necessários, bloquear comandos perigosos ou registrar o uso da ferramenta em um sistema externo.

O que torna essa abordagem diferente

A tabela a seguir compara o comportamento do agente com e sem ganchos.

Sem ganchos	Com ganchos
O agente decide quando está "concluído"	Você define o que significa "feito"
O uso da ferramenta é invisível	Cada chamada de ferramenta pode ser auditada
Comandos perigosos prosseguem silenciosamente	A imposição de política os bloqueia automaticamente
A qualidade depende apenas da engenharia de prompt	Portas de qualidade automatizadas capturam lacunas

Ganchos não substituem controles de segurança do modo de execução - eles os complementam. Os modos de execução controlam o que o agente pode fazer. Os ganchos controlam o quão bem ele faz e o que acontece com os resultados.

Antes e depois

Scenario	Antes	Após
Qualidade da resposta	O agente é interrompido quando ele acredita que terminou	O stop hook valida a completude antes que a resposta chegue aos usuários
Visibilidade da ferramenta	Nenhuma trilha de auditoria da execução da ferramenta	PostToolUse conecta o log e verifica cada chamada de ferramenta
Imposição de política	Comandos perigosos são executados sem verificação	Scripts bloqueiam automaticamente `rm -rf`, `sudo` e outros padrões arriscados.
Garantia de qualidade	A engenharia de prompt é seu único recurso.	Ganchos baseados em LLM avaliam nuances; scripts impõem regras determinísticas

Configurar ganchos

A maneira mais fácil de criar ganchos é por meio da interface do usuário do portal:

Ganchos no nível do agente: Vá para Construtor → Ganchos → selecione Criar gancho.
Ganchos no nível do agente personalizado: Vá para a Tela do Agente → selecione um agente personalizado → Gerenciar Ganchos.

Dica

Você também pode configurar ganchos por meio da API REST v2 usando PUT /api/v2/extendedAgent/agents/{agentName}. O formato YAML na seção a seguir mostra o esquema de configuração completo. Para saber mais, confira o tutorial da API.

A guia YAML da Tela do Agente exibe o formato v1 e não mostra os ganchos. Use a página Ganchos no Construtor para exibir e gerenciar ganchos.

O exemplo a seguir mostra uma configuração de gancho completa:

api_version: azuresre.ai/v2
kind: ExtendedAgent
metadata:
  name: my_hooked_agent
spec:
  instructions: |
    You are a helpful assistant.
  handoffDescription: ""
  enableVanillaMode: true
  hooks:
    Stop:
      - type: prompt
        prompt: |
          Check if the response ends with "Task complete."
          $ARGUMENTS
          Respond with:
          - {"ok": true} if it does
          - {"ok": false, "reason": "End your response with 'Task complete.'"} if not
        timeout: 30

    PostToolUse:
      - type: command
        matcher: "Bash|ExecuteShellCommand"
        timeout: 30
        failMode: block
        script: |
          #!/usr/bin/env python3
          import sys, json, re

          context = json.load(sys.stdin)
          command = context.get('tool_input', {}).get('command', '')

          dangerous = [r'\brm\s+-rf\b', r'\bsudo\b', r'\bchmod\s+777\b']
          for pattern in dangerous:
              if re.search(pattern, command):
                  print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
                  sys.exit(0)

          print(json.dumps({"decision": "allow"}))

Formato de resposta do gancho

Os ganchos devem gerar JSON. Há suporte para dois formatos.

Formato simples (recomendado para ganchos de prompt):

{"ok": true}
{"ok": false, "reason": "Please include more details."}

Formato expandido (recomendado para ganchos de comando):

{"decision": "allow"}
{"decision": "block", "reason": "Dangerous command detected."}
{"decision": "allow", "hookSpecificOutput": {"additionalContext": "Tool audit logged."}}

Os ganchos de comando também podem usar códigos de saída em vez de saída JSON:

Código de saída	Comportamento
`0` sem saída	Permitir (sem objeção)
`0` com JSON	Analisar JSON para decisão
`2`	Bloquear sempre. stderr se torna a causa
Outras	Usa a `failMode` configuração (`allow` ou `block`)

Cuidado

Para ganchos de parada, uma rejeição sem um motivo é tratada como uma aprovação, e o agente é interrompido normalmente. Sempre forneça um reason campo ao rejeitar.

Observação

Você pode definir múltiplos hooks para o mesmo evento. Para PostToolUse, cada gancho que tem um padrão correspondente matcher é executado de forma independente. Se vários ganchos fornecerem additionalContext, o contexto do último gancho será injetado na conversa.

Referência de configuração

A tabela a seguir descreve todas as opções de configuração de gancho disponíveis.

Opção	Tipo	Default	Descrição
`type`	cadeia	`prompt`	`prompt` ou `command`
`prompt`	cadeia	—	Texto de prompt LLM (obrigatório para ganchos de prompt). Use `$ARGUMENTS` para injeção de contexto.
`command`	cadeia	—	Comando de shell em linha (para ganchos de comando, mutuamente exclusivo com `script`).
`script`	cadeia	—	Script de várias linhas (para ganchos de comando, mutuamente exclusivo com `command`).
`matcher`	cadeia	—	Padrão Regex para nomes de ferramentas (necessário para ganchos PostToolUse). `*` corresponde a todas as ferramentas. Os padrões estão ancorados como `^(pattern)$` e diferenciam maiúsculas de minúsculas. Vazio ou nulo não corresponde a nada.
`timeout`	int	`30`	Tempo limite de execução em segundos (deve ser positivo; valores acima de 300 são sinalizados durante a validação da CLI).
`failMode`	cadeia	`allow`	Como lidar com erros de hook: `allow` ou `block`.
`model`	cadeia	`ReasoningFast`	Modelo para ganchos de prompt (nome do cenário ou nome da implantação).
`maxRejections`	int	`3` (padrão do agente)	Número máximo de rejeições antes de forçar a interrupção. Intervalo: 1 a 25. Aplica-se apenas a ganchos de parada do tipo prompt. Os ganchos stop do tipo comando não têm limite implícito. Quando vários ganchos de prompt especificam valores diferentes, o máximo é usado.

Esquema de contexto do hook

Os ganchos recebem um contexto JSON estruturado sobre o evento atual. Ganchos de prompt recebem contexto usando o espaço reservado $ARGUMENTS no texto do prompt. Ganchos de comando recebem o contexto como JSON em stdin.

Para ambos os tipos de gancho, o execution_summary campo contém um caminho de arquivo para a transcrição da conversa (não conteúdo embutido). Para ganchos de prompt, o LLM recebe as ferramentas ReadFile e GrepSearch para acessar esse arquivo. Para ganchos de comando, o arquivo está disponível no caminho especificado no sandbox.

Campos comuns

Todos os ganchos recebem os seguintes campos:

{
  "hook_event_name": "Stop",
  "agent_name": "my_agent",
  "current_turn": 5,
  "max_turns": 50,
  "execution_summary": "/path/to/transcript.txt"
}

Campos do gancho de parada

Os ganchos de parada recebem campos extras sobre a saída final do agente.

{
  "final_output": "Here is my response...",
  "stop_hook_active": false,
  "stop_rejection_count": 0
}

Campos de gancho do PostToolUse

Os ganchos postToolUse recebem campos extras sobre a execução da ferramenta.

{
  "tool_name": "ExecutePythonCode",
  "tool_input": { "code": "print(2+2)" },
  "tool_result": "4",
  "tool_succeeded": true
}

Limits

Os limites a seguir se aplicam a ganchos do agente.

Limit	Valor
Tamanho do script	Máximo de 64 KB
Intervalo	1 a 300 segundos
Máximo de rejeições (prompt de Ganchos de parada)	1 a 25 (padrão: 3)
Shebangs de script com suporte	`#!/bin/bash`, `#!/usr/bin/env python3`
Ambiente de execução de script	Interpretador de código em área restrita

Exemplo: auditar todo o uso da ferramenta

O seguinte gancho postToolUse registra cada chamada de ferramenta e adiciona uma mensagem de contexto de auditoria:

hooks:
  PostToolUse:
    - type: command
      matcher: "*"
      timeout: 30
      failMode: allow
      script: |
        #!/usr/bin/env python3
        import sys, json

        context = json.load(sys.stdin)
        tool_name = context.get('tool_name', 'unknown')

        print(f"Tool used: {tool_name}", file=sys.stderr)

        output = {
            "decision": "allow",
            "hookSpecificOutput": {
                "additionalContext": f"[AUDIT] Tool '{tool_name}' was executed."
            }
        }
        print(json.dumps(output))

O additionalContext campo é adicionado como uma mensagem de usuário na conversa, dando ao agente visibilidade na trilha de auditoria.

Exemplo: exigir um marcador de conclusão

O seguinte gancho de parada rejeita respostas que não terminam com "Tarefa concluída":

hooks:
  Stop:
    - type: command
      timeout: 30
      failMode: allow
      script: |
        #!/bin/bash
        CONTEXT=$(cat)
        FINAL_OUTPUT=$(echo "$CONTEXT" | jq -r '.final_output // empty')

        if [[ "$FINAL_OUTPUT" == *"Task complete."* ]]; then
          exit 0
        else
          echo "Please end your response with 'Task complete.'" >&2
          exit 2
        fi

Práticas recomendadas

Siga estas diretrizes ao configurar ganchos de agente:

Sempre forneça um motivo ao rejeitar. Trate as rejeições sem motivos como aprovações.
Use tempos limite apropriados: os ganchos de longa execução retardam a execução do agente.
Tratar erros de forma elegante: use failMode: allow a menos que a imposição estrita seja necessária.
Seja específico com os filtros: os filtros PostToolUse excessivamente amplos podem causar problemas de desempenho.
Teste detalhadamente os ganchos: ganchos que são sempre rejeitados podem gerar loops (mitigados por maxRejections).
Registrar em stderr: use stderr para a saída de depuração. O sistema interpreta stdout como o resultado do hook.

Tente você mesmo

A captura de tela a seguir mostra um gancho de parada em ação. O agente responde inicialmente com apenas "4", mas o mecanismo rejeita a resposta porque o marcador de conclusão está ausente. Em seguida, o agente continua e adiciona o marcador.

Introdução

Recurso	O que você aprenderá
Configurar ganchos de agente (API)	Configurar conexões usando a API REST v2 e YAML

Capacidade	Como se relaciona
Modos de execução	Os ganchos complementam os controles de segurança do modo de execução. Os modos controlam o que é executado, os ganchos controlam o quão bem ele é executado.
Ferramentas do Python	Crie ferramentas personalizadas que os hooks podem auditar e validar.

Comentários

Esta página foi útil?

Last updated on 2026-03-27