Tutorial: Criar e gerenciar ganchos no portal

Neste tutorial, você criará dois ganchos de governança usando o portal: um gancho Stop que impõe a formatação dos dados (tabelas markdown com cabeçalhos em negrito) e um gancho PostToolUse que bloqueia os comandos perigosos do shell. Você configura ganchos no nível do agente (aplica-se a todos os threads e subagentes) e ao nível do subagente (aplica-se a um subagente específico).

Tempo estimado: 10 minutos

Neste tutorial, você aprenderá como:

Pré-requisitos

• Um agente SRE do Azure em estado de execução
• FunçãoColaborador ou superior no recurso do Agente SRE

Entender onde os ganchos estão no portal

Os ganchos operam em dois níveis. Entender essa distinção é um conceito de arquitetura fundamental.

Criar ganchos no nível do agente

Os ganchos no nível do agente se aplicam ao agente inteiro, incluindo cada thread e cada subagente. Eles têm modos de ativação que controlam quando estão ativos.

Abrir a página de Hooks

Siga estas etapas para navegar até a página Hooks.

1. Vá para sre.azure.com e selecione seu agente.
2. Na barra lateral, expanda o Construtor.
3. Selecione Hooks.

Você verá o título ganchos com uma descrição, um botão Criar gancho e uma grade de dados vazia (ou uma lista de ganchos existentes).

Criar um gancho de parada

Um gancho de parada é acionado quando o agente está prestes a retornar uma resposta final. Use-a para validar a qualidade da resposta e impor regras de formatação.

1. Selecione Criar gancho.

2. Preencha os campos de formulário:

   Campo	Valor
   Nome	require-table-format
   Tipo de evento	Parar
   Modo de ativação	Sempre
   Descrição	Garante que as respostas apresentem dados estruturados como tabelas de markdown com cabeçalhos em negrito

3. Em Definição de Gancho, mantenha o tipo de gancho definido como Prompt.

4. Mantenha o modelo definido como Raciocínio Rápido (padrão).

5. No editor do Prompt , insira 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 o tempo limite (s) em 30, o modo de falha em Allow, e as rejeições máximas em 3.

7. Clique em Salvar.

A caixa de diálogo é encerrada com uma notificação de êxito. O gancho aparece na grade de dados com o tipo de evento Stop e Ativação Always.

Testar o gancho de parada

Siga estas etapas para verificar se o gancho de parada funciona corretamente.

1. Na barra lateral, selecione Chat.
2. Digite Comparar os prós e contras do Python vs Go para criar microsserviços e selecione Enviar.
3. Assista à resposta do agente:
   • O agente responde inicialmente com uma comparação de texto sem formatação.
   • O gancho de parada avalia e rejeita a resposta porque os dados não estão em uma tabela.
   • O agente reformata sua resposta como uma tabela de markdown com cabeçalhos em negrito .

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

Criar um "hook" para PostToolUse

Um gancho PostToolUse é acionado após a ferramenta concluir a execução. Use-o para auditar o uso da ferramenta, bloquear comandos perigosos ou adicionar contexto extra.

1. Volte para Builder>Hooks.

2. Selecione Criar gancho.

3. Preencha o formulário:

   Campo	Valor
   Nome	block-dangerous-commands
   Tipo de evento	Uso da Ferramenta de Postagem
   Modo de ativação	Sempre
   Descrição	Impede o uso de rm -rf, sudo e chmod 777 em comandos de shell
   Tipo de gancho	Command
   Correlacionador de ferramentas	Bash\|ExecuteShellCommand

4. Selecione Python como a linguagem de script.

5. No editor de Script , insira 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 como Bloquear (se o script falhar, o resultado da ferramenta será bloqueado).

7. Clique em Salvar.

Os dois ganchos agora aparecem na grade de dados Hooks.

Testar o gancho do PostToolUse

Siga estas etapas para verificar se o gancho postToolUse funciona corretamente.

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

O comando seguro é executado normalmente. O comando perigoso é bloqueado e o agente recebe uma mensagem explicando o porquê.

Editar e excluir ganchos no nível de agente

Você pode modificar ou remover os ganchos existentes da grade de dados Ganchos.

• Editar: selecione o ícone de edição em qualquer linha de gancho na grade de dados, modifique os campos e selecione Salvar.
• Excluir: marque a caixa de seleção ao lado dos ganchos que você deseja remover, selecione Excluir na barra de ferramentas e confirme.

A grade de dados reflete imediatamente suas alterações.

Criar ganchos de nível de subagente

Você configura ganchos no nível de subagente diretamente na definição de um subagente. Eles se aplicam somente quando um subagente específico é executado, mas não ao agente principal nem a outros subagentes.

Abrir o painel de ganchos de subagente

Siga estas etapas para acessar a configuração do gancho para um subagente específico.

1. Na barra lateral, expanda o Construtor e selecione o Construtor de Subagentes.
2. Selecione um subagente existente para editá-lo ou selecione Criar para iniciar um novo.
3. No formulário do subagente, role para baixo até a seção Hooks.
4. Selecione Gerenciar Ganchos.

Um painel lateral é aberto com as seções Parar e Uso Posterior da Ferramenta. Se nenhum gancho estiver configurado, você verá estados vazios com texto de orientação.

Adicionar um gancho a um subagente

As etapas a seguir adicionam um gancho de interrupção que garante que esse subagente sempre responda com uma seção de resumo.

1. No painel Gerenciar Ganchos , selecione Adicionar gancho na parte inferior do painel.

2. Na caixa de diálogo, preencha o formulário do gancho:

   Campo	Valor
   Tipo de evento	Parar
   Tipo de gancho	Rápido
   Rápido	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 limite (s)	30
   Modo de falha	Permitir
   Rejeições máximas	3

3. Selecione Salvar no gancho.

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

O gancho é exibido no painel Gerenciar Ganchos na seção Parar . O formulário subagente mostra Gerenciar Ganchos (1) no botão.

Gerenciar os ganchos por thread

Os ganchos no nível de agente com ativação Sempre estão ativos em todas as conversas por padrão. Você deve ativar manualmente os ganchos com a ativação Sob Demanda por segmento.

Alternar os ganchos em uma conversa

Siga estas etapas para ativar ou desativar ganchos em um thread específico.

1. Abra um thread de Chat .
2. Selecione o + botão no rodapé do chat.
3. Selecione Gerenciar Ganchos.
4. Ative ou desative os ganchos para o thread atual.

Você pode desativar temporariamente os ganchos Always . Você pode ativar os ganchos Sob Demanda quando necessário. Você não pode alternar as configurações dos ganchos de sistema necessários.

As alterações de gancho entrarão em vigor imediatamente no thread atual.

Solução de problemas

A tabela a seguir lista problemas e soluções comuns ao criar e gerenciar ganchos no portal.

Próxima etapa

Conteúdo relacionado

• Visão geral da capacidade de integrações de agente
• Tutorial: Configurar ganchos de agente por meio da API REST
• Modos de execução