Agents: Concepts
“Agent” covers several things. This guide deals with the two you build:
| Kind | What you write | Where it runs | Use it for |
|---|---|---|---|
| Subagent | A Markdown file with frontmatter + a system prompt | Inside Claude Code or Cursor, launched by the main agent | Isolating context, parallel work, specialist personas, restricted permissions |
| SDK agent | Code that calls the Claude Agent SDK or the Cursor SDK | Your script, CI, server, or cloud | Automation outside the IDE: CI checks, bots, scheduled jobs, products |
Two related things configure agents rather than being agents themselves: AGENTS.md / CLAUDE.md (standing project instructions) and rules. See the platform matrix.
The agent loop
Section titled “The agent loop”Every agent runs the same loop:
gather context → decide → act (tool call) → observe result → repeat → reportWhen you design an agent, you’re choosing:
- Instructions: the system prompt, meaning its role, process, and output format.
- Tools: what it can do. Fewer tools gives sharper behaviour.
- Model: capability versus cost and speed.
- Context: what it starts with, and what it’s allowed to read.
- Stopping condition: when it’s done, and what it returns.
Why subagents exist: context isolation
Section titled “Why subagents exist: context isolation”The main conversation’s context window is precious. A subagent:
- starts with a fresh context: only its system prompt plus the task the parent gives it
- can read 50 files, run 20 searches, and return a one-page summary, so the parent never sees the noise
- can run in parallel with other subagents
- can use a different model (a cheaper one for search, a stronger one for review)
- can be restricted: read-only (
readonly: truein Cursor,tools:allowlist in Claude Code)
What it costs:
- The subagent doesn’t see the parent’s conversation, so the task prompt the parent writes must contain everything it needs.
- Extra latency and tokens. Don’t delegate trivial lookups.
- Results come back as a summary, so the parent has to trust or verify them.
How delegation works
Section titled “How delegation works”The parent agent reads every subagent’s description and decides whether to delegate, just as it does for skills. That means:
- The description is the routing rule. “Use proactively after code changes to run tests and report failures” gets used; “Testing helper” doesn’t.
- Users can force delegation explicitly:
/namein Cursor, or “use the code-reviewer subagent” in either host.
Subagent vs skill
Section titled “Subagent vs skill”| Question | Skill | Subagent |
|---|---|---|
| Runs in… | The current context | A separate context |
| Adds… | Knowledge / procedure | A worker |
| Returns… | Nothing (it changes how the agent works) | A result message |
| Good for… | “How we do X” | “Go do X and report back” |
| Can combine? | A subagent can use skills | A skill can tell the agent to delegate to a subagent |
A useful pattern is to put the procedure in a skill and the execution in a subagent that follows it. That way both the main agent and the subagent can reuse the procedure.
SDK agents
Section titled “SDK agents”SDKs give you the same agent harness that powers Claude Code or Cursor, called from code:
| Claude Agent SDK | Cursor SDK | |
|---|---|---|
| Packages | @anthropic-ai/claude-agent-sdk / claude-agent-sdk |
@cursor/sdk / cursor-sdk |
| Built-in tools | Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, … | The Cursor agent’s tools |
| Add tools | MCP servers (external or in-process SDK servers) | MCP servers |
| Subagents | agents option or .claude/agents/ (with settingSources) |
.cursor/agents/*.md |
| Runs | Wherever your code runs | Locally, or on Cursor Cloud Agents |
Use an SDK agent when there’s no human in the chat: a PR-review bot, a nightly dependency updater, a support-ticket triager, or an agent inside your own product.
Multi-agent architectures
Section titled “Multi-agent architectures”| Pattern | Shape | When |
|---|---|---|
| Single agent + tools | One loop | Default. Start here. |
| Orchestrator + workers | The parent plans and fans out to subagents in parallel | Broad research, large refactors split by area |
| Pipeline | A → B → C, each with a narrow job | Staged work: spec → implement → verify |
| Generator + verifier | One produces, another independently checks | Anything where correctness matters |
| Router | Classifies the request, then hands it to a specialist | Many distinct request types |
See Design patterns for templates and trade-offs.
Safety model
Section titled “Safety model”Agents take actions, so design for failure:
- Least privilege: read-only by default; grant write or shell access only when it’s needed.
- Human checkpoints before irreversible actions (deploys, deletions, sending messages).
- Hooks for hard guarantees that a prompt can’t give: block dangerous commands, require tests.
- Sandboxing for SDK agents: containers, scoped credentials, no production secrets.
- Prompt-injection awareness: anything the agent reads (web pages, issues, files) can contain instructions. Don’t give an agent that reads untrusted input powerful tools as well, unless a human reviews its actions.