feat(core): add prepareStep to AgentOptions for per-step tool control#1192
Merged
omeraplak merged 1 commit intoVoltAgent:mainfrom Apr 8, 2026
Merged
feat(core): add prepareStep to AgentOptions for per-step tool control#1192omeraplak merged 1 commit intoVoltAgent:mainfrom
omeraplak merged 1 commit intoVoltAgent:mainfrom
Conversation
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (7)
✅ Files skipped from review due to trivial changes (4)
🚧 Files skipped from review as they are similar to previous changes (3)
📝 WalkthroughWalkthroughAdds a top-level Changes
Sequence Diagram(s)sequenceDiagram
participant Client as Client
participant Agent as Agent
participant Prepare as PrepareStep
participant AI as AI_SDK
Client->>Agent: generateText(options)
Agent->>Prepare: invoke (options.prepareStep || agent.prepareStep) with { steps }
Prepare-->>Agent: return stepOptions
Agent->>AI: call generateText(aiSDKOptions + stepOptions)
AI-->>Agent: response / stream
Agent-->>Client: return result
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
🦋 Changeset detectedLatest commit: 1c617bb 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 |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
ravyg
force-pushed
the
feat/agent-prepare-step
branch
from
12f7aec to
f9fabf7
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (1)
packages/core/src/agent/prepare-step.spec.ts (1)
74-98: Add a matching per-call override test forstreamText.Override precedence is only asserted for
generateText; adding the same check forstreamTextwould fully cover the stated contract.Suggested test addition
+ it("should allow per-call prepareStep to override agent-level in streamText", async () => { + const agentPrepareStep = vi.fn(() => ({})); + const callPrepareStep = vi.fn(() => ({})); + const model = createMockLanguageModel(); + + const agent = new Agent({ + name: "test-agent", + instructions: "test", + model, + prepareStep: agentPrepareStep, + }); + + const result = await agent.streamText("hello", { + prepareStep: callPrepareStep, + }); + for await (const _part of result.textStream) { + // drain + } + + expect(callPrepareStep).toHaveBeenCalled(); + expect(agentPrepareStep).not.toHaveBeenCalled(); + });🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/core/src/agent/prepare-step.spec.ts` around lines 74 - 98, Add a parallel test to the existing "should allow per-call prepareStep to override agent-level" that calls agent.streamText instead of agent.generateText: create the same agentPrepareStep and callPrepareStep mocks, instantiate Agent with prepareStep: agentPrepareStep, call agent.streamText("hello", { prepareStep: callPrepareStep }) (awaiting the stream completion as needed), and assert that callPrepareStep was called and agentPrepareStep was not; reference Agent, streamText, generateText, and prepareStep to mirror the existing test structure.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@packages/core/src/agent/prepare-step.spec.ts`:
- Around line 74-98: Add a parallel test to the existing "should allow per-call
prepareStep to override agent-level" that calls agent.streamText instead of
agent.generateText: create the same agentPrepareStep and callPrepareStep mocks,
instantiate Agent with prepareStep: agentPrepareStep, call
agent.streamText("hello", { prepareStep: callPrepareStep }) (awaiting the stream
completion as needed), and assert that callPrepareStep was called and
agentPrepareStep was not; reference Agent, streamText, generateText, and
prepareStep to mirror the existing test structure.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d7eeedc7-2097-4a04-b323-cf555cf1f970
📒 Files selected for processing (6)
.changeset/feat-agent-prepare-step.mdpackages/core/src/agent/agent.tspackages/core/src/agent/prepare-step.spec.tspackages/core/src/agent/types.tspackages/core/src/ai-types.tspackages/core/src/index.ts
✅ Files skipped from review due to trivial changes (1)
- packages/core/src/ai-types.ts
🚧 Files skipped from review as they are similar to previous changes (4)
- .changeset/feat-agent-prepare-step.md
- packages/core/src/index.ts
- packages/core/src/agent/types.ts
- packages/core/src/agent/agent.ts
ravyg
force-pushed
the
feat/agent-prepare-step
branch
2 times, most recently
from
4a29c11 to
3e219d9
Compare
Surfaces the AI SDK's prepareStep callback as a top-level AgentOptions property. Users can now set a default step preparation callback at agent creation time to control tool availability per step. Per-call prepareStep in method options overrides the agent-level default. The agent-level default is applied before applyForcedToolChoice so both features compose correctly. Fixes VoltAgent#1187
ravyg
force-pushed
the
feat/agent-prepare-step
branch
from
3e219d9 to
1c617bb
Compare
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
2 participants
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.
Surfaces the AI SDK's
prepareStepcallback as a top-levelAgentOptionsproperty. Users can now set a default step preparation callback at agent creation time to control tool availability per step.Per-call
prepareStepin method options overrides the agent-level default. The agent-level default is applied beforeapplyForcedToolChoiceso both features compose correctly.Fixes #1187
PR Checklist
Please check if your PR fulfills the following requirements:
Bugs / Features
What is the current behavior?
prepareStepcan only be passed per-call via method options (e.g.agent.generateText({ prepareStep: ... })). There is no way to set a default at agent creation time, forcing users to repeat the callback on every call.What is the new behavior?
prepareStepis now available as a top-levelAgentOptionsproperty. It follows the same pattern asstopWhen— agent-level default, per-call override.Changes:
ai-types.ts— newPrepareSteptype alias (follows existingStopWhenpattern)types.ts— addedprepareSteptoAgentOptionsagent.ts— addedprepareSteptoBaseGenerationOptions, stored on Agent instance, applied in bothgenerateTextandstreamTextpaths beforeapplyForcedToolChoiceindex.ts— exportedPrepareSteptypefixes #1187
Notes for reviewers
Follows the exact same pattern as
stopWhen(agent-level default, per-call override). The agent-levelprepareStepis applied beforeapplyForcedToolChoicewraps it, so forced tool choice still works correctly on the first step. Build passes across all 28 packages. No new dependencies.Summary by cubic
Expose
prepareSteponAgentOptionsin@voltagent/coreso agents can set a default per-step callback for tool and step control. Per-callprepareStepstill overrides and runs before forced tool choice; fixes #1187.prepareStepis applied ingenerateTextandstreamText.PrepareStep; added tests and a migration guide example.Written for commit 1c617bb. Summary will update on new commits.
Summary by CodeRabbit