Creating a File-System Based Agentic Workflow with Eve.dev

If you've ever built a complex AI agent, you know the pain of "Prompt Spaghetti." Your system prompt grows to 5,000 words. Your tool definitions become a massive, unreadable tools.ts file. Adding new capabilities feels fragile.

Eve.dev (often called the "Next.js for AI Agents") introduces a brilliant solution: Filesystem-first architecture.

Instead of configuring your agent in a massive JavaScript object, you configure it using folders and files. In this tutorial, we will explore how to architect a highly modular agentic workflow using Eve.dev.

The Problem: Monolithic Configurations

Typically, configuring an agent looks like this:

// The old, messy way
const myAgent = {
  systemPrompt: "You are a coding assistant. Here are 500 lines of rules...",
  tools: [ toolA, toolB, toolC, toolD ],
  models: { },
  // ... endless configuration
}

This doesn't scale when a team is trying to collaborate on different agent skills.

The Eve.dev Solution: Directory Structure

Eve.dev maps folders to agent capabilities. Let's create an Eve.dev workspace for a "DevOps Agent" that can review code, deploy servers, and check logs.

Here is what our directory structure will look like:

/eve
  /agents
    /devops
      instructions.md     <- The core system prompt
      /tools
        deploy.ts         <- Executable TypeScript tool
        check_logs.ts
      /skills
        aws_cli/
          README.md       <- Documentation the agent can read
          commands.sh     <- Shell scripts the agent can execute

Step 1: The Core Instructions (Markdown)

Eve.dev leverages Markdown for prompts. This is far superior to template strings in JavaScript because it allows proper formatting and syntax highlighting.

Create /eve/agents/devops/instructions.md:

# DevOps Agent

You are an expert DevOps engineer responsible for managing infrastructure.

## Core Responsibilities
- Monitor server health
- Deploy new application versions
- Investigate downtime incidents

## Workflow
When asked to investigate an incident:
1. Always check the logs first using `check_logs`.
2. Do not mutate state or restart servers without explicit permission.

Eve.dev automatically loads this file and uses it as the foundational system prompt for the devops agent.

Step 2: Defining Modular Tools

Instead of one massive array of tools, Eve.dev lets you isolate each tool in its own file within the /tools directory.

Create /eve/agents/devops/tools/check_logs.ts:

import { tool } from '@eve/core';
import { z } from 'zod';

export default tool({
  name: 'check_logs',
  description: 'Retrieve recent server logs for a specific service.',
  schema: z.object({
    serviceName: z.string(),
    lines: z.number().default(100)
  }),
  execute: async ({ serviceName, lines }) => {
    // Fetch logs from Datadog or AWS CloudWatch
    return `[INFO] ${serviceName} started successfully...`;
  }
});

Because this file is in the /tools folder, Eve.dev automatically binds it to the DevOps agent. You can add 50 tools simply by adding 50 files.

Step 3: Giving the Agent "Skills"

Sometimes, an agent needs complex knowledge or scripts that shouldn't be crammed into the main prompt. Eve.dev uses a /skills directory for this.

Create /eve/agents/devops/skills/aws_cli/README.md:

# AWS CLI Skill

When you need to interact with AWS, use this skill. 
We use a specific profile named `production-deployer`.
Always append `--profile production-deployer --region us-east-1` to your commands.

Eve.dev uses RAG (Retrieval-Augmented Generation) or context-window injection to dynamically provide these skills to the agent only when it determines they are relevant to the user's request.

Step 4: Initializing the Workspace

To run this beautifully organized agent, you simply point the Eve.dev core to your workspace directory.

import { Eve } from '@eve/core';

// Initialize Eve, pointing it to our filesystem
const eve = new Eve({
  workspace: './eve'
});

async function runInvestigator() {
  // Eve automatically resolves 'devops' to the /agents/devops folder
  const agent = await eve.getAgent('devops');
  
  const response = await agent.run({
    input: "The payment service is returning 500 errors, can you look into it?"
  });
  
  console.log(response.text);
}

Conclusion

By adopting a filesystem-first approach, Eve.dev brings the organizational elegance of modern web frameworks (like Next.js app routing) to AI agent development. Your prompts live in Markdown, your tools live in isolated TypeScript files, and your agent's capabilities can scale infinitely without turning into a monolithic mess.

Frequently Asked Questions (FAQ)

What is a filesystem-first architecture for AI? It means configuring AI agents by organizing files in specific directories (e.g., placing a Markdown file for prompts in a folder, and TypeScript files for tools in a tools/ subfolder) rather than writing a single massive configuration object in code.

Why use Markdown for agent prompts in Eve.dev? Markdown is easily readable, allows for clear hierarchical structuring (headers, lists), and can be managed effectively in version control. It separates the agent's logic (TypeScript) from its personality and instructions (Markdown).

How does Eve.dev handle dynamic skills? Eve.dev can store domain-specific knowledge in a /skills directory and dynamically load them into the agent's context window only when the user's task requires that specific knowledge, keeping the core prompt lean and efficient.