The Open Framework for Building Agents
title: "Agent Configuration" description: "Configure an eve agent's model, reasoning effort, compaction, limits, and runtime behavior in agent.ts."
An eve app's root agent uses files under agent/ by default; a flat layout places them directly in the app root instead. Its optional agent.ts calls defineAgent (from eve) when you need to configure the model or other runtime behavior. Declared subagents have their own agent.ts and capabilities; this page covers the configuration shared by root agents and subagents.
Set the model
A typical config selects a model:
import { defineAgent } from "eve";
export default defineAgent({
model: "anthropic/claude-opus-5.5",
});
For a static AI Gateway model ID, you can make the same source change from the
project root with eve set model anthropic/claude-opus-5.5 or from the local
dev TUI with /model anthropic/claude-opus-5.5.
The root agent.ts can be omitted when no runtime config is needed. eve then selects its default agent.ts source at the same slot, configured with openai/gpt-6-luna-fast and reasoning: "high"; authoring the file replaces that source.
When agent.ts is present, model is required.
A config that selects a static Gateway model is compile-only. A config that contains a dynamic model or a direct-provider LanguageModel remains a runtime entry because eve must resolve that authored value while the agent runs. See Authored module lifecycle.
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.
Use eve's helpers for direct OpenAI or Anthropic access without installing another provider package:
import { defineAgent } from "eve";
import { anthropic } from "eve/models/anthropic";
export default defineAgent({
model: anthropic(), // claude-sonnet-5
});
openai() from eve/models/openai defaults to gpt-6-luna-fast. Both helpers accept an optional native provider model ID and use OPENAI_API_KEY or ANTHROPIC_API_KEY. During local development they can also use credentials saved through /login. Deployments require their API key in the server environment.
For a local ChatGPT subscription, use chatgpt() from eve/models/openai and sign in with /login. It defaults to gpt-6-luna-fast and cannot run in a deployment.
/login can switch a static Gateway string to an eve helper and manage its import. /model changes the selected model and settings immediately. Custom provider SDK calls and dynamic expressions retain their authored behavior and require manual source edits. You can still install an AI SDK provider package and pass its LanguageModel when you need provider-specific configuration.
Model use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. Review the AI Gateway model catalog for gateway-routed models, and review the provider's terms when you configure a direct LanguageModel.
For every OpenAI or Anthropic model call, eve fills the provider's end-user
safety identifier from the active turn's
auth.current
principal when you have not configured it. For OpenAI, the option is
providerOptions.openai.safetyIdentifier; for Anthropic, it is
providerOptions.anthropic.metadata.userId. The default value is a SHA-256
fingerprint of the principal's authenticator, issuer, type, id, and subject;
eve does not send the raw principal fields or attributes. The fingerprint
follows the current caller when a later turn changes users. An authored value
at either provider path takes precedence and is forwarded unchanged. When
auth.current is null, eve does not add an identifier. The same rules apply
to compaction calls.
For AI Gateway model calls, eve sets providerOptions.gateway.sessionId to the
gen_ai.conversation.id used by Agent Runs. By default, all turns in a
conversation, including delegated subagents and compaction calls routed through
Gateway, share that ID so their Gateway generations can be found together.
Direct-provider calls do not receive the option. An authored gateway.sessionId
takes precedence; AI Gateway hashes IDs longer than 256 characters.
AI Gateway also uses this ID for
session affinity,
which tries the provider that served the session's previous call first, among
the providers your routing settings allow, so that provider can read the prompt
from its cache. The conversation
appears as one session in the AI Gateway logs Sessions view. Affinity can move
the pinned provider ahead of your order. To keep order exactly, set
sessionAffinity: false:
import { defineAgent } from "eve";
export default defineAgent({
model: "anthropic/claude-opus-5.5",
modelOptions: {
providerOptions: {
gateway: { order: ["bedrock", "anthropic"], sessionAffinity: false },
},
},
});
For direct OpenAI and chatgpt() model calls, eve sets
providerOptions.openai.promptCacheKey to a SHA-256 hash of the session ID,
which helps OpenAI route a session's calls to the cache that holds its prompt
prefix. Each subagent session gets its own key. An authored
openai.promptCacheKey takes precedence. chatgpt() calls also send the key
in the session-id header, which the Codex backend uses for cache routing.
Gateway-routed calls do not receive the option.
Use a local model
To test against a model running on your own machine, point the AI SDK OpenAI-compatible provider at a local server. This works with any server that implements the OpenAI Chat Completions API, such as Ollama, LM Studio, llama.cpp, or vLLM. With Ollama:
pnpm add @ai-sdk/openai-compatible
ollama pull gpt-oss:20b
OLLAMA_CONTEXT_LENGTH=64000 ollama serve
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { defineAgent } from "eve";
const ollama = createOpenAICompatible({
name: "ollama",
baseURL: "http://localhost:11434/v1",
includeUsage: true, // report token usage while streaming
});
export default defineAgent({
model: ollama("gpt-oss:20b"),
modelContextWindowTokens: 64_000,
});
- Context window. AI Gateway has no metadata for local models, so set
modelContextWindowTokensto the context length your server allocates, not the model's maximum. eve uses it to decide when to compact. Ollama allocates as little as 4K tokens by default; raise it to at least 64K for agents, as above. - Tool calling. eve agents call tools on most turns, so pick a model with
native tool-calling support.
gpt-oss:20b,qwen3, andgemma4are good starting points on Ollama. - Usage.
includeUsage: truelets token usage reach eve's session limits. Local models report no cost, socostUsdstays unset in asessionUsagecheck. - Other servers. Change
baseURL, for example tohttp://localhost:1234/v1for LM Studio. PassapiKeyfor a remote OpenAI-compatible server that requires one.
A deployment cannot reach a server on your machine, so use a Gateway or hosted provider model when you deploy.
Choose the model dynamically
To select a model from the incoming prompt with an AI SDK decision model, use
auto from eve/models.
model also accepts defineDynamic({ events }). Each matching handler must
return the concrete model for its scope; a dynamic model has no compiled
default.
import { defineAgent, defineDynamic } from "eve";
export default defineAgent({
model: defineDynamic({
events: {
"session.started": (_event, ctx) => {
if (ctx.session.auth.initiator?.attributes.plan === "enterprise") {
return "anthropic/claude-opus-5.5";
}
return "anthropic/claude-sonnet-5";
},
},
}),
});
Handlers receive the shared dynamic resolver
context and return a gateway model id, an AI
SDK LanguageModel, or a selection object. Returning null or undefined
fails the turn.
- Scopes.
session.started(once per session),turn.started(once per turn),step.started(every model step). Precedence: step > turn > session. Prefersession.started: prompt caches are per model, so every switch re-ingests the conversation at uncached prices. If no active selection exists before model-dependent work begins, the turn fails. - Failures stop the turn. A resolver that throws, returns no model, or returns an invalid selection fails before the provider call. A selected model without valid credentials fails at request time.
- Serialization. Session/turn selections must be model id strings; return
live
LanguageModelobjects only fromstep.started. - Selection object.
{ model, reasoning?, modelContextWindowTokens?, modelOptions? }. WhenmodelContextWindowTokensis omitted, eve resolves it from the AI Gateway catalog and caches successful metadata in durable session state for 24 hours. Set it explicitly for an unlisted or custom model. Dynamic agents cannot set siblingmodelContextWindowTokensormodelOptionsfields; return per-model values from the handler.
The session.started runtime identity does not include a model id for a
dynamic agent. Each public step.started event reports the concrete modelId
selected for that model call.
Reasoning effort
In an authored agent.ts with a static model, omitting reasoning uses the provider's default.
Set reasoning to control the model's reasoning effort through AI SDK's
provider-agnostic option:
export default defineAgent({
model: "openai/gpt-5.5",
reasoning: "high",
});
Supported values are "provider-default", "none", "minimal", "low",
"medium", "high", and "xhigh". The selected model and provider determine
which levels are available and how they map to provider-native settings. Use
modelOptions.providerOptions when you need provider-specific reasoning controls.
A dynamic model selection can return reasoning alongside model to override
the agent-level setting for that selection. Omitting it inherits the agent setting;
"provider-default" explicitly uses the provider's default.
Run eve set model --reasoning high to update this field from the command line.
Prompt caching
eve caches prompts automatically for AI Gateway models and for Anthropic models
it recognizes by provider or model id. Set modelOptions.promptCache on a
directly called model to mark an unrecognized model as Anthropic (such as a
Bedrock application inference profile) or to use a 1-hour cache:
import { bedrock } from "@ai-sdk/amazon-bedrock";
import { defineAgent } from "eve";
export default defineAgent({
model: bedrock(process.env.BEDROCK_INFERENCE_PROFILE_ARN!),
modelContextWindowTokens: 200_000,
modelOptions: {
promptCache: { anthropic: { ttl: "1h" } }, // or { anthropic: {} } for the default 5m
},
});
Not every Claude model supports a 1-hour cache. eve rejects promptCache on
Gateway models; use providerOptions.gateway.caching instead.
Compaction
Compaction summarizes older turns as you approach the context window. It's on by default, so you only tune when it kicks in. eve adds the estimated fixed checkpoint-prompt envelope to the trigger count, so compaction starts sooner than the conversation-only estimate. Lower thresholdPercent to compact sooner:
export default defineAgent({
model: "anthropic/claude-opus-5.5",
compaction: {
thresholdPercent: 0.75, // default 0.9
},
});
See Default harness for how the loop applies it.
Runtime limits
Use limits for framework-owned runtime caps. sessionUsage decides when the
current durable session must stop starting model calls. It receives the
session's usage and returns true when the limit is reached:
export default defineAgent({
model: "anthropic/claude-opus-5.5",
limits: {
sessionUsage: ({ window }) =>
window.inputTokens - window.cacheReadTokens >= 200_000 ||
window.outputTokens >= 20_000 ||
(window.costUsd ?? 0) >= 1.5,
sessionTimeoutMs: 7 * 24 * 60 * 60 * 1_000,
},
});
sessionTimeoutMs sets how long a session may sit idle before eve completes it,
for every session, including delegated sessions. It defaults to 30 days. The
idle window starts at creation and restarts each time a turn settles, including
turns that answer a message, clear or compact the context, or end in
cancellation. A session never expires while a turn is open, including a turn
held open while its tasks work or while it waits for a person
to answer; the window restarts when that turn settles. Process restarts do not
change the window. When the window elapses, eve emits session.completed and
releases every continuation address; the next qualifying channel message starts
fresh. To carry an earlier conversation into the fresh session, pass it as
prior history. Set it to false to
disable the timeout. Session expiration follows
run-data retention; a zero-retention session loses its
stored payloads when it ends.
sessionUsage gets two usage records with inputTokens, outputTokens,
cacheReadTokens, cacheWriteTokens, and costUsd: total is everything
the session has spent, and window is what it spent since the last approved
continuation. inputTokens includes cache reads and writes. Subtract
cacheReadTokens to count only new input; cache reads are the history a
provider replays from its prompt cache on every step. costUsd is the model
token cost in US dollars that AI Gateway reports with each step, not tool or
infrastructure spend; it is unset when no step reported a cost.
When sessionUsage is omitted, the limit is 40_000_000 new input tokens per
window:
({ window }) => window.inputTokens - window.cacheReadTokens >= 40_000_000;
sessionUsage can raise its threshold after each approval. This limit asks
at 20,000 new input tokens, then at 40,000, 80,000, and so on:
export default defineAgent({
model: "anthropic/claude-opus-5.5",
limits: {
sessionUsage: ({ total, window }) => {
const used = total.inputTokens - total.cacheReadTokens;
// Usage when the last continuation was approved; 0 before the first.
const approvedAt = used - (window.inputTokens - window.cacheReadTokens);
// Double past it, so each approval allows twice the usage before the next prompt.
let next = 20_000;
while (next <= approvedAt) next *= 2;
return used >= next;
},
},
});
Set sessionUsage: () => false to leave sessions uncapped; sessionUsage: false is not accepted. eve calls sessionUsage before each model call once
the window has usage. The model call that crosses a limit is allowed to finish
because exact usage arrives after the call completes. Before the next model
call, eve pauses the turn (turn.waiting) and sends a deterministic
continuation prompt with two options: Continue starts a new window and
resumes the same turn, and Stop cancels the in-flight turn through the
standard cancellation path (turn.cancelled → session.waiting). Stop is a
user decision, not an error. The session stays resumable; because it is still
over budget after Stop, the next message raises a new prompt. Declining a
delegated child's prompt cancels the root turn, which cascades to the whole
delegation tree, so the delegating parent never receives an error result it
could retry. A reply that answers neither option is queued while the existing
prompt stays pending; eve does not raise another
copy or start another turn. The reply is received (message.received) and
processed in the held turn once the budget is granted.
For sessions already waiting on a continuation prompt from an older deployment, the previous turn has completed. A non-answer message still queues behind the existing prompt, but emits no event until Continue is chosen. Continue starts a new turn and receives the queued message once; it does not reopen the completed turn or duplicate the prompt.
Sessions that cannot request input from a human, such as markdown schedules and
delegated runs without input proxying, skip the prompt and fail the next model
call with SESSION_USAGE_LIMIT_REACHED. Its details carry the total and
window usage the check saw.
Each subagent session checks its own usage against its own sessionUsage, or
the root agent's when it authors none. A dynamic subagent can't select
sessionUsage at runtime and always uses the root agent's. Remote agents run
under their own deployment's limits.
A child's usage, including what the child's own subagents spent, also counts
in the parent's usage. An agent task's usage counts with each reply it
sends. A turn it doesn't reply to, such as one a cancel stopped, counts with
the next reply, or when the turn ends if no call waits for a reply. Sessions
that any other serve workflow tool opens with ctx.agent count the same
way; those of an execute or task tool count when the tool finishes. Remote
agents' reported usage counts the same way, cost included. Approving a
continuation starts a new window without erasing total.
Some delegated usage doesn't count against the parent: a ctx.agent turn
still running when its workflow tool finishes or is cancelled; the ctx.agent
usage of an execute tool whose parent turn is cancelled while it waits; and
what a cancelled agent task's own subagents spend after the task reports its
cancelled turn, until the task's next reply.
Workflow world
By default, eve selects the Workflow SDK world for the host: Vercel Workflow on
Vercel, and the SDK's local world in local development or eve start. Advanced
self-hosted deployments can select the Workflow world package to use from the
root agent.ts:
import { defineAgent } from "eve";
export default defineAgent({
model: "anthropic/claude-opus-5.5",
experimental: {
workflow: {
world: "@workflow/world-postgres",
},
},
});
Install that package in your app. It should export a default factory or
createWorld() function. Pin a version built against the same @workflow/*
line as your eve release (currently the 5.0.0-beta line):
pnpm add @workflow/[email protected]
The npm latest tag can lag behind that line, so an unpinned install may pull
an incompatible protocol version that the Workflow SDK rejects during initialization.
Put credentials and host-specific options in runtime environment variables read
by the world package, not in agent.ts. For the Postgres world, that means
putting the connection string or credentials in the env vars it reads. If the
installed package must stay external in hosted output, list it in
build.externalDependencies.
Workflow checkpoint batching
By default, eve commits a durable Workflow step after every model call and its inline tool calls. You can experimentally let one Workflow step run several sequential model calls:
import { defineAgent } from "eve";
export default defineAgent({
model: "anthropic/claude-opus-5.5",
experimental: {
workflow: {
modelCallsPerStep: 4,
},
},
});
experimental.workflow.modelCallsPerStep is a positive-integer ceiling. It defaults to
1 and applies independently to each root agent or declared subagent. A higher
value can reduce Workflow checkpoint overhead in sequential tool loops, but it
widens the replay unit: if the Workflow step is interrupted, its earlier model
calls and inline tool executions can run again. That can repeat provider costs,
events, and side effects. Use stable idempotency keys for non-idempotent tools.
eve ends a batch before it waits for input, authorization, or blocking coordination. A batch can also end below the configured ceiling when the turn completes or steering arrives. Before assistant output begins, steering can interrupt pending model generation. Executing tools finish safely before the batch yields and applies the correction. This option is experimental and may change or disappear in any release. See Execution model and durability for the retry behavior.
Run data retention
By default, eve derives run-data retention from the session's resolved OpenTelemetry trace policy:
- When the policy allows both inputs and outputs, eve uses the World's default retention period.
- When the policy drops the trace or excludes either content direction, eve
requests deletion as soon as the run ends with Workflow's
experimental_retention: 0. Workflow cannot delete inputs and outputs separately.
Without a custom policy, public conversations and development sessions use the
World's default. Private and unknown-audience sessions outside development request
0, even when no OpenTelemetry destination is installed. This decision is made
when the session starts; destination export filters and lifecycle-provider
policies do not change it.
Set experimental.workflow.retention explicitly to override this behavior.
Use 0 to request deletion regardless of the tracing policy, or "default" to
keep run data for the World's default period regardless of the tracing policy:
import { defineAgent } from "eve";
export default defineAgent({
model: "anthropic/claude-opus-5.5",
experimental: {
workflow: {
retention: 0,
},
},
});
The resolved value applies to every run that owns the session, including successor owners started after a deployment handoff, and to the run that collects session activity. Runs eve starts for other purposes keep the world's default: session timeouts and workflow tools.
The value applies per agent. A subagent that runs its own session
uses its own explicit value or derives retention from its resolved trace decision,
including any inherited content ceiling. experimental.workflow.world is root-only.
At 0, supporting Worlds delete run and step inputs, outputs, and errors;
event payloads; and stream contents when the run reaches a terminal state. The
data remains available while the session is active. Run, step, and event records
remain for the World's default period, including IDs, timestamps, statuses,
step names, and attributes. Attributes can contain content, including eve's
session title. This option does not delete local traces, exported telemetry, or
data stored by tools, channels, or model providers.
The Workflow World enforces deletion, not eve or the SDK. A World older than
spec version 4 rejects 0; a spec version 4 World without retention support
keeps the data. Confirm support with your World provider. See
Workflow data retention.
⚠️ At
0, completed session transcripts become unreadable. Deletion races reads of finished runs. Depending on the World, reading deleted session history returns either an empty stream or410withcode: "session_expired". Persist anything you need to keep from inside a tool, or setretention: "default"to preserve completed-session reads independently of tracing.
Other defineAgent fields
defineAgent takes a few more fields, all optional. For the exported types, see the TypeScript API Reference.
| Field | Type | Default | Description |
|---|---|---|---|
reasoning |
AgentReasoningDefinition |
provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |
modelOptions |
AgentModelOptionsDefinition |
none | Provider option overrides forwarded to the model call, and promptCache settings. |
limits |
AgentLimitsDefinition |
field-specific | Framework-owned runtime limits. Sessions complete after 30 idle days by default; usage-limit defaults and inheritance are described above. Set a limit to false to disable it. |
experimental |
AgentExperimentalDefinition |
unset | Unstable opt-ins. workflow.world selects the Workflow world package on the root agent; workflow.modelCallsPerStep batches sequential model calls into a wider replay unit; workflow.retention controls how long the durable runtime keeps run data. |
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. |
tool |
boolean | "deferred" |
true |
Exposes this agent to its parent model as a tool. "deferred" keeps it out of the model's tool list; the model finds it with eve__search and calls it with eve__tool. On the root agent, controls the built-in agent tool. A subagent with tool: false remains callable from authored workflow tools through ctx.agent(). |
externalDependencies is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.
During eve dev, ordinary dependencies are bundled into each retained runtime generation. Packages listed in externalDependencies keep normal Node.js resolution instead, so replacing one of those packages requires restarting the dev server.
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/, Instrumentation |
What to read next
- Default harness for compaction and model context, and Built-in tools for the framework-provided tool set
- TypeScript API Reference for every
defineAgentfield and type - Subagents for the
descriptionrequirement and child-agent config