Project Setup

You're building a file system agent for analyzing call transcripts. This pattern could be extended to analyzing legal documents, coding agents, financial analysis, or SQL generation and execution.

For this project you'll use:

Vercel Sandbox - Secure, isolated environment for running untrusted code (bash commands)
AI SDK - Unified API for building AI applications with streaming, tools, and agents
AI Gateway - Routes requests to AI providers with automatic fallbacks, caching, and rate limiting

Outcome

You have a linked Vercel project with environment variables pulled locally, and you understand which files are pre-built and which you'll create.

Hands-on Exercise 1.1

Set up the starter project and verify you have everything you need to start building the agent.

Requirements:

Deploy the starter with the Deploy with Vercel button, then clone your fork and run pnpm install
Link your local clone to the Vercel project with vc link
Pull environment variables with vc env pull
Add your AI Gateway API key to .env.local

Prerequisites:

For this project, you'll need:

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

Deploy to Vercel

Click the button below to fork the starter and deploy it to Vercel:

This will:

Fork the repository to your GitHub account
Create a Vercel project linked to your fork
Deploy to production with a working landing page

Link your local repo to the Vercel project you just created:

vc link

Select your team and choose Link to existing project, then pick filesystem-agent.

Pull the automatically created environment variables to use locally. This handles OIDC token authentication automatically in your project.

vc env pull

You can now inspect the OIDC token in .env.local in your project.

Add your AI Gateway API Key to .env.local:

AI_GATEWAY_API_KEY=your_ai_gateway_api_key

Repository Overview

The starter repo comes with all necessary files pre-created.

Existing files:

app/form.tsx - A component that accepts a user query and sends to an API route, then renders the stream as it's returned
app/api/route.ts - A route handler that calls the agent and streams back to the UI
lib/calls/ - A directory with pre-loaded dummy call transcripts

Files you will edit in this course:

lib/agent.ts - Where you will define the agent
lib/tools.ts - Where you will define the bash tool for the agent to use

app/
├── page.tsx           # Renders the Form component
├── form.tsx           # Chat input, streams responses from /api
├── api/route.ts       # POST handler that calls agent.stream()
├── layout.tsx         # Root layout
└── globals.css        # Tailwind styles

lib/
├── calls/             # Demo call transcripts (3 files)
│   ├── 1.md
│   ├── 2.md
│   └── 3.md
├── agent.ts           # Empty — you build this
└── tools.ts           # Empty — you build this

The API route already imports from lib/agent.ts, so once you build the agent, the UI will work automatically.

Try It

Verify the link worked:
```
cat .env.local
```
You should see VERCEL_OIDC_TOKEN (or similar sandbox auth variables) and your AI_GATEWAY_API_KEY.
Check the demo data:
```
ls lib/calls/
```
```
1.md  2.md  3.md
```
Peek at a transcript:
```
head -10 lib/calls/1.md
```
You should see call metadata: ID, title, participants, and timestamps.

Don't start the dev server yet

The app won't compile until lib/agent.ts exports an agent. You'll create that in the next lesson.

Commit

git add -A
git commit -m "feat(setup): link project and pull env vars"

Done-When

vc link completed successfully and .vercel/ directory exists
.env.local contains OIDC auth variables and your AI Gateway API key
You can list the three call transcript files in lib/calls/
You understand which files are pre-built and which you'll create