Edit

Tutorial: Configure agent hooks (API) in Azure SRE Agent

Tip

Prefer the portal UI? You can now create and manage hooks directly in the portal without using the REST API. The portal provides a visual form and code editor. No curl commands are required.

In this tutorial, you create a custom agent with a Stop hook that forces the agent to add a completion marker to every response. You configure the hook through the REST API, then test it in the portal's playground.

Estimated time: 15 minutes

Note

Agent-level vs. custom-agent-level hooks: This tutorial creates hooks on a custom agent (custom-agent-level hooks). These hooks only fire when that specific custom agent runs.

To create agent-level hooks that apply to the entire agent (all threads, all custom agents), use Builder > Hooks in the portal.

Level How to create Scope
Agent level Portal: Builder > Hooks Applies to all threads and custom agents
Custom agent level REST API (this tutorial) or Portal: Agent Canvas > Custom agent > Manage Hooks Applies only to one custom agent

In this tutorial, you learn how to:

  • Create a custom agent with a Stop hook using the REST API
  • Test hook behavior in the portal's Test playground
  • Add a PostToolUse hook for auditing tool usage
  • Block dangerous commands with a policy hook

Prerequisites

  • An Azure SRE Agent in Running state
  • curl to call the REST API
  • Azure CLI logged in (az login) to get an access token

Understand the hook API format

This tutorial uses the REST API v2 to create hooks on a custom agent. The portal's YAML editor tab shows v1 format and doesn't display hooks configured via the API, but the hooks are still active. You can verify them in the Builder > Hooks page or the Test playground.

Tip

When to use the API vs the portal:

  • Portal (Builder > Hooks): Best for agent-level hooks in visual form. No code is necessary.
  • API (this tutorial): Best for custom-agent-level hooks, CI/CD pipelines, or programmatic management.

Find your agent's API URL

Your agent's API base URL follows this pattern:

https://{agent-name}--{hash}.{hash}.{region}.azuresre.ai

To find it:

  1. Open sre.azure.com and select your agent.
  2. In the left sidebar, select Builder > Agent Canvas.
  3. Open your browser's Developer Tools (F12 or right-click > Inspect).
  4. Go to the Network tab, filter by "api", and look for requests to a URL ending in .azuresre.ai.
  5. The base URL is everything before /api/....

Alternatively, check the src attribute in the Elements tab. Look for an