The 3 concepts of building an agent

Tap any concept to jump to its 5-card cluster.

• 1Why Three Approaches?Control vs convenience spectrum
• 2The Three, Side by SideRaw API, tool loop, framework
• 3When to Use WhichPicking the right layer

Three layers on one spectrum

You can build the same agent at three levels of abstraction: raw API calls (you drive every step), a hand-written tool-use loop (you own the loop, the model picks tools), or a framework like CrewAI (the loop is hidden, you configure roles).

It's one trade-off: more convenience means less visibility and control. This course teaches the raw layer first on purpose — once you've built the loop by hand, every framework becomes readable instead of magic.

Three ways to make coffee

BEFORE: You want a cup of coffee. You can grind beans by hand, heat water on the stove, and do a careful pour-over — total control over every variable.

PAIN: The pour-over is slow and fiddly. A one-button machine is fast, but if the coffee comes out weak you have no idea which knob to turn — the machine hid all of them.

MAPPING: Raw API = pour-over (full control, more work). Tool-use loop = stovetop moka pot (some structure, still visible). Framework = push-button machine (fast, opaque). Learn the pour-over first so you understand what the machine is doing for you.

What each layer hides

1. Raw APIYou write every request, read every response, and wire tools and history yourself. Nothing hidden.
2. Tool-use loopYou still own a while loop, but the model decides which tool to call; you dispatch it and feed the result back.
3. FrameworkThe loop, retries, and message bookkeeping are built in. You declare agents, tools, and goals; it runs them.
4. Same result, different visibilityAll three can produce the identical answer — they differ in how much you see and can tune.

Why learn all three?

# The learning path, on purpose:

START raw API
  # see exactly how a call + tool works

THEN hand-write the tool-use loop
  # understand what every framework runs

THEN reach for a framework
  # now it's readable, not magic —
  # you know what it hid and can debug it

Frameworks are great — but only once you can see through them.

Misconceptions

One task, three sizes of code

Ask the three layers to do the same job — answer a question, maybe using a tool — and the code shrinks as you climb. Raw is the most lines, the framework is the fewest, and the tool-use loop sits in between.

What disappears isn't your logic (tools, prompts, goals) — it's the boilerplate: the request formatting, the loop, the message bookkeeping. Seeing them side by side makes crystal clear what a framework actually saves you.

Handwritten vs template vs form letter

BEFORE: You need to send the same kind of letter often. You could write each one from scratch, every word.

PAIN: From-scratch is slow and error-prone for a routine letter. But a fully pre-filled form letter gives you almost nothing to change — and hides how it's built.

MAPPING: Raw API = writing each letter by hand. Tool-use loop = a template with clear blanks you fill. Framework = a form letter where you just supply a name. Same letter arrives; you chose how much of the writing to do.

The same job, three ways

1. Raw APIOne chat.completions.create call. No tools, no loop — just send messages, read the text. The "hello world."
2. Tool-use loopDefine tools, then loop: call the model, if it wants a tool run it and feed the result back, repeat until it answers.
3. Framework (CrewAI)Declare an agent with a role, goal, and tools; call kickoff(). The loop runs inside the library.
4. Your logic is identicalThe tools and the prompt are the same across all three — only the surrounding machinery changes.

Pseudocode

# 1) RAW — you write everything
reply = model.chat(messages)         # that's it

# 2) TOOL-USE LOOP — you own the loop
WHILE TRUE:
  r = model.chat(messages, tools)
  IF no tool_calls: RETURN r.text
  run each tool; append results

# 3) FRAMEWORK — the loop is hidden
agent = Agent(role, goal, tools=[...])
result = agent.kickoff(task)          # loop inside

Misconceptions

Pick the layer that fits the job

None of the three is "best." Raw shines when you need full control or are learning. The tool-use loop is the sweet spot for most custom agents — readable and tunable. A framework wins when you want speed, standard patterns, and multi-agent orchestration out of the box.

The right default for this course is the hand-written loop: enough structure to be productive, enough visibility to debug. You reach for a framework when the convenience clearly outweighs the lost control.

Bike, car, or bus?

BEFORE: You need to get across town and you have three options: bike, your own car, or the bus.

PAIN: There's no universally best choice. The bus is effortless but goes only where its route goes; the bike is total freedom but you do all the work.

MAPPING: Raw = the bike (full control, most effort). Tool-use loop = your own car (flexible, you steer). Framework = the bus (fast on common routes, fixed path). Match the vehicle to the trip, not to fashion.

Strengths at a glance

1. Raw API — control & learningBest when you need custom behavior, tight debugging, or you're building the mental model.
2. Tool-use loop — the defaultMost custom single-agent work. Readable, tunable, and it's what the whole course builds on.
3. Framework — speed & scaleGreat for standard patterns, rapid prototypes, and multi-agent orchestration you'd rather not hand-roll.
4. You can mixPrototype in a framework, then drop to the loop for the one part that needs control.

Which layer, right now?

IF learning, or you need full control /
   custom mid-loop behavior:
  USE raw API

ELIF building a custom single agent
      (most of the time):
  USE the hand-written tool-use loop

ELIF you want standard multi-agent
      orchestration fast:
  USE a framework (CrewAI, LangGraph)

# default for this course: the loop

Misconceptions

Test the core insight

One question per concept. Tap to reveal the answer.