How to Build an AI Agent With Claude: A Step-by-Step Technical Guide

Before writing any code, define exactly what the agent is responsible for.

This distinction matters.

Every tool you give an AI agent increases what it can affect.

A narrowly defined agent is usually easier to test, secure and improve than one with broad access to everything.

We will use Python.

Anthropic's current Claude Agent SDK requires Python 3.10 or newer. The Claude Code CLI is bundled with the Python package, so a separate CLI installation is normally unnecessary.

Install the SDK:

pip install claude-agent-sdk

Then make your Anthropic API key available as an environment variable:

export ANTHROPIC_API_KEY="your-api-key"

On Windows PowerShell:

$env:ANTHROPIC_API_KEY="your-api-key"

Now create a simple project structure:

my-agent/
    agent.py
    sample-project/

Place a small test codebase inside sample-project. That gives Claude something real to inspect.

Create agent.py:

import anyio

from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    AssistantMessage,
    TextBlock,
)


async def main():
    options = ClaudeAgentOptions(
        model="sonnet",
        cwd="./sample-project",

        tools=[
            "Read",
            "Glob",
            "Grep",
        ],

        allowed_tools=[
            "Read",
            "Glob",
            "Grep",
        ],

        max_turns=6,

        system_prompt="""
        You are a technical review agent.

        Inspect the project before reaching conclusions.

        Identify the three most important technical issues.

        For each issue:
        1. Explain the problem.
        2. Reference the relevant evidence.
        3. Explain the potential impact.
        4. Recommend one practical next step.

        Do not modify files.
        Do not invent findings when evidence is unavailable.
        """
    )

    async for message in query(
        prompt="""
        Review this project and identify the three
        most important technical issues.
        """,
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)


anyio.run(main)

Run it:

python agent.py

The SDK's query() interface works well for one-off or automated agent tasks. Anthropic also provides ClaudeSDKClient for interactive or stateful conversations where follow-up messages and longer sessions are required.

This is one of the most important parts of the entire Claude agent tutorial.

We used:

tools=["Read", "Glob", "Grep"]

This defines which built-in tools are available to the agent.

We also used:

allowed_tools=["Read", "Glob", "Grep"]

These tools are permitted to execute without asking for approval each time.

The distinction is important. In the current SDK, tools controls the available built-in toolset, while allowed_tools controls which tools are automatically permitted.

Our agent only needs to inspect a project. It therefore does not need access to tools such as:

Write
Edit
Bash

Useful principleGive the agent the smallest toolset capable of completing its job.

You can always expand its capabilities later.

A weak system prompt would say:

You are an expert software engineer. Review this project.

That tells Claude very little about how the task should be completed.

A stronger instruction defines the process:

Inspect the project using the available tools. Do not make assumptions about files you have not examined. Return no more than three findings, ordered by importance, with evidence and one recommended action for each.

The clearer these boundaries are, the easier your agent becomes to test.

Reading files is useful for learning, but business AI agents usually need access to external systems.

A production agent might need to retrieve information from a CRM, check a database, call an internal API or access analytics.

The Claude Agent SDK supports custom tools and MCP-based integrations, allowing developers to expose application-specific capabilities to Claude.

Conceptually, a project-status tool could look like this:

@tool(
    "get_project_status",
    "Get the current status of a project",
    {"project_id": str},
)
async def get_project_status(args):

    project_id = args["project_id"]

    status = lookup_project(project_id)

    return {
        "content": [{
            "type": "text",
            "text": f"Project {project_id}: {status}"
        }]
    }

Your actual lookup_project() function could query your database or internal API.

Claude could then decide when retrieving that information is necessary.

That is where agents become particularly useful.

Your application provides access to real systems. Claude decides when and how those capabilities should be used to complete the task.

A system prompt should never be your only security mechanism.

Suppose an agent can access three types of actions:

Those categories do not carry the same risk. As impact increases, your controls should become stronger.

The Claude Agent SDK includes controls such as maximum turns, budget limits, permission modes and hooks for intercepting tool behaviour.

A safer architecture for an important action might be:

The model should operate inside security boundaries defined by your application.

It should not define those boundaries itself.

Do not decide an agent is ready because one demonstration worked.

Create several repeatable scenarios.

For this technical review agent, test what happens when the project is healthy, when a security problem exists, when important files are missing and when the agent receives a request outside its permitted actions.

Then evaluate more than the wording of the response.

• Did it choose the right tools?
• Did it inspect evidence before answering?
• Did it invent anything?
• Did it stay inside its permissions?
• How many turns did the task require?
• How much did the run cost?

An impressive response is not enough.

A production agent needs predictable behaviour when things go wrong too.