Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

28.5 KB
Raw Blame

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 modelContextWindowTokens to 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, and gemma4 are good starting points on Ollama.
  • Usage. includeUsage: true lets token usage reach eve's session limits. Local models report no cost, so costUsd stays unset in a sessionUsage check.
  • Other servers. Change baseURL, for example to http://localhost:1234/v1 for LM Studio. Pass apiKey for 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. Prefer session.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 LanguageModel objects only from step.started.
  • Selection object. { model, reasoning?, modelContextWindowTokens?, modelOptions? }. When modelContextWindowTokens is 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 sibling modelContextWindowTokens or modelOptions fields; 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 or 410 with code: "session_expired". Persist anything you need to keep from inside a tool, or set retention: "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