You search "claude agents" hoping for one definition and find three. One result shows an agent configured on the Claude Platform. Another describes Claude working agentically, planning and calling tools until a task is done. A third covers Claude Code subagents. Say you want Claude to triage support tickets: which of these do you actually need?
This article separates the three meanings and gives a concrete example of each. It covers how a subagent is defined in Claude Code, so you can see what that setup looks like in practice. It also explains what drives cost, so you can judge whether an agent fits your task before you build one.
What are Claude agents?
A Claude agent is Claude, Anthropic's AI model, combined with tools and instructions so it can carry out a multi-step task instead of answering a single prompt. The model decides what to do next, uses a tool, reads the result, and continues until the task is done or it needs input.
The term is confusing because people use it for several different things:
- Claude Platform agents: agents that developers build on Anthropic's platform, giving Claude a system prompt, tools, and a defined job such as handling support requests or processing documents.
- Claude Code agents: coding-focused agents that work in a software project, reading files, running commands, and editing code. Some setups let one session hand work to specialized helpers, which is why you will see claude code agents described as both a product and a pattern.
- Agentic use of Claude: a looser meaning. Any workflow where Claude plans, acts, and checks its own work across several steps gets called agentic, even if nobody built a dedicated agent.
Why one word covers so much
"Agent" describes a behavior, not a single product. Because the behavior can be built in different places, the same label gets attached to a developer-built system, a coding assistant, and a general way of working. When you read a claim about Claude agents, check which of the three is meant.
Does Claude have agents?
Yes. Anthropic's Claude models function as agents, accessible via the Claude Platform where developers can create agents using the API, as well as through Claude Code, Anthropic's programming tool.
Most developers first encounter the Claude Code subagent. This subagent acts as a focused assistant that the primary Claude Code session can delegate tasks to, such as code reviews or codebase searches. It operates independently on that task and later provides feedback, which allows the main conversation to remain targeted.
How an agent differs from a single chat reply
- Chat reply: you submit one prompt and receive a single response. You control the subsequent steps.
- Agent: the model pursues a goal through multiple steps. It can utilize tools, interpret the results, and determine its next course of action.
- Loop: an agent continually cycles through these stages until the task is completed or it requires your input.
The key distinction lies in the level of autonomy across steps, rather than in the model itself.
How do Claude Code subagents work?
A subagent is a separate helper that the main Claude Code session can hand a task to. It has its own role, its own tools and its own context, and it returns a result when the work is done.
In practice, claude code subagents are defined by a few settings:
- Instructions: a prompt that sets the subagent's role, such as code reviewer or test writer.
- Tool access: the subset of tools it may use, so a reviewer can read files without being able to edit them.
- Model choice: a model suited to the job, for example a lighter one for simple lookups.
The flow is straightforward. The main session recognizes a task that fits a subagent, passes along the relevant instructions, and waits. The subagent works in its own context window, then sends back a result, usually a summary rather than every intermediate step.
Why subagents exist
Two reasons stand out:
- Focused context: noisy work such as searching a large codebase stays in the subagent's context, so the main conversation stays clean.
- Specialized work: a narrow role with limited tools tends to stay on task and is easier to reuse.
For setup details and examples, see the Claude Code agent guide.
What does a Claude agent file look like?
A Claude agent file is a Markdown file that begins with YAML frontmatter and continues with a plain-language system prompt. In a project, these files live in the .claude/agents folder, one file per subagent.
The frontmatter sits between two --- lines and defines how the subagent is identified and configured:
- name: a short identifier, usually lowercase with hyphens.
- description: tells Claude when this subagent should be used.
- tools: the tools the subagent may use. If omitted, it typically inherits the main session's tools.
- model: the model the subagent runs on.
Everything below the frontmatter is the prompt that shapes the subagent's behavior.
Example: a code-review subagent
Saved as .claude/agents/code-reviewer.md:
---
name: code-reviewer
description: Reviews code changes for bugs, readability, and security issues. Use after code is written or modified.
tools: Read, Grep, Glob
model: sonnet
---
You are a senior code reviewer. Examine the recent changes and report:
1. Bugs and logic errors
2. Security concerns
3. Readability and naming problems
Give specific, actionable feedback and reference file names and lines.This example limits the subagent to read-only tools, which suits a reviewer that should inspect code without changing it. A clear description matters most, because it guides when the subagent gets picked.
Claude agents vs skills: what is the difference?
An agent is a separate worker that runs with its own context, while a skill is a set of reusable instructions that loads into the work already in progress. Agents handle delegated tasks; skills teach the current session how to do something a certain way.
| Agent (subagent) | Skill | |
|---|---|---|
| Context | Its own, separate from the main conversation | Shared with the current work |
| Role | Takes a task, does it, reports back | Adds instructions or a procedure |
| Best for | Self-contained, noisy or parallel tasks | Repeatable methods and standards |
When to choose each
- Choose an agent when a task would clutter the main conversation, such as searching a large codebase or reviewing many files. Only the result returns to the main session.
- Choose a skill when you want the same approach applied consistently, such as a report format, a naming convention or a review checklist.
Simple example: a skill defines how your team writes release notes. An agent gathers and summarizes the last month of changes in its own context. The two can work together: the agent can use the skill's instructions to format what it produces.
Examples of Claude agents
Claude agents are usually small, focused helpers, each built around one job. The clearest examples come from software work, but the same pattern fits writing and research too.
Coding examples
- Code reviewer: reads a diff and flags bugs, unclear naming, missing error handling and style problems.
- Test writer: looks at a function or module and drafts unit tests, including edge cases.
- Debugger: takes an error message or failing test, traces the likely cause and proposes a fix.
- Documentation writer: turns code into README sections, docstrings or API notes.
Non-coding examples
- Research helper: gathers sources on a topic, compares them and summarizes the key points.
- SEO helper: drafts title tags and meta descriptions, and suggests headings for a page based on a target keyword.
These are the kinds of roles that often appear when people compare the best claude code subagents.
Tip: keep each agent to one job. A narrow agent has a clear instruction, needs less context and gives more predictable output. If you find yourself writing "and also" in an agent's description, split it into two agents.
How to create your first Claude agent
In Claude Code, you create a subagent by writing one Markdown file that defines a single role, then saving it in .claude/agents. Four steps cover it.
- Pick one role and write a clear description. Choose a narrow job, such as reviewing code or writing tests. The description tells Claude when to delegate to the agent, so state the trigger plainly.
- Choose tools and a model. Give the agent only the tools it needs. A read-only reviewer, for example, has no reason to edit files. Pick a model that fits the complexity of the task.
- Save the file in
.claude/agents. Use a descriptive filename with the.mdextension, and put the instructions for the agent in the body. - Test with a small task and refine. Run a short, low-risk request, read how the agent behaves, then tighten the description or prompt where it drifts.
If you would rather not write the file by hand, the Subagent Generator lets you describe a role, pick tools and a model, and download a valid .claude/agents file in seconds. Free tools need no signup, and nothing leaves your browser.
Long prompts add up, so check the size of your instructions with the Claude Token Counter before you commit to them.
Related articles
Frequently asked questions
How much does it cost to run Claude agents?
Cost follows your Claude usage, meaning tokens consumed and the plan you are on. Each subagent runs in its own context and adds its own token use, so several agents on one task cost more than a single session. Before a long run, check a token counter to estimate how much context you are sending.
Can I use a local model instead of Claude for coding agents?
Claude agent features, such as subagents and their agent files, are designed for Claude models. If you are considering a different tool or a local model, read that tool's documentation to see how it handles agents and what setup it expects.
Which tools should a read-only reviewer agent get?
Give a reviewer only the tools it needs to inspect code. A common choice is Read, Grep and Glob, which let it open files and search for patterns and file names. Without an edit or write tool, it cannot change files, so its output stays limited to feedback.
Can one agent call another agent?
The main session delegates work to subagents, and the results come back to that main session. Keep any chain of delegation short, because each handoff adds context and cost. If a task needs several specialists, it is usually simpler to have the main session call each one in turn than to nest them deeply.