Build your first Claude agent: a step-by-step walkthrough

Plenty of articles tell you that agents are powerful. Very few sit you down and walk you through building one that actually does something useful. This is that walkthrough. By the end you will have a clear mental model of every step required to stand up a working Claude agent — the loop, the tools, the context, the guardrails — and you will know exactly where each piece goes. We will build a support-triage agent that reads a customer message, looks up the account, and drafts a response, because that exercises tools, context, and error handling without drowning you in setup.

Step 1: Stand up the bare agent loop

Start with the smallest thing that runs. An agent is a loop around a model call, so the first milestone is a loop that sends a message to Claude and prints the reply — no tools yet. Pick your model deliberately: Sonnet 4.6 is the sensible default for an agent that will make many calls, with Opus 4.8 reserved for the hardest reasoning steps and Haiku 4.5 for cheap, high-volume classification. Getting a plain request and response working first means that when you add tools, you are debugging tools in isolation rather than the entire stack at once.

The loop's contract is simple. You maintain a list of messages. You call the model. If the response contains tool-use blocks, you execute them and append the results as new messages, then call again. If it does not, you are done and the final text is your answer. Write this control flow before anything else; everything in the rest of this walkthrough slots into it.

Step 2: Define tools the model can actually call

Our triage agent needs two tools: lookup_account, which takes an email and returns plan and status, and get_recent_tickets, which returns the last few tickets for an account. A tool definition is a name, a one-line description of when to use it, and a JSON schema for its inputs. The description is not documentation for humans — it is a prompt the model reads to decide whether to call the tool, so write it as instruction: "Look up a customer account by email. Use this before drafting any reply so you have their plan tier."

flowchart TD
  A["Customer message in"] --> B["Agent loop: send to Claude"]
  B --> C{"Tool requested?"}
  C -->|lookup_account| D["Run account lookup"]
  C -->|get_recent_tickets| E["Fetch recent tickets"]
  D --> F["Append tool results to messages"]
  E --> F
  F --> B
  C -->|No tool| G["Return drafted reply"]

Keep schemas tight. If lookup_account only ever needs an email, the schema has one required string field and nothing else. Loose schemas — a generic params object, optional fields the model has to guess about — are the single most common reason early agents misbehave, because the model fills ambiguity with plausible nonsense. A precise schema is a fence that keeps the model on the path.

Step 3: Wire tool execution into the loop

Now connect the definitions to real functions. When the model returns a tool-use block for lookup_account, your code reads the input, calls your database, and returns the result wrapped as a tool-result block carrying the same tool-use id so the model can match request to response. This is the moment the agent stops being a chatbot and becomes an agent: it is now acting on your systems, not just talking.

Execute defensively from the start. Wrap each tool call in error handling that catches exceptions and returns them to the model as a tool result rather than crashing the loop. If lookup_account throws because the email is malformed, return {"error": "no account found for that email"} as the result. The model reads that, and instead of dying it adapts — perhaps asking for clarification or noting the account is unknown in its draft. Surfacing errors as data rather than exceptions is what makes the loop resilient.

Step 4: Assemble the right context

Your system prompt is where you set the agent's job, its boundaries, and its output contract. For the triage agent: "You draft support replies. Always look up the account before drafting. Never promise refunds or commit to timelines. End every draft with a one-line internal note flagging urgency as low, medium, or high." Notice these are operational rules, not personality fluff. A good agent system prompt reads like a runbook for a careful employee.

Resist the urge to preload everything. You might be tempted to stuff the full customer history into context up front, but that is exactly what the tools are for — let the model pull get_recent_tickets only when a case warrants it. Lean initial context plus on-demand tools keeps each turn cheap and keeps the model focused on the message in front of it rather than wading through data it may not need.

Step 5: Run a real task and watch the trajectory

Feed it a genuine message: "I was charged twice this month and I'm furious." Watch the trajectory. The model should call lookup_account, see the plan tier, likely call get_recent_tickets to check for prior billing complaints, then draft a calm reply and flag urgency high. If it skips the lookup, your tool description was too weak — strengthen it to say the lookup is mandatory. Reading trajectories is the core debugging skill for agents; the transcript tells you exactly where the model's reasoning diverged from what you intended.

Iterate on the failures you see, not the ones you imagine. If the draft promises a refund despite your rule, the rule is buried — move it earlier and make it emphatic. If the model loops calling the same tool twice, your tool result was ambiguous about success. Each fix is small and local because the trajectory pinpoints the exact step that went wrong.

Step 6: Graduate to MCP and the Agent SDK

Once the hand-built version works, you will notice you are reimplementing plumbing that already exists. The Claude Agent SDK gives you the agent loop, tool execution, and context management as production primitives, so you stop maintaining boilerplate. And rather than hardcoding lookup_account against your database, you can expose it through an MCP server, making the same tool reusable across every agent you build. The walkthrough you just did by hand is the mental model; the SDK and MCP are how you ship it without rewriting the engine each time.

Frequently asked questions

Do I need a framework to build a Claude agent?

No. The agent loop is a few dozen lines and building it by hand once is the best way to understand it. Reach for the Claude Agent SDK when you want production-grade context management, retries, and tool orchestration without maintaining that plumbing yourself.

How many tools should my first agent have?

Start with two or three tightly scoped tools. Too many tools at once makes the model's choice harder and your debugging slower. Add tools one at a time, confirming the agent uses each correctly before introducing the next.

Why return errors to the model instead of raising them?

Because the model can recover from data it can read but not from a crashed loop. Returning a clear error string as a tool result lets the agent adapt — retry, ask for clarification, or note the failure — which is the behavior you actually want in production.

Which Claude model should I start with?

Sonnet 4.6 is the pragmatic default for most agent loops. Use Opus 4.8 for the hardest reasoning and Haiku 4.5 for cheap, high-volume steps like classification. Many production agents mix models across different stages of the same workflow.

Bringing agentic AI to your phone lines

This exact build pattern — loop, tools, context, guardrails — is how CallSphere's voice and chat agents handle live calls: they look up accounts, check history, and draft the right response mid-conversation, then book the work. Try it at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.