Skip to content

Hookable Control Over Agent Loop Iterations in AI SDK #4954

Closed
@bryanhelmig

Description

@bryanhelmig

Feature Description

Currently, when using streamText with maxSteps, there's no built-in way to dynamically modify tool choices, system messages, or other options during execution. The only workaround is setting maxSteps to 1 and manually handling the iteration externally, which degrades the experience. This feature request proposes adding hooks or callbacks that allow users to modify options between steps while still benefiting from maxSteps.

Problem Statement

When running an agent loop with maxSteps, you may want to:

  • Specify a particular tool at a specific step.
  • Modify system/user messages dynamically.
  • Enable or disable tools as execution progresses.
  • Sequence through a set of tool calls dynamically based on prior responses.

Currently, to achieve this, the only option is setting maxSteps: 1 and manually handling the loop externally. This results in losing the built-in step iteration benefits of maxSteps.

Proposed Solution

Introduce an optional hook or callback that allows modifying parameters between steps within the agent loop:

const response = await streamText({
  model: openai("gpt-4o"),
  messages: [{ role: "system", content: "You are a helpful assistant." }],
  tools: { toolA, toolB },
  maxSteps: 10,
  onStepFinish: ({ stepType, text, toolCalls, updateCallSettings }) => {
    if (
      stepType === "tool-result" &&
      toolCalls?.some((tc) => tc.toolName === "toolA")
    ) {
      updateCallSettings({ toolChoice: { type: "tool", toolName: "toolB" } });
    }
    if (text.includes("specific trigger")) {
      updateCallSettings({
        messages: [
          ...messages,
          { role: "user", content: "Adjust your approach." },
        ],
      });
    }
  },
});

Benefits

  • More flexibility: Developers can dynamically adjust execution without external loops.
  • Better agent control: Enables fine-grained control over tool usage and messages.
  • Cleaner code: Reduces boilerplate from manually handling step iteration.

Use Cases

No response

Additional context

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions