Build Your Own AI Coding Agent Harness

Vercel published a course that walks developers through building TeensyCode, a working AI coding agent harness in TypeScript, from a zero-tool chatbot up to a ToolLoopAgent with read, grep, write, edit, bash, task and askUser tools. The course covers execute-level safety gates with safe-command allowlists and configurable approval, a Sandbox interface with local (Node fs and child_process) and in-memory (just-bash with a copy-on-write virtual filesystem) backends, pruneMessages context management, and subagent delegation with isolated context. It requires TypeScript, an AI_GATEWAY_API_KEY environment variable, and Node.js 22+ or the Bun runtime, and spans 11 modules, with modules 1 through 6 as build-along and module 7 covering sandbox lifecycle concepts.

A tool loop with three tools is a demo. The problems start when you try to use it for real work. You read a 5,000-line file and it stays in context forever. You give it bash and it runs rm -rf . You ask it to refactor a module and it explains how to refactor a module. One long task fills the context window and the agent loses its own instructions. The cloud sandbox costs money per minute and your code disappears when it times out. Harness is the word for the system around the agent that handles all of this. This course builds TeensyCode from scratch. What You'll Build what-youll-build TeensyCode is a working AI coding agent harness with a compact TypeScript core, a real toolset, and multiple sandbox backends. Something you understand completely because you built every piece: - The loop: ToolLoopAgent with read , grep , write , edit , bash , task , and askUser tools - Safety gates: Execute-level safety with safe-command allowlists, evolving into configurable approval interactive, background, delegated - Behavioral prompts: A structured system prompt with Agency, Guardrails, and Handling Ambiguity sections, plus AGENTS.md injection for per-project configuration - Sandbox abstraction: One Sandbox interface, two implementations: local Node fs and child process and in-memory just-bash with a copy-on-write virtual filesystem . Swap the backend, the tools don't change - Context management: pruneMessages , bounded tool output, and cache control to keep long-running sessions usable and affordable - Subagent delegation: Explorer and executor roles with isolated context, constrained tools, and a model picked per job - Human-in-the-loop: askUser with multiple-choice options and an ambiguity protocol that prefers search, then questions, then action - Sandbox lifecycle: State-machine thinking, snapshot and restore, and durable workflow concepts - Extensibility: Event bus, skills with progressive disclosure, and custom tool registration Prerequisites prerequisites - TypeScript, async/await, basic terminal experience - An AI GATEWAY API KEY environment variable - Node.js 22+ or Bun runtime - Recommended: Building Filesystem Agents https://vercel.com/academy/filesystem-agents course How The Course Works how-the-course-works Causal sequence. Each step exists because the previous one broke something. Step 1 adds read because the chatbot can't see files. Step 2 adds grep because the agent can't search. Step 3 adds bash because it can't run commands, but now it can rm -rf . Each step spotlights one concept while the rest stays runnable. Modules 1 through 6 are build-along. You write code, run it, verify. Module 7 is concept and analysis sandbox lifecycle involves durable workflows and state machines you can't safely demo locally . Modules 8 through 11 mix building and analysis. Course Modules course-modules Module 1: The Agent Loop module-1-the-agent-loop Build a ToolLoopAgent from zero tools a chatbot to read and grep an agent to bash with safety gates. - From Chat to Agent https://vercel.com/academy/build-ai-agent-harness/from-chat-to-agent , where one tool turns a chatbot into an agent - Your First Tools https://vercel.com/academy/build-ai-agent-harness/your-first-tools , where tool descriptions become the model selection API - Completing the Toolbox https://vercel.com/academy/build-ai-agent-harness/completing-the-toolbox , where dangerous tools get execute-level gates Module 2: Tool Design module-2-tool-design Evolve descriptions into a 5-section contract, extract the factory pattern, and build configurable approval. - Descriptions That Work https://vercel.com/academy/build-ai-agent-harness/descriptions-that-work : WHEN TO USE, WHEN NOT TO USE, DO NOT USE FOR, EXAMPLES - Shell Execution with Safety https://vercel.com/academy/build-ai-agent-harness/shell-execution-with-safety : factory plus operations separates contract from execution - Approval Gates https://vercel.com/academy/build-ai-agent-harness/approval-gates : boolean to function to discriminated union Module 3: The System Prompt module-3-the-system-prompt Shape behavior with structured instructions, dynamic composition, verification gates, and AGENTS.md . - Structuring Agent Instructions https://vercel.com/academy/build-ai-agent-harness/structuring-agent-instructions : Agency plus Guardrails, act don't explain - Dynamic Prompt Construction https://vercel.com/academy/build-ai-agent-harness/dynamic-prompt-construction : buildSystemPrompt adapts to runtime context - Verification Gates https://vercel.com/academy/build-ai-agent-harness/verification-gates : typecheck, lint, test, build contract - Project Context https://vercel.com/academy/build-ai-agent-harness/project-context : drop an AGENTS.md , change the agent Module 4: The Sandbox Abstraction module-4-the-sandbox-abstraction One interface, three implementations. Tools call sandbox.exec , not child process.exec . - Designing the Interface https://vercel.com/academy/build-ai-agent-harness/designing-the-interface : the Sandbox type with readFile , exec , stop - Local Implementation https://vercel.com/academy/build-ai-agent-harness/local-implementation : Node fs plus child process wrapper - In-Memory Implementation https://vercel.com/academy/build-ai-agent-harness/in-memory-implementation : just-bash with a copy-on-write overlay - Cloud Implementation https://vercel.com/academy/build-ai-agent-harness/cloud-implementation : remote VM concept and tradeoffs - Lifecycle Hooks https://vercel.com/academy/build-ai-agent-harness/lifecycle-hooks : afterStart , beforeStop , onTimeout Module 5: Context Management module-5-context-management Every tool call stays in context forever. Fix it with pruning, bounded output, and cache control. - The Problem https://vercel.com/academy/build-ai-agent-harness/the-problem : token logging shows linear growth - Pruning Old Results https://vercel.com/academy/build-ai-agent-harness/pruning-old-results : pruneMessages keeps stale tool output from piling up - Tool Output Design https://vercel.com/academy/build-ai-agent-harness/tool-output-design : prevention over cleanup, with bounded caps on every tool - Cache Control https://vercel.com/academy/build-ai-agent-harness/cache-control : provider headers reduce repeated context costs Module 6: Subagent Delegation module-6-subagent-delegation Parent plans, subagents execute. Isolated context, constrained tools, role-based models. - Why Delegate https://vercel.com/academy/build-ai-agent-harness/why-delegate : single-agent failure modes - Explorer Subagent https://vercel.com/academy/build-ai-agent-harness/explorer-subagent : read-only, cheap model, constrained exploration - Executor Subagent https://vercel.com/academy/build-ai-agent-harness/executor-subagent : full tools, stronger model, delegated trust - Task Tool https://vercel.com/academy/build-ai-agent-harness/task-tool : routing, permissions, model per role Module 7: Sandbox Lifecycle module-7-sandbox-lifecycle Cloud sandboxes cost money and time out. Concept and analysis module. - State Machine https://vercel.com/academy/build-ai-agent-harness/state-machine : state transitions, timeouts, and activity tracking - Snapshot and Restore https://vercel.com/academy/build-ai-agent-harness/snapshot-and-restore : freeze, restore, and idempotency hazards - Durable Workflows https://vercel.com/academy/build-ai-agent-harness/durable-workflows : Vercel Workflow with sleep - Hard-Won Lessons https://vercel.com/academy/build-ai-agent-harness/hard-won-lessons : production gotchas from lifecycle work Module 8: Human-in-the-Loop module-8-human-in-the-loop Agents that guess wrong waste more time than agents that ask. - Structured Questions https://vercel.com/academy/build-ai-agent-harness/structured-questions : askUser with multiple choice and an ambiguity protocol - Approval Config https://vercel.com/academy/build-ai-agent-harness/approval-config : config for modes, events for policies Module 9: Planning and Verification module-9-planning-and-verification Plan before acting, verify after acting. - Todo Tool https://vercel.com/academy/build-ai-agent-harness/todo-tool : task decomposition with state tracking - Fast Context Understanding https://vercel.com/academy/build-ai-agent-harness/fast-context-understanding : grep first, read only what you'll change - Verification Contract https://vercel.com/academy/build-ai-agent-harness/verification-contract : gate sequence with scoped claims Module 10: Surfaces module-10-surfaces The agent is headless. CLI, TUI, and web are rendering strategies. - CLI Entry Point https://vercel.com/academy/build-ai-agent-harness/cli-entry-point : args, sandbox factory, clean shutdown - Streaming and Tool Rendering https://vercel.com/academy/build-ai-agent-harness/streaming-and-tool-rendering : real-time text plus tool call display - Web Surface https://vercel.com/academy/build-ai-agent-harness/web-surface : same agent, different renderer Module 11: Extensibility module-11-extensibility Events, not inheritance. Skills as progressive disclosure. Tools as registrations. - Skills System https://vercel.com/academy/build-ai-agent-harness/skills-system : names in the prompt, full content on demand - Custom Tools https://vercel.com/academy/build-ai-agent-harness/custom-tools : register without forking, compose existing tools - Extension Points https://vercel.com/academy/build-ai-agent-harness/extension-points : lifecycle events for subscribe, block, modify Capstone capstone Run your harness against a real project. Not "add a hello world endpoint" but "add rate limiting to the auth routes." Watch where context overflows. Watch where it picks the wrong tool. Watch where the subagent gets bad instructions. Fix what breaks. Tech Stack tech-stack | Component | Purpose | |---|---| | AI SDK https://sdk.vercel.ai | ToolLoopAgent , tool , isStepCount , pruneMessages , streaming | | AI Gateway https://vercel.com/ai-gateway | Model routing. "anthropic/claude-haiku-4.5" as a string, no wrapper | | Vercel Sandbox https://vercel.com/docs/sandbox | Remote VM with an isolated filesystem, git, and npm | | just-bash https://www.npmjs.com/package/just-bash | In-memory virtual filesystem and simulated bash | | Vercel Workflow https://vercel.com/docs/workflows | Durable workflows for sandbox lifecycle | | Zod https://zod.dev | Tool input schemas | On this page