Claude Agent Tutorial: Build Reliable Agentic Loops

This claude agent tutorial is for engineers who want working code and principled design, not framework hype. We cover the agentic loop mechanics, tool integration, context management, and the human-oversight patterns that the CCA-F exam tests directly. Domain 1 (Agentic Architecture and Orchestration) carries 27% of the exam weight, the single largest slice, so getting these fundamentals right matters both in production and on the day.

What exactly is a Claude agent?

A Claude agent is a process in which the model drives its own next action by reading tool results, deciding what to do next, and calling tools again until a stopping condition is met. The loop is not magic: it is a while loop in your code that keeps calling the Messages API until stop_reason equals "end_turn" or your own guard fires.

The minimal anatomy is:

1. A system prompt that defines the agent's goal and constraints.
2. A set of tools the model may call.
3. A host process that appends tool results and re-calls the API.
4. A termination condition that is explicit, not assumed.

That last point is where most first implementations fail. We cover agentic loop anti-patterns in depth elsewhere; here we build the correct version from the start.

How does the agentic loop work in code?

The loop centres on inspecting stop_reason after every API call. When the value is "tool_use", you execute the requested tool and append the result. When it is "end_turn", you exit. Anything else is an error path.

import anthropic
import json

client = anthropic.Anthropic()

def run_agent(system: str, tools: list[dict], initial_message: str) -> str:
    messages = [{"role": "user", "content": initial_message}]
    max_iterations = 20  # hard guard against runaway loops

    for _ in range(max_iterations):
        response = client.messages.create(
            model="claude-opus-4-5",
            max_tokens=4096,
            system=system,
            tools=tools,
            messages=messages,
        )

        # Append the assistant turn
        messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason == "end_turn":
            # Extract the final text block
            for block in response.content:
                if block.type == "text":
                    return block.text
            return ""

        if response.stop_reason != "tool_use":
            raise RuntimeError(f"Unexpected stop_reason: {response.stop_reason}")

        # Execute every tool call in this turn
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                result = dispatch_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result),
                })

        messages.append({"role": "user", "content": tool_results})

    raise RuntimeError("Agent exceeded max_iterations without reaching end_turn")

The max_iterations guard is non-negotiable. Without it, a confused model can loop indefinitely, burning tokens and potentially taking unintended actions. Per Anthropic's guidance on agentic systems, prefer minimal footprint: request only necessary permissions and err on the side of doing less when uncertain.

Understanding stop_reason field inspection and tool result appending are two of the 30 task statements the CCA-F exam tests. The code above encodes both correctly.

How do you design tools that agents actually use correctly?

Tool descriptions are the primary selection mechanism. The model reads your description, not your implementation. A vague description produces misrouting; a precise one produces correct calls on the first attempt.

A minimal but effective tool definition looks like this:

{
  "name": "search_knowledge_base",
  "description": "Full-text search over the internal product knowledge base. Use this when the user asks about product features, pricing, or support policies. Do NOT use for general web search or code execution.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query, written as a natural-language question."
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of results to return. Default 5, max 20.",
        "default": 5
      }
    },
    "required": ["query"]
  }
}

Three rules that pay off immediately:

1. State what the tool is for. Lead with the use-case, not the implementation.
2. State what it is NOT for. Explicit exclusions prevent the model from reaching for the wrong tool when two tools overlap.
3. Constrain the schema tightly. Enums, min/max values, and required fields reduce hallucinated inputs.

When you have too many tools in a single context, the model's accuracy drops. The tool overload problem is real: empirically, performance degrades as the available tool count grows. Scope tools to roles, not to the entire agent surface.

How should you manage context in a long-running agent?

Context is the resource most engineers underestimate. Every tool result you append grows the context window. After enough turns, two problems emerge: cost rises linearly, and the model's effective attention on early content weakens (the attention dilution problem).

The practical strategies, in order of preference:

1. Trim tool results before appending. If a tool returns 10,000 tokens of raw data and the agent needs three fields, extract those fields in your dispatch_tool function before appending. Never pass raw API responses verbatim.

2. Use summary injection for fresh sessions. When a task spans multiple sessions, end each session by asking the model to produce a structured summary, then inject that summary as the first user message of the next session. This is the summary injection for fresh sessions pattern.

SUMMARY_PROMPT = """
Before we end this session, produce a JSON summary of:
- completed_steps: list of actions taken and their outcomes
- pending_steps: list of steps not yet completed
- key_findings: facts discovered that the next session will need
- open_questions: anything that needs human clarification

Respond with only the JSON object, no prose.
"""

3. Fork sessions for divergent exploration. When the agent needs to explore two incompatible hypotheses, fork the conversation rather than letting both branches pollute a single context. See fork_session for divergent exploration for the mechanics.

4. Set a context budget and monitor it. Track usage.input_tokens in every response. When you approach 80% of the model's context limit, trigger a compaction step rather than waiting for a context error.

CONTEXT_BUDGET = 180_000  # tokens, for claude-opus-4-5

def should_compact(response) -> bool:
    return response.usage.input_tokens > CONTEXT_BUDGET * 0.8

When should a human step in?

Autonomous agents are not appropriate for every action. The CCA-F exam consistently rewards answers that apply proportionate human oversight: more autonomy for reversible, low-stakes actions; mandatory human approval for irreversible or high-stakes ones.

The structured handoff to human agents pattern formalises this. Rather than silently failing or guessing, the agent produces a structured handoff object and pauses.

HANDOFF_SCHEMA = {
    "type": "object",
    "properties": {
        "reason": {"type": "string"},
        "action_proposed": {"type": "string"},
        "reversible": {"type": "boolean"},
        "data_needed_from_human": {"type": "array", "items": {"type": "string"}},
        "urgency": {"type": "string", "enum": ["low", "medium", "high"]}
    },
    "required": ["reason", "action_proposed", "reversible", "data_needed_from_human"]
}

Three triggers that should always pause the agent and surface a handoff:

1. The proposed action is irreversible (deleting records, sending external communications, deploying to production).
2. The agent has reached a decision point not covered by its instructions.
3. Confidence in the next action is low and the cost of a wrong action is high.

Two triggers that are tempting but unreliable: the model "feeling uncertain" (models can be confidently wrong) and elapsed time (time alone does not indicate a problem). Root the decision in action type and stakes, not in model-reported confidence.

How do you structure a multi-agent system?

Single agents handle single-concern tasks well. When a task has multiple concerns, a hub-and-spoke architecture separates coordination from execution cleanly.

The coordinator receives the user request, decomposes it into subtasks, dispatches subagents, and synthesises results. Each subagent receives only the context it needs (subagent context isolation keeps costs down and reduces cross-contamination of reasoning).

The coordinator's system prompt should be goal-based, not step-based. Tell it what a good outcome looks like, not which subagents to call in which order. Goal-based vs step-based prompts is a tested concept: step-based prompts break when the environment deviates from the assumed sequence; goal-based prompts adapt.

As of 3 June 2026, more than 10,000 individuals have earned the CCA-F certification, and Domain 1 (which covers all of the above) carries the highest exam weight at 27%. Investing time in these patterns pays off both in production systems and on the exam.

What does a production-ready agent checklist look like?

Before shipping any agent to production, verify each of the following:

Our concept library at /concepts maps all 174 atomic concepts to the five exam domains and 30 task statements. If any of the patterns above feel unfamiliar, that is the right place to drill before sitting the CCA-F.

Where do you go from here?

The patterns in this tutorial cover the core of Domain 1 and touch Domains 2, 4, and 5. The next logical steps are:

• Tool design depth: Read the Tool Design and MCP Integration domain to understand MCP scoping, error propagation, and tool distribution strategy.
• Prompt engineering for agents: The Prompt Engineering and Structured Output domain covers how to write system prompts that produce reliable, parseable outputs from your agents.
• Context management advanced patterns: The Context Management and Reliability domain covers stale context, progressive summarisation traps, and session management scenario analysis.

The CCA-F exam launched on 12 March 2026 and costs $99 per attempt. It is scored on a 100-to-1000 scale with a passing mark of 720. The patterns in this tutorial are not exam trivia: they are the engineering decisions the exam's scenario-based questions are designed to probe.