feat(agents): add TModel generic for discriminated model types in evolve#43
Merged
zrosenbauer merged 5 commits intomainfrom Mar 20, 2026
Merged
feat(agents): add TModel generic for discriminated model types in evolve#43zrosenbauer merged 5 commits intomainfrom
zrosenbauer merged 5 commits intomainfrom
Conversation
Add a 5th generic parameter `TModel` to `AgentConfig` and `Agent` that tracks whether the model was set as a static `Model` or a dynamic `Resolver<TInput, Model>`. This flows through `evolve()` so the mapper callback receives the correctly narrowed type — enabling direct access to `.modelId` without unnecessary `isFunction()` narrowing. Co-Authored-By: Claude <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
🦋 Changeset detectedLatest commit: 23481e7 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
📝 WalkthroughWalkthroughAdds a new generic parameter TModel to AgentConfig and Agent and threads it through agent creation, evolve(), utilities, flow types, runnable guard, and examples so config.model is typed as the agent's specific resolver type. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📝 Coding Plan
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
packages/agents/src/core/agents/types.ts (1)
498-504:⚠️ Potential issue | 🟡 MinorDocument the new exported
TModeltype parameter.Line 503 and Line 680 add a public generic but the corresponding JSDoc blocks don’t describe
TModel. Add@typeParam TModelto both exported API docs to keep generated/public typing docs accurate.As per coding guidelines: "JSDoc on all exports with
@param,@returns,@example" and CLAUDE.md: "any exported types/functions added/modified should have JSDoc."Also applies to: 675-681
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/agents/src/core/agents/types.ts` around lines 498 - 504, Add a JSDoc `@typeParam` entry describing the new generic TModel (which is Resolver<TInput, Model>) to the exported API docs that document AgentConfig and the other exported type around lines 675-681; update the JSDoc blocks for the exported AgentConfig<TInput, TOutput, TTools, TSubAgents, TModel> and the other affected exported type to include a concise `@typeParam` TModel explaining it represents the model resolver type (Resolver<TInput, Model>) so generated docs and typing comments remain accurate.packages/agents/src/core/agents/base/agent.ts (1)
82-92:⚠️ Potential issue | 🟡 Minor
agent()export docs are missing@typeParam TModel.Line 89 introduces a new public generic parameter, but the JSDoc block does not describe it. Please add
@typeParam TModelto keep exported API docs complete.As per coding guidelines: "JSDoc on all exports with
@param,@returns,@example" and CLAUDE.md: "any exported types/functions added/modified should have JSDoc."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/agents/src/core/agents/base/agent.ts` around lines 82 - 92, The exported agent<TInput,...,TModel> function's JSDoc is missing a `@typeParam` for the new generic TModel; update the docblock for the exported function agent to include a `@typeParam` TModel describing that TModel is the Resolver<TInput, Model> type (e.g., "TModel - resolver type used to resolve models for given TInput"), and ensure the top-level JSDoc for agent includes `@param` entries and `@returns` per guidelines so the public API docs include the new generic.packages/agents/src/core/agents/evolve.ts (1)
78-83:⚠️ Potential issue | 🟡 MinorAdd
@typeParam TModelto the exportedevolve()JSDoc.The export now includes a new generic parameter (Line 83) that is not documented in the type-param list.
As per coding guidelines: "JSDoc on all exports with
@param,@returns,@example" and CLAUDE.md: "any exported types/functions added/modified should have JSDoc."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/agents/src/core/agents/evolve.ts` around lines 78 - 83, The JSDoc for the exported function evolve is missing documentation for the newly added generic TModel; update the JSDoc block for evolve to include an `@typeParam` TModel description (e.g., "TModel - resolver type that maps TInput to Model") and briefly explain its role with references to Resolver and Model so the signature: evolve<TInput, TOutput, TTools, TSubAgents, TModel extends Resolver<TInput, Model>> is fully documented; ensure the JSDoc contains `@param/`@returns as required by project guidelines.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/agents/src/core/agents/evolve.ts`:
- Around line 86-91: The evolve() overload is type-unsafe because the overrides
union uses Partial<AgentConfig<TInput, TOutput, TTools, TSubAgents>> without
preserving the agent's TModel, letting callers supply a different model shape
while evolve still returns Agent<..., TModel>; fix by changing both overload
variants so the Partial references include TModel (i.e.
Partial<AgentConfig<TInput, TOutput, TTools, TSubAgents, TModel>> and the
function variant returns Partial<AgentConfig<..., TModel>>), ensuring evolve's
parameter type preserves the original TModel and the returned Agent<TInput,
TOutput, TTools, TSubAgents, TModel> remains sound.
---
Outside diff comments:
In `@packages/agents/src/core/agents/base/agent.ts`:
- Around line 82-92: The exported agent<TInput,...,TModel> function's JSDoc is
missing a `@typeParam` for the new generic TModel; update the docblock for the
exported function agent to include a `@typeParam` TModel describing that TModel is
the Resolver<TInput, Model> type (e.g., "TModel - resolver type used to resolve
models for given TInput"), and ensure the top-level JSDoc for agent includes
`@param` entries and `@returns` per guidelines so the public API docs include the
new generic.
In `@packages/agents/src/core/agents/evolve.ts`:
- Around line 78-83: The JSDoc for the exported function evolve is missing
documentation for the newly added generic TModel; update the JSDoc block for
evolve to include an `@typeParam` TModel description (e.g., "TModel - resolver
type that maps TInput to Model") and briefly explain its role with references to
Resolver and Model so the signature: evolve<TInput, TOutput, TTools, TSubAgents,
TModel extends Resolver<TInput, Model>> is fully documented; ensure the JSDoc
contains `@param/`@returns as required by project guidelines.
In `@packages/agents/src/core/agents/types.ts`:
- Around line 498-504: Add a JSDoc `@typeParam` entry describing the new generic
TModel (which is Resolver<TInput, Model>) to the exported API docs that document
AgentConfig and the other exported type around lines 675-681; update the JSDoc
blocks for the exported AgentConfig<TInput, TOutput, TTools, TSubAgents, TModel>
and the other affected exported type to include a concise `@typeParam` TModel
explaining it represents the model resolver type (Resolver<TInput, Model>) so
generated docs and typing comments remain accurate.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 9c139dc6-7a96-4c1f-a880-a9c1e972b182
📒 Files selected for processing (7)
.changeset/evolve-model-generic.mdpackages/agents/src/core/agents/base/agent.tspackages/agents/src/core/agents/base/utils.tspackages/agents/src/core/agents/evolve.tspackages/agents/src/core/agents/flow/types.tspackages/agents/src/core/agents/types.tspackages/agents/src/lib/runnable.ts
The new TModel generic causes TypeScript to infer LanguageModelV3 from @ai-sdk/provider in the return type. Without an explicit annotation, TS2742 fires because the example package doesn't directly depend on that module. Adding `Agent` return types resolves the portability error. Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@examples/realworld-cli/api/agents/analyzer.ts`:
- Line 35: Add an `@example` block to the exported function createAnalyzerAgent's
JSDoc showing typical usage (e.g., creating an analyzer with fsTools and a file
path, then calling analyzer.generate with a prompt and awaiting the result);
update the JSDoc immediately above the exported function createAnalyzerAgent to
include the code example fenced as JavaScript/TypeScript and ensure the existing
`@param` and `@returns` tags remain accurate.
In `@examples/realworld-cli/api/agents/scanner.ts`:
- Line 12: Add a JSDoc `@example` block to the exported createScannerAgent
function's existing JSDoc comment: include a short usage example showing
creating the scanner (e.g., const scanner = createScannerAgent(fsTools)),
calling generate with a prompt (e.g., const result = await scanner.generate({
prompt: "Find test files" })), and closing the code fence; keep the rest of the
JSDoc (`@param` and `@returns`) intact and ensure the example is wrapped in a proper
code fence and placed before the ending */.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 4e606bc2-fe17-457c-8e2a-fbc4919507bb
📒 Files selected for processing (2)
examples/realworld-cli/api/agents/analyzer.tsexamples/realworld-cli/api/agents/scanner.ts
…t error TModel was a phantom generic on Agent — structurally invisible to TypeScript, so evolve() could not infer concrete model types. Adds readonly model property to Agent interface and exposes config.model on the agent factory return value. Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
packages/agents/src/core/agents/types.ts (2)
483-497:⚠️ Potential issue | 🟡 MinorMissing
@typeParam TModelinAgentConfiginterface JSDoc.Same documentation gap as the
Agentinterface—add the new type parameter to the JSDoc block.📝 Proposed fix
* `@typeParam` TOutput - Agent output type (default: `string`). * `@typeParam` TTools - Record of tools available to this agent. * `@typeParam` TSubAgents - Record of subagents available to this agent. + * `@typeParam` TModel - Model resolver type (default: `Resolver<TInput, Model>`). */ export interface AgentConfig<🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/agents/src/core/agents/types.ts` around lines 483 - 497, Add the missing JSDoc `@typeParam` for the model type to the AgentConfig interface documentation: update the JSDoc block above the AgentConfig interface to include a new line documenting `@typeParam` TModel - describing the agent/model type (matching how Agent's JSDoc was updated) so the type parameters list includes TInput, TOutput, TTools, TSubAgents, and TModel and clarifies its purpose.
663-688:⚠️ Potential issue | 🟡 MinorMissing
@typeParam TModelinAgentinterface JSDoc.The interface JSDoc documents four type parameters but omits the newly added
TModel. Per coding guidelines, exported interfaces should have complete JSDoc.📝 Proposed fix
* `@typeParam` TOutput - Agent output type. * `@typeParam` TTools - Record of tools. * `@typeParam` TSubAgents - Record of subagents. + * `@typeParam` TModel - Model resolver type (default: `Resolver<TInput, Model>`). */ export interface Agent<🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/agents/src/core/agents/types.ts` around lines 663 - 688, Update the Agent interface JSDoc to include the missing `@typeParam` for TModel: add a line documenting TModel (e.g., "@typeParam TModel - Resolver type for the model used by the agent") so the comment block covers all generic parameters declared on the Agent interface (TInput, TOutput, TTools, TSubAgents, TModel) and references the Resolver/Model relationship described in the interface.packages/agents/src/core/agents/base/agent.ts (1)
36-56:⚠️ Potential issue | 🟡 MinorMissing
@typeParam TModelin JSDoc.The function's JSDoc documents
TInput,TOutput,TTools, andTSubAgentsbut omits the newly addedTModelgeneric. As per coding guidelines, exported functions should have complete JSDoc including all type parameters.📝 Proposed fix
* `@typeParam` TTools - Record of tools. * `@typeParam` TSubAgents - Record of subagents. + * `@typeParam` TModel - Model resolver type (default: `Resolver<TInput, Model>`). * `@param` config - Agent configuration including name, model, schemas,🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/agents/src/core/agents/base/agent.ts` around lines 36 - 56, Add the missing `@typeParam` TModel to the function JSDoc for the exported agent factory (the block describing the generic type parameters for the agent returned by createAgent / Agent type), e.g. add a line like "@typeParam TModel - Model type used by the agent (default: unspecified or specific model interface)" and mirror the style of the existing `@typeParam` entries (include default if applicable); ensure the new `@typeParam` appears with the other generics (TInput, TOutput, TTools, TSubAgents) in the top docblock so the JSDoc fully documents all generics.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@packages/agents/src/core/agents/base/agent.ts`:
- Around line 36-56: Add the missing `@typeParam` TModel to the function JSDoc for
the exported agent factory (the block describing the generic type parameters for
the agent returned by createAgent / Agent type), e.g. add a line like
"@typeParam TModel - Model type used by the agent (default: unspecified or
specific model interface)" and mirror the style of the existing `@typeParam`
entries (include default if applicable); ensure the new `@typeParam` appears with
the other generics (TInput, TOutput, TTools, TSubAgents) in the top docblock so
the JSDoc fully documents all generics.
In `@packages/agents/src/core/agents/types.ts`:
- Around line 483-497: Add the missing JSDoc `@typeParam` for the model type to
the AgentConfig interface documentation: update the JSDoc block above the
AgentConfig interface to include a new line documenting `@typeParam` TModel -
describing the agent/model type (matching how Agent's JSDoc was updated) so the
type parameters list includes TInput, TOutput, TTools, TSubAgents, and TModel
and clarifies its purpose.
- Around line 663-688: Update the Agent interface JSDoc to include the missing
`@typeParam` for TModel: add a line documenting TModel (e.g., "@typeParam TModel -
Resolver type for the model used by the agent") so the comment block covers all
generic parameters declared on the Agent interface (TInput, TOutput, TTools,
TSubAgents, TModel) and references the Resolver/Model relationship described in
the interface.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: f0ff8a3e-e16c-4581-8b89-f1b932aae066
📒 Files selected for processing (2)
packages/agents/src/core/agents/base/agent.tspackages/agents/src/core/agents/types.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
TModeltoAgentConfigandAgentthat preserves whether the model was set as a staticModelor dynamicResolver<TInput, Model>TModelthroughevolve()so the mapper callback receives the correctly narrowed type.modelIdaccess in evolve mappers withoutisFunction()narrowingBefore
After
Test plan
pnpm typecheck --filter=@funkai/agentspassespnpm test --filter=@funkai/agents— all 624 tests pass, no type errorsTModel = Resolver<TInput, Model>ensures full backwards compatibility