Build Your First AI Agent with Eve: A 10-Minute Tutorial

👋 Tutorial: Build Your First Eve Agent in 10 Minutes

I'm going to walk you through creating a weather assistant agent with Eve. The whole thing takes about 10 minutes — no Docker, no databases, no YAML. Just TypeScript and markdown.

Step 1: Initialize Your Project

First, make sure you have Node.js 18+ installed. Then run:

npx eve@latest init my-weather-agent

This scaffolds a new project in ./my-weather-agent. It installs dependencies, initializes git, and starts an interactive terminal UI.

⚠️ Quick note: The first time I ran this, I spent 5 minutes wondering why nothing happened — turns out I wasn't in the project directory. Make sure you cd my-weather-agent before running npm run dev.

Step 2: Write the Instructions

Open agent/instructions.md. This is your agent's permanent system prompt — it defines personality, rules, and behavior. Replace the default content with:

You are a helpful weather assistant. You can check the weather for any city.

Rules:
- Always greet the user warmly
- Keep responses concise (2-3 sentences max)
- If the weather data is mocked, clearly say so
- Suggest activities based on the weather

This is just markdown — easy to read, easy to edit, easy to git-track.

Step 3: Create a Tool

Create agent/tools/get_weather.ts with:

import { defineTool } from "eve/tools";
import { z } from "zod";

export default defineTool({
  description: "Get current weather for a city",
  inputSchema: z.object({
    city: z.string().min(1, "City name is required"),
    units: z.enum(["metric", "imperial"]).default("metric"),
  }),
  async execute({ city, units }) {
    // In production, call a real weather API here
    const temp = units === "metric" ? 22 : 72;
    return {
      city,
      condition: "Sunny",
      temperature: temp,
      units,
      humidity: 45,
      wind: "12 km/h",
    };
  },
});

What's happening here? The defineTool function wraps your tool with type safety. The inputSchema tells the LLM exactly what parameters it can use and their types. The execute function is what actually runs when the model decides to call this tool.

Pro tip: I initially forgot to add the units parameter with a default. The LLM kept asking "metric or imperial?" which was annoying. Adding the default made the agent much smoother.

Step 4: Configure the Model

Open agent/agent.ts and set your preferred model:

import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-5",
});

Eve supports all major providers through a unified naming convention: openai/gpt-4o, anthropic/claude-sonnet-5, google/gemini-2.5-pro, groq/llama-4, and more. No provider SDKs to install separately.

Step 5: Run Your Agent

npm run dev

This starts the interactive terminal UI. You should see a prompt. Try:

What's the weather in Tokyo?

If everything works, your agent should call the get_weather tool with city="Tokyo" and return a sunny 22°C response.

If it doesn't work: Check that your AGENT_API_KEY environment variable is set for your chosen provider. For Anthropic Claude, it's ANTHROPIC_API_KEY. For OpenAI, it's OPENAI_API_KEY. Stuck? Run npx eve@latest doctor — it diagnoses common issues.

📡 Bonus: Add an HTTP Channel

Want your agent accessible via API? Create agent/channels/http.ts:

import { defineChannel } from "eve/channels";

export default defineChannel({
  type: "http",
  path: "/weather",
  methods: ["POST"],
});

Now curl your agent:

curl -X POST http://localhost:8080/weather \
  -H "Content-Type: application/json" \
  -d '{"message": "How is the weather in Berlin?"}'

⚡ Performance Notes

From my testing:

🎯 Summary

In 10 minutes, you built a working AI agent with custom tools, a personality defined in markdown, and an HTTP API endpoint. No Docker, no databases, no cloud services. That's the power of Eve's filesystem-first approach.

The best part? Your entire agent is just files. Check it into git, deploy it with Vercel, or share it with your team. It's software — and that's exactly the point.