EveStudioDocs

Instructions & model

Two files decide how an agent thinks: instructions.md, the always-on system prompt, and agent.ts, the model and runtime config. Studio's Instructions tab has two sub-tabs: Prompt edits the first, and Model edits the second. This page covers both, and how Studio warns you when the agent can't run.

If you're new to the folder layout, read The agent, explained first.

Instructions: the system prompt

agent/instructions.md is the agent's permanent identity: its persona, tone, and standing rules. Eve prepends this markdown to every model call in a session, so whatever you write here holds on every turn.

You are a concise assistant. Use tools when they are available.

Keep it to stable behavior: identity, tone, and rules that should always apply. It is the counterpart to skills, which load situational procedures on demand. Anything long or only-sometimes-relevant belongs in a skill, not in instructions, so it doesn't bloat every turn. Instructions never run code; when you need typed executable behavior, reach for a tool.

Edit instructions in Studio

Open the agent and go to Instructions → Prompt. It's a markdown editor over agent/instructions.md:

  1. Edit the prompt.
  2. Save to write the file.
  3. Changes take effect on the next turn: locally as soon as the dev server rebuilds, and in production after you deploy. A durable session keeps its history but adopts the new instructions on its next turn.

Because Studio edits the file directly, anything you change here is exactly what Eve serves. There is no separate copy. A mounted extension can contribute its own instruction fragment (Arcana ships its memory instructions this way); those live in the package and combine with yours at build time.

Dynamic instructions (advanced)

For most agents a static markdown file is all you need. Eve also supports building the prompt from code when you need typed helpers or build-time values: author agent/instructions.ts instead of agent/instructions.md (the two can't coexist at the root), export defineInstructions({ markdown }), and Eve captures the resolved text at build time. To resolve the prompt per session (by tenant, channel, or authenticated user) wrap it in a defineDynamic resolver. You can also split a long prompt across an agent/instructions/ directory, whose entries combine in alphabetical order. See the Eve docs for the dynamic-capabilities API.

Model: agent.ts

agent/agent.ts calls defineAgent to select the model and configure the runtime:

import { defineAgent } from "eve";

export default defineAgent({
  model: "openai/gpt-5.6-luna-fast",
});

The model string routes through the Vercel AI Gateway. If agent.ts is omitted entirely, Eve uses its default source configured with openai/gpt-5.6-luna-fast; when the file is present, model is required. To call a provider directly instead of through the gateway, install that provider's AI SDK package and pass a LanguageModel:

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

export default defineAgent({
  model: anthropic("claude-opus-4-8"),
});

Note the id format differs: the gateway uses a dot (anthropic/claude-opus-4.8), a direct provider id uses hyphens (claude-opus-4-8).

Reasoning effort

Add reasoning to control how hard the model thinks, using Eve's provider-agnostic option:

export default defineAgent({
  model: "openai/gpt-5.6-sol",
  reasoning: "high",
});

Supported values are "provider-default", "none", "minimal", "low", "medium", "high", and "xhigh". The selected model and provider determine which levels are actually available and how they map to native settings. provider-default leaves the field unauthored.

Other runtime config

defineAgent also takes optional fields you may see in agent.ts:

  • compaction: Eve summarizes older turns as a session approaches the context window (on by default at thresholdPercent: 0.9). Lower the threshold to compact sooner.
  • limits: framework-owned caps like maxInputTokensPerSession and maxOutputTokensPerSession.
  • modelOptions: provider-specific option overrides.

These are all optional; a working agent.ts can be just a model.

Edit the model in Studio

Open Instructions → Model. Studio reads agent/agent.ts and shows the configured model. Type any provider/model id, pick one of the favorite chips, or Browse all the live AI Gateway catalog, fetched from the gateway with the agent's own credential and searchable by name or id (each row shows its context window). Set the Reasoning effort (provider-default, none, minimal, low, medium, high, xhigh) and Save. Studio writes the change with Eve's own editor:

eve set --model openai/gpt-5.6-sol --reasoning high

eve set uses the same model-id validation and source editor as /model in the Eve TUI, so the file stays well-formed; provider-default removes an authored reasoning field. If eve set fails, Studio falls back to editing the string literals in agent.ts itself. Two cases are shown read-only with a note: an agent with no agent.ts (Eve defaults the model to openai/gpt-5.6-luna-fast; create the file to set it), and a model that isn't a plain gateway string (defineDynamic, an environment expression, or a provider SDK call), which you edit in agent.ts by hand.

When the agent can't run locally

The model runs through the Vercel AI Gateway, so the agent needs a credential to make any model call: either a VERCEL_OIDC_TOKEN (pulled by linking the project to Vercel) or an AI_GATEWAY_API_KEY. A direct-provider model instead needs that provider's key (e.g. ANTHROPIC_API_KEY).

Studio shows the configured model and warns when it can't run without a credential. In the Chat tab this appears as a Not connected to Vercel banner: Studio walks you through signing in, picking a team, and linking the project so the token lands in your environment and the model can respond. The full flow is in Connect to Vercel.

Where to go next