ai agent tutorial: Build Your First Real Agent Step by Step

If you have been reading about autonomous systems for months but still have nothing running on your machine, this ai agent tutorial is for you.

Most first attempts fail for a simple reason: tutorials stop at “it ran once.” Real agents are not one prompt and one response. They need loops, tool boundaries, budgets, logs, and clear stop conditions. Without that, your “agent” is just a fragile demo that breaks the first time input changes.

In this guide, you will build a minimal but real agent runtime, wire it to safe tools, run an end-to-end task, debug common failures, and finish with a production readiness checklist. This is intentionally execution-first. You should be able to copy the commands, run them, inspect outputs, and know exactly what to improve next.

If you want deeper background after this walkthrough, these Starkslab notes pair well with the build:

• Minimal runtime design: https://starkslab.com/drops/minimal-agent-framework
• Python framework breakdown: https://starkslab.com/notes/build-lightweight-ai-agent-framework-python
• Tooling architecture patterns: https://starkslab.com/notes/build-cli-tools-ai-agents-analytics
• Workflow patterns for shipping: https://starkslab.com/notes/ai-coding-agent-workflow

---

What this ai agent tutorial actually builds

By the end, you will have a local agent that can:

1. Receive a task goal.
2. Plan the next step.
3. Decide whether to call a tool or finish.
4. Execute tool calls with typed input.
5. Write every step to a trace file.
6. Halt safely when budget or stop conditions are hit.

That sounds simple, and that is exactly the point. A first agent should be understandable in one reading session. If you cannot explain the loop, you cannot debug it.

What this build does not include (on purpose):

• Multi-agent orchestration
• Long-term vector memory pipelines
• Background distributed workers
• Full UI dashboards
• Autonomous internet-wide browsing without constraints

Those are second-stage concerns. Your first milestone is reliability, not complexity.

A useful mental model:

• Model = reasoning engine
• Agent loop = decision engine
• Tools = capability layer
• Guardrails = safety + cost control
• Traces = observability

If one layer is missing, you either lose control, lose visibility, or lose repeatability.

---

What do you need before you build your first AI agent?

You only need a small stack:

• Python 3.10+
• A terminal
• One model API key
• A project folder
• 45-90 focused minutes

For model providers, you can use OpenAI-compatible APIs. If you are new to tool calling format and payload expectations, skim the provider reference first: https://platform.openai.com/docs/guides/function-calling. It will save you an hour of guesswork when your first tool payload fails schema validation.

Create a clean working directory:

mkdir -p ~/projects/first-agent
cd ~/projects/first-agent
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install pydantic python-dotenv requests

Then add your environment config:

cat > .env <<'EOF'
OPENAI_API_KEY=replace-me
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL=gpt-4.1-mini
MAX_STEPS=10
MAX_SECONDS=120
EOF

Why these constraints early?

• MAX_STEPS prevents runaway loops.
• MAX_SECONDS prevents infinite drift.
• Fixed model value improves reproducibility while learning.

Before writing any runtime code, decide your first task domain. Keep it painfully narrow. Good first task examples:

• Summarize local markdown notes and produce an action list
• Run a fixed CLI command and turn output into a report
• Read a local JSON file and generate a concise decision memo

Bad first task examples:

• “Automate my business end-to-end”
• “Trade crypto autonomously”
• “Research everything about market X and launch a campaign”

Narrow scope is not a limitation. It is how you get to reliable behavior fast.

---

How to build an AI agent loop from scratch (minimal version)

The core runtime has one job: repeat decision cycles until the model returns a final answer or a halt condition is reached.

A minimal loop looks like this:

# main.py
import json, os, time, subprocess
from dotenv import load_dotenv

load_dotenv()

MAX_STEPS = int(os.getenv("MAX_STEPS", "10"))
MAX_SECONDS = int(os.getenv("MAX_SECONDS", "120"))
TRACE_PATH = "trace.jsonl"


def trace(event: dict):
    with open(TRACE_PATH, "a", encoding="utf-8") as f:
        f.write(json.dumps(event, ensure_ascii=False) + "\n")


def shell_exec(command: str) -> dict:
    try:
        completed = subprocess.run(
            command,
            shell=True,
            capture_output=True,
            text=True,
            timeout=20,
        )
        return {
            "ok": completed.returncode == 0,
            "returncode": completed.returncode,
            "stdout": completed.stdout[-4000:],
            "stderr": completed.stderr[-2000:],
        }
    except Exception as e:
        return {"ok": False, "error": str(e)}


TOOLS = {
    "shell.exec": shell_exec,
}


def mock_model_decide(state):
    # Replace with real model call.
    # Contract: return either {"type": "tool_call", ...} or {"type": "final", ...}
    if len(state["tool_results"]) == 0:
        return {"type": "tool_call", "tool": "shell.exec", "input": "ls -la"}
    return {"type": "final", "output": "Done. Directory inspected."}


def run_agent(goal: str):
    start = time.time()
    state = {"goal": goal, "tool_results": []}

    for step in range(MAX_STEPS):
        if time.time() - start > MAX_SECONDS:
            return {"status": "halted", "reason": "max_seconds", "state": state}

        decision = mock_model_decide(state)
        trace({"step": step, "event": "decision", "decision": decision})

        if decision.get("type") == "final":
            return {"status": "completed", "output": decision.get("output"), "state": state}

        if decision.get("type") == "tool_call":
            tool = decision.get("tool")
            tool_input = decision.get("input", "")
            fn = TOOLS.get(tool)
            if not fn:
                result = {"ok": False, "error": f"unknown tool: {tool}"}
            else:
                result = fn(tool_input)

            state["tool_results"].append({"tool": tool, "input": tool_input, "result": result})
            trace({"step": step, "event": "tool_result", "tool": tool, "result": result})
            continue

        return {"status": "halted", "reason": "invalid_decision", "decision": decision}

    return {"status": "halted", "reason": "max_steps", "state": state}


if __name__ == "__main__":
    outcome = run_agent("Inspect current directory and report findings")
    print(json.dumps(outcome, indent=2))

Why this structure matters:

• The model is forced into one of two explicit actions.
• Tool execution is isolated and typed.
• Every step is persisted as JSONL.
• Halt reasons are explicit, not accidental.

At this stage, avoid hidden magic. No implicit retries. No “auto repair everything” layer. First make failures legible, then improve resilience.

---

How to add tools without making your agent dangerous

Tools are where agents become useful, and where they become risky.

Start with three principles:

1. Allowlist tools

   • Never allow arbitrary tool names from model output.
   • Bind model choices to a known dictionary.

2. Constrain inputs

   • Validate command shape and argument length.
   • Reject dangerous tokens for early versions (rm -rf, recursive wildcards on system paths, raw SSH calls).

3. Constrain environment

   • Run from a known working directory.
   • Restrict filesystem writes to a sandbox path.
   • Set per-tool timeout.

A practical first tool set:

• fs.read(path)
• fs.write(path, content)
• shell.exec(command) with strict filters
• http.fetch(url) with allowlisted domains

If you need broad shell capabilities later, add them with layered controls, not all at once.

A common pattern from early builders is to over-trust model intent: “The model will only do what I asked.” It will not. It will do what your interface permits under imperfect interpretation. Security must be enforced by runtime constraints, not prompt phrasing.

For high-signal design patterns on CLI tool interfaces, revisit this note when you are ready to improve tool ergonomics: https://starkslab.com/notes/build-cli-tools-ai-agents-analytics.

---

How to run this ai agent tutorial on your machine

Now run the full flow as a simple, repeatable sequence.

# 1) enter project
cd ~/projects/first-agent
source .venv/bin/activate

# 2) write runtime
cat > main.py <<'PY'
# (paste the Python code from this tutorial)
PY

# 3) execute
python main.py

# 4) inspect trace
wc -l trace.jsonl
tail -n 20 trace.jsonl

# 5) rerun after changing the goal/decision logic
python main.py

Your success criteria for run one:

• Process returns completed or a clear halted reason
• A trace.jsonl file is generated
• At least one tool call is logged with structured output
• You can explain exactly why the run stopped

If any of those fail, do not add more features. Fix observability first.

Once the baseline works, swap mock_model_decide for a real model call and keep the same decision contract. Most first migrations fail because developers change loop logic and model interface simultaneously. Change one variable at a time.

---

How to evaluate your first runs like an engineer

Most beginners judge runs emotionally: “it felt good” or “it looked weird.” That is too subjective. Use a small scorecard on every run so you can improve quickly without confusion.

Track these five metrics:

1. Task completion quality
   • Did the final output satisfy the goal, or just produce plausible text?
2. Step efficiency
   • How many steps were used versus your MAX_STEPS budget?
3. Tool quality
   • Were tool calls valid on first attempt?
   • Did tool output directly improve the next decision?
4. Safety compliance
   • Any rejected tool calls? Any path or host policy violations?
5. Reproducibility
   • If you rerun with same input, do you get similar trajectory and halt reason?

A practical target for early versions:

• Completion quality: useful answer in under 10 steps
• Tool validity: >80% first-try valid payloads
• Safety: zero policy violations
• Reproducibility: similar outcome across 3 reruns

You can extract basic telemetry from trace.jsonl with a tiny script:

python - <<'PY'
import json
from collections import Counter

steps = 0
events = Counter()
failed_tools = 0

with open('trace.jsonl', 'r', encoding='utf-8') as f:
    for line in f:
        row = json.loads(line)
        steps = max(steps, row.get('step', 0) + 1)
        events[row.get('event', 'unknown')] += 1
        if row.get('event') == 'tool_result':
            ok = row.get('result', {}).get('ok')
            if ok is False:
                failed_tools += 1

print('steps:', steps)
print('events:', dict(events))
print('failed_tool_calls:', failed_tools)
PY

Do not optimize all metrics at once. Pick the biggest failure source and attack it in isolation.

• If tool failures dominate, tighten schemas and command shaping.
• If step count explodes, improve completion criteria.
• If outputs look generic, improve prompt grounding with concrete objectives and acceptance checks.

A simple decision contract that prevents drift

Many agents get stuck because the model never knows when to stop. Add a strict instruction contract around every decision turn:

• You must return exactly one action.
• Allowed actions: tool_call or final.
• If required evidence is missing, choose tool_call.
• If required evidence is present, choose final.
• Never invent tool names or fields.

Then define required evidence per task. Example for an analytics summary:

• 30d visitor count present
• Top 3 referrers present
• One bottleneck and one recommendation present

This removes ambiguity from the finish line. Ambiguity is where loops spiral.

---

What went wrong in this ai agent tutorial (and how to fix it fast)

These are the failures almost everyone hits in the first week.

1) Tool output too noisy to parse

Symptom: model keeps asking for the same command again, or produces weak final summaries.

Cause: stdout is verbose or inconsistent.

Fix: cap output length and prefer machine-friendly outputs where possible (--json, line-delimited formats, stable keys).

---

2) Loop never reaches final answer

Symptom: repeated tool calls until max_steps halt.

Cause: no explicit model guidance for “done” criteria.

Fix: add completion conditions in the decision prompt contract. Example: “Return final when you have A, B, and C facts.”

---

3) Invalid tool payload shape

Symptom: runtime rejects calls with missing fields or wrong types.

Cause: unconstrained tool schema.

Fix: enforce strict JSON schema and return structured validation errors to state so the model can self-correct next step.

---

4) Costs spike during debugging

Symptom: long tool outputs, repeated retries, many loop steps.

Cause: no budget controls and no truncation policy.

Fix: hard limits on tokens per step, output truncation, retry caps, and strict stop conditions.

---

5) “Works once, fails later” behavior

Symptom: first run passes; second run breaks after tiny input variation.

Cause: hidden assumptions in parsing and stop logic.

Fix: build tiny regression cases from traces. Save 3-5 historical traces and replay decisions against them before changing logic.

If you want a practical workflow for iterating these fixes quickly without chaos, use this pattern: isolate one bug class per cycle, patch, run one trace replay, then run one live task. That discipline is covered in https://starkslab.com/notes/ai-coding-agent-workflow.

---

How to harden your agent for real usage

Once local runs are stable, harden in layers:

Layer 1: Safety controls

• Tool allowlist only
• Path sandboxing for read/write
• URL allowlist for network calls
• Per-tool timeout and global timeout

Layer 2: Reliability controls

• Retry policy only for transient failures
• Idempotent writes when possible
• Deterministic halt reasons
• Trace IDs per run

Layer 3: Cost controls

• Step budget
• Token/output budget
• Model fallback policy (cheap model first, stronger model on fail)

Layer 4: Operational controls

• Daily trace review
• Alert on consecutive halts of same type
• Versioned prompts and tool schemas
• Changelog for behavior-affecting changes

Treat your runtime as software infrastructure, not a prompt experiment. That mindset shift is the difference between occasional demos and compounding utility.

---

Production checklist

Use this checklist before you trust the agent with important tasks:

• Every tool has documented input/output schema.
• Unknown tool names are rejected safely.
• All write operations are constrained to approved paths.
• max_steps, max_seconds, and per-tool timeout are enforced.
• Trace file includes decision + tool result for every step.
• Halt reasons are explicit (max_steps, max_seconds, invalid_decision, tool_error).
• At least 3 replay traces pass after any runtime change.
• Error messages are structured and actionable.
• External calls use allowlisted hosts only.
• Cost guardrails are tested (token and output caps).
• One rollback path exists for prompt/schema updates.
• You can explain “why this run stopped” in under 30 seconds.

If you cannot check these quickly, the system is not production-ready yet.

---

Conclusion

The fastest path through an ai agent tutorial is not adding more framework layers. It is mastering one loop, one constrained toolset, and one trace-driven debugging cycle until outcomes are predictable.

Build small, instrument deeply, and harden incrementally. Once this baseline is stable, you can branch into richer memory systems, broader tool ecosystems, and autonomous scheduling with far less pain.

---

Summary

In this ai agent tutorial, you built a minimal real agent runtime, ran a complete command-driven flow, handled common failure modes, and finished with a production checklist you can apply immediately.

Next move: pick one narrow task from your own workflow and ship v1 today. Then iterate with traces, not guesswork. For concrete telemetry and search workflows after the runtime exists, see Datafast CLI for AI Agent Tools: Workflow, Artifacts, Handoffs and SEO CLI for AI Developer Tools: SERPs, Audits, Handoffs.