Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

feat(eve): agents - add reasoning support (#290)

Andrew Barba89969b2b2d8b
diff --git a/.changeset/fuzzy-lions-reason.md b/.changeset/fuzzy-lions-reason.md
new file mode 100644
index 000000000..5ba0e7623
--- /dev/null
+++ b/.changeset/fuzzy-lions-reason.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add a top-level `defineAgent({ reasoning })` option that forwards provider-agnostic reasoning effort to the agent's turn model calls.
diff --git a/docs/agent-config.md b/docs/agent-config.md
index 182d98072..e6752d6f8 100644
--- a/docs/agent-config.md
+++ b/docs/agent-config.md
@@ -1,6 +1,6 @@
---
title: "agent.ts"
-description: "Set the agent's runtime config in agent.ts with defineAgent, including the model and compaction."
+description: "Set the agent's runtime config in agent.ts with defineAgent, including the model, reasoning effort, and compaction."
---
An agent's `agent.ts` calls `defineAgent` (from `eve`) to set its runtime config.
@@ -39,6 +39,23 @@ export default defineAgent({
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](https://vercel.com/ai-gateway/models) for gateway-routed models, and review the provider's terms when you configure a direct `LanguageModel`.
+## Reasoning effort
+
+Set `reasoning` to control the model's reasoning effort through AI SDK's
+provider-agnostic option:
+
+```ts title="agent/agent.ts"
+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.
+
## Compaction
Compaction summarizes older turns as you approach the context window. It's on by default, so you only tune when it kicks in. Lower `thresholdPercent` to compact sooner:
@@ -85,12 +102,13 @@ external in hosted output, list it in `build.externalDependencies`.
`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API](./reference/typescript-api).
-| Field | Type | Default | Description |
-| -------------- | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call. |
-| `experimental` | `{ codeMode?: boolean; workflow?: { world?: string } }` | flags unset | Opt-in flags that can change or disappear in any release. Treat them as unstable. `codeMode` routes executable tools through a sandboxed code-execution wrapper, where the model writes JavaScript that calls the tools inside the [sandbox](./sandbox). `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
-| `outputSchema` | Standard Schema or a JSON Schema object | none | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema. |
-| `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. |
+| 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. |
+| `experimental` | `{ codeMode?: boolean; workflow?: { world?: string } }` | flags unset | Opt-in flags that can change or disappear in any release. Treat them as unstable. `codeMode` routes executable tools through a sandboxed code-execution wrapper, where the model writes JavaScript that calls the tools inside the [sandbox](./sandbox). `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |
+| `outputSchema` | Standard Schema or a JSON Schema object | none | Structured return type for task-mode runs (a subagent, schedule, or remote job). Interactive conversation turns ignore it unless the client supplies a per-message schema. |
+| `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. |
`codeMode` is experimental and may change or be removed.
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index 0955318f5..e52853b75 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -51,7 +51,7 @@ export default defineTool({
| `defineEvalConfig` | `eve/evals` | `evals/evals.config.ts` | [Evals](../evals/overview) |
| `useEveAgent` | `eve/react`, `eve/vue`, `eve/svelte` | frontend | [Frontend](../guides/frontend/overview) |
-A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWorkflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval predicates `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
+A few non-`define*` helpers round out the set: `disableTool` and `ExperimentalWorkflow` from `eve/tools` (see [Default harness](../concepts/default-harness)), the route verbs `GET`/`POST`/`PUT`/`PATCH`/`DELETE`/`WS` from `eve/channels`, the approval predicates `always`/`once`/`never` from `eve/tools/approval`, and the channel auth helpers `localDev`/`vercelOidc`/`placeholderAuth` from `eve/channels/auth`. To wrap a built-in tool, import its default value from `eve/tools/defaults` (`bash`, `readFile`, `writeFile`, `glob`, `grep`, `webFetch`, `webSearch`, `todo`, `loadSkill`). `AgentReasoningDefinition` is exported from `eve` for the top-level `defineAgent({ reasoning })` setting. `AgentWorkflowDefinition` and `AgentWorkflowWorldDefinition` are exported from `eve` for the `defineAgent({ experimental: { workflow } })` config shape.
## Runtime context (`ctx`)
diff --git a/e2e/fixtures/agent-basic-runtime/agent/agent.ts b/e2e/fixtures/agent-basic-runtime/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-basic-runtime/agent/agent.ts
+++ b/e2e/fixtures/agent-basic-runtime/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-channels/agent/agent.ts b/e2e/fixtures/agent-channels/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-channels/agent/agent.ts
+++ b/e2e/fixtures/agent-channels/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-openapi-swagger/agent/agent.ts b/e2e/fixtures/agent-openapi-swagger/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-openapi-swagger/agent/agent.ts
+++ b/e2e/fixtures/agent-openapi-swagger/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-schedules/agent/agent.ts b/e2e/fixtures/agent-schedules/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-schedules/agent/agent.ts
+++ b/e2e/fixtures/agent-schedules/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-skills/agent/agent.ts b/e2e/fixtures/agent-skills/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-skills/agent/agent.ts
+++ b/e2e/fixtures/agent-skills/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-subagents-hitl/agent/agent.ts b/e2e/fixtures/agent-subagents-hitl/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-subagents-hitl/agent/agent.ts
+++ b/e2e/fixtures/agent-subagents-hitl/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-subagents-hitl/agent/subagents/stock-price/agent.ts b/e2e/fixtures/agent-subagents-hitl/agent/subagents/stock-price/agent.ts
index 9a1de8136..257924838 100644
--- a/e2e/fixtures/agent-subagents-hitl/agent/subagents/stock-price/agent.ts
+++ b/e2e/fixtures/agent-subagents-hitl/agent/subagents/stock-price/agent.ts
@@ -4,4 +4,5 @@ export default defineAgent({
description:
'Look up the current stock price for a given ticker symbol. Pass the ticker symbol you want to look up in the message (e.g. "AAPL", "GOOG", or "TSLA").',
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-subagents/agent/agent.ts b/e2e/fixtures/agent-subagents/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-subagents/agent/agent.ts
+++ b/e2e/fixtures/agent-subagents/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-subagents/agent/subagents/echo-marker/agent.ts b/e2e/fixtures/agent-subagents/agent/subagents/echo-marker/agent.ts
index dd4bd8d97..86c6266ef 100644
--- a/e2e/fixtures/agent-subagents/agent/subagents/echo-marker/agent.ts
+++ b/e2e/fixtures/agent-subagents/agent/subagents/echo-marker/agent.ts
@@ -13,4 +13,5 @@ export default defineAgent({
description:
"Smoke-test echo subagent. Call this whenever the user mentions the phrase 'echo marker subagent'. Pass any short text as the input; the subagent replies with a fixed marker token.",
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-tools-hitl/agent/agent.ts b/e2e/fixtures/agent-tools-hitl/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-tools-hitl/agent/agent.ts
+++ b/e2e/fixtures/agent-tools-hitl/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-tools-sandbox/agent/agent.ts b/e2e/fixtures/agent-tools-sandbox/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-tools-sandbox/agent/agent.ts
+++ b/e2e/fixtures/agent-tools-sandbox/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/e2e/fixtures/agent-tools/agent/agent.ts b/e2e/fixtures/agent-tools/agent/agent.ts
index 670a9ede4..bea278ea3 100644
--- a/e2e/fixtures/agent-tools/agent/agent.ts
+++ b/e2e/fixtures/agent-tools/agent/agent.ts
@@ -2,4 +2,5 @@ import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
+ reasoning: "high",
});
diff --git a/packages/eve/src/compiler/manifest.test.ts b/packages/eve/src/compiler/manifest.test.ts
index 0874d815f..2e96919f9 100644
--- a/packages/eve/src/compiler/manifest.test.ts
+++ b/packages/eve/src/compiler/manifest.test.ts
@@ -4,6 +4,22 @@ import { compiledAgentManifestSchema, createCompiledAgentManifest } from "#compi
import { classifyModelRouting } from "#internal/classify-model-routing.js";
describe("compiledAgentManifestSchema", () => {
+ it("preserves reasoning configuration", () => {
+ const manifest = createCompiledAgentManifest({
+ agentRoot: "/app/agent",
+ appRoot: "/app",
+ config: {
+ model: { id: "openai/gpt-5.5", routing: classifyModelRouting("openai/gpt-5.5") },
+ name: "app",
+ reasoning: "high",
+ },
+ });
+
+ const parsed = compiledAgentManifestSchema.parse(manifest);
+
+ expect(parsed.config.reasoning).toBe("high");
+ });
+
it("accepts compiled workflow world configuration", () => {
const manifest = createCompiledAgentManifest({
agentRoot: "/app/agent",
diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.ts
index 134198f6e..7baf3f717 100644
--- a/packages/eve/src/compiler/manifest.ts
+++ b/packages/eve/src/compiler/manifest.ts
@@ -348,6 +348,9 @@ const compiledAgentConfigSchema: z.ZodType<CompiledAgentDefinition> = z
model: compiledRuntimeModelReferenceSchema,
name: z.string(),
outputSchema: jsonObjectSchema.optional(),
+ reasoning: z
+ .enum(["provider-default", "none", "minimal", "low", "medium", "high", "xhigh"])
+ .optional(),
source: moduleSourceRefSchema.optional(),
})
.strict();
@@ -691,6 +694,7 @@ export function createCompiledAgentNodeManifest(input: {
model: cloneCompiledRuntimeModelReference(input.config.model),
name: input.config.name,
outputSchema: input.config.outputSchema,
+ reasoning: input.config.reasoning,
source:
input.config.source === undefined
? undefined
diff --git a/packages/eve/src/compiler/normalize-agent-config.ts b/packages/eve/src/compiler/normalize-agent-config.ts
index f3b1c1656..3efa9cb87 100644
--- a/packages/eve/src/compiler/normalize-agent-config.ts
+++ b/packages/eve/src/compiler/normalize-agent-config.ts
@@ -69,6 +69,7 @@ export async function compileAgentConfig(
model: CompiledRuntimeModelReference;
name: string;
outputSchema?: JsonObject;
+ reasoning?: CompiledAgentDefinition["reasoning"];
source?: ModuleSourceRef;
} = {
compaction,
@@ -98,6 +99,10 @@ export async function compileAgentConfig(
compiledConfig.outputSchema = normalizeJsonSchemaDefinition(definition.outputSchema, "output");
}
+ if (definition.reasoning !== undefined) {
+ compiledConfig.reasoning = definition.reasoning;
+ }
+
if (configModule !== undefined) {
compiledConfig.source = {
exportName: configModule.exportName,
diff --git a/packages/eve/src/execution/session.test.ts b/packages/eve/src/execution/session.test.ts
index ecb3b62a9..bcfa6cb3c 100644
--- a/packages/eve/src/execution/session.test.ts
+++ b/packages/eve/src/execution/session.test.ts
@@ -75,11 +75,12 @@ describe("createSession", () => {
continuationToken: "root-token",
outputSchema,
sessionId: "sess-root",
- turnAgent: createTestTurnAgent({ outputSchema }),
+ turnAgent: createTestTurnAgent({ outputSchema, reasoning: "high" }),
});
expect(session.agent.compactionModelReference).toEqual({ id: "summary-model" });
expect(session.agent.modelReference).toEqual({ id: "test-model" });
+ expect(session.agent.reasoning).toBe("high");
expect(session.outputSchema).toEqual(outputSchema);
expect(session.agent.system).toBe("You are a helpful assistant.\n\nBe concise.");
expect(session.agent.tools).toEqual([
@@ -207,6 +208,23 @@ describe("createSession", () => {
expect(durable.outputSchema).toEqual(runOutputSchema);
expect(hydrated.outputSchema).toEqual(runOutputSchema);
});
+
+ it("restores current reasoning configuration when hydrating a durable session", () => {
+ const session = createSession({
+ continuationToken: "root-token",
+ sessionId: "sess-root",
+ turnAgent: createTestTurnAgent({ reasoning: "low" }),
+ });
+
+ const durable = projectToDurableSession(session);
+ const hydrated = hydrateDurableSession({
+ durable,
+ turnAgent: createTestTurnAgent({ reasoning: "high" }),
+ });
+
+ expect(durable.agent).toEqual({ system: session.agent.system });
+ expect(hydrated.agent.reasoning).toBe("high");
+ });
});
describe("mintSubagentContinuationToken", () => {
diff --git a/packages/eve/src/execution/session.ts b/packages/eve/src/execution/session.ts
index 4ca70a42b..4234d3379 100644
--- a/packages/eve/src/execution/session.ts
+++ b/packages/eve/src/execution/session.ts
@@ -66,6 +66,7 @@ export function createSession(input: CreateSessionInput): HarnessSession {
agent: {
compactionModelReference: turnAgent.compactionModel,
modelReference: turnAgent.model,
+ reasoning: turnAgent.reasoning,
system: turnAgent.instructions.join("\n\n"),
tools,
},
@@ -105,6 +106,7 @@ export function refreshSessionFromTurnAgent(input: {
agent: {
compactionModelReference: input.turnAgent.compactionModel,
modelReference: input.turnAgent.model,
+ reasoning: input.turnAgent.reasoning,
system: input.turnAgent.instructions.join("\n\n"),
tools: createSessionToolDefinitions(input.turnAgent),
},
@@ -200,6 +202,7 @@ export function hydrateDurableSession(input: {
agent: {
compactionModelReference: turnAgent.compactionModel,
modelReference: turnAgent.model,
+ reasoning: turnAgent.reasoning,
system: durable.agent.system,
tools,
},
diff --git a/packages/eve/src/harness/tool-loop.test.ts b/packages/eve/src/harness/tool-loop.test.ts
index 787f98edd..fd4fc416f 100644
--- a/packages/eve/src/harness/tool-loop.test.ts
+++ b/packages/eve/src/harness/tool-loop.test.ts
@@ -586,6 +586,30 @@ describe("createToolLoopHarness", () => {
expect(agentCall!.tools).not.toHaveProperty("code_mode");
});
+ it("forwards the agent reasoning effort to the model call", async () => {
+ setupMockAgent({
+ finishReason: "stop",
+ response: { messages: [{ content: "Hello!", role: "assistant" }] },
+ text: "Hello!",
+ toolCalls: [],
+ toolResults: [],
+ });
+
+ const runStep = createToolLoopHarness(createTestConfig());
+ const session = createTestSession({
+ agent: {
+ modelReference: { id: "test-model" },
+ reasoning: "high",
+ system: "You are a test assistant.",
+ tools: [],
+ },
+ });
+
+ await runStep(session, { message: "Think carefully" });
+
+ expect(vi.mocked(ToolLoopAgent).mock.calls[0]?.[0]).toMatchObject({ reasoning: "high" });
+ });
+
it("preserves approval gates on step-scoped dynamic tools", async () => {
setupMockAgent({
finishReason: "stop",
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index 2278a143c..a3a073733 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -690,6 +690,7 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
},
onStepFinish: hooks.onStepFinish,
prepareStep: hooks.prepareStep,
+ reasoning: session.agent.reasoning,
runtimeContext: telemetryRuntimeContext,
stopWhen: isStepCount(1),
telemetry: enrichTelemetry(telemetryConfig, agentName, telemetryRuntimeContext),
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index 651036872..be1b5e6f8 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -9,6 +9,7 @@ import type { InputResponse } from "#runtime/input/types.js";
import type { SandboxState } from "#sandbox/state.js";
import type { JsonObject } from "#shared/json.js";
import type { InternalToolDefinition } from "#shared/tool-definition.js";
+import type { AgentReasoningDefinition } from "#shared/agent-definition.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
/**
@@ -43,6 +44,7 @@ export interface SessionAgent {
*/
readonly compactionModelReference?: RuntimeModelReference;
readonly modelReference: RuntimeModelReference;
+ readonly reasoning?: AgentReasoningDefinition;
readonly system: string;
readonly tools: readonly SessionToolDefinition[];
}
diff --git a/packages/eve/src/internal/authored-definition/core.test.ts b/packages/eve/src/internal/authored-definition/core.test.ts
index c5ea611ad..52e020870 100644
--- a/packages/eve/src/internal/authored-definition/core.test.ts
+++ b/packages/eve/src/internal/authored-definition/core.test.ts
@@ -5,6 +5,30 @@ import { normalizeAgentDefinition } from "#internal/authored-definition/core.js"
const FAILURE_MESSAGE = "Expected the agent config to match the public eve shape.";
describe("normalizeAgentDefinition", () => {
+ it("accepts provider-agnostic reasoning effort", () => {
+ const definition = normalizeAgentDefinition(
+ {
+ model: "openai/gpt-5.5",
+ reasoning: "high",
+ },
+ FAILURE_MESSAGE,
+ );
+
+ expect(definition.reasoning).toBe("high");
+ });
+
+ it("rejects unsupported reasoning effort", () => {
+ expect(() =>
+ normalizeAgentDefinition(
+ {
+ model: "openai/gpt-5.5",
+ reasoning: "maximum",
+ },
+ FAILURE_MESSAGE,
+ ),
+ ).toThrow(FAILURE_MESSAGE);
+ });
+
it("accepts a workflow world package name", () => {
const definition = normalizeAgentDefinition(
{
diff --git a/packages/eve/src/internal/authored-definition/core.ts b/packages/eve/src/internal/authored-definition/core.ts
index 062d25526..951a9dc7b 100644
--- a/packages/eve/src/internal/authored-definition/core.ts
+++ b/packages/eve/src/internal/authored-definition/core.ts
@@ -46,6 +46,7 @@ export function normalizeAgentDefinition(
"modelContextWindowTokens",
"modelOptions",
"outputSchema",
+ "reasoning",
],
message,
);
@@ -88,9 +89,33 @@ export function normalizeAgentDefinition(
definition.outputSchema = record.outputSchema as NormalizedAgentDefinition["outputSchema"];
}
+ if (record.reasoning !== undefined) {
+ definition.reasoning = normalizeAgentReasoningDefinition(record.reasoning, message);
+ }
+
return definition as Readonly<NormalizedAgentDefinition>;
}
+function normalizeAgentReasoningDefinition(
+ value: unknown,
+ message: string,
+): NonNullable<NormalizedAgentDefinition["reasoning"]> {
+ const reasoning = expectString(value, message);
+
+ switch (reasoning) {
+ case "provider-default":
+ case "none":
+ case "minimal":
+ case "low":
+ case "medium":
+ case "high":
+ case "xhigh":
+ return reasoning;
+ default:
+ throw new Error(message);
+ }
+}
+
function expectPositiveInteger(value: unknown, message: string): number {
if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
throw new Error(message);
diff --git a/packages/eve/src/public/definitions/agent.ts b/packages/eve/src/public/definitions/agent.ts
index 525bb7ab8..49c0b5d1b 100644
--- a/packages/eve/src/public/definitions/agent.ts
+++ b/packages/eve/src/public/definitions/agent.ts
@@ -3,6 +3,7 @@ import type { ExactDefinition } from "#public/definitions/exact.js";
export type {
AgentModelOptionsDefinition,
+ AgentReasoningDefinition,
AgentBuildDefinition,
AgentExperimentalDefinition,
AgentWorkflowDefinition,
diff --git a/packages/eve/src/public/index.ts b/packages/eve/src/public/index.ts
index 30557a12c..d86813242 100644
--- a/packages/eve/src/public/index.ts
+++ b/packages/eve/src/public/index.ts
@@ -8,6 +8,7 @@ export {
type AgentExperimentalDefinition,
type AgentModelDefinition,
type AgentModelOptionsDefinition,
+ type AgentReasoningDefinition,
type AgentWorkflowDefinition,
type AgentWorkflowWorldDefinition,
defineAgent,
diff --git a/packages/eve/src/runtime/agent/bootstrap.ts b/packages/eve/src/runtime/agent/bootstrap.ts
index 55709c9e0..23939bd5e 100644
--- a/packages/eve/src/runtime/agent/bootstrap.ts
+++ b/packages/eve/src/runtime/agent/bootstrap.ts
@@ -30,6 +30,7 @@ export interface RuntimeTurnAgent {
readonly model: RuntimeModelReference;
readonly nodeId?: string;
readonly outputSchema?: ResolvedAgent["config"]["outputSchema"];
+ readonly reasoning?: ResolvedAgent["config"]["reasoning"];
readonly tools: readonly PreparedRuntimeTool[];
readonly workspaceSpec: WorkspaceRuntimeSpec;
}
@@ -63,6 +64,7 @@ export function createResolvedRuntimeTurnAgent(input: {
model: agent.config.model,
nodeId: input.nodeId,
outputSchema: agent.config.outputSchema,
+ reasoning: agent.config.reasoning,
tools: [...input.tools],
workspaceSpec: agent.workspaceSpec,
};
diff --git a/packages/eve/src/runtime/resolve-agent.ts b/packages/eve/src/runtime/resolve-agent.ts
index 9182b40cb..35794f166 100644
--- a/packages/eve/src/runtime/resolve-agent.ts
+++ b/packages/eve/src/runtime/resolve-agent.ts
@@ -151,6 +151,7 @@ function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): Resolve
model: ResolvedAgent["config"]["model"];
name: string;
outputSchema?: ResolvedAgent["config"]["outputSchema"];
+ reasoning?: ResolvedAgent["config"]["reasoning"];
source?: ResolvedAgent["config"]["source"];
} = {
model:
@@ -216,6 +217,10 @@ function createResolvedAgentConfig(manifest: CompiledAgentNodeManifest): Resolve
config.outputSchema = manifest.config.outputSchema;
}
+ if (manifest.config.reasoning !== undefined) {
+ config.reasoning = manifest.config.reasoning;
+ }
+
if (manifest.config.source !== undefined) {
config.source = createResolvedModuleSourceRef(manifest.config.source);
}
diff --git a/packages/eve/src/shared/agent-definition.ts b/packages/eve/src/shared/agent-definition.ts
index d98891e23..335030445 100644
--- a/packages/eve/src/shared/agent-definition.ts
+++ b/packages/eve/src/shared/agent-definition.ts
@@ -1,4 +1,4 @@
-import type { LanguageModel } from "ai";
+import type { CallSettings, LanguageModel } from "ai";
import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
import type { JsonObject } from "#shared/json.js";
import type { ModuleSourceRef } from "#shared/source-ref.js";
@@ -11,6 +11,11 @@ export interface AgentModelOptionsDefinition {
readonly providerOptions?: Record<string, JsonObject>;
}
+/**
+ * Provider-agnostic reasoning effort forwarded to the AI SDK model call.
+ */
+export type AgentReasoningDefinition = NonNullable<CallSettings["reasoning"]>;
+
/**
* How an agent's model is reached at runtime, decided at compile time from the
* authored model value.
@@ -167,6 +172,7 @@ export type InternalAgentDefinition = {
experimental?: AgentExperimentalDefinition;
model: InternalAgentModelDefinition;
outputSchema?: JsonObject;
+ reasoning?: AgentReasoningDefinition;
source?: ModuleSourceRef;
};
@@ -206,6 +212,11 @@ export type PublicAgentDefinition = {
*/
readonly modelContextWindowTokens?: number;
readonly modelOptions?: AgentModelOptionsDefinition;
+ /**
+ * Provider-agnostic reasoning effort for the agent's turn model calls.
+ * Support for individual levels depends on the selected model and provider.
+ */
+ readonly reasoning?: AgentReasoningDefinition;
/**
* Optional structured return type used when this agent runs in task mode
* (for example as a subagent, schedule, or remote job). Interactive