Tutorial: Create and manage hooks in the portal

In this tutorial, you create two governance hooks by using the portal: a Stop hook that enforces data formatting (markdown tables with bold headers) and a PostToolUse hook that blocks dangerous shell commands. You configure hooks at both the agent level (applies to all threads and subagents) and the subagent level (applies to one specific subagent).

Estimated time: 10 minutes

In this tutorial, you learn how to:

Prerequisites

• An Azure SRE Agent in Running state
• Contributor role or higher on the SRE Agent resource

Understand where hooks live in the portal

Hooks operate at two levels. Understanding this distinction is a key architectural concept.

Create agent-level hooks

Agent-level hooks apply to the entire agent, including every thread and every subagent. They have activation modes that control when they're active.

Open the Hooks page

Follow these steps to navigate to the Hooks page.

1. Go to sre.azure.com and select your agent.
2. In the sidebar, expand Builder.
3. Select Hooks.

You see the Hooks heading with a description, a Create hook button, and an empty data grid (or a list of existing hooks).

Create a Stop hook

A Stop hook fires when the agent is about to return a final response. Use it to validate response quality and enforce formatting rules.

1. Select Create hook.

2. Fill in the form fields:

   Field	Value
   Name	require-table-format
   Event type	Stop
   Activation mode	Always
   Description	Ensures responses present structured data as markdown tables with bold headers

3. Under Hook Definition, keep Hook type set to Prompt.

4. Keep Model set to Reasoning Fast (default).

5. In the Prompt editor, enter the following text:

   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. Leave Timeout (sec) at 30, Fail mode at Allow, and Max rejections at 3.

7. Select Save.

The dialog closes with a success notification. The hook appears in the data grid with Event type Stop and Activation Always.

Test the Stop hook

Follow these steps to verify the Stop hook works correctly.

1. In the sidebar, select Chat.
2. Type Compare the pros and cons of Python vs Go for building microservices and select Send.
3. Watch the agent's response:
   • The agent initially responds with a plain text comparison.
   • The Stop hook evaluates and rejects the response because the data isn't in a table.
   • The agent reformats its response as a markdown table with bold headers.

The final response presents the comparison as a formatted table similar to the following example:

Create a PostToolUse hook

A PostToolUse hook fires after a tool finishes execution. Use it to audit tool usage, block dangerous commands, or add extra context.

1. Go back to Builder > Hooks.

2. Select Create hook.

3. Fill in the form:

   Field	Value
   Name	block-dangerous-commands
   Event type	Post Tool Use
   Activation mode	Always
   Description	Blocks rm -rf, sudo, and chmod 777 in shell commands
   Hook type	Command
   Tool matcher	Bash\|ExecuteShellCommand

4. Select Python as the script language.

5. In the Script editor, enter the following 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. Set Fail mode to Block (if the script crashes, the tool result is blocked).

7. Select Save.

Both hooks now appear in the Hooks data grid.

Test the PostToolUse hook

Follow these steps to verify the PostToolUse hook works correctly.

1. In the sidebar, select Chat.
2. Ask the agent to run a safe command: "Run echo hello". The hook allows this command.
3. Ask the agent to run a dangerous command: "Run rm -rf /tmp/test". The hook blocks this command.

The safe command runs normally. The dangerous command is blocked, and the agent gets a message explaining why.

Edit and delete agent-level hooks

You can modify or remove existing hooks from the Hooks data grid.

• Edit: Select the edit icon on any hook row in the data grid, modify the fields, and select Save.
• Delete: Select the check box next to the hooks you want to remove, select Delete in the toolbar, and confirm.

The data grid immediately reflects your changes.

Create subagent-level hooks

You configure subagent-level hooks directly in a subagent's definition. They apply only when that specific subagent runs, not to the main agent, or other subagents.

Open the subagent hooks panel

Follow these steps to access hook configuration for a specific subagent.

1. In the sidebar, expand Builder and select Subagent builder.
2. Select an existing subagent to edit it, or select Create to start a new one.
3. In the subagent form, scroll down to the Hooks section.
4. Select Manage Hooks.

A side panel opens with Stop and Post Tool Use sections. If no hooks are configured, you see empty states with guidance text.

Add a hook to a subagent

The following steps add a Stop hook that ensures this subagent always responds with a summary section.

1. In the Manage Hooks panel, select Add hook at the bottom of the panel.

2. In the dialog, fill in the hook form:

   Field	Value
   Event type	Stop
   Hook type	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."}
   Timeout (sec)	30
   Fail mode	Allow
   Max rejections	3

3. Select Save on the hook.

4. Select Create (or Save) on the subagent to save the full configuration.

The hook appears in the Manage Hooks panel under the Stop section. The subagent form shows Manage Hooks (1) on the button.

Manage hooks per thread

Agent-level hooks with Always activation are active in every conversation by default. You must manually activate hooks with On Demand activation per thread.

Toggle hooks in a conversation

Follow these steps to activate or deactivate hooks in a specific thread.

1. Open a Chat thread.
2. Select the + button in the chat footer.
3. Select Manage Hooks.
4. Toggle hooks on or off for the current thread.

You can temporarily deactivate Always hooks. You can activate On Demand hooks when needed. You can't toggle required system hooks.

Hook changes take effect immediately in the current thread.

Troubleshooting

The following table lists common problems and solutions when you create and manage hooks in the portal.

Next step

Related content

• Agent hooks capability overview
• Tutorial: Configure agent hooks via REST API
• Run modes