Building Filesystem Agents

LLMs have been trained on massive amounts of code. They've spent countless hours navigating directories, grepping through files, and managing state across complex codebases. Agents have put in the time, and they already understand filesystems.

The typical approach to agent context is either stuffing everything into the prompt or using vector search. Prompt stuffing hits token limits. Vector search works for semantic similarity but returns imprecise results when you need a specific value from structured data. Filesystems offer a different tradeoff: structure your data as files, give the agent bash, and the model brings the same capabilities it uses for code navigation.

In this course, you'll build a file system agent for analyzing call transcripts. The same pattern works for legal documents, coding agents, financial analysis, or SQL generation and execution.

Why filesystems work

• Structure matches your domain. Customer records, ticket history, CRM data: these have natural hierarchies that map directly to directories. You're not flattening relationships into embeddings.
• Retrieval is precise. grep -r "pricing objection" calls/ returns exact matches. When you need one specific value, you get that value.
• Context stays minimal. The agent loads files on demand. A large transcript doesn't go into the prompt upfront. The agent reads the metadata, greps for relevant sections, then pulls only what it needs.
• Debuggability. When the agent fails, you see exactly what files it read and what commands it ran. The execution path is visible. No black box.

What you'll build

A complete filesystem-driven agent that runs in a Vercel Sandbox, explores call transcripts using bash commands, and streams responses back to a chat UI. You'll use the AI SDK for the agent loop and tools, and AI Gateway to route requests to Anthropic Claude.

Prerequisites

For this project, you'll need:

• Node.js 18+ installed
• pnpm package manager
• Vercel account
• Vercel CLI
• AI Gateway API Key

You do not need prior experience building agent frameworks.

Getting Started

This course is split into two sections. Follow the order, because each section builds on the previous one.

Section 1: Building an Agent

Set up the project, define the agent, and create a bash tool.

• Project Setup - Clone, link to Vercel, explore the starter repo
• Agent Skeleton - Define the ToolLoopAgent in lib/agent.ts
• Bash Tool - Create createBashTool with Zod schema in lib/tools.ts

By the end, you'll have an agent and a tool defined, ready to connect.

Section 2: Running in the Sandbox

Wire up the sandbox, load data, and test the working agent.

• Wire Up the Sandbox - Initialize the sandbox and connect the bash tool
• Files and Instructions - Load transcripts and add agent instructions
• Test and Extend - Test with real questions, explore extensions

By the end, you'll have a working filesystem agent that explores call transcripts using bash commands.

The Tech Stack

Let's start by setting up the project.