vercel__eve/docs/agent-config.md

title, description

title	description
agent.ts	Set the agent's runtime config in agent.ts with defineAgent, including the model and compaction.

An agent's agent.ts calls defineAgent (from eve) to set its runtime config.

Set the model

A typical config selects a model:

import { defineAgent } from "eve";

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

The root agent.ts can be omitted when no runtime config is needed. In that case, Eve defaults to anthropic/claude-sonnet-4.6. When agent.ts is present, model is required.

model accepts a gateway model id string, which routes through the Vercel AI Gateway. To call a provider directly and configure the model in code, pass a provider-authored LanguageModel:

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

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

Compaction

Compaction summarizes older turns as you approach the context window. It's on by default, so you only tune when it kicks in. Lower thresholdPercent to compact sooner:

export default defineAgent({
  model: "anthropic/claude-opus-4.8",
  compaction: {
    thresholdPercent: 0.75, // default 0.9
  },
});

See Default harness for how the loop applies it.

Other defineAgent fields

defineAgent takes a few more fields, all optional. For the exported types, see the TypeScript API.

Field	Type	Default	Description
modelOptions	AgentModelOptionsDefinition	none	Provider option overrides forwarded to the model call.
experimental	{ codeMode?: boolean }	flags unset	Opt-in flags that can change or disappear in any release. Treat them as unstable. codeMode routes executable tools through a sandboxed code-execution wrapper, where the model writes JavaScript that calls the tools inside the sandbox.
outputSchema	Standard Schema or a JSON Schema object	none	Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema.
build	{ externalDependencies?: string[] }	none	Hosted-build packaging controls. externalDependencies keeps listed packages external while Eve compiles authored modules such as tools and channels, and traces those packages into the hosted output.

Where adjacent settings live

Concern	Lives in
Instructions prompt	agent/instructions.md, Instructions
Per-tool approval (HITL)	agent/tools/*.ts, Tools
Inbound auth & network policy	the channel layer, Auth & route protection
Sandbox / workspace	agent/sandbox/, Sandbox
Telemetry & debugging	agent/instrumentation.ts, Instrumentation

What to read next

• Default harness for the loop and built-in tools this config drives
• TypeScript API for every defineAgent field and type
• Subagents for the description requirement and child-agent config