Lesson 7 / 25

Choosing: Raw API or Framework

Apply a simple decision guide and know when to start without a framework.

A decision guide

Start with the raw API and a small loop when the task is simple or you need full control. Reach for a framework when you need persistence, human approval, tracing, parallel branches or many agents, and the framework's model fits your problem. Always prefer the option you can debug.

A checklist

If most answers are "no", stay with the raw API for now. You can adopt a framework later when a real need appears.

Need to pause and resume long runs?        yes / no
Need human approval steps?                   yes / no
Need tracing across many steps?              yes / no
Need several cooperating agents?             yes / no
Team already knows this framework?           yes / no

Keep tools framework-independent

Write your tool functions as plain code (or expose them over MCP). Then switching frameworks only changes the wiring, not the useful part.

Quick check: Which project most clearly justifies starting with the raw API?

  • A system needing pause, resume and human approvals across hours
  • A small script that calls one or two tools
  • A team of ten cooperating agents
  • A product needing full tracing dashboards
Answer

A small script that calls one or two tools — A small task does not need framework machinery, and the raw loop is easy to understand.