Providers

The SDK supports multiple LLM providers through a unified interface.

Provider Factory

Create providers using the factory function:

import { createProvider, type ProviderCredentials } from '@agentic-work/sdk/providers';

const provider = createProvider({
  type: 'openai',
  apiKey: process.env.OPENAI_API_KEY
});

Supported Providers

OpenAI

const openai = createProvider({
  type: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  baseUrl: 'https://api.openai.com/v1', // optional
  defaultModel: 'gpt-4o' // optional
});

// Available models
const models = await openai.listModels();
// ['gpt-4o', 'gpt-4-turbo', 'gpt-4o-mini', 'o1-preview', ...]

Anthropic

const anthropic = createProvider({
  type: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY
});

// Models: claude-3-5-sonnet-20241022, claude-3-opus, claude-3-haiku

Google (Gemini)

const google = createProvider({
  type: 'google',
  apiKey: process.env.GOOGLE_API_KEY
});

// Models: gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash

Google Vertex AI

const vertex = createProvider({
  type: 'vertex-ai',
  projectId: process.env.GOOGLE_PROJECT_ID,
  location: 'us-central1',
  // Uses Application Default Credentials or service account
});

Azure OpenAI

const azure = createProvider({
  type: 'azure-openai',
  azureEndpoint: process.env.AZURE_OPENAI_ENDPOINT,
  azureApiKey: process.env.AZURE_OPENAI_API_KEY,
  azureApiVersion: '2024-02-01',
  azureDeploymentName: 'gpt-4o-deployment'
});

AWS Bedrock

const bedrock = createProvider({
  type: 'bedrock',
  awsRegion: 'us-east-1',
  awsAccessKeyId: process.env.AWS_ACCESS_KEY_ID,
  awsSecretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
});

// Models: anthropic.claude-3-sonnet, meta.llama3-70b, amazon.titan-text

Ollama (Local)

const ollama = createProvider({
  type: 'ollama',
  baseUrl: 'http://localhost:11434',
  defaultModel: 'llama3.2'
});

// List local models
const models = await ollama.listModels();

Provider Interface

All providers implement the same interface:

interface Provider {
  readonly type: ProviderType;

  // Get a completion
  complete(options: CompletionOptions): Promise<CompletionResponse>;

  // Stream a completion
  stream(options: CompletionOptions): AsyncGenerator<StreamChunk>;

  // List available models
  listModels(): Promise<string[]>;

  // Check provider health
  healthCheck(): Promise<boolean>;
}

Completion Options

interface CompletionOptions {
  model: string;
  messages: Message[];
  tools?: ToolDefinition[];
  temperature?: number;     // 0-2, default varies by provider
  maxTokens?: number;       // Max response tokens
  topP?: number;           // Nucleus sampling
  stopSequences?: string[]; // Stop generation at these strings
  stream?: boolean;        // Enable streaming (for complete())
}

Making Completions

Non-Streaming

const response = await provider.complete({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is 2+2?' }
  ],
  temperature: 0.7,
  maxTokens: 1000
});

console.log(response.choices[0].message.content);
console.log('Tokens used:', response.usage?.totalTokens);

Streaming

const stream = provider.stream({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Tell me a story' }]
});

for await (const chunk of stream) {
  switch (chunk.type) {
    case 'text_delta':
      process.stdout.write(chunk.text);
      break;
    case 'tool_call_delta':
      console.log('Tool:', chunk.toolCall);
      break;
    case 'done':
      console.log('\nFinished:', chunk.finishReason);
      break;
    case 'error':
      console.error('Error:', chunk.error);
      break;
  }
}

Tool Calling

const response = await provider.complete({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'What is the weather in Paris?' }],
  tools: [{
    name: 'get_weather',
    description: 'Get current weather for a city',
    inputSchema: {
      type: 'object',
      properties: {
        city: { type: 'string' }
      },
      required: ['city']
    }
  }]
});

// Check for tool calls
const toolCalls = response.choices[0].message.toolCalls;
if (toolCalls) {
  for (const call of toolCalls) {
    console.log(`Tool: ${call.name}`);
    console.log(`Args: ${JSON.stringify(call.arguments)}`);
  }
}

Health Checks

const isHealthy = await provider.healthCheck();
if (!isHealthy) {
  console.error('Provider is not responding');
}

Provider Credentials Reference

interface ProviderCredentials {
  type: ProviderType;

  // Common
  apiKey?: string;
  baseUrl?: string;
  defaultModel?: string;

  // AWS Bedrock
  awsRegion?: string;
  awsAccessKeyId?: string;
  awsSecretAccessKey?: string;
  awsSessionToken?: string;

  // Azure OpenAI
  azureEndpoint?: string;
  azureApiKey?: string;
  azureApiVersion?: string;
  azureDeploymentName?: string;

  // Azure AI Foundry
  azureAIEndpoint?: string;
  azureAIApiKey?: string;

  // Google Vertex AI
  googleProjectId?: string;
  googleLocation?: string;
  googleCredentials?: string | Record<string, unknown>;
}

Error Handling

try {
  const response = await provider.complete({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello' }]
  });
} catch (error) {
  // Handle provider-specific errors
  console.error('Provider error:', error.message);
}