Integration with AI SDK

.github/workflows/ci.yml

@@ -253,6 +253,12 @@ jobs:
         continue-on-error: true
 
       # Sample 3: fetch-esm to local server
+      #
+      # DO NOT MERGE!!!
+      #
+      # The url to the sample repo below has been modified to point to the "esm-improve" branch for testing.
+      # Restore this to the main branch before merging this PR.
+      #
       - name: Instantiate sample project using verdaccio artifacts - Fetch ESM
         run: |
           node scripts/init-from-verdaccio.js --registry-dir ${{ steps.tmp-dir.outputs.dir }}/npm-registry --sample https://github.com/temporalio/samples-typescript/tree/main/fetch-esm --target-dir ${{ steps.tmp-dir.outputs.dir }}/sample-fetch-esm

package.json

@@ -38,6 +38,7 @@
     "docs": "cd packages/docs && pnpm run maybe-install-deps-and-build-docs"
   },
   "dependencies": {
+    "@temporalio/ai-sdk": "workspace:*",
     "@temporalio/client": "workspace:*",
     "@temporalio/cloud": "workspace:*",
     "@temporalio/common": "workspace:*",
@@ -56,9 +57,9 @@
     "temporalio": "file:packages/meta"
   },
   "devDependencies": {
-    "@opentelemetry/api": "^1.7.0",
-    "@opentelemetry/core": "^1.19.0",
-    "@opentelemetry/sdk-node": "^0.46.0",
+    "@opentelemetry/api": "1.9.0",
+    "@opentelemetry/core": "1.25.1",
+    "@opentelemetry/sdk-node": "0.52.1",
     "@tsconfig/node18": "^18.2.4",
     "@types/fs-extra": "^11.0.4",
     "@types/ms": "^0.7.34",

packages/ai-sdk/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@temporalio/ai-sdk",
+  "version": "1.13.2",
+  "description": "Temporal AI SDK integration package",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "keywords": [
+    "temporal",
+    "workflow",
+    "ai",
+    "ai-sdk",
+    "llm"
+  ],
+  "author": "Temporal Technologies Inc. <[email protected]>",
+  "license": "MIT",
+  "dependencies": {
+    "@ai-sdk/provider": "^2.0.0",
+    "@ai-sdk/mcp": "^0.0.8",
+    "@temporalio/plugin": "workspace:*",
+    "@temporalio/workflow": "workspace:*",
+    "@ungap/structured-clone": "^1.3.0",
+    "headers-polyfill": "^4.0.3",
+    "web-streams-polyfill": "^4.2.0"
+  },
+  "peerDependencies": {
+    "ai": "^5.0.91"
+  },
+  "engines": {
+    "node": ">= 18.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/temporalio/sdk-typescript/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/temporalio/sdk-typescript.git",
+    "directory": "packages/ai-sdk"
+  },
+  "homepage": "https://github.com/temporalio/sdk-typescript/tree/main/packages/ai-sdk",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "lib"
+  ]
+}

packages/ai-sdk/src/activities.ts

@@ -0,0 +1,85 @@
+import {
+  LanguageModelV2CallOptions,
+  LanguageModelV2CallWarning,
+  LanguageModelV2Content,
+  LanguageModelV2FinishReason,
+  LanguageModelV2ResponseMetadata,
+  LanguageModelV2Usage,
+  ProviderV2,
+  SharedV2Headers,
+  SharedV2ProviderMetadata,
+} from '@ai-sdk/provider';
+import type { experimental_MCPClient as MCPClient } from '@ai-sdk/mcp';
+import { ToolCallOptions } from 'ai';
+
+export interface ListToolResult {
+  description?: string;
+  inputSchema: any;
+}
+
+export interface ListToolArgs {
+  clientArgs?: any;
+}
+
+export interface CallToolArgs {
+  clientArgs?: any;
+  name: string;
+  args: any;
+  options: ToolCallOptions;
+}
+
+/**
+ * Creates Temporal activities for AI model invocation using the provided AI SDK provider.
+ * These activities allow workflows to call AI models while maintaining Temporal's
+ * execution guarantees and replay safety.
+ *
+ * @param provider The AI SDK provider to use for model invocations
+ * @param mcpClientFactory
+ * @returns An object containing the activity functions
+ *
+ * @experimental The AI SDK integration is an experimental feature; APIs may change without notice.
+ */
+export const createActivities = (provider: ProviderV2, mcpClientFactory?: (_: any) => Promise<MCPClient>): object => {
+  const activities = {
+    async invokeModel(
+      modelId: string,
+      options: LanguageModelV2CallOptions
+    ): Promise<{
+      content: Array<LanguageModelV2Content>;
+      finishReason: LanguageModelV2FinishReason;
+      usage: LanguageModelV2Usage;
+      providerMetadata?: SharedV2ProviderMetadata;
+      request?: { body?: unknown };
+      response?: LanguageModelV2ResponseMetadata & { headers?: SharedV2Headers; body?: unknown };
+      warnings: Array<LanguageModelV2CallWarning>;
+    }> {
+      const model = provider.languageModel(modelId);
+      return await model.doGenerate(options);
+    },
+  };
+  if (mcpClientFactory === undefined) {
+    return activities;
+  }
+  return {
+    ...activities,
+    async listTools(args: ListToolArgs): Promise<Record<string, ListToolResult>> {
+      const mcpClient = await mcpClientFactory(args.clientArgs);
+      const tools = await mcpClient.tools();
+
+      return Object.fromEntries(
+        Object.entries(tools).map(([k, v]) => [
+          k,
+          {
+            description: v.description,
+            inputSchema: v.inputSchema,
+          },
+        ])
+      );
+    },
+    async callTool(args: CallToolArgs): Promise<any> {
+      const mcpClient = await mcpClientFactory(args.clientArgs);
+      const tools = await mcpClient.tools();
+      return tools[args.name].execute(args.args, args.options);
+    },
+  };
+};

packages/ai-sdk/src/index.ts

@@ -0,0 +1,9 @@
+// eslint-disable-next-line import/no-unassigned-import
+import 'ai';
+// eslint-disable-next-line import/no-unassigned-import
+import './load-polyfills';
+
+export * from './mcp';
+export * from './plugin';
+export * from './provider';
+export * from './testing';

packages/ai-sdk/src/load-polyfills.ts

@@ -0,0 +1,18 @@
+import { Headers } from 'headers-polyfill';
+import { inWorkflowContext } from '@temporalio/workflow';
+
+if (inWorkflowContext()) {
+  // Apply Headers polyfill
+  if (typeof globalThis.Headers === 'undefined') {
+    globalThis.Headers = Headers;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-require-imports,import/no-unassigned-import
+  require('web-streams-polyfill/polyfill');
+  // Attach the polyfill as a Global function
+  if (!('structuredClone' in globalThis)) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports,import/no-unassigned-import
+    const structuredClone = require('@ungap/structured-clone');
+    globalThis.structuredClone = structuredClone.default;
+  }
+}

packages/ai-sdk/src/mcp.ts

@@ -0,0 +1,40 @@
+import { ToolSet } from 'ai';
+import * as workflow from '@temporalio/workflow';
+import { ActivityOptions } from '@temporalio/workflow';
+import { ListToolResult } from './activities';
+
+export class TemporalMCPClient {
+  constructor(
+    // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+    readonly clientArgs?: any,
+    readonly options?: ActivityOptions
+  ) {}
+
+  async tools(): Promise<ToolSet> {
+    const tools: Record<string, ListToolResult> = await workflow
+      .proxyActivities(this.options ?? { startToCloseTimeout: '10 minutes' })
+      .listTools({ clientArgs: this.clientArgs });
+    return Object.fromEntries(
+      Object.entries(tools).map(([toolName, toolResult]) => [
+        toolName,
+        {
+          execute: async (args: any, options) =>
+            await workflow
+              .proxyActivities({
+                summary: toolName,
+                ...(this.options ?? { startToCloseTimeout: '10 minutes' }),
+              })
+              .callTool({ name: toolName, args, options, clientArgs: this.clientArgs }),
+          inputSchema: {
+            ...toolResult.inputSchema,
+            _type: undefined,
+            validate: undefined,
+            [Symbol.for('vercel.ai.schema')]: true,
+            [Symbol.for('vercel.ai.validator')]: true,
+          },
+          type: 'dynamic',
+        },
+      ])
+    );
+  }
+}

packages/ai-sdk/src/plugin.ts

@@ -0,0 +1,24 @@
+import { ProviderV2 } from '@ai-sdk/provider';
+import type { experimental_MCPClient as MCPClient } from '@ai-sdk/mcp';
+import { SimplePlugin } from '@temporalio/plugin';
+import { createActivities } from './activities';
+
+export interface AiSDKPluginOptions {
+  modelProvider: ProviderV2;
+  mcpClientFactory?: (args?: any) => Promise<MCPClient>;
+}
+
+/**
+ * A Temporal plugin that integrates AI SDK providers for use in workflows.
+ * This plugin creates activities that allow workflows to invoke AI models.
+ *
+ * @experimental The AI SDK plugin is an experimental feature; APIs may change without notice.
+ */
+export class AiSDKPlugin extends SimplePlugin {
+  constructor(options: AiSDKPluginOptions) {
+    super({
+      name: 'AiSDKPlugin',
+      activities: createActivities(options.modelProvider, options.mcpClientFactory),
+    });
+  }
+}

packages/ai-sdk/src/provider.ts

@@ -0,0 +1,92 @@
+import {
+  EmbeddingModelV2,
+  ImageModelV2,
+  LanguageModelV2,
+  LanguageModelV2CallOptions,
+  LanguageModelV2CallWarning,
+  LanguageModelV2Content,
+  LanguageModelV2FinishReason,
+  LanguageModelV2ResponseMetadata,
+  LanguageModelV2Usage,
+  ProviderV2,
+  SharedV2Headers,
+  SharedV2ProviderMetadata,
+} from '@ai-sdk/provider';
+import * as workflow from '@temporalio/workflow';
+import { ActivityOptions } from '@temporalio/workflow';
+
+/**
+ * A language model implementation that delegates AI model calls to Temporal activities.
+ * This allows workflows to invoke AI models through the Temporal execution model.
+ *
+ * @experimental The AI SDK integration is an experimental feature; APIs may change without notice.
+ */
+export class TemporalLanguageModel implements LanguageModelV2 {
+  readonly specificationVersion = 'v2';
+  readonly provider = 'temporal';
+  readonly supportedUrls = {};
+
+  constructor(
+    readonly modelId: string,
+    readonly options?: ActivityOptions
+  ) {}
+
+  async doGenerate(options: LanguageModelV2CallOptions): Promise<{
+    content: Array<LanguageModelV2Content>;
+    finishReason: LanguageModelV2FinishReason;
+    usage: LanguageModelV2Usage;
+    providerMetadata?: SharedV2ProviderMetadata;
+    request?: { body?: unknown };
+    response?: LanguageModelV2ResponseMetadata & { headers?: SharedV2Headers; body?: unknown };
+    warnings: Array<LanguageModelV2CallWarning>;
+  }> {
+    const result = await workflow
+      .proxyActivities(this.options ?? { startToCloseTimeout: '10 minutes' })
+      .invokeModel(this.modelId, options);
+    if (result === undefined) {
+      throw new Error('Received undefined response from model activity.');
+    }
+    if (result.response !== undefined) {
+      result.response.timestamp = new Date(result.response.timestamp);
+    }
+    return result;
+  }
+
+  doStream(_options: LanguageModelV2CallOptions): PromiseLike<{
+    stream: any;
+    request?: { body?: unknown };
+    response?: { headers?: SharedV2Headers };
+  }> {
+    throw new Error('Streaming not supported.');
+  }
+}
+
+/**
+ * A Temporal-specific provider implementation that creates AI models which execute
+ * through Temporal activities. This provider integrates AI SDK models with Temporal's
+ * execution model to ensure reliable, durable AI model invocations.
+ *
+ * @experimental The AI SDK integration is an experimental feature; APIs may change without notice.
+ */
+export class TemporalProvider implements ProviderV2 {
+  constructor(readonly options?: ActivityOptions) {}
+
+  imageModel(_modelId: string): ImageModelV2 {
+    throw new Error('Not implemented');
+  }
+
+  languageModel(modelId: string): LanguageModelV2 {
+    return new TemporalLanguageModel(modelId, this.options);
+  }
+
+  textEmbeddingModel(_modelId: string): EmbeddingModelV2<string> {
+    throw new Error('Not implemented');
+  }
+}
+
+/**
+ * A singleton instance of TemporalProvider for convenient use in applications.
+ *
+ * @experimental The AI SDK integration is an experimental feature; APIs may change without notice.
+ */
+export const temporalProvider: TemporalProvider = new TemporalProvider();