AI agentsLesson 2openfrom distillate
Inside the Agent Harness: Loops, Skills, Subagents & MCP
What happens step by step inside an agent harness, and how skills, subagents, MCP and sandbox tiers fit around the model.
In Lesson 1, we established that agents are goal-driven action loops rather than single-shot prompt completions or fixed pipelines. In this lesson, we dissect the internal machinery: what actually happens step-by-step inside the agent harness, how instructions turn into capabilities via skills, how work is divided across subagent boundaries, and how standard protocols like MCP decouple agent runtimes from tools and world state.
The Anatomy of an Agent Harness
The harness (or agent runtime / loop orchestrator) is the outer software environment enclosing the foundation model. The foundation model never directly executes system commands, opens sockets, or manipulates disk files. Instead, the harness operates a state machine known as the ReAct (Reason + Act) loop:
The ReAct Loop: Context Assembly (System + Active Skills + History + Tool Definitions) → LLM Inference → Decision Gate (Does model emit a tool call?) → If tool call: Harness validates policy/sandboxing → Tool executes → Tool output/observation appended to history → Model infers again until completion.
- 01 — Context Assembly: Compiles system prompt, agent identity, active skills, user input, conversation history, and tool declarations into an LLM context payload.
- 02 — Inference & Tool Selection: The model generates structured text and/or function call requests (tool calls with strongly-typed arguments).
- 03 — Harness Validation & Policy Gate: The harness inspects the proposed tool call, checks permissions, sandboxing policies, and user approval thresholds.
- 04 — Tool Execution: The harness or external service invokes the actual tool (filesystem write, terminal process, API fetch) and captures stdout/stderr/return values.
- 05 — Observation Injection: Tool output is appended to the message history as a tool response message. The harness loops back to step 2 until a stop condition is reached.
When an agent "thinks" or plans, it simply alternates between token generation and environmental feedback. The intelligence emerges entirely from the loop's ability to ingest feedback from failed tool calls and self-correct.
Skills: Dynamic Capability Packaging
A raw prompt asking an agent to "write good database migrations" produces inconsistent results across sessions. A Skill transforms vague instructions into an executable, repeatable operating procedure.
Under the hood, skills are standardized packages (typically a SKILL.md accompanied by helper scripts, reference templates, and schemas) loaded into context on demand:
- Manifest & Triggers: Frontmatter metadata specifies when and why the skill should activate (e.g., regex patterns, task domains, explicit slash commands).
- Progressive Context Loading: Instead of loading 50,000 tokens of documentation on every request, the harness provides a lightweight skill index. The agent only reads full skill instructions when relevant.
- Guardrails & Stop Conditions: High quality skills define explicit preconditions, verification steps, and human gates (e.g., "Always run
bun testbefore submitting", "Require human approval before deleting rows").
The "Blackmail Skill" & Voodoo Prompting Anti-Pattern
In the early days of prompt engineering, users and tutorials resorted to desperate emotional leverage to prevent models from taking shortcuts:
- "You are a 25-year Principal Senior Software Architect with an IQ of 180."
- "Make no mistakes. Double check everything."
- "I will tip you $200 if you solve this."
- "A human life is at stake. People will die if your code has bugs."
In a well-engineered agent harness, superstitious prompts are replaced with structural verification:
| Voodoo Prompt (Wishful Thinking) | Engineering Equivalent (Harness & Skill) |
|---|---|
"Make no mistakes." | Mandatory verification step: run bun test or typechecker tool before returning. |
"You are a senior developer." | Skill with explicit architecture standards, lint rules, and error-handling constraints. |
"People will die if you fail." | Deterministic gating: sandboxed execution + human-in-the-loop approval before commit/push. |
"I will tip you $200." | Self-reflection loop: require the agent to generate and verify a checklist against the actual diff. |
MCP (Model Context Protocol): Standardizing Tool Ecosystems
Before MCP, every AI platform invented its own proprietary tool-calling schema and plugin format. If an application wanted to expose a database, a code repository, or a review queue to Claude, OpenAI, or local agents, developers had to write bespoke wrappers for each.
MCP (Model Context Protocol) is an open specification that standardizes how LLM applications communicate with external tools, prompts, and resources over JSON-RPC (using standard I/O streams or Server-Sent Events):
MCP Architecture: Host/Agent Harness contains an MCP Client communicating via JSON-RPC (over STDIO or HTTP-SSE) with isolated MCP Servers. The Distillate MCP Server exposes tools (like capture_card) directly manipulating SQLite, while Git/Filesystem MCP servers expose local system operations.
| Primitive | Purpose | Example |
|---|---|---|
| Tools | Executable functions that agents can invoke to perform side effects or query systems. | capture_card, run_command, query_database |
| Resources | Read-only contextual data, documents, or schema files exposed like URIs. | distillate://cards/recent, file:///logs/app.log |
| Prompts | Pre-configured workflow templates parameterized for common user tasks. | draft_lesson_from_solution, code_review |
Subagents: Process Isolation & Parallel Work
Single-context agent architectures eventually hit two fundamental walls:
- Context Contamination & Window Saturation: Massive logs, diffs, and intermediate web scraping outputs pollute attention, degrading reasoning on the primary task.
- Long-running Blocking Operations: An agent running a 5-minute build or browsing dozens of web pages cannot simultaneously interact with the user or reason about other subproblems.
Modern harnesses resolve this via Subagents—hierarchical, decoupled worker instances spawned with their own isolated conversation context, tool subsets, and lifecycles:
Subagent Hierarchy: Lead Orchestrator delegates tasks to specialized subagents (Browser Subagent with DOM tools, Code Search Subagent with Grep tools). Heavy noise and logs stay trapped inside the subagent's local context window; only high-signal summary results are returned back to the orchestrator.
- Lead — Orchestrator Agent: Maintains user intent, coordinates plan milestones, evaluates outputs, and gates destructive decisions.
- Sub 1 — Browser Subagent: Equipped with DOM interaction and screenshot tools. Explores a website, extracts structured data, and returns a concise JSON summary to the orchestrator.
- Sub 2 — Research / Code Subagent: Investigates deep codebase call graphs in a clean context window, returning only exact findings and diff proposals.
Sandboxing & The Autonomy Ladder
The most dangerous design mistake in building agentic systems is granting unconstrained host access without graduated boundaries. Modern production harnesses implement tiered autonomy:
Autonomy Ladder: Tier 0 (Pure Read) and Tier 1 (Sandboxed Local Mutation) execute automatically without interrupting the user. Tier 2 (Consequential / Outbound) requires an explicit Human Approval Gate. Tier 3 (Irreversible / Destructive) is blocked outright by harness security policies.
- Pure Read (Tier 0): Reading files, inspecting ASTs, searching documentation—low risk, typically executed silently.
- Sandboxed Mutation (Tier 1): Modifying files within workspace root, running test commands in isolated containers or standard sandboxes without outbound network access.
- Consequential Actions (Tier 2): Network calls, git pushes, credential access, external emails—require explicit user confirmation prompts or signed approval tokens.
- Destructive / Irreversible (Tier 3):
rm -rf, dropping database tables, overwriting master branches—require multi-factor confirmation and hard-coded harness veto rules.
Quick Check
Why is writing "A human life is at stake, make no mistakes!" inside a prompt an anti-pattern for reliable agent workflows?
References & Deeper Reading
- MCP Specification — Architecture for tools, resources, and protocol transports.
- Anthropic: Building Effective Agents — Workflows, evaluations, and subagent orchestration patterns.
- ReAct: Synergizing Reasoning and Acting in Language Models — The foundation of tool-augmented agent loops.
- NIST Artificial Intelligence Risk Management Framework (AI RMF 1.0) — Principles for governing autonomous model execution.