| name | three-layer-agent-stack |
| description | Use when building AI-powered products or agents, when raw model intelligence isn't enough to solve user problems, or when designing the architecture for agentic workflows |
The Three-Layer Agent Stack
Overview
A framework for building effective AI agents by synchronizing innovation across three distinct layers: Model, API, and Harness. Success requires tight integration—not treating the model as a black box.
Core principle: Features like "compaction" (long-running tasks) require simultaneous changes across all three layers.
The Stack
┌─────────────────────────────────────────────────────────────────┐
│ LAYER 3: HARNESS / PRODUCT LAYER │
│ ───────────────────────────────────────────────────────────── │
│ The environment that executes actions and provides context │
│ • VS Code / IDE integration │
│ • Terminal / Shell access │
│ • Sandbox / Secure execution environment │
├─────────────────────────────────────────────────────────────────┤
│ LAYER 2: API LAYER │
│ ───────────────────────────────────────────────────────────── │
│ Interface handling state, context windows, and orchestration │
│ • Context management / Compaction │
│ • State handoff between sessions │
│ • Tool routing and formatting │
├─────────────────────────────────────────────────────────────────┤
│ LAYER 1: MODEL LAYER │
│ ───────────────────────────────────────────────────────────── │
│ Foundation model providing reasoning and intelligence │
│ • Code generation / Reasoning │
│ • Summarization for compaction │
│ • Environment-specific training │
└─────────────────────────────────────────────────────────────────┘
Key Principles
| Principle | Description |
|---|
| Full-Stack Iteration | Changes often need Model + API + Harness together |
| Harness Specificity | Models perform best when trained for specific environments |
| Feedback Loops | Product usage (Harness) must inform model training |
| Safety Sandboxing | Harness provides secure environment for code execution |
Common Mistakes
- Model-only optimization: Changing model without adapting harness
- Generic API assumptions: Assuming generic API supports agentic behaviors
- No feedback loop: Harness doesn't feed back to model training
Real-World Example
Implementing "Compaction" to allow Codex to run 24 hours:
- Model: Must understand summarization
- API: Must handle the context handoff
- Harness: Must prepare and format the payload
Source: Alexander Embiricos (OpenAI Codex) via Lenny's Podcast
