Agent Config

Purpose and Scope

The agent configuration file is the top-level runtime declaration for an eve agent. In eve terminology, an agent's agent.ts calls defineAgent from eve and exports the resulting configuration. This is the file reviewers should open when they want to understand which model the agent uses, whether reasoning effort has been selected, how aggressively older conversation context is compacted, and what framework-owned token ceilings apply to a durable session. It is not the place for the agent's persona, callable tools, channel setup, schedules, or frontend integration; those live in their own filesystem conventions. Sources: docs/agent-config.md

The source contract is deliberately small because eve is filesystem-first. A project can be inspected by looking at conventional files under the agent directory, and the runtime configuration is one of those conventions. The root agent.ts is optional when no runtime configuration is needed, which keeps simple projects from carrying a meaningless placeholder. If the file is omitted, eve uses the default model anthropic/claude-sonnet-5. If the file is present, model becomes required, so adding the file is an explicit decision to own model selection and any additional runtime settings. Sources: docs/agent-config.md

Use this page when you are choosing between the default model and an explicit model, switching from Vercel AI Gateway routing to a direct provider SDK, tuning reasoning behavior, adjusting long-session context handling, or setting per-session budget guards. Each of those choices affects operations as much as code style. A model identifier controls routing and credentials, a reasoning level can change provider behavior, compaction changes how conversation history is summarized, and limits determine when a durable session is allowed to continue making model calls.

Relevant Source Files

• docs/agent-config.md - Defines the public agent.ts documentation contract, including defineAgent, gateway model ids, provider-authored LanguageModel values, reasoning effort, provider options, compaction, runtime limits, token-limit behavior, and workflow-world defaults.

Core Configuration Contract

A typical configuration imports defineAgent and exports a default value from agent/agent.ts. The minimal useful form selects a model. In the documented gateway example, the value is a string such as anthropic/claude-opus-4.8, which routes through the Vercel AI Gateway. This keeps model routing out of custom application boot code and makes the agent's default model visible in one predictable file. It also means the identifier follows the gateway catalog's naming scheme, so it should not be blindly copied into direct provider SDK calls. Sources: docs/agent-config.md

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

The same model field can also accept a provider-authored LanguageModel. That path is useful when a project wants to configure the provider in code or call the provider directly instead of using a gateway model id string. The tradeoff is dependency and credential ownership. A fresh eve init app includes the core AI SDK package, but it does not install every provider package. If the configuration imports @ai-sdk/anthropic, the project must install that package and provide the provider-specific key expected by the SDK. Sources: docs/agent-config.md

npm install @ai-sdk/anthropic

import { anthropic } from "@ai-sdk/anthropic";
import { defineAgent } from "eve";
 
export default defineAgent({
  model: anthropic("claude-opus-4-8"),
});

The gateway and direct-provider examples intentionally use different Anthropic model id spellings. The gateway route uses anthropic/claude-opus-4.8, while the direct provider call uses the provider-native claude-opus-4-8. That distinction is a common source of setup confusion because both values describe an Anthropic model but belong to different routing paths. When a local session fails to reach the model, first identify whether the configuration is using a gateway string or a direct LanguageModel, then check the matching package installation, API key, model catalog, and provider terms. Sources: docs/agent-config.md

Model selection is also a governance decision. The source documentation notes that model use is subject to the terms, data-processing commitments, retention behavior, and available controls of the selected provider and routing path. That means a pull request changing agent.ts can change more than output quality. It can alter where prompts and data are routed, which provider terms apply, and which controls operators can rely on. Treat model edits as deployable runtime changes, not cosmetic refactors, especially for agents that handle user data or business records. Sources: docs/agent-config.md

System-to-Code Mapping

Because eve organizes agent behavior around files, agent.ts should be read beside the other agent primitives rather than as a replacement for them. Instructions define the always-on behavior, tools expose typed functions, skills provide reusable procedures, channels deliver messages, schedules start recurring work, and subagents delegate tasks. The top-level config supplies runtime policy around the model and session loop. Keeping those responsibilities separate makes the project easier to review: a developer can ask, “What can this agent do?” in capability files and “How does the runtime run it?” in agent.ts. Sources: docs/agent-config.md

This separation also helps when debugging. If the agent gives poor answers, agent.ts may be the right place to inspect model quality or reasoning effort, but it is not where a missing tool description or weak persona should be fixed. If a conversation loses older details, compaction may be relevant, but the instructions and task design still matter. If a session stops unexpectedly after heavy usage, token limits belong in this file. The mapping table gives teams a way to route problems to the right source file before making changes.

Runtime Controls: Reasoning, Compaction, and Limits

Set reasoning when the selected model and provider expose useful reasoning-effort behavior through the AI SDK provider-agnostic option. The documented values are provider-default, none, minimal, low, medium, high, and xhigh. The shape of the option is portable, but the effect is provider-dependent. A level that is accepted by the configuration still needs representative testing with the selected model because providers decide which levels are available and how they map to native settings. For provider-specific reasoning controls, use modelOptions.providerOptions. Sources: docs/agent-config.md

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

Compaction is eve's built-in response to context pressure. As a session approaches the model context window, older turns are summarized so the conversation can continue with a compressed record of prior work. It is enabled by default, so most projects should begin without a custom compaction block. The documented tuning knob is compaction.thresholdPercent; lowering it makes compaction begin sooner. The example lowers the threshold to 0.75, while the comment identifies 0.9 as the default threshold. Sources: docs/agent-config.md

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

Tune compaction only when you have a product reason or evaluation signal. Earlier compaction can make very long conversations more resilient because the runtime summarizes before the context window is under severe pressure. It can also compress details sooner than a user expects, which may matter for agents that must retain exact prior wording, calculations, or constraints. Later compaction preserves more raw history for longer, but it leaves less room before the window fills. The best threshold depends on conversation length, model behavior, and whether the agent can recover details from tools, memory, or external systems.

Runtime limits are framework-owned caps for the current durable session. Configure limits.maxInputTokensPerSession and limits.maxOutputTokensPerSession when a product needs explicit guardrails around accumulated model usage. Input and output budgets are checked independently. The call that crosses either configured limit is allowed to finish because providers only report exact token usage after a call completes. Follow-up model calls in the same session then fail with SESSION_TOKEN_LIMIT_REACHED. Sources: docs/agent-config.md

export default defineAgent({
  model: "anthropic/claude-opus-4.8",
  limits: {
    maxInputTokensPerSession: 200_000,
    maxOutputTokensPerSession: 20_000,
  },
});

The default input limit is high enough that many local experiments will never notice it, but it is still part of the contract. When maxInputTokensPerSession is omitted, eve applies 40_000_000 provider-reported input tokens for root sessions and 5_000_000 for delegated subagent sessions. maxOutputTokensPerSession is unset unless configured. That asymmetry matters for cost and safety reviews: input usage has a default ceiling, delegated work has a smaller default input ceiling, and output volume requires an explicit cap if the product needs one. Sources: docs/agent-config.md

Workflow World and Project Placement

The source documentation also defines the default workflow-world selection. On Vercel, eve selects Vercel Workflow. In local development or when using eve start, it selects the Workflow SDK's local world. This means most projects do not need to encode a local-versus-hosted execution branch inside agent.ts. The file can stay focused on agent runtime configuration while the environment determines the appropriate workflow host. For durable agents, that distinction is important because the workflow host governs where execution runs, while the configuration describes model-facing and session-facing policy. Sources: docs/agent-config.md

In practice, begin with the scaffolded shape and add options as requirements become concrete. An analytics assistant might choose a stronger model and a higher reasoning setting after evaluation shows improved analysis quality. A support agent with long customer conversations might tune compaction after observing context pressure. A budget-sensitive workflow might set both input and output limits. A parent agent that delegates to subagents should remember the lower default input budget for delegated sessions. Each change should be small enough to review and easy to connect to an operational reason.

Compact Reference

Implementation Guidance and Next Steps

Before editing agent.ts, name the runtime problem you are solving. If the issue is model quality, change model or reasoning and test representative prompts. If the issue is credential setup, confirm whether the project uses a gateway id string or a direct provider LanguageModel. If the issue is long-session continuity, evaluate compaction behavior over a conversation long enough to approach the context window. If the issue is spend control, configure token limits and verify that the current call can finish before the next call is rejected.

After the change, run the local development flow and exercise the path that depends on the new setting. A model swap should be tested with the same prompt set before and after the change. A reasoning change should be tested against the task that motivated it, not only a smoke prompt. A compaction change should be tested in a long session where older details matter. Token limits should be validated by observing that follow-up calls fail with the documented error after provider-reported usage crosses the configured budget. For broader context, continue with Default Harness, Execution Model and Durability, Subagents, and Project Layout Reference.