Ch5. agent.ts, Models, Compaction
Interpret defineAgent configuration as runtime policy for models, output schemas, compaction, and experimental flags.
핵심 요약
agent.tsis not just a model picker; it is runtime policy and output contract.outputSchema, compaction, andmodelOptionsstrongly affect long-session quality and cost.- Experimental flags and hosted-build packaging controls need owners and release gates.
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:
| Rule | Operational meaning |
|---|---|
Root agent.ts can be omitted when no runtime config is needed | Useful for tiny agents, but production agents should pin model/config for review. |
If agent.ts is present, model is required | Do not hide policy behind an empty defineAgent({}). |
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
| Model definition | Example | Advantage | Caution |
|---|---|---|---|
| Gateway model id string | "anthropic/claude-opus-4.8" | Vercel AI Gateway routing, central policy, OIDC flow | Review Gateway model catalog and policy. |
AI SDK LanguageModel | anthropic("claude-opus-4.8") | Direct provider control | Install provider package and manage provider key/terms. |
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
| Agent type | Selection criteria |
|---|---|
| customer support | low latency, stable instruction following, safety behavior |
| internal research | long context, tool reasoning, citation discipline |
| code/file work | tool-call stability, sandbox behavior, large context |
| back-office automation | structured output reliability and approval UX |
| eval judge | consistency, cost, and separation from agent-under-test |
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:
| Scenario | Why |
|---|---|
| subagent result aggregation | parent needs machine-readable results |
| scheduled report | downstream job reads JSON |
| remote agent delegation | deployment-to-deployment contract |
| eval target | exact schema assertions |
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.
| Workload | Recommended policy |
|---|---|
| short FAQ/support | default threshold |
| long research | compact earlier; persist key artifacts in files/state |
| coding/file work | read-before-write evidence can disappear from summary |
| regulated decisioning | externalize important evidence |
| multi-subagent work | structure child results before parent aggregation |
Experimental Flags
Official docs mark experimental.codeMode as unstable. ExperimentalWorkflow is covered separately under Dynamic Workflows. Both require stricter release gates.
| Feature | Meaning | Production standard |
|---|---|---|
codeMode | model-authored JavaScript can call tools through a sandboxed wrapper | limited internal agents only |
ExperimentalWorkflow | model-authored JavaScript orchestrates subagents | subagent-only coordination, no direct side effects |
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
| Item | Question |
|---|---|
| model | Is the routing path approved? |
| modelOptions | Are behavior and cost intended? |
| outputSchema | Is task-mode structure needed here? |
| compaction | Can the workload tolerate summary drift? |
| experimental | Are unstable features scoped and evaluated? |
| build | Are external dependencies reviewed and deployable? |