feat(agents): add AgentOverrides and FlowAgentOverrides types

.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`

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>;
 

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()`.
  *

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()`.
  *

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,