Ganchos de Agente no Agente SRE do Azure

Os ganchos são pontos de controlo personalizados que intercetam e controlam o comportamento dos agentes em momentos-chave. Use ganchos para impor portas de qualidade nas respostas dos agentes, auditar e controlar a utilização de ferramentas, bloquear operações perigosas aplicando políticas e impedir a conclusão antecipada da tarefa ao validar a saída do agente.

O problema

O seu agente executa tarefas de forma autónoma – investigar incidentes, executar ferramentas e gerar respostas. Mas autonomia sem supervisão cria risco:

• Respostas incompletas: O agente diz "feito" antes de responder a tudo o que pediu.
• Utilização de ferramentas não auditadas: Não tens visibilidade sobre quais ferramentas o agente chama ou que resultados obtém.
• Sem aplicação de políticas: Operações perigosas (comandos destrutivos, alterações não autorizadas) prosseguem sem controlo.
• Lacunas de qualidade: As respostas falham informação crítica porque não há passo de validação.

É preciso uma forma de intercetar o comportamento dos agentes em momentos-chave sem o abrandar ou retirar completamente a sua autonomia.

Como funcionam os ganchos de agente

Os ganchos são pontos de controlo personalizados que associas a eventos específicos de agentes. Quando um evento é disparado, o seu gancho de código avalia a situação e decide se permite ou bloqueia 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

Atualmente, são suportados dois hook events:

Dois níveis de ganchos

Os ganchos operam em dois níveis:

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

Tipos de execução

Podes implementar hooks usando um LLM ou um script shell:

Os ganchos de prompt são poderosos para avaliação subjetiva, como verificar se uma resposta aborda todas as preocupações dos utilizadores ou verificar se a investigação foi suficientemente minuciosa. Utilizam o marcador $ARGUMENTS para receber o contexto completo do hook. Se $ARGUMENTS não estiver presente no prompt, o contexto é adicionado automaticamente. Quando uma transcrição de conversa está disponível, os ganchos de prompt também têm acesso a ferramentas ReadFile e GrepSearch, que permitem ao LLM analisar o histórico completo da conversa.

Os 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 registar o uso de ferramentas num sistema externo.

O que torna esta abordagem diferente

A tabela seguinte compara o comportamento dos agentes com e sem ganchos.

Os ganchos não substituem os controlos de segurança do modo de execução – eles complementam-nos. Os modos de execução controlam o que o agente pode fazer. Os ganchos controlam o desempenho e o que acontece com os resultados.

Antes e depois

Configurar ganchos

A forma mais fácil de criar ganchos é através da interface do portal:

1. Ganchos ao nível do agente: Vai a Builder → Hooks → seleciona Criar gancho.
2. Ganchos ao nível de agente personalizado: Vá ao Agent Canvas → selecione um agente personalizado → Gerir Ganchos.

O exemplo seguinte mostra uma configuração completa do gancho:

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 têm de produzir JSON. São suportados dois formatos.

Formato simples (recomendado para ganchos de estímulo):

{"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:

Referência de configuração

A tabela seguinte descreve todas as opções disponíveis de configuração de ganchos.

Esquema de contexto de gancho

Os ganchos recebem contexto JSON estruturado sobre o evento atual. Os hooks de prompt recebem contexto através do espaço reservado $ARGUMENTS no texto do prompt. Os hooks de comando recebem contexto como JSON em stdin.

Para ambos os tipos de hooks, o campo execution_summary contém um caminho de ficheiro para a transcrição da conversa (não conteúdo inline). Para ganchos em prompts, o LLM recebe ReadFile e GrepSearch como ferramentas para aceder a este ficheiro. Para ganchos de comando, o ficheiro 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 de gancho para parar

Os ganchos de paragem recebem informações adicionais sobre a saída final do agente.

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

PostToolUse campos de ganchos

Os ganchos PostToolUse recebem campos extra sobre a execução da ferramenta.

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

Limits

Os seguintes limites aplicam-se aos ganchos de agente.

Exemplo: Auditar toda a utilização de ferramentas

O seguinte gancho PostToolUse regista todas as chamadas 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 do utilizador à conversa, dando ao agente visibilidade sobre o registo de auditoria.

Exemplo: Exigir um marcador de conclusão

O seguinte gancho Stop rejeita respostas que não terminam em "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

Melhores práticas

Siga estas orientações ao configurar ganchos de agente:

1. Dê sempre uma razão ao rejeitar. Trate as rejeições sem motivos como aprovações.
2. Configure timeouts adequados: Hooks de longa duração desaceleram a execução do agente.
3. Lidar com erros com elegância: Usar failMode: allow a menos que seja exigida uma aplicação rigorosa.
4. Seja específico com os matchers: O uso excessivo dos matchers PostTool pode causar problemas de desempenho.
5. Testar exaustivamente os ganchos: Ganchos que sempre rejeitam podem causar loops (mitigados por maxRejections).
6. Log to stderr: Utilize o stderr para a saída de depuração. O sistema analisa o stdout como o resultado do gancho.

Experimente você mesmo

A captura de ecrã seguinte mostra um gancho Stop em ação. O agente responde inicialmente apenas com "4", mas o refrão rejeita a resposta porque falta o marcador de conclusão. Em seguida, o agente continua e adiciona o marcador.

Introdução

Conteúdo relacionado