You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Connect Azure DevOps for source code analysis, work item management, and wiki knowledge with OAuth or managed identity authentication.
4
+
ms.topic: conceptual
5
+
ms.service: azure-sre-agent
6
+
ms.date: 03/16/2026
7
+
author: craigshoemaker
8
+
ms.author: cshoe
9
+
ms.ai-usage: ai-assisted
10
+
#customer intent: As an SRE, I want to understand Azure DevOps connector capabilities so that I can decide which connector type and authentication method to use for my team's needs.
11
+
---
12
+
13
+
# Azure DevOps connector in Azure SRE Agent
14
+
15
+
Connect Azure DevOps so your agent can search your code, create work items, and index your wiki as a knowledge source.
16
+
17
+
> [!TIP]
18
+
> **Quick overview**
19
+
>
20
+
> - Two connector types: **Azure DevOps OAuth** for live code and work items, **Documentation connector** for wiki knowledge.
> - A single connector covers your entire Azure DevOps organization, including all projects and repos.
23
+
> - Wiki content is indexed for semantic search and autosyncs every 24 hours.
24
+
25
+
## Two connector types
26
+
27
+
Azure DevOps has two connector types because they serve different purposes.
28
+
29
+
| Connector | What it does | Auth options |
30
+
|---|---|---|
31
+
|**Azure DevOps OAuth**| Live source code access, work items, pipelines, semantic code search | User account (OAuth) or Managed identity |
32
+
|**Documentation connector**| Indexes wiki pages and docs into a searchable knowledge base | Managed identity or PAT |
33
+
34
+
You can use both together. Use the OAuth connector for live code investigations and the documentation connector for wiki-based knowledge.
35
+
36
+
## Azure DevOps OAuth connector
37
+
38
+
The OAuth connector gives your agent live access to source code, work items, and pipelines across your entire Azure DevOps organization.
39
+
40
+
### Authentication types
41
+
42
+
Choose the authentication method that fits your team's needs.
43
+
44
+
| Method | How it works | Best for |
45
+
|---|---|---|
46
+
|**User account**| Sign in with your Microsoft Entra ID account. The agent accesses Azure DevOps through your permissions. Tokens refresh automatically. | The interactive setup is recommended for most users |
47
+
|**Managed identity**| Use the agent's managed identity to authenticate. Supports Federated Identity Credentials (FIC) for cross-tenant access. | Automated setup, service accounts, cross-tenant access |
48
+
49
+
> [!TIP]
50
+
> **OAuth tokens refresh automatically**
51
+
>
52
+
> Azure DevOps OAuth tokens expire after approximately one hour, but your agent refreshes them automatically before expiration using a 5-minute buffer. Each refresh generates a new refresh token, creating a self-sustaining renewal chain. Your connector stays connected through multihour investigations with no manual reauthentication required.
53
+
>
54
+
> **When you need to reauthenticate:** if the refresh token expires (lifetime varies by Microsoft Entra ID policy), if an admin revokes the app authorization, or if you set up your connector before version 26.2.247.0 (one reauthentication enables autorefresh going forward).
55
+
56
+
### What the agent can do
57
+
58
+
The OAuth connector gives your agent the following capabilities.
59
+
60
+
**Source code analysis:**
61
+
62
+
- Search code across all repos in your organization by using the Azure DevOps Search API.
- Perform semantic code searches to find code related to an incident by using natural language.
66
+
67
+
**Work item management:**
68
+
69
+
- Create work items (Task, Bug, Epic, Feature) with area path, iteration, priority, and severity.
70
+
- Link work items to Azure resources for traceability.
71
+
72
+
**Repository mapping:**
73
+
74
+
- Find and link Azure Repos to Azure resources.
75
+
- Identify infrastructure-as-code files (Bicep, Terraform, ARM templates) in linked repos.
76
+
77
+
## Documentation connector (wiki knowledge)
78
+
79
+
Index your Azure DevOps wiki pages so your agent can search them during investigations. When your agent encounters an issue, it searches your indexed wiki for relevant troubleshooting guides, architecture docs, and runbooks.
80
+
81
+
### How it works
82
+
83
+
The documentation connector processes your wiki content through the following steps:
84
+
85
+
1.**Crawls** all pages from your specified Azure DevOps wiki URL (or a specific subsection).
86
+
1.**Chunks and embeds** document content into a vector search index.
87
+
1.**Semantic search** - during investigations, your agent finds relevant passages and cites the original wiki page.
88
+
1.**Auto-syncs every 24 hours** to pick up wiki updates.
89
+
90
+
### Supported content
91
+
92
+
The documentation connector supports the following content types:
description: Intercept and control agent behavior with custom scripts or LLM-based validation that runs before or after specific agent actions.
4
4
ms.topic: concept-article
5
5
ms.service: azure-sre-agent
6
-
ms.date: 03/09/2026
6
+
ms.date: 03/18/2026
7
7
author: craigshoemaker
8
8
ms.author: cshoe
9
9
ms.ai-usage: ai-assisted
@@ -13,7 +13,7 @@ ms.custom: hooks, agent hooks, stop hook, post tool use, validation, audit, poli
13
13
14
14
# Agent hooks in Azure SRE Agent
15
15
16
-
Hooks are custom checkpoints that intercept and control agent behavior at key moments. Use hooks to enforce quality gates on agent responses, audit and control tool usage, block dangerous operations with policy enforcement, and prevent early task completion by validating agent output.
16
+
Hooks are custom checkpoints that intercept and control agent behavior at key moments. Use hooks to enforce quality gates on agent responses, audit and control tool usage, block dangerous operations by enforcing policies, and prevent early task completion by validating agent output.
|**PostToolUse**| A tool finishes executing successfully | Audit usage, block results, inject extra context |
48
+
49
+
### Two levels of hooks
50
+
51
+
Hooks operate at two levels:
52
+
53
+
| Level | Where to configure | Scope |
54
+
|-------|--------------------|-------|
55
+
|**Agent level**|**Builder → Hooks** in the portal | Applies to the entire agent including all threads and all custom agents |
56
+
|**Custom agent level**|**Agent Canvas → Custom agent → Manage Hooks**, or via the REST API v2 | Applies only when that specific custom agent runs |
57
+
58
+
Both levels can coexist. If an agent-level hook and a custom-agent-level hook both match the same event, **both run**. The agent-level hooks fire first.
48
59
49
60
### Execution types
50
61
@@ -55,11 +66,11 @@ You can implement hooks by using either an LLM or a shell script:
55
66
|**Prompt**| An LLM evaluates your prompt and returns a JSON decision | Nuanced validation ("Is this response complete?") |
56
67
|**Command**| A bash or Python script runs in a sandboxed environment | Deterministic checks, policy enforcement, auditing |
57
68
58
-
**Prompt hooks** are powerful for subjective evaluation, such as checking if a response addresses all user concerns or verifying that an investigation was thorough enough. They use the `$ARGUMENTS` placeholder to receive the full hook context. If `$ARGUMENTS` isn't present in the prompt, the context is appended automatically. Prompt hooks also receive `ReadFile` and `GrepSearch` tools when a conversation transcript is available, which lets the LLM reason about the full conversation history.
69
+
**Prompt hooks** are powerful for subjective evaluation, such as checking if a response addresses all user concerns or verifying that an investigation was thorough enough. They use the `$ARGUMENTS` placeholder to receive the full hook context. If `$ARGUMENTS` isn't present in the prompt, the context is appended automatically. When a conversation transcript is available, prompt hooks also receive `ReadFile` and `GrepSearch` tools, which let the LLM reason about the full conversation history.
59
70
60
71
**Command hooks** are better for deterministic checks, such as validating that a response contains required markers, blocking dangerous commands, or logging tool usage to an external system.
61
72
62
-
## What makes this different
73
+
## What makes this approach different
63
74
64
75
The following table compares agent behavior with and without hooks.
65
76
@@ -83,21 +94,15 @@ Hooks don't replace run mode safety controls - they complement them. Run modes c
83
94
84
95
## Configure hooks
85
96
86
-
Hooks require the **v2 YAML format** (`api_version: azuresre.ai/v2`, `kind: ExtendedAgent`). Define hooks under `spec.hooks` in the agent configuration.
97
+
The easiest way to create hooks is through the portal UI:
87
98
88
-
> [!WARNING]
89
-
> The portal's Subagent builder YAML tab displays agent configuration in **v1 format only**. It doesn't show or support editing hooks. To configure hooks, use the **REST API v2** endpoint:
90
-
>
91
-
> ```
92
-
> PUT /api/v2/extendedAgent/agents/{agentName}
93
-
> Content-Type: application/json
94
-
> ```
95
-
>
96
-
> Hooks configured through the API are active even though they don't appear in the portal YAML view. You can verify hooks are working by testing the agent in the portal's **Test playground**.
97
-
>
98
-
> :::image type="content" source="media/agent-hooks/hooks-portal-v1-limitation.png" alt-text="Screenshot of the portal YAML tab showing v1 format without hooks." lightbox="media/agent-hooks/hooks-portal-v1-limitation.png":::
99
+
1.**Agent-level hooks:** Go to **Builder** → **Hooks** → select **Create hook**.
100
+
2.**Custom-agent-level hooks:** Go to **Agent Canvas** → select a custom agent → **Manage Hooks**.
101
+
102
+
> [!TIP]
103
+
> You can also configure hooks through **REST API v2** by using `PUT /api/v2/extendedAgent/agents/{agentName}`. The YAML format in the following section shows the full configuration schema. To learn more, see the [API tutorial](tutorial-agent-hooks.md).
99
104
>
100
-
> The portal YAML tab displays v1 format. Hooks aren't visible here but are active on the server.
105
+
> The **Agent Canvas YAML** tab displays v1 format and doesn't show hooks. Use the **Hooks** page under **Builder** to view and manage hooks.
101
106
102
107
The following example shows a complete hook configuration:
103
108
@@ -168,7 +173,7 @@ Command hooks can also use exit codes instead of JSON output:
168
173
|---|---|
169
174
|`0` with no output | Allow (no objection) |
170
175
|`0` with JSON | Parse JSON for decision |
171
-
|`2`| Always block — stderr becomes the reason |
176
+
|`2`| Always block. stderr becomes the reason |
172
177
| Other | Uses `failMode` setting (`allow` or `block`) |
173
178
174
179
> [!CAUTION]
@@ -252,7 +257,7 @@ The following limits apply to agent hooks.
252
257
253
258
## Example: Audit all tool usage
254
259
255
-
The following PostToolUse hook logs every tool call and injects an audit context message:
260
+
The following PostToolUse hook logs every tool call and adds an audit context message:
256
261
257
262
```yaml
258
263
hooks:
@@ -279,7 +284,7 @@ hooks:
279
284
print(json.dumps(output))
280
285
```
281
286
282
-
The `additionalContext` field is injected as a user message into the conversation, giving the agent visibility into the audit trail.
287
+
The `additionalContext` field is added as a user message into the conversation, giving the agent visibility into the audit trail.
283
288
284
289
## Example: Require a completion marker
285
290
@@ -308,25 +313,28 @@ hooks:
308
313
309
314
Follow these guidelines when you configure agent hooks:
310
315
311
-
1. **Always provide a reason when rejecting** — Rejections without reasons are treated as approvals.
1. **Be specific with matchers**:Overly broad PostToolUse matchers can cause performance problems.
320
+
1. **Test hooks thoroughly**:Hooks that always reject can cause loops (mitigated by `maxRejections`).
321
+
1. **Log to stderr**: Use stderr for debugging output. The system parses stdout as the hook result.
317
322
318
323
## Try it yourself
319
324
320
325
The following screenshot shows a Stop hook in action. The agent initially responds with just "4", but the hook rejects the response because the completion marker is missing. The agent then continues and adds the marker.
321
326
322
327
:::image type="content" source="media/agent-hooks/hooks-stop-hook-working.png" alt-text="Screenshot showing a Stop hook in action where the agent response is decorated with a completion marker after hook rejection." lightbox="media/agent-hooks/hooks-stop-hook-working.png":::
0 commit comments