Tutorial: Criar e gerir ganchos no portal

Neste tutorial, crias dois hooks de governação usando o portal: um hook Stop que impõe a formatação dos dados (tabelas markdown com cabeçalhos a negrito) e um hook PostToolUse que bloqueia comandos de shell perigosos. Configuras ganchos tanto ao nível do agente (aplica-se a todos os threads e subagentes) como ao nível do subagente (aplica-se a um subagente específico).

Tempo estimado: 10 minutos

Neste tutorial, aprenderás como:

Pré-requisitos

• Um agente SRE do Azure no estado Em execução
• Função de contribuidor ou superior no recurso SRE Agent

Compreenda onde os ganchos se encontram no portal

Os ganchos funcionam em dois níveis. Compreender esta distinção é um conceito arquitetónico fundamental.

Criar ganchos ao nível do agente

Ganchos a nível de agente aplicam-se a todo o agente, incluindo todas as threads e subagentes. Têm modos de ativação que controlam quando entram em funcionamento.

Abrir a página de Hooks

Siga estes passos para navegar até à página Hooks.

1. Vai a sre.azure.com e escolhe o teu agente.
2. Na barra lateral, expande Builder.
3. Selecione ganchos.

Vês o título Hooks com uma descrição, um botão Criar ganchos e uma grelha de dados vazia (ou uma lista de ganchos existentes).

Crie um gancho de paragem

Um gancho de paragem dispara quando o agente está prestes a dar uma resposta final. Use-o para validar a qualidade da resposta e impor regras de formatação.

1. Selecionar Criar gancho.

2. Preencha os campos do formulário:

   Campo	Valor
   Nome	require-table-format
   Tipo de evento	Parar
   Modo de ativação	Sempre
   Descrição	Assegura que as respostas apresentam dados estruturados como tabelas de marcação com cabeçalhos a negrito

3. Na definição de Hook, mantenha o tipo de Hook definido para Prompt.

4. Mantém o modelo definido para Raciocínio Rápido (por defeito).

5. No editor de Prompts , introduza o seguinte texto:

   Check the agent response below.
   
   $ARGUMENTS
   
   Does the response present any structured data (lists of items, comparisons, metrics) as a markdown table with **bold** column headers?
   If no structured data is present, approve.
   If structured data IS present as a table with bold headers: {"ok": true}
   If structured data is present but NOT formatted as a table: {"ok": false, "reason": "Reformat the structured data as a markdown table with **bold** column headers."}
   

6. Deixe Tempo Limite (sec) em 30, Modo de reprovação em Allow, e rejeições máximas em 3.

7. Selecione Guardar.

O diálogo termina com uma notificação de sucesso. O gancho aparece na grelha de dados com Tipo de Evento Stop e Ativação: Sempre.

Teste o gancho de paragem

Siga estes passos para verificar se o gancho de paragem funciona corretamente.

1. Na barra lateral, selecione Chat.
2. Tipo: Compare os prós e contras de Python vs Go para construir microserviços e selecione Enviar.
3. Veja a resposta do agente:
   • O agente responde inicialmente com uma comparação em texto simples.
   • O gancho Stop avalia e rejeita a resposta porque os dados não estão numa tabela.
   • O agente reformata a sua resposta como uma tabela em markdown com cabeçalhos a negrito.

A resposta final apresenta a comparação como uma tabela formatada semelhante ao seguinte exemplo:

Criar um gancho PostToolUse

Um gancho PostToolUse dispara depois de uma ferramenta terminar a execução. Use-o para auditar o uso de ferramentas, bloquear comandos perigosos ou adicionar contexto extra.

1. Volta a Builder>Hooks.

2. Selecionar Criar gancho.

3. Preencha o formulário:

   Campo	Valor
   Nome	block-dangerous-commands
   Tipo de evento	Uso na Pós-Ferramenta
   Modo de ativação	Sempre
   Descrição	Bloqueia rm -rf, sudo e chmod 777 nos comandos shell
   Tipo de anzol	Comando
   Combinador de ferramentas	Bash\|ExecuteShellCommand

4. Selecione Python como linguagem de script.

5. No editor de scripts, introduza o seguinte 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"}))
   

6. Defina o modo de falha para Bloquear (se o script falhar, o resultado da ferramenta é bloqueado).

7. Selecione Guardar.

Ambos os ganchos aparecem agora na grelha de dados Hooks.

Teste o gancho PostToolUse

Siga estes passos para verificar se o gancho PostToolUse funciona corretamente.

1. Na barra lateral, selecione Chat.
2. Peça ao agente para correr um comando seguro: "echo hello". O gancho permite este comando.
3. Pede ao agente para executar um comando perigoso: "Executar rm -rf /tmp/test". O gancho bloqueia este comando.

O comando seguro corre normalmente. O comando perigoso é bloqueado, e o agente recebe uma mensagem a explicar porquê.

Editar e eliminar ganchos ao nível do agente

Pode modificar ou remover ganchos existentes da grelha de dados do Hooks.

• Edit: Selecione o ícone de edição em qualquer linha de gancho na grelha de dados, modifique os campos e selecione Guardar.
• Eliminar: Selecione a caixa de seleção ao lado dos ganchos que quer remover, selecione Eliminar na barra de ferramentas e confirme.

A grelha de dados reflete imediatamente as suas alterações.

Criar ganchos ao nível do subagente

Configura-se ganchos ao nível do subagente diretamente na definição de um subagente. Aplicam-se apenas quando esse subagente específico está em execução, e não ao agente principal nem a outros subagentes.

Abra o painel de ações do subagente

Siga estes passos para aceder à configuração do hook para um subagente específico.

1. Na barra lateral, expande Construtor e seleciona Construtor de Subagentes.
2. Selecione um subagente existente para o editar, ou selecione Criar para iniciar um novo.
3. No formulário de subagente, desça até à secção Hooks.
4. Selecione Gerir Hooks.

Um painel lateral abre-se com as secções Stop e Utilização da Ferramenta. Se não houver ganchos configurados, vê-se estados vazios com texto de orientação.

Adicionar um gancho a um subagente

Os passos seguintes adicionam um gancho Stop que garante que este subagente responde sempre com uma secção de resumo.

1. No painel Gerir ganchos , selecione Adicionar gancho na parte inferior do painel.

2. No diálogo, preencha o formulário do ponto de integração.

   Campo	Valor
   Tipo de evento	Parar
   Tipo de anzol	Prompt
   Prompt	Check the response below. $ARGUMENTS Does it include a clear summary section at the end? If yes: {"ok": true} If no: {"ok": false, "reason": "Add a Summary section at the end of your response."}
   Tempo morto (segundo)	30
   Modo de falha	Allow
   Máximo de rejeições	3

3. Seleciona Guardar na opção.

4. Selecione Criar (ou Guardar) no subagente para guardar a configuração completa.

O gancho aparece no painel Gerenciar Ganchos , na secção Parar . O formulário do subagente mostra Gerenciar Ganchos (1) no botão.

Gerir ganchos por fio

Ganchos ao nível do agente com ativação Sempre estão ativos em todas as conversas por padrão. Tens de ativar manualmente os ganchos com ativação On Demand por tópico.

Alternar pontos de ativação numa conversa

Siga estes passos para ativar ou desativar ganchos num tópico específico.

1. Abre um tópico de chat .
2. Selecione o + botão no rodapé do chat.
3. Selecionar Gerir ganchos.
4. Ativar ou desativar os hooks para o thread atual.

Podes desativar temporariamente os ganchos Always. Podes ativar ganchos On Demand quando necessário. Não podes ativar ou desativar os hooks de sistema necessários.

As alterações de hooks entram em vigor imediatamente na thread atual.

Troubleshooting

A tabela seguinte lista problemas e soluções comuns quando cria e gere ganchos no portal.

Próximo passo

Conteúdo relacionado

• Visão geral das capacidades dos Agentes Hooks
• Tutorial: Configurar ganchos de agente via API REST
• Modos de execução