At a glance
| Direct model/API | AI framework | |
|---|---|---|
| What you write | HTTP calls, your loop | Config + framework objects |
| Visibility | High | Depends on abstractions |
| Best for | Simple apps, learning, strict audit | Complex tools/RAG/multi-step flows |
| Risk | Reinventing glue | Opaque magic, version churn |
| Swap vendor | Change one client module | May touch many framework plugins |
What is each?
Direct integration means your code talks to the provider using HTTP or an official thin SDK (Calling AI and Model APIs with Python, Calling AI Services from JavaScript and TypeScript).
An AI framework supplies orchestration primitives on top. See How to Choose an Agent Framework for categories.
Key differences
Direct code makes prompt boundaries and tool permissions obvious in review. Frameworks can standardise patterns across a large team but may bury control flow in runners and callbacks. Performance and cost tracing are often easier when you own the loop — unless the framework's observability is excellent and you actually enable it.
When to choose which
- Choose direct for prototypes, compliance-sensitive paths, and features with one or two model calls.
- Choose a framework when multiple products share tool definitions, complex graphs, or retrieval pipelines and the team accepts the dependency.
- Hybrid is common: direct calls for core paths; framework helpers for a subsystem.
Example
A billing assistant with two tools (get_invoice, create_credit) fits a 60-line direct loop. A research desk that fans out to web search, document RAG and a writer agent may justify a graph-oriented framework — after a manual spike proves the design (Agentic Workflows: Patterns for Reliable AI Automation).
Practical notes
Cost and debugging differ too. Direct integration makes it obvious how many tokens each step used because you log the raw requests. Frameworks may batch or hide retries unless you enable tracing. Team skills matter: if nobody on call understands the framework's runnable graph, incidents take longer. Conversely, if five product squads each invent incompatible tool loops, a shared framework or shared internal library reduces drift. Write a short decision record: problem, options (direct vs framework categories), choice, and review date. Re-open that record when vendor pricing or tool count changes. Pair with What is an AI Framework? for definitions and How to Choose an Agent Framework for category fit. Work through one real request end to end, write down the failure modes you observed, and add a regression test so the next change does not silently drop validation, auth, or logging. Prefer boring, reviewable code over a clever abstraction until the second or third product needs the same pattern.
Common mistakes
- Rewriting working direct code into a framework with no capability gain.
- Assuming frameworks remove the need to understand Function Calling (Tool Calling) Explained.
- Skipping evals because the framework demo looked good.