> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Azure DevOps Boards Tools

> Connect Genesis to Azure DevOps Boards so agents can create, update, read, search, and inspect work items, sprints, boards, comments, history, links, and attachments.

## **Overview**

<Note>
  Before using this tool group, save an Azure DevOps connection as described in
  [Azure DevOps](/docs/Setup/Azure-DevOps). If `connection_id` is omitted, the
  tools use the effective default `azure_devops` connection for the current
  user (My default, then Role default). Actions that need a project use the
  explicit `project` parameter first and otherwise fall back to the connection's
  saved default `project`. When multiple role defaults conflict, pass
  `connection_id` explicitly or set a user default. See
  [Default connection layers](/docs/Setup/Connections#default-connection-layers).
</Note>

### **Tool Name**

```json theme={null}
azure_devops_boards_tools
```

### **Purpose**

The **azure\_devops\_boards\_tools** group integrates Genesis with Azure DevOps
Boards. Create and update work items (including sprint moves), link work items
to each other or to pull requests, read single or batched work item details,
search with structured filters or WIQL, list sprints and boards, read comments
and revision history, inspect links and text attachments, and retrieve sprint
capacity for a specific team iteration. Successful agent writes also record
best-effort observations on the [Requests](/docs/User-Guide/Work-Center) page
when that feature is enabled.

### **Key Features**

<Steps>
  <Step title="Create and update work items" icon="ticket">
    Open new Azure DevOps work items, patch standard fields (including sprint
    moves via `iteration_path`), add comments, and link items to parents,
    children, related work, or pull requests.
  </Step>

  <Step title="Read issue context" icon="file-lines">
    Fetch one work item or up to 100 ids per batch; read comments, revision
    history, grouped links, and text attachments.
  </Step>

  <Step title="Query Boards data" icon="magnifying-glass">
    Find work items with structured filters (`ado_find_work_items`) or
    hand-written WIQL (`ado_search_work_items`).
  </Step>

  <Step title="Explore team structure" icon="table-columns">
    List iterations (sprints), Kanban boards, and backlog levels for a team.
  </Step>

  <Step title="Inspect sprint capacity" icon="chart-line">
    Retrieve team capacity for a specific iteration to support planning.
  </Step>

  <Step title="Track managed work on Requests" icon="clipboard-list">
    When Requests is enabled, agent creates, updates, comments, and links
    through the write tools appear on the Activity tab with deep links back to
    Azure DevOps. [Assignment automation](/docs/Setup/Azure-DevOps-Automation)
    can also poll for work items assigned to the connection identity and open
    orchestrator threads without an explicit agent tool call.
  </Step>
</Steps>

## **Requests page tracking**

When [Requests](/docs/User-Guide/Work-Center) is enabled (`GENESIS_SHOW_WORK`),
successful agent writes through `ado_create_work_item`, `ado_update_work_item`,
and `ado_link_work_items` record observations in the Genesis ticket ledger.
Each tracked row shows the Azure DevOps state, a normalized Genesis lifecycle
state, the agent executor, the Genesis thread when one exists, and a deep link
to the work item in Azure DevOps. Azure DevOps remains the system of record —
ledger emission is observability only and never affects tool success.

* Work items appear when an agent manages them through these write tools, or when
  [Azure DevOps assignment automation](/docs/Setup/Azure-DevOps-Automation)
  picks up a work item assigned to the connection identity. Genesis does not
  bulk-import a backlog.
* `ado_get_work_item` refreshes provider state for items Genesis already tracks;
  read-only lookups never import untracked backlog items.
* Failed writes against an already-tracked item record an error on its timeline;
  failed writes against untracked ids are not imported.
* State changes applied through `state` or `fields={"System.State": ...}` emit
  status-change events; comment-only updates keep the item in a `working` state
  so later observations can close the loop.

See [Requests](/docs/User-Guide/Work-Center) for the Activity and Health tabs
and [Ticket automation endpoints](/docs/Genesis-API/API-Reference#ticket-automation-endpoints)
for the read API.

## **Input Parameters for Each Function**

### **`ado_create_work_item`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`work_item_type`** | String | none | Required. Azure DevOps work item type such as `Task`, `Issue`, `Bug`, `Epic`, or a project-specific type. |
| **`title`** | String | none | Required. Work item title. |
| **`description`** | String | `None` | Optional work item description. |
| **`project`** | String | connection default project when available | Optional Azure DevOps project. |
| **`assigned_to`** | String | `None` | Optional assignee display name or email. |
| **`tags`** | String | `None` | Optional semicolon-separated Azure DevOps tags. |
| **`area_path`** | String | `None` | Optional Azure DevOps area path. |
| **`iteration_path`** | String | `None` | Optional Azure DevOps iteration path. |
| **`priority`** | Integer | `None` | Optional priority value written to `Microsoft.VSTS.Common.Priority`. |
| **`parent_id`** | Integer | `None` | Optional parent work item id. In v1, Genesis returns this as a `next_steps` hint instead of creating the relation automatically. |
| **`fields`** | Object | `None` | Optional map of additional Azure DevOps field reference-name/value pairs. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_update_work_item`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`work_item_id`** | Integer | none | Required. Azure DevOps work item id. |
| **`project`** | String | connection default project when available | Optional Azure DevOps project. Required when `comment` is set unless the connection has a default project (the comments API is project-scoped). Field updates resolve the work item by `work_item_id` without this parameter. |
| **`state`** | String | `None` | Optional new state. |
| **`assigned_to`** | String | `None` | Optional new assignee display name or email. |
| **`iteration_path`** | String | `None` | Optional new iteration path to move the item to a sprint. |
| **`comment`** | String | `None` | Optional comment to add after field updates. |
| **`fields`** | Object | `None` | Optional map of additional Azure DevOps field reference-name/value pairs to update. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

<Note>
  `ado_update_work_item` requires at least one field update or a `comment`.
  When `comment` is set, Genesis posts through the project-scoped comments API —
  pass `project` or save a default `project` on the connection. Write operations
  require a PAT with **Work Items (Read & Write)**; a read-only PAT returns
  `error_type: permission`.
</Note>

### **`ado_link_work_items`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`work_item_id`** | Integer | none | Required. ADO work item id the link is added to. |
| **`link_type`** | String | none | Required. Link kind: `parent` (target becomes this item's parent), `child`, `related`, or `pull_request`. |
| **`target_work_item_id`** | Integer | `None` | Other work item id. Required for `parent`, `child`, and `related` links. |
| **`repo`** | String | `None` | Repository name or id. Required for `pull_request` links. |
| **`pull_request_id`** | Integer | `None` | Pull request id. Required for `pull_request` links. |
| **`comment`** | String | `None` | Optional note stored on the link. |
| **`project`** | String | `None` | Optional ADO project for `pull_request` repo lookup. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

<Note>
  `link_type` semantics: `parent` makes `target_work_item_id` the parent of
  `work_item_id`; `child` makes it a child; `related` adds a plain relation;
  `pull_request` attaches the PR named by `repo` and `pull_request_id` as an
  artifact link. A work item cannot be linked to itself. Requires a PAT with
  **Work Items (Read & Write)**.
</Note>

### **`ado_get_work_item`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`work_item_id`** | Integer | none | Required. Azure DevOps work item id. |
| **`project`** | String | `None` | Optional project parameter kept for signature consistency. |
| **`include_relations`** | Boolean | `false` | Include work item relations in the response. |
| **`include_comments`** | Boolean | `false` | If `true`, expand all work item data (fields, relations, links). Comment text still requires `ado_get_work_item_comments`. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_get_work_items_batch`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`work_item_ids`** | Array of integers | none | Required. Work item ids to fetch (1–100 per call). |
| **`fields`** | Array of strings | `None` | Optional Azure DevOps field reference names to return (for example `System.Title`). Omit for all fields. |
| **`include_relations`** | Boolean | `false` | Include each item's relations. Ignored when `fields` is set. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_search_work_items`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`wiql`** | String | none | Required. WIQL query string. |
| **`project`** | String | connection default project when available | Optional Azure DevOps project. Required for WIQL using the `@Project` macro. |
| **`team`** | String | `None` | Optional Azure DevOps team. Required for WIQL using the `@CurrentIteration` macro. |
| **`top`** | Integer | `50` | Maximum number of work items to return. Genesis clamps the value between `1` and `200`. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

<Note>
  `ado_search_work_items` returns id/url references in `query_result.workItems`
  only. Fetch full fields with `ado_get_work_items_batch`. Invalid WIQL returns
  `error_type: invalid_wiql` with the parser message. For common searches
  (for example "bugs assigned to me"), prefer `ado_find_work_items`.
</Note>

### **`ado_find_work_items`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`work_item_types`** | Array of strings | `None` | Work item types to match, for example `['Bug']` or `['User Story', 'Task']`. |
| **`states`** | Array of strings | `None` | States to match, for example `['Active', 'New']`. |
| **`assigned_to`** | String | `None` | Assignee filter: `'@me'` for the connection's authenticated identity, or a display name/email. |
| **`created_by`** | String | `None` | Creator filter: `'@me'` or a display name/email. |
| **`priority_at_most`** | Integer | `None` | Inclusive priority ceiling, `1` (highest) to `4`; use `2` for high-priority items. |
| **`iteration`** | String | `None` | Iteration path, or `'current'` for the active sprint (requires `team`). |
| **`area_path`** | String | `None` | Area path subtree to search under. |
| **`tags`** | Array of strings | `None` | Match work items carrying any of these tags. |
| **`text_contains`** | String | `None` | Substring matched against title or description. |
| **`created_after`** | String | `None` | Only items created on or after this ISO date (`YYYY-MM-DD`). |
| **`changed_after`** | String | `None` | Only items changed on or after this ISO date (`YYYY-MM-DD`). |
| **`order_by`** | String | `'changed'` | Sort order: `'changed'`, `'created'`, `'priority'`, or `'id'`. |
| **`top`** | Integer | `50` | Maximum number of work items to return. Genesis clamps the value between `1` and `200`. |
| **`include_details`** | Boolean | `true` | When `true`, fetch full fields for matches; when `false`, return id/url references only. |
| **`project`** | String | connection default project when available | Optional Azure DevOps project. |
| **`team`** | String | `None` | Optional Azure DevOps team. Required when `iteration` is `'current'`. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_list_iterations`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`team`** | String | project's default team | Optional Azure DevOps team. |
| **`timeframe`** | String | `None` | Set to `'current'` to return only the active sprint. |
| **`project`** | String | connection default project when available | Optional Azure DevOps project. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_list_boards`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`team`** | String | project's default team | Optional Azure DevOps team. |
| **`project`** | String | connection default project when available | Optional Azure DevOps project. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_list_backlogs`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`team`** | String | project's default team | Optional Azure DevOps team. |
| **`project`** | String | connection default project when available | Optional Azure DevOps project. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_get_work_item_comments`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`work_item_id`** | Integer | none | Required. Azure DevOps work item id. |
| **`top`** | Integer | `None` | Maximum comments per page. Genesis clamps the value between `1` and `200` when set. |
| **`continuation_token`** | String | `None` | Continuation token from a previous page to fetch the next one. |
| **`project`** | String | connection default project when available | Optional Azure DevOps project. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_get_work_item_history`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`work_item_id`** | Integer | none | Required. Azure DevOps work item id. |
| **`top`** | Integer | `None` | Maximum revisions to return. Genesis clamps the value between `1` and `200` when set. |
| **`skip`** | Integer | `None` | Number of revisions to skip (for paging). |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_get_work_item_links`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`work_item_id`** | Integer | none | Required. Azure DevOps work item id. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_download_attachment`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`attachment_id`** | String | none | Required. Attachment id (GUID) from `ado_get_work_item_links`. |
| **`file_name`** | String | `None` | Optional attachment file name hint. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

### **`ado_get_sprint_capacity`**

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`team`** | String | none | Required. Azure DevOps team name. |
| **`iteration`** | String | none | Required. Azure DevOps iteration id. |
| **`project`** | String | connection default project when available | Optional Azure DevOps project. |
| **`connection_id`** | String | default `azure_devops` connection | Optional saved Azure DevOps connection name. |

## **Workflow/How It Works**

1. Configure your effective default `azure_devops` connection in
   [Azure DevOps](/docs/Setup/Azure-DevOps), or pass `connection_id`.
2. Use `ado_create_work_item` to open new tasks, bugs, or other work items.
3. Use `ado_get_work_item`, `ado_get_work_items_batch`, and
   `ado_update_work_item` to inspect and modify existing work (including sprint
   moves with `iteration_path`).
4. Use `ado_link_work_items` to relate work items or attach a pull request;
   use `ado_get_work_item_links` to inspect existing relationships.
5. Use `ado_find_work_items` for structured searches (for example bugs assigned
   to you in the current sprint) or `ado_search_work_items` for hand-written
   WIQL.
6. Use `ado_list_iterations`, `ado_list_boards`, and `ado_list_backlogs` to
   discover team structure; use `ado_get_sprint_capacity` for planning data.
7. Use `ado_get_work_item_comments`, `ado_get_work_item_history`, and
   `ado_download_attachment` for discussion, audit, and attachment context.

## **Examples**

```python theme={null}
# Create a bug in Azure DevOps Boards
ado_create_work_item(
    work_item_type="Bug",
    title="Retry pipeline logs on transient 429 responses",
    project="Platform",
    assigned_to="engineer@example.com",
    tags="incident;platform",
    priority=1,
)
```

```python theme={null}
# Move a work item to a sprint and mark it done
ado_update_work_item(
    work_item_id=42,
    project="Platform",
    iteration_path="Platform\\Sprint 25",
    state="Done",
    comment="Shipped in Sprint 25.",
)
```

```python theme={null}
# Make work item 12 a child of epic 10
ado_link_work_items(
    work_item_id=12,
    link_type="child",
    target_work_item_id=10,
)
```

```python theme={null}
# Attach a pull request to a work item
ado_link_work_items(
    work_item_id=55,
    link_type="pull_request",
    repo="platform-api",
    pull_request_id=123,
    project="Platform",
)
```

```python theme={null}
# Find high-priority bugs assigned to the connection identity
ado_find_work_items(
    work_item_types=["Bug"],
    assigned_to="@me",
    priority_at_most=2,
    project="Platform",
    team="Platform Team",
    top=25,
)
```

```python theme={null}
# Search recent active bugs with WIQL
ado_search_work_items(
    wiql=(
        "SELECT [System.Id], [System.Title], [System.State] "
        "FROM WorkItems "
        "WHERE [System.TeamProject] = @project "
        "AND [System.WorkItemType] = 'Bug' "
        "AND [System.State] <> 'Closed' "
        "ORDER BY [System.ChangedDate] DESC"
    ),
    project="Platform",
    top=25,
)
```

```python theme={null}
# Inspect sprint capacity for one team iteration
ado_get_sprint_capacity(
    team="Platform Team",
    iteration="Platform\\Sprint 24",
    project="Platform",
)
```

## **Output**

* **`ado_create_work_item`** returns the created `work_item`. When `parent_id`
  is supplied and creation succeeds, the response can also include `next_steps`
  that remind the caller to link the parent work item in Azure DevOps.
* **`ado_update_work_item`** returns `success: true` plus the updated
  `work_item` when fields were patched, and `comment` when a comment was added.
* **`ado_link_work_items`** returns `success: true`, the updated `work_item`,
  and the `link` relation that was added.
* **`ado_get_work_item`** returns `work_item` with every system and custom field.
  `include_relations` adds the raw relations array.
* **`ado_get_work_items_batch`** returns `work_items`, `count`, and `missing_ids`
  for ids Azure DevOps did not return (deleted or not visible to the PAT).
* **`ado_search_work_items`** returns the raw Azure DevOps `query_result` whose
  `workItems` are id/url references only. When you pass `project`, Genesis also
  echoes `project` in the response.
* **`ado_find_work_items`** returns `wiql`, `count`, `work_items` (full details
  by default, or id/url references when `include_details` is `false`), and
  optionally `missing_ids` or `detail_fetch_error`.
* **`ado_list_iterations`** returns `iterations` with id, name, path, and
  start/finish dates.
* **`ado_list_boards`** returns `boards` with id, name, and url.
* **`ado_list_backlogs`** returns `backlogs` with id, name, rank, and accepted
  work item types.
* **`ado_get_work_item_comments`** returns `comments`, `count`, `total_count`,
  and `continuation_token` for paging.
* **`ado_get_work_item_history`** returns `revisions` (field snapshots, oldest
  first) and `count`.
* **`ado_get_work_item_links`** returns links grouped as `parent`, `children`,
  `related`, `pull_requests`, `commits`, `attachments`, `hyperlinks`, and
  `other`, plus per-group counts.
* **`ado_download_attachment`** returns `text` (UTF-8, truncated past 100,000
  characters), `size_bytes`, and `truncated`.
* **`ado_get_sprint_capacity`** returns `capacity`.

## **Configuration Details**

* `fields` uses Azure DevOps field reference names such as `System.Title`,
  `System.State`, or `Microsoft.VSTS.Common.Priority`.
* Calls that resolve a project require either an explicit `project` parameter
  or a default `project` on the saved connection.

## **Limitations or Notes**

1. `ado_get_work_item` accepts `project` for signature consistency; the work
   item is resolved by `work_item_id`. On `ado_update_work_item`, `project`
   (or a connection default) is required when `comment` is set because Azure
   DevOps serves the comments API only under a project URL.
2. Comment text is never inlined by `ado_get_work_item` — use
   `ado_get_work_item_comments` for discussion content.
3. `ado_search_work_items` and `ado_find_work_items` (with
   `include_details=false`) return id/url references; fetch full records with
   `ado_get_work_items_batch` (up to 100 ids per call).
4. `ado_find_work_items` with `iteration='current'` requires `team` because
   Azure DevOps resolves the active sprint per team.
5. `ado_download_attachment` reads text attachments only. Binary attachments
   (images, archives, office documents) return an error — open the attachment
   URL in Azure DevOps instead.
6. `parent_id` on `ado_create_work_item` adds a follow-up hint only. Use
   `ado_link_work_items` with `link_type='parent'` or `link_type='child'` to
   create the hierarchy after creation.
7. `ado_update_work_item` and `ado_link_work_items` are write operations. A PAT
   with Work Items read-only access returns `error_type: permission` (Azure
   DevOps may answer with HTTP 401 for insufficient scope).
8. Requests-page tracking is best-effort. Ledger emission is guarded so
   malformed Azure DevOps payloads or ledger unavailability never change tool
   success responses.

## **Related Pages**

* [Azure DevOps](/docs/Setup/Azure-DevOps)
* [Requests](/docs/User-Guide/Work-Center)
* [Azure DevOps Pipelines Tools](/docs/Genbot-Toolkit/Azure-DevOps-Pipelines-Tools)
* [Azure DevOps Wiki Tools](/docs/Genbot-Toolkit/Azure-DevOps-Wiki-Tools)
* [Git Action Tools](/docs/Genbot-Toolkit/Git-Action-Tools)