# Agents The Agents view is your command center for everything that acts in your system—human operators, bots, and CI integrations. Every agent gets a clear identity, composable prompts, and capability assignments that define what it can do and how it behaves. Agents are the unit Valdr reasons about: ownership, behavior, execution history, and audit all attach here. {{< callout type="info" >}} **System Prompt Preview removes the guesswork.** See exactly what your agent receives at launch—prompts, capabilities, and ordering—before you ship. {{< /callout >}} ## What this page covers - Agent registry with kinds, handles, and status filtering - System prompt composition from linked prompts and capabilities - Capability assignment with searchable selection - Notes for coordination, alerts, and status tracking - Inline editing for agent names and handles - Creating new agents with tags and metadata ## Quick start {{% steps %}} ### 1 — Browse the registry Filter agents by kind (human, bot, ci) to find the operator you need. Handles (`@coder-nova`) make agents addressable across your system. ### 2 — Check the system prompt Open any agent and review the **System Prompt Preview** on the Overview tab. This is exactly what the agent receives at launch—no guessing. ### 3 — Assign capabilities Use the searchable Capabilities tab to grant domain-specific behaviors. Capabilities link to playbook prompts that shape how the agent works. ### 4 — Link prompts for context Add system, guide, or checklist prompts on the Prompts tab. These compose with capability playbooks to build the full system prompt. {{% /steps %}} ## Agent kinds and handles Every agent has a **kind** that signals its nature: | Kind | Use case | |------|----------| | `human` | Human operators and reviewers | | `bot` | AI agents and automations that execute tasks autonomously | | `ci` | CI/CD integrations that post results back to PM MCP | **Handles** (e.g., `@valdr-auditor`) make agents addressable in tasks, reviews, and mentions. Once set, handles cannot be cleared—only changed to a new value. > [!TIP] > Use lowercase handles with dashes for consistency: `@coder-nova`, `@security-reviewer`, `@nightly-build`. ## Overview tab: System Prompt Preview The Overview tab shows what matters most: the **fully composed system prompt** that will be sent to the agent at launch time. No more wondering what your agent actually receives. ### Prompt composition order Valdr assembles the system prompt in a fixed, predictable order: 1. **Agent System Charter** — Identity and mission (prompts with `system` context) 2. **Guidance** — Operational instructions (prompts with `guide` context) 3. **Capability Playbooks** — Domain behaviors sorted alphabetically by capability key 4. **Checklists** — Required steps for validation (prompts with `checklist` context) This ordering is deterministic. Capability playbooks sort alphabetically by lowercase key, so naming conventions like `auditor.base`, `auditor.schema`, `auditor.tooling` produce predictable prompt structure. > [!NOTE] > See [Prompt Ordering](/valdr/docs/valdr-packs/prompt-ordering/) for the full specification on how prompts compose and how to control ordering with capability key naming. ### Sidebar widgets The Overview sidebar provides quick access to: - **Tags** — Editable labels for filtering and organization - **Prompts summary** — Count of system, guide, checklist, and capability prompts - **Latest Note** — Most recent coordination or status update - **Activity** — Creation and last update timestamps ## Prompts tab: Direct bindings The Prompts tab manages **direct prompt bindings**—prompts linked to the agent outside of capabilities. Use these for: - **System prompts**: Agent identity, mission, and guardrails - **Guide prompts**: Communication style, tool policies, execution patterns - **Checklist prompts**: Validation steps auditors score against > [!TIP] > Use **direct prompts** for agent-specific identity and workflow. Use **capabilities** for reusable domain behavior shared across agents. ### Linking a prompt {{% steps %}} ### 1 — Search for the prompt Type in the searchable dropdown to find prompts by name or ID. ### 2 — Set contexts Add comma-separated contexts like `system`, `guide`, or `checklist` to control where the prompt appears in composition. ### 3 — Click Link Prompt The binding is saved immediately. The Overview tab updates to show the new system prompt preview. {{% /steps %}} > [!TIP] > Prompts can have multiple contexts. A prompt with `system, guide` appears in both sections of the composed prompt. ## Capabilities tab: Domain behaviors Capabilities encode domain-specific behaviors. Each capability can link to a **playbook prompt** that provides detailed instructions for that capability. ### Assigning capabilities {{% steps %}} ### 1 — Search for capabilities Type in the searchable dropdown. Results filter by key or category, and already-assigned capabilities are excluded. ### 2 — Select from the list Click or press Enter on a highlighted suggestion. Free-text entry is not allowed—you must select a valid capability definition. ### 3 — Click Add Capability The capability is assigned with its linked playbook prompt (if any). The system prompt preview updates automatically. {{% /steps %}} ### Capability naming for ordering Capabilities sort alphabetically by lowercase key. Use dot notation to control grouping and order: ``` auditor.base ← Sorts first (foundation) auditor.prompt_integrity auditor.schema auditor.task_correctness auditor.tooling ← Sorts last in auditor group ``` For explicit ordering, use numeric prefixes: ``` auditor.01_identity auditor.02_instructions auditor.03_guardrails ``` Numeric prefixes affect presentation order only; they do not imply priority, severity, or execution order. ## Notes tab: Coordination and status Notes capture coordination, alerts, and status updates for agents. Each note has a **type** that signals its purpose: | Type | Use case | |------|----------| | `status` | Current state or availability | | `preference` | Working style or preferences | | `alert` | Important notice or warning | | `coordination` | Process coordination or workflow notes | | `summary` | Overview or recap | Notes support **Markdown** for rich formatting. Edit or delete notes with the hover actions on each entry. > [!TIP] > Use `alert` notes to flag agents that are temporarily unavailable or have known issues. The latest note shows on the Overview tab for quick visibility. ## Creating agents Click **Add Agent** from the agent list to register a new operator, bot, or CI integration. Create agents sparingly—start by inspecting and extending existing ones. {{% steps %}} ### 1 — Set primary details Enter the agent name, select a kind, and optionally set a handle. Handles must be lowercase with letters, numbers, and dashes. ### 2 — Add tags Comma-separated tags help with filtering and organization (e.g., `typescript, frontend`). ### 3 — Create The agent is registered immediately. Navigate to the detail view to assign capabilities and link prompts. {{% /steps %}} ## Inline editing Agent names and handles are editable inline on the detail view header: - **Double-click** (or press Enter/Space) to enter edit mode - **Enter** to save, **Escape** to cancel - Names cannot be empty; handles cannot be cleared once set ## Why this matters - **Predictable behavior**: System Prompt Preview shows exactly what agents receive—no guessing, no surprises, no post-deployment mysteries. - **Composable prompts**: Mix system, guide, checklist, and capability prompts without manual concatenation or fragile config files. - **Searchable assignment**: Find and assign capabilities instantly; already-assigned items are excluded so you can't double-assign. - **Audit-ready**: Every agent has clear ownership, typed notes, and traceable capability assignments. - **Full visibility**: See the complete agent configuration in one view—no hunting through scattered config files or prompt directories. ## Next steps - **[Prompt Ordering](/valdr/docs/valdr-packs/prompt-ordering/)** — Deep dive on how prompts compose and how to control ordering with capability key naming - **[Capabilities](/valdr/docs/ui/capabilities/)** — Manage capability definitions and playbook prompts - **[Agent Sessions](/valdr/docs/ui/agent-sessions/)** — See agent activity and execution history