Defining an Agent
name, description, system_prompt and allowed_tools.
What an Agent Definition Is
An agent in the Claude Agent SDK is not magic. It is a small, explicit configuration that tells the model who it is and what it is allowed to do.
An AgentDefinition has four core fields:
- name — a short identifier used to route work to this agent
- description — what this agent is for (this is how a coordinator decides to delegate to it)
- system_prompt — the durable instructions that shape behavior
- allowed_tools — the exact set of tools this agent may call
Get these four right and the agent behaves predictably. Get them wrong and you get misrouting, scope creep, and unreliable tool selection.
The Shape of a Definition
Here is the minimal skeleton of an agent definition. Notice that every field carries weight: nothing here is decorative.
The allowed_tools list follows the principle of least privilege — grant only the tools the role actually needs.
agent = AgentDefinition(
name="refund_specialist",
description=(
"Handles customer refund requests after identity "
"verification. Use for billing disputes and order "
"cancellations."
),
system_prompt=(
"You are a careful refund specialist. Always verify "
"the customer's identity before processing anything."
),
allowed_tools=["get_customer", "lookup_order", "process_refund"],
)