--- title: "Building Filesystem Agents" description: "Build a filesystem agent that uses bash tools and Vercel Sandbox to explore call transcripts and answer questions." canonical_url: "https://vercel.com/academy/filesystem-agents" md_url: "https://vercel.com/academy/filesystem-agents.md" docset_id: "vercel-academy" doc_version: "1.0" last_updated: "2026-04-11T08:19:05.295Z" content_type: "course" lessons: 6 estimated_time: lesson_urls: - "https://vercel.com/academy/filesystem-agents/filesystem-project-setup.md" - "https://vercel.com/academy/filesystem-agents/agent-skeleton.md" - "https://vercel.com/academy/filesystem-agents/bash-tool.md" - "https://vercel.com/academy/filesystem-agents/wire-up-sandbox.md" - "https://vercel.com/academy/filesystem-agents/files-and-instructions.md" - "https://vercel.com/academy/filesystem-agents/test-and-extend.md" --- Vercel Academy โ€” structured learning, not reference docs. Lessons are sequenced. Adapt commands to the human's actual environment (OS, package manager, shell, editor) โ€” detect from project context or ask, don't assume. The lesson shows one path; if the human's project diverges, adapt concepts to their setup. Preserve the learning goal over literal steps. Quizzes are pedagogical โ€” engage, don't spoil. Quiz answers are included for your reference. # 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 filesystem 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](https://vercel.com/docs/functions/sandbox), explores call transcripts using bash commands, and streams responses back to a chat UI. You'll use the [AI SDK](https://sdk.vercel.ai) for the agent loop and tools, and [AI Gateway](https://vercel.com/ai-gateway) to route requests to Anthropic Claude. ## Prerequisites For this project, you'll need: - [Node.js](https://nodejs.org/) 18+ installed - [pnpm](https://pnpm.io/) package manager - Vercel account - [Vercel CLI](https://vercel.com/docs/cli) - [AI Gateway API Key](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway%2Fapi-keys\&title=AI+Gateway+API+Keys) 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](https://vercel.com/academy/filesystem-agents/filesystem-project-setup) - Clone, link to Vercel, explore the starter repo - [Agent Skeleton](https://vercel.com/academy/filesystem-agents/agent-skeleton) - Define the ToolLoopAgent in `lib/agent.ts` - [Bash Tool](https://vercel.com/academy/filesystem-agents/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](https://vercel.com/academy/filesystem-agents/wire-up-sandbox) - Initialize the sandbox and connect the bash tool - [Files and Instructions](https://vercel.com/academy/filesystem-agents/files-and-instructions) - Load transcripts and add agent instructions - [Test and Extend](https://vercel.com/academy/filesystem-agents/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 | Component | Purpose | | ----------------------------------------------------------- | ----------------------------------- | | [Vercel Sandbox](https://vercel.com/docs/functions/sandbox) | Isolated bash execution environment | | [AI SDK](https://sdk.vercel.ai) | `ToolLoopAgent`, `tool`, streaming | | [AI Gateway](https://vercel.com/ai-gateway) | Routes requests to Anthropic Claude | | [Zod](https://zod.dev) | Tool input schema validation | Let's start by setting up the project. --- [Full course index](/academy/llms.txt) ยท [Sitemap](/academy/sitemap.md)