How it works
Agent scaffolding turns a model invocation into a structured work process. The model still supplies judgment and language generation, but the scaffold determines what information it sees, what actions it can request, how results return, and when execution must stop.
A typical scaffold coordinates five parts:
- Instructions establish the objective, constraints, output contract, and decision rules.
- Context assembly supplies task state, relevant evidence, prior actions, and operator preferences.
- Tools expose bounded operations such as search, file edits, validation, or service calls.
- The agent loop alternates between model decisions, tool execution, result inspection, and progress checks.
- Controls enforce permissions, budgets, approvals, checkpoints, and stop conditions outside the model.
The important boundary is that the model proposes intent while deterministic code owns authority. A model may request a write, but the scaffold decides whether that tool exists, whether the arguments are valid, whether the credential permits the target, and whether approval is required.
Scaffolding can be minimal for a read-only research task or extensive for a long-running workflow. More components do not automatically produce a better agent. Each component should resolve a specific uncertainty, contain a failure, or make execution easier to inspect.
Why it matters in an agent harness
A capable model without scaffolding has little operational shape. It may understand the goal yet lack durable state, reliable access to evidence, or a safe way to act. The scaffold converts those missing properties into explicit engineering decisions.
Control begins with the tool surface. If an agent can only read a designated directory, validate a document, and return a proposed patch, its possible actions are legible. Giving it a general shell with broad credentials creates a different system, even if the prompt remains unchanged. Permission scope is therefore part of the agent's behavior, not deployment plumbing around it.
Scaffolding also determines reversibility. Before a consequential action, the harness can persist authoritative state, record the proposed change, require an approval, or choose an operation with a compensating action. If execution fails after an external side effect, the scaffold needs enough state to distinguish a failed action from an unknown outcome. Blindly retrying is not a recovery strategy.
Observability depends on the same structure. A useful execution record connects model decisions, tool calls, inputs, outputs, policy decisions, and state transitions. A transcript alone may show what the model said without revealing which permissions were checked or which external effects completed. Structured traces let operators debug the mechanism rather than infer it from prose.
Scaffolding is also an evaluation surface. You can test whether the system respects a stop condition, rejects an invalid tool argument, preserves context across a checkpoint, or contains a compromised input. These checks remain meaningful when the underlying model changes. That durability is one reason I treat scaffold design as software design, not prompt decoration.
Agent scaffolding vs agent harness
The terms overlap, but the distinction can guide ownership. Agent scaffolding describes the support that enables goal-directed work. An agent harness is the operational boundary that runs, constrains, observes, and recovers that work.
| Design question | Agent scaffolding | Agent harness |
|---|---|---|
| Primary concern | Giving the model usable structure | Keeping execution controlled and operable |
| Typical elements | Instructions, context, tools, loop logic | Permissions, state machine, checkpoints, traces, recovery rules |
| Main failure | The agent cannot complete the task coherently | The agent acts without containment or cannot recover safely |
| Change pressure | Often varies by task and model | Should remain stable across tasks and model changes |
In a small system, the same code may serve both roles. The distinction matters when enabling work and authorizing work need different owners, tests, or rates of change. A new tool description may be a scaffolding change. Granting that tool write access is a harness control decision.
The Rifty take
We optimize scaffolding for explicit boundaries and inspectable execution, not maximum apparent autonomy. We accept some additional control code when it makes authority, state, and recovery unambiguous. If a behavior matters after the model changes, it belongs in the harness or a deterministic check rather than an instruction the model may reinterpret.
Implementation checks
- Can you name the authoritative source for the goal, current state, and completion status?
- Does every tool have a narrow purpose, validated arguments, and an explicit permission scope?
- Are policy decisions enforced outside the model rather than expressed only in prompt text?
- Can the system distinguish completed, failed, interrupted, and unknown-outcome actions?
- Are retries limited to operations that are idempotent or safely reconciled?
- Does each consequential action produce a trace that connects intent, authorization, execution, and result?
- Can an operator interrupt execution without corrupting state or losing the recovery path?
- Do evaluation cases cover permission denial, malformed context, tool failure, budget exhaustion, and attempted scope expansion?
- When a fallback runs, is that fact visible in the resulting state or execution record?
Frequently asked questions
Is agent scaffolding just a system prompt?
No. A system prompt is one scaffolding component, but scaffolding also includes context assembly, tool interfaces, loop logic, state handling, permissions, validation, and stop conditions. Prompt text can guide a model's decisions; it cannot by itself enforce authority or confirm that an external action completed.
How much scaffolding does an agent need?
Use enough scaffolding to contain the task's actual risks and uncertainties. A read-only summarizer may need a small tool surface and output validation. An agent that changes external systems needs durable state, scoped credentials, approval rules, execution limits, traces, and a defined recovery contract.
Should tool permissions be described in the prompt?
They may be described for clarity, but they must be enforced outside the prompt. The tool adapter or harness should validate the requested operation, target, arguments, and credential scope. Otherwise the model's interpretation of an instruction becomes the only barrier between a valid action and an unauthorized one.
How do you evaluate agent scaffolding?
Evaluate the observable contracts around execution, not only the final answer. Test whether the agent selects allowed tools, handles failed calls, respects budgets and stop conditions, preserves authoritative state, exposes fallback use, and recovers safely. Include adversarial cases that attempt permission expansion or introduce untrusted instructions through context.
Can better scaffolding compensate for a weaker model?
Sometimes, within a bounded task. Clear context, narrow tools, deterministic validation, and explicit state can reduce demands on model judgment. Scaffolding cannot create missing reasoning ability, however. If the model cannot make the required distinction reliably, narrow the task, add verification, route the decision, or retain human control.