pm_agent
{"content":"{{\u003c badge content=\"Vanguard\" color=\"blue\" class=\"tier-badge\" \u003e}}\n\nThe `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`.\n\n## Actions\n\n`create`, `get`, `list`, `update`, `delete`, `get_prompt`, `help`\n\n---\n\n## create\n\nCreate a new agent.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `name` | string | Yes | Human-readable name (max 120 chars) |\n| `handle` | string | Yes | Stable identifier (max 120 chars, e.g., `\"sigrid\"`) |\n| `kind` | string | No | Agent kind: `bot`, `ci`, or `human` |\n| `defaultRole` | string | No | One of: `planner`, `executor`, `reviewer`, `auditor`, `orchestrator` |\n| `tags` | string[] | No | Freeform tags |\n| `notes` | array | No | Array of `{ noteType, body }` |\n| `capabilities` | array | No | Array of `{ key, category? }` |\n| `prompts` | array | No | Array of `{ promptId or promptKey, useFor? }` |\n\n**Note type values:** `alert`, `coordination`, `preference`, `status`, `summary`\n\n### Example\n\n```text\npm_agent {\n action: \"create\",\n name: \"Sigrid the Reviewer\",\n handle: \"sigrid\",\n kind: \"bot\",\n defaultRole: \"reviewer\",\n capabilities: [\n { key: \"review.quality-gate\", category: \"core\" },\n { key: \"review.findings-classification\", category: \"workflow\" }\n ],\n prompts: [\n { promptKey: \"reviewer.system\", useFor: \"system\" }\n ]\n}\n```\n\n---\n\n## get\n\nFetch an agent by ID or handle.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `id` | string | One of |\n| `handle` | string | One of |\n\nReturns the full agent record with capabilities, prompts, notes, and tags.\n\n---\n\n## list\n\nList agents with optional filters.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `kinds` | string[] | No | Filter by kind |\n| `defaultRoles` | string[] | No | Filter by role |\n| `capabilityKeys` | string[] | No | Agents with these capabilities |\n| `search` | string | No | Search text |\n| `limit` | number | No | 1–200 |\n\n### Example\n\n```text\npm_agent {\n action: \"list\",\n defaultRoles: [\"reviewer\", \"auditor\"],\n limit: 20\n}\n```\n\n---\n\n## update\n\nUpdate an existing agent. Collection updates use operation-specific patch semantics.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `id` / `handle` | string | Yes |\n| `name` | string | No |\n| `newHandle` | string | No |\n| `kind` | string | No |\n| `defaultRole` | string | No |\n| `tags` | object or array | No |\n| `notes` | object or array | No |\n| `capabilities` | object or array | No |\n| `prompts` | object or array | No |\n\nCollection patch shapes:\n\n- `tags`: full replacement array, or `{ set?, add?, remove? }`\n- `notes`: full array to add multiple notes, or `{ add?, remove? }`\n- `capabilities`: full replacement array, or `{ set?, remove? }`\n- `prompts`: full replacement array, or `{ set?, remove? }`\n\n```text\npm_agent {\n action: \"update\",\n handle: \"sigrid\",\n capabilities: {\n set: [\n { key: \"review.quality-gate\", category: \"core\" },\n { key: \"review.security-checklist\", category: \"workflow\" }\n ],\n remove: [\"review.old-checklist\"]\n }\n}\n```\n\n---\n\n## delete\n\nDelete an agent. **Destructive.**\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `id` | string | Yes |\n\nReturns deletion impact metrics: `deletedCapabilities`, `deletedPromptBindings`, `deletedNotes`, `nullifiedTaskAssignees`, etc.\n\n{{\u003c callout type=\"warning\" \u003e}}\nDeletion is **blocked** if the agent owns projects or sprints. Transfer ownership before deleting.\n{{\u003c /callout \u003e}}\n\n---\n\n## get_prompt\n\nBuild 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.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `id` / `handle` | string | Yes | |\n| `capabilityKeys` | string[] | No | Subset of capabilities to include |\n\nUse this to inspect exactly what your agent will see, or to preview the prompt with a specific capability subset.\n\n---\n\n## help\n\n```text\npm_agent { action: \"help\" }\n```\n\n## Related\n\n- [pm_capability](../capabilities/) — capabilities that attach to agents\n- [pm_prompt](../prompts/) — prompts bound to agents\n- [pm_session](../sessions/) — launch sessions with an agent via `agentHandle`","description":"Manage the agent registry — create agents, bind capabilities and prompts, and build agent system prompts.","title":"pm_agent"}
Vanguard
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
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
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? }
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.
Deletion is blocked if the agent owns projects or sprints. Transfer ownership before deleting.
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
pm_agent { action: "help" }Related
- pm_capability — capabilities that attach to agents
- pm_prompt — prompts bound to agents
- pm_session — launch sessions with an agent via
agentHandle