# Template 01 — Agent Definition Fill-in-the-Blank

Use this template to define a new Claude Managed Agent from scratch. An agent is the reusable configuration that bundles the model, system prompt, tools, and optional MCP servers or skills. You create it once and reference it by ID every time you start a session.

This template covers every required and optional field in the agent definition, gives you a model-selection rubric so you pick the right Claude model for your cost and complexity needs, and shows you exactly how to construct the tools whitelist so the agent can only do what you intend.

---

## How to Use This Template

1. Read through every `[FILL IN: ...]` placeholder and replace it with your own content.
2. Delete any optional sections you don't need (MCP servers, skills, metadata).
3. Use the **Model Selection Rubric** below to choose the right `model` value before filling in the code block.
4. Paste the finished JSON/CLI block into your terminal or application code.
5. Compare your result to the worked example at the bottom before running it.

---

## Model Selection Rubric

| Your situation | Recommended model | API ID |
|---|---|---|
| Simple, repetitive tasks — classification, routing, short summaries, FAQ answers | Claude Haiku 4.5 | `claude-haiku-4-5-20251001` |
| Most agentic work — multi-step research, code generation, analysis, drafting | Claude Sonnet 4.6 | `claude-sonnet-4-6` |
| Complex reasoning, long-horizon coding, tasks where quality matters more than cost | Claude Opus 4.7 | `claude-opus-4-7` |

**Cost reference (per million tokens, input / output):**
- Haiku 4.5: $1 / $5
- Sonnet 4.6: $3 / $15
- Opus 4.7: $5 / $25

**Rule of thumb:** Start with Sonnet 4.6. Switch down to Haiku if cost is high and quality is acceptable. Switch up to Opus only when Sonnet consistently fails on your benchmark tasks.

---

## Part 1 — Plain-Language Agent Brief

Fill this out first. It forces you to think clearly before touching any code.

```
Agent name: [FILL IN: Short, descriptive name — e.g., "Support Triage Agent"]

One-line purpose:
[FILL IN: One sentence describing exactly what this agent does. Start with a verb.
Example: "Reads incoming support tickets, classifies them by priority and category, and drafts a first-response."]

Target user or system:
[FILL IN: Who or what triggers this agent? A human end-user? An internal ops team member?
An automated webhook from your CRM?
Example: "Customer support team at a 10-person SaaS company"]

What "done" looks like for a typical task:
[FILL IN: Describe the output or end state.
Example: "A Markdown-formatted triage report with: ticket ID, priority level (P1/P2/P3),
category (billing / technical / feature request), suggested assignee, and a draft reply."]

What the agent must NEVER do:
[FILL IN: Hard constraints. These become the <constraints> in your system prompt.
Example: "Must never promise refunds, must never access customer payment data,
must never respond directly to a customer without human review."]
```

---

## Part 2 — System Prompt Skeleton

The system prompt defines persona and constraints. User messages (sent via `user.message` events) describe the specific work to do. Keep them separate.

```
You are [FILL IN: role description — e.g., "a customer support triage specialist"].
[FILL IN: 1-2 sentences on your communication style and expertise level.
Example: "You write clearly and concisely. You are familiar with SaaS billing, onboarding, and technical troubleshooting."]

Your goals:
1. [FILL IN: Primary goal — e.g., "Classify each incoming support ticket by priority (P1/P2/P3) and category."]
2. [FILL IN: Secondary goal — e.g., "Draft a first-response message for the assigned team member to review and send."]
3. [FILL IN: Optional tertiary goal — or delete this line]

Constraints:
- [FILL IN: Hard rule #1 — e.g., "Never promise specific timelines or SLAs."]
- [FILL IN: Hard rule #2 — e.g., "Never access or repeat customer payment information."]
- [FILL IN: Hard rule #3 — or delete this line]
- If you are uncertain about how to proceed, pause and ask a clarifying question rather than guessing.

Output format:
[FILL IN: Describe exactly what Claude should produce. Be specific about structure.
Example: "Always produce a JSON object with keys: ticket_id, priority, category, assignee, draft_reply."]
```

---

## Part 3 — Tools Whitelist

The agent toolset identifier is `agent_toolset_20260401`. All 8 tools are enabled by default. Use the whitelist pattern to start with everything off, then turn on only what you need.

**Built-in tools reference:**

| Tool name | What it does | Enable for this agent? |
|---|---|---|
| `bash` | Runs shell commands in the container | [FILL IN: yes / no] |
| `read` | Reads a file from the local filesystem | [FILL IN: yes / no] |
| `write` | Writes a file to the local filesystem | [FILL IN: yes / no] |
| `edit` | Performs string replacement in a file | [FILL IN: yes / no] |
| `glob` | Finds files by pattern | [FILL IN: yes / no] |
| `grep` | Searches file contents with regex | [FILL IN: yes / no] |
| `web_fetch` | Fetches a URL's content | [FILL IN: yes / no] |
| `web_search` | Searches the web | [FILL IN: yes / no] |

**Whitelist JSON block** — replace `true`/`false` based on the table above:

```json
{
  "type": "agent_toolset_20260401",
  "default_config": { "enabled": false },
  "configs": [
    { "name": "bash",       "enabled": [FILL IN: true or false] },
    { "name": "read",       "enabled": [FILL IN: true or false] },
    { "name": "write",      "enabled": [FILL IN: true or false] },
    { "name": "edit",       "enabled": [FILL IN: true or false] },
    { "name": "glob",       "enabled": [FILL IN: true or false] },
    { "name": "grep",       "enabled": [FILL IN: true or false] },
    { "name": "web_fetch",  "enabled": [FILL IN: true or false] },
    { "name": "web_search", "enabled": [FILL IN: true or false] }
  ]
}
```

---

## Part 4 — Complete Agent Creation (CLI)

Fill in your values and paste this into a terminal with `ANTHROPIC_API_KEY` set.

```bash
ant beta:agents create <<'YAML'
name: [FILL IN: agent name]
description: [FILL IN: one-line description for your own records]
model: [FILL IN: claude-haiku-4-5-20251001 | claude-sonnet-4-6 | claude-opus-4-7]
system: |
  [FILL IN: paste your completed system prompt here, preserving indentation]
tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: false
    configs:
      - name: bash
        enabled: [FILL IN: true or false]
      - name: read
        enabled: [FILL IN: true or false]
      - name: write
        enabled: [FILL IN: true or false]
      - name: edit
        enabled: [FILL IN: true or false]
      - name: glob
        enabled: [FILL IN: true or false]
      - name: grep
        enabled: [FILL IN: true or false]
      - name: web_fetch
        enabled: [FILL IN: true or false]
      - name: web_search
        enabled: [FILL IN: true or false]
metadata:
  owner: [FILL IN: your name or team — e.g., "support-team"]
  version_notes: [FILL IN: brief note — e.g., "initial build"]
YAML
```

**Save the agent ID that is returned.** You will reference it every time you create a session.

---

## Part 5 — Optional: MCP Server and Skills

Only fill these in if your agent needs third-party integrations (via MCP) or domain-specific expertise modules (skills).

### MCP Server (optional)

```yaml
mcp_servers:
  - type: url
    name: [FILL IN: short name — e.g., "github"]
    url: [FILL IN: MCP server URL — e.g., "https://api.githubcopilot.com/mcp/"]
tools:
  # Add this alongside the agent_toolset block:
  - type: mcp_toolset
    mcp_server_name: [FILL IN: must match the name above]
    default_config:
      permission_policy:
        type: always_ask   # safe default for MCP; change to always_allow only after testing
```

### Skills (optional)

```yaml
skills:
  # Anthropic pre-built skill example (xlsx, docx, pptx, pdf):
  - type: anthropic
    skill_id: [FILL IN: xlsx | docx | pptx | pdf]

  # Custom skill example:
  - type: custom
    skill_id: [FILL IN: skill_xxxxx ID from your organization]
    version: latest
```

---

## Worked Example — Customer Support Triage Agent

*Fictional business: Meridian SaaS — a 12-person team running a project management tool. Their support lead, Priya, is building a triage agent to handle the overnight ticket queue.*

### Part 1 — Plain-Language Brief (filled out)

```
Agent name: Meridian Support Triage

One-line purpose:
Reads new Zendesk tickets from a nightly export file, classifies each by
priority and category, and writes a structured triage report for the morning
stand-up.

Target user or system:
Priya's support team (3 people). The agent runs automatically each morning at
6 AM via a cron job that creates a new session and sends the export file.

What "done" looks like:
A JSON file at /workspace/triage_report.json with one entry per ticket:
{ ticket_id, subject, priority, category, suggested_assignee, draft_first_response }

What the agent must NEVER do:
- Access external URLs or the internet (all data is in the uploaded file).
- Modify or delete the input export file.
- Include customer PII (email, full name) in the triage report summary field.
```

### Part 2 — System Prompt (filled out)

```
You are a support triage specialist for Meridian, a project management SaaS.
You write concisely and use plain language. You understand software products,
billing, and onboarding workflows.

Your goals:
1. Read the ticket export file at /workspace/tickets.json and classify each
   ticket by priority (P1 = outage/data loss, P2 = broken feature, P3 = question/request)
   and category (billing / technical / onboarding / feature-request / other).
2. Suggest an assignee based on category (technical → eng-on-call,
   billing → finance, onboarding → success).
3. Write a professional, empathetic draft first-response for each ticket.

Constraints:
- Do not access the internet. All data is in the uploaded file.
- Do not modify or delete /workspace/tickets.json.
- Do not include customer email addresses in the draft response itself.
- If a ticket is ambiguous, classify it P2 and note the ambiguity.
- Pause and ask if you encounter tickets in a language other than English.

Output format:
Write your results to /workspace/triage_report.json as a JSON array. Each
object must have exactly these keys:
ticket_id, priority, category, suggested_assignee, draft_first_response.
```

### Part 3 — Tools Whitelist (filled out)

| Tool name | Enabled? | Reason |
|---|---|---|
| `bash` | no | Not needed; read/write tools cover file operations |
| `read` | yes | Must read the ticket export file |
| `write` | yes | Must write the triage report |
| `edit` | no | No in-place edits required |
| `glob` | no | Single known file path |
| `grep` | no | Claude reads and parses JSON directly |
| `web_fetch` | no | No internet access by design |
| `web_search` | no | No internet access by design |

### Part 4 — CLI Command (filled out)

```bash
ant beta:agents create <<'YAML'
name: Meridian Support Triage
description: Classifies overnight support tickets and writes a triage report.
model: claude-haiku-4-5-20251001
system: |
  You are a support triage specialist for Meridian, a project management SaaS.
  You write concisely and use plain language. You understand software products,
  billing, and onboarding workflows.

  Your goals:
  1. Read the ticket export file at /workspace/tickets.json and classify each
     ticket by priority (P1 = outage/data loss, P2 = broken feature,
     P3 = question/request) and category (billing / technical / onboarding /
     feature-request / other).
  2. Suggest an assignee based on category (technical → eng-on-call,
     billing → finance, onboarding → success).
  3. Write a professional, empathetic draft first-response for each ticket.

  Constraints:
  - Do not access the internet.
  - Do not modify or delete /workspace/tickets.json.
  - Do not include customer email addresses in draft responses.
  - If a ticket is ambiguous, classify it P2 and note the ambiguity.
  - Pause and ask if you encounter tickets in a language other than English.

  Output format:
  Write your results to /workspace/triage_report.json as a JSON array. Each
  object must have exactly: ticket_id, priority, category,
  suggested_assignee, draft_first_response.
tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: false
    configs:
      - name: read
        enabled: true
      - name: write
        enabled: true
metadata:
  owner: priya-support-team
  version_notes: initial build, haiku for cost efficiency
YAML
```

**Why Haiku?** The task is well-defined with a clear schema. Haiku handles classification and templated drafting reliably at one-fifth the cost of Opus.