168 lines
7.0 KiB
Markdown
168 lines
7.0 KiB
Markdown
---
|
|
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`.
|