0
# AI Connectors
1

2
Comprehensive integrations with major AI providers including chat completions, embeddings, text-to-speech, image generation, and real-time communication capabilities. Supports OpenAI, Azure OpenAI, Google AI, Anthropic, Mistral, and many other providers.
3

4
## Capabilities
5

6
### OpenAI Chat Completion
7

8
Chat completion services using OpenAI's GPT models for conversational AI and text generation.
9

10
```python { .api }
11
class OpenAIChatCompletion:
12
    """
13
    OpenAI chat completion service for GPT models.
14
    """
15
    
16
    def __init__(
17
        self,
18
        ai_model_id: str,
19
        api_key: str | None = None,
20
        org_id: str | None = None,
21
        service_id: str | None = None,
22
        default_headers: dict[str, str] | None = None,
23
        async_client: AsyncOpenAI | None = None
24
    ):
25
        """
26
        Initialize OpenAI chat completion service.
27
        
28
        Parameters:
29
        - ai_model_id: The OpenAI model ID (e.g., 'gpt-4', 'gpt-3.5-turbo')
30
        - api_key: OpenAI API key (can also be set via environment variable)
31
        - org_id: OpenAI organization ID
32
        - service_id: Unique identifier for this service instance
33
        - default_headers: Default headers for requests
34
        - async_client: Pre-configured OpenAI async client
35
        """
36
    
37
    async def get_chat_message_contents(
38
        self,
39
        chat_history: ChatHistory,
40
        settings: OpenAIChatPromptExecutionSettings,
41
        **kwargs
42
    ) -> list[ChatMessageContent]:
43
        """
44
        Get chat message contents from OpenAI.
45
        
46
        Parameters:
47
        - chat_history: The conversation history
48
        - settings: Execution settings for the request
49
        - **kwargs: Additional arguments
50
        
51
        Returns:
52
        List of ChatMessageContent responses
53
        """
54
    
55
    async def get_streaming_chat_message_contents(
56
        self,
57
        chat_history: ChatHistory,
58
        settings: OpenAIChatPromptExecutionSettings,
59
        **kwargs
60
    ):
61
        """
62
        Get streaming chat message contents from OpenAI.
63
        
64
        Parameters:
65
        - chat_history: The conversation history
66
        - settings: Execution settings for the request
67
        - **kwargs: Additional arguments
68
        
69
        Yields:
70
        StreamingChatMessageContent as responses stream in
71
        """
72

73
class AzureChatCompletion:
74
    """
75
    Azure OpenAI chat completion service.
76
    """
77
    
78
    def __init__(
79
        self,
80
        deployment_name: str,
81
        endpoint: str | None = None,
82
        api_key: str | None = None,
83
        api_version: str | None = None,
84
        service_id: str | None = None,
85
        ad_token: str | None = None,
86
        ad_token_provider: Callable[[], str | Awaitable[str]] | None = None,
87
        default_headers: dict[str, str] | None = None,
88
        async_client: AsyncAzureOpenAI | None = None
89
    ):
90
        """
91
        Initialize Azure OpenAI chat completion service.
92
        
93
        Parameters:
94
        - deployment_name: Azure OpenAI deployment name
95
        - endpoint: Azure OpenAI endpoint URL
96
        - api_key: Azure OpenAI API key
97
        - api_version: API version to use
98
        - service_id: Unique identifier for this service instance
99
        - ad_token: Azure AD token for authentication
100
        - ad_token_provider: Token provider function for Azure AD auth
101
        - default_headers: Default headers for requests
102
        - async_client: Pre-configured Azure OpenAI async client
103
        """
104
    
105
    async def get_chat_message_contents(
106
        self,
107
        chat_history: ChatHistory,
108
        settings: AzureChatPromptExecutionSettings,
109
        **kwargs
110
    ) -> list[ChatMessageContent]:
111
        """
112
        Get chat message contents from Azure OpenAI.
113
        
114
        Parameters:
115
        - chat_history: The conversation history
116
        - settings: Execution settings including Azure-specific options
117
        - **kwargs: Additional arguments
118
        
119
        Returns:
120
        List of ChatMessageContent responses
121
        """
122
```
123

124
### Text Embedding Models
125

126
Text embedding services for converting text into vector representations for semantic search and retrieval.
127

128
```python { .api }
129
class OpenAITextEmbedding:
130
    """
131
    OpenAI text embedding service.
132
    """
133
    
134
    def __init__(
135
        self,
136
        ai_model_id: str,
137
        api_key: str | None = None,
138
        org_id: str | None = None,
139
        service_id: str | None = None,
140
        default_headers: dict[str, str] | None = None,
141
        async_client: AsyncOpenAI | None = None
142
    ):
143
        """
144
        Initialize OpenAI text embedding service.
145
        
146
        Parameters:
147
        - ai_model_id: The embedding model ID (e.g., 'text-embedding-ada-002')
148
        - api_key: OpenAI API key
149
        - org_id: OpenAI organization ID
150
        - service_id: Unique identifier for this service instance
151
        - default_headers: Default headers for requests
152
        - async_client: Pre-configured OpenAI async client
153
        """
154
    
155
    async def generate_embeddings(
156
        self,
157
        texts: list[str],
158
        **kwargs
159
    ) -> list[list[float]]:
160
        """
161
        Generate embeddings for the given texts.
162
        
163
        Parameters:
164
        - texts: List of text strings to embed
165
        - **kwargs: Additional arguments
166
        
167
        Returns:
168
        List of embedding vectors (list of floats)
169
        """
170

171
class AzureTextEmbedding:
172
    """
173
    Azure OpenAI text embedding service.
174
    """
175
    
176
    def __init__(
177
        self,
178
        deployment_name: str,  
179
        endpoint: str | None = None,
180
        api_key: str | None = None,
181
        api_version: str | None = None,
182
        service_id: str | None = None,
183
        ad_token: str | None = None,
184
        ad_token_provider: Callable[[], str | Awaitable[str]] | None = None,
185
        default_headers: dict[str, str] | None = None,
186
        async_client: AsyncAzureOpenAI | None = None
187
    ):
188
        """
189
        Initialize Azure OpenAI text embedding service.
190
        
191
        Parameters:
192
        - deployment_name: Azure OpenAI embedding deployment name
193
        - endpoint: Azure OpenAI endpoint URL
194
        - api_key: Azure OpenAI API key
195
        - api_version: API version to use
196
        - service_id: Unique identifier for this service instance
197
        - ad_token: Azure AD token for authentication
198
        - ad_token_provider: Token provider function for Azure AD auth
199
        - default_headers: Default headers for requests
200
        - async_client: Pre-configured Azure OpenAI async client
201
        """
202
    
203
    async def generate_embeddings(
204
        self,
205
        texts: list[str],
206
        **kwargs
207
    ) -> list[list[float]]:
208
        """
209
        Generate embeddings for the given texts using Azure OpenAI.
210
        
211
        Parameters:
212
        - texts: List of text strings to embed
213
        - **kwargs: Additional arguments
214
        
215
        Returns:
216
        List of embedding vectors (list of floats)
217
        """
218
```
219

220
### Audio Services  
221

222
Text-to-speech and speech-to-text capabilities for audio processing.
223

224
```python { .api }
225
class OpenAITextToAudio:
226
    """
227
    OpenAI text-to-audio service for speech synthesis.
228
    """
229
    
230
    def __init__(
231
        self,
232
        ai_model_id: str = "tts-1",
233
        api_key: str | None = None,
234
        org_id: str | None = None,
235
        service_id: str | None = None,
236
        default_headers: dict[str, str] | None = None,
237
        async_client: AsyncOpenAI | None = None
238
    ):
239
        """
240
        Initialize OpenAI text-to-audio service.
241
        
242
        Parameters:
243
        - ai_model_id: TTS model ID (e.g., 'tts-1', 'tts-1-hd')
244
        - api_key: OpenAI API key
245
        - org_id: OpenAI organization ID
246
        - service_id: Unique identifier for this service instance
247
        - default_headers: Default headers for requests
248
        - async_client: Pre-configured OpenAI async client
249
        """
250
    
251
    async def get_audio_contents(
252
        self,
253
        text: str,
254
        settings: OpenAITextToAudioExecutionSettings,
255
        **kwargs
256
    ) -> list[AudioContent]:
257
        """
258
        Generate audio from text.
259
        
260
        Parameters:
261
        - text: Text to convert to speech
262
        - settings: Audio generation settings (voice, format, etc.)
263
        - **kwargs: Additional arguments
264
        
265
        Returns:
266
        List of AudioContent with generated speech
267
        """
268

269
class OpenAIAudioToText:
270
    """
271
    OpenAI audio-to-text service for speech recognition.
272
    """
273
    
274
    def __init__(
275
        self,
276
        ai_model_id: str = "whisper-1",
277
        api_key: str | None = None,
278
        org_id: str | None = None,
279
        service_id: str | None = None,
280
        default_headers: dict[str, str] | None = None,
281
        async_client: AsyncOpenAI | None = None
282
    ):
283
        """
284
        Initialize OpenAI audio-to-text service.
285
        
286
        Parameters:
287
        - ai_model_id: Whisper model ID (e.g., 'whisper-1')
288
        - api_key: OpenAI API key
289
        - org_id: OpenAI organization ID
290
        - service_id: Unique identifier for this service instance
291
        - default_headers: Default headers for requests
292
        - async_client: Pre-configured OpenAI async client
293
        """
294
    
295
    async def get_text_contents(
296
        self,
297
        audio_content: AudioContent,
298
        settings: OpenAIAudioToTextExecutionSettings,
299
        **kwargs
300
    ) -> list[TextContent]:
301
        """
302
        Convert audio to text using Whisper.
303
        
304
        Parameters:
305
        - audio_content: Audio content to transcribe
306
        - settings: Transcription settings
307
        - **kwargs: Additional arguments
308
        
309
        Returns:
310
        List of TextContent with transcribed text
311
        """
312
```
313

314
### Image Generation
315

316
DALL-E image generation services for creating images from text descriptions.
317

318
```python { .api }
319
class OpenAITextToImage:
320
    """
321
    OpenAI text-to-image service using DALL-E.
322
    """
323
    
324
    def __init__(
325
        self,
326
        ai_model_id: str = "dall-e-3",
327
        api_key: str | None = None,
328
        org_id: str | None = None,
329
        service_id: str | None = None,
330
        default_headers: dict[str, str] | None = None,
331
        async_client: AsyncOpenAI | None = None
332
    ):
333
        """
334
        Initialize OpenAI text-to-image service.
335
        
336
        Parameters:
337
        - ai_model_id: DALL-E model ID (e.g., 'dall-e-2', 'dall-e-3')
338
        - api_key: OpenAI API key
339
        - org_id: OpenAI organization ID
340
        - service_id: Unique identifier for this service instance
341
        - default_headers: Default headers for requests
342
        - async_client: Pre-configured OpenAI async client
343
        """
344
    
345
    async def get_image_contents(
346
        self,
347
        description: str,
348
        settings: OpenAITextToImageExecutionSettings,
349
        **kwargs
350
    ) -> list[ImageContent]:
351
        """
352
        Generate images from text description.
353
        
354
        Parameters:
355
        - description: Text description of the image to generate
356
        - settings: Image generation settings (size, quality, etc.)
357
        - **kwargs: Additional arguments
358
        
359
        Returns:
360
        List of ImageContent with generated images
361
        """
362

363
class AzureTextToImage:
364
    """
365
    Azure OpenAI text-to-image service.
366
    """
367
    
368
    def __init__(
369
        self,
370
        deployment_name: str,
371
        endpoint: str | None = None,
372
        api_key: str | None = None,
373
        api_version: str | None = None,
374
        service_id: str | None = None,
375
        ad_token: str | None = None,
376
        ad_token_provider: Callable[[], str | Awaitable[str]] | None = None,
377
        default_headers: dict[str, str] | None = None,
378
        async_client: AsyncAzureOpenAI | None = None
379
    ):
380
        """
381
        Initialize Azure OpenAI text-to-image service.
382
        
383
        Parameters:
384
        - deployment_name: Azure OpenAI DALL-E deployment name
385
        - endpoint: Azure OpenAI endpoint URL
386
        - api_key: Azure OpenAI API key
387
        - api_version: API version to use
388
        - service_id: Unique identifier for this service instance
389
        - ad_token: Azure AD token for authentication
390
        - ad_token_provider: Token provider function for Azure AD auth
391
        - default_headers: Default headers for requests
392
        - async_client: Pre-configured Azure OpenAI async client
393
        """
394
    
395
    async def get_image_contents(
396
        self,
397
        description: str,
398
        settings: OpenAITextToImageExecutionSettings,
399
        **kwargs
400
    ) -> list[ImageContent]:
401
        """
402
        Generate images from text description using Azure OpenAI.
403
        
404
        Parameters:
405
        - description: Text description of the image to generate
406
        - settings: Image generation settings
407
        - **kwargs: Additional arguments
408
        
409
        Returns:
410
        List of ImageContent with generated images
411
        """
412
```
413

414
### Real-time Communication
415

416
WebSocket and WebRTC services for real-time communication with AI models.
417

418
```python { .api }
419
class OpenAIRealtimeWebsocket:
420
    """
421
    OpenAI real-time WebSocket communication service.
422
    """
423
    
424
    def __init__(
425
        self,
426
        ai_model_id: str = "gpt-4o-realtime-preview-2024-10-01",
427
        api_key: str | None = None,
428
        org_id: str | None = None,
429
        service_id: str | None = None
430
    ):
431
        """
432
        Initialize OpenAI real-time WebSocket service.
433
        
434
        Parameters:
435
        - ai_model_id: Real-time model ID
436
        - api_key: OpenAI API key
437
        - org_id: OpenAI organization ID
438
        - service_id: Unique identifier for this service instance
439
        """
440
    
441
    async def start_session(
442
        self,
443
        settings: OpenAIRealtimeExecutionSettings,
444
        **kwargs
445
    ):
446
        """
447
        Start a real-time session.
448
        
449
        Parameters:
450
        - settings: Real-time execution settings
451
        - **kwargs: Additional arguments
452
        
453
        Returns:
454
        Session context for real-time communication
455
        """
456

457
class AzureRealtimeWebsocket:
458
    """
459
    Azure OpenAI real-time WebSocket communication service.
460
    """
461
    
462
    def __init__(
463
        self,
464
        deployment_name: str,
465
        endpoint: str | None = None,
466
        api_key: str | None = None,
467
        api_version: str | None = None,
468
        service_id: str | None = None,
469
        ad_token: str | None = None,
470
        ad_token_provider: Callable[[], str | Awaitable[str]] | None = None
471
    ):
472
        """
473
        Initialize Azure OpenAI real-time WebSocket service.
474
        
475
        Parameters:
476
        - deployment_name: Azure OpenAI real-time deployment name
477
        - endpoint: Azure OpenAI endpoint URL
478
        - api_key: Azure OpenAI API key
479
        - api_version: API version to use
480
        - service_id: Unique identifier for this service instance
481
        - ad_token: Azure AD token for authentication
482
        - ad_token_provider: Token provider function for Azure AD auth
483
        """
484
```
485

486
### Other AI Providers
487

488
Semantic Kernel supports many other AI providers through dedicated connector modules:
489

490
```python { .api }
491
# Anthropic Claude
492
from semantic_kernel.connectors.ai.anthropic import AnthropicChatCompletion
493

494
# Google AI and Vertex AI
495
from semantic_kernel.connectors.ai.google.google_ai import GoogleAIChatCompletion
496
from semantic_kernel.connectors.ai.google.vertex_ai import VertexAIChatCompletion
497

498
# Hugging Face
499
from semantic_kernel.connectors.ai.hugging_face import HuggingFaceChatCompletion
500

501
# Mistral AI
502
from semantic_kernel.connectors.ai.mistral_ai import MistralAIChatCompletion
503

504
# NVIDIA NIM
505
from semantic_kernel.connectors.ai.nvidia import NVIDIAChatCompletion
506

507
# Ollama (local models)
508
from semantic_kernel.connectors.ai.ollama import OllamaChatCompletion
509

510
# ONNX Runtime
511
from semantic_kernel.connectors.ai.onnx import ONNXGenAIChatCompletion
512

513
# Amazon Bedrock
514
from semantic_kernel.connectors.ai.bedrock import BedrockChatCompletion
515

516
# Azure AI Inference
517
from semantic_kernel.connectors.ai.azure_ai_inference import AzureAIInferenceChatCompletion
518
```
519

520
### Execution Settings
521

522
Configuration classes for controlling AI service behavior.
523

524
```python { .api }
525
class PromptExecutionSettings:
526
    """
527
    Base class for AI service execution settings.
528
    """
529
    
530
    def __init__(
531
        self,
532
        service_id: str | None = None,
533
        extension_data: dict[str, Any] | None = None,
534
        **kwargs
535
    ):
536
        """
537
        Initialize execution settings.
538
        
539
        Parameters:
540
        - service_id: ID of the service to use for execution
541
        - extension_data: Additional service-specific settings
542
        - **kwargs: Additional settings
543
        """
544

545
class OpenAIChatPromptExecutionSettings(PromptExecutionSettings):
546
    """
547
    OpenAI-specific chat execution settings.
548
    """
549
    
550
    def __init__(
551
        self,
552
        service_id: str | None = None,
553
        max_tokens: int | None = None,
554
        temperature: float | None = None,
555
        top_p: float | None = None,
556
        frequency_penalty: float | None = None,
557
        presence_penalty: float | None = None,
558
        function_choice_behavior: FunctionChoiceBehavior | None = None,
559
        **kwargs
560
    ):
561
        """
562
        Initialize OpenAI chat execution settings.
563
        
564
        Parameters:
565
        - service_id: Service ID
566
        - max_tokens: Maximum tokens to generate
567
        - temperature: Sampling temperature (0.0 to 2.0)
568
        - top_p: Nucleus sampling parameter
569
        - frequency_penalty: Frequency penalty (-2.0 to 2.0)
570
        - presence_penalty: Presence penalty (-2.0 to 2.0)
571
        - function_choice_behavior: Function calling behavior
572
        - **kwargs: Additional OpenAI parameters
573
        """
574

575
class FunctionChoiceBehavior:
576
    """
577
    Controls how the AI service handles function calling.
578
    """
579
    
580
    @staticmethod
581
    def Auto(auto_invoke: bool = True, filters: dict | None = None) -> FunctionChoiceBehavior:
582
        """
583
        Automatically choose and invoke functions.
584
        
585
        Parameters:
586
        - auto_invoke: Whether to automatically invoke chosen functions
587
        - filters: Function name filters
588
        
589
        Returns:
590
        FunctionChoiceBehavior configured for automatic function calling
591
        """
592
    
593
    @staticmethod
594
    def Required(auto_invoke: bool = True, filters: dict | None = None) -> FunctionChoiceBehavior:
595
        """
596
        Require function calling.
597
        
598
        Parameters:
599
        - auto_invoke: Whether to automatically invoke chosen functions
600
        - filters: Function name filters
601
        
602
        Returns:
603
        FunctionChoiceBehavior configured to require function calling
604
        """
605
    
606
    @staticmethod 
607
    def NoneInvoke() -> FunctionChoiceBehavior:
608
        """
609
        Disable function calling.
610
        
611
        Returns:
612
        FunctionChoiceBehavior configured to disable function calling
613
        """
614
```
615

616
## Usage Examples
617

618
### Basic Chat Completion
619

620
```python
621
from semantic_kernel import Kernel
622
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
623
from semantic_kernel.contents import ChatHistory
624

625
# Initialize service and kernel
626
chat_service = OpenAIChatCompletion(
627
    ai_model_id="gpt-4",
628
    api_key="your-api-key"
629
)
630

631
kernel = Kernel()
632
kernel.add_service(chat_service)
633

634
# Create chat history and get response
635
chat_history = ChatHistory()
636
chat_history.add_user_message("What is the capital of France?")
637

638
# Get response using kernel
639
result = await kernel.invoke_prompt(
640
    "{{$chat_history}}",
641
    chat_history=chat_history
642
)
643
print(result.value)
644
```
645

646
### Multiple AI Services
647

648
```python
649
from semantic_kernel import Kernel
650
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion, OpenAITextEmbedding
651
from semantic_kernel.services import AIServiceSelector
652

653
# Create multiple services
654
chat_service = OpenAIChatCompletion(
655
    service_id="gpt-4-chat",
656
    ai_model_id="gpt-4", 
657
    api_key="your-api-key"
658
)
659

660
embedding_service = OpenAITextEmbedding(
661
    service_id="text-embedding",
662
    ai_model_id="text-embedding-ada-002",
663
    api_key="your-api-key"
664
)
665

666
# Initialize kernel with services
667
kernel = Kernel(services=[chat_service, embedding_service])
668

669
# Services are automatically selected based on capability needed
670
chat_result = await kernel.invoke_prompt("Hello, world!")  # Uses chat service
671
embeddings = await embedding_service.generate_embeddings(["Hello", "World"])  # Direct service usage
672
```