Agents — AIGuide

First principles

What makes something an "agent"?

A plain chatbot maps one prompt to one reply. An agent adds three things that turn a text model into something that can get real work done:

🛠️Tools — it can take actions in the world: read and edit files, run commands, search the web.
🧠Memory & retrieval — it can pull in context: your project files, standing instructions, past conversation.
🔁A loop with judgement — it decides what to do next based on what just happened, and repeats until the goal is met.

Anthropic calls this foundation the "augmented LLM" — a model wrapped with tools, retrieval, and memory. The defining trait of an agent (versus a fixed workflow) is that the model chooses its own path: how many steps to take, which tools to call, and when to stop.

Where it sits

The autonomy spectrum

"Agent" isn't binary — it's the far end of a spectrum of how much the system decides for itself. Anthropic draws a sharp line between a workflow (you script the steps) and an agent (the model scripts them).

📍

Claude Code is an interactive agent

It's fully agentic — it decides its own path — but it keeps a human in the loop: it can pause for permission, and you can interrupt or steer it at any moment. That's the sweet spot between raw autonomy and control.

Under the hood

Anatomy of the Claude Code agent

Claude Code is an agentic harness — the machinery wrapped around the model. Five parts work together:

🧠

The brain — the model

A Claude model (Opus, Sonnet, Haiku, Fable) does the reasoning: understanding the task, writing solutions, judging results.

🛠️

The hands — tools

Read, Write, Edit, Grep, Bash, WebFetch, and more — the concrete actions the agent can take.

📚

The memory — context

The context window, plus CLAUDE.md project instructions and cross-session auto-memory.

🔁

The engine — the loop

The cycle that ties it together: gather context, act, verify, decide, repeat.

🛡️

The guardrails — permissions & safety

Permission modes, allow/deny rules, sandboxing, checkpoints, and human approval keep autonomy bounded and reversible.

The engine

The agent loop & the tool-use protocol

Mechanically, the loop is a conversation between the model and its environment. The model emits a tool-use request; the harness runs it and returns a tool-result; the model reads that and decides the next move. That back-and-forth repeats.

Zoomed out, each trip around that protocol is one of five phases. This is the same loop covered on the In Claude Code page — here's the short version:

🧭 Gather context

Read files, search, load memory & git state.

🧠 Reason

Plan the next concrete step.

🛠️ Act

Call one or more tools.

👀 Observe

Read the results.

🔀 Decide

Loop, delegate, or stop.

🔁 Repeat

Until the goal is met.

The hands

The toolbox

Tools are what give the agent agency. Claude Code ships with a broad built-in set, grouped by what they do — plus any tools you connect through MCP servers.

📄 Files

Read, Write, Edit — read, create, and precisely modify files (Read handles images, PDFs, notebooks).

🔎 Search

Glob (find files by pattern) and Grep (regex content search, ripgrep-based).

⌨️ Execution

Bash / PowerShell to run commands, tests, and git — with read-only commands auto-approved.

🌐 Web

WebSearch for results and WebFetch to pull a page in and read it.

✅ Task & planning

Task/todo tools to track multi-step work, and plan-mode tools to design before editing.

🧑‍🔧 Delegation

The Agent/Task tool spawns subagents; Skill runs a skill. (Subagents get their own page next.)

🔌 MCP

mcp__server__tool — anything a connected MCP server exposes: databases, browsers, APIs.

💬 Interaction

Ask clarifying questions, send files, and push notifications back to you.

🔐

Tools carry their own permission logic

Reading and searching are safe and usually run freely; writing, executing, and web access default to asking. Every tool declares whether it needs approval — that's the security boundary in action (see Permissions).

The brain

Models & reasoning

You choose which Claude model powers the agent, trading speed and cost against raw capability. Pick with /model in-session, the --model flag, or a settings file.

Model	Feel	Reach for it when…
`haiku`	Fast & light	Simple, mechanical tasks; quick iteration; cheap subagents.
`sonnet`	Balanced	Everyday coding — the sensible default for most work.
`opus`	Deep reasoning	Hard problems, architecture, tricky debugging.
`fable`	Most capable	Long autonomous sessions and deep root-cause investigations.
`opusplan`	Mixed	Opus while planning, Sonnet while executing — capability where it counts, cheaper elsewhere.

🧩 Extended thinking

Let the model reason longer before acting on a hard problem. In VS Code, toggle it from the / menu; the reasoning shows as expandable blocks.

⚡ Effort levels

Reasoning effort (low → max) tunes how much thinking the agent spends per step — dial it up for the gnarly parts, down for the routine.

🏷️

Aliases vs. pinned IDs

Aliases like opus or sonnet always resolve to the latest version; full IDs like claude-opus-4-8 pin an exact model for reproducibility. Long-context variants (e.g. sonnet[1m]) trade some cost for a much larger window.

The dial

Permissions & autonomy

Permissions decide how much the agent may do without asking. You set a mode for the overall posture and rules for the fine print.

Mode	What it does	Use when…
`default`	Asks before the first use of each tool that changes things	Exploring a new codebase; you want to see every action.
`plan`	Read-only — investigates and proposes, makes no edits	You want a plan before any changes land.
`acceptEdits`	Auto-approves file edits & routine file commands	The task is clear and you trust the direction.
`auto`	Runs with background safety checks	Larger tasks where you want flow with guardrails.
`bypassPermissions` ⚠️	Skips prompts entirely (still blocks the truly dangerous)	Only in isolated VMs/containers — full system access.

How a rule is decided

For any single action, rules are checked in a fixed order — the first match wins:

Rules are patterns scoped to a tool. A few examples:

# allow — run without asking Bash(npm run test:*) Read(src/**) WebFetch(domain:docs.claude.com) # ask — always confirm Bash(git push:*) # deny — never, even if asked Read(./.env) Bash(rm -rf *)

Manage these interactively with /permissions, or commit them in .claude/settings.json so your whole team shares the same guardrails.

What it remembers

Memory & context

An agent is only as good as what it can see. Claude Code layers three kinds of memory into the context window:

📌CLAUDE.md — standing project instructions loaded every session: build commands, conventions, architecture. Keep it tight (aim ~200 lines).
🧠Auto-memory — notes the agent writes itself across sessions from your corrections, loaded on demand so it doesn't crowd the window.
💬The live context window — the current conversation, files read, and tool outputs. Finite, so it's managed carefully.

🗜️

Auto-compaction

When the window fills, Claude Code trims the oldest tool outputs first, then summarises older conversation — preserving your requests and key code so the loop keeps running. Use /context to see what's taking up space. Heavy reading is best pushed into subagents so it never touches the main window.

Where it runs

Five ways to run the agent

The same agent loop drives every one of these — they differ only in how you interact with it.

⌨️

Interactive terminal

Run claude for a full human-in-the-loop REPL. You see every step and can interrupt with Esc. Best for hands-on development.

🧩

VS Code extension

The same loop in a graphical panel — diffs, plan review, @-mentions, session history. Best for IDE-integrated work.

🤖

Headless / print mode

claude -p "…" runs non-interactively and prints a result — pre-approve tools with --allowedTools. Best for CI/CD and scripts.

☁️

Cloud sessions

Run in Anthropic-managed VMs from claude.ai/code — no local setup, isolated execution. Best for cloud-native workflows.

🧰

The Claude Agent SDK

Drive the exact same agent loop from your own Python or TypeScript program — same tools, context management, permissions, and subagent machinery — to embed an agent in a product or pipeline. Best for building custom, production agents.

Staying in control

Safety & guardrails

Autonomy is only useful if it's safe. Claude Code layers several independent protections so no single failure lets the agent do harm.

🔐 Permissions (policy)

The first boundary — allow/ask/deny rules and modes decide what runs without you.

📦 Sandboxing (OS)

Optional kernel-level isolation of the shell's filesystem & network — survives even prompt injection.

↩️ Checkpoints

Every file edit is snapshotted and reversible — rewind to undo the agent's changes.

🪝 Hooks

Your own scripts run before/after tool use to enforce custom, deterministic checks.

🙋 Human-in-the-loop

You review changes, answer prompts, and can interrupt or redirect at any moment.

🛡️ Trust verification

Opening a new repo prompts a trust check, so a malicious CLAUDE.md or setting can't act silently.

⚠️

The golden rule

Bounded autonomy beats maximal autonomy. Give the agent the least access it needs, keep dangerous actions behind a prompt, and review before you approve — especially anything that touches the outside world (deploys, pushes, sending messages), which checkpoints can't undo.

How to think about it

Design principles

1 · Start simple

A plain LLM call beats an over-engineered agent. Add agentic complexity only when a task genuinely needs discovery and iteration.

2 · Prefer workflows when the path is known

If you can predict the steps, script them. Save true agency for open-ended problems.

3 · Make actions observable & reversible

Diffs, checkpoints, and permission prompts turn autonomy into something you can trust and audit.

Next up

One agent is powerful. Many are a team.

Everything here describes a single agent. The real leverage comes when the agent delegates to specialised helpers with their own isolated contexts — subagents. That's the next page.

Next lesson: Subagents Skip ahead: Advanced patterns