feat (ai): add experimental Agent abstraction (#7092)

## Background

Over 60% of users prefer an OOP Agent abstraction over the functional
`generateText` / `streamText` abstractions.

## Summary

Add an experimental `Agent` abstraction.

## Verification

Ran new examples.

Author: lgrammel

.changeset/fuzzy-goats-mate.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat (ai): add experimental Agent abstraction

examples/ai-core/src/agent/openai-generate.ts

@@ -0,0 +1,19 @@
+import { openai } from '@ai-sdk/openai';
+import { Experimental_Agent as Agent } from 'ai';
+import 'dotenv/config';
+
+async function main() {
+  const agent = new Agent({
+    model: openai('gpt-4o'),
+  });
+
+  const { text, usage } = await agent.generate({
+    prompt: 'Invent a new holiday and describe its traditions.',
+  });
+
+  console.log(text);
+  console.log();
+  console.log('Usage:', usage);
+}
+
+main().catch(console.error);

examples/ai-core/src/agent/openai-stream.ts

@@ -0,0 +1,26 @@
+import { openai } from '@ai-sdk/openai';
+import { Experimental_Agent as Agent } from 'ai';
+import 'dotenv/config';
+
+async function main() {
+  const agent = new Agent({
+    model: openai('gpt-3.5-turbo'),
+    maxOutputTokens: 512,
+    temperature: 0.3,
+    maxRetries: 5,
+  });
+
+  const result = agent.stream({
+    prompt: 'Invent a new holiday and describe its traditions.',
+  });
+
+  for await (const textPart of result.textStream) {
+    process.stdout.write(textPart);
+  }
+
+  console.log();
+  console.log('Token usage:', await result.usage);
+  console.log('Finish reason:', await result.finishReason);
+}
+
+main().catch(console.error);

packages/ai/src/agent/agent.ts

@@ -0,0 +1,131 @@
+import { IdGenerator } from '@ai-sdk/provider-utils';
+import {
+  generateText,
+  GenerateTextOnStepFinishCallback,
+} from '../../core/generate-text/generate-text';
+import { Output } from '../../core/generate-text/output';
+import { PrepareStepFunction } from '../../core/generate-text/prepare-step';
+import { StopCondition } from '../../core/generate-text/stop-condition';
+import { ToolCallRepairFunction } from '../../core/generate-text/tool-call-repair-function';
+import { ToolSet } from '../../core/generate-text/tool-set';
+import { CallSettings } from '../../core/prompt/call-settings';
+import { TelemetrySettings } from '../../core/telemetry/telemetry-settings';
+import { LanguageModel, ToolChoice } from '../../core/types/language-model';
+import { streamText } from '../../core/generate-text/stream-text';
+import { StreamTextResult } from '../../core/generate-text/stream-text-result';
+import { Prompt } from '../../core/prompt/prompt';
+import { ProviderMetadata } from '../../core/types/provider-metadata';
+import { GenerateTextResult } from '../../core/generate-text/generate-text-result';
+
+export type AgentSettings<
+  TOOLS extends ToolSet,
+  OUTPUT = never,
+  OUTPUT_PARTIAL = never,
+> = CallSettings & {
+  /**
+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(1)
+   */
+  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 parsing structured outputs from the LLM response.
+   */
+  experimental_output?: Output<OUTPUT, OUTPUT_PARTIAL>;
+
+  /**
+   * @deprecated Use `prepareStep` instead.
+   */
+  experimental_prepareStep?: PrepareStepFunction<NoInfer<TOOLS>>;
+
+  /**
+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?: GenerateTextOnStepFinishCallback<NoInfer<TOOLS>>;
+
+  /**
+   * Internal. For test use only. May change without notice.
+   */
+  _internal?: {
+    generateId?: IdGenerator;
+    currentDate?: () => Date;
+  };
+};
+
+export class Agent<
+  TOOLS extends ToolSet,
+  OUTPUT = never,
+  OUTPUT_PARTIAL = never,
+> {
+  private readonly settings: AgentSettings<TOOLS, OUTPUT, OUTPUT_PARTIAL>;
+
+  constructor(settings: AgentSettings<TOOLS, OUTPUT, OUTPUT_PARTIAL>) {
+    this.settings = settings;
+  }
+
+  async generate(
+    options: Prompt & {
+      /**
+Additional provider-specific metadata. They are passed through
+from the provider to the AI SDK and enable provider-specific
+results that can be fully encapsulated in the provider.
+   */
+      providerMetadata?: ProviderMetadata;
+    },
+  ): Promise<GenerateTextResult<TOOLS, OUTPUT>> {
+    return generateText({ ...this.settings, ...options });
+  }
+
+  stream(
+    options: Prompt & {
+      /**
+Additional provider-specific metadata. They are passed through
+from the provider to the AI SDK and enable provider-specific
+results that can be fully encapsulated in the provider.
+   */
+      providerMetadata?: ProviderMetadata;
+    },
+  ): StreamTextResult<TOOLS, OUTPUT_PARTIAL> {
+    return streamText({ ...this.settings, ...options });
+  }
+}

packages/ai/src/agent/index.ts

@@ -0,0 +1,4 @@
+export {
+  type AgentSettings as Experimental_AgentSettings,
+  Agent as Experimental_Agent,
+} from './agent';

packages/ai/src/index.ts

@@ -9,6 +9,7 @@ export {
 } from '@ai-sdk/provider-utils';
 
 // directory exports
+export * from './agent';
 export * from './error';
 export * from './text-stream';
 export * from './ui';