# Configure agent.ts

> defineAgent fields: model (gateway id or LanguageModel), compaction thresholdPercent, modelOptions, experimental.codeMode, outputSchema, and build.externalDependencies packaging.

- Repository: vercel/eve
- GitHub: https://github.com/vercel/eve
- Human docs: https://grok-wiki.com/public/docs/vercel-eve-759e1d74a10f
- Complete Markdown: https://grok-wiki.com/public/docs/vercel-eve-759e1d74a10f/llms-full.txt

## Source Files

- `docs/agent-config.md`
- `packages/eve/src/public/definitions/agent.ts`
- `packages/eve/src/compiler/normalize-agent-config.ts`
- `packages/eve/src/compiler/model-catalog.ts`
- `apps/fixtures/weather-agent/agent/agent.ts`

---

---
title: "Configure agent.ts"
description: "defineAgent fields: model (gateway id or LanguageModel), compaction thresholdPercent, modelOptions, experimental.codeMode, outputSchema, and build.externalDependencies packaging."
---

`agent/agent.ts` exports a default `defineAgent({ ... })` call that sets the agent's runtime configuration. Eve compiles this module at build time into `.eve/` manifest artifacts: model routing, compaction thresholds, experimental flags, structured output schemas, and hosted-build externals. Agent identity (`name`) is derived from `manifest.agentId` (package name or app-root basename); do not author a `name` field. Declare inbound auth and network policy on channels, not in `agent.ts`.

```text
agent/agent.ts  →  compileAgentConfig()  →  .eve/manifest (config.*)
                              ↓
                    runtime resolve-agent  →  harness sessions / turns
```

<Steps>
<Step title="Create or edit agent/agent.ts">

Export a default `defineAgent` call from `agent/agent.ts` (or `agent.mjs` / `agent.cts` / `agent.mts`). `eve init` scaffolds this file with a gateway model id.

```ts title="agent/agent.ts"
import { defineAgent } from "eve";

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

</Step>

<Step title="Verify discovery and compilation">

Run `eve info` to confirm the config module is discovered, then `eve build` to compile it into `.eve/`. Build fails closed when `model` is missing, unknown keys are present, or the AI Gateway catalog cannot resolve context-window metadata for compaction.

</Step>
</Steps>

## Omitting agent.ts

When no config module exists under `agent/`, Eve injects a synthetic default: `model: "anthropic/claude-sonnet-4.6"`. Once you add `agent.ts`, `model` is required — an empty export throws at compile time with `The "model" field is required.`

## Model

`model` selects the language model for agent turns. Accept either a gateway model id string or an AI SDK `LanguageModel` instance.

<CodeGroup>
```ts title="Gateway model id"
import { defineAgent } from "eve";

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

```ts title="Direct provider instance"
import { anthropic } from "@ai-sdk/anthropic";
import { defineAgent } from "eve";

export default defineAgent({
  model: anthropic("claude-opus-4.8"),
});
```

```ts title="Provider options (weather fixture)"
import { defineAgent } from "eve";

export default defineAgent({
  model: "openai/gpt-5.5",
  modelOptions: {
    providerOptions: {
      openai: {
        reasoningEffort: "high",
        reasoningSummary: "auto",
      },
    },
  },
});
```
</CodeGroup>

<ParamField body="model" type="string | LanguageModel" required>
Gateway model id (`provider/model`) or an AI SDK-compatible `LanguageModel` (for example from `anthropic(...)`, `gateway(...)`, or another provider factory). Required when `agent.ts` is present.
</ParamField>

<ParamField body="modelContextWindowTokens" type="number">
Optional override for the primary model's context window size in tokens. Escape hatch when Eve cannot resolve metadata from the AI Gateway catalog (custom or unlisted models). When set, Eve skips the catalog lookup and uses this value verbatim for compaction threshold math.
</ParamField>

<ParamField body="modelOptions" type="AgentModelOptionsDefinition">
Provider option overrides forwarded to the AI SDK model runtime call. Currently supports `providerOptions`: a record keyed by provider slug with JSON-serializable option objects.
</ParamField>

### Routing at compile time

Eve classifies how the model reaches inference and embeds routing in the compiled manifest:

| Authored value | Routing | Runtime behavior |
| --- | --- | --- |
| Gateway id string (`anthropic/claude-sonnet-4.6`) | `gateway` | Routed through the Vercel AI Gateway |
| `gateway(...)` instance | `gateway` | Same as a string id |
| Direct provider instance (`anthropic(...)`) | `external` | Bypasses the gateway; talks to the provider endpoint |
| Gateway id + `providerOptions.gateway.byok` | `gateway` with `byok` | Forwards a bring-your-own-key provider block through the gateway |

<Note>
Compile time fetches the AI Gateway model catalog (cached at `.eve/cache/model-catalog.json`, 24-hour TTL) to embed `contextWindowTokens` for compaction. Build fails when metadata is unavailable and no `modelContextWindowTokens` override is set: `Cannot compile agent compaction because ... does not have known AI Gateway context window metadata.`
</Note>

Credential setup for gateway vs direct provider routing is covered on the installation page.

## Compaction

Compaction summarizes older turns when the conversation approaches the model's context window. The harness applies it automatically; tune when it triggers via the optional `compaction` block.

```ts title="agent/agent.ts"
export default defineAgent({
  model: "anthropic/claude-opus-4.8",
  compaction: {
    thresholdPercent: 0.75,
  },
});
```

<ParamField body="compaction.thresholdPercent" type="number (0–1)">
Fraction of the primary model context window that triggers compaction. Defaults to `0.9` at runtime when omitted. Lower values compact sooner.
</ParamField>

<ParamField body="compaction.model" type="LanguageModel">
Optional model used only for compaction summaries. When omitted, Eve uses the active turn model for the summary call.
</ParamField>

<ParamField body="compaction.modelContextWindowTokens" type="number">
Same escape hatch as `modelContextWindowTokens`, but for the compaction summary model.
</ParamField>

At session creation, Eve computes the token threshold as `floor(contextWindowTokens × thresholdPercent)` with a `recentWindowSize` of 10 turns preserved verbatim. See the default harness page for how compaction interacts with read-before-write tracking and todo re-injection.

## Experimental code mode

`experimental.codeMode` routes executable tools through a sandboxed code-execution wrapper (`code_mode` tool) instead of exposing them directly to the model. The model writes JavaScript that calls tools inside the sandbox.

```ts title="agent/agent.ts"
export default defineAgent({
  model: "openai/gpt-5.4",
  experimental: { codeMode: true },
});
```

<Warning>
`experimental` flags are unstable and may change or be removed in any release. Each agent node (root and every subagent) carries its own flags — enable code mode for the whole graph, only a subagent, or only the parent.
</Warning>

| Resolution | Effective value |
| --- | --- |
| `experimental.codeMode: true` | Code mode on |
| `experimental.codeMode: false` | Code mode off (overrides env) |
| Flag omitted | Falls back to `EVE_EXPERIMENTAL_CODE_MODE` env var; only `"1"` enables it |

When any node in the compiled graph enables code mode (or the `Workflow` tool), the hosted build bundles sandbox worker assets. Code mode requires a configured sandbox backend.

## Output schema

`outputSchema` declares a structured return type for task-mode runs: subagent delegation, schedule invocations, and remote jobs. Eve normalizes Standard Schema or JSON Schema objects to JSON Schema at compile time.

```ts title="agent/agent.ts"
import { z } from "zod";
import { defineAgent } from "eve";

const Report = z.object({
  title: z.string(),
  count: z.number().int(),
});

export default defineAgent({
  model: "openai/gpt-5.4-mini",
  outputSchema: Report,
});
```

Interactive conversation turns ignore the agent-level schema unless the client supplies a per-message `outputSchema` on `POST /eve/v1/session`. After a structured-output turn completes, the schema does not leak into subsequent plain turns.

## Build packaging

`build.externalDependencies` controls hosted-build packaging only. It does not affect prompts, tool execution, or runtime APIs.

```ts title="agent/agent.ts"
export default defineAgent({
  model: "openai/gpt-5.4-mini",
  build: {
    externalDependencies: ["sharp", "fixture-trace-only-dep"],
  },
});
```

<ParamField body="build.externalDependencies" type="string[]">
Package names Eve should keep external while compiling authored TypeScript modules (tools, channels, schedules, skills, instructions, connections, sandbox). Listed packages are traced into `server/node_modules` in hosted output instead of being inlined by the bundler. Prefer this for packages sensitive to bundling (native binaries, platform-specific artifacts).
</ParamField>

During compilation, Eve merges `externalDependencies` from the root agent down through the subagent graph and passes the merged list to every authored module compile step. The framework also auto-traces `@napi-rs/keyring` (pulled in transitively through Vercel OIDC auth) without requiring author configuration.

## Description (subagents)

`description` is optional on the root agent. Local subagents under `agent/subagents/<id>/agent.ts` must include `description` — Eve surfaces it as the lowered subagent tool's description so the parent can decide when to delegate. Build fails with a clear error when a subagent omits it.

## Field reference

| Field | Type | Default | Scope |
| --- | --- | --- | --- |
| `model` | `string \| LanguageModel` | `anthropic/claude-sonnet-4.6` when `agent.ts` omitted | Runtime turns |
| `modelContextWindowTokens` | `number` | catalog lookup | Compaction threshold math |
| `modelOptions` | `{ providerOptions? }` | none | Model call options |
| `compaction` | object | harness defaults (`thresholdPercent` → `0.9`) | Context management |
| `experimental.codeMode` | `boolean` | env backstop, else `false` | Tool exposure mode |
| `outputSchema` | Standard Schema or JSON Schema | none | Task-mode structured output |
| `build.externalDependencies` | `string[]` | none | Hosted build packaging |
| `description` | `string` | none | Subagent tool description (required for local subagents) |

`defineAgent` rejects unknown keys at normalization time. TypeScript checks the argument against `AgentDefinition` via `ExactDefinition`, so typos surface as compile errors in the editor.

## Adjacent configuration

| Concern | Location |
| --- | --- |
| System prompt | `agent/instructions.md` or `agent/instructions.ts` |
| Per-tool HITL approval | `agent/tools/*.ts` |
| Inbound auth and network policy | channel definitions (`agent/channels/`) |
| Sandbox and workspace | `agent/sandbox/` |
| Telemetry | `agent/instrumentation.ts` |
| Eval suites | `evals/` |

## Troubleshooting

| Symptom | Likely cause |
| --- | --- |
| `The "model" field is required.` | `agent.ts` exists but omits `model` |
| `does not have known AI Gateway context window metadata` | Unlisted gateway model id without `modelContextWindowTokens` override |
| `to provide a valid AI SDK language model` | Provider instance missing `provider`, `modelId`, `doGenerate`, or `doStream`; or unsupported `specificationVersion` |
| `missing a "description" field` | Local subagent `agent.ts` without `description` |
| `Expected ... to match the public Eve shape` | Unknown key, wrong type, or `thresholdPercent` outside `0–1` |

Run `eve info` for discovery diagnostics and `eve build` to surface compile-time validation errors before deployment.

## Related pages

<CardGroup>
<Card title="Project layout" href="/project-layout">
Where `agent.ts` lives in the authored tree and what compiles into `.eve/` artifacts.
</Card>
<Card title="Default harness" href="/default-harness">
How compaction, built-in tools, and the agent loop consume `agent.ts` config.
</Card>
<Card title="Subagents and schedules" href="/subagents-and-schedules">
Per-subagent `defineAgent` overrides, required `description`, and task-mode `outputSchema`.
</Card>
<Card title="Auth and deployment" href="/auth-and-deployment">
Model credentials, `eve build` / `eve deploy`, and hosted `externalDependencies` tracing.
</Card>
<Card title="TypeScript API" href="/typescript-api">
Exported `defineAgent` types, `AgentDefinition`, and related `define*` helpers.
</Card>
</CardGroup>