Building AI Agents with Claude: A Practical Guide

What are AI Agents?

AI agents go beyond simple chat — they can autonomously plan, use tools, and complete multi-step tasks. With Claude's tool use API, you can build agents that interact with databases, APIs, file systems, and more.

The Agentic Loop

At its core, an AI agent follows a simple loop:

• Send user message to Claude with available tools defined
• Claude responds with either text or a tool use request
• If tool use: Execute the tool and feed results back to Claude
• Repeat until Claude provides a final text response

Basic Agent Implementation

import anthropic
client = anthropic.Anthropic()
tools = [
    {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "City name"}
            },
            "required": ["city"]
        }
    }
]
def run_agent(user_message):
    messages = [{"role": "user", "content": user_message}]
while True:
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            tools=tools,
            messages=messages
        )
# Process the response
        stop_reason = response.stop_reason
        messages.append({"role": "assistant", "content": response.content})
if stop_reason == "end_turn":
            # Claude is done, return the text response
            return next(
                block.text for block in response.content
                if block.type == "text"
            )
        elif stop_reason == "tool_use":
            # Execute tool calls and feed results back
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": str(result)
                    })
            messages.append({"role": "user", "content": tool_results})
def execute_tool(name, inputs):
    if name == "get_weather":
        return f"Weather in {inputs['city']}: Sunny, 22°C"
    return "Unknown tool"

Tool Design Best Practices

Write Clear Descriptions

Tool descriptions are critical — Claude reads them to decide when and how to use each tool:

{
    "name": "search_database",
    "description": "Search the PostgreSQL database for records. Supports filtering by column name and value. Returns up to 100 matching rows as JSON.",
    "input_schema": {
        "type": "object",
        "properties": {
            "table": {"type": "string", "description": "Table name to search"},
            "column": {"type": "string", "description": "Column to filter on"},
            "value": {"type": "string", "description": "Value to match"}
        },
        "required": ["table"]
    }
}

Use Enums for Constrained Inputs

When an input should only accept specific values, use enums:

"properties": {
    "sort_order": {
        "type": "string",
        "enum": ["asc", "desc"],
        "description": "Sort direction"
    }
}

Keep Tools Focused

Each tool should do one thing well. Instead of a monolithic manage_users tool, create separate tools:

• list_users — Query and filter users
• create_user — Add a new user
• update_user — Modify user properties
• delete_user — Remove a user

Multi-Agent Patterns

Router Pattern

Use a lightweight agent to classify the request, then delegate to a specialized agent:

User → Router Agent → Code Agent (for coding tasks)
                    → Research Agent (for information tasks)
                    → Data Agent (for database tasks)

Supervisor Pattern

A supervisor agent coordinates multiple worker agents:

User → Supervisor Agent → Worker 1 (research)
                         → Worker 2 (coding)
                         → Worker 3 (testing)

Safety and Guardrails

When building agents, implement these safety measures:

• Tool permissions: Limit what tools can do (read-only, specific directories)
• Confirmation steps: Require human approval for destructive actions
• Max iterations: Set a maximum loop count to prevent runaway agents
• Input validation: Validate tool inputs on the execution side
• Logging: Log all tool calls for audit and debugging
• Rate limiting: Prevent agents from making too many API calls

Model Selection

Getting Started

• Define your agent's goal clearly
• List the tools it needs
• Start with Claude Sonnet 4 and upgrade to Opus 4.6 if needed
• Test with simple scenarios first
• Add guardrails before deploying to production