Skip to content
Home › Agentic Architecture & Orchestration

AgentDefinition

Agentic Architecture & Orchestration

Definition

The definition of a subagent's identity, instructions, and capabilities — supplied programmatically via the agents param or on the filesystem as .claude/agents/*.md.

Key points

  • Programmatic (agents param) required fields: description, prompt. Optional: tools (allowed; omit = inherit all), disallowedTools (accepts MCP patterns mcp__server, mcp__server__*, mcp__*), model (fable/opus/sonnet/haiku/inherit/full ID), skills, memory (user/project/local), mcpServers, initialPrompt, maxTurns, background, effort (low/medium/high/xhigh/max/number), permissionMode.
  • Python kwarg is allowed_tools; disallowedTools/mcpServers stay camelCase in Python to match wire format.
  • Filesystem (.claude/agents/*.md) required frontmatter: name (lowercase+hyphens; hooks receive it as agent_type), description. Optional adds isolation (worktree = temp git worktree), color, hooks, permissionMode, etc. Here model defaults to inherit.
  • Three ways to create subagents: (1) agents param; (2) .claude/agents/*.md; (3) built-in general-purpose. Programmatic defs take precedence over filesystem defs of the same name.
  • File precedence (high→low): Managed settings > --agents CLI flag > .claude/agents/ (project) > ~/.claude/agents/ (user) > plugin agents/.
  • Built-in subagents: Explore (read-only; Write/Edit denied), Plan (read-only, plan mode), general-purpose.
  • Model resolution: CLAUDE_CODE_SUBAGENT_MODEL env → per-invocation model → frontmatter model → main model.
  • Tool combos: read-only = Read/Grep/Glob; test = Bash/Read/Grep; code-mod = Read/Edit/Write/Grep/Glob; full = omit tools.

Why it matters for the exam

  • D1 tests that AgentDefinition sets identity/instructions/capabilities, the two definition surfaces, and precedence (programmatic > filesystem; managed > CLI > project > user > plugin).

Common gotchas

  • Filesystem model defaults to inherit, but the effective model still follows the resolution chain (env var wins).
  • Plugin subagents don't support hooks/mcpServers/permissionMode.
  • Subagents don't inherit parent conversation history or system prompt — only their own prompt + Agent tool string + project CLAUDE.md.

See also

Sources

Referenced by