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.

eve is a filesystem-first framework for durable agents. You write capabilities under agent/, and eve runs the model loop, persists every session, and serves the agent over HTTP and platform channels. This guide walks you from zero to a working, tool-calling agent that you can talk to through the terminal UI and query over HTTP.
1
Prerequisites
2
Make sure you have:
3
  • Node 24 or newer — eve pins engines.node to the lowest major the release supports.
  • npm — bundled with Node.
    • 4
    You also need a model credential. The scaffold’s default model is anthropic/claude-sonnet-4.6, routed through the Vercel AI Gateway. Set one of the following before you run the agent:
    5
    Vercel AI Gateway
    export AI_GATEWAY_API_KEY="<your-key>"
# or, if you have Vercel CLI linked:
# vercel link   # sets VERCEL_OIDC_TOKEN automatically
    Direct Anthropic
    export ANTHROPIC_API_KEY="<your-key>"
# also update agent/agent.ts to use the @ai-sdk/anthropic package
    6
    If you skip the credential, the dev TUI flags the missing key and its /model command walks you through pasting a key or linking a project.
    7
    Scaffold the project
    8
    npx runs eve init without installing eve globally:
    9
    npx eve@latest init my-agent
cd my-agent
    10
    The command:
    11
  • Creates a my-agent/ directory using the current package manager.
  • Installs eve, ai, and zod as dependencies.
  • Initialises Git.
  • Starts the development server and opens the interactive terminal UI (TUI).
    • 12
    Stop the server with Ctrl+C before making the edits below. The command does not create a Vercel project or deploy.
    13
    Pass --channel-web-nextjs to also scaffold a Next.js Web Chat application. Every app ships the built-in HTTP channel (agent/channels/eve.ts) regardless of which flags you use.
    14
    Customise the system prompt
    15
    agent/instructions.md is the always-on system prompt. Replace the starter text with something specific to your agent’s identity:
    16
    You are a concise weather demo assistant. Tell users that the weather data is mocked.

- Answer only weather-related questions.
- Always call get_weather before giving a forecast.
    17
    Instructions are identity and standing rules. On-demand procedures belong in skills, and actions belong in tools.
    18
    Add a tool
    19
    The filename becomes the tool name the model sees and must be snake_case ASCII. Create agent/tools/get_weather.ts:
    20
    import { defineTool } from "eve/tools";
import { z } from "zod";

// The model sees this tool as `get_weather`, from the filename.
export default defineTool({
  description: "Get the current weather for a city.",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "Sunny", temperatureF: 72 };
  },
});
    21
    Tools run in your app runtime with full process.env, not inside a sandbox. The inputSchema both validates the call and types the input you receive inside execute.
    22
    Confirm the model config
    23
    agent/agent.ts holds the model and runtime config. The scaffold writes a sensible default — review it and change the model if needed:
    24
    import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-4.6",
});
    25
    Run the agent
    26
    Start the local development server:
    27
    npm run dev
    28
    The dev TUI opens. Type a message and watch the model loop play out in order:
    29
    > What is the weather in Brooklyn?
    30
    You should see:
    31
  • The get_weather tool call with { city: "Brooklyn" }.
  • The tool result { city: "Brooklyn", condition: "Sunny", temperatureF: 72 }.
  • The model’s final reply.
    • 32
    Send a message over HTTP
    33
    Every eve app exposes a stable HTTP API. While npm run dev is running, start a durable session:
    34
    curl -X POST http://127.0.0.1:3000/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"What is the weather in Brooklyn?"}'
    35
    The response includes:
    36
  • A continuationToken in the JSON body — reuse it to resume the conversation.
  • An x-eve-session-id header — use it to attach to the stream.
    • 37
    Stream the session
    38
    Attach to the session event stream using the sessionId from the previous step:
    39
    curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream
    40
    The stream is NDJSON (application/x-ndjson; charset=utf-8). For this run you will see:
    41
    EventDescriptionsession.startedThe session began.actions.requestedThe model called get_weather.action.resultTool returned weather data.message.completedThe model’s final reply.session.completedSession finished.
    42
    reasoning.appended and message.appended are optional live-streaming events. Clients that cannot surface incremental output can ignore them and rely on reasoning.completed and message.completed.
    43
    Send a follow-up message
    44
    When the session is waiting for the next user message, post a follow-up using the continuationToken:
    45
    curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
  -H 'content-type: application/json' \
  -d '{"continuationToken":"<token>","message":"Now do Queens."}'
    46
    The agent resumes the same durable session with full conversation history intact.

    Tools

    Full defineTool API: output bounding, authorization, and the toModelOutput hook.

    Instructions

    Shape behaviour with the always-on system prompt and on-demand skills.

    Channels

    Connect the agent to Slack, Discord, or a custom web UI.

    Sessions & Streaming

    The full event contract, continuation tokens, and durable state.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us