sam-4screen-desktop 2026-8-10:15:1:41
This commit is contained in:
167
300 areas/350 AI/AI Tool - Eve - Agent Orchestration.md
Normal file
167
300 areas/350 AI/AI Tool - Eve - Agent Orchestration.md
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
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`.
|
||||
Reference in New Issue
Block a user