feat(model-provider): add automatic claude headers support (#1314)

ulivz · web-flow · commit 160b758914b9 · 2025-09-15T14:05:49.000+08:00
diff --git a/multimodal/tarko/agent/tests/agent/kernel/agent.test.ts b/multimodal/tarko/agent/tests/agent/kernel/agent.test.ts
@@ -151,7 +151,9 @@ describe('Agent', () => {
           "baseProvider": "openai",
           "baseURL": undefined,
           "displayName": undefined,
+          "headers": {},
           "id": "gpt-4o",
+          "params": undefined,
           "provider": "openai",
         }
       `);
diff --git a/multimodal/tarko/llm-client/src/handlers/anthropic.ts b/multimodal/tarko/llm-client/src/handlers/anthropic.ts
@@ -543,7 +543,10 @@ export class AnthropicHandler extends BaseHandler<AnthropicModel> {
 
     const stream = typeof body.stream === 'boolean' ? body.stream : undefined;
     const maxTokens = body.max_tokens ?? getDefaultMaxTokens(body.model);
-    const client = new Anthropic({ apiKey: getApiKey(this.opts.apiKey)! });
+    const client = new Anthropic({ 
+      apiKey: getApiKey(this.opts.apiKey)!,
+      defaultHeaders: this.opts.defaultHeaders,
+    });
     const stopSequences = convertStopSequences(body.stop);
     const topP = typeof body.top_p === 'number' ? body.top_p : undefined;
     const temperature =
diff --git a/multimodal/tarko/llm-client/src/handlers/azure-openai.ts b/multimodal/tarko/llm-client/src/handlers/azure-openai.ts
@@ -47,6 +47,7 @@ export class AzureOpenAIHandler extends BaseHandler<AzureOpenAIModel> {
       azureADTokenProvider,
       apiVersion,
       endpoint,
+      defaultHeaders: this.opts.defaultHeaders,
     });
 
     // We have to delete the provider field because it's not a valid parameter for the OpenAI API.
diff --git a/multimodal/tarko/llm-client/src/handlers/groq.ts b/multimodal/tarko/llm-client/src/handlers/groq.ts
@@ -44,6 +44,7 @@ export class GroqHandler extends BaseHandler<GroqModel> {
     const client = new OpenAI({
       apiKey,
       baseURL: 'https://api.groq.com/openai/v1',
+      defaultHeaders: this.opts.defaultHeaders,
     });
 
     if (apiKey === undefined) {
diff --git a/multimodal/tarko/llm-client/src/handlers/openai-compatible.ts b/multimodal/tarko/llm-client/src/handlers/openai-compatible.ts
@@ -76,6 +76,7 @@ export class OpenAICompatibleHandler extends BaseHandler<OpenAICompatibleModel>
     const openai = new OpenAI({
       ...this.opts,
       apiKey,
+      defaultHeaders: this.opts.defaultHeaders,
     });
 
     // We have to delete the provider field because it's not a valid parameter for the OpenAI API.
diff --git a/multimodal/tarko/llm-client/src/handlers/openai-non-streaming.ts b/multimodal/tarko/llm-client/src/handlers/openai-non-streaming.ts
@@ -116,6 +116,7 @@ export class OpenAINonStreamingHandler extends BaseHandler<OpenAIModel> {
     const openai = new OpenAI({
       ...this.opts,
       apiKey,
+      defaultHeaders: this.opts.defaultHeaders,
     });
 
     // We have to delete the provider field because it's not a valid parameter for the OpenAI API
diff --git a/multimodal/tarko/llm-client/src/handlers/openai.ts b/multimodal/tarko/llm-client/src/handlers/openai.ts
@@ -37,6 +37,7 @@ export class OpenAIHandler extends BaseHandler<OpenAIModel> {
     const openai = new OpenAI({
       ...this.opts,
       apiKey,
+      defaultHeaders: this.opts.defaultHeaders,
     });
 
     // We have to delete the provider field because it's not a valid parameter for the OpenAI API.
diff --git a/multimodal/tarko/llm-client/src/handlers/openrouter.ts b/multimodal/tarko/llm-client/src/handlers/openrouter.ts
@@ -35,6 +35,7 @@ export class OpenRouterHandler extends BaseHandler<OpenRouterModel> {
       defaultHeaders: {
         'HTTP-Referer': 'docs.tokenjs.ai',
         'X-Title': 'Token.js',
+        ...this.opts.defaultHeaders,
       },
     });
 
diff --git a/multimodal/tarko/llm-client/src/handlers/perplexity.ts b/multimodal/tarko/llm-client/src/handlers/perplexity.ts
@@ -42,6 +42,7 @@ export class PerplexityHandler extends BaseHandler<PerplexityModel> {
       ...this.opts,
       baseURL: 'https://api.perplexity.ai',
       apiKey,
+      defaultHeaders: this.opts.defaultHeaders,
     });
 
     const model = body.model.replace(PERPLEXITY_PREFIX, '');
diff --git a/multimodal/tarko/llm-client/src/userTypes/index.ts b/multimodal/tarko/llm-client/src/userTypes/index.ts
@@ -21,6 +21,7 @@ import {
 } from 'openai/resources/index';
 
 export type ConfigOptions = Pick<ClientOptions, 'apiKey' | 'baseURL'> & {
+  defaultHeaders?: Record<string, string>;
   azure?: {
     endpoint?: string;
     apiVersion?: string;
diff --git a/multimodal/tarko/model-provider/README.md b/multimodal/tarko/model-provider/README.md
@@ -14,6 +14,7 @@ npm install @tarko/model-provider
 - 🎯 **Unified Interface**: Single API for all providers with OpenAI-compatible interface
 - ⚙️ **Smart Resolution**: Automatic model configuration resolution with fallbacks
 - 🔧 **Extensible**: Easy to add new providers through configuration
+- 🔗 **Custom Headers**: Support for custom headers with automatic provider enhancements
 - 📦 **Type Safe**: Full TypeScript support with strict typing
 
 ## Quick Start
@@ -80,6 +81,30 @@ const resolvedModel = resolveModel(
 );
 ```
 
+### Custom Headers Support
+
+Add custom headers to any model configuration:
+
+```typescript
+// Custom headers for any provider
+const modelWithHeaders = resolveModel({
+  provider: 'openai',
+  id: 'gpt-4',
+  headers: {
+    'X-Custom-Header': 'value',
+    'Authorization': 'Bearer custom-token'
+  }
+});
+
+// Headers are passed through to the underlying HTTP client
+const client = createLLMClient(modelWithHeaders);
+```
+
+**Automatic Provider Enhancements:**
+- Claude models (`claude-*`, `anthropic/*`) automatically get `anthropic-beta` headers
+- Custom headers merge with automatic provider headers
+- Headers are validated and passed to the HTTP client
+
 ## API Reference
 
 ### Types
@@ -93,6 +118,7 @@ interface AgentModel {
   baseProvider?: BaseModelProviderName; // Base implementation
   apiKey?: string;                      // API key
   baseURL?: string;                     // Base URL
+  headers?: Record<string, string>;     // Custom headers (auto-merged with provider defaults)
 }
 ```
 
diff --git a/multimodal/tarko/model-provider/src/azure-claude-params.ts b/multimodal/tarko/model-provider/src/azure-claude-params.ts
@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2025 Bytedance, Inc. and its affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Automatically adds anthropic_beta parameters for Azure OpenAI provider with Claude models
+ * This is needed for Azure OpenAI's Claude model proxy service
+ *
+ * @param modelId - The model identifier
+ * @param provider - The provider name
+ * @param existingParams - Existing experimental parameters
+ * @returns Updated parameters with anthropic_beta if applicable
+ */
+export function addAzureClaudeParamsIfNeeded(
+  modelId: string,
+  provider: string,
+  existingParams?: Record<string, any>,
+): Record<string, any> | undefined {
+  // Only apply to azure-openai provider with gcp-claude4-sonnet model
+  if (provider === 'azure-openai' && modelId === 'gcp-claude4-sonnet') {
+    return {
+      ...existingParams,
+      anthropic_beta: ['fine-grained-tool-streaming-2025-05-14'],
+    };
+  }
+
+  return existingParams;
+}
diff --git a/multimodal/tarko/model-provider/src/claude-headers.ts b/multimodal/tarko/model-provider/src/claude-headers.ts
@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2025 Bytedance, Inc. and its affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Claude model detection and header utilities
+ */
+
+/**
+ * Check if a model is a Claude model
+ */
+export function isClaudeModel(model: string): boolean {
+  const claudePatterns = [
+    /^claude-/i,
+    /^anthropic\//i,
+  ];
+  return claudePatterns.some((pattern) => pattern.test(model));
+}
+
+/**
+ * Get Claude-specific beta features headers
+ */
+export function getClaudeHeaders(): Record<string, string> {
+  const betaFeatures = [
+    'fine-grained-tool-streaming-2025-05-14',
+    'token-efficient-tools-2025-02-19',
+  ];
+
+  return {
+    'anthropic-beta': betaFeatures.join(','),
+  };
+}
+
+/**
+ * Automatically add Claude headers to model configuration if it's a Claude model
+ */
+export function addClaudeHeadersIfNeeded(
+  model: string,
+  existingHeaders?: Record<string, string>,
+): Record<string, string> {
+  if (!isClaudeModel(model)) {
+    return existingHeaders || {};
+  }
+
+  const claudeHeaders = getClaudeHeaders();
+  return {
+    ...existingHeaders,
+    ...claudeHeaders,
+  };
+}
diff --git a/multimodal/tarko/model-provider/src/index.ts b/multimodal/tarko/model-provider/src/index.ts
@@ -8,6 +8,8 @@ export * from './model-resolver';
 export * from './llm-client';
 export * from './third-party';
 export * from './constants';
+export * from './claude-headers';
+export * from './azure-claude-params';
 
 // Re-export OpenAI for convenience
 export { OpenAI } from 'openai';
diff --git a/multimodal/tarko/model-provider/src/llm-client.ts b/multimodal/tarko/model-provider/src/llm-client.ts
@@ -28,11 +28,12 @@ export function createLLMClient(
   agentModel: AgentModel,
   requestInterceptor?: LLMRequestInterceptor,
 ): OpenAI {
-  const { provider, id, baseProvider, baseURL, apiKey } = agentModel;
+  const { provider, id, baseProvider, baseURL, apiKey, headers, params } = agentModel;
 
   const client = new TokenJS({
     apiKey,
     baseURL,
+    defaultHeaders: headers,
   });
 
   // Add extended model support for non-native providers
@@ -60,11 +61,13 @@ export function createLLMClient(
   return {
     chat: {
       completions: {
-        async create(params: ChatCompletionCreateParamsBase) {
+        async create(requestParams: ChatCompletionCreateParamsBase) {
           const requestPayload = {
-            ...params,
+            ...requestParams,
             provider,
             model: id,
+            // Merge experimental params directly into request body
+            ...params,
           };
 
           const finalRequest = requestInterceptor
diff --git a/multimodal/tarko/model-provider/src/model-resolver.ts b/multimodal/tarko/model-provider/src/model-resolver.ts
@@ -5,6 +5,8 @@
 
 import { AgentModel, ModelProviderName, BaseModelProviderName } from './types';
 import { HIGH_LEVEL_MODEL_PROVIDER_CONFIGS } from './constants';
+import { addClaudeHeadersIfNeeded } from './claude-headers';
+import { addAzureClaudeParamsIfNeeded } from './azure-claude-params';
 
 /**
  * Get the actual provider implementation name
@@ -50,12 +52,20 @@ export function resolveModel(
     apiKey = apiKey || defaultConfig.apiKey;
   }
 
+  // Automatically add Claude headers if it's a Claude model
+  const headers = addClaudeHeadersIfNeeded(model, agentModel?.headers);
+
+  // Automatically add Azure Claude params if needed
+  const params = addAzureClaudeParamsIfNeeded(model, provider, agentModel?.params);
+
   return {
     provider,
     id: model,
     displayName,
     baseURL,
     apiKey,
+    headers,
+    params,
     baseProvider: getActualProvider(provider),
   };
 }
diff --git a/multimodal/tarko/model-provider/src/types.ts b/multimodal/tarko/model-provider/src/types.ts
@@ -38,6 +38,10 @@ export interface Model {
    * Provider's base URL
    */
   baseURL?: string;
+  /**
+   * Additional headers to include in requests
+   */
+  headers?: Record<string, string>;
 }
 
 /**
@@ -60,6 +64,11 @@ export interface AgentModel extends Model {
    * Base provider name
    */
   baseProvider?: BaseModelProviderName;
+  /**
+   * Experimental parameters passed directly through request body
+   * @warning Use with caution - these parameters bypass validation
+   */
+  params?: Record<string, any>;
 }
 
 /**
diff --git a/multimodal/tarko/model-provider/tests/azure-claude-params.test.ts b/multimodal/tarko/model-provider/tests/azure-claude-params.test.ts
@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2025 Bytedance, Inc. and its affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from 'vitest';
+import { addAzureClaudeParamsIfNeeded } from '../src/azure-claude-params';
+
+describe('addAzureClaudeParamsIfNeeded', () => {
+  it('should add anthropic_beta for azure-openai provider with gcp-claude4-sonnet model', () => {
+    const result = addAzureClaudeParamsIfNeeded('gcp-claude4-sonnet', 'azure-openai');
+    expect(result).toEqual({
+      anthropic_beta: ['fine-grained-tool-streaming-2025-05-14'],
+    });
+  });
+
+  it('should merge with existing params for azure-openai provider with gcp-claude4-sonnet model', () => {
+    const existingParams = { customParam: 'value' };
+    const result = addAzureClaudeParamsIfNeeded('gcp-claude4-sonnet', 'azure-openai', existingParams);
+    expect(result).toEqual({
+      customParam: 'value',
+      anthropic_beta: ['fine-grained-tool-streaming-2025-05-14'],
+    });
+  });
+
+  it('should not add params for other providers', () => {
+    const result = addAzureClaudeParamsIfNeeded('gcp-claude4-sonnet', 'openai');
+    expect(result).toBeUndefined();
+  });
+
+  it('should not add params for other models on azure-openai', () => {
+    const result = addAzureClaudeParamsIfNeeded('gpt-4', 'azure-openai');
+    expect(result).toBeUndefined();
+  });
+
+  it('should return existing params unchanged for non-matching cases', () => {
+    const existingParams = { customParam: 'value' };
+    const result = addAzureClaudeParamsIfNeeded('gpt-4', 'openai', existingParams);
+    expect(result).toEqual(existingParams);
+  });
+});
diff --git a/multimodal/tarko/model-provider/tests/claude-headers.test.ts b/multimodal/tarko/model-provider/tests/claude-headers.test.ts
diff --git a/multimodal/tarko/model-provider/tests/integration.test.ts b/multimodal/tarko/model-provider/tests/integration.test.ts
diff --git a/multimodal/tarko/model-provider/tests/model-resolver.test.ts b/multimodal/tarko/model-provider/tests/model-resolver.test.ts
