AgentDefinition
Agent SDKDefinition
The Agent SDK configuration object that blueprints a reusable agent: which model it runs on, what system prompt shapes its behavior, which tools it may call, and what lifecycle hooks fire during its execution. `AgentDefinition` is defined once and can be instantiated many times — each run gets an independent agent instance from the same static configuration. For what a subagent *is*, see [Subagent](/glossary/subagent).
Example Usage
Define a `SecurityAuditAgent` with read-only tools and a conservative system prompt once; reuse that definition across every codebase review without re-specifying model, tool list, or hooks each time.
Why It Matters for the CCA-F Exam
Domain 1 tests `AgentDefinition` in system design questions: which field controls tool access, how definitions enforce least-privilege at configuration time (not runtime), how the definition/instance distinction maps to class/instance in OOP, and how `AgentDefinition` differs from `CLAUDE.md`.
In Depth
AgentDefinition is a schema-first configuration object, and the exam tests it at the field level. The core fields are:
| Field | Type | Purpose |
|---|---|---|
model | string | Which Claude model the agent runs on (e.g. claude-opus-4-8) |
system | string | System prompt that shapes persona, output format, and constraints |
tools | string[] | Allow-list of callable tool names — unlisted tools are inaccessible |
hooks | Hook[] | Lifecycle hooks (PreToolUse, PostToolUse, Stop, SubagentStop, etc.) |
description | string | Human-readable label for logging and observability |
The tools field enforces Least Privilege (Tool Access) at design time, not runtime. If a tool name is not in the allow-list, the running agent cannot access it regardless of what the system prompt says. This means architects can audit tool access by reading definitions — no need to trace runtime logs.
The class/instance analogy is load-bearing for the exam: AgentDefinition is the class (or blueprint); a running agent is an instance created from it. Multiple concurrent agents can share the same definition. The definition is never mutated by a live instance — if you change a field on the definition object after instantiation, already-running agents are unaffected.
A common exam trap is conflating AgentDefinition with CLAUDE.md. They both configure agent behavior, but at different layers: CLAUDE.md configures the Claude Code CLI for a *development workflow* (instructions, memory, hooks for the dev environment); AgentDefinition configures an SDK agent for a *production application* (model choice, tool access, lifecycle hooks for the running system). They are not interchangeable and live in separate parts of the stack.
See the code example below for a minimal but complete AgentDefinition using a TypeScript-style schema, then cross-reference SubagentStop Hook for how lifecycle hooks attach to the definition.
Example
Minimal AgentDefinition for a read-only security auditor. The `tools` array is the allow-list: no tool outside it is accessible at runtime. The `hooks` array wires in PostToolUse logging and SubagentStop result validation. This object is defined once and reused across many audit invocations.
{
"model": "claude-opus-4-8",
"description": "SecurityAuditAgent — read-only, conservative findings",
"system": "You are a security auditor. Report findings conservatively. Cite the exact file and line for every issue. Never suggest fixes — analysis only.",
"tools": ["read_file", "search_code", "list_directory"],
"hooks": [
{ "event": "PostToolUse", "handler": "logToolUse" },
{ "event": "SubagentStop", "handler": "validateAuditSchema" }
]
}Frequently Asked Questions
Can an AgentDefinition be modified after the agent starts running?
`AgentDefinition` is static configuration. Once an agent instance is created from it, the running agent does not reflect subsequent mutations to the definition object. If you need different behavior, create a new definition and a new agent instance.
What is the difference between AgentDefinition tools and MCP server tools?
The `tools` field in `AgentDefinition` is an allow-list of SDK-registered tools (built-in or custom-defined). MCP server tools are exposed via a separate MCP client integration and are surfaced to the model through a different mechanism. Both appear as callable tools in the model's context, but they are configured and registered differently.
If I have 10 subagents all using the same AgentDefinition, is there one system prompt or ten?
Each agent instance gets its own system prompt injected at instantiation time from the definition. There are effectively ten independent copies — the definition is a template, and each instance is separate. Changes to the definition after the fact do not propagate to already-running instances.