0
# Agents and Multi-Agent Systems
1
2
Autonomous AI agents capable of conversation, collaboration, and orchestrated workflows. Supports various agent types, group chats, orchestration patterns, and complex multi-agent scenarios for building sophisticated AI systems.
3
4
## Capabilities
5
6
### Base Agent Framework
7
8
Core agent classes and interfaces for building autonomous AI agents.
9
10
```python { .api }
11
class Agent:
12
"""
13
Base class for AI agents in Semantic Kernel.
14
"""
15
16
def __init__(
17
self,
18
service_id: str,
19
kernel: Kernel,
20
name: str | None = None,
21
description: str | None = None,
22
instructions: str | None = None
23
):
24
"""
25
Initialize a base agent.
26
27
Parameters:
28
- service_id: ID of the AI service to use
29
- kernel: Kernel instance for execution
30
- name: Name of the agent
31
- description: Description of the agent's purpose
32
- instructions: System instructions for the agent
33
"""
34
35
async def invoke(
36
self,
37
input: str | ChatHistory,
38
**kwargs
39
) -> AgentResponseItem:
40
"""
41
Invoke the agent with input.
42
43
Parameters:
44
- input: Input message or chat history
45
- **kwargs: Additional arguments
46
47
Returns:
48
AgentResponseItem containing the agent's response
49
"""
50
51
@property
52
def name(self) -> str:
53
"""Get the agent name."""
54
55
@property
56
def description(self) -> str:
57
"""Get the agent description."""
58
59
@property
60
def instructions(self) -> str:
61
"""Get the agent instructions."""
62
63
class AgentThread:
64
"""
65
Represents a conversation thread with an agent.
66
"""
67
68
def __init__(self, agent: Agent):
69
"""
70
Initialize an agent thread.
71
72
Parameters:
73
- agent: The agent for this thread
74
"""
75
76
async def add_chat_message(self, message: ChatMessageContent) -> None:
77
"""
78
Add a message to the thread.
79
80
Parameters:
81
- message: Message to add to the thread
82
"""
83
84
async def invoke(self, message: str) -> list[ChatMessageContent]:
85
"""
86
Send a message to the agent and get responses.
87
88
Parameters:
89
- message: Message to send to the agent
90
91
Returns:
92
List of response messages from the agent
93
"""
94
95
@property
96
def messages(self) -> list[ChatMessageContent]:
97
"""Get all messages in the thread."""
98
99
class AgentResponseItem:
100
"""
101
Container for agent response data.
102
"""
103
104
def __init__(
105
self,
106
content: ChatMessageContent,
107
metadata: dict[str, Any] | None = None
108
):
109
"""
110
Initialize agent response item.
111
112
Parameters:
113
- content: The response message content
114
- metadata: Additional response metadata
115
"""
116
117
@property
118
def content(self) -> ChatMessageContent:
119
"""Get the response content."""
120
121
@property
122
def metadata(self) -> dict[str, Any]:
123
"""Get the response metadata."""
124
125
class AgentSpec:
126
"""
127
Specification for configuring an agent.
128
"""
129
130
def __init__(
131
self,
132
name: str,
133
description: str,
134
instructions: str,
135
model_connection: ModelConnection,
136
tools: list[ToolSpec] | None = None
137
):
138
"""
139
Initialize agent specification.
140
141
Parameters:
142
- name: Agent name
143
- description: Agent description
144
- instructions: System instructions
145
- model_connection: AI model connection details
146
- tools: Available tools for the agent
147
"""
148
149
@property
150
def name(self) -> str:
151
"""Get the agent name."""
152
153
@property
154
def description(self) -> str:
155
"""Get the agent description."""
156
157
@property
158
def instructions(self) -> str:
159
"""Get the agent instructions."""
160
161
class AgentRegistry:
162
"""
163
Registry for managing multiple agents.
164
"""
165
166
def __init__(self):
167
"""Initialize agent registry."""
168
169
def register_agent(self, agent: Agent) -> None:
170
"""
171
Register an agent with the registry.
172
173
Parameters:
174
- agent: Agent to register
175
"""
176
177
def get_agent(self, name: str) -> Agent:
178
"""
179
Get an agent by name.
180
181
Parameters:
182
- name: Name of the agent to retrieve
183
184
Returns:
185
The requested agent
186
"""
187
188
def list_agents(self) -> list[str]:
189
"""
190
List all registered agent names.
191
192
Returns:
193
List of agent names
194
"""
195
```
196
197
### Chat Completion Agents
198
199
Agents built on top of chat completion models for conversational AI.
200
201
```python { .api }
202
class ChatCompletionAgent(Agent):
203
"""
204
Agent powered by chat completion models.
205
"""
206
207
def __init__(
208
self,
209
service_id: str,
210
kernel: Kernel,
211
name: str | None = None,
212
description: str | None = None,
213
instructions: str | None = None,
214
execution_settings: PromptExecutionSettings | None = None
215
):
216
"""
217
Initialize a chat completion agent.
218
219
Parameters:
220
- service_id: ID of the chat completion service
221
- kernel: Kernel instance for execution
222
- name: Name of the agent
223
- description: Description of the agent's purpose
224
- instructions: System instructions for the agent
225
- execution_settings: Settings for chat completion
226
"""
227
228
async def invoke(
229
self,
230
input: str | ChatHistory,
231
**kwargs
232
) -> AgentResponseItem:
233
"""
234
Invoke the chat completion agent.
235
236
Parameters:
237
- input: Input message or chat history
238
- **kwargs: Additional arguments
239
240
Returns:
241
AgentResponseItem with the agent's response
242
"""
243
244
class ChatHistoryAgentThread(AgentThread):
245
"""
246
Agent thread that maintains chat history.
247
"""
248
249
def __init__(
250
self,
251
agent: ChatCompletionAgent,
252
chat_history: ChatHistory | None = None
253
):
254
"""
255
Initialize chat history agent thread.
256
257
Parameters:
258
- agent: The chat completion agent
259
- chat_history: Initial chat history (optional)
260
"""
261
262
async def invoke(self, message: str) -> list[ChatMessageContent]:
263
"""
264
Send message and get response while maintaining history.
265
266
Parameters:
267
- message: Message to send to the agent
268
269
Returns:
270
List of response messages from the agent
271
"""
272
273
@property
274
def chat_history(self) -> ChatHistory:
275
"""Get the chat history for this thread."""
276
```
277
278
### OpenAI Assistant Agents
279
280
Agents that integrate with OpenAI's Assistant API.
281
282
```python { .api }
283
class OpenAIAssistantAgent(Agent):
284
"""
285
Agent that uses OpenAI's Assistant API.
286
"""
287
288
def __init__(
289
self,
290
kernel: Kernel,
291
service_id: str,
292
name: str,
293
instructions: str | None = None,
294
description: str | None = None,
295
assistant_id: str | None = None,
296
enable_code_interpreter: bool = False,
297
enable_file_search: bool = False,
298
enable_json_response: bool = False,
299
file_ids: list[str] | None = None,
300
metadata: dict[str, str] | None = None,
301
max_completion_tokens: int | None = None,
302
max_prompt_tokens: int | None = None,
303
parallel_tool_calls_enabled: bool = True,
304
truncation_message_count: int | None = None,
305
temperature: float | None = None,
306
top_p: float | None = None,
307
vector_store_id: str | None = None
308
):
309
"""
310
Initialize OpenAI Assistant agent.
311
312
Parameters:
313
- kernel: Kernel instance for execution
314
- service_id: ID of the OpenAI service
315
- name: Assistant name
316
- instructions: System instructions for the assistant
317
- description: Assistant description
318
- assistant_id: Existing assistant ID (if using existing assistant)
319
- enable_code_interpreter: Enable code interpretation tool
320
- enable_file_search: Enable file search tool
321
- enable_json_response: Enable JSON response format
322
- file_ids: List of file IDs for the assistant
323
- metadata: Additional metadata
324
- max_completion_tokens: Maximum completion tokens
325
- max_prompt_tokens: Maximum prompt tokens
326
- parallel_tool_calls_enabled: Enable parallel tool calls
327
- truncation_message_count: Message truncation count
328
- temperature: Sampling temperature
329
- top_p: Nucleus sampling parameter
330
- vector_store_id: Vector store ID for file search
331
"""
332
333
async def create_thread(self) -> AssistantAgentThread:
334
"""
335
Create a new conversation thread.
336
337
Returns:
338
AssistantAgentThread for conversation
339
"""
340
341
async def delete(self) -> None:
342
"""Delete the assistant from OpenAI."""
343
344
class AzureAssistantAgent(Agent):
345
"""
346
Agent that uses Azure OpenAI's Assistant API.
347
"""
348
349
def __init__(
350
self,
351
kernel: Kernel,
352
service_id: str,
353
name: str,
354
instructions: str | None = None,
355
description: str | None = None,
356
assistant_id: str | None = None,
357
enable_code_interpreter: bool = False,
358
enable_file_search: bool = False,
359
enable_json_response: bool = False,
360
file_ids: list[str] | None = None,
361
metadata: dict[str, str] | None = None,
362
max_completion_tokens: int | None = None,
363
max_prompt_tokens: int | None = None,
364
parallel_tool_calls_enabled: bool = True,
365
truncation_message_count: int | None = None,
366
temperature: float | None = None,
367
top_p: float | None = None,
368
vector_store_id: str | None = None
369
):
370
"""
371
Initialize Azure OpenAI Assistant agent.
372
373
Parameters: (same as OpenAIAssistantAgent)
374
"""
375
376
async def create_thread(self) -> AssistantAgentThread:
377
"""
378
Create a new conversation thread.
379
380
Returns:
381
AssistantAgentThread for conversation
382
"""
383
384
class AssistantAgentThread(AgentThread):
385
"""
386
Thread for OpenAI/Azure Assistant agents.
387
"""
388
389
def __init__(self, agent: OpenAIAssistantAgent | AzureAssistantAgent):
390
"""
391
Initialize assistant agent thread.
392
393
Parameters:
394
- agent: The assistant agent
395
"""
396
397
async def invoke(
398
self,
399
message: str,
400
polling_options: RunPollingOptions | None = None
401
) -> list[ChatMessageContent]:
402
"""
403
Send message and get response from assistant.
404
405
Parameters:
406
- message: Message to send
407
- polling_options: Options for polling the run status
408
409
Returns:
410
List of response messages from the assistant
411
"""
412
413
async def add_chat_message(self, message: ChatMessageContent) -> None:
414
"""
415
Add a message to the assistant thread.
416
417
Parameters:
418
- message: Message to add
419
"""
420
421
class RunPollingOptions:
422
"""
423
Configuration for polling assistant run status.
424
"""
425
426
def __init__(
427
self,
428
sleep_interval: int = 1,
429
max_polling_iterations: int = 50
430
):
431
"""
432
Initialize polling options.
433
434
Parameters:
435
- sleep_interval: Seconds to sleep between polls
436
- max_polling_iterations: Maximum number of polling iterations
437
"""
438
439
@property
440
def sleep_interval(self) -> int:
441
"""Get the sleep interval."""
442
443
@property
444
def max_polling_iterations(self) -> int:
445
"""Get the maximum polling iterations."""
446
```
447
448
### Multi-Agent Group Chat
449
450
Systems for managing conversations between multiple agents.
451
452
```python { .api }
453
class AgentGroupChat:
454
"""
455
Manages conversations between multiple agents.
456
"""
457
458
def __init__(
459
self,
460
agents: list[Agent] | None = None,
461
selection_strategy: SelectionStrategy | None = None,
462
termination_strategy: TerminationStrategy | None = None
463
):
464
"""
465
Initialize agent group chat.
466
467
Parameters:
468
- agents: List of agents participating in the group chat
469
- selection_strategy: Strategy for selecting next agent to speak
470
- termination_strategy: Strategy for determining when to end conversation
471
"""
472
473
def add_agent(self, agent: Agent) -> None:
474
"""
475
Add an agent to the group chat.
476
477
Parameters:
478
- agent: Agent to add to the group
479
"""
480
481
async def invoke(
482
self,
483
message: str,
484
max_turns: int | None = None
485
) -> list[ChatMessageContent]:
486
"""
487
Start or continue a group conversation.
488
489
Parameters:
490
- message: Initial message to start the conversation
491
- max_turns: Maximum number of conversation turns
492
493
Returns:
494
List of all messages in the group conversation
495
"""
496
497
@property
498
def agents(self) -> list[Agent]:
499
"""Get the agents in the group chat."""
500
501
@property
502
def chat_history(self) -> ChatHistory:
503
"""Get the complete chat history."""
504
505
class AgentChat:
506
"""
507
Simplified interface for agent conversations.
508
"""
509
510
def __init__(self, agents: list[Agent]):
511
"""
512
Initialize agent chat.
513
514
Parameters:
515
- agents: List of agents for the chat
516
"""
517
518
async def invoke(
519
self,
520
message: str,
521
termination_strategy: TerminationStrategy | None = None
522
) -> ChatHistory:
523
"""
524
Invoke agent chat with a message.
525
526
Parameters:
527
- message: Message to start the conversation
528
- termination_strategy: Strategy for ending the conversation
529
530
Returns:
531
ChatHistory containing the full conversation
532
"""
533
```
534
535
### Specialized Agent Types
536
537
Additional agent implementations for specific platforms and use cases.
538
539
```python { .api }
540
class BedrockAgent(Agent):
541
"""
542
Agent that integrates with Amazon Bedrock.
543
"""
544
545
def __init__(
546
self,
547
service_id: str,
548
kernel: Kernel,
549
name: str | None = None,
550
description: str | None = None,
551
instructions: str | None = None,
552
agent_id: str | None = None,
553
agent_alias_id: str | None = None
554
):
555
"""
556
Initialize Bedrock agent.
557
558
Parameters:
559
- service_id: ID of the Bedrock service
560
- kernel: Kernel instance for execution
561
- name: Agent name
562
- description: Agent description
563
- instructions: System instructions
564
- agent_id: Bedrock agent ID
565
- agent_alias_id: Bedrock agent alias ID
566
"""
567
568
class BedrockAgentThread(AgentThread):
569
"""
570
Thread for Bedrock agents.
571
"""
572
573
def __init__(self, agent: BedrockAgent):
574
"""
575
Initialize Bedrock agent thread.
576
577
Parameters:
578
- agent: The Bedrock agent
579
"""
580
581
class AzureAIAgent(Agent):
582
"""
583
Agent that integrates with Azure AI services.
584
"""
585
586
def __init__(
587
self,
588
service_id: str,
589
kernel: Kernel,
590
name: str | None = None,
591
description: str | None = None,
592
instructions: str | None = None,
593
settings: AzureAIAgentSettings | None = None
594
):
595
"""
596
Initialize Azure AI agent.
597
598
Parameters:
599
- service_id: ID of the Azure AI service
600
- kernel: Kernel instance for execution
601
- name: Agent name
602
- description: Agent description
603
- instructions: System instructions
604
- settings: Azure AI agent settings
605
"""
606
607
class AzureAIAgentThread(AgentThread):
608
"""
609
Thread for Azure AI agents.
610
"""
611
612
def __init__(self, agent: AzureAIAgent):
613
"""
614
Initialize Azure AI agent thread.
615
616
Parameters:
617
- agent: The Azure AI agent
618
"""
619
620
class CopilotStudioAgent(Agent):
621
"""
622
Agent that integrates with Microsoft Copilot Studio.
623
"""
624
625
def __init__(
626
self,
627
service_id: str,
628
kernel: Kernel,
629
name: str | None = None,
630
description: str | None = None,
631
instructions: str | None = None,
632
settings: CopilotStudioAgentSettings | None = None
633
):
634
"""
635
Initialize Copilot Studio agent.
636
637
Parameters:
638
- service_id: ID of the Copilot Studio service
639
- kernel: Kernel instance for execution
640
- name: Agent name
641
- description: Agent description
642
- instructions: System instructions
643
- settings: Copilot Studio agent settings
644
"""
645
646
class CopilotStudioAgentThread(AgentThread):
647
"""
648
Thread for Copilot Studio agents.
649
"""
650
651
def __init__(self, agent: CopilotStudioAgent):
652
"""
653
Initialize Copilot Studio agent thread.
654
655
Parameters:
656
- agent: The Copilot Studio agent
657
"""
658
659
class AutoGenConversableAgent(Agent):
660
"""
661
Agent that integrates with the AutoGen framework.
662
"""
663
664
def __init__(
665
self,
666
service_id: str,
667
kernel: Kernel,
668
name: str | None = None,
669
description: str | None = None,
670
instructions: str | None = None,
671
system_message: str | None = None
672
):
673
"""
674
Initialize AutoGen conversable agent.
675
676
Parameters:
677
- service_id: ID of the AI service
678
- kernel: Kernel instance for execution
679
- name: Agent name
680
- description: Agent description
681
- instructions: System instructions
682
- system_message: AutoGen system message
683
"""
684
685
class AutoGenConversableAgentThread(AgentThread):
686
"""
687
Thread for AutoGen conversable agents.
688
"""
689
690
def __init__(self, agent: AutoGenConversableAgent):
691
"""
692
Initialize AutoGen conversable agent thread.
693
694
Parameters:
695
- agent: The AutoGen conversable agent
696
"""
697
```
698
699
### Agent Orchestration
700
701
Orchestration patterns for coordinating multiple agents.
702
703
```python { .api }
704
class ConcurrentOrchestration:
705
"""
706
Orchestration that runs agents concurrently.
707
"""
708
709
def __init__(self, agents: list[Agent]):
710
"""
711
Initialize concurrent orchestration.
712
713
Parameters:
714
- agents: List of agents to orchestrate
715
"""
716
717
async def invoke(
718
self,
719
message: str,
720
**kwargs
721
) -> list[AgentResponseItem]:
722
"""
723
Invoke all agents concurrently.
724
725
Parameters:
726
- message: Message to send to all agents
727
- **kwargs: Additional arguments
728
729
Returns:
730
List of responses from all agents
731
"""
732
733
class SequentialOrchestration:
734
"""
735
Orchestration that runs agents in sequence.
736
"""
737
738
def __init__(self, agents: list[Agent]):
739
"""
740
Initialize sequential orchestration.
741
742
Parameters:
743
- agents: List of agents in execution order
744
"""
745
746
async def invoke(
747
self,
748
message: str,
749
**kwargs
750
) -> list[AgentResponseItem]:
751
"""
752
Invoke agents sequentially.
753
754
Parameters:
755
- message: Initial message for the sequence
756
- **kwargs: Additional arguments
757
758
Returns:
759
List of responses from each agent in sequence
760
"""
761
762
class HandoffOrchestration:
763
"""
764
Orchestration with agent handoff capabilities.
765
"""
766
767
def __init__(
768
self,
769
agents: list[Agent],
770
handoffs: OrchestrationHandoffs
771
):
772
"""
773
Initialize handoff orchestration.
774
775
Parameters:
776
- agents: List of available agents
777
- handoffs: Handoff configuration between agents
778
"""
779
780
async def invoke(
781
self,
782
message: str,
783
initial_agent: str | None = None,
784
**kwargs
785
) -> list[AgentResponseItem]:
786
"""
787
Invoke with agent handoff capabilities.
788
789
Parameters:
790
- message: Initial message
791
- initial_agent: Name of the initial agent to start with
792
- **kwargs: Additional arguments
793
794
Returns:
795
List of responses including handoffs
796
"""
797
798
class GroupChatOrchestration:
799
"""
800
Orchestration for group chat scenarios.
801
"""
802
803
def __init__(
804
self,
805
agents: list[Agent],
806
chat_manager: GroupChatManager
807
):
808
"""
809
Initialize group chat orchestration.
810
811
Parameters:
812
- agents: List of agents in the group
813
- chat_manager: Manager for the group chat
814
"""
815
816
async def invoke(
817
self,
818
message: str,
819
max_turns: int | None = None,
820
**kwargs
821
) -> ChatHistory:
822
"""
823
Invoke group chat orchestration.
824
825
Parameters:
826
- message: Initial message for the group
827
- max_turns: Maximum number of conversation turns
828
- **kwargs: Additional arguments
829
830
Returns:
831
ChatHistory containing the group conversation
832
"""
833
```
834
835
## Usage Examples
836
837
### Basic Agent Setup
838
839
```python
840
from semantic_kernel import Kernel
841
from semantic_kernel.agents import ChatCompletionAgent
842
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
843
844
# Setup kernel with chat service
845
kernel = Kernel()
846
chat_service = OpenAIChatCompletion(
847
service_id="gpt-4-agent",
848
ai_model_id="gpt-4",
849
api_key="your-api-key"
850
)
851
kernel.add_service(chat_service)
852
853
# Create an agent
854
agent = ChatCompletionAgent(
855
service_id="gpt-4-agent",
856
kernel=kernel,
857
name="Assistant",
858
instructions="You are a helpful AI assistant.",
859
description="General purpose AI assistant"
860
)
861
862
# Use the agent
863
response = await agent.invoke("Hello, can you help me with Python?")
864
print(response.content.content)
865
```
866
867
### Multi-Agent Group Chat
868
869
```python
870
from semantic_kernel.agents import AgentGroupChat, ChatCompletionAgent
871
872
# Create multiple specialized agents
873
researcher = ChatCompletionAgent(
874
service_id="gpt-4-agent",
875
kernel=kernel,
876
name="Researcher",
877
instructions="You are a research specialist. Focus on gathering facts and data."
878
)
879
880
writer = ChatCompletionAgent(
881
service_id="gpt-4-agent",
882
kernel=kernel,
883
name="Writer",
884
instructions="You are a professional writer. Focus on clear, engaging content."
885
)
886
887
critic = ChatCompletionAgent(
888
service_id="gpt-4-agent",
889
kernel=kernel,
890
name="Critic",
891
instructions="You are a constructive critic. Provide feedback and suggestions."
892
)
893
894
# Create group chat
895
group_chat = AgentGroupChat(agents=[researcher, writer, critic])
896
897
# Start conversation
898
messages = await group_chat.invoke(
899
"I need help writing an article about renewable energy",
900
max_turns=10
901
)
902
903
# Review conversation
904
for message in messages:
905
print(f"{message.name}: {message.content}")
906
```
907
908
### OpenAI Assistant Integration
909
910
```python
911
from semantic_kernel.agents import OpenAIAssistantAgent
912
913
# Create assistant agent with tools
914
assistant = OpenAIAssistantAgent(
915
kernel=kernel,
916
service_id="openai-assistant",
917
name="Code Helper",
918
instructions="You are a coding assistant with access to code interpretation.",
919
description="Helps with code analysis and execution",
920
enable_code_interpreter=True,
921
enable_file_search=True
922
)
923
924
# Create thread and have conversation
925
thread = await assistant.create_thread()
926
responses = await thread.invoke("Can you help me analyze this Python script?")
927
928
for response in responses:
929
print(response.content)
930
```