Ch5. agent.ts, Models, Compaction

agent/agent.ts configures runtime behavior. In small demos it often only selects a model. In enterprise systems it decides model routing, output contracts, long-session memory behavior, and unstable feature adoption.

Basic Form

import { defineAgent } from "eve";

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

The official agent.ts docs clarify two important rules:

The scaffold default is anthropic/claude-sonnet-4.6; stronger examples often use anthropic/claude-opus-4.8. Treat these as routing examples, not universal recommendations.

Model Routing Strategy

For enterprise teams, Gateway-routed models are usually the default because usage, fallback, cost, and policy can be centralized. Direct provider models are still valid when specific provider options or self-host constraints require them.

Model Selection Matrix

The goal is not "the smartest model." The goal is the model with the lowest failure cost for the capability surface.

modelOptions

modelOptions forwards provider-specific tuning such as temperature, reasoning effort, or provider metadata.

Operating rules:

• separate reasoning-heavy agents from transactional agents
• gate model option changes like prompt changes
• record model id and options in eval results
• document provider-specific portability risks

outputSchema

outputSchema is not a global enforcement mechanism for every chat reply. Official docs describe it as the structured return type for task-mode runs such as subagents, schedules, or remote jobs. Clients may also pass per-turn schemas.

Good uses:

import { defineAgent } from "eve";
import { z } from "zod";

export default defineAgent({
  description: "Review a proposed operation and return risk level and required approvals.",
  model: "anthropic/claude-opus-4.8",
  outputSchema: z.object({
    risk: z.enum(["low", "medium", "high"]),
    requiredApprovals: z.array(z.string()),
    rationale: z.string(),
  }),
});

Compaction

The default harness summarizes older turns as the context window fills. The default threshold is 90%.

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

Compaction saves context and cost, but it is also a risk surface. A bad summary can corrupt the factual base of a long session.

Experimental Flags

Official docs mark experimental.codeMode as unstable. ExperimentalWorkflow is covered separately under Dynamic Workflows. Both require stricter release gates.

Hosted Build Packaging

build.externalDependencies keeps selected packages external in hosted output. It is packaging control, not security approval.

Review:

• package install availability in target host
• third-party SDK network and data behavior
• security review for externalized dependency
• parity between Vercel and self-host environments

Review Checklist