From 395892d3d77a6a2c4e0ac16415d7ed1c67df783c Mon Sep 17 00:00:00 2001
From: Zac Rosenbauer <zacrosenbauer@gmail.com>
Date: Thu, 19 Mar 2026 22:56:28 -0400
Subject: [PATCH 1/2] feat(agents): add AgentOverrides and FlowAgentOverrides
 types for evolve

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .changeset/agent-overrides-type.md            |  5 +++
 packages/agents/src/core/agents/evolve.ts     | 13 ++-----
 packages/agents/src/core/agents/flow/types.ts | 27 +++++++++++++
 packages/agents/src/core/agents/types.ts      | 39 +++++++++++++++++++
 packages/agents/src/index.ts                  |  2 +
 5 files changed, 77 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/agent-overrides-type.md

diff --git a/.changeset/agent-overrides-type.md b/.changeset/agent-overrides-type.md
new file mode 100644
index 0000000..90b6009
--- /dev/null
+++ b/.changeset/agent-overrides-type.md
@@ -0,0 +1,5 @@
+---
+"@funkai/agents": minor
+---
+
+Add `AgentOverrides` and `FlowAgentOverrides` dedicated types for `evolve()` overrides, exported from `@funkai/agents`
diff --git a/packages/agents/src/core/agents/evolve.ts b/packages/agents/src/core/agents/evolve.ts
index 4646115..2dbf123 100644
--- a/packages/agents/src/core/agents/evolve.ts
+++ b/packages/agents/src/core/agents/evolve.ts
@@ -9,9 +9,10 @@ import type {
   FlowAgentConfigWithOutput,
   FlowAgentConfigWithoutOutput,
   FlowAgentHandler,
+  FlowAgentOverrides,
   FlowSubAgents,
 } from "@/core/agents/flow/types.js";
-import type { Agent, AgentConfig, Resolver, SubAgents } from "@/core/agents/types.js";
+import type { Agent, AgentConfig, AgentOverrides, Resolver, SubAgents } from "@/core/agents/types.js";
 import type { Tool } from "@/core/tool.js";
 import type { Model } from "@/core/types.js";
 import { getAgentConfig, getFlowAgentConfig, isAgent, isFlowAgent } from "@/lib/runnable.js";
@@ -83,11 +84,7 @@ export function evolve<
   TModel extends Resolver<TInput, Model>,
 >(
   base: Agent<TInput, TOutput, TTools, TSubAgents, TModel>,
-  overrides:
-    | Partial<AgentConfig<TInput, TOutput, TTools, TSubAgents, TModel>>
-    | ((
-        config: AgentConfig<TInput, TOutput, TTools, TSubAgents, TModel>,
-      ) => Partial<AgentConfig<TInput, TOutput, TTools, TSubAgents, TModel>>),
+  overrides: AgentOverrides<TInput, TOutput, TTools, TSubAgents, TModel>,
 ): Agent<TInput, TOutput, TTools, TSubAgents, TModel>;
 
 /**
@@ -115,9 +112,7 @@ export function evolve<
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- widened to accept both FlowAgent output variants
 export function evolve<TInput, TOutput = any>(
   base: FlowAgent<TInput, TOutput>,
-  overrides:
-    | Partial<FlowAgentConfig<TInput, TOutput>>
-    | ((config: FlowAgentConfig<TInput, TOutput>) => Partial<FlowAgentConfig<TInput, TOutput>>),
+  overrides: FlowAgentOverrides<TInput, TOutput>,
   handler?: FlowAgentHandler<TInput, TOutput>,
 ): FlowAgent<TInput, TOutput>;
 
diff --git a/packages/agents/src/core/agents/flow/types.ts b/packages/agents/src/core/agents/flow/types.ts
index bd18b34..3a8146e 100644
--- a/packages/agents/src/core/agents/flow/types.ts
+++ b/packages/agents/src/core/agents/flow/types.ts
@@ -282,6 +282,33 @@ export type FlowAgentHandler<TInput, TOutput> = (
   params: FlowAgentParams<TInput>,
 ) => Promise<TOutput>;
 
+/**
+ * Overrides for evolving a flow agent via `evolve()`.
+ *
+ * Accepts a partial config object or a mapper function that receives the
+ * current config and returns partial overrides. Scalars replace the base;
+ * record fields (agents) are shallow-merged.
+ *
+ * @typeParam TInput - Flow agent input type.
+ * @typeParam TOutput - Flow agent output type.
+ *
+ * @example
+ * ```typescript
+ * // Static overrides
+ * const overrides: FlowAgentOverrides<Input, Output> = {
+ *   logger: pinoLogger,
+ * }
+ *
+ * // Mapper function
+ * const overrides: FlowAgentOverrides<Input, Output> = (config) => ({
+ *   name: `${config.name}-local`,
+ * })
+ * ```
+ */
+export type FlowAgentOverrides<TInput, TOutput = void> =
+  | Partial<FlowAgentConfig<TInput, TOutput>>
+  | ((config: FlowAgentConfig<TInput, TOutput>) => Partial<FlowAgentConfig<TInput, TOutput>>);
+
 /**
  * A created flow agent — exposes `.generate()`, `.stream()`, and `.fn()`.
  *
diff --git a/packages/agents/src/core/agents/types.ts b/packages/agents/src/core/agents/types.ts
index 90e1986..5c0e003 100644
--- a/packages/agents/src/core/agents/types.ts
+++ b/packages/agents/src/core/agents/types.ts
@@ -660,6 +660,45 @@ export interface AgentConfig<
   onStepFinish?: (event: StepFinishEvent) => void | Promise<void>;
 }
 
+/**
+ * Overrides for evolving an agent via `evolve()`.
+ *
+ * Accepts a partial config object or a mapper function that receives the
+ * current config and returns partial overrides. Scalars replace the base;
+ * record fields (tools, agents) are shallow-merged.
+ *
+ * @typeParam TInput - Agent input type.
+ * @typeParam TOutput - Agent output type.
+ * @typeParam TTools - Record of tools.
+ * @typeParam TSubAgents - Record of subagents.
+ * @typeParam TModel - Model resolver type.
+ *
+ * @example
+ * ```typescript
+ * // Static overrides
+ * const overrides: AgentOverrides<string, string, Tools, SubAgents, Model> = {
+ *   name: 'reviewer-local',
+ *   model: openai('gpt-4.1-mini'),
+ * }
+ *
+ * // Mapper function
+ * const overrides: AgentOverrides<string, string, Tools, SubAgents, Model> = (config) => ({
+ *   name: `${config.name}-local`,
+ * })
+ * ```
+ */
+export type AgentOverrides<
+  TInput,
+  TOutput,
+  TTools extends Record<string, Tool>,
+  TSubAgents extends SubAgents,
+  TModel extends Resolver<TInput, Model> = Resolver<TInput, Model>,
+> =
+  | Partial<AgentConfig<TInput, TOutput, TTools, TSubAgents, TModel>>
+  | ((
+      config: AgentConfig<TInput, TOutput, TTools, TSubAgents, TModel>,
+    ) => Partial<AgentConfig<TInput, TOutput, TTools, TSubAgents, TModel>>);
+
 /**
  * A created agent — exposes `.generate()`, `.stream()`, and `.fn()`.
  *
diff --git a/packages/agents/src/index.ts b/packages/agents/src/index.ts
index 08a2669..11e598a 100644
--- a/packages/agents/src/index.ts
+++ b/packages/agents/src/index.ts
@@ -28,6 +28,7 @@ export type {
   Message,
   Agent,
   AgentConfig,
+  AgentOverrides,
   BaseGenerateParams,
   GenerateParams,
   GenerateResult,
@@ -38,6 +39,7 @@ export type {
   FlowAgent,
   FlowAgentConfig,
   FlowAgentHandler,
+  FlowAgentOverrides,
   FlowAgentParams,
   FlowAgentGenerateResult,
   FlowSubAgents,

From 7e242f32f55eb94eb0f05201cc87429d0f2a35ef Mon Sep 17 00:00:00 2001
From: Zac Rosenbauer <zacrosenbauer@gmail.com>
Date: Thu, 19 Mar 2026 23:09:12 -0400
Subject: [PATCH 2/2] style(agents): fix formatting in evolve.ts

Co-Authored-By: Claude <noreply@anthropic.com>
---
 packages/agents/src/core/agents/evolve.ts | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/agents/src/core/agents/evolve.ts b/packages/agents/src/core/agents/evolve.ts
index 2dbf123..e9b8829 100644
--- a/packages/agents/src/core/agents/evolve.ts
+++ b/packages/agents/src/core/agents/evolve.ts
@@ -12,7 +12,13 @@ import type {
   FlowAgentOverrides,
   FlowSubAgents,
 } from "@/core/agents/flow/types.js";
-import type { Agent, AgentConfig, AgentOverrides, Resolver, SubAgents } from "@/core/agents/types.js";
+import type {
+  Agent,
+  AgentConfig,
+  AgentOverrides,
+  Resolver,
+  SubAgents,
+} from "@/core/agents/types.js";
 import type { Tool } from "@/core/tool.js";
 import type { Model } from "@/core/types.js";
 import { getAgentConfig, getFlowAgentConfig, isAgent, isFlowAgent } from "@/lib/runnable.js";