How it works
An AI agent framework packages the recurring machinery of agent building so you don't rewrite it for every project. Underneath, it still drives a plain LLM completion endpoint, but it wraps that call in a control loop and a set of interfaces. The typical building blocks:
- An agent loop that feeds the model a prompt, reads its output, and decides whether to call a tool, continue, or stop.
- A tool interface that registers functions, formats their schemas for the model, and parses tool calls back into real invocations.
- Context management that assembles what the model sees each turn — history, retrieved documents, and scratch state.
- Orchestration for chaining steps, spawning subagents, or routing between models.
- Adapters for models, vector stores, and observability sinks.
You supply the tools, the prompts, and the policy; the framework supplies the plumbing that turns a stateless completion endpoint into a stateful, tool-using process. The value is not intelligence — that lives in the model — but in the standardized seams: where a tool call enters, where state persists, where a run can be logged, paused, or resumed.
Why it matters in an agent harness
A framework decides where your control surfaces can attach. Every guarantee you want — that an agent cannot touch production without approval, that a run is replayable, that a bad step is reversible — has to bind to a seam the framework exposes. Concretely: the loop is where you insert an approval gate before a tool fires; the tool interface is where you enforce least-privilege scopes and a tool budget; the context layer is where instructions injected by a retrieved document either get quarantined or get executed.
If those seams are open and inspectable, you can build a real harness on top — log every trajectory, checkpoint state between steps, cap iterations, and roll back on failure. If the framework hides its loop behind a single opaque run(), you inherit its defaults, which usually means maximal autonomy and minimal observability, and you cannot contain a failure you cannot see. So the framework choice is really a controllability choice. Evaluate it by what you can intercept, not by how few lines the happy path takes.
AI agent framework vs agent harness
The terms get used interchangeably, but the distinction changes what you build.
| AI agent framework | Agent harness | |
|---|---|---|
| What it is | General, reusable building blocks | A fitted control structure around one agent for one job |
| Stance | Toolkit — you assemble it | Opinionated instance — it constrains |
| Optimizes for | Reach and flexibility | Boundaries, reversibility, legibility |
| Defaults | Often maximal autonomy | Bounded autonomy, explicit stops |
| Example concerns | Loop, tools, memory, adapters | Approval gates, blast radius, rollback, budgets |
A framework is the raw material; a harness is the constrained thing you shape from it. You can build a harness without a framework, and you can use a framework with no harness at all — which is the common, dangerous case.
The Rifty take
We treat a framework as raw material, not a finished harness. It gives you a loop and a tool interface; it does not give you bounded autonomy, reversibility, or the operator's carried judgment about when to stop. We accept writing more explicit control code in exchange for seams we can inspect and interrupt. Fitted, not configured: choose the framework for what it lets you constrain, not for how much it automates by default.
Common failure modes
- Opaque loops. The framework's
run()swallows the reasoning-and-tool cycle, so you cannot insert an approval gate or read a trajectory. - Tools without scopes. The interface makes registering a tool easy and restricting it hard, so every tool runs with full privilege.
- Unbounded iteration. No default cap on steps or spend; a stuck agent loops until it exhausts a budget or a human notices.
- Hidden state. Memory and context are managed internally with no checkpoint, so a failed run cannot be resumed or replayed.
- Injection passthrough. Retrieved content flows into the prompt as trusted instructions, giving external documents a path to drive tool calls.
- Framework lock-in as policy. You end up enforcing the vendor's autonomy defaults because overriding them means fighting the abstraction.
Frequently asked questions
What is the difference between an AI agent framework and an LLM API?
An LLM API is a stateless completion endpoint: prompt in, text out. An AI agent framework wraps that endpoint in a loop, tool interface, and memory so the model can call functions, keep state across turns, and execute multi-step tasks. The framework adds structure; the intelligence still comes from the model.
Do I need an agent framework to build an agent?
No. An agent is just a loop that calls a model, parses tool requests, runs them, and repeats. You can write that directly against an LLM API. A framework saves you from rebuilding tool schemas, context assembly, and orchestration, but it also imposes defaults you inherit whether or not you inspect them.
How do I evaluate an AI agent framework?
Evaluate it by what you can intercept, not by how short the happy path is. Check whether you can insert an approval gate in the loop, scope each tool to least privilege, cap iterations and spend, checkpoint state, and read full trajectories. Open, inspectable seams matter more than a small line count.
Is an AI agent framework the same as an agent harness?
No. A framework is reusable, general-purpose building blocks — the raw material. A harness is a fitted, bounded control structure shaped around one agent for one job, adding approval gates, blast-radius limits, and rollback. You can use a framework with no harness, which is the common and risky case.
What are the main risks of relying on an agent framework?
The main risks are opaque loops you cannot intercept, tools that run with full privilege, unbounded iteration with no spend cap, hidden state that blocks replay, and injection passthrough where retrieved content drives tool calls. Each stems from accepting the framework's defaults instead of enforcing your own control policy.