feat(ai-proxy): add Anthropic LLM provider support

.github/workflows/build.yml

@@ -142,6 +142,7 @@ jobs:
         run: yarn workspace @forestadmin/ai-proxy test --testPathPattern='llm.integration'
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 
   send-coverage:
     name: Send Coverage

packages/ai-proxy/jest.config.ts

@@ -1,9 +1,18 @@
 /* eslint-disable import/no-relative-packages */
+import path from 'path';
+
 import jestConfig from '../../jest.config';
 
+// Jest < 30 doesn't resolve wildcard exports in package.json.
+// @anthropic-ai/sdk uses "./lib/*" exports that need this workaround.
+const anthropicSdkDir = path.dirname(require.resolve('@anthropic-ai/sdk'));
+
 export default {
   ...jestConfig,
   collectCoverageFrom: ['<rootDir>/src/**/*.ts', '!<rootDir>/src/examples/**'],
   testMatch: ['<rootDir>/test/**/*.test.ts'],
   setupFiles: ['<rootDir>/test/setup-env.ts'],
+  moduleNameMapper: {
+    '^@anthropic-ai/sdk/(.*)$': `${anthropicSdkDir}/$1`,
+  },
 };

packages/ai-proxy/package.json

@@ -14,6 +14,7 @@
   "dependencies": {
     "@forestadmin/agent-toolkit": "1.0.0",
     "@forestadmin/datasource-toolkit": "1.50.1",
+    "@langchain/anthropic": "1.3.17",
     "@langchain/community": "1.1.4",
     "@langchain/core": "1.1.15",
     "@langchain/langgraph": "^1.1.0",

packages/ai-proxy/src/anthropic-adapter.ts

@@ -0,0 +1,87 @@
+import type { OpenAIMessage } from './langchain-adapter';
+import type { ChatCompletionTool, ChatCompletionToolChoice } from './provider';
+import type { ChatAnthropic } from '@langchain/anthropic';
+import type { BaseMessage } from '@langchain/core/messages';
+
+import { LangChainAdapter } from './langchain-adapter';
+
+/**
+ * Extended tool_choice type for Anthropic.
+ *
+ * LangChain's AnthropicToolChoice doesn't include `disable_parallel_tool_use`,
+ * but the Anthropic API supports it and LangChain passes objects through directly.
+ */
+type AnthropicToolChoiceWithParallelControl =
+  | 'auto'
+  | 'any'
+  | 'none'
+  | { type: 'tool'; name: string; disable_parallel_tool_use?: boolean }
+  | { type: 'auto' | 'any'; disable_parallel_tool_use: boolean };
+
+export default class AnthropicAdapter {
+  static convertMessages(messages: OpenAIMessage[]): BaseMessage[] {
+    return LangChainAdapter.convertMessages(AnthropicAdapter.mergeSystemMessages(messages));
+  }
+
+  /** Cast `as string` works around LangChain's AnthropicToolChoice missing `disable_parallel_tool_use`. */
+  static bindTools(
+    model: ChatAnthropic,
+    tools: ChatCompletionTool[],
+    {
+      toolChoice,
+      parallelToolCalls,
+    }: { toolChoice?: ChatCompletionToolChoice; parallelToolCalls?: boolean },
+  ): ChatAnthropic {
+    return model.bindTools(tools, {
+      tool_choice: AnthropicAdapter.convertToolChoice({ toolChoice, parallelToolCalls }) as string,
+    }) as ChatAnthropic;
+  }
+
+  /**
+   * Convert OpenAI tool_choice to Anthropic format, applying parallel tool restriction.
+   *
+   * Converts to LangChain format first, then applies `disable_parallel_tool_use`
+   * when `parallelToolCalls` is explicitly `false` (not just falsy — `undefined` means
+   * no restriction).
+   */
+  private static convertToolChoice({
+    toolChoice,
+    parallelToolCalls,
+  }: {
+    toolChoice?: ChatCompletionToolChoice;
+    parallelToolCalls?: boolean;
+  } = {}): AnthropicToolChoiceWithParallelControl | undefined {
+    const base = LangChainAdapter.convertToolChoice(toolChoice);
+
+    if (parallelToolCalls !== false) return base;
+
+    // Anthropic requires object form to set disable_parallel_tool_use
+    if (base === undefined || base === 'auto') {
+      return { type: 'auto', disable_parallel_tool_use: true };
+    }
+
+    if (base === 'any') {
+      return { type: 'any', disable_parallel_tool_use: true };
+    }
+
+    if (base === 'none') return 'none';
+
+    return { ...base, disable_parallel_tool_use: true };
+  }
+
+  /**
+   * Merge all system messages into a single one placed first.
+   *
+   * Anthropic only allows a single system message at the beginning of the conversation.
+   */
+  private static mergeSystemMessages(messages: OpenAIMessage[]): OpenAIMessage[] {
+    const systemContents = messages.filter(m => m.role === 'system').map(m => m.content || '');
+
+    if (systemContents.length <= 1) return messages;
+
+    const merged: OpenAIMessage = { role: 'system', content: systemContents.join('\n\n') };
+    const nonSystem = messages.filter(m => m.role !== 'system');
+
+    return [merged, ...nonSystem];
+  }
+}

packages/ai-proxy/src/errors.ts

@@ -42,9 +42,12 @@ export class AINotFoundError extends NotFoundError {
 }
 
 export class AIUnprocessableError extends UnprocessableError {
-  constructor(message: string) {
+  readonly cause?: Error;
+
+  constructor(message: string, options?: { cause?: Error }) {
     super(message);
     this.name = 'AIUnprocessableError';
+    if (options?.cause) this.cause = options.cause;
   }
 }
 
@@ -55,17 +58,10 @@ export class AINotConfiguredError extends AIError {
   }
 }
 
-export class OpenAIUnprocessableError extends AIUnprocessableError {
-  constructor(message: string) {
-    super(message);
-    this.name = 'OpenAIError';
-  }
-}
-
 export class AIToolUnprocessableError extends AIUnprocessableError {
   constructor(message: string) {
     super(message);
-    this.name = 'AIToolError';
+    this.name = 'AIToolUnprocessableError';
   }
 }
 

packages/ai-proxy/src/index.ts

@@ -3,6 +3,7 @@ import type { McpConfiguration } from './mcp-client';
 import McpConfigChecker from './mcp-config-checker';
 
 export { createAiProvider } from './create-ai-provider';
+export { default as ProviderDispatcher } from './provider-dispatcher';
 export * from './provider-dispatcher';
 export * from './remote-tools';
 export * from './router';

packages/ai-proxy/src/langchain-adapter.ts

@@ -0,0 +1,189 @@
+import type { ChatCompletionResponse, ChatCompletionToolChoice } from './provider';
+import type { BaseMessage } from '@langchain/core/messages';
+
+import { AIMessage, HumanMessage, SystemMessage, ToolMessage } from '@langchain/core/messages';
+import crypto from 'crypto';
+
+import { AIBadRequestError } from './errors';
+
+interface OpenAISystemMessage {
+  role: 'system';
+  content: string | null;
+}
+
+interface OpenAIUserMessage {
+  role: 'user';
+  content: string | null;
+}
+
+interface OpenAIAssistantMessage {
+  role: 'assistant';
+  content: string | null;
+  tool_calls?: Array<{
+    id: string;
+    function: {
+      name: string;
+      arguments: string;
+    };
+  }>;
+}
+
+interface OpenAIToolMessage {
+  role: 'tool';
+  content: string | null;
+  tool_call_id: string;
+}
+
+export type OpenAIMessage =
+  | OpenAISystemMessage
+  | OpenAIUserMessage
+  | OpenAIAssistantMessage
+  | OpenAIToolMessage;
+
+export type LangChainToolChoice =
+  | 'auto'
+  | 'any'
+  | 'none'
+  | { type: 'tool'; name: string }
+  | undefined;
+
+/** Handles generic format conversions between OpenAI and LangChain. */
+export class LangChainAdapter {
+  /** Convert OpenAI-format messages to LangChain messages. */
+  static convertMessages(messages: OpenAIMessage[]): BaseMessage[] {
+    const result: BaseMessage[] = [];
+
+    for (const msg of messages) {
+      switch (msg.role) {
+        case 'system':
+          result.push(new SystemMessage(msg.content || ''));
+          break;
+        case 'user':
+          result.push(new HumanMessage(msg.content || ''));
+          break;
+        case 'assistant':
+          if (msg.tool_calls) {
+            result.push(
+              new AIMessage({
+                content: msg.content || '',
+                tool_calls: msg.tool_calls.map(tc => ({
+                  id: tc.id,
+                  name: tc.function.name,
+                  args: LangChainAdapter.parseToolArguments(
+                    tc.function.name,
+                    tc.function.arguments,
+                  ),
+                })),
+              }),
+            );
+          } else {
+            result.push(new AIMessage(msg.content || ''));
+          }
+
+          break;
+        case 'tool':
+          if (!msg.tool_call_id) {
+            throw new AIBadRequestError('Tool message is missing required "tool_call_id" field.');
+          }
+
+          result.push(
+            new ToolMessage({
+              content: msg.content || '',
+              tool_call_id: msg.tool_call_id,
+            }),
+          );
+          break;
+        default:
+          throw new AIBadRequestError(
+            `Unsupported message role '${
+              (msg as { role: string }).role
+            }'. Expected: system, user, assistant, or tool.`,
+          );
+      }
+    }
+
+    return result;
+  }
+
+  /** Convert a LangChain AIMessage to an OpenAI-compatible ChatCompletionResponse. */
+  static convertResponse(response: AIMessage, modelName: string | null): ChatCompletionResponse {
+    const toolCalls = response.tool_calls?.map(tc => ({
+      id: tc.id || `call_${crypto.randomUUID()}`,
+      type: 'function' as const,
+      function: {
+        name: tc.name,
+        arguments: JSON.stringify(tc.args),
+      },
+    }));
+
+    const usageMetadata = response.usage_metadata as
+      | { input_tokens?: number; output_tokens?: number; total_tokens?: number }
+      | undefined;
+
+    return {
+      id: response.id || `msg_${crypto.randomUUID()}`,
+      object: 'chat.completion',
+      created: Math.floor(Date.now() / 1000),
+      model: modelName,
+      choices: [
+        {
+          index: 0,
+          message: {
+            role: 'assistant',
+            content: LangChainAdapter.extractTextContent(response.content),
+            refusal: null,
+            tool_calls: toolCalls?.length ? toolCalls : undefined,
+          },
+          finish_reason: toolCalls?.length ? 'tool_calls' : 'stop',
+          logprobs: null,
+        },
+      ],
+      usage: {
+        prompt_tokens: usageMetadata?.input_tokens ?? 0,
+        completion_tokens: usageMetadata?.output_tokens ?? 0,
+        total_tokens: usageMetadata?.total_tokens ?? 0,
+      },
+    };
+  }
+
+  /** Convert OpenAI tool_choice to LangChain format. */
+  static convertToolChoice(toolChoice: ChatCompletionToolChoice | undefined): LangChainToolChoice {
+    if (!toolChoice) return undefined;
+    if (toolChoice === 'auto') return 'auto';
+    if (toolChoice === 'none') return 'none';
+    if (toolChoice === 'required') return 'any';
+
+    if (typeof toolChoice === 'object' && toolChoice.type === 'function') {
+      return { type: 'tool', name: toolChoice.function.name };
+    }
+
+    throw new AIBadRequestError(
+      `Unsupported tool_choice value. Expected: 'auto', 'none', 'required', or {type: 'function', function: {name: '...'}}.`,
+    );
+  }
+
+  private static extractTextContent(content: AIMessage['content']): string | null {
+    if (typeof content === 'string') return content || null;
+
+    if (Array.isArray(content)) {
+      const text = content
+        .filter(block => block.type === 'text')
+        .map(block => ('text' in block ? block.text : ''))
+        .join('');
+
+      return text || null;
+    }
+
+    return null;
+  }
+
+  private static parseToolArguments(toolName: string, args: string): Record<string, unknown> {
+    try {
+      return JSON.parse(args);
+    } catch {
+      throw new AIBadRequestError(
+        `Invalid JSON in tool_calls arguments for tool '${toolName}': ${args}`,
+      );
+    }
+  }
+}