DEV Community

Subham Kumar
Subham Kumar

Posted on

Claude Agentic Loop Explained: Guide to stop_reason, Tool Use, and Claude Agents

#ai #api #claude #agents

If you are learning the Anthropic Claude API, preparing for the Claude Certified Architect exam, or building AI agents, there is one concept you must understand:

The Claude Agentic Loop.

At first, terms like:

  • Agentic AI
  • Tool Use
  • stop_reason
  • Claude Agents

can feel confusing.

But don't worry.

This guide explains everything in very simple language.

Think of Claude as a smart person.

A smart person can answer questions.

But sometimes they need information from somewhere else.

They may need to:

  • Check a database
  • Search for information
  • Look up an order
  • Call another service

That is exactly how Claude agents work.

By the end of this guide, you will understand:

  • What an agentic loop is
  • What stop_reason means
  • Difference between tool_use and end_turn
  • How Claude tools work
  • Why Claude API is stateless
  • How to build a simple Claude agent

What Is a Claude Agent?

An AI agent is an AI system that can:

  1. Think
  2. Decide
  3. Use tools
  4. Observe results
  5. Continue working until a task is complete

Real-Life Analogy

Imagine a chef.

The chef is the brain.

Kitchen tools are the hands.

The chef decides:

"I need a knife."

But the knife does not move by itself.

Someone must pick it up and use it.

Similarly:

  • Claude = Brain
  • Tools = Hands
  • Your Code = Worker who executes actions

Chatbot vs Agent

Many beginners think a chatbot and an agent are the same thing.

They are not.

Normal Chatbot 

User asks question
       ↓
Claude answers
       ↓
Conversation ends
Enter fullscreen mode Exit fullscreen mode

Example:

User:

What is the capital of India?
Enter fullscreen mode Exit fullscreen mode

Claude:

New Delhi.
Enter fullscreen mode Exit fullscreen mode

Done.

Agent 

User asks question
       ↓
Claude thinks
       ↓
Needs tool?
   /      \
 Yes      No
  ↓        ↓
Use Tool  Final Answer
  ↓
Get Result
  ↓
Think Again
  ↓
Final Answer
Enter fullscreen mode Exit fullscreen mode

Example:

Where is my order 4821?
Enter fullscreen mode Exit fullscreen mode

Claude cannot know this information automatically.

It needs to:

  1. Use an order lookup tool
  2. Receive order information
  3. Generate a final answer

This process is called an Agentic Loop.

What Is a Claude Agentic Loop?

The Claude Agentic Loop is the repeated process where Claude:

  1. Receives a request
  2. Thinks about it
  3. Decides whether a tool is needed
  4. Uses a tool if required
  5. Receives the result
  6. Thinks again
  7. Returns the final answer

Flow Diagram 

User Request
      ↓
Claude Reasons
      ↓
Need Tool?
   /      \
 Yes      No
  ↓        ↓
Tool Call  Final Answer
  ↓
Tool Result
  ↓
Claude Reasons Again
  ↓
Final Answer
Enter fullscreen mode Exit fullscreen mode

This loop continues until Claude decides the task is complete.

Understanding Conversation Roles

Claude conversations contain roles.

System Role

The system role defines Claude's behavior.

Example:

You are a helpful customer support agent.
Enter fullscreen mode Exit fullscreen mode

Think of it as Claude's job description.

User Role

Represents messages from the human.

Example:

{
    "role": "user",
    "content": "Where is my order?"
}
Enter fullscreen mode Exit fullscreen mode

Assistant Role

Represents Claude's responses.

Example:

{
    "role": "assistant",
    "content": "I can help with that."
}
Enter fullscreen mode Exit fullscreen mode

Why Roles Matter

Think of a play.

System = Director
User = Customer
Assistant = Claude
Enter fullscreen mode Exit fullscreen mode

Each role has a different responsibility.

Claude uses these roles to understand context.

What Is stop_reason?

This is one of the most important concepts in Claude agent development.

Simple Definition

stop_reason tells your application:

Why Claude stopped generating the current response.

Your code should always check it.

Important stop_reason Values

tool_use

Meaning:

I need a tool.
Enter fullscreen mode Exit fullscreen mode

Claude is asking your application to execute a tool.

Claude does not execute tools itself.

Your code must do it.

end_turn

Meaning:

I am finished.
Enter fullscreen mode Exit fullscreen mode

Claude is telling your application:

The task is complete.

The agent loop should stop.

tool_use vs end_turn

stop_reason Meaning Action
tool_use Claude needs a tool Execute tool and continue
end_turn Claude is finished Stop the loop

Easy Memory Trick 

tool_use  = Continue Working
end_turn  = Stop Working
Enter fullscreen mode Exit fullscreen mode

Simple Order Lookup Example

Suppose a user asks:

Where is my order 4821?
Enter fullscreen mode Exit fullscreen mode

Claude identifies that this is an order lookup request.

Claude requests:

lookup_order
Enter fullscreen mode Exit fullscreen mode

Claude returns:

stop_reason = tool_use
Enter fullscreen mode Exit fullscreen mode

Your application executes the tool.

Tool returns:

Status: Shipped
Carrier: DHL
Delivery: Tomorrow
Enter fullscreen mode Exit fullscreen mode

Claude receives the result and generates:

Your order has been shipped and will arrive tomorrow.
Enter fullscreen mode Exit fullscreen mode

Now Claude returns:

stop_reason = end_turn
Enter fullscreen mode Exit fullscreen mode

The loop stops.

Why Claude API Is Stateless

Another very important concept.

What Does Stateless Mean?

Stateless means:

Claude does not automatically remember previous API calls.
Enter fullscreen mode Exit fullscreen mode

Every request starts fresh.

Example

First API request:

My name is Akash.
Enter fullscreen mode Exit fullscreen mode

Second API request:

What is my name?
Enter fullscreen mode Exit fullscreen mode

Claude will not know unless the first message is included again.

Maintaining Conversation History

You must send previous messages every time.

messages = [
    {
        "role": "user",
        "content": "My name is Akash"
    },
    {
        "role": "assistant",
        "content": "Nice to meet you Akash"
    },
    {
        "role": "user",
        "content": "What is my name?"
    }
]
Enter fullscreen mode Exit fullscreen mode

Now Claude has context.

Defining a Tool

Let's create a simple tool.

lookup_order_tool = {
    "name": "lookup_order",
    "description": "Look up order information",
    "input_schema": {
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string"
            }
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Line-by-Line Explanation

Name 

"name": "lookup_order"
Enter fullscreen mode Exit fullscreen mode

The tool identifier.

Claude uses this name when requesting the tool.

Description 

"description": "Look up order information"
Enter fullscreen mode Exit fullscreen mode

Helps Claude understand when to use the tool.

Input Schema 

"input_schema"
Enter fullscreen mode Exit fullscreen mode

Defines the expected inputs.

order_id 

"order_id"
Enter fullscreen mode Exit fullscreen mode

The order number provided by the user.

Claude Does Not Execute Functions

Many beginners assume Claude can run Python code.

It cannot.

Claude only requests:

Please call lookup_order
Enter fullscreen mode Exit fullscreen mode

Your application executes the function.

Tool Function Example 

## Simple mock database lookup
def lookup_order(order_id):

    orders = {
        "4821": {
            "status": "Shipped",
            "carrier": "DHL"
        }
    }

    return orders.get(order_id, "Order not found")
Enter fullscreen mode Exit fullscreen mode

Explanation

Create Function 

def lookup_order(order_id):
Enter fullscreen mode Exit fullscreen mode

Creates the tool function.

Mock Database 

orders = {
Enter fullscreen mode Exit fullscreen mode

Stores sample order information.

Order Details 

"4821": {
    "status": "Shipped"
}
Enter fullscreen mode Exit fullscreen mode

Sample data.

Return Result 

return orders.get(order_id, "Order not found")
Enter fullscreen mode Exit fullscreen mode

Returns matching order details.

Building the Agent Loop

A simplified example:

while True:

    response = call_claude(messages)

    if response.stop_reason == "end_turn":
        break

    if response.stop_reason == "tool_use":

        result = execute_tool()

        messages.append(result)
Enter fullscreen mode Exit fullscreen mode

Line-by-Line Explanation

Infinite Loop 

while True:
Enter fullscreen mode Exit fullscreen mode

Continue until Claude finishes.

Call Claude 

response = call_claude(messages)
Enter fullscreen mode Exit fullscreen mode

Send conversation history.

Check Completion 

if response.stop_reason == "end_turn":
Enter fullscreen mode Exit fullscreen mode

Claude is finished.

Stop Loop 

break
Enter fullscreen mode Exit fullscreen mode

Exit the loop.

Check Tool Request 

if response.stop_reason == "tool_use":
Enter fullscreen mode Exit fullscreen mode

Claude needs a tool.

Execute Tool 

result = execute_tool()
Enter fullscreen mode Exit fullscreen mode

Run the requested tool.

Save Tool Result 

messages.append(result)
Enter fullscreen mode Exit fullscreen mode

Add result back to the conversation history.

Correct Message Order

Always follow this order:

User Question
      ↓
Assistant Tool Request
      ↓
Tool Result
      ↓
Assistant Final Response
Enter fullscreen mode Exit fullscreen mode

This order is important because Claude needs the complete context.

Real-World Example

Imagine a travel booking agent.

User:

Book me a flight from India to Australia.
Enter fullscreen mode Exit fullscreen mode

Claude may:

  1. Search flights
  2. Compare prices
  3. Select best option
  4. Book ticket
  5. Generate confirmation

This is agentic behavior.

Why Tool Selection Should Be Model-Driven

Bad approach:

Always call Tool A
Always call Tool B
Always call Tool C
Enter fullscreen mode Exit fullscreen mode

Problems:

  • Expensive
  • Inflexible
  • Unnecessary

Better approach:

Provide available tools
Let Claude decide
Enter fullscreen mode Exit fullscreen mode

This is what makes a system agentic.

Common Mistakes

Mistake 1: Reading Claude's Words Instead of stop_reason

Bad:

if "done" in response.text:
    stop()
Enter fullscreen mode Exit fullscreen mode

Good:

if response.stop_reason == "end_turn":
    stop()
Enter fullscreen mode Exit fullscreen mode

Mistake 2: Using Loop Count as Main Exit Condition

Bad:

if iteration == 5:
    stop()
Enter fullscreen mode Exit fullscreen mode

Good:

if response.stop_reason == "end_turn":
    stop()
Enter fullscreen mode Exit fullscreen mode

Mistake 3: Forgetting Conversation History

Without history, Claude loses context.

Always maintain the messages array.

Mistake 4: Assuming Claude Executes Tools

Claude only requests tools.

Your application executes them.

Mistake 5: Wrong Message Order

Always append:

Assistant Tool Request
       ↓
Tool Result
Enter fullscreen mode Exit fullscreen mode

in that sequence.

Claude Certified Architect Exam Tips

Remember these facts:

Fact 1 

tool_use = Continue Loop
Enter fullscreen mode Exit fullscreen mode

Fact 2 

end_turn = Stop Loop
Enter fullscreen mode Exit fullscreen mode

Fact 3

Claude API is stateless.

Fact 4

Always send full conversation history.

Fact 5

Claude chooses tools.

Fact 6

Your code executes tools.

Key Takeaways

  • Claude agents can think, use tools, and continue working until a task is complete.
  • The repeated cycle is called an Agentic Loop.
  • stop_reason tells your application why Claude stopped.
  • tool_use means execute a tool and continue.
  • end_turn means stop the loop.
  • Claude does not execute tools directly.
  • Your application executes tools.
  • Claude API is stateless.
  • Always send conversation history with every request.

FAQ

What is a Claude Agentic Loop?

A repeated cycle where Claude reasons, requests tools, receives results, and completes a task.

What does tool_use mean?

Claude wants your application to execute a tool.

What does end_turn mean?

Claude has finished and the loop should stop.

Does Claude execute Python functions?

No. Claude only requests tool calls.

Why is Claude API stateless?

Because it does not automatically remember previous API requests.

What is the difference between a chatbot and an agent?

A chatbot answers and stops. An agent can use tools and continue working.

Should I stop when Claude says "I'm done"?

No. Use:

response.stop_reason == "end_turn"
Enter fullscreen mode Exit fullscreen mode

Why is stop_reason important?

It is the official mechanism for controlling Claude agent loops.

Conclusion

The foundation of modern Claude agents is the Agentic Loop.

Claude can decide when it needs tools, request them, receive results, and continue reasoning until the task is complete.

The key signal controlling this process is:

stop_reason
Enter fullscreen mode Exit fullscreen mode

Remember:

tool_use = Continue
end_turn = Stop
Enter fullscreen mode Exit fullscreen mode

Once you understand these concepts, you will have a strong foundation for building Claude agents and preparing for the Claude Certified Architect certification.

Top comments (0)