ai 6.0.33 → 6.0.35

package/src/agent/infer-agent-tools.ts

@@ -0,0 +1,7 @@
+import { Agent } from './agent';
+
+/**
+ * Infer the type of the tools of an agent.
+ */
+export type InferAgentTools<AGENT> =
+  AGENT extends Agent<any, infer TOOLS, any> ? TOOLS : never;

package/src/agent/infer-agent-ui-message.test-d.ts

@@ -0,0 +1,54 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import {
+  DataUIPart,
+  DynamicToolUIPart,
+  FileUIPart,
+  ReasoningUIPart,
+  SourceDocumentUIPart,
+  SourceUrlUIPart,
+  StepStartUIPart,
+  TextUIPart,
+  UIMessage,
+} from '../ui/ui-messages';
+import { ToolLoopAgent } from './tool-loop-agent';
+import { InferAgentUIMessage } from './infer-agent-ui-message';
+
+describe('InferAgentUIMessage', () => {
+  it('should not contain arbitrary static tools when no tools are provided', () => {
+    const agent = new ToolLoopAgent({
+      model: 'openai/gpt-4o',
+      // no tools
+    });
+
+    type Message = InferAgentUIMessage<typeof agent>;
+
+    expectTypeOf<Message>().toMatchTypeOf<UIMessage<unknown, never, {}>>();
+
+    type MessagePart = Message['parts'][number];
+
+    expectTypeOf<MessagePart>().toMatchTypeOf<
+      | TextUIPart
+      | ReasoningUIPart
+      // No static tools, so no ToolUIPart
+      | DynamicToolUIPart
+      | SourceUrlUIPart
+      | SourceDocumentUIPart
+      | FileUIPart
+      | DataUIPart<never>
+      | StepStartUIPart
+    >();
+  });
+
+  it('should include metadata when provided', () => {
+    const agent = new ToolLoopAgent({
+      model: 'openai/gpt-4o',
+      // no tools
+    });
+
+    type Message = InferAgentUIMessage<typeof agent, { foo: string }>;
+
+    expectTypeOf<Message>().toMatchTypeOf<
+      UIMessage<{ foo: string }, never, {}>
+    >();
+  });
+});

package/src/agent/infer-agent-ui-message.ts

@@ -0,0 +1,11 @@
+import { InferUITools, UIMessage } from '../ui/ui-messages';
+import { InferAgentTools } from './infer-agent-tools';
+
+/**
+ * Infer the UI message type of an agent.
+ */
+export type InferAgentUIMessage<AGENT, MESSAGE_METADATA = unknown> = UIMessage<
+  MESSAGE_METADATA,
+  never,
+  InferUITools<InferAgentTools<AGENT>>
+>;

package/src/agent/pipe-agent-ui-stream-to-response.ts

@@ -0,0 +1,52 @@
+import { ServerResponse } from 'node:http';
+import { StreamTextTransform, UIMessageStreamOptions } from '../generate-text';
+import { Output } from '../generate-text/output';
+import { ToolSet } from '../generate-text/tool-set';
+import { TimeoutConfiguration } from '../prompt/call-settings';
+import { pipeUIMessageStreamToResponse } from '../ui-message-stream';
+import { UIMessageStreamResponseInit } from '../ui-message-stream/ui-message-stream-response-init';
+import { InferUITools, UIMessage } from '../ui/ui-messages';
+import { Agent } from './agent';
+import { createAgentUIStream } from './create-agent-ui-stream';
+
+/**
+ * Pipes the agent UI message stream to a Node.js ServerResponse object.
+ *
+ * @param agent - The agent to run.
+ * @param uiMessages - The input UI messages.
+ */
+export async function pipeAgentUIStreamToResponse<
+  CALL_OPTIONS = never,
+  TOOLS extends ToolSet = {},
+  OUTPUT extends Output = never,
+  MESSAGE_METADATA = unknown,
+>({
+  response,
+  headers,
+  status,
+  statusText,
+  consumeSseStream,
+  ...options
+}: {
+  response: ServerResponse;
+  agent: Agent<CALL_OPTIONS, TOOLS, OUTPUT>;
+  uiMessages: unknown[];
+  abortSignal?: AbortSignal;
+  timeout?: TimeoutConfiguration;
+  options?: CALL_OPTIONS;
+  experimental_transform?:
+    | StreamTextTransform<TOOLS>
+    | Array<StreamTextTransform<TOOLS>>;
+} & UIMessageStreamResponseInit &
+  UIMessageStreamOptions<
+    UIMessage<MESSAGE_METADATA, never, InferUITools<TOOLS>>
+  >): Promise<void> {
+  pipeUIMessageStreamToResponse({
+    response,
+    headers,
+    status,
+    statusText,
+    consumeSseStream,
+    stream: await createAgentUIStream(options),
+  });
+}

package/src/agent/tool-loop-agent-on-finish-callback.ts

@@ -0,0 +1,31 @@
+import { StepResult } from '../generate-text/step-result';
+import { ToolSet } from '../generate-text/tool-set';
+import { LanguageModelUsage } from '../types/usage';
+
+/**
+Callback that is set using the `onFinish` option.
+
+@param event - The event that is passed to the callback.
+ */
+export type ToolLoopAgentOnFinishCallback<TOOLS extends ToolSet = {}> = (
+  event: StepResult<TOOLS> & {
+    /**
+     * Details for all steps.
+     */
+    readonly steps: StepResult<TOOLS>[];
+
+    /**
+     * Total usage for all steps. This is the sum of the usage of all steps.
+     */
+    readonly totalUsage: LanguageModelUsage;
+
+    /**
+     * Context that is passed into tool calls.
+     *
+     * Experimental (can break in patch releases).
+     *
+     * @default undefined
+     */
+    experimental_context?: unknown;
+  },
+) => PromiseLike<void> | void;

package/src/agent/tool-loop-agent-on-step-finish-callback.ts

@@ -0,0 +1,11 @@
+import { StepResult } from '../generate-text/step-result';
+import { ToolSet } from '../generate-text/tool-set';
+
+/**
+Callback that is set using the `onStepFinish` option.
+
+@param stepResult - The result of the step.
+ */
+export type ToolLoopAgentOnStepFinishCallback<TOOLS extends ToolSet = {}> = (
+  stepResult: StepResult<TOOLS>,
+) => Promise<void> | void;

package/src/agent/tool-loop-agent-settings.ts

@@ -0,0 +1,182 @@
+import {
+  FlexibleSchema,
+  MaybePromiseLike,
+  ProviderOptions,
+  SystemModelMessage,
+} from '@ai-sdk/provider-utils';
+import { Output } from '../generate-text/output';
+import { PrepareStepFunction } from '../generate-text/prepare-step';
+import { StopCondition } from '../generate-text/stop-condition';
+import { ToolCallRepairFunction } from '../generate-text/tool-call-repair-function';
+import { ToolSet } from '../generate-text/tool-set';
+import { CallSettings } from '../prompt/call-settings';
+import { Prompt } from '../prompt/prompt';
+import { TelemetrySettings } from '../telemetry/telemetry-settings';
+import { LanguageModel, ToolChoice } from '../types/language-model';
+import { DownloadFunction } from '../util/download/download-function';
+import { AgentCallParameters } from './agent';
+import { ToolLoopAgentOnFinishCallback } from './tool-loop-agent-on-finish-callback';
+import { ToolLoopAgentOnStepFinishCallback } from './tool-loop-agent-on-step-finish-callback';
+
+/**
+ * Configuration options for an agent.
+ */
+export type ToolLoopAgentSettings<
+  CALL_OPTIONS = never,
+  TOOLS extends ToolSet = {},
+  OUTPUT extends Output = never,
+> = Omit<CallSettings, 'abortSignal'> & {
+  /**
+   * The id of the agent.
+   */
+  id?: string;
+
+  /**
+   * The instructions for the agent.
+   *
+   * It can be a string, or, if you need to pass additional provider options (e.g. for caching), a `SystemModelMessage`.
+   */
+  instructions?: string | SystemModelMessage | Array<SystemModelMessage>;
+
+  /**
+The language model to use.
+   */
+  model: LanguageModel;
+
+  /**
+The tools that the model can call. The model needs to support calling tools.
+*/
+  tools?: TOOLS;
+
+  /**
+The tool choice strategy. Default: 'auto'.
+   */
+  toolChoice?: ToolChoice<NoInfer<TOOLS>>;
+
+  /**
+Condition for stopping the generation when there are tool results in the last step.
+When the condition is an array, any of the conditions can be met to stop the generation.
+
+@default stepCountIs(20)
+   */
+  stopWhen?:
+    | StopCondition<NoInfer<TOOLS>>
+    | Array<StopCondition<NoInfer<TOOLS>>>;
+
+  /**
+Optional telemetry configuration (experimental).
+   */
+  experimental_telemetry?: TelemetrySettings;
+
+  /**
+Limits the tools that are available for the model to call without
+changing the tool call and result types in the result.
+   */
+  activeTools?: Array<keyof NoInfer<TOOLS>>;
+
+  /**
+Optional specification for generating structured outputs.
+   */
+  output?: OUTPUT;
+
+  /**
+Optional function that you can use to provide different settings for a step.
+  */
+  prepareStep?: PrepareStepFunction<NoInfer<TOOLS>>;
+
+  /**
+A function that attempts to repair a tool call that failed to parse.
+   */
+  experimental_repairToolCall?: ToolCallRepairFunction<NoInfer<TOOLS>>;
+
+  /**
+   * Callback that is called when each step (LLM call) is finished, including intermediate steps.
+   */
+  onStepFinish?: ToolLoopAgentOnStepFinishCallback<NoInfer<TOOLS>>;
+
+  /**
+   * Callback that is called when all steps are finished and the response is complete.
+   */
+  onFinish?: ToolLoopAgentOnFinishCallback<NoInfer<TOOLS>>;
+
+  /**
+Additional provider-specific options. They are passed through
+to the provider from the AI SDK and enable provider-specific
+functionality that can be fully encapsulated in the provider.
+         */
+  providerOptions?: ProviderOptions;
+
+  /**
+   * Context that is passed into tool calls.
+   *
+   * Experimental (can break in patch releases).
+   *
+   * @default undefined
+   */
+  experimental_context?: unknown;
+
+  /**
+Custom download function to use for URLs.
+
+By default, files are downloaded if the model does not support the URL for the given media type.
+     */
+  experimental_download?: DownloadFunction | undefined;
+
+  /**
+   * The schema for the call options.
+   */
+  callOptionsSchema?: FlexibleSchema<CALL_OPTIONS>;
+
+  /**
+   * Prepare the parameters for the generateText or streamText call.
+   *
+   * You can use this to have templates based on call options.
+   */
+  prepareCall?: (
+    options: AgentCallParameters<CALL_OPTIONS> &
+      Pick<
+        ToolLoopAgentSettings<CALL_OPTIONS, TOOLS, OUTPUT>,
+        | 'model'
+        | 'tools'
+        | 'maxOutputTokens'
+        | 'temperature'
+        | 'topP'
+        | 'topK'
+        | 'presencePenalty'
+        | 'frequencyPenalty'
+        | 'stopSequences'
+        | 'seed'
+        | 'headers'
+        | 'instructions'
+        | 'stopWhen'
+        | 'experimental_telemetry'
+        | 'activeTools'
+        | 'providerOptions'
+        | 'experimental_context'
+        | 'experimental_download'
+      >,
+  ) => MaybePromiseLike<
+    Pick<
+      ToolLoopAgentSettings<CALL_OPTIONS, TOOLS, OUTPUT>,
+      | 'model'
+      | 'tools'
+      | 'maxOutputTokens'
+      | 'temperature'
+      | 'topP'
+      | 'topK'
+      | 'presencePenalty'
+      | 'frequencyPenalty'
+      | 'stopSequences'
+      | 'seed'
+      | 'headers'
+      | 'instructions'
+      | 'stopWhen'
+      | 'experimental_telemetry'
+      | 'activeTools'
+      | 'providerOptions'
+      | 'experimental_context'
+      | 'experimental_download'
+    > &
+      Omit<Prompt, 'system'>
+  >;
+};

package/src/agent/tool-loop-agent.test-d.ts

@@ -0,0 +1,114 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import { z } from 'zod';
+import { Output } from '../generate-text';
+import { MockLanguageModelV3 } from '../test/mock-language-model-v3';
+import { AsyncIterableStream } from '../util/async-iterable-stream';
+import { DeepPartial } from '../util/deep-partial';
+import { AgentCallParameters, AgentStreamParameters } from './agent';
+import { ToolLoopAgent } from './tool-loop-agent';
+
+describe('ToolLoopAgent', () => {
+  describe('generate', () => {
+    it('should not allow system prompt', async () => {
+      const agent = new ToolLoopAgent({
+        model: new MockLanguageModelV3(),
+      });
+
+      await agent.generate({
+        // @ts-expect-error - system prompt is not allowed
+        system: '123',
+        prompt: 'Hello, world!',
+      });
+    });
+
+    it('should require options when call options are provided', async () => {
+      const agent = new ToolLoopAgent<{ callOption: string }>({
+        model: new MockLanguageModelV3(),
+      });
+
+      expectTypeOf<Parameters<typeof agent.generate>[0]>().toEqualTypeOf<
+        AgentCallParameters<{ callOption: string }>
+      >();
+    });
+
+    it('should not require options when call options are not provided', async () => {
+      const agent = new ToolLoopAgent({
+        model: new MockLanguageModelV3(),
+      });
+
+      expectTypeOf<Parameters<typeof agent.generate>[0]>().toEqualTypeOf<
+        AgentCallParameters<never>
+      >();
+    });
+
+    it('should infer output type', async () => {
+      const agent = new ToolLoopAgent({
+        model: new MockLanguageModelV3(),
+        output: Output.object({
+          schema: z.object({ value: z.string() }),
+        }),
+      });
+
+      const generateResult = await agent.generate({
+        prompt: 'Hello, world!',
+      });
+
+      const output = generateResult.output;
+
+      expectTypeOf<typeof output>().toEqualTypeOf<{ value: string }>();
+    });
+  });
+
+  describe('stream', () => {
+    it('should not allow system prompt', () => {
+      const agent = new ToolLoopAgent({
+        model: new MockLanguageModelV3(),
+      });
+
+      agent.stream({
+        // @ts-expect-error - system prompt is not allowed
+        system: '123',
+        prompt: 'Hello, world!',
+      });
+    });
+
+    it('should require options when call options are provided', async () => {
+      const agent = new ToolLoopAgent<{ callOption: string }>({
+        model: new MockLanguageModelV3(),
+      });
+
+      expectTypeOf<Parameters<typeof agent.stream>[0]>().toEqualTypeOf<
+        AgentStreamParameters<{ callOption: string }, {}>
+      >();
+    });
+
+    it('should not require options when call options are not provided', async () => {
+      const agent = new ToolLoopAgent({
+        model: new MockLanguageModelV3(),
+      });
+
+      expectTypeOf<Parameters<typeof agent.stream>[0]>().toEqualTypeOf<
+        AgentStreamParameters<never, {}>
+      >();
+    });
+
+    it('should infer output type', async () => {
+      const agent = new ToolLoopAgent({
+        model: new MockLanguageModelV3(),
+        output: Output.object({
+          schema: z.object({ value: z.string() }),
+        }),
+      });
+
+      const streamResult = await agent.stream({
+        prompt: 'Hello, world!',
+      });
+
+      const partialOutputStream = streamResult.partialOutputStream;
+
+      expectTypeOf<typeof partialOutputStream>().toEqualTypeOf<
+        AsyncIterableStream<DeepPartial<{ value: string }>>
+      >();
+    });
+  });
+});