# pm_agent
{{< badge content="Vanguard" color="blue" class="tier-badge" >}}

The `pm_agent` tool manages the agent registry — identities that can execute tasks, run reviews, orchestrate sprints, or plan work. Each agent has a `handle` (stable identifier), a `defaultRole`, a set of `capabilities`, `prompts` bindings, and optional `tags` and `notes`.

## Actions

`create`, `get`, `list`, `update`, `delete`, `get_prompt`, `help`

---

## create

Create a new agent.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `name` | string | Yes | Human-readable name (max 120 chars) |
| `handle` | string | Yes | Stable identifier (max 120 chars, e.g., `"sigrid"`) |
| `kind` | string | No | Agent kind: `bot`, `ci`, or `human` |
| `defaultRole` | string | No | One of: `planner`, `executor`, `reviewer`, `auditor`, `orchestrator` |
| `tags` | string[] | No | Freeform tags |
| `notes` | array | No | Array of `{ noteType, body }` |
| `capabilities` | array | No | Array of `{ key, category? }` |
| `prompts` | array | No | Array of `{ promptId or promptKey, useFor? }` |

**Note type values:** `alert`, `coordination`, `preference`, `status`, `summary`

### Example

```text
pm_agent {
  action: "create",
  name: "Sigrid the Reviewer",
  handle: "sigrid",
  kind: "bot",
  defaultRole: "reviewer",
  capabilities: [
    { key: "review.quality-gate", category: "core" },
    { key: "review.findings-classification", category: "workflow" }
  ],
  prompts: [
    { promptKey: "reviewer.system", useFor: "system" }
  ]
}
```

---

## get

Fetch an agent by ID or handle.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `id` | string | One of |
| `handle` | string | One of |

Returns the full agent record with capabilities, prompts, notes, and tags.

---

## list

List agents with optional filters.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `kinds` | string[] | No | Filter by kind |
| `defaultRoles` | string[] | No | Filter by role |
| `capabilityKeys` | string[] | No | Agents with these capabilities |
| `search` | string | No | Search text |
| `limit` | number | No | 1–200 |

### Example

```text
pm_agent {
  action: "list",
  defaultRoles: ["reviewer", "auditor"],
  limit: 20
}
```

---

## update

Update an existing agent. Collection updates use operation-specific patch semantics.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `id` / `handle` | string | Yes |
| `name` | string | No |
| `newHandle` | string | No |
| `kind` | string | No |
| `defaultRole` | string | No |
| `tags` | object or array | No |
| `notes` | object or array | No |
| `capabilities` | object or array | No |
| `prompts` | object or array | No |

Collection patch shapes:

- `tags`: full replacement array, or `{ set?, add?, remove? }`
- `notes`: full array to add multiple notes, or `{ add?, remove? }`
- `capabilities`: full replacement array, or `{ set?, remove? }`
- `prompts`: full replacement array, or `{ set?, remove? }`

```text
pm_agent {
  action: "update",
  handle: "sigrid",
  capabilities: {
    set: [
      { key: "review.quality-gate", category: "core" },
      { key: "review.security-checklist", category: "workflow" }
    ],
    remove: ["review.old-checklist"]
  }
}
```

---

## delete

Delete an agent. **Destructive.**

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `id` | string | Yes |

Returns deletion impact metrics: `deletedCapabilities`, `deletedPromptBindings`, `deletedNotes`, `nullifiedTaskAssignees`, etc.

{{< callout type="warning" >}}
Deletion is **blocked** if the agent owns projects or sprints. Transfer ownership before deleting.
{{< /callout >}}

---

## get_prompt

Build and fetch the full system prompt for an agent — the actual text the agent receives when launched. This is the combined system prompt, identity, and capability set the launcher assembles.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `id` / `handle` | string | Yes | |
| `capabilityKeys` | string[] | No | Subset of capabilities to include |

Use this to inspect exactly what your agent will see, or to preview the prompt with a specific capability subset.

---

## help

```text
pm_agent { action: "help" }
```

## Related

- [pm_capability](../capabilities/) — capabilities that attach to agents
- [pm_prompt](../prompts/) — prompts bound to agents
- [pm_session](../sessions/) — launch sessions with an agent via `agentHandle`