@robota-sdk/agent-provider 3.0.0-beta.64

package/src/anthropic/parsers/response-parser.ts

@@ -0,0 +1,184 @@
+import { randomUUID } from 'node:crypto';
+import { TUniversalMessage, logger } from '@robota-sdk/agent-core';
+import type Anthropic from '@anthropic-ai/sdk';
+import type { IAnthropicMessage } from '../types/api-types';
+
+/**
+ * Anthropic response parser utility
+ *
+ * Handles parsing of responses from Anthropic API into standardized formats.
+ * Extracts parsing logic from the main provider for better modularity.
+ */
+export class AnthropicResponseParser {
+  /**
+   * Parse complete Anthropic message response
+   *
+   * @param response - Raw Anthropic API response
+   * @returns Standardized universal message
+   */
+  static parseResponse(response: IAnthropicMessage): TUniversalMessage {
+    try {
+      const content = response.content?.[0]?.text || '';
+
+      // Parse tool calls if present
+      const toolUseBlocks = response.content?.filter((block) => block.type === 'tool_use') || [];
+      const toolCalls = toolUseBlocks
+        .filter((toolBlock) => toolBlock.id && toolBlock.name)
+        .map((toolBlock) => ({
+          id: toolBlock.id!,
+          type: 'function' as const,
+          function: {
+            name: toolBlock.name!,
+            arguments: JSON.stringify(toolBlock.input || {}),
+          },
+        }));
+
+      // Calculate token usage
+      const usage = response.usage
+        ? {
+            promptTokens: response.usage.input_tokens,
+            completionTokens: response.usage.output_tokens,
+            totalTokens: response.usage.input_tokens + response.usage.output_tokens,
+          }
+        : undefined;
+
+      const result: TUniversalMessage = {
+        id: randomUUID(),
+        state: 'complete' as const,
+        role: 'assistant',
+        content: toolCalls.length > 0 ? null : content,
+        timestamp: new Date(),
+        ...(toolCalls.length > 0 && { toolCalls }),
+        ...(usage && { usage }),
+        metadata: {
+          model: response.model,
+          finishReason: response.stop_reason || 'unknown',
+        },
+      };
+
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown parsing error';
+      logger.error('Error parsing Anthropic response:', { message: errorMessage });
+      throw error;
+    }
+  }
+
+  /**
+   * Parse Anthropic streaming chunk
+   *
+   * @param chunk - Raw streaming chunk from Anthropic API
+   * @returns Parsed universal message or null if no content
+   */
+  static parseStreamingChunk(chunk: Anthropic.MessageStreamEvent): TUniversalMessage | null {
+    try {
+      // Handle different chunk types
+      switch (chunk.type) {
+        case 'content_block_start':
+          if (chunk.content_block?.type === 'text') {
+            return {
+              id: randomUUID(),
+              state: 'complete' as const,
+              role: 'assistant',
+              content: '',
+              timestamp: new Date(),
+              metadata: {
+                isStreamChunk: true,
+                isComplete: false,
+              },
+            };
+          }
+          if (chunk.content_block?.type === 'tool_use') {
+            return {
+              id: randomUUID(),
+              state: 'complete' as const,
+              role: 'assistant',
+              content: null,
+              timestamp: new Date(),
+              toolCalls: [
+                {
+                  id: chunk.content_block.id,
+                  type: 'function' as const,
+                  function: {
+                    name: chunk.content_block.name || '',
+                    arguments: JSON.stringify(chunk.content_block.input || {}),
+                  },
+                },
+              ],
+              metadata: {
+                isStreamChunk: true,
+                isComplete: false,
+              },
+            };
+          }
+          break;
+
+        case 'content_block_delta':
+          if (chunk.delta?.type === 'text_delta') {
+            return {
+              id: randomUUID(),
+              state: 'complete' as const,
+              role: 'assistant',
+              content: chunk.delta.text || '',
+              timestamp: new Date(),
+              metadata: {
+                isStreamChunk: true,
+                isComplete: false,
+              },
+            };
+          }
+          if (chunk.delta?.type === 'input_json_delta') {
+            // Handle tool call argument streaming
+            return {
+              id: randomUUID(),
+              state: 'complete' as const,
+              role: 'assistant',
+              content: null,
+              timestamp: new Date(),
+              metadata: {
+                isStreamChunk: true,
+                isComplete: false,
+              },
+            };
+          }
+          break;
+
+        case 'content_block_stop':
+          return {
+            id: randomUUID(),
+            state: 'complete' as const,
+            role: 'assistant',
+            content: '',
+            timestamp: new Date(),
+            metadata: {
+              isStreamChunk: true,
+              isComplete: false,
+            },
+          };
+
+        case 'message_stop':
+          return {
+            id: randomUUID(),
+            state: 'complete' as const,
+            role: 'assistant',
+            content: '',
+            timestamp: new Date(),
+            metadata: {
+              isStreamChunk: true,
+              isComplete: true,
+            },
+          };
+
+        default:
+          // Unknown chunk type, skip
+          break;
+      }
+
+      return null;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown parsing error';
+      logger.error('Error parsing Anthropic streaming chunk:', { message: errorMessage });
+      return null;
+    }
+  }
+}

package/src/anthropic/provider-definition.ts

@@ -0,0 +1,93 @@
+import {
+  CLAUDE_MODELS,
+  type IProviderDefinition,
+  type IProviderModelCatalogEntry,
+} from '@robota-sdk/agent-core';
+import { AnthropicProvider } from './provider';
+import { refreshAnthropicModelCatalog } from './model-catalog-refresh';
+
+export const DEFAULT_ANTHROPIC_PROVIDER_MODEL = 'claude-sonnet-4-6';
+export const DEFAULT_ANTHROPIC_PROVIDER_API_KEY_ENV = 'ANTHROPIC_API_KEY';
+export const DEFAULT_ANTHROPIC_PROVIDER_API_KEY_REFERENCE = `$ENV:${DEFAULT_ANTHROPIC_PROVIDER_API_KEY_ENV}`;
+export const ANTHROPIC_MODEL_SOURCE_URL = 'https://platform.claude.com/docs/en/api/models/list';
+export const ANTHROPIC_MODEL_LAST_VERIFIED_AT = '2026-05-04';
+const ANTHROPIC_API_KEY_URL = 'https://platform.claude.com/settings/keys';
+const ANTHROPIC_SETUP_SOURCE_URL = 'https://platform.claude.com/docs/en/api/overview';
+const ANTHROPIC_SETUP_LAST_VERIFIED_AT = '2026-05-08';
+const ANTHROPIC_SETUP_HELP_LINKS: NonNullable<IProviderDefinition['setupHelpLinks']> = [
+  {
+    kind: 'api-key',
+    label: 'Anthropic API keys',
+    url: ANTHROPIC_API_KEY_URL,
+    sourceUrl: ANTHROPIC_SETUP_SOURCE_URL,
+    lastVerifiedAt: ANTHROPIC_SETUP_LAST_VERIFIED_AT,
+  },
+];
+
+export function createAnthropicProviderDefinition(): IProviderDefinition {
+  return {
+    type: 'anthropic',
+    displayName: 'Anthropic',
+    description: 'Claude models through Anthropic API',
+    defaults: {
+      model: DEFAULT_ANTHROPIC_PROVIDER_MODEL,
+      apiKey: DEFAULT_ANTHROPIC_PROVIDER_API_KEY_REFERENCE,
+    },
+    modelCatalog: {
+      status: 'fallback',
+      sourceUrl: ANTHROPIC_MODEL_SOURCE_URL,
+      lastVerifiedAt: ANTHROPIC_MODEL_LAST_VERIFIED_AT,
+      entries: buildAnthropicModelCatalogEntries(),
+    },
+    setupHelpLinks: ANTHROPIC_SETUP_HELP_LINKS,
+    setupSteps: [
+      {
+        key: 'apiKey',
+        title: 'Anthropic API key',
+        defaultValue: DEFAULT_ANTHROPIC_PROVIDER_API_KEY_REFERENCE,
+        masked: true,
+      },
+      {
+        key: 'model',
+        title: 'Anthropic model',
+        defaultValue: DEFAULT_ANTHROPIC_PROVIDER_MODEL,
+      },
+    ],
+    refreshModelCatalog: ({ profile }) => refreshAnthropicModelCatalog(profile),
+    modelCatalogCacheTtlSeconds: 86400,
+    requiresApiKey: true,
+    createProvider: (config) =>
+      new AnthropicProvider({
+        apiKey: requireAnthropicApiKey(config.apiKey),
+        ...(config.baseURL !== undefined && { baseURL: config.baseURL }),
+        ...(config.timeout !== undefined && { timeout: config.timeout }),
+        defaultModel: config.model,
+      }),
+  };
+}
+
+function buildAnthropicModelCatalogEntries(): IProviderModelCatalogEntry[] {
+  const seen = new Set<string>();
+  const entries: IProviderModelCatalogEntry[] = [];
+  for (const model of Object.values(CLAUDE_MODELS)) {
+    if (seen.has(model.name)) continue;
+    seen.add(model.name);
+    entries.push({
+      id: model.id,
+      displayName: model.name,
+      contextWindow: model.contextWindow,
+      capabilities: ['tools', 'vision', 'json_schema', 'reasoning', 'streaming'],
+      lifecycle: 'active',
+      sourceUrl: ANTHROPIC_MODEL_SOURCE_URL,
+      lastVerifiedAt: ANTHROPIC_MODEL_LAST_VERIFIED_AT,
+    });
+  }
+  return entries;
+}
+
+function requireAnthropicApiKey(apiKey: string | undefined): string {
+  if (!apiKey) {
+    throw new Error('Provider anthropic requires apiKey');
+  }
+  return apiKey;
+}

package/src/anthropic/provider.ts

@@ -0,0 +1,290 @@
+import { randomUUID } from 'node:crypto';
+import Anthropic from '@anthropic-ai/sdk';
+import type { IAnthropicProviderOptions } from './types';
+import { AbstractAIProvider, getModelMaxOutput } from '@robota-sdk/agent-core';
+import type {
+  IProviderCapabilities,
+  IProviderNativeWebToolRequest,
+  TUniversalMessage,
+  IChatOptions,
+  TTextDeltaCallback,
+} from '@robota-sdk/agent-core';
+import { convertToAnthropicFormat, convertToolsToAnthropicFormat } from './message-converter';
+import { streamAndAssemble } from './streaming-handler';
+
+/**
+ * Anthropic provider implementation for Robota
+ *
+ * IMPORTANT PROVIDER-SPECIFIC RULES:
+ * 1. This provider MUST extend BaseAIProvider from @robota-sdk/agent-core
+ * 2. Content handling for Anthropic API:
+ *    - When tool_calls are present: content MUST be null (not empty string)
+ *    - For regular assistant messages: content should be a string
+ * 3. Use override keyword for all methods inherited from BaseAIProvider
+ * 4. Provider-specific API behavior should be documented here
+ *
+ * @public
+ */
+export class AnthropicProvider extends AbstractAIProvider {
+  override readonly name = 'anthropic';
+  override readonly version = '1.0.0';
+
+  private readonly client?: Anthropic;
+  private readonly options: IAnthropicProviderOptions;
+
+  /**
+   * When true, Anthropic server tools (web_search) are included in every request.
+   * The server executes these tools internally — no local tool registration needed.
+   */
+  enableWebTools = false;
+
+  /**
+   * Optional callback for text deltas during streaming.
+   * Set by the consumer (e.g., Session) to receive real-time text chunks.
+   * When set, chat() uses streaming internally while still returning
+   * the complete assembled message.
+   */
+  onTextDelta?: TTextDeltaCallback;
+
+  /** Callback when a server tool (web_search etc.) is invoked by the API */
+  onServerToolUse?: (toolName: string, input: Record<string, string>) => void;
+
+  constructor(options: IAnthropicProviderOptions) {
+    super();
+    this.options = options;
+
+    // Set executor if provided
+    if (options.executor) {
+      this.executor = options.executor;
+    }
+
+    // Only create client if not using executor
+    if (!this.executor) {
+      // Create client from apiKey if not provided.
+      if (options.client) {
+        this.client = options.client;
+      } else if (options.apiKey) {
+        this.client = new Anthropic({
+          apiKey: options.apiKey,
+          ...(options.timeout && { timeout: options.timeout }),
+          ...(options.baseURL && { baseURL: options.baseURL }),
+        });
+      } else {
+        throw new Error('Either Anthropic client, apiKey, or executor is required');
+      }
+    }
+  }
+
+  /**
+   * Generate response using TUniversalMessage
+   */
+  override async chat(
+    messages: TUniversalMessage[],
+    options?: IChatOptions,
+  ): Promise<TUniversalMessage> {
+    this.validateMessages(messages);
+    this.validateNativeWebTools(options?.nativeWebTools);
+
+    // Use executor when configured; otherwise use direct execution
+    if (this.executor) {
+      try {
+        return await this.executeViaExecutorOrDirect(messages, options);
+      } catch (error) {
+        throw error;
+      }
+    }
+
+    // Direct execution with Anthropic client
+    if (!this.client) {
+      throw new Error(
+        'Anthropic client not available. Either provide a client/apiKey or use an executor.',
+      );
+    }
+
+    // Separate system messages for the Anthropic system parameter
+    const systemMessages = messages.filter((m) => m.role === 'system');
+    const nonSystemMessages = messages.filter((m) => m.role !== 'system');
+    const anthropicMessages = convertToAnthropicFormat(nonSystemMessages);
+    const systemPrompt = systemMessages.map((m) => m.content || '').join('\n\n') || undefined;
+
+    if (!options?.model) {
+      throw new Error(
+        'Model is required in chat options. Please specify a model in defaultModel configuration.',
+      );
+    }
+
+    const functionTools = options?.tools ? convertToolsToAnthropicFormat(options.tools) : [];
+    const serverTools: Anthropic.Messages.ToolUnion[] = this.enableWebTools
+      ? [{ type: 'web_search_20250305' as const, name: 'web_search' }]
+      : [];
+    const allTools: Anthropic.Messages.ToolUnion[] = [...functionTools, ...serverTools];
+
+    const baseParams: Anthropic.MessageCreateParamsNonStreaming = {
+      model: options.model as string,
+      messages: anthropicMessages,
+      max_tokens: options?.maxTokens || getModelMaxOutput(options.model as string),
+      ...(systemPrompt && { system: systemPrompt }),
+      ...(options?.temperature !== undefined && { temperature: options.temperature }),
+      ...(allTools.length > 0 && { tools: allTools }),
+    };
+
+    // Always use streaming to avoid Anthropic SDK's 10-minute non-streaming timeout.
+    // When no onTextDelta callback is available, use a no-op to silently assemble the response.
+    const textDeltaCb = options?.onTextDelta ?? this.onTextDelta ?? (() => {});
+    return streamAndAssemble(
+      this.client,
+      baseParams,
+      textDeltaCb,
+      this.onServerToolUse,
+      options?.signal,
+      options?.onProviderNativeRawPayload,
+    );
+  }
+
+  /**
+   * Generate streaming response using TUniversalMessage
+   */
+  override async *chatStream(
+    messages: TUniversalMessage[],
+    options?: IChatOptions,
+  ): AsyncIterable<TUniversalMessage> {
+    this.validateMessages(messages);
+    this.validateNativeWebTools(options?.nativeWebTools);
+
+    // Use executor when configured; otherwise use direct execution
+    if (this.executor) {
+      try {
+        yield* this.executeStreamViaExecutorOrDirect(messages, options);
+        return;
+      } catch (error) {
+        throw error;
+      }
+    }
+
+    // Direct execution with Anthropic client
+    if (!this.client) {
+      throw new Error(
+        'Anthropic client not available. Either provide a client/apiKey or use an executor.',
+      );
+    }
+
+    const anthropicMessages = convertToAnthropicFormat(messages);
+
+    if (!options?.model) {
+      throw new Error(
+        'Model is required in chat options. Please specify a model in defaultModel configuration.',
+      );
+    }
+
+    const requestParams: Anthropic.MessageCreateParamsStreaming = {
+      model: options.model as string,
+      messages: anthropicMessages,
+      max_tokens: options?.maxTokens || getModelMaxOutput(options.model as string),
+      stream: true,
+    };
+
+    if (options?.temperature !== undefined) {
+      requestParams.temperature = options.temperature;
+    }
+
+    const functionTools = options?.tools ? convertToolsToAnthropicFormat(options.tools) : [];
+    const serverTools: Anthropic.Messages.ToolUnion[] = this.enableWebTools
+      ? [{ type: 'web_search_20250305' as const, name: 'web_search' }]
+      : [];
+    const allTools: Anthropic.Messages.ToolUnion[] = [...functionTools, ...serverTools];
+
+    if (allTools.length > 0) {
+      requestParams.tools = allTools;
+    }
+
+    options?.onProviderNativeRawPayload?.({
+      provider: 'anthropic',
+      apiSurface: 'anthropic-messages',
+      payloadKind: 'request',
+      payload: requestParams,
+    });
+    const stream = await this.client.messages.create(requestParams);
+
+    let sequence = 0;
+    for await (const chunk of stream) {
+      options?.onProviderNativeRawPayload?.({
+        provider: 'anthropic',
+        apiSurface: 'anthropic-messages',
+        payloadKind: 'stream_event',
+        sequence,
+        payload: chunk,
+      });
+      sequence++;
+      if (chunk.type === 'content_block_delta' && chunk.delta.type === 'text_delta') {
+        yield {
+          id: randomUUID(),
+          role: 'assistant',
+          content: chunk.delta.text,
+          state: 'complete' as const,
+          timestamp: new Date(),
+        };
+      }
+    }
+  }
+
+  override supportsTools(): boolean {
+    return true;
+  }
+
+  override getCapabilities(): IProviderCapabilities {
+    return {
+      functionCalling: { supported: true },
+      nativeWebTools: {
+        webSearch: this.enableWebTools
+          ? { supported: true, enabled: true, source: 'anthropic-messages' }
+          : {
+              supported: true,
+              enabled: false,
+              source: 'anthropic-messages',
+              reason: 'Call configureNativeWebTools({ webSearch: true }) or set enableWebTools.',
+            },
+        webFetch: {
+          supported: false,
+          enabled: false,
+          source: 'anthropic-messages',
+          reason: 'Anthropic provider exposes server web search only.',
+        },
+      },
+    };
+  }
+
+  configureNativeWebTools(request: IProviderNativeWebToolRequest): IProviderCapabilities {
+    if (request.webSearch === true) {
+      this.enableWebTools = true;
+    }
+    this.validateNativeWebTools(request);
+    return this.getCapabilities();
+  }
+
+  override validateConfig(): boolean {
+    return !!this.client && !!this.options && !!this.options.apiKey;
+  }
+
+  override async dispose(): Promise<void> {
+    // Anthropic client doesn't need explicit cleanup
+  }
+
+  /**
+   * Validate TUniversalMessage array
+   */
+  protected override validateMessages(messages: TUniversalMessage[]): void {
+    if (!Array.isArray(messages)) {
+      throw new Error('Messages must be an array');
+    }
+
+    if (messages.length === 0) {
+      throw new Error('Messages array cannot be empty');
+    }
+
+    for (const message of messages) {
+      if (!message.role || !['user', 'assistant', 'system', 'tool'].includes(message.role)) {
+        throw new Error(`Invalid message role: ${message.role}`);
+      }
+    }
+  }
+}