---
created: 2026-08-09 13:06
modified: 2026-08-09 13:06
type: note
tags:
  - ai
  - ai-agents
  - llm
aliases: []
---
# [[AI Tool - Eve - Agent Orchestration]]


## 📌 Overview
**Eve** is an open-source, file-system-first AI agent framework developed by Vercel. Unlike traditional runtime-managed frameworks (like LangChain or CrewAI) that require complex code orchestration, Eve treats your **directory structure as the application code**. By mapping folders directly to agent topology and routing paths, it turns file layouts into isolated, multi-agent microservices.

---

## 🔥 Powers & Capabilities
* **File System Topology:** Creating a folder automatically instantiates a new agent capability. Nesting folders creates native supervisor-to-subagent routing boundaries.
* **Zero-Config Tooling:** Any TypeScript file placed inside a `tools/` directory is automatically scanned at build time. Eve generates the JSON schemas for the LLM natively without code boilerplate.
* **Durable Workflows:** Built-in support for long-running, multi-step agent actions. It can freeze execution during long processes and resume natively without state drift.
* **Local Isolation:** Can be compiled into a standard standalone Node.js (Nitro) server that stores workflow data locally on disk inside a `.workflow-data/` folder, completely independent of cloud ecosystems.
* **AI Coding Agent Friendly:** Because instructions are plain Markdown (`instructions.md`), local tools like **Hermes, Goose, or OpenClaw** can seamlessly read, modify, and scale agent rules without parsing structural code graphs.

---

## 🛠️ Local Installation & Setup (Non-Vercel Stack)

To run Eve entirely on your local machine behind a reverse proxy like **Caddy**:

### 1. Initialize Project
```bash
# Create project and install core packages locally
npm install eve@latest ai zod
```

### 2. Configure Model Runtime
Define your chosen LLM provider in `agent/agent.ts` passing your API keys via local environment variables:
```typescript
import { anthropic } from '@ai-sdk/anthropic';
import { defineAgent } from 'eve';

export default defineAgent({
  model: anthropic('claude-3-5-sonnet-latest'),
});
```

### 3. Local Execution Commands
```bash
# Start local interactive TUI development environment
npx eve dev

# Compile directory tree into standalone local server
npx eve build

# Spin up production local network process
npx eve start
```

---

## 📁 Repository Directory Structure

```text
my-agent-root/
├── .workflow-data/           # Automatically stores local session state & memory logs
├── agent/
│   ├── instructions.md       # Master Coordinator prompt / system rules
│   ├── agent.ts              # Model SDK and global config
│   │
│   ├── subagents/            # 📁 Sub-agents automatically inferred by folder names
│   │   ├── security-guard/
│   │   │   └── instructions.md
│   │   └── browser-driver/
│   │       └── instructions.md
│   │
│   └── tools/                # 📁 Automatically exposed executable utilities
│       ├── system_tool.ts
│       └── notify_tool.ts
└── package.json
```

---

## 🚀 Specialized Local Use Case: Google Takeout & Prefect Hybrid

This architecture leverages **Prefect** for robust state scheduling, data pipelines, and error mitigation, while using **Eve** as a modular, localized execution brain for volatile UI and system tasks.

### Architecture Data Flow
1. **Prefect Flow** monitors the local download directory.
2. When a file completion event triggers, Prefect issues a local HTTP `POST` to the **Eve Master Agent**.
3. **Eve Main Agent** processes the instruction and securely hands off execution to the `/browser-driver` sub-agent.
4. The sub-agent runs local TypeScript tools to interface with the web layout, clicks the next batch, and triggers a localized webhook notification.

### Implementation Blueprint

#### 1. Eve Notification Tool (`agent/tools/send_ntfy.ts`)
```typescript
import { z } from 'zod';

export const send_ntfy = {
  description: 'Sends a status notification message to a local NTFY topic endpoint.',
  parameters: z.object({
    message: z.string().describe('The notification body content.'),
  }),
  execute: async ({ message }: { message: string }) => {
    const response = await fetch('https://ntfy.sh', {
      method: 'POST',
      body: message,
    });
    return { success: response.ok, status: response.status };
  }
};
```

#### 2. Prefect Orchestrator Node (`takeout_pipeline.py`)
```python
import requests
from prefect import flow, task

@task(retries=3, retry_delay_seconds=30)
def alert_eve_engine(status_msg: str):
    """Triggers the locally hosted Eve Nitro server process"""
    url = "http://localhost:3000/eve/v1/session"
    payload = {
        "message": f"System Status: {status_msg}. Execute browser-driver sequence and alert NTFY."
    }
    response = requests.post(url, json=payload)
    return response.json()

@flow(name="Google Takeout Watcher")
def monitor_takeout_flow():
    # Local disk I/O monitoring logic checking for archive completions
    archive_ready = True 
    if archive_ready:
        alert_eve_engine("Takeout segment 1 download completed successfully.")

if __name__ == "__main__":
    monitor_takeout_flow()
```

---

## 🔍 Strategic Verdict
* **Do not use Eve** for high-load multi-tenant server infrastructure with 50+ concurrent external sessions on a single machine; use **LangGraph** with explicit database checkpointers (e.g., Postgres) to prevent memory bottlenecks.
* **Do use Eve** as a highly isolated, self-documenting automation sub-module for local tool pipelines where file-system layouts make it simple for AI coding assistants to expand functionality.

---

## ⚠️ CORRECTION (2026-08-09) — examples below are GENERIC, not our stack

The original note's "Specialized Local Use Case" section uses **wrong specifics** for our
environment. Do NOT copy them directly:

| In the note | Our reality |
|---|---|
| `https://ntfy.sh` (public) | Self-hosted **Apprise API server** at `https://apprise.lab.audasmedia.com.au/notify` (fans out to NTFY/Telegram/email) |
| Hypothetical `takeout_pipeline.py` | Real Prefect flows: `takeout-fetch`, `photo-ingest`, `photo-quality-scan`, `immich-import`, `photo-watch` (on photo-pool, .13) |
| `http://localhost:3000/eve/v1/session` | Eve not yet installed; when trialled it'd run on .13 behind Caddy (prefect/photo-filter.home.lab pattern) |
| Generic "browser-driver" | Our pipeline is deterministic + Prefect-owned; LLM layer only needed for **browser-driven Google export clicks** (Takeout has no API) |

**Assessment (2026-08-09)**: Eve (Vercel, open-source, Jun 2026, BETA) is interesting as a
*supplement* for LLM-orchestrated Google interaction — file-system agent model, durable
execution, sandboxes, local Nitro mode. **Not** a Prefect replacement. Defer adoption until:
(a) local `eve start` stable on .13, (b) clean call-back into Prefect/Apprise,
(c) a genuinely LLM-needed Google task. Track in `plan/01` + `plan/03`.