File-Based AI Agents: How Flue, Vercel Eve & Mastra Let You Build an Agent from a Folder (2026)
Discover how file-based AI agents are replacing complex code graphs. Compare how Flue, Vercel Eve, and Mastra let you build an agent from a simple folder.
If you tried to build an AI agent a year ago, you know the slog. You had to learn LangChain, then LangGraph, then how Pydantic fit into all of it. Wiring up MCP servers was a project of its own. Registering tools, loading skills, managing state — each one a task in itself before your agent did anything useful.
In just the last eight weeks, that entire stack collapsed into one instruction.
Make a folder.
Drop in an instructions.md for its personality. A tools/ folder for what it can do. A skills/ folder for what it knows. Run one command — and the folder is the agent. No graph to hand-wire. No orchestration layer. Just files you can read, edit, and version.
Three frameworks landed this idea almost simultaneously: Flue (from the Astro team), Vercel Eve, and Mastra. I think file-based AI agents are the biggest shift in how we build agents since MCP.
Check out my previous articles
What Are File-Based AI Agents?
A file-based AI agent is exactly what it sounds like: an agent defined by a folder of files instead of hand-wired code. You create a directory, drop in an instructions.md for its personality and system prompt, a tools/ folder for what it can do, and a skills/ folder for what it knows. Run one command and the folder is the agent.
There’s no graph to construct, no orchestration layer to reason about — just files you can open in any text editor and version like any other project.
A folder used to be where a project started. Now it’s where the agent lives. Make one, drop in your instructions, and watch it wake up.
The point is that everything an agent needs is now plain, portable material. Its identity, its knowledge, its capabilities all live as markdown and TypeScript on disk. You can read it, diff it, fork it, and move it between frameworks.
Three frameworks shipped this pattern in eight weeks.
The Astro team launched Flue (”The Open Agent Framework”), with 1.0 Beta on June 16, 2026.
Vercel announced Eve (”Next.js for agents”) at its Ship conference on June 17, 2026.
Mastra, an established ~24k-star framework, shipped File-Based Agents on July 3, 2026. Three independent teams, the same answer — that’s convergence.
Flue Framework: The Astro Team’s Agent Harness
Github Repo: https://github.com/withastro/flue
What it is. Flue is a TypeScript framework for durable AI agents and workflows, built around what it calls an “agent harness” — “like Claude Code, but 100% headless and programmable.” It comes from the Astro team and was announced by Astro co-founder Fred K. Schott. It went public around May 1, 2026, and hit 1.0 Beta on June 16, 2026. As of July 22 it’s Apache-2.0, ~4.4k stars, and openly flagged Experimental — APIs may change.
How the folder looks. Flue is more code-first than the others — TypeScript agents, markdown skills:
my-agent/
flue.config.ts # the only thing `flue init` scaffolds
agents/hello-world.ts # defineAgent(() => ({ model, tools, skills, ... }))
.flue/workflows/<name>.ts # run({ init, payload }) + optional Hono route
.agents/skills/<name>/SKILL.md # markdown skills (or import with { type: 'skill' })
AGENTS.md # context, discovered from cwd
channels/ # @flue/slack, etc.
How it works. Flue records everything your agent does, so if a run gets interrupted — crash, restart, whatever — it picks up right where it left off. And the same agent folder runs anywhere: Node.js, Cloudflare, GitHub Actions, or GitLab CI/CD.
Need external tools? MCP servers plug in with a single function call.
Install it. One caveat: flue init is deliberately minimal. It scaffolds only a flue.config.ts; you write the agent file yourself. It’s not a full project generator like the other two:
npm install @flue/runtime && npm install -D @flue/cli
echo 'ANTHROPIC_API_KEY="..."' > .env
npx flue init --target node # or --target cloudflare
# create agents/hello-world.ts yourself, then:
npx flue run hello-world --input '{"message":"Tell me a joke."}'
Requires Node >=22.19.0.
The repo (github.com/withastro/flue) ships runnable examples — examples/node-websocket and examples/cloudflare-websocket are the fastest way to see a live agent.
The honest knock, from Flue’s own Hacker News launch thread: no tests in packages/ yet, and it’s early (Experimental for a reason). Worth knowing before you build anything load-bearing on it.
Vercel Eve: Next.js for Agents
Github Repo: github.com/vercel/eve
What it is. Eve is Vercel’s open-source agent framework, announced June 17, 2026 at Vercel’s Ship conference in London as part of its “Agent Stack.” It’s Apache-2.0 (npm eve, github.com/vercel/eve), and as of July 22 it’s at ~3.9k stars and version 0.27.0 (a public beta).
Vercel CTO Malte Ubl’s framing is the cleanest one-liner of the bunch: it’s “Next.js for agents.” The way Next turns folders into routes, Eve turns folders into agents — discovered at build time.
How the folder looks. This is the purest expression of “agent = directory”:
agent/
agent.ts # optional: model + runtime config (defineAgent)
instructions.md # required: the always-on system prompt
tools/*.ts # defineTool + Zod schema; filename = tool name
skills/*.md # markdown w/ frontmatter, loaded on demand
subagents/<name>/ # child agents, same shape one level down
channels/*.ts # slack.ts, discord.ts...; HTTP on by default
schedules/*.ts # defineSchedule({ cron, run })
connections/*.ts # defineMcpClientConnection (MCP or OpenAPI)
A minimal agent is two files: instructions.md plus an optional agent.ts.
How it works. Your agent survives crashes and redeploys — Eve saves its progress automatically. Each agent gets its own sandbox to run code safely, and if you want a human to approve an action before it happens, that’s one flag on a tool. Out of the box it connects to Slack, GitHub, Snowflake, Salesforce, Notion, and Linear. Vercel says it runs 100+ agents internally, including one resolving 92% of support tickets (their numbers, not independently confirmed).
Install it. Unlike Flue, Eve gives you a full scaffold — directory, dependencies, git init, and a terminal UI, all in one command:
npx eve@latest init my-agent # scaffolds dir, installs deps, git init, launches TUI
npm run dev # or: npx eve@latest init . for an existing project
Deploy with vercel deploy. There are polished official templates from vercel-labs worth cloning directly:
# Slack bot: one tool + one skill, Vercel Connect creds
git clone https://github.com/vercel-labs/eve-slack-agent-template
# Durable personal agent: web chat, Slack, Linear, long-term memory
git clone https://github.com/vercel-labs/personal-agent-template
There’s also eve-chat-template and eve-content-agent-template. The fair criticism: this is Vercel-native. The code is Apache-2.0, but the durable runtime, sandbox, and gateway are most seamless on Vercel — the launch post says other platforms are “on the way.” I dug into exactly this playbook in Vercel’s Open-Source Empire: give away the framework, monetize the hosting underneath.
Check out more about Vercel’s Open-Source Empire in this article.
Vercel's Open-Source Empire: How 62 Projects Turn Developer Adoption Into Platform Revenue
Vercel is shipping production-grade AI infrastructure at a pace most companies reserve for their core products—and doing it in public. Across two GitHubs, 558 repositories the company is building an entire stack for AI agents while keeping the frameworks millions of developers rely on stable and boring.
Mastra File-Based Agents: A 24k-Star Framework Converts
Github Repo: https://github.com/mastra-ai/mastra
What it is. This is the one that convinced me the shift is real. Mastra is a YC-backed, open-source TypeScript agent framework with roughly 24k GitHub stars — a mature, code-first project.
On July 3, 2026, in @mastra/core@1.48.0, it shipped File-Based Agents (announced by Paul Scanlon). When a framework that big adopts the folder convention on top of its existing code API, that’s not a startup chasing a trend — that’s convergence.
How the folder looks. Each agent is a directory under src/mastra/agents/:
src/mastra/agents/<name>/
config.ts # model config
instructions.md # the prompt
memory.ts
workspace/ # seed files
tools/*.ts
skills/ # plain .md, .ts, OR SKILL.md packages with references/
subagents/ # recursive, up to 3 levels deep
How it works. The killer detail is the skills/ folder: it accepts Anthropic’s SKILL.md format directly — write a skill once, and it works in Claude and in Mastra. File-based agents also work side by side with Mastra’s existing code-defined agents, so teams can switch over gradually instead of rewriting everything. Run mastra dev and your agent folders are picked up automatically.
Install it. Mastra’s CLI is a proper project generator — it scaffolds a working example agent for you:
npm create mastra@latest # interactive; scaffolds src/mastra with an example agent
npm create mastra@latest my-app -- --default
npx mastra dev # file-based agents are discovered here
One licensing nuance to flag: the Mastra core is Apache-2.0, but the ee/ directory sits under a separate Mastra Enterprise License. The file-based agent feature itself is in the Apache-2.0 core, still marked beta and only a few weeks old. Templates live at mastra.ai/docs/getting-started/templates — start there rather than digging through the monorepo.
Flue vs Eve vs Mastra: Quick Comparison
All Three Are Open Source (Apache-2.0)
Here’s what makes me optimistic about this wave: all three are Apache-2.0. Flue, Eve, and Mastra’s core are all on GitHub under a permissive license — read every line, fork it, self-host.
Mastra draws the one line worth knowing (its ee/ directory is under a separate enterprise license), but the file-based agent feature lives in the open core. And the conventions are open too: AGENTS.md and MCP now live at the Linux Foundation’s Agentic AI Foundation, and SKILL.md is Anthropic’s open spec. That’s why Mastra can accept a Claude skill unchanged, and why an AGENTS.md you wrote for OpenClaw or Codex or any platform isn’t wasted when you move to Flue.
> Your agent folder is portable in a way your agent graph never was.
Final Verdict: Who Should Use What
Non-coders and indie builders — this is your entry point. If you can write a clear markdown file, you can define an agent. It’s the same promise Claude Skills made, now extended to full deployable agents.
TypeScript and web developers — Eve if you live on Vercel and want the most polished DX, Flue if you want to deploy anywhere, Mastra if you want a mature ecosystem and drop-in Claude-skill compatibility.
Python teams on LangGraph or PydanticAI — you’re not stranded. Pydantic AI V2 shows the ideas flowing your way. Start moving your prompts and skills into files now; that’s becoming the portable layer regardless of which engine runs underneath.
For two years the question was “which agent framework should I learn?” The answer arriving now is simpler and a lot more durable:
> Learn to write good files. The frameworks will meet you there.
A folder of markdown really is the whole thing now, which still feels wrong to people who learned the graph frameworks. I run a public skill pack that way, no orchestration layer, just files I edit by hand. What the file-based approach gives up is enforcement: nothing stops a skill from being vague, so the discipline moves from the framework into the writing.