Chapter 6: Defining Your Agent — Name, System Prompt, Model, Effort

By the end of this chapter, you will know every field in the agent configuration, how to write an effective system prompt, and how to version and update agents without breaking running sessions.

The Big Idea

An agent definition is a document. It says who this agent is, what it's supposed to do, which model powers it, and what tools it can use. Every session you run references this document.

Getting the agent definition right is the highest-leverage thing you'll do in Managed Agents. A well-crafted system prompt can take an agent from producing mediocre work to producing genuinely excellent work on the same task. A poorly defined agent will frustrate you with erratic behavior no matter how good the underlying model is.

According to the agent setup documentation, an agent is "a reusable, versioned configuration that defines persona and capabilities. It bundles the model, system prompt, tools, MCP servers, and skills that shape how Claude behaves during a session."

This chapter goes field by field through the agent configuration so you understand what every knob does.

The Analogy

Writing an agent definition is like writing a hire profile and an orientation manual in one document.

The hire profile covers: what's this person's specialty, what tools do they have access to, what model are we asking them to run on. That's the model, tools, and name fields.

The orientation manual covers: here's how we work, here's what matters, here's how to handle situations that come up. That's the system field — the system prompt.

Most teams spend ten minutes on the hire profile and rush the orientation manual. Then they wonder why their new hire keeps doing things their own way. A detailed, specific orientation manual produces reliably good work. A vague one produces erratic surprises.

Write the system prompt like you're writing an orientation manual for someone brilliant but new. Don't tell them what kind of person to be. Tell them specifically how to approach the work, what good output looks like, and what to do when they're uncertain.

How It Actually Works

The Full Configuration Fields

From the agent setup documentation:

name — More Useful Than You Think

The name isn't just cosmetic. It appears in logs, in the Console, and in the response objects your code handles. Use a name that's meaningful at a glance: "Marketing Copy Agent" is useful; "Agent 1" is not.

If you build multiple agents for different use cases, consistent naming conventions make them manageable. A pattern like "{function}-{version}" or "{team}-{purpose}" works well at scale.

model — Two Formats

The model field can be passed as a simple string ID or as an object:

• Simple: 'claude-opus-4-7'
• With speed mode: {"id": "claude-opus-4-6", "speed": "fast"}

The speed: fast option is a Research Preview for Opus 4.6 specifically. It uses dedicated rate limits separate from standard Opus rate limits. (Agent setup)

The default speed is "standard". The response object echoes the speed field so you can confirm what mode is active.

system — Where Quality Is Made

The system prompt is distinct from user messages. Per the agent setup docs: "The system prompt is distinct from user messages, which should describe the work to be done."

This separation matters architecturally. The system prompt defines who the agent is and how it works. The user message describes the specific task for this session. Keep them separate in your thinking.

What to put in the system prompt:

• The agent's role and specialty ("You are a financial analysis agent...")
• Output format preferences ("Always structure reports with: Executive Summary, Key Findings, Recommendations")
• Working style ("Before writing any code, outline your approach in plain English")
• Error handling preferences ("If you're unsure about a data source, note the uncertainty explicitly")
• Things to avoid ("Never delete files without confirming with the user first")

What NOT to put in the system prompt:

• The specific task (that goes in the user message)
• Credentials or secrets (those go in vaults)
• Instructions so long they fill the entire context window

On sparse vs. detailed prompts:

The Quickstart example uses a deliberately minimal system prompt:

"You are a helpful coding assistant. Write clean, well-documented code."

The cookbook documentation explains: "The system prompt is deliberately sparse. We want the agent to figure out the iterate loop for itself rather than follow a step-by-step script, the test output makes the task obvious enough without further hand-holding."

This is good guidance for simple, well-defined tasks. For complex workflows with multiple sub-tasks or specific output requirements, a more detailed system prompt produces more consistent results. Use your prototype runs to calibrate how much guidance your agent needs.

tools — What the Agent Can Do

The tools field defines the agent's capabilities. The most important value here is the built-in toolset identifier agent_toolset_20260401, which enables all eight built-in tools by default. Chapter 7 covers each tool in detail.

tools:
  - type: agent_toolset_20260401

Custom tools and MCP tools also go here. They're covered in their respective chapters.

Versioning: How Updates Work

Every time you update an agent, a new version is created. The version counter increments from 1. According to the agent setup documentation:

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."

Update semantics you need to know:

• Omitted fields are preserved. You only need to include fields you're changing. To update just the system prompt, pass only --system.
• Array fields (tools, mcp_servers, skills) are fully replaced. If you pass a new tools array, it replaces the old one entirely. To add a tool, include all existing tools plus the new one.
• metadata is merged. Pass new keys to add them; pass existing keys to update them; omit keys to preserve them. Set a key to an empty string to delete it.
• No-op detection. If the update produces no change, no new version is created. The existing version is returned.

Pinning Sessions to a Version

By default, client.beta.sessions.create(agent=agent.id, ...) uses the latest agent version. To pin to a specific version:

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

"This lets you control exactly which version runs and stage rollouts of new versions independently." (Sessions)

This is critical for production deployments: update the agent with a new system prompt, test on a few sessions pinned to the new version, then roll out broadly once you've confirmed it works.

Archiving Agents

When you archive an agent, it becomes read-only. New sessions cannot reference it, but existing sessions continue to run. (Agent setup)

ant beta:agents archive --agent-id "$AGENT_ID"

Use archiving rather than deletion when you're retiring an agent that has active sessions or historical data you want to preserve.

Agent Response Object — What You Get Back

When you create or retrieve an agent, the response includes these fields beyond your configuration:

• id — e.g., "agent_01HqR2k7vXbZ9mNpL3wYcT8f"
• type — always "agent"
• version — starts at 1, increments on each update
• created_at and updated_at — ISO timestamps
• archived_at — null until archived

(Agent setup)

Chapter Recap

• The agent definition bundles model, system prompt, tools, MCP servers, skills, and metadata into a reusable, versioned configuration. Create it once; reference it by ID for every session.
• The system prompt is the highest-leverage element. Treat it like an orientation manual: specific about behavior and output quality, separate from task-specific instructions.
• Updates create new versions automatically. Pass the current version number to update calls to avoid race conditions. Pin sessions to specific versions for controlled rollouts.