So you’ve seen the demos. An AI that books your calendar, writes and executes its own code, browses the web, and checks its own work before delivering a polished answer. You want to build that — but every tutorial you find either glosses over the fundamentals or drops you straight into a maze of framework docs.
This guide is different. By the end, you’ll understand exactly what an AI agent is under the hood, what skills and tools you need to build one, and how to follow a realistic, step-by-step roadmap from zero to your first working agent project.
Let’s get into it.
Interactive Concept Map
Click any node to expand or collapse. Use the controls to zoom, fit to view, or go fullscreen.
What Is an AI Agent, Really?
Before writing a single line of code, you need a clear mental model.
A large language model (LLM) like Claude or GPT-4 is, at its core, a very sophisticated text predictor. You give it a prompt; it generates a response. That’s a single, stateless interaction — useful, but limited.
An AI agent wraps that LLM inside a control loop that gives it:
- Memory — access to past context or stored facts
- Tools — the ability to call external functions (search the web, run Python, query a database)
- Planning — the ability to break a complex goal into sub-steps
- Observation — feedback from tool results that informs the next action
The simplest agent loop looks like this:
User Goal → LLM thinks → LLM chooses an action → Tool runs → Result fed back to LLM → LLM thinks again → ... → Final answer
This is the ReAct pattern (Reason + Act), and it’s the foundation of almost every agent framework in production today.
Real-world analogy: Think of the LLM as a brilliant consultant locked in a room with only a phone. The tools are phone numbers the consultant can call — a search engine, a calculator, a code interpreter. Your job as the harness engineer is to wire up the room: pick the right phone numbers, make sure the calls connect reliably, and prevent the consultant from ordering pizza on the company card.
What You Need Before You Start
Skills Checklist
You do not need a machine learning background to build agents. You do need:
- Python fundamentals — functions, classes, dictionaries, async/await basics
- REST APIs — understanding how to make HTTP requests and parse JSON responses
- Basic prompt engineering — knowing how system prompts, user prompts, and temperature affect model behavior
- CLI comfort — installing packages, running scripts, reading tracebacks
If you’re shaky on Python, spend two weeks with the Python official tutorial before continuing. Everything else in this guide assumes you can write and run a Python script.
Tools and Accounts to Set Up
| Tool | Why You Need It | Cost |
|---|---|---|
| Anthropic API or OpenAI API | The LLM brain | Pay-as-you-go |
| Python 3.11+ | Runtime | Free |
uv or pip |
Package management | Free |
| VS Code or Cursor | Editor | Free |
| Git + GitHub | Version control | Free |
A simple .env manager (python-dotenv) |
Secret management | Free |
Create your API account first — you’ll need a key within the first hour of building.
Stage 1: Understand the Core Concepts (Week 1)
The Four Pillars of Any Agent
Spend your first week learning these four concepts in isolation before combining them.
1. Prompting for reasoning
The way you prompt an LLM dramatically changes how it “thinks.” Learn the difference between:
– Zero-shot prompting — just ask the question
– Chain-of-thought prompting — ask the model to reason step by step before answering
– Few-shot prompting — provide 2–3 examples of the behavior you want
For agents, chain-of-thought is your foundation. A prompt like “Think step by step before choosing an action” dramatically improves reliability on multi-step tasks.
2. Tool calling (function calling)
Modern LLM APIs let you define a list of functions (tools) in a structured schema. The model decides when to call one and returns a structured response you can execute in code. This is the mechanism that transforms a chatbot into an agent.
Here’s a minimal example using the Anthropic SDK:
import anthropic
client = anthropic.Anthropic()
tools = [
{
"name": "get_weather",
"description": "Get the current weather for a city",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "City name"}
},
"required": ["city"]
}
}
]
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What's the weather in Berlin?"}]
)
# Check if the model wants to call a tool
if response.stop_reason == "tool_use":
tool_call = next(b for b in response.content if b.type == "tool_use")
print(f"Model wants to call: {tool_call.name}")
print(f"With inputs: {tool_call.input}")
Run this. Read the output carefully. This is the heartbeat of every agent you will ever build.
3. The agent loop
Now wire the tool call into a loop. When the model returns a tool_use stop reason, you execute the function, feed the result back as a tool_result message, and call the model again. Repeat until the model returns end_turn with a final answer.
Write this loop yourself from scratch before using any framework. Understanding it bare-metal is the difference between a practitioner and someone who cargo-cults framework code.
4. Memory patterns
Agents forget everything between runs unless you engineer memory in. The three main approaches:
– In-context memory — stuff recent history into the system prompt (cheap, hits token limits fast)
– External memory — store facts in a vector database or key-value store, retrieve relevant chunks at runtime
– Episodic memory — log past interactions to a database, summarize and inject relevant episodes
For your first agent, start with in-context memory. Move to external memory once you’ve felt the pain of token limits.
Stage 2: Build Your First Agent from Scratch (Weeks 2–3)
The Project: A Research Assistant Agent
Your first real agent project: a CLI tool that takes a research question, searches the web for relevant sources, reads and summarizes them, and produces a structured answer with citations.
This project forces you to implement:
– A tool for web search (use the Brave Search API or Tavily — both have free tiers)
– A tool for fetching and extracting page content
– A multi-step reasoning loop
– Basic output formatting
Project Structure
research-agent/
├── .env # API keys
├── main.py # Entry point
├── agent.py # Core agent loop
├── tools/
│ ├── search.py # Web search tool
│ └── fetch.py # Page fetch + extraction tool
├── memory.py # Conversation history management
└── requirements.txt
Step-by-Step Build
Step 1 — Define your tools as Python functions first. Before worrying about the LLM, write search(query: str) -> list[dict] and fetch_page(url: str) -> str as plain functions that work independently.
Step 2 — Write the tool schemas. Convert each function signature into the JSON schema format your LLM API expects. Keep descriptions precise — vague descriptions lead to wrong tool calls.
Step 3 — Build the agent loop. A clean loop looks like:
def run_agent(goal: str, tools: list, max_turns: int = 10) -> str:
messages = [{"role": "user", "content": goal}]
for turn in range(max_turns):
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=4096,
system=SYSTEM_PROMPT,
tools=tools,
messages=messages
)
# Append assistant response to history
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason == "end_turn":
# Extract final text answer
return next(b.text for b in response.content if hasattr(b, "text"))
if response.stop_reason == "tool_use":
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})
return "Max turns reached without a final answer."
Step 4 — Test with real questions. Try: “What are the three most-cited papers on ReAct agents published in 2024?” Watch the trace. Where does it go wrong? That debugging process is your real education.
Step 5 — Add logging. Print every tool call and result to a log file. You cannot improve what you cannot observe. This logging habit will serve you for your entire career in harness engineering.
Stage 3: Learn the Frameworks (Weeks 4–6)
Once you’ve built an agent from scratch, frameworks stop being magic boxes and start making sense.
The Main Frameworks to Know in 2026
LangGraph — Graph-based agent orchestration from LangChain. Excellent for stateful, multi-step workflows. Best choice when your agent has complex branching logic or needs human-in-the-loop checkpoints.
CrewAI — Multi-agent framework focused on role-based collaboration. Good for workflows that benefit from specialized agent “personas” (Researcher, Writer, Reviewer).
Claude Agent SDK (Anthropic) — Anthropic’s first-party Python SDK for building production agents with Claude. Tight integration with tool use, streaming, and built-in patterns for common agent architectures. Recommended if Claude is your primary model.
AutoGen (Microsoft) — Strong for code-focused agents and multi-agent conversations. Large community, lots of examples.
How to Learn a Framework Effectively
Don’t start with the docs homepage. Instead:
1. Find the “quickstart” — get a hello-world agent running in under 30 minutes
2. Read the source code of 2–3 official examples
3. Rebuild your research assistant from Stage 2 using the framework
4. Note what the framework gives you for free vs. what you still had to write yourself
That comparison is the most valuable learning in this stage.
Stage 4: Add the Harness (Weeks 7–10)
This is where beginner agent builders stop and senior harness engineers begin.
A “harness” is the reliability infrastructure around your agent: everything that makes it safe, observable, and trustworthy in production.
What Goes Into a Production Harness
Guardrails — Input and output validation. Prevent the agent from taking actions outside its defined scope. Catch and handle malformed tool calls. Reject inputs that trigger known failure modes.
Observability — Structured logging of every LLM call, tool invocation, token count, and latency. Without this, debugging production failures is guesswork. Tools like LangSmith, Braintrust, or a simple Postgres + structured logs setup work well.
Retry logic and error handling — LLM APIs fail. Tool calls return unexpected formats. Network requests time out. Your harness needs graceful error handling and smart retry strategies (exponential backoff, fallback tools).
Cost controls — Set hard limits on tokens per run and runs per day. One infinite loop bug can turn into a surprise $500 API bill. Always budget.
Human-in-the-loop checkpoints — For high-stakes actions (sending emails, making purchases, deleting data), pause the agent and require explicit human approval before proceeding.
A Simple Harness Pattern
class AgentHarness:
def __init__(self, agent, max_cost_usd=1.0, max_turns=15):
self.agent = agent
self.max_cost_usd = max_cost_usd
self.max_turns = max_turns
self.cost_tracker = CostTracker()
self.logger = StructuredLogger()
def run(self, goal: str) -> AgentResult:
with self.logger.trace(goal=goal) as trace:
try:
result = self.agent.run(
goal,
hooks={
"on_tool_call": self._validate_tool_call,
"on_llm_response": self._check_cost,
}
)
trace.success(result)
return result
except CostLimitExceeded as e:
trace.error("cost_limit", str(e))
raise
except GuardrailViolation as e:
trace.error("guardrail", str(e))
raise
This pattern — wrapping agent logic in a harness class with hooks, cost tracking, and structured logging — is the core of the harness engineering discipline. It’s what separates a demo that works once from a system that works reliably at scale.
Stage 5: Your Portfolio Project (Weeks 11–12)
By now you have the skills to build something worth showing. Choose a portfolio project that demonstrates end-to-end harness engineering, not just the agent itself.
Project Ideas for Beginners
- Automated code reviewer — An agent that reads a GitHub PR, runs static analysis tools, and posts a structured review comment
- Personal knowledge base agent — Indexes your notes/bookmarks, answers questions with citations
- Meeting prep agent — Given a calendar event and attendee names, researches everyone and produces a briefing doc
- Customer support triage agent — Classifies support tickets, drafts responses, escalates when confidence is low
For each project, document:
1. The agent’s goal and tools
2. The harness: guardrails, logging, error handling, cost controls
3. What went wrong in testing and how you fixed it
That last point — the failure analysis — is what makes your portfolio stand out. Anyone can show a working demo. Showing that you understand and handle failure modes signals genuine production readiness.
The Harness Engineer’s Mindset
Here’s the mental shift that distinguishes harness engineers from prompt engineers:
Prompt engineers optimize for the best-case response.
Harness engineers design for the worst-case failure.
Every tool can return garbage. Every LLM call can hallucinate. Every loop can run forever. Your job is not to write the perfect prompt — it’s to build a system robust enough that imperfect prompts still produce acceptable outcomes.
This mindset is learned, not innate. The fastest way to develop it is to break your own agents deliberately. Write tests that inject malformed tool results. Send the agent adversarial inputs. Set your max_turns to 1 and see what breaks. The more chaos you introduce in development, the more confidence you’ll have in production.
What to Study Next
Once you’ve completed this roadmap, the natural next steps are:
- Multi-agent systems — coordinating fleets of specialized agents toward a shared goal
- Evaluation and evals — building automated test suites that measure agent reliability
- Advanced memory — vector stores, knowledge graphs, long-term episodic memory architectures
- Security — prompt injection defense, tool permission scoping, sandboxed execution environments
All of these topics are covered in depth here on harnessengineering.academy. Browse the tutorials section to find your next deep dive.
Your Action Plan This Week
- Set up your Python environment and get an API key from Anthropic or OpenAI
- Run the tool-calling example from Stage 1 and read the raw API response carefully
- Write the basic agent loop from scratch — no frameworks yet
- Start your research assistant project
The hardest part of building AI agents is not the code. It’s getting started. Every senior harness engineer has a story about the first agent that barely worked, crashed constantly, and cost $40 in API calls to debug. That’s the education. Go build yours.
Kai Renner is a senior AI/ML engineering leader and the founder of harnessengineering.academy. He writes about production AI systems, agent architecture, and the emerging discipline of harness engineering.
Ready to go deeper? Check out Introduction to Agent Harness Patterns and Your First LangGraph Agent: A Step-by-Step Tutorial to continue your learning journey.