Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/vercel/eve/llms.txt

Use this file to discover all available pages before exploring further.

The Build an Agent tutorial constructs one application end to end: a data analytics assistant. You ask questions in natural language and, across nine steps, the assistant learns to query a warehouse, run analysis in a sandbox, remember your team’s metric definitions, and refuse to exceed a query budget without asking first. This page summarises every stage of the tutorial and the core code involved so you can orient yourself before diving in. Each stage links to its full write-up.
Complete the Quickstart first if you have not yet run eve locally. You need Node 24+, npm, and a model credential before beginning.

​
What you will build

By the end of the tutorial the project looks like this: 
analytics-assistant/
├── package.json
├── next.config.ts
├── app/
│   ├── page.tsx
│   └── _components/
│       └── agent-chat.tsx
└── agent/
    ├── agent.ts
    ├── instructions.md
    ├── tools/
    │   ├── run_sql.ts
    │   └── connect_warehouse.ts
    ├── skills/
    │   └── metric_definitions.md
    ├── channels/
    │   └── eve.ts
    └── lib/
        └── sample-db.ts
Every new capability gets its own file in a predictable location. Nothing is hidden inside a config object.

​
Tutorial stages

1
Scaffold the agent and set a persona
2
Create the project, choose a capable model, and write a standing analyst identity into agent/instructions.md. A persona shapes every reply the agent makes.
3
npx eve@latest init analytics-assistant
cd analytics-assistant
4
import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-opus-4.8",
});
5
You are a senior data analyst. You answer questions about the team's data.

- Prefer exact numbers to hand-waving. If you can compute it, compute it.
- State the assumptions behind any number you report (date range, filters, grain).
- Use the tools available to you rather than guessing. If you cannot answer from
  the data, say so plainly.
6
Run npm run dev and ask a question. The agent answers using the analyst persona even before it can see any data.
7
→ Covered in detail in the Quickstart and Introduction.
8
Understand sessions, turns, and durable steps
9
Before adding data access, it helps to know exactly what happened in Stage 1.
10
TermMeaningsessionYour whole conversation — durable, can span days.turnOne message you send and the work it triggers.stepA durable checkpoint within the turn.
11
Each turn runs as a durable workflow. Completed steps never re-run; eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects (charges, emails) idempotent, or gate them with an approval step.
12
→ See Execution Model for the full session/turn/step contract.
13
Add a SQL tool over sample data
14
Give the agent a run_sql tool. The filename becomes the tool name the model sees:
15
import { defineTool } from "eve/tools";
import { z } from "zod";
import { runReadOnlySql } from "../lib/sample-db.js";

export default defineTool({
  description:
    "Run a read-only SQL query against the analytics tables (orders, customers) " +
    "and return the columns and rows.",
  inputSchema: z.object({
    sql: z.string().describe("A single read-only SELECT statement."),
  }),
  async execute({ sql }) {
    const { columns, rows } = await runReadOnlySql(sql);
    // Bound output so a wide query can't flood the model's context.
    return { columns, rows: rows.slice(0, 500), truncated: rows.length > 500 };
  },
});
16
Restart the dev server and ask: “Which customer has spent the most, and how much?” Watch the model emit a run_sql call, receive the rows, and return a real number.
17
→ See Tools for the complete defineTool API.
18
Connect a real warehouse
19
Replace the in-memory sample data with a connection to your actual warehouse. This step introduces human-in-the-loop authorization: the agent parks the turn while you approve the sign-in in the browser, then resumes exactly where it left off.
20
→ See Connections for MCP and OpenAPI connection setup.
21
Run analysis in the sandbox
22
Add a sandboxed execution environment so the agent can run Python or shell scripts safely without touching the host filesystem.
23
→ See Sandbox for the full ctx.getSandbox() API.
24
Add a metric glossary as a skill
25
Skills are Markdown procedures the model loads on demand — they do not consume context on every turn. Write the team’s metric definitions into agent/skills/metric_definitions.md and the agent automatically applies them when a matching question arrives.
26
→ See Skills for the full skill authoring guide.
27
Add team playbooks
28
Extend the skills folder with multi-step operational playbooks that the agent follows for common data tasks.
29
→ See Skills for packaged skills with SKILL.md.
30
Guard the query budget with an approval gate
31
Use input.requested — eve’s human-in-the-loop primitive — to pause a turn and ask for explicit approval before running expensive queries. The turn waits for your yes/no, then picks up exactly where it left off.
32
→ See Tools for human-in-the-loop approval configuration.
33
Add the web UI and deploy to Vercel
34
Add the Next.js Web Chat frontend with one command, then deploy the finished assistant:
35
npx eve channels add web
npm install
36
The generated next.config.ts wraps your config with withEve, which wires the eve routes automatically:
37
import type { NextConfig } from "next";
import { withEve } from "eve/next";

const nextConfig: NextConfig = {};

export default withEve(nextConfig);
38
Deploy to Vercel:
39
vercel deploy
40
Verify the deployment by pointing the eve CLI at your live URL:
41
npx eve dev https://your-analytics-app.vercel.app
42
→ See Deployment for the full production checklist.

​
Final project structure

After all nine stages, every capability has a clear file-system home: 
analytics-assistant/
├── package.json
├── next.config.ts          ← withEve wrapper for Next.js
├── app/
│   ├── page.tsx
│   └── _components/
│       └── agent-chat.tsx  ← useEveAgent chat UI
└── agent/
    ├── agent.ts            ← model + runtime config
    ├── instructions.md     ← analyst persona and standing rules
    ├── tools/
    │   ├── run_sql.ts      ← query sample data or warehouse
    │   └── connect_warehouse.ts
    ├── skills/
    │   ├── metric_definitions.md  ← on-demand metric glossary
    │   └── team_playbooks.md
    ├── channels/
    │   └── eve.ts          ← built-in HTTP channel
    └── lib/
        └── sample-db.ts    ← in-memory SQLite stand-in (Stages 1–3)
Once eve is a dependency, the package bundles the full documentation at node_modules/eve/docs/. Coding agents (Claude Code, Cursor, and others) can read those docs locally without fetching anything external.

Tools

Complete defineTool API reference — schemas, output bounding, and authorization.

Instructions & Skills

Always-on prompts vs. on-demand Markdown procedures.

Deployment

Build, start, and ship an eve app to Vercel.

Build docs developers (and LLMs) love

Get started for freeTalk to us