sam/obsidian-vault

Fork 0

Files

Sam Rolfe f3cf3fb012 sam-4screen-desktop 2026-8-10:15:1:41

2026-08-10 15:01:42 +10:00

7.0 KiB

Raw Blame History

created, modified, type, tags, aliases

created

modified

type

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

# 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:

import { anthropic } from '@ai-sdk/anthropic';
import { defineAgent } from 'eve';

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

3. Local Execution Commands

# 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

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

Prefect Flow monitors the local download directory.
When a file completion event triggers, Prefect issues a local HTTP POST to the Eve Master Agent.
Eve Main Agent processes the instruction and securely hands off execution to the /browser-driver sub-agent.
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`)

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`)

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.

7.0 KiB Raw Blame History