From 648dd7c38ba2a2a7caac6931a66cf50d0bc59a03 Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Thu, 13 Feb 2025 11:34:00 +0900 Subject: [PATCH 01/70] Add python process how-to guides --- .../process/examples/example-cycles.md | 222 ++++++++++++++++- .../process/examples/example-first-process.md | 227 ++++++++++++++++-- 2 files changed, 421 insertions(+), 28 deletions(-) diff --git a/semantic-kernel/Frameworks/process/examples/example-cycles.md b/semantic-kernel/Frameworks/process/examples/example-cycles.md index cfff1cb3..d46a2424 100644 --- a/semantic-kernel/Frameworks/process/examples/example-cycles.md +++ b/semantic-kernel/Frameworks/process/examples/example-cycles.md @@ -87,16 +87,74 @@ public class ProofreadStep : KernelProcessStep } ``` +A new step named `ProofreadStep` has been created. This step uses the LLM to grade the generated documentation as discussed above. Notice that this step conditionally emits either the `DocumentationApproved` event or the `DocumentationRejected` event based on the response from the LLM. In the case of `DocumentationApproved`, the event will include the approved documentation as it's payload and in the case of `DocumentationRejected` it will include the suggestions from the proofreader. ::: zone-end ::: zone pivot="programming-language-python" +```python +# A sample response model for the ProofreadingStep structured output +class ProofreadingResponse(BaseModel): + """A class to represent the response from the proofreading step.""" + + meets_expectations: bool = Field(description="Specifies if the proposed docs meets the standards for publishing.") + explanation: str = Field(description="An explanation of why the documentation does or does not meet expectations.") + suggestions: list[str] = Field(description="List of suggestions, empty if there no suggestions for improvement.") + + +# A process step to proofread documentation +class ProofreadStep(KernelProcessStep): + @kernel_function + async def proofread_documentation(self, docs: str, context: KernelProcessStepContext, kernel: Kernel) -> None: + print(f"{ProofreadStep.__name__}\n\t Proofreading product documentation...") + + system_prompt = """ + Your job is to proofread customer facing documentation for a new product from Contoso. You will be provide with + proposed documentation for a product and you must do the following things: + + 1. Determine if the documentation is passes the following criteria: + 1. Documentation must use a professional tone. + 1. Documentation should be free of spelling or grammar mistakes. + 1. Documentation should be free of any offensive or inappropriate language. + 1. Documentation should be technically accurate. + 2. If the documentation does not pass 1, you must write detailed feedback of the changes that are needed to + improve the documentation. + """ + + chat_history = ChatHistory(system_message=system_prompt) + chat_history.add_user_message(docs) + + # Use structured output to ensure the response format is easily parsable + chat_service, settings = kernel.select_ai_service(type=ChatCompletionClientBase) + assert isinstance(chat_service, ChatCompletionClientBase) # nosec + assert isinstance(settings, OpenAIChatPromptExecutionSettings) # nosec + + settings.response_format = ProofreadingResponse + + response = await chat_service.get_chat_message_content(chat_history=chat_history, settings=settings) + + formatted_response: ProofreadingResponse = ProofreadingResponse.model_validate_json(response.content) + + suggestions_text = "\n\t\t".join(formatted_response.suggestions) + print( + f"\n\tGrade: {'Pass' if formatted_response.meets_expectations else 'Fail'}\n\t" + f"Explanation: {formatted_response.explanation}\n\t" + f"Suggestions: {suggestions_text}" + ) + + if formatted_response.meets_expectations: + await context.emit_event(process_event="documentation_approved", data=docs) + else: + await context.emit_event( + process_event="documentation_rejected", + data={"explanation": formatted_response.explanation, "suggestions": formatted_response.suggestions}, + ) +``` +A new step named `ProofreadStep` has been created. This step uses the LLM to grade the generated documentation as discussed above. Notice that this step conditionally emits either the `documentation_approved` event or the `documentation_rejected` event based on the response from the LLM. In the case of `documentation_approved`, the event will include the approved documentation as it's payload and in the case of `documentation_rejected` it will include the suggestions from the proofreader. ::: zone-end ::: zone pivot="programming-language-java" ::: zone-end -A new step named `ProofreadStep` has been created. This step uses the LLM to grade the generated documentation as discussed above. Notice that this step conditionally emits either the `DocumentationApproved` event or the `DocumentationRejected` event based on the response from the LLM. In the case of `DocumentationApproved`, the event will include the approved documentation as it's payload and in the case of `DocumentationRejected` it will include the suggestions from the proofreader. - ### Update the documentation generation step ::: zone pivot="programming-language-csharp" @@ -160,16 +218,68 @@ public class GenerateDocumentationStep : KernelProcessStep None: + print(f"{GenerateDocumentationStep.__name__}\n\t Generating documentation for provided product_info...") + + self.state.chat_history.add_user_message(f"Product Information:\n{product_info}") + + chat_service, settings = kernel.select_ai_service(type=ChatCompletionClientBase) + assert isinstance(chat_service, ChatCompletionClientBase) # nosec + + response = await chat_service.get_chat_message_content(chat_history=self.state.chat_history, settings=settings) + + await context.emit_event(process_event="documentation_generated", data=str(response)) + + @kernel_function + async def apply_suggestions(self, suggestions: str, context: KernelProcessStepContext, kernel: Kernel) -> None: + print(f"{GenerateDocumentationStep.__name__}\n\t Rewriting documentation with provided suggestions...") + + self.state.chat_history.add_user_message( + f"Rewrite the documentation with the following suggestions:\n\n{suggestions}" + ) + + chat_service, settings = kernel.select_ai_service(type=ChatCompletionClientBase) + assert isinstance(chat_service, ChatCompletionClientBase) # nosec + + generated_documentation_response = await chat_service.get_chat_message_content( + chat_history=self.state.chat_history, settings=settings + ) + + await context.emit_event(process_event="documentation_generated", data=str(generated_documentation_response)) +``` + +The `GenerateDocumentationStep` has been updated to include a new KernelFunction. The new function will be used to apply suggested changes to the documentation if our proofreading step requires them. Notice that both functions for generating or rewriting documentation emit the same event named `documentation_generated` indicating that new documentation is available. ::: zone-end ::: zone pivot="programming-language-java" ::: zone-end -The `GenerateDocumentationStep` has been updated to include a new KernelFunction. The new function will be used to apply suggested changes to the documentation if our proofreading step requires them. Notice that both functions for generating or rewriting documentation emit the same event named `DocumentationGenerated` indicating that new documentation is available. - ### Flow updates ::: zone pivot="programming-language-csharp" @@ -209,25 +319,64 @@ var process = processBuilder.Build(); return process; ``` +Our updated process routing now does the following: +- When an external event with `id = Start` is sent to the process, this event and its associated data will be sent to the `infoGatheringStep`. +- When the `infoGatheringStep` finishes running, send the returned object to the `docsGenerationStep`. +- When the `docsGenerationStep` finishes running, send the generated docs to the `docsProofreadStep`. +- When the `docsProofreadStep` rejects our documentation and provides suggestions, send the suggestions back to the `docsGenerationStep`. +- Finally, when the `docsProofreadStep` approves our documentation, send the returned object to the `docsPublishStep`. ::: zone-end ::: zone pivot="programming-language-python" +```python +# Create the process builder +process_builder = ProcessBuilder(name="DocumentationGeneration") + +# Add the steps +info_gathering_step = process_builder.add_step(GatherProductInfoStep) +docs_generation_step = process_builder.add_step(GenerateDocumentationStep) +docs_proofread_step = process_builder.add_step(ProofreadStep) # Add new step here +docs_publish_step = process_builder.add_step(PublishDocumentationStep) + +# Orchestrate the events +process_builder.on_input_event("Start").send_event_to(target=info_gathering_step) + +info_gathering_step.on_function_result().send_event_to( + target=docs_generation_step, function_name="generate_documentation", parameter_name="product_info" +) + +docs_generation_step.on_event("documentation_generated").send_event_to( + target=docs_proofread_step, parameter_name="docs" +) + +docs_proofread_step.on_event("documentation_rejected").send_event_to( + target=docs_generation_step, + function_name="apply_suggestions", + parameter_name="suggestions", +) + +docs_proofread_step.on_event("documentation_approved").send_event_to(target=docs_publish_step) +``` + +Our updated process routing now does the following: +- When an external event with `id = Start` is sent to the process, this event and its associated data will be sent to the `info_gathering_step`. +- When the `info_gathering_step` finishes running, send the returned object to the `docs_generation_step`. +- When the `docs_generation_step` finishes running, send the generated docs to the `docs_proofread_step`. +- When the `docs_proofread_step` rejects our documentation and provides suggestions, send the suggestions back to the `docs_generation_step`. +- Finally, when the `docs_proofread_step` approves our documentation, send the returned object to the `docs_publish_step`. ::: zone-end ::: zone pivot="programming-language-java" ::: zone-end -Our updated process routing now does the following: -- When an external event with `id = Start` is sent to the process, this event and its associated data will be sent to the `infoGatheringStep` step. -- When the `infoGatheringStep` finishes running, send the returned object to the `docsGenerationStep` step. -- When the `docsGenerationStep` finishes running, send the generated docs to the `docsProofreadStep` step. -- When the `docsProofreadStep` rejects our documentation and provides suggestions, send the suggestions back to the `docsGenerationStep`. -- Finally, when the `docsProofreadStep` approves our documentation, send the returned object to the `docsPublishStep` step. + ### Build and run the Process Running our updated process shows the following output in the console: +::: zone pivot="programming-language-csharp" + ```md GatherProductInfoStep: Gathering product information for product named Contoso GlowBrew @@ -289,6 +438,59 @@ Introducing GlowBrew-your new partner in coffee brewing that brings together adv We hope you enjoy your GlowBrew experience and that it brings a delightful blend of flavor and brightness to your coffee moments! ``` +::: zone-end + +::: zone pivot="programming-language-python" + +```md +GatherProductInfoStep + Gathering product information for Product Name: Contoso GlowBrew +GenerateDocumentationStep + Generating documentation for provided product_info... +ProofreadStep + Proofreading product documentation... + + Grade: Pass + Explanation: The GlowBrew AI Coffee Machine User Guide meets all the required criteria for publishing. The document maintains a professional tone throughout, is free from spelling and grammatical errors, contains no offensive or inappropriate content, and appears to be technically accurate in its description of the product features and troubleshooting advice. + Suggestions: +PublishDocumentationStep + Publishing product documentation: + +# GlowBrew AI Coffee Machine User Guide + +Welcome to the future of coffee making with the GlowBrew AI Coffee Machine! Step into a world where cutting-edge technology meets exquisite taste, creating a coffee experience like no other. Designed for coffee aficionados and tech enthusiasts alike, the GlowBrew promises not just a cup of coffee, but an adventure for your senses. + +## Key Features + +### Luminous Brew Technology +Illuminate your mornings with the GlowBrew's mesmerizing programmable LED light shows. With an unmatched number of LEDs, the GlowBrew can transform your kitchen ambiance to sync perfectly with each stage of the brewing process. Choose from a spectrum of colors and patterns to set the perfect mood, whether you're winding down with a rich decaf or kick-starting your day with a bold espresso. + +### AI Taste Assistant +Expand your coffee horizons with the AI Taste Assistant, your personal barista that learns and evolves with your palate. Over time, GlowBrew adapts to your preferences, suggesting new and exciting brew combinations. Experience a variety of flavors, from single-origin specialties to intricate blend recipes, tailored to your unique taste. + +### Gourmet Aroma Diffusion +Enhance your coffee experience with unrivaled aromatic pleasure. The GlowBrew's built-in aroma diffusers release a carefully calibrated scent profile that awakens your senses, heightening anticipation for your first sip. It's not just a coffee machine, it's an indulgent sensory journey. + +## Troubleshooting + +### LED Lights Malfunctioning +If you experience issues with your LED lights: + +1. **Reset the LED Settings**: Use the GlowBrew app to navigate to the lighting settings and perform a reset. +2. **Check LED Connections**: Open the GlowBrew machine and ensure all LED wiring connections are secure. +3. **Perform a Factory Reset**: As a last resort, a full factory reset can resolve persistent issues. Follow the instructions in the user manual to perform this reset safely. + +## Experience the Glow + +With GlowBrew, every cup of coffee is an art form that combines luminous aesthetics, an intuitive learning AI, and the intoxicating allure of rich aromas. Make each morning magical and every break a celebration with the GlowBrew AI Coffee Machine. Brew brilliantly, taste innovatively, and glow endlessly. + +For more support, explore our comprehensive FAQ section or contact our dedicated customer service team. +``` +::: zone-end + +::: zone pivot="programming-language-java" +::: zone-end + ## What's Next? diff --git a/semantic-kernel/Frameworks/process/examples/example-first-process.md b/semantic-kernel/Frameworks/process/examples/example-first-process.md index 2fbe00d7..447fa929 100644 --- a/semantic-kernel/Frameworks/process/examples/example-first-process.md +++ b/semantic-kernel/Frameworks/process/examples/example-first-process.md @@ -34,6 +34,7 @@ dotnet add package Microsoft.SemanticKernel.Process.LocalRuntime --version 1.33. ::: zone-end ::: zone pivot="programming-language-python" +pip install semantic-kernel==1.20.0 ::: zone-end ::: zone pivot="programming-language-java" @@ -144,15 +145,109 @@ public class PublishDocumentationStep : KernelProcessStep } ``` +The code above defines the three steps we need for our Process. There are a few points to call out here: +- In Semantic Kernel, a `KernelFunction` defines a block of code that is invocable by native code or by an LLM. In the case of the Process framework, `KernelFunction`s are the invocable members of a Step and each step requires at least one KernelFunction to be defined. +- The Process Framework has support for stateless and stateful steps. Stateful steps automatically checkpoint their progress and maintain state over multiple invocations. The `GenerateDocumentationStep` provides an example of this where the `GeneratedDocumentationState` class is used to persist the `ChatHistory` object. +- Steps can manually emit events by calling `EmitEventAsync` on the `KernelProcessStepContext` object. To get an instance of `KernelProcessStepContext` just add it as a parameter on your KernelFunction and the framework will automatically inject it. ::: zone-end ::: zone pivot="programming-language-python" -::: zone-end +```python +import asyncio +from typing import ClassVar + +from pydantic import BaseModel, Field + +from semantic_kernel import Kernel +from semantic_kernel.connectors.ai.chat_completion_client_base import ChatCompletionClientBase +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion +from semantic_kernel.contents import ChatHistory +from semantic_kernel.functions import kernel_function +from semantic_kernel.processes import ProcessBuilder +from semantic_kernel.processes.kernel_process import KernelProcessStep, KernelProcessStepContext, KernelProcessStepState +from semantic_kernel.processes.local_runtime import KernelProcessEvent, start + + +# A process step to gather information about a product +class GatherProductInfoStep(KernelProcessStep): + @kernel_function + def gather_product_information(self, product_name: str) -> str: + print(f"{GatherProductInfoStep.__name__}\n\t Gathering product information for Product Name: {product_name}") + + return """ +Product Description: + +GlowBrew is a revolutionary AI driven coffee machine with industry leading number of LEDs and +programmable light shows. The machine is also capable of brewing coffee and has a built in grinder. + +Product Features: +1. **Luminous Brew Technology**: Customize your morning ambiance with programmable LED lights that sync + with your brewing process. +2. **AI Taste Assistant**: Learns your taste preferences over time and suggests new brew combinations + to explore. +3. **Gourmet Aroma Diffusion**: Built-in aroma diffusers enhance your coffee's scent profile, energizing + your senses before the first sip. + +Troubleshooting: +- **Issue**: LED Lights Malfunctioning + - **Solution**: Reset the lighting settings via the app. Ensure the LED connections inside the + GlowBrew are secure. Perform a factory reset if necessary. + """ + + +# A sample step state model for the GenerateDocumentationStep +class GeneratedDocumentationState(BaseModel): + """State for the GenerateDocumentationStep.""" + + chat_history: ChatHistory | None = None + + +# A process step to generate documentation for a product +class GenerateDocumentationStep(KernelProcessStep[GeneratedDocumentationState]): + state: GeneratedDocumentationState = Field(default_factory=GeneratedDocumentationState) + + system_prompt: ClassVar[str] = """ +Your job is to write high quality and engaging customer facing documentation for a new product from Contoso. You will +be provide with information about the product in the form of internal documentation, specs, and troubleshooting guides +and you must use this information and nothing else to generate the documentation. If suggestions are provided on the +documentation you create, take the suggestions into account and rewrite the documentation. Make sure the product +sounds amazing. +""" + + async def activate(self, state: KernelProcessStepState[GeneratedDocumentationState]): + self.state = state.state + if self.state.chat_history is None: + self.state.chat_history = ChatHistory(system_message=self.system_prompt) + self.state.chat_history + + @kernel_function + async def generate_documentation( + self, context: KernelProcessStepContext, product_info: str, kernel: Kernel + ) -> None: + print(f"{GenerateDocumentationStep.__name__}\n\t Generating documentation for provided product_info...") + + self.state.chat_history.add_user_message(f"Product Information:\n{product_info}") + + chat_service, settings = kernel.select_ai_service(type=ChatCompletionClientBase) + assert isinstance(chat_service, ChatCompletionClientBase) # nosec + + response = await chat_service.get_chat_message_content(chat_history=self.state.chat_history, settings=settings) + + await context.emit_event(process_event="documentation_generated", data=str(response)) + + +# A process step to publish documentation +class PublishDocumentationStep(KernelProcessStep): + @kernel_function + async def publish_documentation(self, docs: str) -> None: + print(f"{PublishDocumentationStep.__name__}\n\t Publishing product documentation:\n\n{docs}") +``` The code above defines the three steps we need for our Process. There are a few points to call out here: - In Semantic Kernel, a `KernelFunction` defines a block of code that is invocable by native code or by an LLM. In the case of the Process framework, `KernelFunction`s are the invocable members of a Step and each step requires at least one KernelFunction to be defined. - The Process Framework has support for stateless and stateful steps. Stateful steps automatically checkpoint their progress and maintain state over multiple invocations. The `GenerateDocumentationStep` provides an example of this where the `GeneratedDocumentationState` class is used to persist the `ChatHistory` object. -- Steps can manually emit events by calling `EmitEventAsync` on the `KernelProcessStepContext` object. To get an instance of `KernelProcessStepContext` just add it as a parameter on your KernelFunction and the framework will automatically inject it. +- Steps can manually emit events by calling `emit_event` on the `KernelProcessStepContext` object. To get an instance of `KernelProcessStepContext` just add it as a parameter on your KernelFunction and the framework will automatically inject it. +::: zone-end ### Define the process flow @@ -181,13 +276,51 @@ docsGenerationStep .SendEventTo(new(docsPublishStep)); ``` +There are a few things going on here so let's break it down step by step. + +1. Create the builder: +Processes use a builder pattern to simplify wiring everything up. The builder provides methods for managing the steps within a process and for managing the lifecycle of the process. + +1. Add the steps: +Steps are added to the process by calling the `AddStepFromType` method of the builder. This allows the Process Framework to manage the lifecycle of steps by instantiating instances as needed. In this case we've added three steps to the process and created a variable for each one. These variables give us a handle to the unique instance of each step that we can use next to define the orchestration of events. + +1. Orchestrate the events: +This is where the routing of events from step to step are defined. In this case we have the following routes: + - When an external event with `id = Start` is sent to the process, this event and its associated data will be sent to the `infoGatheringStep` step. + - When the `infoGatheringStep` finishes running, send the returned object to the `docsGenerationStep` step. + - Finally, when the `docsGenerationStep` finishes running, send the returned object to the `docsPublishStep` step. + +> [!TIP] +> **_Event Routing in Process Framework:_** You may be wondering how events that are sent to steps are routed to KernelFunctions within the step. In the code above, each step has only defined a single KernelFunction and each KernelFunction has only a single parameter (other than Kernel and the step context which are special, more on that later). When the event containing the generated documentation is sent to the `docsPublishStep` it will be passed to the `docs` parameter of the `PublishDocumentation` KernelFunction of the `docsGenerationStep` step because there is no other choice. However, steps can have multiple KernelFunctions and KernelFunctions can have multiple parameters, in these advanced scenarios you need to specify the target function and parameter. + ::: zone-end ::: zone pivot="programming-language-python" -::: zone-end +```python +# Create the process builder +process_builder = ProcessBuilder(name="DocumentationGeneration") -::: zone pivot="programming-language-java" -::: zone-end +# Add the steps +info_gathering_step = process_builder.add_step(GatherProductInfoStep) +docs_generation_step = process_builder.add_step(GenerateDocumentationStep) +docs_publish_step = process_builder.add_step(PublishDocumentationStep) + +# Orchestrate the events +process_builder.on_input_event("Start").send_event_to(target=info_gathering_step) + +info_gathering_step.on_function_result().send_event_to( + target=docs_generation_step, function_name="generate_documentation", parameter_name="product_info" +) + +docs_generation_step.on_event("documentation_generated").send_event_to(target=docs_publish_step) + +# Configure the kernel with an AI Service and connection details, if necessary +kernel = Kernel() +kernel.add_service(AzureChatCompletion()) + +# Build the process +kernel_process = process_builder.build() +``` There are a few things going on here so let's break it down step by step. @@ -195,16 +328,21 @@ There are a few things going on here so let's break it down step by step. Processes use a builder pattern to simplify wiring everything up. The builder provides methods for managing the steps within a process and for managing the lifecycle of the process. 1. Add the steps: -Steps are added to the process by calling the `AddStepFromType` method of the builder. This allows the Process Framework to manage the lifecycle of steps by instantiating instances as needed. In this case we've added three steps to the process and created a variable for each one. These variables give us a handle to the unique instance of each step that we can use next to define the orchestration of events. +Steps are added to the process by calling the `add_step` method of the builder, which adds the step type to the builder. This allows the Process Framework to manage the lifecycle of steps by instantiating instances as needed. In this case we've added three steps to the process and created a variable for each one. These variables give us a handle to the unique instance of each step that we can use next to define the orchestration of events. 1. Orchestrate the events: This is where the routing of events from step to step are defined. In this case we have the following routes: - - When an external event with `id = Start` is sent to the process, this event and its associated data will be sent to the `infoGatheringStep` step. - - When the `infoGatheringStep` finishes running, send the returned object to the `docsGenerationStep` step. - - Finally, when the `docsGenerationStep` finishes running, send the returned object to the `docsPublishStep` step. + - When an external event with `id = Start` is sent to the process, this event and its associated data will be sent to the `info_gathering_step`. + - When the `info_gathering_step` finishes running, send the returned object to the `docs_generation_step`. + - Finally, when the `docs_generation_step` finishes running, send the returned object to the `docs_publish_step`. > [!TIP] -> **_Event Routing in Process Framework:_** You may be wondering how events that are sent to steps are routed to KernelFunctions within the step. In the code above, each step has only defined a single KernelFunction and each KernelFunction has only a single parameter (other than Kernel and the step context which are special, more on that later). When the event containing the generated documentation is sent to the `docsPublishStep` it will be passed to the `docs` parameter of the `PublishDocumentation` KernelFunction of the `docsGenerationStep` step because there is no other choice. However, steps can have multiple KernelFunctions and KernelFunctions can have multiple parameters in in these advanced scenarios you need to specify the target function and parameter. +> **_Event Routing in Process Framework:_** You may be wondering how events that are sent to steps are routed to KernelFunctions within the step. In the code above, each step has only defined a single KernelFunction and each KernelFunction has only a single parameter (other than Kernel and the step context which are special, more on that later). When the event containing the generated documentation is sent to the `docs_publish_step` it will be passed to the `docs` parameter of the `publish_documentation` KernelFunction of the `docs_generation_step` because there is no other choice. However, steps can have multiple KernelFunctions and KernelFunctions can have multiple parameters, in these advanced scenarios you need to specify the target function and parameter. + +::: zone-end + +::: zone pivot="programming-language-java" +::: zone-end ### Build and run the Process @@ -221,14 +359,6 @@ var process = processBuilder.Build(); await process.StartAsync(kernel, new KernelProcessEvent { Id = "Start", Data = "Contoso GlowBrew" }); ``` -::: zone-end - -::: zone pivot="programming-language-python" -::: zone-end - -::: zone pivot="programming-language-java" -::: zone-end - We build the process and call `StartAsync` to run it. Our process is expecting an initial external event called `Start` to kick things off and so we provide that as well. Running this process shows the following output in the Console: ``` @@ -277,6 +407,67 @@ Join the growing community of GlowBrew enthusiasts today, and redefine how you e Ready to embark on an extraordinary coffee journey? Discover the perfect blend of technology and flavor with Contoso's GlowBrew. Your coffee awaits! ``` +::: zone-end + +::: zone pivot="programming-language-python" + +```python +# Configure the kernel with an AI Service and connection details, if necessary +kernel = Kernel() +kernel.add_service(AzureChatCompletion()) + +# Build the process +kernel_process = process_builder.build() + +# Start the process +async with await start( + process=kernel_process, + kernel=kernel, + initial_event=KernelProcessEvent(id="Start", data="Contoso GlowBrew"), +) as process_context: + _ = await process_context.get_state() +``` + +We build the process and call `start` with the asynchronous context manager to run it. Our process is expecting an initial external event called `Start` to kick things off and so we provide that as well. Running this process shows the following output in the Console: + +``` +GatherProductInfoStep + Gathering product information for Product Name: Contoso GlowBrew +GenerateDocumentationStep + Generating documentation for provided product_info... +PublishDocumentationStep + Publishing product documentation: + +# GlowBrew AI-Driven Coffee Machine: Elevate Your Coffee Experience + +Welcome to the future of coffee enjoyment with GlowBrew, the AI-driven coffee machine that not only crafts the perfect cup but does so with a light show that brightens your day. Designed for coffee enthusiasts and tech aficionados alike, GlowBrew combines cutting-edge brewing technology with an immersive lighting experience to start every day on a bright note. + +## Unleash the Power of Luminous Brew Technology + +With GlowBrew, your mornings will never be dull. The industry-leading number of programmable LEDs offers endless possibilities for customizing your coffee-making ritual. Sync the light show with the brewing process to create a visually stimulating ambiance that transforms your kitchen into a vibrant café each morning. + +## Discover New Flavor Dimensions with the AI Taste Assistant + +Leave the traditional coffee routines behind and say hello to personalization sophistication. The AI Taste Assistant learns and adapts to your unique preferences over time. Whether you prefer a strong espresso or a light latte, the assistant suggests new brew combinations tailored to your palate, inviting you to explore a world of flavors you never knew existed. + +## Heighten Your Senses with Gourmet Aroma Diffusion + +The moment you step into the room, let the GlowBrew’s built-in aroma diffusers captivate your senses. This feature is designed to enrich your coffee’s scent profile, ensuring every cup you brew is a multi-sensory delight. Let the burgeoning aroma energize you before the very first sip. + +## Troubleshooting Guide: LED Lights Malfunctioning + +Occasionally, you might encounter an issue with the LED lights not functioning as intended. Here’s how to resolve it efficiently: + +- **Reset Lighting Settings**: Start by using the GlowBrew app to reset the lighting configurations to their default state. +- **Check Connections**: Ensure that all LED connections inside your GlowBrew machine are secure and properly connected. +- **Perform a Factory Reset**: If the problem persists, perform a factory reset on your GlowBrew to restore all settings to their original state. + +Experience the art of coffee making like never before with the GlowBrew AI-driven coffee machine. From captivating light shows to aromatic sensations, every feature is engineered to enhance your daily brew. Brew, savor, and glow with GlowBrew. +``` +::: zone-end + +::: zone pivot="programming-language-java" +::: zone-end ## What's Next? From 2b565e2266090787f9024af9923818f8d7c46a9e Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Thu, 13 Feb 2025 19:47:59 +0900 Subject: [PATCH 02/70] Improve Python agent learn site samples. --- .../examples/example-agent-collaboration.md | 418 ++++++++++-------- .../agent/examples/example-assistant-code.md | 83 ++-- .../examples/example-assistant-search.md | 5 +- 3 files changed, 285 insertions(+), 221 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md index 3206ad89..39b1ea49 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md +++ b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md @@ -26,6 +26,8 @@ The approach will be broken down step-by-step to high-light the key parts of the Before proceeding with feature coding, make sure your development environment is fully set up and configured. +This sample uses an optional text file as part of processing. If you'd like to use it, you may download it [here](https://github.com/microsoft/semantic-kernel/blob/3f22587de5a6f42b41bd268f237547e1034de7df/dotnet/samples/LearnResources/Resources/WomensSuffrage.txt). Place the file in your code working directory. + ::: zone pivot="programming-language-csharp" Start by creating a _Console_ project. Then, include the following package references to ensure all required dependencies are available. @@ -68,11 +70,16 @@ The _Agent Framework_ is experimental and requires warning suppression. This ma ::: zone-end ::: zone pivot="programming-language-python" +Start by installing the Semantic Kernel Python package. + +```bash +pip install semantic-kernel +``` + ```python import asyncio import os import copy -import pyperclip # Install via pip from semantic_kernel.agents import AgentGroupChat, ChatCompletionAgent from semantic_kernel.agents.strategies.selection.kernel_function_selection_strategy import ( @@ -167,7 +174,7 @@ Configure the following settings in your `.env` file for either Azure OpenAI or ```python AZURE_OPENAI_API_KEY="..." -AZURE_OPENAI_ENDPOINT="https://..." +AZURE_OPENAI_ENDPOINT="https://.openai.azure.com/" AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..." AZURE_OPENAI_API_VERSION="..." @@ -254,11 +261,6 @@ toolKernel.Plugins.AddFromType(); ``` ::: zone-end -::: zone pivot="programming-language-python" -```python -tool_kernel = copy.deepcopy(kernel) -tool_kernel.add_plugin(ClipboardAccess(), plugin_name="clipboard") -``` ::: zone-end ::: zone pivot="programming-language-java" @@ -267,9 +269,9 @@ tool_kernel.add_plugin(ClipboardAccess(), plugin_name="clipboard") ::: zone-end +::: zone pivot="programming-language-csharp" The _Clipboard_ plugin may be defined as part of the sample. -::: zone pivot="programming-language-csharp" ```csharp private sealed class ClipboardAccess { @@ -297,21 +299,6 @@ private sealed class ClipboardAccess ``` ::: zone-end -::: zone pivot="programming-language-python" - -Note: we are leveraging a Python package called pyperclip. Please install is using pip. - -```python -class ClipboardAccess: - @kernel_function - def set_clipboard(content: str): - if not content.strip(): - return - - pyperclip.copy(content) -``` -::: zone-end - ::: zone pivot="programming-language-java" > Agents are currently unavailable in Java. @@ -320,9 +307,9 @@ class ClipboardAccess: ### Agent Definition +::: zone pivot="programming-language-csharp" Let's declare the agent names as `const` so they might be referenced in _Agent Group Chat_ strategies: -::: zone pivot="programming-language-csharp" ```csharp const string ReviewerName = "Reviewer"; const string WriterName = "Writer"; @@ -330,6 +317,9 @@ const string WriterName = "Writer"; ::: zone-end ::: zone pivot="programming-language-python" + +We will declare the agent names as "Reviewer" and "Writer." + ```python REVIEWER_NAME = "Reviewer" COPYWRITER_NAME = "Writer" @@ -379,23 +369,20 @@ ChatCompletionAgent agentReviewer = ::: zone pivot="programming-language-python" ```python agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, - kernel=_create_kernel_with_chat_completion(REVIEWER_NAME), - name=REVIEWER_NAME, - instructions=""" - Your responsiblity is to review and identify how to improve user provided content. - If the user has providing input or direction for content already provided, specify how to - address this input. - Never directly perform the correction or provide example. - Once the content has been updated in a subsequent response, you will review the content - again until satisfactory. - Always copy satisfactory content to the clipboard using available tools and inform user. - - RULES: - - Only identify suggestions that are specific and actionable. - - Verify previous suggestions have been addressed. - - Never repeat previous suggestions. - """, + service_id=REVIEWER_NAME, + kernel=kernel, + name=REVIEWER_NAME, + instructions=""" +Your responsibility is to review and identify how to improve user provided content. +If the user has provided input or direction for content already provided, specify how to address this input. +Never directly perform the correction or provide an example. +Once the content has been updated in a subsequent response, review it again until it is satisfactory. + +RULES: +- Only identify suggestions that are specific and actionable. +- Verify previous suggestions have been addressed. +- Never repeat previous suggestions. +""", ) ``` ::: zone-end @@ -406,11 +393,11 @@ agent_reviewer = ChatCompletionAgent( ::: zone-end -The _Writer_ agent is is similiar, but doesn't require the specification of _Execution Settings_ since it isn't configured with a plug-in. +::: zone pivot="programming-language-csharp" +The _Writer_ agent is similiar, but doesn't require the specification of _Execution Settings_ since it isn't configured with a plug-in. Here the _Writer_ is given a single-purpose task, follow direction and rewrite the content. -::: zone pivot="programming-language-csharp" ```csharp ChatCompletionAgent agentWriter = new() @@ -430,19 +417,19 @@ ChatCompletionAgent agentWriter = ::: zone-end ::: zone pivot="programming-language-python" +The _Writer_ agent is similiar. It is given a single-purpose task, follow direction and rewrite the content. ```python agent_writer = ChatCompletionAgent( - service_id=COPYWRITER_NAME, - kernel=_create_kernel_with_chat_completion(COPYWRITER_NAME), - name=COPYWRITER_NAME, - instructions=""" - Your sole responsiblity is to rewrite content according to review suggestions. - - - Always apply all review direction. - - Always revise the content in its entirety without explanation. - - Never address the user. - """, -) + service_id=WRITER_NAME, + kernel=kernel, + name=WRITER_NAME, + instructions=""" +Your sole responsibility is to rewrite content according to review suggestions. +- Always apply all review directions. +- Always revise the content in its entirety without explanation. +- Never address the user. +""", + ) ``` ::: zone-end @@ -489,25 +476,25 @@ KernelFunction selectionFunction = ::: zone pivot="programming-language-python" ```python selection_function = KernelFunctionFromPrompt( - function_name="selection", - prompt=f""" - Determine which participant takes the next turn in a conversation based on the the most recent participant. - State only the name of the participant to take the next turn. - No participant should take more than one turn in a row. - - Choose only from these participants: - - {REVIEWER_NAME} - - {COPYWRITER_NAME} - - Always follow these rules when selecting the next participant: - - After user input, it is {COPYWRITER_NAME}'s turn. - - After {COPYWRITER_NAME} replies, it is {REVIEWER_NAME}'s turn. - - After {REVIEWER_NAME} provides feedback, it is {COPYWRITER_NAME}'s turn. - - History: - {{{{$history}}}} - """, -) + function_name="selection", + prompt=f""" +Examine the provided RESPONSE and choose the next participant. +State only the name of the chosen participant without explanation. +Never choose the participant named in the RESPONSE. + +Choose only from these participants: +- {REVIEWER_NAME} +- {WRITER_NAME} + +Rules: +- If RESPONSE is user input, it is {REVIEWER_NAME}'s turn. +- If RESPONSE is by {REVIEWER_NAME}, it is {WRITER_NAME}'s turn. +- If RESPONSE is by {WRITER_NAME}, it is {REVIEWER_NAME}'s turn. + +RESPONSE: +{{{{$lastmessage}}}} +""" + ) ``` ::: zone-end @@ -540,20 +527,20 @@ KernelFunction terminationFunction = ::: zone pivot="programming-language-python" ```python -TERMINATION_KEYWORD = "yes" - -termination_function = KernelFunctionFromPrompt( - function_name="termination", - prompt=f""" - Examine the RESPONSE and determine whether the content has been deemed satisfactory. - If content is satisfactory, respond with a single word without explanation: {TERMINATION_KEYWORD}. - If specific suggestions are being provided, it is not satisfactory. - If no correction is suggested, it is satisfactory. + termination_keyword = "yes" - RESPONSE: - {{{{$history}}}} - """, -) + termination_function = KernelFunctionFromPrompt( + function_name="termination", + prompt=f""" +Examine the RESPONSE and determine whether the content has been deemed satisfactory. +If the content is satisfactory, respond with a single word without explanation: {termination_keyword}. +If specific suggestions are being provided, it is not satisfactory. +If no correction is suggested, it is satisfactory. + +RESPONSE: +{{{{$lastmessage}}}} +""" + ) ``` ::: zone-end @@ -573,7 +560,7 @@ ChatHistoryTruncationReducer historyReducer = new(1); ::: zone pivot="programming-language-python" ```python -**ChatHistoryReducer is coming soon to Python.** +history_reducer = ChatHistoryTruncationReducer(target_count=1) ``` ::: zone-end @@ -644,26 +631,28 @@ Creating `AgentGroupChat` involves: Notice that each strategy is responsible for parsing the `KernelFunction` result. ```python chat = AgentGroupChat( - agents=[agent_writer, agent_reviewer], + agents=[agent_reviewer, agent_writer], selection_strategy=KernelFunctionSelectionStrategy( + initial_agent=agent_reviewer, function=selection_function, - kernel=_create_kernel_with_chat_completion("selection"), - result_parser=lambda result: str(result.value[0]) if result.value is not None else COPYWRITER_NAME, - agent_variable_name="agents", - history_variable_name="history", + kernel=kernel, + result_parser=lambda result: str(result.value[0]).strip() if result.value[0] is not None else WRITER_NAME, + history_variable_name="lastmessage", history_reducer=history_reducer, ), termination_strategy=KernelFunctionTerminationStrategy( agents=[agent_reviewer], function=termination_function, - kernel=_create_kernel_with_chat_completion("termination"), - result_parser=lambda result: TERMINATION_KEYWORD in str(result.value[0]).lower(), - history_variable_name="history", + kernel=kernel, + result_parser=lambda result: termination_keyword in str(result.value[0]).lower(), + history_variable_name="lastmessage", maximum_iterations=10, history_reducer=history_reducer, ), ) ``` + +The `lastmessage` `history_variable_name` corresponds with the `KernelFunctionSelectionStrategy` and the `KernelFunctionTerminationStrategy` prompt that was defined above. This is where the last message is placed when rendering the prompt. ::: zone-end ::: zone pivot="programming-language-java" @@ -702,15 +691,14 @@ while not is_complete: ::: zone-end +::: zone pivot="programming-language-csharp" Now let's capture user input within the previous loop. In this case: - Empty input will be ignored - The term `EXIT` will signal that the conversation is completed - The term `RESET` will clear the _Agent Group Chat_ history - Any term starting with `@` will be treated as a file-path whose content will be provided as input -- Valid input will be added to the _Agent Group Chaty_ as a _User_ message. - +- Valid input will be added to the _Agent Group Chat_ as a _User_ message. -::: zone pivot="programming-language-csharp" ```csharp Console.WriteLine(); Console.Write("> "); @@ -757,8 +745,18 @@ chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, input)); ::: zone-end ::: zone pivot="programming-language-python" +Now let's capture user input within the previous loop. In this case: +- Empty input will be ignored. +- The term `exit` will signal that the conversation is complete. +- The term `reset` will clear the _Agent Group Chat_ history. +- Any term starting with `@` will be treated as a file-path whose content will be provided as input. +- Valid input will be added to the _Agent Group Chat_ as a _User_ message. + +The operation logic inside the while loop looks like: + ```python -user_input = input("User:> ") +print() +user_input = input("User > ").strip() if not user_input: continue @@ -771,18 +769,22 @@ if user_input.lower() == "reset": print("[Conversation has been reset]") continue -if user_input.startswith("@") and len(input) > 1: - file_path = input[1:] +# Try to grab files from the script's current directory +if user_input.startswith("@") and len(user_input) > 1: + file_name = user_input[1:] + script_dir = os.path.dirname(os.path.abspath(__file__)) + file_path = os.path.join(script_dir, file_name) try: if not os.path.exists(file_path): print(f"Unable to access file: {file_path}") continue - with open(file_path) as file: + with open(file_path, "r", encoding="utf-8") as file: user_input = file.read() except Exception: print(f"Unable to access file: {file_path}") continue +# Add the current user_input to the chat await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=user_input)) ``` ::: zone-end @@ -826,13 +828,17 @@ catch (HttpOperationException exception) ::: zone pivot="programming-language-python" ```python -chat.is_complete = False -async for response in chat.invoke(): - print(f"# {response.role} - {response.name or '*'}: '{response.content}'") +try: + async for response in chat.invoke(): + if response is None or not response.name: + continue + print() + print(f"# {response.name.upper()}:\n{response.content}") +except Exception as e: + print(f"Error during chat invocation: {e}") -if chat.is_complete: - is_complete = True - break +# Reset the chat's complete flag for the new conversation round. +chat.is_complete = False ``` ::: zone-end @@ -845,6 +851,8 @@ if chat.is_complete: ## Final +::: zone pivot="programming-language-csharp" + Bringing all the steps together, we have the final code for this example. The complete implementation is provided below. Try using these suggested inputs: @@ -852,14 +860,12 @@ Try using these suggested inputs: 1. Hi 2. {"message: "hello world"} 3. {"message": "hello world"} -4. Semantic Kernel (SK) is an open-source SDK that enables developers to build and orchestrate complex AI workflows that involve natural language processing (NLP) and machine learning models. It provies a flexible platform for integrating AI capabilities such as semantic search, text summarization, and dialogue systems into applications. With SK, you can easily combine different AI services and models, define thei relationships, and orchestrate interactions between them. +4. Semantic Kernel (SK) is an open-source SDK that enables developers to build and orchestrate complex AI workflows that involve natural language processing (NLP) and machine learning models. It provies a flexible platform for integrating AI capabilities such as semantic search, text summarization, and dialogue systems into applications. With SK, you can easily combine different AI services and models, define their relationships, and orchestrate interactions between them. 5. make this two paragraphs 6. thank you 7. @.\WomensSuffrage.txt 8. its good, but is it ready for my college professor? - -::: zone pivot="programming-language-csharp" ```csharp // Copyright (c) Microsoft. All rights reserved. @@ -1114,12 +1120,28 @@ public static class Program ::: zone-end ::: zone pivot="programming-language-python" + +Bringing all the steps together, we now have the final code for this example. The complete implementation is shown below. + +You can try using one of the suggested inputs. As the agent chat begins, the agents will exchange messages for several iterations until the reviewer agent is satisfied with the copywriter's work. The `while` loop ensures the conversation continues, even if the chat is initially considered complete, by resetting the `is_complete` flag to `False`. + +1. Rozes are red, violetz are blue. +2. Semantic Kernel (SK) is an open-source SDK that enables developers to build and orchestrate complex AI workflows that involve natural language processing (NLP) and machine learning models. It provies a flexible platform for integrating AI capabilities such as semantic search, text summarization, and dialogue systems into applications. With SK, you can easily combine different AI services and models, define their relationships, and orchestrate interactions between them. +4. Make this two paragraphs +5. thank you +7. @WomensSuffrage.txt +8. It's good, but is it ready for my college professor? + +> [!TIP] +> You can reference any file by providing `@`. To reference the "WomensSuffrage" text from above, download it [here](https://github.com/microsoft/semantic-kernel/blob/3f22587de5a6f42b41bd268f237547e1034de7df/dotnet/samples/LearnResources/Resources/WomensSuffrage.txt) and place it in your current working directory. You can then reference it with `@WomensSuffrage.txt`. + ```python # Copyright (c) Microsoft. All rights reserved. import asyncio import os +from semantic_kernel import Kernel from semantic_kernel.agents import AgentGroupChat, ChatCompletionAgent from semantic_kernel.agents.strategies.selection.kernel_function_selection_strategy import ( KernelFunctionSelectionStrategy, @@ -1128,12 +1150,10 @@ from semantic_kernel.agents.strategies.termination.kernel_function_termination_s KernelFunctionTerminationStrategy, ) from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion -from semantic_kernel.contents import ChatHistoryTruncationReducer from semantic_kernel.contents.chat_message_content import ChatMessageContent +from semantic_kernel.contents.history_reducer.chat_history_truncation_reducer import ChatHistoryTruncationReducer from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.functions.kernel_function_decorator import kernel_function from semantic_kernel.functions.kernel_function_from_prompt import KernelFunctionFromPrompt -from semantic_kernel.kernel import Kernel ################################################################### # The following sample demonstrates how to create a simple, # @@ -1142,122 +1162,123 @@ from semantic_kernel.kernel import Kernel # complete a user's task. # ################################################################### - -class ClipboardAccess: - @kernel_function - def set_clipboard(content: str): - if not content.strip(): - return - - pyperclip.copy(content) - - +# Define agent names REVIEWER_NAME = "Reviewer" -COPYWRITER_NAME = "Writer" +WRITER_NAME = "Writer" -def _create_kernel_with_chat_completion(service_id: str) -> Kernel: +def create_kernel() -> Kernel: + """Creates a Kernel instance with an Azure OpenAI ChatCompletion service.""" kernel = Kernel() - kernel.add_service(AzureChatCompletion(service_id=service_id)) + kernel.add_service(service=AzureChatCompletion()) return kernel async def main(): + # Create a single kernel instance for all agents. + kernel = create_kernel() + + # Create ChatCompletionAgents using the same kernel. agent_reviewer = ChatCompletionAgent( service_id=REVIEWER_NAME, - kernel=_create_kernel_with_chat_completion(REVIEWER_NAME), + kernel=kernel, name=REVIEWER_NAME, instructions=""" - Your responsiblity is to review and identify how to improve user provided content. - If the user has providing input or direction for content already provided, specify how to - address this input. - Never directly perform the correction or provide example. - Once the content has been updated in a subsequent response, you will review the content - again until satisfactory. - Always copy satisfactory content to the clipboard using available tools and inform user. - - RULES: - - Only identify suggestions that are specific and actionable. - - Verify previous suggestions have been addressed. - - Never repeat previous suggestions. - """, +Your responsibility is to review and identify how to improve user provided content. +If the user has provided input or direction for content already provided, specify how to address this input. +Never directly perform the correction or provide an example. +Once the content has been updated in a subsequent response, review it again until it is satisfactory. + +RULES: +- Only identify suggestions that are specific and actionable. +- Verify previous suggestions have been addressed. +- Never repeat previous suggestions. +""", ) agent_writer = ChatCompletionAgent( - service_id=COPYWRITER_NAME, - kernel=_create_kernel_with_chat_completion(COPYWRITER_NAME), - name=COPYWRITER_NAME, + service_id=WRITER_NAME, + kernel=kernel, + name=WRITER_NAME, instructions=""" - Your sole responsiblity is to rewrite content according to review suggestions. - - - Always apply all review direction. - - Always revise the content in its entirety without explanation. - - Never address the user. - """, +Your sole responsibility is to rewrite content according to review suggestions. +- Always apply all review directions. +- Always revise the content in its entirety without explanation. +- Never address the user. +""", ) + # Define a selection function to determine which agent should take the next turn. selection_function = KernelFunctionFromPrompt( function_name="selection", prompt=f""" - Determine which participant takes the next turn in a conversation based on the the most recent participant. - State only the name of the participant to take the next turn. - No participant should take more than one turn in a row. - - Choose only from these participants: - - {REVIEWER_NAME} - - {COPYWRITER_NAME} - - Always follow these rules when selecting the next participant: - - After user input, it is {COPYWRITER_NAME}'s turn. - - After {COPYWRITER_NAME} replies, it is {REVIEWER_NAME}'s turn. - - After {REVIEWER_NAME} provides feedback, it is {COPYWRITER_NAME}'s turn. - - History: - {{{{$history}}}} - """, +Examine the provided RESPONSE and choose the next participant. +State only the name of the chosen participant without explanation. +Never choose the participant named in the RESPONSE. + +Choose only from these participants: +- {REVIEWER_NAME} +- {WRITER_NAME} + +Rules: +- If RESPONSE is user input, it is {REVIEWER_NAME}'s turn. +- If RESPONSE is by {REVIEWER_NAME}, it is {WRITER_NAME}'s turn. +- If RESPONSE is by {WRITER_NAME}, it is {REVIEWER_NAME}'s turn. + +RESPONSE: +{{{{$lastmessage}}}} +""", ) - TERMINATION_KEYWORD = "yes" + # Define a termination function where the reviewer signals completion with "yes". + termination_keyword = "yes" termination_function = KernelFunctionFromPrompt( function_name="termination", prompt=f""" - Examine the RESPONSE and determine whether the content has been deemed satisfactory. - If content is satisfactory, respond with a single word without explanation: {TERMINATION_KEYWORD}. - If specific suggestions are being provided, it is not satisfactory. - If no correction is suggested, it is satisfactory. - - RESPONSE: - {{{{$history}}}} - """, +Examine the RESPONSE and determine whether the content has been deemed satisfactory. +If the content is satisfactory, respond with a single word without explanation: {termination_keyword}. +If specific suggestions are being provided, it is not satisfactory. +If no correction is suggested, it is satisfactory. + +RESPONSE: +{{{{$lastmessage}}}} +""", ) - history_reducer = ChatHistoryTruncationReducer(target_count=1) + history_reducer = ChatHistoryTruncationReducer(target_count=5) + # Create the AgentGroupChat with selection and termination strategies. chat = AgentGroupChat( - agents=[agent_writer, agent_reviewer], + agents=[agent_reviewer, agent_writer], selection_strategy=KernelFunctionSelectionStrategy( + initial_agent=agent_reviewer, function=selection_function, - kernel=_create_kernel_with_chat_completion("selection"), - result_parser=lambda result: str(result.value[0]) if result.value is not None else COPYWRITER_NAME, - agent_variable_name="agents", - history_variable_name="history", + kernel=kernel, + result_parser=lambda result: str(result.value[0]).strip() if result.value[0] is not None else WRITER_NAME, + history_variable_name="lastmessage", history_reducer=history_reducer, ), termination_strategy=KernelFunctionTerminationStrategy( agents=[agent_reviewer], function=termination_function, - kernel=_create_kernel_with_chat_completion("termination"), - result_parser=lambda result: TERMINATION_KEYWORD in str(result.value[0]).lower(), - history_variable_name="history", + kernel=kernel, + result_parser=lambda result: termination_keyword in str(result.value[0]).lower(), + history_variable_name="lastmessage", maximum_iterations=10, history_reducer=history_reducer, ), ) - is_complete: bool = False + print( + "Ready! Type your input, or 'exit' to quit, 'reset' to restart the conversation. " + "You may pass in a file path using @." + ) + + is_complete = False while not is_complete: - user_input = input("User:> ") + print() + user_input = input("User > ").strip() if not user_input: continue @@ -1270,26 +1291,35 @@ async def main(): print("[Conversation has been reset]") continue - if user_input.startswith("@") and len(input) > 1: - file_path = input[1:] + # Try to grab files from the script's current directory + if user_input.startswith("@") and len(user_input) > 1: + file_name = user_input[1:] + script_dir = os.path.dirname(os.path.abspath(__file__)) + file_path = os.path.join(script_dir, file_name) try: if not os.path.exists(file_path): print(f"Unable to access file: {file_path}") continue - with open(file_path) as file: + with open(file_path, "r", encoding="utf-8") as file: user_input = file.read() except Exception: print(f"Unable to access file: {file_path}") continue + # Add the current user_input to the chat await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=user_input)) - async for response in chat.invoke(): - print(f"# {response.role} - {response.name or '*'}: '{response.content}'") + try: + async for response in chat.invoke(): + if response is None or not response.name: + continue + print() + print(f"# {response.name.upper()}:\n{response.content}") + except Exception as e: + print(f"Error during chat invocation: {e}") - if chat.is_complete: - is_complete = True - break + # Reset the chat's complete flag for the new conversation round. + chat.is_complete = False if __name__ == "__main__": diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index 67aa0290..2f3f2c81 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -172,7 +172,7 @@ Configure the following settings in your `.env` file for either Azure OpenAI or ```python AZURE_OPENAI_API_KEY="..." -AZURE_OPENAI_ENDPOINT="https://..." +AZURE_OPENAI_ENDPOINT="https://.openai.azure.com/" AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..." AZURE_OPENAI_API_VERSION="..." @@ -181,6 +181,9 @@ OPENAI_ORG_ID="" OPENAI_CHAT_MODEL_ID="" ``` +[!TIP] +Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](https://learn.microsoft.com/en-us/azure/ai-services/openai/api-version-deprecation). + Once configured, the respective AI service classes will pick up the required variables and use them during instantiation. ::: zone-end @@ -239,14 +242,18 @@ OpenAIFile fileDataCountryList = await fileClient.UploadFileAsync("PopulationByC # Let's form the file paths that we will later pass to the assistant csv_file_path_1 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", "PopulationByAdmin1.csv", ) csv_file_path_2 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", "PopulationByCountry.csv", ) ``` +You may need to modify the path creation code based on the storage location of your CSV files. + ::: zone-end ::: zone pivot="programming-language-java" @@ -285,18 +292,18 @@ OpenAIAssistantAgent agent = ::: zone pivot="programming-language-python" ```python agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", - instructions=""" - Analyze the available data to provide an answer to the user's question. - Always format response using markdown. - Always include a numerical index that starts at 1 for any lists or tables. - Always sort lists in ascending order. - """, - enable_code_interpreter=True, - code_interpreter_filenames=[csv_file_path_1, csv_file_path_2], - ) + kernel=Kernel(), + service_id="agent", + name="SampleAssistantAgent", + instructions=""" + Analyze the available data to provide an answer to the user's question. + Always format response using markdown. + Always include a numerical index that starts at 1 for any lists or tables. + Always sort lists in ascending order. + """, + enable_code_interpreter=True, + code_interpreter_filenames=[csv_file_path_1, csv_file_path_2], +) ``` ::: zone-end @@ -722,7 +729,10 @@ public static class Program ::: zone pivot="programming-language-python" ```python +# Copyright (c) Microsoft. All rights reserved. + import asyncio +import logging import os from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent @@ -731,19 +741,29 @@ from semantic_kernel.contents.streaming_file_reference_content import StreamingF from semantic_kernel.contents.utils.author_role import AuthorRole from semantic_kernel.kernel import Kernel +logging.basicConfig(level=logging.ERROR) + +################################################################### +# The following sample demonstrates how to create a simple, # +# OpenAI assistant agent that utilizes the code interpreter # +# to analyze uploaded files. # +################################################################### + # Let's form the file paths that we will later pass to the assistant csv_file_path_1 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", "PopulationByAdmin1.csv", ) csv_file_path_2 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", "PopulationByCountry.csv", ) -async def download_file_content(agent, file_id: str): +async def download_file_content(agent: AzureAssistantAgent, file_id: str): try: # Fetch the content of the file using the provided method response_content = await agent.client.files.content(file_id) @@ -766,7 +786,7 @@ async def download_file_content(agent, file_id: str): print(f"An error occurred while downloading file {file_id}: {str(e)}") -async def download_response_image(agent, file_ids: list[str]): +async def download_response_image(agent: AzureAssistantAgent, file_ids: list[str]): if file_ids: # Iterate over file_ids and download each one for file_id in file_ids: @@ -801,30 +821,41 @@ async def main(): if user_input.lower() == "exit": is_complete = True - break await agent.add_chat_message( thread_id=thread_id, message=ChatMessageContent(role=AuthorRole.USER, content=user_input) ) - is_code: bool = False - async for response in agent.invoke_stream(thread_id=thread_id): - if is_code != response.metadata.get("code"): - print() - is_code = not is_code - - print(f"{response.content}", end="", flush=True) + is_code = False + last_role = None + async for response in agent.invoke_stream(thread_id=thread_id): + current_is_code = response.metadata.get("code", False) + + if current_is_code: + if not is_code: + print("\n\n```python") + is_code = True + print(response.content, end="", flush=True) + else: + if is_code: + print("\n```") + is_code = False + last_role = None + if hasattr(response, "role") and response.role is not None and last_role != response.role: + print(f"\n# {response.role}: ", end="", flush=True) + last_role = response.role + print(response.content, end="", flush=True) file_ids.extend([ item.file_id for item in response.items if isinstance(item, StreamingFileReferenceContent) ]) - - print() + if is_code: + print("```\n") await download_response_image(agent, file_ids) file_ids.clear() finally: - print("Cleaning up resources...") + print("\nCleaning up resources...") if agent is not None: [await agent.delete_file(file_id) for file_id in agent.code_interpreter_file_ids] await agent.delete_thread(thread_id) diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index ca3c70b3..cf6e0f6f 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -174,7 +174,7 @@ Configure the following settings in your `.env` file for either Azure OpenAI or ```python AZURE_OPENAI_API_KEY="..." -AZURE_OPENAI_ENDPOINT="https://..." +AZURE_OPENAI_ENDPOINT="https://.openai.azure.com/" AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..." AZURE_OPENAI_API_VERSION="..." @@ -183,6 +183,9 @@ OPENAI_ORG_ID="" OPENAI_CHAT_MODEL_ID="" ``` +> [!TIP] +> Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](https://learn.microsoft.com/en-us/azure/ai-services/openai/api-version-deprecation). + Once configured, the respective AI service classes will pick up the required variables and use them during instantiation. ::: zone-end From f1b1b6c382e81010ca527244ea4b0bae61c48e40 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 13 Feb 2025 11:54:20 -0800 Subject: [PATCH 03/70] Fix spurious zone-end tag --- .../get-started/quick-start-guide.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/semantic-kernel/get-started/quick-start-guide.md b/semantic-kernel/get-started/quick-start-guide.md index 767fba6f..ed58aa72 100644 --- a/semantic-kernel/get-started/quick-start-guide.md +++ b/semantic-kernel/get-started/quick-start-guide.md @@ -300,11 +300,25 @@ To make it easier to get started building enterprise apps with Semantic Kernel, In the following sections, we'll unpack the above sample by walking through steps **1**, **2**, **3**, **4**, **6**, **9**, and **10**. Everything you need to build a simple agent that is powered by an AI service and can run your code. + ::: zone pivot="programming-language-csharp,programming-language-python" + - [Import packages](#1-import-packages) - [Add AI services](#2-add-ai-services) - ::: zone pivot="programming-language-csharp,programming-language-python" - [Enterprise components](#3-add-enterprise-services) +- [Build the kernel](#4-build-the-kernel-and-retrieve-services) +- Add memory (skipped) +- [Add plugins](#6-add-plugins) +- Create kernel arguments (skipped) +- Create prompts (skipped) +- [Planning](#9-planning) +- [Invoke](#10-invoke) + ::: zone-end + + ::: zone pivot="programming-language-java" + +- [Import packages](#1-import-packages) +- [Add AI services](#2-add-ai-services) - [Build the kernel](#4-build-the-kernel-and-retrieve-services) - Add memory (skipped) - [Add plugins](#6-add-plugins) @@ -313,6 +327,8 @@ In the following sections, we'll unpack the above sample by walking through step - [Planning](#9-planning) - [Invoke](#10-invoke) + ::: zone-end + ### 1) Import packages For this sample, we first started by importing the following packages: From b5eb15b8dc2746c227e9994936c4c8ba3d182bbc Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Thu, 13 Feb 2025 12:09:40 -0800 Subject: [PATCH 04/70] Ingestion -> injection --- semantic-kernel/concepts/kernel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/kernel.md b/semantic-kernel/concepts/kernel.md index 69de031c..a3758b3c 100644 --- a/semantic-kernel/concepts/kernel.md +++ b/semantic-kernel/concepts/kernel.md @@ -32,7 +32,7 @@ Before building a kernel, you should first understand the two types of component | | Components | Description | |---|---|---| -| 1 | **Services** | These consist of both AI services (e.g., chat completion) and other services (e.g., logging and HTTP clients) that are necessary to run your application. This was modelled after the Service Provider pattern in .NET so that we could support dependency ingestion across all languages. | +| 1 | **Services** | These consist of both AI services (e.g., chat completion) and other services (e.g., logging and HTTP clients) that are necessary to run your application. This was modelled after the Service Provider pattern in .NET so that we could support dependency injection across all languages. | | 2 | **Plugins** | These are the components that are used by your AI services and prompt templates to perform work. AI services, for example, can use plugins to retrieve data from a database or call an external API to perform actions. | ::: zone pivot="programming-language-csharp" From 34650880bd37f63ababf0e7e598106ebbc6ac5f0 Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Fri, 14 Feb 2025 12:30:51 +0900 Subject: [PATCH 05/70] Include links to repo code. --- .../Frameworks/agent/examples/example-agent-collaboration.md | 2 ++ .../Frameworks/agent/examples/example-assistant-code.md | 2 ++ .../Frameworks/agent/examples/example-assistant-search.md | 2 ++ semantic-kernel/Frameworks/agent/examples/example-chat-agent.md | 2 ++ 4 files changed, 8 insertions(+) diff --git a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md index 39b1ea49..c140cf0b 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md +++ b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md @@ -1325,6 +1325,8 @@ RESPONSE: if __name__ == "__main__": asyncio.run(main()) ``` + +You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/agent_docs/agent_collaboration.py), as shown above, in our repo. ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index 2f3f2c81..d07d4538 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -865,6 +865,8 @@ async def main(): if __name__ == "__main__": asyncio.run(main()) ``` + +You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/agent_docs/assistant_code.py), as shown above, in our repo. ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index cf6e0f6f..1150e49e 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -783,6 +783,8 @@ async def main(): if __name__ == "__main__": asyncio.run(main()) ``` + +You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/agent_docs/assistant_search.py), as shown above, in our repo. ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md index 7870d9ed..1905fb7c 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md +++ b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md @@ -669,6 +669,8 @@ async def main(): if __name__ == "__main__": asyncio.run(main()) ``` + +You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/agent_docs/chat_agent.py), as shown above, in our repo. ::: zone-end ::: zone pivot="programming-language-java" From a2d9cd051156291f8822760a7f3fa6595d9b8a33 Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Fri, 14 Feb 2025 12:39:15 +0900 Subject: [PATCH 06/70] Remove fixed locale from link --- .../Frameworks/agent/examples/example-assistant-code.md | 2 +- .../Frameworks/agent/examples/example-assistant-search.md | 2 +- .../concepts/ai-services/chat-completion/index.md | 6 +++--- .../telemetry-with-azure-ai-foundry-tracing.md | 6 +++--- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index d07d4538..2e35a34d 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -182,7 +182,7 @@ OPENAI_CHAT_MODEL_ID="" ``` [!TIP] -Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](https://learn.microsoft.com/en-us/azure/ai-services/openai/api-version-deprecation). +Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](https://learn.microsoft.com/azure/ai-services/openai/api-version-deprecation). Once configured, the respective AI service classes will pick up the required variables and use them during instantiation. ::: zone-end diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index 1150e49e..3c7fbf76 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -184,7 +184,7 @@ OPENAI_CHAT_MODEL_ID="" ``` > [!TIP] -> Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](https://learn.microsoft.com/en-us/azure/ai-services/openai/api-version-deprecation). +> Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](https://learn.microsoft.com/azure/ai-services/openai/api-version-deprecation). Once configured, the respective AI service classes will pick up the required variables and use them during instantiation. ::: zone-end diff --git a/semantic-kernel/concepts/ai-services/chat-completion/index.md b/semantic-kernel/concepts/ai-services/chat-completion/index.md index c8218409..c468e7dc 100644 --- a/semantic-kernel/concepts/ai-services/chat-completion/index.md +++ b/semantic-kernel/concepts/ai-services/chat-completion/index.md @@ -920,7 +920,7 @@ chat_completion_service = AzureChatCompletion(service_id="my-service-id") ``` > [!NOTE] -> The `AzureChatCompletion` service also supports [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. +> The `AzureChatCompletion` service also supports [Microsoft Entra](https://learn.microsoft.com/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. # [OpenAI](#tab/python-OpenAI) @@ -967,7 +967,7 @@ chat_completion_service = AzureAIInferenceChatCompletion( ``` > [!NOTE] -> The `AzureAIInferenceChatCompletion` service also supports [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. +> The `AzureAIInferenceChatCompletion` service also supports [Microsoft Entra](https://learn.microsoft.com/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. # [Anthropic](#tab/python-Anthropic) @@ -1274,7 +1274,7 @@ execution_settings = OnnxGenAIPromptExecutionSettings() --- > [!TIP] -> To see what you can configure in the execution settings, you can check the class definition in the [source code](https://github.com/microsoft/semantic-kernel/tree/main/python/semantic_kernel/connectors/ai) or check out the [API documentation](https://learn.microsoft.com/en-us/python/api/semantic-kernel/semantic_kernel.connectors.ai?view=semantic-kernel-python). +> To see what you can configure in the execution settings, you can check the class definition in the [source code](https://github.com/microsoft/semantic-kernel/tree/main/python/semantic_kernel/connectors/ai) or check out the [API documentation](https://learn.microsoft.com/python/api/semantic-kernel/semantic_kernel.connectors.ai?view=semantic-kernel-python). ::: zone-end diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md index 36153162..f9943d9d 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md @@ -10,7 +10,7 @@ ms.service: semantic-kernel # Visualize traces on Azure AI Foundry Tracing UI -[Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-studio/) Tracing UI is a web-based user interface that allows you to visualize traces and logs generated by your applications. This article provides a step-by-step guide on how to visualize traces on Azure AI Foundry Tracing UI. +[Azure AI Foundry](https://learn.microsoft.com/azure/ai-studio/) Tracing UI is a web-based user interface that allows you to visualize traces and logs generated by your applications. This article provides a step-by-step guide on how to visualize traces on Azure AI Foundry Tracing UI. > [!IMPORTANT] > Before you start, make sure you have completed the tutorial on [inspecting telemetry data with Application Insights](./telemetry-with-app-insights.md). @@ -20,8 +20,8 @@ ms.service: semantic-kernel Prerequisites: -- An Azure AI Foundry project. Follow this [guide](https://learn.microsoft.com/en-us/azure/ai-studio/how-to/create-projects) to create one if you don't have one. -- A serverless inference API. Follow this [guide](https://learn.microsoft.com/en-us/azure/ai-studio/how-to/deploy-models-serverless) to create one if you don't have one. +- An Azure AI Foundry project. Follow this [guide](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects) to create one if you don't have one. +- A serverless inference API. Follow this [guide](https://learn.microsoft.com/azure/ai-studio/how-to/deploy-models-serverless) to create one if you don't have one. - Alternatively, you can attach an Azure OpenAI resource to the project, in which case you don't need to create a serverless API. ## Attach an Application Insights resource to the project From 40075fb94080e29cf00641cb44fdba654df8a63b Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Fri, 14 Feb 2025 12:42:22 +0900 Subject: [PATCH 07/70] Fix python sample resource link --- .../Frameworks/agent/examples/example-agent-collaboration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md index c140cf0b..802a309a 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md +++ b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md @@ -1133,7 +1133,7 @@ You can try using one of the suggested inputs. As the agent chat begins, the age 8. It's good, but is it ready for my college professor? > [!TIP] -> You can reference any file by providing `@`. To reference the "WomensSuffrage" text from above, download it [here](https://github.com/microsoft/semantic-kernel/blob/3f22587de5a6f42b41bd268f237547e1034de7df/dotnet/samples/LearnResources/Resources/WomensSuffrage.txt) and place it in your current working directory. You can then reference it with `@WomensSuffrage.txt`. +> You can reference any file by providing `@`. To reference the "WomensSuffrage" text from above, download it [here](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/resources/WomensSuffrage.txt) and place it in your current working directory. You can then reference it with `@WomensSuffrage.txt`. ```python # Copyright (c) Microsoft. All rights reserved. From 4bea51e314cb9b574927099422571e5115ad6bdd Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Fri, 14 Feb 2025 12:48:47 +0900 Subject: [PATCH 08/70] Use site relative links for learn site links. They don't need to be absolute. --- README.md | 6 +++--- .../agent/examples/example-assistant-code.md | 2 +- .../agent/examples/example-assistant-search.md | 2 +- .../Frameworks/process/process-deployment.md | 2 +- .../concepts/ai-services/chat-completion/index.md | 6 +++--- .../enterprise-readiness/observability/index.md | 8 ++++---- .../observability/telemetry-advanced.md | 4 ++-- .../observability/telemetry-with-aspire-dashboard.md | 10 +++++----- .../telemetry-with-azure-ai-foundry-tracing.md | 6 +++--- .../observability/telemetry-with-console.md | 2 +- 10 files changed, 24 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 75500b2b..e6f7a7f1 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # Microsoft Semantic Kernel Documentation -This is the GitHub repository for the technical product documentation for **Semantic Kernel**. This documentation is published at [Microsoft Semantic Kernel documentation](https://learn.microsoft.com/semantic-kernel). +This is the GitHub repository for the technical product documentation for **Semantic Kernel**. This documentation is published at [Microsoft Semantic Kernel documentation](/semantic-kernel). ## How to contribute -Thanks for your interest in [contributing](https://learn.microsoft.com/), home of technical content for Microsoft products and services. +Thanks for your interest in contributing to the home of technical content for Microsoft products and services. -To learn how to make contributions to the content in this repository, start with our [Docs contributor guide](https://learn.microsoft.com/contribute). +To learn how to make contributions to the content in this repository, start with our [Docs contributor guide](/contribute). ## Code of conduct diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index 2e35a34d..b39a5eb8 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -182,7 +182,7 @@ OPENAI_CHAT_MODEL_ID="" ``` [!TIP] -Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](https://learn.microsoft.com/azure/ai-services/openai/api-version-deprecation). +Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](/azure/ai-services/openai/api-version-deprecation). Once configured, the respective AI service classes will pick up the required variables and use them during instantiation. ::: zone-end diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index 3c7fbf76..f38a28d4 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -184,7 +184,7 @@ OPENAI_CHAT_MODEL_ID="" ``` > [!TIP] -> Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](https://learn.microsoft.com/azure/ai-services/openai/api-version-deprecation). +> Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](/azure/ai-services/openai/api-version-deprecation). Once configured, the respective AI service classes will pick up the required variables and use them during instantiation. ::: zone-end diff --git a/semantic-kernel/Frameworks/process/process-deployment.md b/semantic-kernel/Frameworks/process/process-deployment.md index 3be467a4..8ba8aa0e 100644 --- a/semantic-kernel/Frameworks/process/process-deployment.md +++ b/semantic-kernel/Frameworks/process/process-deployment.md @@ -18,7 +18,7 @@ The Process Framework provides an in-process runtime that allows developers to r ## Cloud Runtimes -For scenarios requiring scalability and distributed processing, the Process Framework supports cloud runtimes such as [**Orleans**](https://learn.microsoft.com/dotnet/orleans/overview) and [**Dapr**](https://dapr.io/). These options empower developers to deploy processes in a distributed manner, facilitating high availability and load balancing across multiple instances. By leveraging these cloud runtimes, organizations can streamline their operations and manage substantial workloads with ease. +For scenarios requiring scalability and distributed processing, the Process Framework supports cloud runtimes such as [**Orleans**](/dotnet/orleans/overview) and [**Dapr**](https://dapr.io/). These options empower developers to deploy processes in a distributed manner, facilitating high availability and load balancing across multiple instances. By leveraging these cloud runtimes, organizations can streamline their operations and manage substantial workloads with ease. - **Orleans Runtime:** This framework provides a programming model for building distributed applications and is particularly well-suited for handling virtual actors in a resilient manner, complementing the Process Framework’s event-driven architecture. diff --git a/semantic-kernel/concepts/ai-services/chat-completion/index.md b/semantic-kernel/concepts/ai-services/chat-completion/index.md index c468e7dc..27305c4d 100644 --- a/semantic-kernel/concepts/ai-services/chat-completion/index.md +++ b/semantic-kernel/concepts/ai-services/chat-completion/index.md @@ -920,7 +920,7 @@ chat_completion_service = AzureChatCompletion(service_id="my-service-id") ``` > [!NOTE] -> The `AzureChatCompletion` service also supports [Microsoft Entra](https://learn.microsoft.com/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. +> The `AzureChatCompletion` service also supports [Microsoft Entra](/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. # [OpenAI](#tab/python-OpenAI) @@ -967,7 +967,7 @@ chat_completion_service = AzureAIInferenceChatCompletion( ``` > [!NOTE] -> The `AzureAIInferenceChatCompletion` service also supports [Microsoft Entra](https://learn.microsoft.com/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. +> The `AzureAIInferenceChatCompletion` service also supports [Microsoft Entra](/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. # [Anthropic](#tab/python-Anthropic) @@ -1274,7 +1274,7 @@ execution_settings = OnnxGenAIPromptExecutionSettings() --- > [!TIP] -> To see what you can configure in the execution settings, you can check the class definition in the [source code](https://github.com/microsoft/semantic-kernel/tree/main/python/semantic_kernel/connectors/ai) or check out the [API documentation](https://learn.microsoft.com/python/api/semantic-kernel/semantic_kernel.connectors.ai?view=semantic-kernel-python). +> To see what you can configure in the execution settings, you can check the class definition in the [source code](https://github.com/microsoft/semantic-kernel/tree/main/python/semantic_kernel/connectors/ai) or check out the [API documentation](/python/api/semantic-kernel/semantic_kernel.connectors.ai?view=semantic-kernel-python). ::: zone-end diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/index.md b/semantic-kernel/concepts/enterprise-readiness/observability/index.md index 41583f59..79b13241 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/index.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/index.md @@ -20,8 +20,8 @@ Observability is typically achieved through logging, metrics, and tracing. They Useful materials for further reading: - [Observability defined by Cloud Native Computing Foundation](https://glossary.cncf.io/observability/) -- [Distributed tracing](https://learn.microsoft.com/dotnet/core/diagnostics/distributed-tracing) -- [Observability in .Net](https://learn.microsoft.com/dotnet/core/diagnostics/observability-with-otel) +- [Distributed tracing](/dotnet/core/diagnostics/distributed-tracing) +- [Observability in .Net](/dotnet/core/diagnostics/observability-with-otel) - [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) ## Observability in Semantic Kernel @@ -33,7 +33,7 @@ Specifically, Semantic Kernel provides the following observability features: - **Logging**: Semantic Kernel logs meaningful events and errors from the kernel, kernel plugins and functions, as well as the AI connectors. ![Logs and events](../../../media/telemetry-log-events-overview-app-insights.png) > [!IMPORTANT] - > [Traces in Application Insights](https://learn.microsoft.com/azure/azure-monitor/app/data-model-complete#trace) represent traditional log entries and [OpenTelemetry span events](https://opentelemetry.io/docs/concepts/signals/traces/#span-events). They are not the same as distributed traces. + > [Traces in Application Insights](/azure/azure-monitor/app/data-model-complete#trace) represent traditional log entries and [OpenTelemetry span events](https://opentelemetry.io/docs/concepts/signals/traces/#span-events). They are not the same as distributed traces. - **Metrics**: Semantic Kernel emits metrics from kernel functions and AI connectors. You will be able to monitor metrics such as the kernel function execution time, the token consumption of AI connectors, etc. ![Metrics](../../../media/telemetry-metrics-overview-app-insights.png) - **Tracing**: Semantic Kernel supports distributed tracing. You can track activities across different services and within Semantic Kernel. @@ -44,7 +44,7 @@ Specifically, Semantic Kernel provides the following observability features: | Telemetry | Description | |-----------|---------------------------------------| -| Log | Logs are recorded throughout the Kernel. For more information on Logging in .Net, please refer to this [document](https://learn.microsoft.com/dotnet/core/extensions/logging). Sensitive data, such as kernel function arguments and results, are logged at the trace level. Please refer to this [table](https://learn.microsoft.com/dotnet/core/extensions/logging?tabs=command-line#log-level) for more information on log levels. | +| Log | Logs are recorded throughout the Kernel. For more information on Logging in .Net, please refer to this [document](/dotnet/core/extensions/logging). Sensitive data, such as kernel function arguments and results, are logged at the trace level. Please refer to this [table](/dotnet/core/extensions/logging?tabs=command-line#log-level) for more information on log levels. | | Activity | Each kernel function execution and each call to an AI model are recorded as an activity. All activities are generated by an activity source named "Microsoft.SemanticKernel". | | Metric | Semantic Kernel captures the following metrics from kernel functions:
  • `semantic_kernel.function.invocation.duration` (Histogram) - function execution time (in seconds)
  • `semantic_kernel.function.streaming.duration` (Histogram) - function streaming execution time (in seconds)
  • `semantic_kernel.function.invocation.token_usage.prompt` (Histogram) - number of prompt token usage (only for `KernelFunctionFromPrompt`)
  • `semantic_kernel.function.invocation.token_usage.completion` (Histogram) - number of completion token usage (only for `KernelFunctionFromPrompt`)
    • | diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-advanced.md b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-advanced.md index bb604e6b..2efebe69 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-advanced.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-advanced.md @@ -12,7 +12,7 @@ ms.service: semantic-kernel # More advanced scenarios for telemetry > [!NOTE] -> This article will use [Aspire Dashboard](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/overview?tabs=bash) for illustration. If you prefer to use other tools, please refer to the documentation of the tool you are using on setup instructions. +> This article will use [Aspire Dashboard](/dotnet/aspire/fundamentals/dashboard/overview?tabs=bash) for illustration. If you prefer to use other tools, please refer to the documentation of the tool you are using on setup instructions. ## Auto Function Calling @@ -375,7 +375,7 @@ Please refer to this [article](./telemetry-with-console.md#environment-variables ### Start the Aspire Dashboard -Follow the instructions [here](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash#start-the-dashboard) to start the dashboard. Once the dashboard is running, open a browser and navigate to `http://localhost:18888` to access the dashboard. +Follow the instructions [here](/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash#start-the-dashboard) to start the dashboard. Once the dashboard is running, open a browser and navigate to `http://localhost:18888` to access the dashboard. ### Run diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard.md b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard.md index b83abbfb..6bd39dfe 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard.md @@ -11,9 +11,9 @@ ms.service: semantic-kernel # Inspection of telemetry data with Aspire Dashboard -[Aspire Dashboard](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/overview?tabs=bash) is part of the [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/get-started/aspire-overview) offering. The dashboard allows developers to monitor and inspect their distributed applications. +[Aspire Dashboard](/dotnet/aspire/fundamentals/dashboard/overview?tabs=bash) is part of the [.NET Aspire](/dotnet/aspire/get-started/aspire-overview) offering. The dashboard allows developers to monitor and inspect their distributed applications. -In this example, we will use the [standalone mode](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash) and learn how to export telemetry data to Aspire Dashboard, and inspect the data there. +In this example, we will use the [standalone mode](/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash) and learn how to export telemetry data to Aspire Dashboard, and inspect the data there. ## Exporter @@ -330,7 +330,7 @@ Please refer to this [article](./telemetry-with-console.md#add-telemetry-1) for ## Start the Aspire Dashboard -Follow the instructions [here](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash#start-the-dashboard) to start the dashboard. Once the dashboard is running, open a browser and navigate to `http://localhost:18888` to access the dashboard. +Follow the instructions [here](/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash#start-the-dashboard) to start the dashboard. Once the dashboard is running, open a browser and navigate to `http://localhost:18888` to access the dashboard. ## Run @@ -366,7 +366,7 @@ python telemetry_aspire_dashboard_quickstart.py After running the application, head over to the dashboard to inspect the telemetry data. > [!TIP] -> Follow this [guide](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/explore) to explore the Aspire Dashboard interface. +> Follow this [guide](/dotnet/aspire/fundamentals/dashboard/explore) to explore the Aspire Dashboard interface. ### Traces @@ -383,7 +383,7 @@ In the trace details, you can see the span that represents the prompt function a ### Logs -Head over to the `Structured` tab to view the logs emitted by the application. Please refer to this [guide](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/explore#structured-logs-page) on how to work with structured logs in the dashboard. +Head over to the `Structured` tab to view the logs emitted by the application. Please refer to this [guide](/dotnet/aspire/fundamentals/dashboard/explore#structured-logs-page) on how to work with structured logs in the dashboard. ## Next steps diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md index f9943d9d..00ab843c 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md @@ -10,7 +10,7 @@ ms.service: semantic-kernel # Visualize traces on Azure AI Foundry Tracing UI -[Azure AI Foundry](https://learn.microsoft.com/azure/ai-studio/) Tracing UI is a web-based user interface that allows you to visualize traces and logs generated by your applications. This article provides a step-by-step guide on how to visualize traces on Azure AI Foundry Tracing UI. +[Azure AI Foundry](/azure/ai-studio/) Tracing UI is a web-based user interface that allows you to visualize traces and logs generated by your applications. This article provides a step-by-step guide on how to visualize traces on Azure AI Foundry Tracing UI. > [!IMPORTANT] > Before you start, make sure you have completed the tutorial on [inspecting telemetry data with Application Insights](./telemetry-with-app-insights.md). @@ -20,8 +20,8 @@ ms.service: semantic-kernel Prerequisites: -- An Azure AI Foundry project. Follow this [guide](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects) to create one if you don't have one. -- A serverless inference API. Follow this [guide](https://learn.microsoft.com/azure/ai-studio/how-to/deploy-models-serverless) to create one if you don't have one. +- An Azure AI Foundry project. Follow this [guide](/azure/ai-studio/how-to/create-projects) to create one if you don't have one. +- A serverless inference API. Follow this [guide](/azure/ai-studio/how-to/deploy-models-serverless) to create one if you don't have one. - Alternatively, you can attach an Azure OpenAI resource to the project, in which case you don't need to create a serverless API. ## Attach an Application Insights resource to the project diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console.md b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console.md index 56354c16..f066c170 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console.md @@ -478,7 +478,7 @@ Value: 16 Here you can see the name, the description, the unit, the time range, the type, the value of the metric, and the meter that the metric belongs to. > [!NOTE] -> The above metric is a Counter metric. For a full list of metric types, see [here](https://learn.microsoft.com/dotnet/core/diagnostics/metrics-instrumentation#types-of-instruments). Depending on the type of metric, the output may vary. +> The above metric is a Counter metric. For a full list of metric types, see [here](/dotnet/core/diagnostics/metrics-instrumentation#types-of-instruments). Depending on the type of metric, the output may vary. ::: zone-end From d635b4565fa5e0aa866a9d1456460a18d88a0982 Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Fri, 14 Feb 2025 12:59:27 +0900 Subject: [PATCH 09/70] Fix media link --- .../concepts/enterprise-readiness/observability/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/index.md b/semantic-kernel/concepts/enterprise-readiness/observability/index.md index 79b13241..c88edbe5 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/index.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/index.md @@ -37,7 +37,7 @@ Specifically, Semantic Kernel provides the following observability features: - **Metrics**: Semantic Kernel emits metrics from kernel functions and AI connectors. You will be able to monitor metrics such as the kernel function execution time, the token consumption of AI connectors, etc. ![Metrics](../../../media/telemetry-metrics-overview-app-insights.png) - **Tracing**: Semantic Kernel supports distributed tracing. You can track activities across different services and within Semantic Kernel. - ![Complete end-to-end transaction of a request](../../media/telemetry-trace-overview-app-insights.png) + ![Complete end-to-end transaction of a request](../../../media/telemetry-trace-overview-app-insights.png) ::: zone pivot="programming-language-csharp" From 78ad2e7ceb9b97500515f645efcfcee615be6998 Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Fri, 14 Feb 2025 13:14:22 +0900 Subject: [PATCH 10/70] Scope link per language --- .../agent/examples/example-agent-collaboration.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md index 802a309a..87fe4167 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md +++ b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md @@ -26,10 +26,11 @@ The approach will be broken down step-by-step to high-light the key parts of the Before proceeding with feature coding, make sure your development environment is fully set up and configured. -This sample uses an optional text file as part of processing. If you'd like to use it, you may download it [here](https://github.com/microsoft/semantic-kernel/blob/3f22587de5a6f42b41bd268f237547e1034de7df/dotnet/samples/LearnResources/Resources/WomensSuffrage.txt). Place the file in your code working directory. - ::: zone pivot="programming-language-csharp" +> [!TIP] +> This sample uses an optional text file as part of processing. If you'd like to use it, you may download it [here](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/LearnResources/Resources/WomensSuffrage.txt). Place the file in your code working directory. + Start by creating a _Console_ project. Then, include the following package references to ensure all required dependencies are available. To add package dependencies from the command-line use the `dotnet` command: @@ -70,6 +71,10 @@ The _Agent Framework_ is experimental and requires warning suppression. This ma ::: zone-end ::: zone pivot="programming-language-python" + +> [!TIP] +> This sample uses an optional text file as part of processing. If you'd like to use it, you may download it [here](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/resources/WomensSuffrage.txt). Place the file in your code working directory. + Start by installing the Semantic Kernel Python package. ```bash From fa534a9ebc07895986ad804ccb6c028f2ef12dce Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Fri, 14 Feb 2025 13:34:57 +0900 Subject: [PATCH 11/70] More cleanup --- .../agent/examples/example-assistant-code.md | 12 ++++++++++-- .../Frameworks/agent/examples/example-chat-agent.md | 4 ++-- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index b39a5eb8..c9b79287 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -92,7 +92,7 @@ from semantic_kernel.contents.utils.author_role import AuthorRole from semantic_kernel.kernel import Kernel ``` -Additionally, copy the `PopulationByAdmin1.csv` and `PopulationByCountry.csv` data files from [_Semantic Kernel_ `LearnResources` Project](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/learn_resources/resources). Add these files in your project folder. +Additionally, copy the `PopulationByAdmin1.csv` and `PopulationByCountry.csv` data files from the [_Semantic Kernel_ `learn_resources/resources` directory](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/learn_resources/resources). Add these files to your working directory. ::: zone-end ::: zone pivot="programming-language-java" @@ -238,6 +238,10 @@ OpenAIFile fileDataCountryList = await fileClient.UploadFileAsync("PopulationByC ::: zone-end ::: zone pivot="programming-language-python" + +> [!TIP] +> You may need to adjust the file paths depending upon where your files are located. + ```python # Let's form the file paths that we will later pass to the assistant csv_file_path_1 = os.path.join( @@ -264,9 +268,10 @@ You may need to modify the path creation code based on the storage location of y ### Agent Definition +::: zone pivot="programming-language-csharp" + We are now ready to instantiate an _OpenAI Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. -::: zone pivot="programming-language-csharp" ```csharp Console.WriteLine("Defining agent..."); OpenAIAssistantAgent agent = @@ -290,6 +295,9 @@ OpenAIAssistantAgent agent = ::: zone-end ::: zone pivot="programming-language-python" + +We are now ready to instantiate an _Azure Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. + ```python agent = await AzureAssistantAgent.create( kernel=Kernel(), diff --git a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md index 1905fb7c..589526ef 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md +++ b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md @@ -177,7 +177,7 @@ Configure the following settings in your `.env` file for either Azure OpenAI or ```python AZURE_OPENAI_API_KEY="..." -AZURE_OPENAI_ENDPOINT="https://..." +AZURE_OPENAI_ENDPOINT="https://.openai.azure.com/" AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..." AZURE_OPENAI_API_VERSION="..." @@ -343,7 +343,7 @@ agent = ChatCompletionAgent( The current date and time is: {{$now}}. """, arguments=KernelArguments( - settings=AzureAIPromptExecutionSettings(function_choice_behavior=FunctionChoiceBehavior.Auto()), + settings=AzureChatPromptExecutionSettings(function_choice_behavior=FunctionChoiceBehavior.Auto()), repository="microsoft/semantic-kernel", ), ) From 7666b338a0d27be026485e33203a903e14670fc4 Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Mon, 17 Feb 2025 08:33:50 +0900 Subject: [PATCH 12/70] Add prompt template config import. Remove view from link in Python code pivot. --- semantic-kernel/Frameworks/agent/agent-templates.md | 2 ++ semantic-kernel/concepts/ai-services/chat-completion/index.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/semantic-kernel/Frameworks/agent/agent-templates.md b/semantic-kernel/Frameworks/agent/agent-templates.md index 49cb8ae2..36d0ad38 100644 --- a/semantic-kernel/Frameworks/agent/agent-templates.md +++ b/semantic-kernel/Frameworks/agent/agent-templates.md @@ -179,6 +179,8 @@ ChatCompletionAgent agent = ```python import yaml +from semantic_kernel.prompt_template import PromptTemplateConfig + # Read the YAML file with open("./GenerateStory.yaml", "r", encoding="utf-8") as file: generate_story_yaml = file.read() diff --git a/semantic-kernel/concepts/ai-services/chat-completion/index.md b/semantic-kernel/concepts/ai-services/chat-completion/index.md index 27305c4d..88d3eaea 100644 --- a/semantic-kernel/concepts/ai-services/chat-completion/index.md +++ b/semantic-kernel/concepts/ai-services/chat-completion/index.md @@ -1274,7 +1274,7 @@ execution_settings = OnnxGenAIPromptExecutionSettings() --- > [!TIP] -> To see what you can configure in the execution settings, you can check the class definition in the [source code](https://github.com/microsoft/semantic-kernel/tree/main/python/semantic_kernel/connectors/ai) or check out the [API documentation](/python/api/semantic-kernel/semantic_kernel.connectors.ai?view=semantic-kernel-python). +> To see what you can configure in the execution settings, you can check the class definition in the [source code](https://github.com/microsoft/semantic-kernel/tree/main/python/semantic_kernel/connectors/ai) or check out the [API documentation](/python/api/semantic-kernel/semantic_kernel.connectors.ai). ::: zone-end From c03c0589e399d57f308a4a767d01ac33ecb14bcb Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Mon, 17 Feb 2025 09:42:50 +0900 Subject: [PATCH 13/70] Updates to callout reserved param names with Python function calling. --- .../chat-completion/function-calling/index.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/semantic-kernel/concepts/ai-services/chat-completion/function-calling/index.md b/semantic-kernel/concepts/ai-services/chat-completion/function-calling/index.md index f11b8df5..f122da5b 100644 --- a/semantic-kernel/concepts/ai-services/chat-completion/function-calling/index.md +++ b/semantic-kernel/concepts/ai-services/chat-completion/function-calling/index.md @@ -207,6 +207,41 @@ kernel.add_plugin(OrderPizzaPlugin(pizza_service, user_context, payment_service) > [!NOTE] > Only functions with the `kernel_function` decorator will be serialized and sent to the model. This allows you to have helper functions that are not exposed to the model. +## Reserved Parameter Names for Auto Function Calling + +When using auto function calling in KernelFunctions, certain parameter names are **reserved** and receive special handling. These reserved names allow you to automatically access key objects required for function execution. + +### Reserved Names + +The following parameter names are reserved: +- `kernel` +- `service` +- `execution_settings` +- `arguments` + +### How They Work + +During function invocation, the method [`gather_function_parameters`](https://github.com/microsoft/semantic-kernel/blob/main/python/semantic_kernel/functions/kernel_function_from_method.py#L148) inspects each parameter. If the parameter's name matches one of the reserved names, it is populated with specific objects: + +- **`kernel`**: Injected with the kernel object. +- **`service`**: Populated with the AI service selected based on the provided arguments. +- **`execution_settings`**: Contains settings pertinent to the function's execution. +- **`arguments`**: Receives the entire set of kernel arguments passed during invocation. + +This design ensures that these parameters are automatically managed, eliminating the need for manual extraction or assignment. + +### Example Usage + +Consider the following example: + +```python +class SimplePlugin: + @kernel_function(name="GetWeather", description="Get the weather for a location.") + async def get_the_weather(self, location: str, arguments: KernelArguments) -> str: + # The 'arguments' parameter is reserved and automatically populated with KernelArguments. + return f"Received user input: {location}, the weather is nice!" +``` + ::: zone-end ::: zone pivot="programming-language-java" From 039d3cd570c79cb8c8a23b016cda99aa3e63f2f9 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Mon, 17 Feb 2025 14:55:06 +0100 Subject: [PATCH 14/70] updated filters page --- .../concepts/enterprise-readiness/filters.md | 154 ++++++++++++++++-- 1 file changed, 141 insertions(+), 13 deletions(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index 73adc461..286d3673 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -9,13 +9,11 @@ ms.date: 09/10/2024 ms.service: semantic-kernel --- -::: zone pivot="programming-language-csharp" - # What are Filters? Filters enhance security by providing control and visibility over how and when functions run. This is needed to instill responsible AI principles into your work so that you feel confident your solution is enterprise ready. -For example, filters are leveraged to validate permissions before an approval flow begins. The `IFunctionInvocationFilter` is run to check the permissions of the person that’s looking to submit an approval. This means that only a select group of people will be able to kick off the process. +For example, filters are leveraged to validate permissions before an approval flow begins. The filter runs to check the permissions of the person that’s looking to submit an approval. This means that only a select group of people will be able to kick off the process. A good example of filters is provided [here](https://devblogs.microsoft.com/semantic-kernel/filters-in-semantic-kernel/) in our detailed Semantic Kernel blog post on Filters.   @@ -45,7 +43,9 @@ For cases where filter order is important, it is recommended to add filters dire ## Function Invocation Filter -This filter is triggered every time a Semantic Kernel function is invoked, regardless of whether it is a function created from a prompt or a C# method. +This filter is triggered every time a Semantic Kernel function is invoked, regardless of whether it is a function created from a prompt or a method. + +::: zone pivot="programming-language-csharp" ```csharp /// @@ -80,14 +80,94 @@ Add filter using `Kernel` property: kernel.FunctionInvocationFilters.Add(new LoggingFilter(logger)); ``` + ### Code examples * [Function invocation filter examples](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/FunctionInvocationFiltering.cs) +* +::: zone-end +::: zone pivot="programming-language-python" + +```python + +import logging +from typing import Awaitable, Callable +from semantic_kernel.filters import FunctionInvocationContext + +logger = logging.getLogger(__name__) + +async def logger_filter(context: FunctionInvocationContext, next: Callable[[FunctionInvocationContext], Awaitable[None]]) -> None: + logger.info(f"FunctionInvoking - {context.function.plugin_name}.{context.function.name}") + + await next(context) + + logger.info(f"FunctionInvoked - {context.function.plugin_name}.{context.function.name}") + +# Add filter to the kernel +kernel.add_filter('function_invocation', logger_filter) + +``` + +You can also add a filter directly to the kernel: + +```python + +@kernel.filter('function_invocation') +async def logger_filter(context: FunctionInvocationContext, next: Callable[[FunctionInvocationContext], Awaitable[None]]) -> None: + logger.info(f"FunctionInvoking - {context.function.plugin_name}.{context.function.name}") + + await next(context) + + logger.info(f"FunctionInvoked - {context.function.plugin_name}.{context.function.name}") +``` + + +### Streaming invocation + +Functions in Semantic Kernel can be invoked in two ways: streaming and non-streaming. In streaming mode, a function typically returns `AsyncGenerator`, while in non-streaming mode, it returns `FunctionResult`. This distinction affects how results can be overridden in the filter: in streaming mode, the new function result value must be of type `AsyncGenerator`, whereas in non-streaming mode, it can simply be of type `T`. + +So to build a simple logger filter for streaming, you would use something like this: + +```python +@kernel.filter(FilterTypes.FUNCTION_INVOCATION) +async def streaming_exception_handling( + context: FunctionInvocationContext, + next: Callable[[FunctionInvocationContext], Coroutine[Any, Any, None]], +): + await next(context) + + async def override_stream(stream): + try: + async for partial in stream: + yield partial + except Exception as e: + yield [ + StreamingChatMessageContent(role=AuthorRole.ASSISTANT, content=f"Exception caught: {e}", choice_index=0) + ] + + stream = context.result.value + context.result = FunctionResult(function=context.result.function, value=override_stream(stream)) +``` + +### Code examples +* [Function invocation filter examples](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/function_invocation_filters.py) +* [Streaming function invocation filter examples](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/function_invocation_filters_stream.py) + +::: zone-end +::: zone pivot="programming-language-java" + +## Coming soon + +More info coming soon. + +::: zone-end ## Prompt Render Filter This filter is invoked only during a prompt rendering operation, such as when a function created from a prompt is called. It will not be triggered for Semantic Kernel functions created from methods. +::: zone pivot="programming-language-csharp" + ```csharp /// /// Example of prompt render filter which overrides rendered prompt before sending it to AI. @@ -127,10 +207,37 @@ kernel.PromptRenderFilters.Add(new SafePromptFilter()); * [Prompt render filter examples](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/PromptRenderFiltering.cs) + +::: zone-end +::: zone pivot="programming-language-python" + +```python +from semantic_kernel.filters import FilterTypes, PromptRenderContext + +@kernel.filter(FilterTypes.PROMPT_RENDERING) +async def prompt_rendering_filter(context: PromptRenderContext, next): + await next(context) + context.rendered_prompt = f"You pretend to be Mosscap, but you are Papssom who is the opposite of Moscapp in every way {context.rendered_prompt or ''}" +``` + +### Code examples +* [Prompt render filter examples](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/prompt_filters.py) + +::: zone-end +::: zone pivot="programming-language-java" + +## Coming soon + +More info coming soon. + +::: zone-end + ## Auto Function Invocation Filter This filter is invoked only during an automatic function calling process. It will not be triggered when a function is invoked outside of this process. +::: zone pivot="programming-language-csharp" + ```csharp /// /// Example of auto function invocation filter which terminates function calling process as soon as we have the desired result. @@ -175,6 +282,34 @@ kernel.AutoFunctionInvocationFilters.Add(new EarlyTerminationFilter()); * [Auto function invocation filter examples](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/AutoFunctionInvocationFiltering.cs) +::: zone-end +::: zone pivot="programming-language-python" + +```python + +from semantic_kernel.filters import FilterTypes, AutoFunctionInvocationContext + +@kernel.filter(FilterTypes.AUTO_FUNCTION_INVOCATION) +async def auto_function_invocation_filter(context: AutoFunctionInvocationContext, next): + await next(context) + if context.function_result == "desired result": + context.terminate = True +``` + +### Code examples +* [Auto function invocation filter examples](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/auto_function_invoke_filters.py) + + +::: zone-end +::: zone pivot="programming-language-java" + +## Coming soon + +More info coming soon. + +::: zone-end +::: zone pivot="programming-language-csharp" + ## Streaming and non-streaming invocation Functions in Semantic Kernel can be invoked in two ways: streaming and non-streaming. In streaming mode, a function typically returns `IAsyncEnumerable`, while in non-streaming mode, it returns `FunctionResult`. This distinction affects how results can be overridden in the filter: in streaming mode, the new function result value must be of type `IAsyncEnumerable`, whereas in non-streaming mode, it can simply be of type `T`. To determine which result type needs to be returned, the `context.IsStreaming` flag is available in the filter context model. @@ -245,15 +380,8 @@ ChatMessageContent result = await chatCompletionService.GetChatMessageContentAsy ::: zone-end ::: zone pivot="programming-language-python" -## Coming soon - -More info coming soon. +## More examples: -::: zone-end -::: zone pivot="programming-language-java" - -## Coming soon - -More info coming soon. +* [Retry logic with a filter](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/retry_with_filters.py) ::: zone-end \ No newline at end of file From 39f9534ac03a308084509fa21ac7608a18d2c37a Mon Sep 17 00:00:00 2001 From: Evan Mattson <35585003+moonbox3@users.noreply.github.com> Date: Tue, 18 Feb 2025 08:17:22 +0900 Subject: [PATCH 15/70] Python: merge Python docs updates from live to main (#464) * Improve Python agent learn site samples. * Include links to repo code. * Remove fixed locale from link * Fix python sample resource link * Use site relative links for learn site links. They don't need to be absolute. * Fix media link * Scope link per language * More cleanup * Add prompt template config import. Remove view from link in Python code pivot. * Updates to callout reserved param names with Python function calling. --- README.md | 6 +- .../Frameworks/agent/agent-templates.md | 2 + .../examples/example-agent-collaboration.md | 425 ++++++++++-------- .../agent/examples/example-assistant-code.md | 97 ++-- .../examples/example-assistant-search.md | 7 +- .../agent/examples/example-chat-agent.md | 6 +- .../Frameworks/process/process-deployment.md | 2 +- .../chat-completion/function-calling/index.md | 35 ++ .../ai-services/chat-completion/index.md | 6 +- .../observability/index.md | 10 +- .../observability/telemetry-advanced.md | 4 +- .../telemetry-with-aspire-dashboard.md | 10 +- ...telemetry-with-azure-ai-foundry-tracing.md | 6 +- .../observability/telemetry-with-console.md | 2 +- 14 files changed, 370 insertions(+), 248 deletions(-) diff --git a/README.md b/README.md index 75500b2b..e6f7a7f1 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,12 @@ # Microsoft Semantic Kernel Documentation -This is the GitHub repository for the technical product documentation for **Semantic Kernel**. This documentation is published at [Microsoft Semantic Kernel documentation](https://learn.microsoft.com/semantic-kernel). +This is the GitHub repository for the technical product documentation for **Semantic Kernel**. This documentation is published at [Microsoft Semantic Kernel documentation](/semantic-kernel). ## How to contribute -Thanks for your interest in [contributing](https://learn.microsoft.com/), home of technical content for Microsoft products and services. +Thanks for your interest in contributing to the home of technical content for Microsoft products and services. -To learn how to make contributions to the content in this repository, start with our [Docs contributor guide](https://learn.microsoft.com/contribute). +To learn how to make contributions to the content in this repository, start with our [Docs contributor guide](/contribute). ## Code of conduct diff --git a/semantic-kernel/Frameworks/agent/agent-templates.md b/semantic-kernel/Frameworks/agent/agent-templates.md index 49cb8ae2..36d0ad38 100644 --- a/semantic-kernel/Frameworks/agent/agent-templates.md +++ b/semantic-kernel/Frameworks/agent/agent-templates.md @@ -179,6 +179,8 @@ ChatCompletionAgent agent = ```python import yaml +from semantic_kernel.prompt_template import PromptTemplateConfig + # Read the YAML file with open("./GenerateStory.yaml", "r", encoding="utf-8") as file: generate_story_yaml = file.read() diff --git a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md index 3206ad89..87fe4167 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md +++ b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md @@ -28,6 +28,9 @@ Before proceeding with feature coding, make sure your development environment is ::: zone pivot="programming-language-csharp" +> [!TIP] +> This sample uses an optional text file as part of processing. If you'd like to use it, you may download it [here](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/LearnResources/Resources/WomensSuffrage.txt). Place the file in your code working directory. + Start by creating a _Console_ project. Then, include the following package references to ensure all required dependencies are available. To add package dependencies from the command-line use the `dotnet` command: @@ -68,11 +71,20 @@ The _Agent Framework_ is experimental and requires warning suppression. This ma ::: zone-end ::: zone pivot="programming-language-python" + +> [!TIP] +> This sample uses an optional text file as part of processing. If you'd like to use it, you may download it [here](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/resources/WomensSuffrage.txt). Place the file in your code working directory. + +Start by installing the Semantic Kernel Python package. + +```bash +pip install semantic-kernel +``` + ```python import asyncio import os import copy -import pyperclip # Install via pip from semantic_kernel.agents import AgentGroupChat, ChatCompletionAgent from semantic_kernel.agents.strategies.selection.kernel_function_selection_strategy import ( @@ -167,7 +179,7 @@ Configure the following settings in your `.env` file for either Azure OpenAI or ```python AZURE_OPENAI_API_KEY="..." -AZURE_OPENAI_ENDPOINT="https://..." +AZURE_OPENAI_ENDPOINT="https://.openai.azure.com/" AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..." AZURE_OPENAI_API_VERSION="..." @@ -254,11 +266,6 @@ toolKernel.Plugins.AddFromType(); ``` ::: zone-end -::: zone pivot="programming-language-python" -```python -tool_kernel = copy.deepcopy(kernel) -tool_kernel.add_plugin(ClipboardAccess(), plugin_name="clipboard") -``` ::: zone-end ::: zone pivot="programming-language-java" @@ -267,9 +274,9 @@ tool_kernel.add_plugin(ClipboardAccess(), plugin_name="clipboard") ::: zone-end +::: zone pivot="programming-language-csharp" The _Clipboard_ plugin may be defined as part of the sample. -::: zone pivot="programming-language-csharp" ```csharp private sealed class ClipboardAccess { @@ -297,21 +304,6 @@ private sealed class ClipboardAccess ``` ::: zone-end -::: zone pivot="programming-language-python" - -Note: we are leveraging a Python package called pyperclip. Please install is using pip. - -```python -class ClipboardAccess: - @kernel_function - def set_clipboard(content: str): - if not content.strip(): - return - - pyperclip.copy(content) -``` -::: zone-end - ::: zone pivot="programming-language-java" > Agents are currently unavailable in Java. @@ -320,9 +312,9 @@ class ClipboardAccess: ### Agent Definition +::: zone pivot="programming-language-csharp" Let's declare the agent names as `const` so they might be referenced in _Agent Group Chat_ strategies: -::: zone pivot="programming-language-csharp" ```csharp const string ReviewerName = "Reviewer"; const string WriterName = "Writer"; @@ -330,6 +322,9 @@ const string WriterName = "Writer"; ::: zone-end ::: zone pivot="programming-language-python" + +We will declare the agent names as "Reviewer" and "Writer." + ```python REVIEWER_NAME = "Reviewer" COPYWRITER_NAME = "Writer" @@ -379,23 +374,20 @@ ChatCompletionAgent agentReviewer = ::: zone pivot="programming-language-python" ```python agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, - kernel=_create_kernel_with_chat_completion(REVIEWER_NAME), - name=REVIEWER_NAME, - instructions=""" - Your responsiblity is to review and identify how to improve user provided content. - If the user has providing input or direction for content already provided, specify how to - address this input. - Never directly perform the correction or provide example. - Once the content has been updated in a subsequent response, you will review the content - again until satisfactory. - Always copy satisfactory content to the clipboard using available tools and inform user. - - RULES: - - Only identify suggestions that are specific and actionable. - - Verify previous suggestions have been addressed. - - Never repeat previous suggestions. - """, + service_id=REVIEWER_NAME, + kernel=kernel, + name=REVIEWER_NAME, + instructions=""" +Your responsibility is to review and identify how to improve user provided content. +If the user has provided input or direction for content already provided, specify how to address this input. +Never directly perform the correction or provide an example. +Once the content has been updated in a subsequent response, review it again until it is satisfactory. + +RULES: +- Only identify suggestions that are specific and actionable. +- Verify previous suggestions have been addressed. +- Never repeat previous suggestions. +""", ) ``` ::: zone-end @@ -406,11 +398,11 @@ agent_reviewer = ChatCompletionAgent( ::: zone-end -The _Writer_ agent is is similiar, but doesn't require the specification of _Execution Settings_ since it isn't configured with a plug-in. +::: zone pivot="programming-language-csharp" +The _Writer_ agent is similiar, but doesn't require the specification of _Execution Settings_ since it isn't configured with a plug-in. Here the _Writer_ is given a single-purpose task, follow direction and rewrite the content. -::: zone pivot="programming-language-csharp" ```csharp ChatCompletionAgent agentWriter = new() @@ -430,19 +422,19 @@ ChatCompletionAgent agentWriter = ::: zone-end ::: zone pivot="programming-language-python" +The _Writer_ agent is similiar. It is given a single-purpose task, follow direction and rewrite the content. ```python agent_writer = ChatCompletionAgent( - service_id=COPYWRITER_NAME, - kernel=_create_kernel_with_chat_completion(COPYWRITER_NAME), - name=COPYWRITER_NAME, - instructions=""" - Your sole responsiblity is to rewrite content according to review suggestions. - - - Always apply all review direction. - - Always revise the content in its entirety without explanation. - - Never address the user. - """, -) + service_id=WRITER_NAME, + kernel=kernel, + name=WRITER_NAME, + instructions=""" +Your sole responsibility is to rewrite content according to review suggestions. +- Always apply all review directions. +- Always revise the content in its entirety without explanation. +- Never address the user. +""", + ) ``` ::: zone-end @@ -489,25 +481,25 @@ KernelFunction selectionFunction = ::: zone pivot="programming-language-python" ```python selection_function = KernelFunctionFromPrompt( - function_name="selection", - prompt=f""" - Determine which participant takes the next turn in a conversation based on the the most recent participant. - State only the name of the participant to take the next turn. - No participant should take more than one turn in a row. - - Choose only from these participants: - - {REVIEWER_NAME} - - {COPYWRITER_NAME} - - Always follow these rules when selecting the next participant: - - After user input, it is {COPYWRITER_NAME}'s turn. - - After {COPYWRITER_NAME} replies, it is {REVIEWER_NAME}'s turn. - - After {REVIEWER_NAME} provides feedback, it is {COPYWRITER_NAME}'s turn. - - History: - {{{{$history}}}} - """, -) + function_name="selection", + prompt=f""" +Examine the provided RESPONSE and choose the next participant. +State only the name of the chosen participant without explanation. +Never choose the participant named in the RESPONSE. + +Choose only from these participants: +- {REVIEWER_NAME} +- {WRITER_NAME} + +Rules: +- If RESPONSE is user input, it is {REVIEWER_NAME}'s turn. +- If RESPONSE is by {REVIEWER_NAME}, it is {WRITER_NAME}'s turn. +- If RESPONSE is by {WRITER_NAME}, it is {REVIEWER_NAME}'s turn. + +RESPONSE: +{{{{$lastmessage}}}} +""" + ) ``` ::: zone-end @@ -540,20 +532,20 @@ KernelFunction terminationFunction = ::: zone pivot="programming-language-python" ```python -TERMINATION_KEYWORD = "yes" - -termination_function = KernelFunctionFromPrompt( - function_name="termination", - prompt=f""" - Examine the RESPONSE and determine whether the content has been deemed satisfactory. - If content is satisfactory, respond with a single word without explanation: {TERMINATION_KEYWORD}. - If specific suggestions are being provided, it is not satisfactory. - If no correction is suggested, it is satisfactory. + termination_keyword = "yes" - RESPONSE: - {{{{$history}}}} - """, -) + termination_function = KernelFunctionFromPrompt( + function_name="termination", + prompt=f""" +Examine the RESPONSE and determine whether the content has been deemed satisfactory. +If the content is satisfactory, respond with a single word without explanation: {termination_keyword}. +If specific suggestions are being provided, it is not satisfactory. +If no correction is suggested, it is satisfactory. + +RESPONSE: +{{{{$lastmessage}}}} +""" + ) ``` ::: zone-end @@ -573,7 +565,7 @@ ChatHistoryTruncationReducer historyReducer = new(1); ::: zone pivot="programming-language-python" ```python -**ChatHistoryReducer is coming soon to Python.** +history_reducer = ChatHistoryTruncationReducer(target_count=1) ``` ::: zone-end @@ -644,26 +636,28 @@ Creating `AgentGroupChat` involves: Notice that each strategy is responsible for parsing the `KernelFunction` result. ```python chat = AgentGroupChat( - agents=[agent_writer, agent_reviewer], + agents=[agent_reviewer, agent_writer], selection_strategy=KernelFunctionSelectionStrategy( + initial_agent=agent_reviewer, function=selection_function, - kernel=_create_kernel_with_chat_completion("selection"), - result_parser=lambda result: str(result.value[0]) if result.value is not None else COPYWRITER_NAME, - agent_variable_name="agents", - history_variable_name="history", + kernel=kernel, + result_parser=lambda result: str(result.value[0]).strip() if result.value[0] is not None else WRITER_NAME, + history_variable_name="lastmessage", history_reducer=history_reducer, ), termination_strategy=KernelFunctionTerminationStrategy( agents=[agent_reviewer], function=termination_function, - kernel=_create_kernel_with_chat_completion("termination"), - result_parser=lambda result: TERMINATION_KEYWORD in str(result.value[0]).lower(), - history_variable_name="history", + kernel=kernel, + result_parser=lambda result: termination_keyword in str(result.value[0]).lower(), + history_variable_name="lastmessage", maximum_iterations=10, history_reducer=history_reducer, ), ) ``` + +The `lastmessage` `history_variable_name` corresponds with the `KernelFunctionSelectionStrategy` and the `KernelFunctionTerminationStrategy` prompt that was defined above. This is where the last message is placed when rendering the prompt. ::: zone-end ::: zone pivot="programming-language-java" @@ -702,15 +696,14 @@ while not is_complete: ::: zone-end +::: zone pivot="programming-language-csharp" Now let's capture user input within the previous loop. In this case: - Empty input will be ignored - The term `EXIT` will signal that the conversation is completed - The term `RESET` will clear the _Agent Group Chat_ history - Any term starting with `@` will be treated as a file-path whose content will be provided as input -- Valid input will be added to the _Agent Group Chaty_ as a _User_ message. - +- Valid input will be added to the _Agent Group Chat_ as a _User_ message. -::: zone pivot="programming-language-csharp" ```csharp Console.WriteLine(); Console.Write("> "); @@ -757,8 +750,18 @@ chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, input)); ::: zone-end ::: zone pivot="programming-language-python" +Now let's capture user input within the previous loop. In this case: +- Empty input will be ignored. +- The term `exit` will signal that the conversation is complete. +- The term `reset` will clear the _Agent Group Chat_ history. +- Any term starting with `@` will be treated as a file-path whose content will be provided as input. +- Valid input will be added to the _Agent Group Chat_ as a _User_ message. + +The operation logic inside the while loop looks like: + ```python -user_input = input("User:> ") +print() +user_input = input("User > ").strip() if not user_input: continue @@ -771,18 +774,22 @@ if user_input.lower() == "reset": print("[Conversation has been reset]") continue -if user_input.startswith("@") and len(input) > 1: - file_path = input[1:] +# Try to grab files from the script's current directory +if user_input.startswith("@") and len(user_input) > 1: + file_name = user_input[1:] + script_dir = os.path.dirname(os.path.abspath(__file__)) + file_path = os.path.join(script_dir, file_name) try: if not os.path.exists(file_path): print(f"Unable to access file: {file_path}") continue - with open(file_path) as file: + with open(file_path, "r", encoding="utf-8") as file: user_input = file.read() except Exception: print(f"Unable to access file: {file_path}") continue +# Add the current user_input to the chat await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=user_input)) ``` ::: zone-end @@ -826,13 +833,17 @@ catch (HttpOperationException exception) ::: zone pivot="programming-language-python" ```python -chat.is_complete = False -async for response in chat.invoke(): - print(f"# {response.role} - {response.name or '*'}: '{response.content}'") +try: + async for response in chat.invoke(): + if response is None or not response.name: + continue + print() + print(f"# {response.name.upper()}:\n{response.content}") +except Exception as e: + print(f"Error during chat invocation: {e}") -if chat.is_complete: - is_complete = True - break +# Reset the chat's complete flag for the new conversation round. +chat.is_complete = False ``` ::: zone-end @@ -845,6 +856,8 @@ if chat.is_complete: ## Final +::: zone pivot="programming-language-csharp" + Bringing all the steps together, we have the final code for this example. The complete implementation is provided below. Try using these suggested inputs: @@ -852,14 +865,12 @@ Try using these suggested inputs: 1. Hi 2. {"message: "hello world"} 3. {"message": "hello world"} -4. Semantic Kernel (SK) is an open-source SDK that enables developers to build and orchestrate complex AI workflows that involve natural language processing (NLP) and machine learning models. It provies a flexible platform for integrating AI capabilities such as semantic search, text summarization, and dialogue systems into applications. With SK, you can easily combine different AI services and models, define thei relationships, and orchestrate interactions between them. +4. Semantic Kernel (SK) is an open-source SDK that enables developers to build and orchestrate complex AI workflows that involve natural language processing (NLP) and machine learning models. It provies a flexible platform for integrating AI capabilities such as semantic search, text summarization, and dialogue systems into applications. With SK, you can easily combine different AI services and models, define their relationships, and orchestrate interactions between them. 5. make this two paragraphs 6. thank you 7. @.\WomensSuffrage.txt 8. its good, but is it ready for my college professor? - -::: zone pivot="programming-language-csharp" ```csharp // Copyright (c) Microsoft. All rights reserved. @@ -1114,12 +1125,28 @@ public static class Program ::: zone-end ::: zone pivot="programming-language-python" + +Bringing all the steps together, we now have the final code for this example. The complete implementation is shown below. + +You can try using one of the suggested inputs. As the agent chat begins, the agents will exchange messages for several iterations until the reviewer agent is satisfied with the copywriter's work. The `while` loop ensures the conversation continues, even if the chat is initially considered complete, by resetting the `is_complete` flag to `False`. + +1. Rozes are red, violetz are blue. +2. Semantic Kernel (SK) is an open-source SDK that enables developers to build and orchestrate complex AI workflows that involve natural language processing (NLP) and machine learning models. It provies a flexible platform for integrating AI capabilities such as semantic search, text summarization, and dialogue systems into applications. With SK, you can easily combine different AI services and models, define their relationships, and orchestrate interactions between them. +4. Make this two paragraphs +5. thank you +7. @WomensSuffrage.txt +8. It's good, but is it ready for my college professor? + +> [!TIP] +> You can reference any file by providing `@`. To reference the "WomensSuffrage" text from above, download it [here](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/resources/WomensSuffrage.txt) and place it in your current working directory. You can then reference it with `@WomensSuffrage.txt`. + ```python # Copyright (c) Microsoft. All rights reserved. import asyncio import os +from semantic_kernel import Kernel from semantic_kernel.agents import AgentGroupChat, ChatCompletionAgent from semantic_kernel.agents.strategies.selection.kernel_function_selection_strategy import ( KernelFunctionSelectionStrategy, @@ -1128,12 +1155,10 @@ from semantic_kernel.agents.strategies.termination.kernel_function_termination_s KernelFunctionTerminationStrategy, ) from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion -from semantic_kernel.contents import ChatHistoryTruncationReducer from semantic_kernel.contents.chat_message_content import ChatMessageContent +from semantic_kernel.contents.history_reducer.chat_history_truncation_reducer import ChatHistoryTruncationReducer from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.functions.kernel_function_decorator import kernel_function from semantic_kernel.functions.kernel_function_from_prompt import KernelFunctionFromPrompt -from semantic_kernel.kernel import Kernel ################################################################### # The following sample demonstrates how to create a simple, # @@ -1142,122 +1167,123 @@ from semantic_kernel.kernel import Kernel # complete a user's task. # ################################################################### - -class ClipboardAccess: - @kernel_function - def set_clipboard(content: str): - if not content.strip(): - return - - pyperclip.copy(content) - - +# Define agent names REVIEWER_NAME = "Reviewer" -COPYWRITER_NAME = "Writer" +WRITER_NAME = "Writer" -def _create_kernel_with_chat_completion(service_id: str) -> Kernel: +def create_kernel() -> Kernel: + """Creates a Kernel instance with an Azure OpenAI ChatCompletion service.""" kernel = Kernel() - kernel.add_service(AzureChatCompletion(service_id=service_id)) + kernel.add_service(service=AzureChatCompletion()) return kernel async def main(): + # Create a single kernel instance for all agents. + kernel = create_kernel() + + # Create ChatCompletionAgents using the same kernel. agent_reviewer = ChatCompletionAgent( service_id=REVIEWER_NAME, - kernel=_create_kernel_with_chat_completion(REVIEWER_NAME), + kernel=kernel, name=REVIEWER_NAME, instructions=""" - Your responsiblity is to review and identify how to improve user provided content. - If the user has providing input or direction for content already provided, specify how to - address this input. - Never directly perform the correction or provide example. - Once the content has been updated in a subsequent response, you will review the content - again until satisfactory. - Always copy satisfactory content to the clipboard using available tools and inform user. - - RULES: - - Only identify suggestions that are specific and actionable. - - Verify previous suggestions have been addressed. - - Never repeat previous suggestions. - """, +Your responsibility is to review and identify how to improve user provided content. +If the user has provided input or direction for content already provided, specify how to address this input. +Never directly perform the correction or provide an example. +Once the content has been updated in a subsequent response, review it again until it is satisfactory. + +RULES: +- Only identify suggestions that are specific and actionable. +- Verify previous suggestions have been addressed. +- Never repeat previous suggestions. +""", ) agent_writer = ChatCompletionAgent( - service_id=COPYWRITER_NAME, - kernel=_create_kernel_with_chat_completion(COPYWRITER_NAME), - name=COPYWRITER_NAME, + service_id=WRITER_NAME, + kernel=kernel, + name=WRITER_NAME, instructions=""" - Your sole responsiblity is to rewrite content according to review suggestions. - - - Always apply all review direction. - - Always revise the content in its entirety without explanation. - - Never address the user. - """, +Your sole responsibility is to rewrite content according to review suggestions. +- Always apply all review directions. +- Always revise the content in its entirety without explanation. +- Never address the user. +""", ) + # Define a selection function to determine which agent should take the next turn. selection_function = KernelFunctionFromPrompt( function_name="selection", prompt=f""" - Determine which participant takes the next turn in a conversation based on the the most recent participant. - State only the name of the participant to take the next turn. - No participant should take more than one turn in a row. - - Choose only from these participants: - - {REVIEWER_NAME} - - {COPYWRITER_NAME} - - Always follow these rules when selecting the next participant: - - After user input, it is {COPYWRITER_NAME}'s turn. - - After {COPYWRITER_NAME} replies, it is {REVIEWER_NAME}'s turn. - - After {REVIEWER_NAME} provides feedback, it is {COPYWRITER_NAME}'s turn. - - History: - {{{{$history}}}} - """, +Examine the provided RESPONSE and choose the next participant. +State only the name of the chosen participant without explanation. +Never choose the participant named in the RESPONSE. + +Choose only from these participants: +- {REVIEWER_NAME} +- {WRITER_NAME} + +Rules: +- If RESPONSE is user input, it is {REVIEWER_NAME}'s turn. +- If RESPONSE is by {REVIEWER_NAME}, it is {WRITER_NAME}'s turn. +- If RESPONSE is by {WRITER_NAME}, it is {REVIEWER_NAME}'s turn. + +RESPONSE: +{{{{$lastmessage}}}} +""", ) - TERMINATION_KEYWORD = "yes" + # Define a termination function where the reviewer signals completion with "yes". + termination_keyword = "yes" termination_function = KernelFunctionFromPrompt( function_name="termination", prompt=f""" - Examine the RESPONSE and determine whether the content has been deemed satisfactory. - If content is satisfactory, respond with a single word without explanation: {TERMINATION_KEYWORD}. - If specific suggestions are being provided, it is not satisfactory. - If no correction is suggested, it is satisfactory. - - RESPONSE: - {{{{$history}}}} - """, +Examine the RESPONSE and determine whether the content has been deemed satisfactory. +If the content is satisfactory, respond with a single word without explanation: {termination_keyword}. +If specific suggestions are being provided, it is not satisfactory. +If no correction is suggested, it is satisfactory. + +RESPONSE: +{{{{$lastmessage}}}} +""", ) - history_reducer = ChatHistoryTruncationReducer(target_count=1) + history_reducer = ChatHistoryTruncationReducer(target_count=5) + # Create the AgentGroupChat with selection and termination strategies. chat = AgentGroupChat( - agents=[agent_writer, agent_reviewer], + agents=[agent_reviewer, agent_writer], selection_strategy=KernelFunctionSelectionStrategy( + initial_agent=agent_reviewer, function=selection_function, - kernel=_create_kernel_with_chat_completion("selection"), - result_parser=lambda result: str(result.value[0]) if result.value is not None else COPYWRITER_NAME, - agent_variable_name="agents", - history_variable_name="history", + kernel=kernel, + result_parser=lambda result: str(result.value[0]).strip() if result.value[0] is not None else WRITER_NAME, + history_variable_name="lastmessage", history_reducer=history_reducer, ), termination_strategy=KernelFunctionTerminationStrategy( agents=[agent_reviewer], function=termination_function, - kernel=_create_kernel_with_chat_completion("termination"), - result_parser=lambda result: TERMINATION_KEYWORD in str(result.value[0]).lower(), - history_variable_name="history", + kernel=kernel, + result_parser=lambda result: termination_keyword in str(result.value[0]).lower(), + history_variable_name="lastmessage", maximum_iterations=10, history_reducer=history_reducer, ), ) - is_complete: bool = False + print( + "Ready! Type your input, or 'exit' to quit, 'reset' to restart the conversation. " + "You may pass in a file path using @." + ) + + is_complete = False while not is_complete: - user_input = input("User:> ") + print() + user_input = input("User > ").strip() if not user_input: continue @@ -1270,31 +1296,42 @@ async def main(): print("[Conversation has been reset]") continue - if user_input.startswith("@") and len(input) > 1: - file_path = input[1:] + # Try to grab files from the script's current directory + if user_input.startswith("@") and len(user_input) > 1: + file_name = user_input[1:] + script_dir = os.path.dirname(os.path.abspath(__file__)) + file_path = os.path.join(script_dir, file_name) try: if not os.path.exists(file_path): print(f"Unable to access file: {file_path}") continue - with open(file_path) as file: + with open(file_path, "r", encoding="utf-8") as file: user_input = file.read() except Exception: print(f"Unable to access file: {file_path}") continue + # Add the current user_input to the chat await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=user_input)) - async for response in chat.invoke(): - print(f"# {response.role} - {response.name or '*'}: '{response.content}'") + try: + async for response in chat.invoke(): + if response is None or not response.name: + continue + print() + print(f"# {response.name.upper()}:\n{response.content}") + except Exception as e: + print(f"Error during chat invocation: {e}") - if chat.is_complete: - is_complete = True - break + # Reset the chat's complete flag for the new conversation round. + chat.is_complete = False if __name__ == "__main__": asyncio.run(main()) ``` + +You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/agent_docs/agent_collaboration.py), as shown above, in our repo. ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index 67aa0290..c9b79287 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -92,7 +92,7 @@ from semantic_kernel.contents.utils.author_role import AuthorRole from semantic_kernel.kernel import Kernel ``` -Additionally, copy the `PopulationByAdmin1.csv` and `PopulationByCountry.csv` data files from [_Semantic Kernel_ `LearnResources` Project](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/learn_resources/resources). Add these files in your project folder. +Additionally, copy the `PopulationByAdmin1.csv` and `PopulationByCountry.csv` data files from the [_Semantic Kernel_ `learn_resources/resources` directory](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/learn_resources/resources). Add these files to your working directory. ::: zone-end ::: zone pivot="programming-language-java" @@ -172,7 +172,7 @@ Configure the following settings in your `.env` file for either Azure OpenAI or ```python AZURE_OPENAI_API_KEY="..." -AZURE_OPENAI_ENDPOINT="https://..." +AZURE_OPENAI_ENDPOINT="https://.openai.azure.com/" AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..." AZURE_OPENAI_API_VERSION="..." @@ -181,6 +181,9 @@ OPENAI_ORG_ID="" OPENAI_CHAT_MODEL_ID="" ``` +[!TIP] +Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](/azure/ai-services/openai/api-version-deprecation). + Once configured, the respective AI service classes will pick up the required variables and use them during instantiation. ::: zone-end @@ -235,18 +238,26 @@ OpenAIFile fileDataCountryList = await fileClient.UploadFileAsync("PopulationByC ::: zone-end ::: zone pivot="programming-language-python" + +> [!TIP] +> You may need to adjust the file paths depending upon where your files are located. + ```python # Let's form the file paths that we will later pass to the assistant csv_file_path_1 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", "PopulationByAdmin1.csv", ) csv_file_path_2 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", "PopulationByCountry.csv", ) ``` +You may need to modify the path creation code based on the storage location of your CSV files. + ::: zone-end ::: zone pivot="programming-language-java" @@ -257,9 +268,10 @@ csv_file_path_2 = os.path.join( ### Agent Definition +::: zone pivot="programming-language-csharp" + We are now ready to instantiate an _OpenAI Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. -::: zone pivot="programming-language-csharp" ```csharp Console.WriteLine("Defining agent..."); OpenAIAssistantAgent agent = @@ -283,20 +295,23 @@ OpenAIAssistantAgent agent = ::: zone-end ::: zone pivot="programming-language-python" + +We are now ready to instantiate an _Azure Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. + ```python agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", - instructions=""" - Analyze the available data to provide an answer to the user's question. - Always format response using markdown. - Always include a numerical index that starts at 1 for any lists or tables. - Always sort lists in ascending order. - """, - enable_code_interpreter=True, - code_interpreter_filenames=[csv_file_path_1, csv_file_path_2], - ) + kernel=Kernel(), + service_id="agent", + name="SampleAssistantAgent", + instructions=""" + Analyze the available data to provide an answer to the user's question. + Always format response using markdown. + Always include a numerical index that starts at 1 for any lists or tables. + Always sort lists in ascending order. + """, + enable_code_interpreter=True, + code_interpreter_filenames=[csv_file_path_1, csv_file_path_2], +) ``` ::: zone-end @@ -722,7 +737,10 @@ public static class Program ::: zone pivot="programming-language-python" ```python +# Copyright (c) Microsoft. All rights reserved. + import asyncio +import logging import os from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent @@ -731,19 +749,29 @@ from semantic_kernel.contents.streaming_file_reference_content import StreamingF from semantic_kernel.contents.utils.author_role import AuthorRole from semantic_kernel.kernel import Kernel +logging.basicConfig(level=logging.ERROR) + +################################################################### +# The following sample demonstrates how to create a simple, # +# OpenAI assistant agent that utilizes the code interpreter # +# to analyze uploaded files. # +################################################################### + # Let's form the file paths that we will later pass to the assistant csv_file_path_1 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", "PopulationByAdmin1.csv", ) csv_file_path_2 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", "PopulationByCountry.csv", ) -async def download_file_content(agent, file_id: str): +async def download_file_content(agent: AzureAssistantAgent, file_id: str): try: # Fetch the content of the file using the provided method response_content = await agent.client.files.content(file_id) @@ -766,7 +794,7 @@ async def download_file_content(agent, file_id: str): print(f"An error occurred while downloading file {file_id}: {str(e)}") -async def download_response_image(agent, file_ids: list[str]): +async def download_response_image(agent: AzureAssistantAgent, file_ids: list[str]): if file_ids: # Iterate over file_ids and download each one for file_id in file_ids: @@ -801,30 +829,41 @@ async def main(): if user_input.lower() == "exit": is_complete = True - break await agent.add_chat_message( thread_id=thread_id, message=ChatMessageContent(role=AuthorRole.USER, content=user_input) ) - is_code: bool = False - async for response in agent.invoke_stream(thread_id=thread_id): - if is_code != response.metadata.get("code"): - print() - is_code = not is_code - - print(f"{response.content}", end="", flush=True) + is_code = False + last_role = None + async for response in agent.invoke_stream(thread_id=thread_id): + current_is_code = response.metadata.get("code", False) + + if current_is_code: + if not is_code: + print("\n\n```python") + is_code = True + print(response.content, end="", flush=True) + else: + if is_code: + print("\n```") + is_code = False + last_role = None + if hasattr(response, "role") and response.role is not None and last_role != response.role: + print(f"\n# {response.role}: ", end="", flush=True) + last_role = response.role + print(response.content, end="", flush=True) file_ids.extend([ item.file_id for item in response.items if isinstance(item, StreamingFileReferenceContent) ]) - - print() + if is_code: + print("```\n") await download_response_image(agent, file_ids) file_ids.clear() finally: - print("Cleaning up resources...") + print("\nCleaning up resources...") if agent is not None: [await agent.delete_file(file_id) for file_id in agent.code_interpreter_file_ids] await agent.delete_thread(thread_id) @@ -834,6 +873,8 @@ async def main(): if __name__ == "__main__": asyncio.run(main()) ``` + +You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/agent_docs/assistant_code.py), as shown above, in our repo. ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index ca3c70b3..f38a28d4 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -174,7 +174,7 @@ Configure the following settings in your `.env` file for either Azure OpenAI or ```python AZURE_OPENAI_API_KEY="..." -AZURE_OPENAI_ENDPOINT="https://..." +AZURE_OPENAI_ENDPOINT="https://.openai.azure.com/" AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..." AZURE_OPENAI_API_VERSION="..." @@ -183,6 +183,9 @@ OPENAI_ORG_ID="" OPENAI_CHAT_MODEL_ID="" ``` +> [!TIP] +> Azure Assistants require an API version of at least 2024-05-01-preview. As new features are introduced, API versions are updated accordingly. As of this writing, the latest version is 2025-01-01-preview. For the most up-to-date versioning details, refer to the [Azure OpenAI API preview lifecycle](/azure/ai-services/openai/api-version-deprecation). + Once configured, the respective AI service classes will pick up the required variables and use them during instantiation. ::: zone-end @@ -780,6 +783,8 @@ async def main(): if __name__ == "__main__": asyncio.run(main()) ``` + +You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/agent_docs/assistant_search.py), as shown above, in our repo. ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md index 7870d9ed..589526ef 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md +++ b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md @@ -177,7 +177,7 @@ Configure the following settings in your `.env` file for either Azure OpenAI or ```python AZURE_OPENAI_API_KEY="..." -AZURE_OPENAI_ENDPOINT="https://..." +AZURE_OPENAI_ENDPOINT="https://.openai.azure.com/" AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="..." AZURE_OPENAI_API_VERSION="..." @@ -343,7 +343,7 @@ agent = ChatCompletionAgent( The current date and time is: {{$now}}. """, arguments=KernelArguments( - settings=AzureAIPromptExecutionSettings(function_choice_behavior=FunctionChoiceBehavior.Auto()), + settings=AzureChatPromptExecutionSettings(function_choice_behavior=FunctionChoiceBehavior.Auto()), repository="microsoft/semantic-kernel", ), ) @@ -669,6 +669,8 @@ async def main(): if __name__ == "__main__": asyncio.run(main()) ``` + +You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/agent_docs/chat_agent.py), as shown above, in our repo. ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/Frameworks/process/process-deployment.md b/semantic-kernel/Frameworks/process/process-deployment.md index 3be467a4..8ba8aa0e 100644 --- a/semantic-kernel/Frameworks/process/process-deployment.md +++ b/semantic-kernel/Frameworks/process/process-deployment.md @@ -18,7 +18,7 @@ The Process Framework provides an in-process runtime that allows developers to r ## Cloud Runtimes -For scenarios requiring scalability and distributed processing, the Process Framework supports cloud runtimes such as [**Orleans**](https://learn.microsoft.com/dotnet/orleans/overview) and [**Dapr**](https://dapr.io/). These options empower developers to deploy processes in a distributed manner, facilitating high availability and load balancing across multiple instances. By leveraging these cloud runtimes, organizations can streamline their operations and manage substantial workloads with ease. +For scenarios requiring scalability and distributed processing, the Process Framework supports cloud runtimes such as [**Orleans**](/dotnet/orleans/overview) and [**Dapr**](https://dapr.io/). These options empower developers to deploy processes in a distributed manner, facilitating high availability and load balancing across multiple instances. By leveraging these cloud runtimes, organizations can streamline their operations and manage substantial workloads with ease. - **Orleans Runtime:** This framework provides a programming model for building distributed applications and is particularly well-suited for handling virtual actors in a resilient manner, complementing the Process Framework’s event-driven architecture. diff --git a/semantic-kernel/concepts/ai-services/chat-completion/function-calling/index.md b/semantic-kernel/concepts/ai-services/chat-completion/function-calling/index.md index f11b8df5..f122da5b 100644 --- a/semantic-kernel/concepts/ai-services/chat-completion/function-calling/index.md +++ b/semantic-kernel/concepts/ai-services/chat-completion/function-calling/index.md @@ -207,6 +207,41 @@ kernel.add_plugin(OrderPizzaPlugin(pizza_service, user_context, payment_service) > [!NOTE] > Only functions with the `kernel_function` decorator will be serialized and sent to the model. This allows you to have helper functions that are not exposed to the model. +## Reserved Parameter Names for Auto Function Calling + +When using auto function calling in KernelFunctions, certain parameter names are **reserved** and receive special handling. These reserved names allow you to automatically access key objects required for function execution. + +### Reserved Names + +The following parameter names are reserved: +- `kernel` +- `service` +- `execution_settings` +- `arguments` + +### How They Work + +During function invocation, the method [`gather_function_parameters`](https://github.com/microsoft/semantic-kernel/blob/main/python/semantic_kernel/functions/kernel_function_from_method.py#L148) inspects each parameter. If the parameter's name matches one of the reserved names, it is populated with specific objects: + +- **`kernel`**: Injected with the kernel object. +- **`service`**: Populated with the AI service selected based on the provided arguments. +- **`execution_settings`**: Contains settings pertinent to the function's execution. +- **`arguments`**: Receives the entire set of kernel arguments passed during invocation. + +This design ensures that these parameters are automatically managed, eliminating the need for manual extraction or assignment. + +### Example Usage + +Consider the following example: + +```python +class SimplePlugin: + @kernel_function(name="GetWeather", description="Get the weather for a location.") + async def get_the_weather(self, location: str, arguments: KernelArguments) -> str: + # The 'arguments' parameter is reserved and automatically populated with KernelArguments. + return f"Received user input: {location}, the weather is nice!" +``` + ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/concepts/ai-services/chat-completion/index.md b/semantic-kernel/concepts/ai-services/chat-completion/index.md index c8218409..88d3eaea 100644 --- a/semantic-kernel/concepts/ai-services/chat-completion/index.md +++ b/semantic-kernel/concepts/ai-services/chat-completion/index.md @@ -920,7 +920,7 @@ chat_completion_service = AzureChatCompletion(service_id="my-service-id") ``` > [!NOTE] -> The `AzureChatCompletion` service also supports [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. +> The `AzureChatCompletion` service also supports [Microsoft Entra](/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. # [OpenAI](#tab/python-OpenAI) @@ -967,7 +967,7 @@ chat_completion_service = AzureAIInferenceChatCompletion( ``` > [!NOTE] -> The `AzureAIInferenceChatCompletion` service also supports [Microsoft Entra](https://learn.microsoft.com/en-us/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. +> The `AzureAIInferenceChatCompletion` service also supports [Microsoft Entra](/entra/identity/authentication/overview-authentication) authentication. If you don't provide an API key, the service will attempt to authenticate using the Entra token. # [Anthropic](#tab/python-Anthropic) @@ -1274,7 +1274,7 @@ execution_settings = OnnxGenAIPromptExecutionSettings() --- > [!TIP] -> To see what you can configure in the execution settings, you can check the class definition in the [source code](https://github.com/microsoft/semantic-kernel/tree/main/python/semantic_kernel/connectors/ai) or check out the [API documentation](https://learn.microsoft.com/en-us/python/api/semantic-kernel/semantic_kernel.connectors.ai?view=semantic-kernel-python). +> To see what you can configure in the execution settings, you can check the class definition in the [source code](https://github.com/microsoft/semantic-kernel/tree/main/python/semantic_kernel/connectors/ai) or check out the [API documentation](/python/api/semantic-kernel/semantic_kernel.connectors.ai). ::: zone-end diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/index.md b/semantic-kernel/concepts/enterprise-readiness/observability/index.md index 41583f59..c88edbe5 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/index.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/index.md @@ -20,8 +20,8 @@ Observability is typically achieved through logging, metrics, and tracing. They Useful materials for further reading: - [Observability defined by Cloud Native Computing Foundation](https://glossary.cncf.io/observability/) -- [Distributed tracing](https://learn.microsoft.com/dotnet/core/diagnostics/distributed-tracing) -- [Observability in .Net](https://learn.microsoft.com/dotnet/core/diagnostics/observability-with-otel) +- [Distributed tracing](/dotnet/core/diagnostics/distributed-tracing) +- [Observability in .Net](/dotnet/core/diagnostics/observability-with-otel) - [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) ## Observability in Semantic Kernel @@ -33,18 +33,18 @@ Specifically, Semantic Kernel provides the following observability features: - **Logging**: Semantic Kernel logs meaningful events and errors from the kernel, kernel plugins and functions, as well as the AI connectors. ![Logs and events](../../../media/telemetry-log-events-overview-app-insights.png) > [!IMPORTANT] - > [Traces in Application Insights](https://learn.microsoft.com/azure/azure-monitor/app/data-model-complete#trace) represent traditional log entries and [OpenTelemetry span events](https://opentelemetry.io/docs/concepts/signals/traces/#span-events). They are not the same as distributed traces. + > [Traces in Application Insights](/azure/azure-monitor/app/data-model-complete#trace) represent traditional log entries and [OpenTelemetry span events](https://opentelemetry.io/docs/concepts/signals/traces/#span-events). They are not the same as distributed traces. - **Metrics**: Semantic Kernel emits metrics from kernel functions and AI connectors. You will be able to monitor metrics such as the kernel function execution time, the token consumption of AI connectors, etc. ![Metrics](../../../media/telemetry-metrics-overview-app-insights.png) - **Tracing**: Semantic Kernel supports distributed tracing. You can track activities across different services and within Semantic Kernel. - ![Complete end-to-end transaction of a request](../../media/telemetry-trace-overview-app-insights.png) + ![Complete end-to-end transaction of a request](../../../media/telemetry-trace-overview-app-insights.png) ::: zone pivot="programming-language-csharp" | Telemetry | Description | |-----------|---------------------------------------| -| Log | Logs are recorded throughout the Kernel. For more information on Logging in .Net, please refer to this [document](https://learn.microsoft.com/dotnet/core/extensions/logging). Sensitive data, such as kernel function arguments and results, are logged at the trace level. Please refer to this [table](https://learn.microsoft.com/dotnet/core/extensions/logging?tabs=command-line#log-level) for more information on log levels. | +| Log | Logs are recorded throughout the Kernel. For more information on Logging in .Net, please refer to this [document](/dotnet/core/extensions/logging). Sensitive data, such as kernel function arguments and results, are logged at the trace level. Please refer to this [table](/dotnet/core/extensions/logging?tabs=command-line#log-level) for more information on log levels. | | Activity | Each kernel function execution and each call to an AI model are recorded as an activity. All activities are generated by an activity source named "Microsoft.SemanticKernel". | | Metric | Semantic Kernel captures the following metrics from kernel functions:
    • `semantic_kernel.function.invocation.duration` (Histogram) - function execution time (in seconds)
    • `semantic_kernel.function.streaming.duration` (Histogram) - function streaming execution time (in seconds)
    • `semantic_kernel.function.invocation.token_usage.prompt` (Histogram) - number of prompt token usage (only for `KernelFunctionFromPrompt`)
    • `semantic_kernel.function.invocation.token_usage.completion` (Histogram) - number of completion token usage (only for `KernelFunctionFromPrompt`)
      • | diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-advanced.md b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-advanced.md index bb604e6b..2efebe69 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-advanced.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-advanced.md @@ -12,7 +12,7 @@ ms.service: semantic-kernel # More advanced scenarios for telemetry > [!NOTE] -> This article will use [Aspire Dashboard](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/overview?tabs=bash) for illustration. If you prefer to use other tools, please refer to the documentation of the tool you are using on setup instructions. +> This article will use [Aspire Dashboard](/dotnet/aspire/fundamentals/dashboard/overview?tabs=bash) for illustration. If you prefer to use other tools, please refer to the documentation of the tool you are using on setup instructions. ## Auto Function Calling @@ -375,7 +375,7 @@ Please refer to this [article](./telemetry-with-console.md#environment-variables ### Start the Aspire Dashboard -Follow the instructions [here](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash#start-the-dashboard) to start the dashboard. Once the dashboard is running, open a browser and navigate to `http://localhost:18888` to access the dashboard. +Follow the instructions [here](/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash#start-the-dashboard) to start the dashboard. Once the dashboard is running, open a browser and navigate to `http://localhost:18888` to access the dashboard. ### Run diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard.md b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard.md index b83abbfb..6bd39dfe 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-aspire-dashboard.md @@ -11,9 +11,9 @@ ms.service: semantic-kernel # Inspection of telemetry data with Aspire Dashboard -[Aspire Dashboard](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/overview?tabs=bash) is part of the [.NET Aspire](https://learn.microsoft.com/dotnet/aspire/get-started/aspire-overview) offering. The dashboard allows developers to monitor and inspect their distributed applications. +[Aspire Dashboard](/dotnet/aspire/fundamentals/dashboard/overview?tabs=bash) is part of the [.NET Aspire](/dotnet/aspire/get-started/aspire-overview) offering. The dashboard allows developers to monitor and inspect their distributed applications. -In this example, we will use the [standalone mode](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash) and learn how to export telemetry data to Aspire Dashboard, and inspect the data there. +In this example, we will use the [standalone mode](/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash) and learn how to export telemetry data to Aspire Dashboard, and inspect the data there. ## Exporter @@ -330,7 +330,7 @@ Please refer to this [article](./telemetry-with-console.md#add-telemetry-1) for ## Start the Aspire Dashboard -Follow the instructions [here](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash#start-the-dashboard) to start the dashboard. Once the dashboard is running, open a browser and navigate to `http://localhost:18888` to access the dashboard. +Follow the instructions [here](/dotnet/aspire/fundamentals/dashboard/standalone?tabs=bash#start-the-dashboard) to start the dashboard. Once the dashboard is running, open a browser and navigate to `http://localhost:18888` to access the dashboard. ## Run @@ -366,7 +366,7 @@ python telemetry_aspire_dashboard_quickstart.py After running the application, head over to the dashboard to inspect the telemetry data. > [!TIP] -> Follow this [guide](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/explore) to explore the Aspire Dashboard interface. +> Follow this [guide](/dotnet/aspire/fundamentals/dashboard/explore) to explore the Aspire Dashboard interface. ### Traces @@ -383,7 +383,7 @@ In the trace details, you can see the span that represents the prompt function a ### Logs -Head over to the `Structured` tab to view the logs emitted by the application. Please refer to this [guide](https://learn.microsoft.com/dotnet/aspire/fundamentals/dashboard/explore#structured-logs-page) on how to work with structured logs in the dashboard. +Head over to the `Structured` tab to view the logs emitted by the application. Please refer to this [guide](/dotnet/aspire/fundamentals/dashboard/explore#structured-logs-page) on how to work with structured logs in the dashboard. ## Next steps diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md index 36153162..00ab843c 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-azure-ai-foundry-tracing.md @@ -10,7 +10,7 @@ ms.service: semantic-kernel # Visualize traces on Azure AI Foundry Tracing UI -[Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-studio/) Tracing UI is a web-based user interface that allows you to visualize traces and logs generated by your applications. This article provides a step-by-step guide on how to visualize traces on Azure AI Foundry Tracing UI. +[Azure AI Foundry](/azure/ai-studio/) Tracing UI is a web-based user interface that allows you to visualize traces and logs generated by your applications. This article provides a step-by-step guide on how to visualize traces on Azure AI Foundry Tracing UI. > [!IMPORTANT] > Before you start, make sure you have completed the tutorial on [inspecting telemetry data with Application Insights](./telemetry-with-app-insights.md). @@ -20,8 +20,8 @@ ms.service: semantic-kernel Prerequisites: -- An Azure AI Foundry project. Follow this [guide](https://learn.microsoft.com/en-us/azure/ai-studio/how-to/create-projects) to create one if you don't have one. -- A serverless inference API. Follow this [guide](https://learn.microsoft.com/en-us/azure/ai-studio/how-to/deploy-models-serverless) to create one if you don't have one. +- An Azure AI Foundry project. Follow this [guide](/azure/ai-studio/how-to/create-projects) to create one if you don't have one. +- A serverless inference API. Follow this [guide](/azure/ai-studio/how-to/deploy-models-serverless) to create one if you don't have one. - Alternatively, you can attach an Azure OpenAI resource to the project, in which case you don't need to create a serverless API. ## Attach an Application Insights resource to the project diff --git a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console.md b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console.md index 56354c16..f066c170 100644 --- a/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console.md +++ b/semantic-kernel/concepts/enterprise-readiness/observability/telemetry-with-console.md @@ -478,7 +478,7 @@ Value: 16 Here you can see the name, the description, the unit, the time range, the type, the value of the metric, and the meter that the metric belongs to. > [!NOTE] -> The above metric is a Counter metric. For a full list of metric types, see [here](https://learn.microsoft.com/dotnet/core/diagnostics/metrics-instrumentation#types-of-instruments). Depending on the type of metric, the output may vary. +> The above metric is a Counter metric. For a full list of metric types, see [here](/dotnet/core/diagnostics/metrics-instrumentation#types-of-instruments). Depending on the type of metric, the output may vary. ::: zone-end From 84cf4bd8d220c54412dd443b8d64d767641ca57e Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Tue, 18 Feb 2025 08:28:15 +0900 Subject: [PATCH 16/70] Add Python processes sample code. --- .../Frameworks/process/examples/example-human-in-loop.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/semantic-kernel/Frameworks/process/examples/example-human-in-loop.md b/semantic-kernel/Frameworks/process/examples/example-human-in-loop.md index b41da7a1..445f9d10 100644 --- a/semantic-kernel/Frameworks/process/examples/example-human-in-loop.md +++ b/semantic-kernel/Frameworks/process/examples/example-human-in-loop.md @@ -45,6 +45,7 @@ public class PublishDocumentationStep : KernelProcessStep ::: zone-end ::: zone pivot="programming-language-python" +> Support for Python Human-in-the-loop Process behavior is coming soon. ::: zone-end ::: zone pivot="programming-language-java" @@ -81,6 +82,7 @@ Now whenever the newly generated documentation is approved by the proofread agen ::: zone-end ::: zone pivot="programming-language-python" +> Support for Python Human-in-the-loop Process behavior is coming soon. ::: zone-end ::: zone pivot="programming-language-java" @@ -132,6 +134,7 @@ return process; ::: zone-end ::: zone pivot="programming-language-python" +> Support for Python Human-in-the-loop Process behavior is coming soon. ::: zone-end ::: zone pivot="programming-language-java" @@ -154,6 +157,7 @@ await process.StartAsync(kernel, new KernelProcessEvent { Id = "HumanApprovalRes ::: zone-end ::: zone pivot="programming-language-python" +> Support for Python Human-in-the-loop Process behavior is coming soon. ::: zone-end ::: zone pivot="programming-language-java" From 03244eded4c85a9d039ddd28722c2e91bbba2121 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Tue, 18 Feb 2025 09:44:59 +0100 Subject: [PATCH 17/70] fixed headings --- .../concepts/enterprise-readiness/filters.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index 286d3673..fe2a0f16 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -226,8 +226,6 @@ async def prompt_rendering_filter(context: PromptRenderContext, next): ::: zone-end ::: zone pivot="programming-language-java" -## Coming soon - More info coming soon. ::: zone-end @@ -303,8 +301,6 @@ async def auto_function_invocation_filter(context: AutoFunctionInvocationContext ::: zone-end ::: zone pivot="programming-language-java" -## Coming soon - More info coming soon. ::: zone-end @@ -370,8 +366,12 @@ IChatCompletionService chatCompletionService = kernel.GetRequiredService Date: Tue, 18 Feb 2025 09:50:02 +0100 Subject: [PATCH 18/70] removed heading --- semantic-kernel/concepts/enterprise-readiness/filters.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index fe2a0f16..249d1de4 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -156,8 +156,6 @@ async def streaming_exception_handling( ::: zone-end ::: zone pivot="programming-language-java" -## Coming soon - More info coming soon. ::: zone-end From fa77efcc9e27890efa17ba2a632ae29b17c06b89 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Tue, 18 Feb 2025 10:02:09 +0100 Subject: [PATCH 19/70] added notes on ordering --- .../concepts/enterprise-readiness/filters.md | 55 ++++++++++++++++++- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index 249d1de4..a47eba80 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -24,7 +24,7 @@ There are three types of filters: - **Function Invocation Filter** - this filter is executed each time a `KernelFunction` is invoked. It allows: - Access to information about the function being executed and its arguments - Handling of exceptions during function execution - - Overriding of the function result + - Overriding of the function result, either before (for instance for caching scenario's) or after execution (for instance for responsible AI scenarios) - Retrying of the function in case of failure (e.g., [switching to an alternative AI model](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/RetryWithFilters.cs)) - **Prompt Render Filter** - this filter is triggered before the prompt rendering operation, enabling: @@ -37,9 +37,17 @@ Each filter includes a `context` object that contains all relevant information a In a filter, calling the `next` delegate is essential to proceed to the next registered filter or the original operation (whether function invocation or prompt rendering). Without calling `next`, the operation will not be executed. +::: zone pivot="programming-language-csharp" + To use a filter, first define it, then add it to the `Kernel` object either through dependency injection or the appropriate `Kernel` property. When using dependency injection, the order of filters is not guaranteed, so with multiple filters, the execution order may be unpredictable. -For cases where filter order is important, it is recommended to add filters directly to the `Kernel` object using appropriate properties. This approach allows filters to be added, removed, or reordered at runtime. +::: zone-end +::: zone pivot="programming-language-python" + +To use a filter, you can either define a function with the required parameters and add it to the `Kernel` object using the `add_filter` method, or use the `@kernel.filter` decorator to define a filter function and add it to the `Kernel` object. + +::: zone-end + ## Function Invocation Filter @@ -366,6 +374,49 @@ ChatMessageContent result = await chatCompletionService.GetChatMessageContentAsy ::: zone-end +## Ordering + +::: zone pivot="programming-language-csharp" + +When using dependency injection, the order of filters is not guaranteed. If the order of filters is important, it is recommended to add filters directly to the `Kernel` object using appropriate properties. This approach allows filters to be added, removed, or reordered at runtime. + +::: zone-end +::: zone pivot="programming-language-python" + +Filters are executed according to the order in which they are added to the `Kernel` object, which is equivalent between using `add_filter` and the `@kernel.filter` decorator. The order of filters can be important and should be understood well. + +Consider the following example: + +```python +def func(): + print('function') + + +@kernel.filter(FilterTypes.FUNCTION_INVOCATION) +async def filter1(context: FunctionInvocationContext, next): + print('before filter 1') + await next(context) + print('after filter 1') + +@kernel.filter(FilterTypes.FUNCTION_INVOCATION) +async def filter2(context: FunctionInvocationContext, next): + print('before filter 2') + await next(context) + print('after filter 2') +``` + +When executed the function, the output will be: + +```python +before filter 1 +before filter 2 +function +after filter 2 +after filter 1 +``` + +::: zone-end + ## More examples ::: zone pivot="programming-language-csharp" From 26e2b72938515ab2960c34cabc5db7ee8bd321ba Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Tue, 18 Feb 2025 10:03:52 +0100 Subject: [PATCH 20/70] try inline zone --- semantic-kernel/concepts/enterprise-readiness/filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index a47eba80..3549d842 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -25,7 +25,7 @@ There are three types of filters: - Access to information about the function being executed and its arguments - Handling of exceptions during function execution - Overriding of the function result, either before (for instance for caching scenario's) or after execution (for instance for responsible AI scenarios) - - Retrying of the function in case of failure (e.g., [switching to an alternative AI model](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/RetryWithFilters.cs)) + - Retrying of the function in case of failure ::: zone pivot="programming-language-csharp (e.g., [switching to an alternative AI model](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/RetryWithFilters.cs)) ::: zone-end - **Prompt Render Filter** - this filter is triggered before the prompt rendering operation, enabling: - Viewing and modifying the prompt that will be sent to the AI (e.g., for RAG or [PII redaction](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/PIIDetection.cs)) From 436e9cc2eef73cc1b560384fd998d1a071df7b12 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Tue, 18 Feb 2025 10:04:58 +0100 Subject: [PATCH 21/70] fix bullet --- semantic-kernel/concepts/enterprise-readiness/filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index 3549d842..ff914220 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -92,7 +92,7 @@ kernel.FunctionInvocationFilters.Add(new LoggingFilter(logger)); ### Code examples * [Function invocation filter examples](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/FunctionInvocationFiltering.cs) -* + ::: zone-end ::: zone pivot="programming-language-python" From 9c91c5490867f753fa289eeaeee075059e833a2a Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Tue, 18 Feb 2025 10:06:28 +0100 Subject: [PATCH 22/70] single line zone --- .../concepts/enterprise-readiness/filters.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index ff914220..55f53937 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -25,7 +25,15 @@ There are three types of filters: - Access to information about the function being executed and its arguments - Handling of exceptions during function execution - Overriding of the function result, either before (for instance for caching scenario's) or after execution (for instance for responsible AI scenarios) - - Retrying of the function in case of failure ::: zone pivot="programming-language-csharp (e.g., [switching to an alternative AI model](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/RetryWithFilters.cs)) ::: zone-end +::: zone pivot="programming-language-csharp" + - Retrying of the function in case of failure (e.g., [switching to an alternative AI model](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/RetryWithFilters.cs)) +::: zone-end +::: zone pivot="programming-language-python" + - Retrying of the function in case of failure +::: zone-end +::: zone pivot="programming-language-java" + - Retrying of the function in case of failure +::: zone-end - **Prompt Render Filter** - this filter is triggered before the prompt rendering operation, enabling: - Viewing and modifying the prompt that will be sent to the AI (e.g., for RAG or [PII redaction](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/PIIDetection.cs)) From 9d59fc2788085f8582c3b7d49aa21ba88f3a92f5 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Tue, 18 Feb 2025 11:00:09 +0100 Subject: [PATCH 23/70] small text updates --- .../concepts/enterprise-readiness/filters.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index 55f53937..f7434e14 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -25,15 +25,7 @@ There are three types of filters: - Access to information about the function being executed and its arguments - Handling of exceptions during function execution - Overriding of the function result, either before (for instance for caching scenario's) or after execution (for instance for responsible AI scenarios) -::: zone pivot="programming-language-csharp" - Retrying of the function in case of failure (e.g., [switching to an alternative AI model](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/RetryWithFilters.cs)) -::: zone-end -::: zone pivot="programming-language-python" - - Retrying of the function in case of failure -::: zone-end -::: zone pivot="programming-language-java" - - Retrying of the function in case of failure -::: zone-end - **Prompt Render Filter** - this filter is triggered before the prompt rendering operation, enabling: - Viewing and modifying the prompt that will be sent to the AI (e.g., for RAG or [PII redaction](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/PIIDetection.cs)) @@ -140,9 +132,9 @@ async def logger_filter(context: FunctionInvocationContext, next: Callable[[Func ### Streaming invocation -Functions in Semantic Kernel can be invoked in two ways: streaming and non-streaming. In streaming mode, a function typically returns `AsyncGenerator`, while in non-streaming mode, it returns `FunctionResult`. This distinction affects how results can be overridden in the filter: in streaming mode, the new function result value must be of type `AsyncGenerator`, whereas in non-streaming mode, it can simply be of type `T`. +Functions in Semantic Kernel can be invoked in two ways: streaming and non-streaming. In streaming mode, a function typically returns a `AsyncGenerator[T]` object where `T` is a kind of streaming content type, while in non-streaming mode, it returns `FunctionResult`. This distinction affects how results can be overridden in the filter: in streaming mode, the new function result value must also be of type `AsyncGenerator[T]`. -So to build a simple logger filter for streaming, you would use something like this: +So to build a simple logger filter for a streaming function invocation, you would use something like this: ```python @kernel.filter(FilterTypes.FUNCTION_INVOCATION) @@ -391,7 +383,7 @@ When using dependency injection, the order of filters is not guaranteed. If the ::: zone-end ::: zone pivot="programming-language-python" -Filters are executed according to the order in which they are added to the `Kernel` object, which is equivalent between using `add_filter` and the `@kernel.filter` decorator. The order of filters can be important and should be understood well. +Filters are executed in the order they are added to the Kernel object -- whether through `add_filter` or the `@kernel.filter` decorator. Because execution order can affect behavior, it's important to manage filter order carefully. Consider the following example: @@ -413,7 +405,7 @@ async def filter2(context: FunctionInvocationContext, next): print('after filter 2') ``` -When executed the function, the output will be: +When executing the function, the output will be: ```python before filter 1 From 40430831c0d9193a5a6b49739c4a3a296c2ea7a8 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 19 Feb 2025 11:49:04 +0100 Subject: [PATCH 24/70] added new sample links --- .../concepts/enterprise-readiness/filters.md | 97 +++++++++++++------ 1 file changed, 65 insertions(+), 32 deletions(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index f7434e14..5f541620 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -20,7 +20,7 @@ A good example of filters is provided [here](https://devblogs.microsoft.com/sema ![Semantic Kernel Filters](../../media/WhatAreFilters.png) There are three types of filters: - +::: zone pivot="programming-language-csharp" - **Function Invocation Filter** - this filter is executed each time a `KernelFunction` is invoked. It allows: - Access to information about the function being executed and its arguments - Handling of exceptions during function execution @@ -30,6 +30,29 @@ There are three types of filters: - **Prompt Render Filter** - this filter is triggered before the prompt rendering operation, enabling: - Viewing and modifying the prompt that will be sent to the AI (e.g., for RAG or [PII redaction](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Filtering/PIIDetection.cs)) - Preventing prompt submission to the AI by overriding the function result (e.g., for [Semantic Caching](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/Concepts/Caching/SemanticCachingWithFilters.cs)) +::: zone-end +::: zone pivot="programming-language-python" +- **Function Invocation Filter** - this filter is executed each time a `KernelFunction` is invoked. It allows: + - Access to information about the function being executed and its arguments + - Handling of exceptions during function execution + - Overriding of the function result, either before (for instance for caching scenario's) or after execution (for instance for responsible AI scenarios) + - Retrying of the function in case of failure (e.g., [switching to an alternative AI model](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/retry_with_different_model.py)) + +- **Prompt Render Filter** - this filter is triggered before the prompt rendering operation, enabling: +- Viewing and modifying the prompt that will be sent to the AI +- Preventing prompt submission to the AI by overriding the function result (e.g., for [Semantic Caching](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/caching/semantic_caching.py)) +::: zone-end +::: zone pivot="programming-language-java" +- **Function Invocation Filter** - this filter is executed each time a `KernelFunction` is invoked. It allows: + - Access to information about the function being executed and its arguments + - Handling of exceptions during function execution + - Overriding of the function result, either before (for instance for caching scenario's) or after execution (for instance for responsible AI scenarios) + - Retrying of the function in case of failure + +- **Prompt Render Filter** - this filter is triggered before the prompt rendering operation, enabling: +- Viewing and modifying the prompt that will be sent to the AI +- Preventing prompt submission to the AI by overriding the function result +::: zone-end - **Auto Function Invocation Filter** - similar to the function invocation filter, this filter operates within the scope of `automatic function calling`, providing additional context, including chat history, a list of all functions to be executed, and iteration counters. It also allows termination of the auto function calling process (e.g., if a desired result is obtained from the second of three planned functions). @@ -129,37 +152,8 @@ async def logger_filter(context: FunctionInvocationContext, next: Callable[[Func logger.info(f"FunctionInvoked - {context.function.plugin_name}.{context.function.name}") ``` - -### Streaming invocation - -Functions in Semantic Kernel can be invoked in two ways: streaming and non-streaming. In streaming mode, a function typically returns a `AsyncGenerator[T]` object where `T` is a kind of streaming content type, while in non-streaming mode, it returns `FunctionResult`. This distinction affects how results can be overridden in the filter: in streaming mode, the new function result value must also be of type `AsyncGenerator[T]`. - -So to build a simple logger filter for a streaming function invocation, you would use something like this: - -```python -@kernel.filter(FilterTypes.FUNCTION_INVOCATION) -async def streaming_exception_handling( - context: FunctionInvocationContext, - next: Callable[[FunctionInvocationContext], Coroutine[Any, Any, None]], -): - await next(context) - - async def override_stream(stream): - try: - async for partial in stream: - yield partial - except Exception as e: - yield [ - StreamingChatMessageContent(role=AuthorRole.ASSISTANT, content=f"Exception caught: {e}", choice_index=0) - ] - - stream = context.result.value - context.result = FunctionResult(function=context.result.function, value=override_stream(stream)) -``` - ### Code examples * [Function invocation filter examples](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/function_invocation_filters.py) -* [Streaming function invocation filter examples](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/function_invocation_filters_stream.py) ::: zone-end ::: zone pivot="programming-language-java" @@ -310,9 +304,8 @@ async def auto_function_invocation_filter(context: AutoFunctionInvocationContext More info coming soon. ::: zone-end -::: zone pivot="programming-language-csharp" - ## Streaming and non-streaming invocation +::: zone pivot="programming-language-csharp" Functions in Semantic Kernel can be invoked in two ways: streaming and non-streaming. In streaming mode, a function typically returns `IAsyncEnumerable`, while in non-streaming mode, it returns `FunctionResult`. This distinction affects how results can be overridden in the filter: in streaming mode, the new function result value must be of type `IAsyncEnumerable`, whereas in non-streaming mode, it can simply be of type `T`. To determine which result type needs to be returned, the `context.IsStreaming` flag is available in the filter context model. @@ -372,6 +365,44 @@ IChatCompletionService chatCompletionService = kernel.GetRequiredService Date: Wed, 19 Feb 2025 11:50:38 +0100 Subject: [PATCH 25/70] fix indentation --- semantic-kernel/concepts/enterprise-readiness/filters.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index 5f541620..15b7e90b 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -39,8 +39,8 @@ There are three types of filters: - Retrying of the function in case of failure (e.g., [switching to an alternative AI model](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/retry_with_different_model.py)) - **Prompt Render Filter** - this filter is triggered before the prompt rendering operation, enabling: -- Viewing and modifying the prompt that will be sent to the AI -- Preventing prompt submission to the AI by overriding the function result (e.g., for [Semantic Caching](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/caching/semantic_caching.py)) + - Viewing and modifying the prompt that will be sent to the AI + - Preventing prompt submission to the AI by overriding the function result (e.g., for [Semantic Caching](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/caching/semantic_caching.py)) ::: zone-end ::: zone pivot="programming-language-java" - **Function Invocation Filter** - this filter is executed each time a `KernelFunction` is invoked. It allows: @@ -50,8 +50,8 @@ There are three types of filters: - Retrying of the function in case of failure - **Prompt Render Filter** - this filter is triggered before the prompt rendering operation, enabling: -- Viewing and modifying the prompt that will be sent to the AI -- Preventing prompt submission to the AI by overriding the function result + - Viewing and modifying the prompt that will be sent to the AI + - Preventing prompt submission to the AI by overriding the function result ::: zone-end - **Auto Function Invocation Filter** - similar to the function invocation filter, this filter operates within the scope of `automatic function calling`, providing additional context, including chat history, a list of all functions to be executed, and iteration counters. It also allows termination of the auto function calling process (e.g., if a desired result is obtained from the second of three planned functions). From 7d9f07a4106203f81f7fba21100bbc4b11246309 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 19 Feb 2025 11:56:36 +0100 Subject: [PATCH 26/70] polish --- semantic-kernel/concepts/enterprise-readiness/filters.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/semantic-kernel/concepts/enterprise-readiness/filters.md b/semantic-kernel/concepts/enterprise-readiness/filters.md index 15b7e90b..ae38f166 100644 --- a/semantic-kernel/concepts/enterprise-readiness/filters.md +++ b/semantic-kernel/concepts/enterprise-readiness/filters.md @@ -376,7 +376,7 @@ So to build a simple logger filter for a streaming function invocation, you woul @kernel.filter(FilterTypes.FUNCTION_INVOCATION) async def streaming_exception_handling( context: FunctionInvocationContext, - next: Callable[[FunctionInvocationContext], Coroutine[Any, Any, None]], + next: Callable[[FunctionInvocationContext], Awaitable[None]], ): await next(context) if not context.is_streaming: @@ -395,7 +395,7 @@ async def streaming_exception_handling( context.result = FunctionResult(function=context.result.function, value=override_stream(stream)) ``` -Code example: +### Code examples * [Streaming function invocation filter examples](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/filtering/function_invocation_filters_stream.py) ::: zone-end From f0d5d11f745b14d0364f45bd55bcf7a70cfe64af Mon Sep 17 00:00:00 2001 From: Ben Thomas Date: Tue, 25 Feb 2025 08:01:41 -0800 Subject: [PATCH 27/70] Update semantic-kernel/Frameworks/process/examples/example-cycles.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- semantic-kernel/Frameworks/process/examples/example-cycles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/semantic-kernel/Frameworks/process/examples/example-cycles.md b/semantic-kernel/Frameworks/process/examples/example-cycles.md index d46a2424..f9440026 100644 --- a/semantic-kernel/Frameworks/process/examples/example-cycles.md +++ b/semantic-kernel/Frameworks/process/examples/example-cycles.md @@ -108,10 +108,10 @@ class ProofreadStep(KernelProcessStep): print(f"{ProofreadStep.__name__}\n\t Proofreading product documentation...") system_prompt = """ - Your job is to proofread customer facing documentation for a new product from Contoso. You will be provide with + Your job is to proofread customer facing documentation for a new product from Contoso. You will be provided with proposed documentation for a product and you must do the following things: - 1. Determine if the documentation is passes the following criteria: + 1. Determine if the documentation passes the following criteria: 1. Documentation must use a professional tone. 1. Documentation should be free of spelling or grammar mistakes. 1. Documentation should be free of any offensive or inappropriate language. From b754b73e7fb613770e601a26059a3753e874a8cc Mon Sep 17 00:00:00 2001 From: Sophia Lagerkrans-Pandey <163188263+sophialagerkranspandey@users.noreply.github.com> Date: Tue, 25 Feb 2025 09:16:04 -0800 Subject: [PATCH 28/70] Update semantic-kernel/Frameworks/process/examples/example-cycles.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- semantic-kernel/Frameworks/process/examples/example-cycles.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/semantic-kernel/Frameworks/process/examples/example-cycles.md b/semantic-kernel/Frameworks/process/examples/example-cycles.md index f9440026..f7e4dba9 100644 --- a/semantic-kernel/Frameworks/process/examples/example-cycles.md +++ b/semantic-kernel/Frameworks/process/examples/example-cycles.md @@ -98,8 +98,7 @@ class ProofreadingResponse(BaseModel): meets_expectations: bool = Field(description="Specifies if the proposed docs meets the standards for publishing.") explanation: str = Field(description="An explanation of why the documentation does or does not meet expectations.") - suggestions: list[str] = Field(description="List of suggestions, empty if there no suggestions for improvement.") - + suggestions: list[str] = Field(description="List of suggestions, empty if there are no suggestions for improvement.") # A process step to proofread documentation class ProofreadStep(KernelProcessStep): From 1db60e286b126a2f070144932e72638c827f63ed Mon Sep 17 00:00:00 2001 From: Sophia Lagerkrans-Pandey <163188263+sophialagerkranspandey@users.noreply.github.com> Date: Tue, 25 Feb 2025 09:16:11 -0800 Subject: [PATCH 29/70] Update semantic-kernel/Frameworks/process/examples/example-first-process.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../Frameworks/process/examples/example-first-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/Frameworks/process/examples/example-first-process.md b/semantic-kernel/Frameworks/process/examples/example-first-process.md index 447fa929..88d30f2f 100644 --- a/semantic-kernel/Frameworks/process/examples/example-first-process.md +++ b/semantic-kernel/Frameworks/process/examples/example-first-process.md @@ -208,7 +208,7 @@ class GenerateDocumentationStep(KernelProcessStep[GeneratedDocumentationState]): system_prompt: ClassVar[str] = """ Your job is to write high quality and engaging customer facing documentation for a new product from Contoso. You will -be provide with information about the product in the form of internal documentation, specs, and troubleshooting guides +be provided with information about the product in the form of internal documentation, specs, and troubleshooting guides and you must use this information and nothing else to generate the documentation. If suggestions are provided on the documentation you create, take the suggestions into account and rewrite the documentation. Make sure the product sounds amazing. From 50864c0c7cf5838ea62acda5be19b86ec967d405 Mon Sep 17 00:00:00 2001 From: Sophia Lagerkrans-Pandey <163188263+sophialagerkranspandey@users.noreply.github.com> Date: Tue, 25 Feb 2025 09:16:22 -0800 Subject: [PATCH 30/70] Update semantic-kernel/Frameworks/process/examples/example-cycles.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- semantic-kernel/Frameworks/process/examples/example-cycles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/Frameworks/process/examples/example-cycles.md b/semantic-kernel/Frameworks/process/examples/example-cycles.md index f7e4dba9..78248e01 100644 --- a/semantic-kernel/Frameworks/process/examples/example-cycles.md +++ b/semantic-kernel/Frameworks/process/examples/example-cycles.md @@ -228,7 +228,7 @@ class GenerateDocumentationStep(KernelProcessStep[GeneratedDocumentationState]): system_prompt: ClassVar[str] = """ Your job is to write high quality and engaging customer facing documentation for a new product from Contoso. You will -be provide with information about the product in the form of internal documentation, specs, and troubleshooting guides +be provided with information about the product in the form of internal documentation, specs, and troubleshooting guides and you must use this information and nothing else to generate the documentation. If suggestions are provided on the documentation you create, take the suggestions into account and rewrite the documentation. Make sure the product sounds amazing. From a97ebdbdb77b0e58b45374adfd2c3397f52e956b Mon Sep 17 00:00:00 2001 From: Eric Urban Date: Wed, 26 Feb 2025 02:27:05 -0800 Subject: [PATCH 31/70] OpenAI not Open AI (#468) --- semantic-kernel/Frameworks/agent/TOC.yml | 2 +- .../Frameworks/agent/agent-architecture.md | 6 ++--- .../Frameworks/agent/agent-chat.md | 6 ++--- .../Frameworks/agent/agent-functions.md | 4 +-- .../Frameworks/agent/agent-streaming.md | 12 ++++----- .../Frameworks/agent/agent-templates.md | 4 +-- .../Frameworks/agent/assistant-agent.md | 26 +++++++++---------- .../Frameworks/agent/chat-completion-agent.md | 4 +-- .../examples/example-agent-collaboration.md | 6 ++--- .../agent/examples/example-assistant-code.md | 18 ++++++------- .../examples/example-assistant-search.md | 16 ++++++------ .../agent/examples/example-chat-agent.md | 8 +++--- semantic-kernel/Frameworks/agent/index.md | 4 +-- .../ai-services/embedding-generation/index.md | 6 ++--- .../embedding-generation.md | 4 +-- .../how-to/vector-store-data-ingestion.md | 2 +- 16 files changed, 64 insertions(+), 64 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/TOC.yml b/semantic-kernel/Frameworks/agent/TOC.yml index 8c88375f..c85787ea 100644 --- a/semantic-kernel/Frameworks/agent/TOC.yml +++ b/semantic-kernel/Frameworks/agent/TOC.yml @@ -4,7 +4,7 @@ href: agent-architecture.md - name: Chat Completion Agent href: chat-completion-agent.md -- name: Open AI Assistant Agent +- name: OpenAI Assistant Agent href: assistant-agent.md - name: Agent Collaboration href: agent-chat.md diff --git a/semantic-kernel/Frameworks/agent/agent-architecture.md b/semantic-kernel/Frameworks/agent/agent-architecture.md index e44f73d5..c3966fa8 100644 --- a/semantic-kernel/Frameworks/agent/agent-architecture.md +++ b/semantic-kernel/Frameworks/agent/agent-architecture.md @@ -28,7 +28,7 @@ The _Agent Framework_ was developed with the following key priorities in mind: ## Agent -The abstract _Agent_ class serves as the core abstraction for all types of agents, providing a foundational structure that can be extended to create more specialized agents. One key subclass is _Kernel Agent_, which establishes a direct association with a [_Kernel_](../../concepts/kernel.md) object. This relationship forms the basis for more specific agent implementations, such as the [_Chat Completion Agent_](./chat-completion-agent.md) and the [_Open AI Assistant Agent_](./assistant-agent.md), both of which leverage the Kernel's capabilities to execute their respective functions. +The abstract _Agent_ class serves as the core abstraction for all types of agents, providing a foundational structure that can be extended to create more specialized agents. One key subclass is _Kernel Agent_, which establishes a direct association with a [_Kernel_](../../concepts/kernel.md) object. This relationship forms the basis for more specific agent implementations, such as the [_Chat Completion Agent_](./chat-completion-agent.md) and the [_OpenAI Assistant Agent_](./assistant-agent.md), both of which leverage the Kernel's capabilities to execute their respective functions. ::: zone pivot="programming-language-csharp" @@ -103,7 +103,7 @@ The _Agent Framework_ is built on the foundational concepts and features that ma At the heart of the _Semantic Kernel_ ecosystem is the [_Kernel_](../../concepts/kernel.md), which serves as the core object that drives AI operations and interactions. To create any agent within this framework, a _Kernel instance_ is required as it provides the foundational context and capabilities for the agent’s functionality. The _Kernel_ acts as the engine for processing instructions, managing state, and invoking the necessary AI services that power the agent's behavior. -The [_Chat Completion Agent_](./chat-completion-agent.md) and [_Open AI Assistant Agent_](./assistant-agent.md) articles provide specific details on how to create each type of agent. +The [_Chat Completion Agent_](./chat-completion-agent.md) and [_OpenAI Assistant Agent_](./assistant-agent.md) articles provide specific details on how to create each type of agent. These resources offer step-by-step instructions and highlight the key configurations needed to tailor the agents to different conversational or task-based applications, demonstrating how the Kernel enables dynamic and intelligent agent behaviors across diverse use cases. #### Related API's: @@ -169,7 +169,7 @@ Plugins are a fundamental aspect of the _Semantic Kernel_, enabling developers t Agent messaging, including both input and response, is built upon the core content types of the _Semantic Kernel_, providing a unified structure for communication. This design choice simplifies the process of transitioning from traditional chat-completion patterns to more advanced agent-driven patterns in your application development. By leveraging familiar _Semantic Kernel_ content types, developers can seamlessly integrate agent capabilities into their applications without needing to overhaul existing systems. This streamlining ensures that as you evolve from basic conversational AI to more autonomous, task-oriented agents, the underlying framework remains consistent, making development faster and more efficient. -> Note: The [_Open AI Assistant Agent_`_](./assistant-agent.md) introduced content types specific to its usage for _File References_ and _Content Annotation_: +> Note: The [_OpenAI Assistant Agent_`_](./assistant-agent.md) introduced content types specific to its usage for _File References_ and _Content Annotation_: #### Related API's: diff --git a/semantic-kernel/Frameworks/agent/agent-chat.md b/semantic-kernel/Frameworks/agent/agent-chat.md index 90771da6..bf59e765 100644 --- a/semantic-kernel/Frameworks/agent/agent-chat.md +++ b/semantic-kernel/Frameworks/agent/agent-chat.md @@ -38,7 +38,7 @@ Detailed API documentation related to this discussion is available at: ## What is _Agent Chat_? -_Agent Chat_ provides a framework that enables interaction between multiple agents, even if they are of different types. This makes it possible for a [_Chat Completion Agent_](./chat-completion-agent.md) and an [_Open AI Assistant Agent_](./assistant-agent.md) to work together within the same conversation. _Agent Chat_ also defines entry points for initiating collaboration between agents, whether through multiple responses or a single agent response. +_Agent Chat_ provides a framework that enables interaction between multiple agents, even if they are of different types. This makes it possible for a [_Chat Completion Agent_](./chat-completion-agent.md) and an [_OpenAI Assistant Agent_](./assistant-agent.md) to work together within the same conversation. _Agent Chat_ also defines entry points for initiating collaboration between agents, whether through multiple responses or a single agent response. As an abstract class, _Agent Chat_ can be subclassed to support custom scenarios. @@ -280,7 +280,7 @@ history = await chat.get_chat_messages() ::: zone-end -Since different agent types or configurations may maintain their own version of the conversation history, agent specific history is also available by specifing an agent. (For example: [_Open AI Assistant_](./assistant-agent.md) versus [_Chat Completion Agent_](./chat-completion-agent.md).) +Since different agent types or configurations may maintain their own version of the conversation history, agent specific history is also available by specifing an agent. (For example: [_OpenAI Assistant_](./assistant-agent.md) versus [_Chat Completion Agent_](./chat-completion-agent.md).) ::: zone pivot="programming-language-csharp" ```csharp @@ -636,7 +636,7 @@ if chat.is_complete: ### Clear Full Conversation State -When done using an _Agent Chat_ where an [_Open AI Assistant_](./assistant-agent.md) participated, it may be necessary to delete the remote _thread_ associated with the _assistant_. _Agent Chat_ supports resetting or clearing the entire conversation state, which includes deleting any remote _thread_ definition. This ensures that no residual conversation data remains linked to the assistant once the chat concludes. +When done using an _Agent Chat_ where an [_OpenAI Assistant_](./assistant-agent.md) participated, it may be necessary to delete the remote _thread_ associated with the _assistant_. _Agent Chat_ supports resetting or clearing the entire conversation state, which includes deleting any remote _thread_ definition. This ensures that no residual conversation data remains linked to the assistant once the chat concludes. A full reset does not remove the _agents_ that had joined the _Agent Chat_ and leaves the _Agent Chat_ in a state where it can be reused. This allows for the continuation of interactions with the same agents without needing to reinitialize them, making future conversations more efficient. diff --git a/semantic-kernel/Frameworks/agent/agent-functions.md b/semantic-kernel/Frameworks/agent/agent-functions.md index a367e793..3ada7e4f 100644 --- a/semantic-kernel/Frameworks/agent/agent-functions.md +++ b/semantic-kernel/Frameworks/agent/agent-functions.md @@ -50,7 +50,7 @@ Any [Plugin](../../concepts/plugins/index.md) available to an _Agent_ is managed [Plugins](../../concepts/plugins/index.md) can be added to the _Kernel_ either before or after the _Agent_ is created. The process of initializing [Plugins](../../concepts/plugins/index.md) follows the same patterns used for any _Semantic Kernel_ implementation, allowing for consistency and ease of use in managing AI capabilities. -> Note: For a [_Chat Completion Agent_](./chat-completion-agent.md), the function calling mode must be explicitly enabled. [_Open AI Assistant_](./assistant-agent.md) agent is always based on automatic function calling. +> Note: For a [_Chat Completion Agent_](./chat-completion-agent.md), the function calling mode must be explicitly enabled. [_OpenAI Assistant_](./assistant-agent.md) agent is always based on automatic function calling. ::: zone pivot="programming-language-csharp" ```csharp @@ -198,7 +198,7 @@ agent = ChatCompletionAgent( ## Limitations for Agent Function Calling -When directly invoking a[_Chat Completion Agent_](./chat-completion-agent.md), all _Function Choice Behaviors_ are supported. However, when using an [_Open AI Assistant_](./assistant-agent.md) or [_Agent Chat_](./agent-chat.md), only _Automatic_ [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is currently available. +When directly invoking a[_Chat Completion Agent_](./chat-completion-agent.md), all _Function Choice Behaviors_ are supported. However, when using an [_OpenAI Assistant_](./assistant-agent.md) or [_Agent Chat_](./agent-chat.md), only _Automatic_ [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is currently available. ## How-To diff --git a/semantic-kernel/Frameworks/agent/agent-streaming.md b/semantic-kernel/Frameworks/agent/agent-streaming.md index befc0004..eac08b71 100644 --- a/semantic-kernel/Frameworks/agent/agent-streaming.md +++ b/semantic-kernel/Frameworks/agent/agent-streaming.md @@ -19,9 +19,9 @@ A streamed response delivers the message content in small, incremental chunks. T #### Streaming References: -- [Open AI Streaming Guide](https://platform.openai.com/docs/api-reference/streaming) -- [Open AI Chat Completion Streaming](https://platform.openai.com/docs/api-reference/chat/create#chat-create-stream) -- [Open AI Assistant Streaming](https://platform.openai.com/docs/api-reference/assistants-streaming) +- [OpenAI Streaming Guide](https://platform.openai.com/docs/api-reference/streaming) +- [OpenAI Chat Completion Streaming](https://platform.openai.com/docs/api-reference/chat/create#chat-create-stream) +- [OpenAI Assistant Streaming](https://platform.openai.com/docs/api-reference/assistants-streaming) - [Azure OpenAI Service REST API](/azure/ai-services/openai/reference) @@ -54,7 +54,7 @@ A streamed response delivers the message content in small, incremental chunks. T ## Streaming Agent Invocation -The _Agent Framework_ supports _streamed_ responses when using [_Agent Chat_](./agent-chat.md) or when directly invoking a [_Chat Completion Agent_](./chat-completion-agent.md) or [_Open AI Assistant Agent_](./assistant-agent.md). In either mode, the framework delivers responses asynchronously as they are streamed. Alongside the streamed response, a consistent, non-streamed history is maintained to track the conversation. This ensures both real-time interaction and a reliable record of the conversation's flow. +The _Agent Framework_ supports _streamed_ responses when using [_Agent Chat_](./agent-chat.md) or when directly invoking a [_Chat Completion Agent_](./chat-completion-agent.md) or [_OpenAI Assistant Agent_](./assistant-agent.md). In either mode, the framework delivers responses asynchronously as they are streamed. Alongside the streamed response, a consistent, non-streamed history is maintained to track the conversation. This ensures both real-time interaction and a reliable record of the conversation's flow. ### Streamed response from _Chat Completion Agent_ @@ -104,9 +104,9 @@ async for response in agent.invoke_stream(chat) ::: zone-end -### Streamed response from _Open AI Assistant Agent_ +### Streamed response from _OpenAI Assistant Agent_ -When invoking a streamed response from an [_Open AI Assistant Agent_](./assistant-agent.md), an optional _Chat History_ can be provided to capture the complete messages for further analysis if needed. Since the assistant maintains the conversation state as a remote thread, capturing these messages is not always necessary. The decision to store and analyze the full response depends on the specific requirements of the interaction. +When invoking a streamed response from an [_OpenAI Assistant Agent_](./assistant-agent.md), an optional _Chat History_ can be provided to capture the complete messages for further analysis if needed. Since the assistant maintains the conversation state as a remote thread, capturing these messages is not always necessary. The decision to store and analyze the full response depends on the specific requirements of the interaction. ::: zone pivot="programming-language-csharp" ```csharp diff --git a/semantic-kernel/Frameworks/agent/agent-templates.md b/semantic-kernel/Frameworks/agent/agent-templates.md index 36d0ad38..e972ea8a 100644 --- a/semantic-kernel/Frameworks/agent/agent-templates.md +++ b/semantic-kernel/Frameworks/agent/agent-templates.md @@ -93,9 +93,9 @@ agent = ChatCompletionAgent( ::: zone-end -#### Open AI Assistant Agent +#### OpenAI Assistant Agent -Templated instructions are especially powerful when working with an [_Open AI Assistant Agent_](./assistant-agent.md). With this approach, a single assistant definition can be created and reused multiple times, each time with different parameter values tailored to specific tasks or contexts. This enables a more efficient setup, allowing the same assistant framework to handle a wide range of scenarios while maintaining consistency in its core behavior. +Templated instructions are especially powerful when working with an [_OpenAI Assistant Agent_](./assistant-agent.md). With this approach, a single assistant definition can be created and reused multiple times, each time with different parameter values tailored to specific tasks or contexts. This enables a more efficient setup, allowing the same assistant framework to handle a wide range of scenarios while maintaining consistency in its core behavior. ::: zone pivot="programming-language-csharp" ```csharp diff --git a/semantic-kernel/Frameworks/agent/assistant-agent.md b/semantic-kernel/Frameworks/agent/assistant-agent.md index bd63e69e..e4d36c81 100644 --- a/semantic-kernel/Frameworks/agent/assistant-agent.md +++ b/semantic-kernel/Frameworks/agent/assistant-agent.md @@ -1,5 +1,5 @@ --- -title: Exploring the Semantic Kernel Open AI Assistant Agent (Experimental) +title: Exploring the Semantic Kernel OpenAI Assistant Agent (Experimental) description: An exploration of the definition, behaviors, and usage patterns for a `OpenAIAssistantAgent` zone_pivot_groups: programming-languages author: crickman @@ -8,7 +8,7 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# Exploring the _Semantic Kernel_ _Open AI Assistant Agent_ +# Exploring the _Semantic Kernel_ _OpenAI Assistant Agent_ > [!WARNING] > The *Semantic Kernel Agent Framework* is in preview and is subject to change. @@ -41,14 +41,14 @@ Detailed API documentation related to this discussion is available at: The _OpenAI Assistant API_ is a specialized interface designed for more advanced and interactive AI capabilities, enabling developers to create personalized and multi-step task-oriented agents. Unlike the Chat Completion API, which focuses on simple conversational exchanges, the Assistant API allows for dynamic, goal-driven interactions with additional features like code-interpreter and file-search. -- [Open AI Assistant Guide](https://platform.openai.com/docs/assistants) -- [Open AI Assistant API](https://platform.openai.com/docs/api-reference/assistants) +- [OpenAI Assistant Guide](https://platform.openai.com/docs/assistants) +- [OpenAI Assistant API](https://platform.openai.com/docs/api-reference/assistants) - [Assistant API in Azure](/azure/ai-services/openai/assistants-quickstart) -## Creating an _Open AI Assistant Agent_ +## Creating an _OpenAI Assistant Agent_ -Creating an _Open AI Assistant_ requires invoking a remote service, which is handled asynchronously. To manage this, the _Open AI Assistant Agent_ is instantiated through a static factory method, ensuring the process occurs in a non-blocking manner. This method abstracts the complexity of the asynchronous call, returning a promise or future once the assistant is fully initialized and ready for use. +Creating an _OpenAI Assistant_ requires invoking a remote service, which is handled asynchronously. To manage this, the _OpenAI Assistant Agent_ is instantiated through a static factory method, ensuring the process occurs in a non-blocking manner. This method abstracts the complexity of the asynchronous call, returning a promise or future once the assistant is fully initialized and ready for use. ::: zone pivot="programming-language-csharp" ```csharp @@ -91,9 +91,9 @@ openai_agent = await OpenAIAssistantAgent.create( ::: zone-end -## Retrieving an _Open AI Assistant Agent_ +## Retrieving an _OpenAI Assistant Agent_ -Once created, the identifier of the assistant may be access via its identifier. This identifier may be used to create an _Open AI Assistant Agent_ from an existing assistant definition. +Once created, the identifier of the assistant may be access via its identifier. This identifier may be used to create an _OpenAI Assistant Agent_ from an existing assistant definition. ::: zone pivot="programming-language-csharp" @@ -125,7 +125,7 @@ agent = await AzureAssistantAgent.retrieve(id=agent_id, kernel=kernel) ::: zone-end -## Using an _Open AI Assistant Agent_ +## Using an _OpenAI Assistant Agent_ As with all aspects of the _Assistant API_, conversations are stored remotely. Each conversation is referred to as a _thread_ and identified by a unique `string` identifier. Interactions with your _OpenAI Assistant Agent_ are tied to this specific thread identifier which must be specified when calling the agent/ @@ -181,7 +181,7 @@ await agent.delete_thread(thread_id) ::: zone-end -## Deleting an _Open AI Assistant Agent_ +## Deleting an _OpenAI Assistant Agent_ Since the assistant's definition is stored remotely, it supports the capability to self-delete. This enables the agent to be removed from the system when it is no longer needed. @@ -217,10 +217,10 @@ is_deleted = agent._is_deleted ## How-To -For an end-to-end example for a _Open AI Assistant Agent_, see: +For an end-to-end example for a _OpenAI Assistant Agent_, see: -- [How-To: _Open AI Assistant Agent_ Code Interpreter](./examples/example-assistant-code.md) -- [How-To: _Open AI Assistant Agent_ File Search](./examples/example-assistant-search.md) +- [How-To: _OpenAI Assistant Agent_ Code Interpreter](./examples/example-assistant-code.md) +- [How-To: _OpenAI Assistant Agent_ File Search](./examples/example-assistant-search.md) > [!div class="nextstepaction"] diff --git a/semantic-kernel/Frameworks/agent/chat-completion-agent.md b/semantic-kernel/Frameworks/agent/chat-completion-agent.md index 6c1c115a..b3e7a40d 100644 --- a/semantic-kernel/Frameworks/agent/chat-completion-agent.md +++ b/semantic-kernel/Frameworks/agent/chat-completion-agent.md @@ -51,7 +51,7 @@ For .NET, some of AI services that support models with chat-completion include: Model|_Semantic Kernel_ AI Service --|-- -Azure Open AI|[`Microsoft.SemanticKernel.Connectors.AzureOpenAI`](/dotnet/api/microsoft.semantickernel.connectors.azureopenai) +Azure OpenAI|[`Microsoft.SemanticKernel.Connectors.AzureOpenAI`](/dotnet/api/microsoft.semantickernel.connectors.azureopenai) Gemini|[`Microsoft.SemanticKernel.Connectors.Google`](/dotnet/api/microsoft.semantickernel.connectors.google) HuggingFace|[`Microsoft.SemanticKernel.Connectors.HuggingFace`](/dotnet/api/microsoft.semantickernel.connectors.huggingface) Mistral|[`Microsoft.SemanticKernel.Connectors.MistralAI`](/dotnet/api/microsoft.semantickernel.connectors.mistralai) @@ -234,4 +234,4 @@ For an end-to-end example for a _Chat Completion Agent_, see: > [!div class="nextstepaction"] -> [Exploring _Open AI Assistant Agent_](./assistant-agent.md) +> [Exploring _OpenAI Assistant Agent_](./assistant-agent.md) diff --git a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md index 87fe4167..fc11bf27 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md +++ b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md @@ -111,16 +111,16 @@ from semantic_kernel.kernel import Kernel ## Configuration -This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _Open AI_ or _Azure Open AI_. +This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_. ::: zone pivot="programming-language-csharp" ```powershell -# Open AI +# OpenAI dotnet user-secrets set "OpenAISettings:ApiKey" "" dotnet user-secrets set "OpenAISettings:ChatModel" "gpt-4o" -# Azure Open AI +# Azure OpenAI dotnet user-secrets set "AzureOpenAISettings:ApiKey" "" # Not required if using token-credential dotnet user-secrets set "AzureOpenAISettings:Endpoint" "" dotnet user-secrets set "AzureOpenAISettings:ChatModelDeployment" "gpt-4o" diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index c9b79287..f8fab56a 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -1,6 +1,6 @@ --- -title: How-To: _Open AI Assistant Agent_ Code Interpreter (Experimental) -description: A step-by-step walk-through of defining and utilizing the code-interpreter tool of an Open AI Assistant Agent. +title: How-To: _OpenAI Assistant Agent_ Code Interpreter (Experimental) +description: A step-by-step walk-through of defining and utilizing the code-interpreter tool of an OpenAI Assistant Agent. zone_pivot_groups: programming-languages author: crickman ms.topic: tutorial @@ -8,14 +8,14 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# How-To: _Open AI Assistant Agent_ Code Interpreter +# How-To: _OpenAI Assistant Agent_ Code Interpreter > [!WARNING] > The *Semantic Kernel Agent Framework* is in preview and is subject to change. ## Overview -In this sample, we will explore how to use the _code-interpreter_ tool of an [_Open AI Assistant Agent_](../assistant-agent.md) to complete data-analysis tasks. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will generate both image and text responses. This will demonstrate the versatility of this tool in performing quantitative analysis. +In this sample, we will explore how to use the _code-interpreter_ tool of an [_OpenAI Assistant Agent_](../assistant-agent.md) to complete data-analysis tasks. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will generate both image and text responses. This will demonstrate the versatility of this tool in performing quantitative analysis. Streaming will be used to deliver the agent's responses. This will provide real-time updates as the task progresses. @@ -104,16 +104,16 @@ Additionally, copy the `PopulationByAdmin1.csv` and `PopulationByCountry.csv` da ## Configuration -This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _Open AI_ or _Azure Open AI_. +This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_. ::: zone pivot="programming-language-csharp" ```powershell -# Open AI +# OpenAI dotnet user-secrets set "OpenAISettings:ApiKey" "" dotnet user-secrets set "OpenAISettings:ChatModel" "gpt-4o" -# Azure Open AI +# Azure OpenAI dotnet user-secrets set "AzureOpenAISettings:ApiKey" "" # Not required if using token-credential dotnet user-secrets set "AzureOpenAISettings:Endpoint" "" dotnet user-secrets set "AzureOpenAISettings:ChatModelDeployment" "gpt-4o" @@ -205,7 +205,7 @@ The full example code is provided in the [Final](#final) section. Refer to that ### Setup -Prior to creating an _Open AI Assistant Agent_, ensure the configuration settings are available and prepare the file resources. +Prior to creating an _OpenAI Assistant Agent_, ensure the configuration settings are available and prepare the file resources. ::: zone pivot="programming-language-csharp" @@ -885,5 +885,5 @@ You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/m > [!div class="nextstepaction"] -> [How-To: _Open AI Assistant Agent_ Code File Search](./example-assistant-search.md) +> [How-To: _OpenAI Assistant Agent_ Code File Search](./example-assistant-search.md) diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index f38a28d4..e05c069c 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -1,6 +1,6 @@ --- -title: How-To: _Open AI Assistant Agent_ File Search (Experimental) -description: A step-by-step walk-through of defining and utilizing the file-search tool of an Open AI Assistant Agent. +title: How-To: _OpenAI Assistant Agent_ File Search (Experimental) +description: A step-by-step walk-through of defining and utilizing the file-search tool of an OpenAI Assistant Agent. zone_pivot_groups: programming-languages author: crickman ms.topic: tutorial @@ -8,14 +8,14 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# How-To: _Open AI Assistant Agent_ File Search +# How-To: _OpenAI Assistant Agent_ File Search > [!WARNING] > The *Semantic Kernel Agent Framework* is in preview and is subject to change. ## Overview -In this sample, we will explore how to use the _file-search_ tool of an [_Open AI Assistant Agent_](../assistant-agent.md) to complete comprehension tasks. The approach will be step-by-step, ensuring clarity and precision throughout the process. As part of the task, the agent will provide document citations within the response. +In this sample, we will explore how to use the _file-search_ tool of an [_OpenAI Assistant Agent_](../assistant-agent.md) to complete comprehension tasks. The approach will be step-by-step, ensuring clarity and precision throughout the process. As part of the task, the agent will provide document citations within the response. Streaming will be used to deliver the agent's responses. This will provide real-time updates as the task progresses. @@ -106,16 +106,16 @@ Additionally, copy the `Grimms-The-King-of-the-Golden-Mountain.txt`, `Grimms-The ## Configuration -This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _Open AI_ or _Azure Open AI_. +This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_. ::: zone pivot="programming-language-csharp" ```powershell -# Open AI +# OpenAI dotnet user-secrets set "OpenAISettings:ApiKey" "" dotnet user-secrets set "OpenAISettings:ChatModel" "gpt-4o" -# Azure Open AI +# Azure OpenAI dotnet user-secrets set "AzureOpenAISettings:ApiKey" "" # Not required if using token-credential dotnet user-secrets set "AzureOpenAISettings:Endpoint" "https://lightspeed-team-shared-openai-eastus.openai.azure.com/" dotnet user-secrets set "AzureOpenAISettings:ChatModelDeployment" "gpt-4o" @@ -208,7 +208,7 @@ The full example code is provided in the [Final](#final) section. Refer to that ### Setup -Prior to creating an _Open AI Assistant Agent_, ensure the configuration settings are available and prepare the file resources. +Prior to creating an _OpenAI Assistant Agent_, ensure the configuration settings are available and prepare the file resources. ::: zone pivot="programming-language-csharp" diff --git a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md index 589526ef..ced3bb01 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md +++ b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md @@ -103,18 +103,18 @@ Additionally, copy the GitHub plug-in and models (`github.py`) from [_Semantic K ## Configuration -This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _Open AI_ or _Azure Open AI_ and also for _GitHub_. +This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_ and also for _GitHub_. > Note: For information on GitHub _Personal Access Tokens_, see: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). ::: zone pivot="programming-language-csharp" ```powershell -# Open AI +# OpenAI dotnet user-secrets set "OpenAISettings:ApiKey" "" dotnet user-secrets set "OpenAISettings:ChatModel" "gpt-4o" -# Azure Open AI +# Azure OpenAI dotnet user-secrets set "AzureOpenAISettings:ApiKey" "" # Not required if using token-credential dotnet user-secrets set "AzureOpenAISettings:Endpoint" "" dotnet user-secrets set "AzureOpenAISettings:ChatModelDeployment" "gpt-4o" @@ -682,6 +682,6 @@ You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/m > [!div class="nextstepaction"] -> [How-To: _Open AI Assistant Agent_ Code Interpreter](./example-assistant-code.md) +> [How-To: _OpenAI Assistant Agent_ Code Interpreter](./example-assistant-code.md) diff --git a/semantic-kernel/Frameworks/agent/index.md b/semantic-kernel/Frameworks/agent/index.md index 978b0dce..7d8299ea 100644 --- a/semantic-kernel/Frameworks/agent/index.md +++ b/semantic-kernel/Frameworks/agent/index.md @@ -66,7 +66,7 @@ Package|Description [Microsoft.SemanticKernel](https://www.nuget.org/packages/Microsoft.SemanticKernel)|This contains the core _Semantic Kernel_ libraries for getting started with the _Agent Framework_. This must be explicitly referenced by your application. [Microsoft.SemanticKernel.Agents.Abstractions](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Abstractions)|Defines the core agent abstractions for the _Agent Framework_. Generally not required to be specified as it is included in both the `Microsoft.SemanticKernel.Agents.Core` and `Microsoft.SemanticKernel.Agents.OpenAI` packages. [Microsoft.SemanticKernel.Agents.Core](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Core)|Includes the [`ChatCompletionAgent`](./chat-completion-agent.md) and [`AgentGroupChat`](./agent-chat.md) classes. -[Microsoft.SemanticKernel.Agents.OpenAI](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.OpenAI)|Provides ability to use the [Open AI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent`](./assistant-agent.md). +[Microsoft.SemanticKernel.Agents.OpenAI](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.OpenAI)|Provides ability to use the [OpenAI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent`](./assistant-agent.md). ::: zone-end @@ -74,7 +74,7 @@ Package|Description Module|Description --|-- -[semantic-kernel.agents](https://pypi.org/project/semantic-kernel/)|This is the _Semantic Kernel_ library for getting started with the _Agent Framework_. This must be explicitly referenced by your application. This module contains the [`ChatCompletionAgent`](./chat-completion-agent.md) and [`AgentGroupChat`](./agent-chat.md) classes, as well as the ability to use the [Open AI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent` or `AzureOpenAssistant`](./assistant-agent.md). +[semantic-kernel.agents](https://pypi.org/project/semantic-kernel/)|This is the _Semantic Kernel_ library for getting started with the _Agent Framework_. This must be explicitly referenced by your application. This module contains the [`ChatCompletionAgent`](./chat-completion-agent.md) and [`AgentGroupChat`](./agent-chat.md) classes, as well as the ability to use the [OpenAI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent` or `AzureOpenAssistant`](./assistant-agent.md). ::: zone-end diff --git a/semantic-kernel/concepts/ai-services/embedding-generation/index.md b/semantic-kernel/concepts/ai-services/embedding-generation/index.md index f2f4aa7c..773ab713 100644 --- a/semantic-kernel/concepts/ai-services/embedding-generation/index.md +++ b/semantic-kernel/concepts/ai-services/embedding-generation/index.md @@ -154,7 +154,7 @@ using Microsoft.SemanticKernel; IKernelBuilder kernelBuilder = Kernel.CreateBuilder(); kernelBuilder.AddAzureOpenAITextEmbeddingGeneration( deploymentName: "NAME_OF_YOUR_DEPLOYMENT", // Name of deployment, e.g. "text-embedding-ada-002". - endpoint: "YOUR_AZURE_ENDPOINT", // Name of Azure Open AI service endpoint, e.g. https://myaiservice.openai.azure.com. + endpoint: "YOUR_AZURE_ENDPOINT", // Name of Azure OpenAI service endpoint, e.g. https://myaiservice.openai.azure.com. apiKey: "YOUR_API_KEY", modelId: "MODEL_ID", // Optional name of the underlying model if the deployment name doesn't match the model name, e.g. text-embedding-ada-002. serviceId: "YOUR_SERVICE_ID", // Optional; for targeting specific services within Semantic Kernel. @@ -301,7 +301,7 @@ var builder = Host.CreateApplicationBuilder(args); #pragma warning disable SKEXP0010 builder.Services.AddAzureOpenAITextEmbeddingGeneration( deploymentName: "NAME_OF_YOUR_DEPLOYMENT", // Name of deployment, e.g. "text-embedding-ada-002". - endpoint: "YOUR_AZURE_ENDPOINT", // Name of Azure Open AI service endpoint, e.g. https://myaiservice.openai.azure.com. + endpoint: "YOUR_AZURE_ENDPOINT", // Name of Azure OpenAI service endpoint, e.g. https://myaiservice.openai.azure.com. apiKey: "YOUR_API_KEY", modelId: "MODEL_ID", // Optional name of the underlying model if the deployment name doesn't match the model name, e.g. text-embedding-ada-002. serviceId: "YOUR_SERVICE_ID", // Optional; for targeting specific services within Semantic Kernel. @@ -468,7 +468,7 @@ using Microsoft.SemanticKernel.Connectors.AzureOpenAI; #pragma warning disable SKEXP0010 AzureOpenAITextEmbeddingGenerationService textEmbeddingGenerationService = new ( deploymentName: "NAME_OF_YOUR_DEPLOYMENT", // Name of deployment, e.g. "text-embedding-ada-002". - endpoint: "YOUR_AZURE_ENDPOINT", // Name of Azure Open AI service endpoint, e.g. https://myaiservice.openai.azure.com. + endpoint: "YOUR_AZURE_ENDPOINT", // Name of Azure OpenAI service endpoint, e.g. https://myaiservice.openai.azure.com. apiKey: "YOUR_API_KEY", modelId: "MODEL_ID", // Optional name of the underlying model if the deployment name doesn't match the model name, e.g. text-embedding-ada-002. httpClient: new HttpClient(), // Optional; if not provided, the HttpClient from the kernel will be used. diff --git a/semantic-kernel/concepts/vector-store-connectors/embedding-generation.md b/semantic-kernel/concepts/vector-store-connectors/embedding-generation.md index a1765df1..736d5d59 100644 --- a/semantic-kernel/concepts/vector-store-connectors/embedding-generation.md +++ b/semantic-kernel/concepts/vector-store-connectors/embedding-generation.md @@ -26,7 +26,7 @@ You can construct instances of the text embedding services provided by Semantic They all implement the `ITextEmbeddingGenerationService` interface. ```csharp -// Constructing an Azure Open AI embedding generation service directly. +// Constructing an Azure OpenAI embedding generation service directly. ITextEmbeddingGenerationService azureOpenAITES = new AzureOpenAITextEmbeddingGenerationService( "text-embedding-ada-002", "https://{myservice}.openai.azure.com/", @@ -113,7 +113,7 @@ public async Task GenerateEmbeddingsAndSearchAsync( ## Embedding dimensions Vector databases typically require you to specify the number of dimensions that each vector has when creating the collection. -Different embedding models typically support generating vectors with different dimension sizes. E.g. Open AI `text-embedding-ada-002` +Different embedding models typically support generating vectors with different dimension sizes. E.g. OpenAI `text-embedding-ada-002` generates vectors with 1536 dimensions. Some models also allow a developer to choose the number of dimensions they want in the output vector, e.g. Google `text-embedding-004` produces vectors with 768 dimension by default, but allows a developer to choose any number of dimensions between 1 and 768. diff --git a/semantic-kernel/concepts/vector-store-connectors/how-to/vector-store-data-ingestion.md b/semantic-kernel/concepts/vector-store-connectors/how-to/vector-store-data-ingestion.md index be9d84d3..d7f6e62b 100644 --- a/semantic-kernel/concepts/vector-store-connectors/how-to/vector-store-data-ingestion.md +++ b/semantic-kernel/concepts/vector-store-connectors/how-to/vector-store-data-ingestion.md @@ -240,7 +240,7 @@ var deploymentName = "text-embedding-ada-002"; var endpoint = "https://sksample.openai.azure.com/"; var apiKey = "your-api-key"; -// Register Azure Open AI text embedding generation service and Redis vector store. +// Register Azure OpenAI text embedding generation service and Redis vector store. var builder = Kernel.CreateBuilder() .AddAzureOpenAITextEmbeddingGeneration(deploymentName, endpoint, apiKey) .AddRedisVectorStore("localhost:6379"); From 20fdca69cd29b62a636e6b490acadf15f0f4ddd6 Mon Sep 17 00:00:00 2001 From: westey <164392973+westey-m@users.noreply.github.com> Date: Wed, 26 Feb 2025 10:57:59 +0000 Subject: [PATCH 32/70] Fix unsupported distance functions in samples --- semantic-kernel/concepts/vector-store-connectors/index.md | 2 +- .../out-of-the-box-connectors/pinecone-connector.md | 2 +- .../out-of-the-box-connectors/qdrant-connector.md | 2 +- .../out-of-the-box-connectors/redis-connector.md | 4 ++-- .../out-of-the-box-connectors/weaviate-connector.md | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/semantic-kernel/concepts/vector-store-connectors/index.md b/semantic-kernel/concepts/vector-store-connectors/index.md index 1284ab54..56f362eb 100644 --- a/semantic-kernel/concepts/vector-store-connectors/index.md +++ b/semantic-kernel/concepts/vector-store-connectors/index.md @@ -169,7 +169,7 @@ public class Hotel [VectorStoreRecordData(IsFullTextSearchable = true)] public string Description { get; set; } - [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)] + [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineSimilarity, IndexKind.Hnsw)] public ReadOnlyMemory? DescriptionEmbedding { get; set; } [VectorStoreRecordData(IsFilterable = true)] diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/pinecone-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/pinecone-connector.md index ff7fd03a..134a29bc 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/pinecone-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/pinecone-connector.md @@ -158,7 +158,7 @@ public class Hotel [VectorStoreRecordData(IsFullTextSearchable = true, StoragePropertyName = "hotel_description")] public string Description { get; set; } - [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)] + [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineSimilarity, IndexKind.Hnsw)] public ReadOnlyMemory? DescriptionEmbedding { get; set; } } ``` diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/qdrant-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/qdrant-connector.md index 1b0934e2..03ee4e4b 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/qdrant-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/qdrant-connector.md @@ -138,7 +138,7 @@ public class Hotel [VectorStoreRecordData(IsFullTextSearchable = true, StoragePropertyName = "hotel_description")] public string Description { get; set; } - [VectorStoreRecordVector(4, DistanceFunction.CosineDistance, IndexKind.Hnsw, StoragePropertyName = "hotel_description_embedding")] + [VectorStoreRecordVector(4, DistanceFunction.CosineSimilarity, IndexKind.Hnsw, StoragePropertyName = "hotel_description_embedding")] public ReadOnlyMemory? DescriptionEmbedding { get; set; } } ``` diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/redis-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/redis-connector.md index fbd9f8f1..72d8ef82 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/redis-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/redis-connector.md @@ -340,7 +340,7 @@ public class Hotel [VectorStoreRecordData(IsFullTextSearchable = true)] public string Description { get; set; } - [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw)] + [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineSimilarity, IndexKind.Hnsw)] public ReadOnlyMemory? DescriptionEmbedding { get; set; } } ``` @@ -375,7 +375,7 @@ public class Hotel [VectorStoreRecordData(IsFullTextSearchable = true, StoragePropertyName = "hotel_description")] public string Description { get; set; } - [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineDistance, IndexKind.Hnsw, StoragePropertyName = "hotel_description_embedding")] + [VectorStoreRecordVector(Dimensions: 4, DistanceFunction.CosineSimilarity, IndexKind.Hnsw, StoragePropertyName = "hotel_description_embedding")] public ReadOnlyMemory? DescriptionEmbedding { get; set; } } ``` diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md index 52ea034a..52a0178a 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md @@ -163,7 +163,7 @@ public class Hotel public string Description { get; set; } [JsonPropertyName("HOTEL_DESCRIPTION_EMBEDDING")] - [VectorStoreRecordVector(4, DistanceFunction.EuclideanDistance, IndexKind.QuantizedFlat)] + [VectorStoreRecordVector(4, DistanceFunction.CosineDistance, IndexKind.QuantizedFlat)] public ReadOnlyMemory? DescriptionEmbedding { get; set; } } ``` From d7d91a3c5555b92e2821aaba0d2c8dcb08c0bf96 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Mon, 17 Feb 2025 15:09:44 +0100 Subject: [PATCH 33/70] updated table --- .../out-of-the-box-connectors/index.md | 94 +++++++++---------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md index 15b30d1d..e95a8f24 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md @@ -22,60 +22,60 @@ Semantic Kernel provides a number of out-of-the-box Vector Store integrations ma ::: zone pivot="programming-language-csharp" -| Vector Store Connectors | C# | Uses officially supported SDK | Maintainer / Vendor | -|------------------------------------------------------------|:---------------:|:---------------------------------:|:----------------------------------:| -| [Azure AI Search](./azure-ai-search-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Cosmos DB MongoDB (vCore)](./azure-cosmosdb-mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Cosmos DB No SQL](./azure-cosmosdb-nosql-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Couchbase](./couchbase-connector.md) | ✅ | ✅ | Couchbase | -| [Elasticsearch](./elasticsearch-connector.md) | ✅ | ✅ | Elastic | -| Chroma | Planned | | | -| [In-Memory](./inmemory-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project | -| Milvus | Planned | | | -| [MongoDB](./mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Pinecone](./pinecone-connector.md) | ✅ | ❌ | Microsoft Semantic Kernel Project | -| [Postgres](./postgres-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| Sql Server | Planned | | | -| [SQLite](./sqlite-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Volatile (In-Memory)](./volatile-connector.md) | Deprecated (use In-Memory) | N/A | Microsoft Semantic Kernel Project | -| [Weaviate](./weaviate-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| Vector Store Connectors | C# | Uses officially supported SDK | Maintainer / Vendor | +| ------------------------------------------------------------------ | :------------------------: | :---------------------------: | :-------------------------------: | +| [Azure AI Search](./azure-ai-search-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Cosmos DB MongoDB (vCore)](./azure-cosmosdb-mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Cosmos DB No SQL](./azure-cosmosdb-nosql-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Couchbase](./couchbase-connector.md) | ✅ | ✅ | Couchbase | +| [Elasticsearch](./elasticsearch-connector.md) | ✅ | ✅ | Elastic | +| Chroma | Planned | | | +| [In-Memory](./inmemory-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project | +| Milvus | Planned | | | +| [MongoDB](./mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Pinecone](./pinecone-connector.md) | ✅ | ❌ | Microsoft Semantic Kernel Project | +| [Postgres](./postgres-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| Sql Server | Planned | | | +| [SQLite](./sqlite-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Volatile (In-Memory)](./volatile-connector.md) | Deprecated (use In-Memory) | N/A | Microsoft Semantic Kernel Project | +| [Weaviate](./weaviate-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | ::: zone-end ::: zone pivot="programming-language-python" -| Vector Store Connectors | Python | Uses officially supported SDK | Maintainer / Vendor | -|------------------------------------------------------------|:---------------:|:----------------------------------:|:----------------------------------:| -| [Azure AI Search](./azure-ai-search-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Cosmos DB MongoDB (vCore)](./azure-cosmosdb-mongodb-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | -| [Cosmos DB No SQL](./azure-cosmosdb-nosql-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | -| [Elasticsearch](./elasticsearch-connector.md) | Planned | | | -| Chroma | Planned | | | -| [In-Memory](./inmemory-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project | -| Milvus | Planned | | | -| [MongoDB](./mongodb-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | -| [Pinecone](./pinecone-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | -| [Postgres](./postgres-connector.md) | ✅ | | Microsoft Semantic Kernel Project | -| [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| Sql Server | Planned | | | -| [SQLite](./sqlite-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | -| [Volatile (In-Memory)](./volatile-connector.md) | Deprecated (use In-Memory) | N/A | Microsoft Semantic Kernel Project | -| [Weaviate](./weaviate-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project | +| Vector Store Connectors | Python | Uses officially supported SDK | Maintainer / Vendor | +| ------------------------------------------------------------------ | :------------------------: | :---------------------------: | :-------------------------------: | +| [Azure AI Search](./azure-ai-search-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Cosmos DB MongoDB (vCore)](./azure-cosmosdb-mongodb-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | +| [Cosmos DB No SQL](./azure-cosmosdb-nosql-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Elasticsearch](./elasticsearch-connector.md) | Planned | | | +| Chroma | Planned | | | +| [In-Memory](./inmemory-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project | +| Milvus | Planned | | | +| [MongoDB](./mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Pinecone](./pinecone-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | +| [Postgres](./postgres-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| Sql Server | Planned | | | +| [SQLite](./sqlite-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | +| [Volatile (In-Memory)](./volatile-connector.md) | Deprecated (use In-Memory) | N/A | Microsoft Semantic Kernel Project | +| [Weaviate](./weaviate-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | ::: zone-end ::: zone pivot="programming-language-java" -| Vector Store Connectors | Java | Uses officially supported SDK | Maintainer / Vendor | -|------------------------------------------------------------|:--------------:|:----------------------------------:|:----------------------------------:| -| [Azure AI Search](./azure-ai-search-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| HSQLDB | Use [JDBC](./jdbc-connector.md) | ✅ | Microsoft Semantic Kernel Project | -| [JDBC](./jdbc-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| MySQL | Use [JDBC](./jdbc-connector.md) | ✅ | Microsoft Semantic Kernel Project | -| Postgres | Use [JDBC](./jdbc-connector.md) | | Microsoft Semantic Kernel Project | -| [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| SQLite | Use [JDBC](./jdbc-connector.md) | ✅ | Microsoft Semantic Kernel Project | -| [Volatile (In-Memory)](./volatile-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project | +| Vector Store Connectors | Java | Uses officially supported SDK | Maintainer / Vendor | +| ------------------------------------------------- | :-----------------------------: | :---------------------------: | :-------------------------------: | +| [Azure AI Search](./azure-ai-search-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| HSQLDB | Use [JDBC](./jdbc-connector.md) | ✅ | Microsoft Semantic Kernel Project | +| [JDBC](./jdbc-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| MySQL | Use [JDBC](./jdbc-connector.md) | ✅ | Microsoft Semantic Kernel Project | +| Postgres | Use [JDBC](./jdbc-connector.md) | | Microsoft Semantic Kernel Project | +| [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| SQLite | Use [JDBC](./jdbc-connector.md) | ✅ | Microsoft Semantic Kernel Project | +| [Volatile (In-Memory)](./volatile-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project | ::: zone-end From e5bc203287653a1be611c5d55cff0d835ba61067 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Mon, 17 Feb 2025 15:53:24 +0100 Subject: [PATCH 34/70] adding mssing stores --- .../out-of-the-box-connectors/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md index e95a8f24..958500a3 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md @@ -59,9 +59,10 @@ Semantic Kernel provides a number of out-of-the-box Vector Store integrations ma | [Postgres](./postgres-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | | [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | | [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| Sql Server | Planned | | | -| [SQLite](./sqlite-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | +| SQL Server | Planned | ✅ | Microsoft Semantic Kernel Project | +| SQLite | Planned | ✅ | Microsoft Semantic Kernel Project | | [Volatile (In-Memory)](./volatile-connector.md) | Deprecated (use In-Memory) | N/A | Microsoft Semantic Kernel Project | +| Usearch | Planned | ✅ | Microsoft Semantic Kernel Project | | [Weaviate](./weaviate-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | ::: zone-end From 65270c5cf694a3cf6319ea3b494044235790b20a Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 26 Feb 2025 14:46:28 +0100 Subject: [PATCH 35/70] updated a whole bunch --- .../out-of-the-box-connectors/TOC.yml | 2 + .../azure-ai-search-connector.md | 64 +++++++--- .../azure-cosmosdb-mongodb-connector.md | 97 ++++++++++++--- .../chroma-connector.md | 104 ++++++++++++++++ .../out-of-the-box-connectors/index.md | 36 +++--- .../mongodb-connector.md | 96 ++++++++++++--- .../weaviate-connector.md | 113 ++++++++++++++---- 7 files changed, 423 insertions(+), 89 deletions(-) create mode 100644 semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/TOC.yml b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/TOC.yml index b4c46306..de9c5f57 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/TOC.yml +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/TOC.yml @@ -6,6 +6,8 @@ href: azure-cosmosdb-mongodb-connector.md - name: Azure CosmosDB NoSQL connector href: azure-cosmosdb-nosql-connector.md +- name: Chroma connector + href: chroma-connector.md - name: Couchbase connector href: couchbase-connector.md - name: Elasticsearch connector diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-ai-search-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-ai-search-connector.md index 305ce851..9f75aca2 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-ai-search-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-ai-search-connector.md @@ -17,27 +17,59 @@ ms.service: semantic-kernel The Azure AI Search Vector Store connector can be used to access and manage data in Azure AI Search. The connector has the following characteristics. -| Feature Area | Support | -|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------| -| Collection maps to | Azure AI Search Index | -| Supported key property types | string | -| Supported data property types |
      • string
      • int
      • long
      • double
      • float
      • bool
      • DateTimeOffset
      • *and enumerables of each of these types*
      | -| Supported vector property types | ReadOnlyMemory\ | -| Supported index types |
      • Hnsw
      • Flat
      | -| Supported distance functions |
      • CosineSimilarity
      • DotProductSimilarity
      • EuclideanDistance
      | -| Supported filter clauses |
      • AnyTagEqualTo
      • EqualTo
      | -| Supports multiple vectors in a record | Yes | -| IsFilterable supported? | Yes | -| IsFullTextSearchable supported? | Yes | -| StoragePropertyName supported? | No, use `JsonSerializerOptions` and `JsonPropertyNameAttribute` instead. [See here for more info.](#data-mapping) | +::: zone pivot="programming-language-csharp" + +| Feature Area | Support | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Collection maps to | Azure AI Search Index | +| Supported key property types | string | +| Supported data property types |
      • string
      • int
      • long
      • double
      • float
      • bool
      • DateTimeOffset
      • *and enumerables of each of these types*
      | +| Supported vector property types | ReadOnlyMemory\ | +| Supported index types |
      • Hnsw
      • Flat
      | +| Supported distance functions |
      • CosineSimilarity
      • DotProductSimilarity
      • EuclideanDistance
      | +| Supported filter clauses |
      • AnyTagEqualTo
      • EqualTo
      | +| Supports multiple vectors in a record | Yes | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | Yes | +| StoragePropertyName supported? | No, use `JsonSerializerOptions` and `JsonPropertyNameAttribute` instead. [See here for more info.](#data-mapping) | +::: zone-end +::: zone pivot="programming-language-python" +| Feature Area | Support | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Collection maps to | Azure AI Search Index | +| Supported key property types | string | +| Supported data property types |
      • string
      • int
      • long
      • double
      • float
      • bool
      • DateTimeOffset
      • *and iterables of each of these types*
      | +| Supported vector property types | list[float], list[int], ndarray | +| Supported index types |
      • Hnsw
      • Flat
      | +| Supported distance functions |
      • CosineSimilarity
      • DotProductSimilarity
      • EuclideanDistance
    • Hamming
    | +| Supported filter clauses |
    • AnyTagEqualTo
    • EqualTo
    | +| Supports multiple vectors in a record | Yes | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | Yes | +::: zone-end +::: zone pivot="programming-language-java" +| Feature Area | Support | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Collection maps to | Azure AI Search Index | +| Supported key property types | string | +| Supported data property types |
    • string
    • int
    • long
    • double
    • float
    • bool
    • DateTimeOffset
    • *and enumerables of each of these types*
    | +| Supported vector property types | ReadOnlyMemory\ | +| Supported index types |
    • Hnsw
    • Flat
    | +| Supported distance functions |
    • CosineSimilarity
    • DotProductSimilarity
    • EuclideanDistance
    | +| Supported filter clauses |
    • AnyTagEqualTo
    • EqualTo
    | +| Supports multiple vectors in a record | Yes | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | Yes | +| StoragePropertyName supported? | No, use `JsonSerializerOptions` and `JsonPropertyNameAttribute` instead. [See here for more info.](#data-mapping) | +::: zone-end ## Limitations Notable Azure AI Search connector functionality limitations. -| Feature Area | Workaround | -|--------------------------------------------------------------------------------------| -----------------------------------------------------------------------------------------------| -| Configuring full text search analyzers during collection creation is not supported. | Use the Azure AI Search Client SDK directly for collection creation | +| Feature Area | Workaround | +| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| Configuring full text search analyzers during collection creation is not supported. | Use the Azure AI Search Client SDK directly for collection creation | ::: zone pivot="programming-language-csharp" diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-cosmosdb-mongodb-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-cosmosdb-mongodb-connector.md index 46fbbf96..c50ed06f 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-cosmosdb-mongodb-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-cosmosdb-mongodb-connector.md @@ -13,30 +13,50 @@ ms.service: semantic-kernel > [!WARNING] > The Semantic Kernel Vector Store functionality is in preview, and improvements that require breaking changes may still occur in limited circumstances before release. -::: zone pivot="programming-language-csharp" - ## Overview The Azure CosmosDB MongoDB Vector Store connector can be used to access and manage data in Azure CosmosDB MongoDB (vCore). The connector has the following characteristics. -| Feature Area | Support | -|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------| -| Collection maps to | Azure Cosmos DB MongoDB (vCore) Collection + Index | -| Supported key property types | string | -| Supported data property types |
    • string
    • int
    • long
    • double
    • float
    • decimal
    • bool
    • DateTime
    • *and enumerables of each of these types*
    | -| Supported vector property types |
    • ReadOnlyMemory\
    • ReadOnlyMemory\
    | -| Supported index types |
    • Hnsw
    • IvfFlat
    | -| Supported distance functions |
    • CosineDistance
    • DotProductSimilarity
    • EuclideanDistance
    | -| Supported filter clauses |
    • EqualTo
    | -| Supports multiple vectors in a record | Yes | -| IsFilterable supported? | Yes | -| IsFullTextSearchable supported? | No | -| StoragePropertyName supported? | No, use BsonElementAttribute instead. [See here for more info.](#data-mapping) | +::: zone pivot="programming-language-csharp" + +| Feature Area | Support | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Collection maps to | Azure Cosmos DB MongoDB (vCore) Collection + Index | +| Supported key property types | string | +| Supported data property types |
    • string
    • int
    • long
    • double
    • float
    • decimal
    • bool
    • DateTime
    • *and enumerables of each of these types*
    | +| Supported vector property types |
    • ReadOnlyMemory\
    • ReadOnlyMemory\
    | +| Supported index types |
    • Hnsw
    • IvfFlat
    | +| Supported distance functions |
    • CosineDistance
    • DotProductSimilarity
    • EuclideanDistance
    | +| Supported filter clauses |
    • EqualTo
    | +| Supports multiple vectors in a record | Yes | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | No | +| StoragePropertyName supported? | No, use BsonElementAttribute instead. [See here for more info.](#data-mapping) | +::: zone-end +::: zone pivot="programming-language-python" +| Feature Area | Support | +| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Collection maps to | Azure Cosmos DB MongoDB (vCore) Collection + Index | +| Supported key property types | string | +| Supported data property types |
    • string
    • int
    • long
    • double
    • float
    • decimal
    • bool
    • DateTime
    • *and iterables of each of these types*
    | +| Supported vector property types |
    • list[float]
    • list[int]
  • ndarray
| +| Supported index types |
  • Hnsw
  • IvfFlat
| +| Supported distance functions |
  • CosineDistance
  • DotProductSimilarity
  • EuclideanDistance
| +| Supported filter clauses |
  • EqualTo
  • AnyTagsEqualTo
| +| Supports multiple vectors in a record | Yes | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | No | +::: zone-end +::: zone pivot="programming-language-java" +More info coming soon. +::: zone-end ## Limitations This connector is compatible with Azure Cosmos DB MongoDB (vCore) and is *not* designed to be compatible with Azure Cosmos DB MongoDB (RU). +::: zone pivot="programming-language-csharp" + ## Getting started Add the Azure CosmosDB MongoDB Vector Store connector NuGet package to your project. @@ -165,9 +185,52 @@ public class Hotel ::: zone-end ::: zone pivot="programming-language-python" -## Coming soon +## Getting started -More info coming soon. +Add the Azure CosmosDB MongoDB Vector Store dependencies to your environment. Because the Azure CosmosDB MongoDB connector is built on the MongoDB Atlas connector and uses the same client as that one, you need to install with these extras: + +```bash +pip install semantic-kernel[azure, mongo] +``` + +You can then create the vector store. + +```python +from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBforMongoDBStore + +# If the right environment settings are set, namely AZURE_COSMOS_DB_MONGODB_CONNECTION_STRING and optionally AZURE_COSMOS_DB_MONGODB_DATABASE_NAME, this is enough to create the Store: +store = AzureCosmosDBforMongoDBStore() +``` + +Alternatively, you can also pass in your own mongodb client if you want to have more control over the client construction: + +```python +from pymongo import AsyncMongoClient +from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBforMongoDBStore + +client = AsyncMongoClient(...) +store = AzureCosmosDBforMongoDBStore(mongo_client=client) +``` + +When a client is passed in, Semantic Kernel will not close the connection for you, so you need to ensure to close it, for instance with a `async with` statement. + +You can also create a collection directly, without the store. + +```python +from semantic_kernel.connectors.memory.azure_cosmos_db import AzureCosmosDBforMongoDBCollection + +# `hotel` is a class created with the @vectorstoremodel decorator +collection = AzureCosmosDBforMongoDBCollection( + collection_name="my_collection", + data_model_type=hotel +) +``` + +## Serialization + +Since the Azure CosmosDB for MongoDB connector needs a simple dict with the fields corresponding to the index as the input, the serialization is quite easy, it only uses a predetermined key `_id`, so we replace the key of the data model with that if it is not already `_id`. + +For more details on this concept see the [serialization documentation](./../serialization.md). ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md new file mode 100644 index 00000000..f16e802c --- /dev/null +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md @@ -0,0 +1,104 @@ +--- +title: Using the Semantic Kernel Chroma Vector Store connector (Preview) +description: Contains information on how to use a Semantic Kernel Vector store connector to access and manipulate data in ChromaDB. +zone_pivot_groups: programming-languages +author: eavanvalkenburg +ms.topic: conceptual +ms.author: eavanvalkenburg +ms.date: 02/26/2025 +ms.service: semantic-kernel +--- + +# Using the Chroma connector (Preview) + +> [!WARNING] +> The Semantic Kernel Vector Store functionality is in preview, and improvements that require breaking changes may still occur in limited circumstances before release. + +::: zone pivot="programming-language-csharp" + +## Not supported + +Not supported. + +::: zone-end +::: zone pivot="programming-language-python" + +## Overview + +The Chroma Vector Store connector can be used to access and manage data in Chroma. The connector has the +following characteristics. + +| Feature Area | Support | +| ------------------------------------- | ------------------------------------------------------------------------------------------------- | +| Collection maps to | Chroma collection | +| Supported key property types | string | +| Supported data property types | All types that are supported by System.Text.Json (either built-in or by using a custom converter) | +| Supported vector property types |
  • list[float]
  • list[int]
  • ndarray]
| +| Supported index types |
  • HNSW
| +| Supported distance functions |
  • CosineSimilarity
  • DotProductSimilarity
  • EuclideanSquaredDistance
| +| Supported filter clauses |
  • AnyTagEqualTo
  • EqualTo
| +| Supports multiple vectors in a record | No | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | Yes | + +## Limitations + +Notable Chroma connector functionality limitations. + +| Feature Area | Workaround | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| Client-server mode | Use the client.HttpClient and pass the result to the `client` parameter, we do not support a AsyncHttpClient at this time | +| Chroma Cloud | Unclear at this time, as Chroma Cloud is still in private preview | + +## Getting Started + +Add the Chroma Vector Store connector dependencies to your project. + +```bash +pip install semantic-kernel[chroma] +``` + +You can then create the vector store. + +```python +from semantic_kernel.connectors.memory.chroma import ChromaStore + +store = ChromaStore() +``` + +Alternatively, you can also pass in your own mongodb client if you want to have more control over the client construction: + +```python +from chromadb import Client +from semantic_kernel.connectors.memory.chroma import ChromaStore + +client = Client(...) +store = ChromaStore(client=client) +``` + +You can also create a collection directly, without the store. + +```python +from semantic_kernel.connectors.memory.chroma import ChromaCollection + +# `hotel` is a class created with the @vectorstoremodel decorator +collection = ChromaCollection( + collection_name="my_collection", + data_model_type=hotel +) +``` + +## Serialization + +The Chroma client returns both `get` and `search` results in tabular form, this means that there are between 3 and 5 lists being returned in a dict, the lists are 'keys', 'documents', 'embeddings', and optionally 'metadatas' and 'distances'. The Semantic Kernel Chroma connector will automatically convert this into a list of `dict` objects, which are then parsed back to your data model. + +It could be very interesting performance wise to do straight serialization from this format into a dataframe-like structure as that saves a lot of rebuilding of the data structure. This is not done for you, even when using container mode, you would have to specify this yourself, for more details on this concept see the [serialization documentation](./../serialization.md). + +::: zone-end +::: zone pivot="programming-language-java" + +## Not supported + +Not supported. + +::: zone-end diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md index 958500a3..ef0c44cc 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/index.md @@ -45,25 +45,23 @@ Semantic Kernel provides a number of out-of-the-box Vector Store integrations ma ::: zone-end ::: zone pivot="programming-language-python" -| Vector Store Connectors | Python | Uses officially supported SDK | Maintainer / Vendor | -| ------------------------------------------------------------------ | :------------------------: | :---------------------------: | :-------------------------------: | -| [Azure AI Search](./azure-ai-search-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Cosmos DB MongoDB (vCore)](./azure-cosmosdb-mongodb-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | -| [Cosmos DB No SQL](./azure-cosmosdb-nosql-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Elasticsearch](./elasticsearch-connector.md) | Planned | | | -| Chroma | Planned | | | -| [In-Memory](./inmemory-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project | -| Milvus | Planned | | | -| [MongoDB](./mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Pinecone](./pinecone-connector.md) | In Development | ✅ | Microsoft Semantic Kernel Project | -| [Postgres](./postgres-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | -| SQL Server | Planned | ✅ | Microsoft Semantic Kernel Project | -| SQLite | Planned | ✅ | Microsoft Semantic Kernel Project | -| [Volatile (In-Memory)](./volatile-connector.md) | Deprecated (use In-Memory) | N/A | Microsoft Semantic Kernel Project | -| Usearch | Planned | ✅ | Microsoft Semantic Kernel Project | -| [Weaviate](./weaviate-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| Vector Store Connectors | Python | Uses officially supported SDK | Maintainer / Vendor | +| ------------------------------------------------------------------ | :-----: | :---------------------------: | :-------------------------------: | +| [Azure AI Search](./azure-ai-search-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Cosmos DB MongoDB (vCore)](./azure-cosmosdb-mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Cosmos DB No SQL](./azure-cosmosdb-nosql-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Chroma](./chroma-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Elasticsearch](./elasticsearch-connector.md) | Planned | | | +| Faiss | Planned | | | +| [In-Memory](./inmemory-connector.md) | ✅ | N/A | Microsoft Semantic Kernel Project | +| [MongoDB](./mongodb-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Pinecone](./pinecone-connector.md) | Planned | ✅ | Microsoft Semantic Kernel Project | +| [Postgres](./postgres-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Qdrant](./qdrant-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| [Redis](./redis-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | +| SQL Server | Planned | ✅ | Microsoft Semantic Kernel Project | +| SQLite | Planned | ✅ | Microsoft Semantic Kernel Project | +| [Weaviate](./weaviate-connector.md) | ✅ | ✅ | Microsoft Semantic Kernel Project | ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md index 6c406610..e5e79881 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md @@ -13,25 +13,44 @@ ms.service: semantic-kernel > [!WARNING] > The Semantic Kernel Vector Store functionality is in preview, and improvements that require breaking changes may still occur in limited circumstances before release. -::: zone pivot="programming-language-csharp" - ## Overview The MongoDB Vector Store connector can be used to access and manage data in MongoDB. The connector has the following characteristics. -| Feature Area | Support | -|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------| -| Collection maps to | MongoDB Collection + Index | -| Supported key property types | string | -| Supported data property types |
  • string
  • int
  • long
  • double
  • float
  • decimal
  • bool
  • DateTime
  • *and enumerables of each of these types*
| -| Supported vector property types |
  • ReadOnlyMemory\
  • ReadOnlyMemory\
| -| Supported index types | N/A | -| Supported distance functions |
  • CosineSimilarity
  • DotProductSimilarity
  • EuclideanDistance
| -| Supported filter clauses |
  • EqualTo
| -| Supports multiple vectors in a record | Yes | -| IsFilterable supported? | Yes | -| IsFullTextSearchable supported? | No | -| StoragePropertyName supported? | No, use BsonElementAttribute instead. [See here for more info.](#data-mapping) | +::: zone pivot="programming-language-csharp" + +| Feature Area | Support | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Collection maps to | MongoDB Collection + Index | +| Supported key property types | string | +| Supported data property types |
  • string
  • int
  • long
  • double
  • float
  • decimal
  • bool
  • DateTime
  • *and enumerables of each of these types*
| +| Supported vector property types |
  • ReadOnlyMemory\
  • ReadOnlyMemory\
| +| Supported index types | N/A | +| Supported distance functions |
  • CosineSimilarity
  • DotProductSimilarity
  • EuclideanDistance
| +| Supported filter clauses |
  • EqualTo
| +| Supports multiple vectors in a record | Yes | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | No | +| StoragePropertyName supported? | No, use BsonElementAttribute instead. [See here for more info.](#data-mapping) | +::: zone-end +::: zone pivot="programming-language-python" + +| Feature Area | Support | +| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Collection maps to | MongoDB Collection + Index | +| Supported key property types | string | +| Supported data property types |
  • string
  • int
  • long
  • double
  • float
  • decimal
  • bool
  • DateTime
  • *and iterables of each of these types*
| +| Supported vector property types |
  • list[float]
  • list[int]
  • ndarray
    • | +| Supported index types |
    • Hnsw
    • IvfFlat
    | +| Supported distance functions |
    • CosineDistance
    • DotProductSimilarity
    • EuclideanDistance
    | +| Supported filter clauses |
    • EqualTo
    • AnyTagsEqualTo
    | +| Supports multiple vectors in a record | Yes | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | No | +::: zone-end +::: zone pivot="programming-language-java" +More info coming soon. +::: zone-end ## Getting started @@ -136,9 +155,52 @@ public class Hotel ::: zone-end ::: zone pivot="programming-language-python" -## Coming soon +## Getting started -More info coming soon. +Add the MongoDB Atlas Vector Store dependencies to your environment. It needs the `pymongo` package which is included in the mongo extra: + +```bash +pip install semantic-kernel[mongo] +``` + +You can then create the vector store. + +```python +from semantic_kernel.connectors.memory.mongodb_atlas import MongoDBAtlasStore + +# If the right environment settings are set, namely MONGODB_ATLAS_CONNECTION_STRING and optionally MONGODB_ATLAS_DATABASE_NAME and MONGODB_ATLAS_INDEX_NAME, this is enough to create the Store: +store = MongoDBAtlasStore() +``` + +Alternatively, you can also pass in your own mongodb client if you want to have more control over the client construction: + +```python +from pymongo import AsyncMongoClient +from semantic_kernel.connectors.memory.mongodb_atlas import MongoDBAtlasStore + +client = AsyncMongoClient(...) +store = MongoDBAtlasStore(mongo_client=client) +``` + +When a client is passed in, Semantic Kernel will not close the connection for you, so you need to ensure to close it, for instance with a `async with` statement. + +You can also create a collection directly, without the store. + +```python +from semantic_kernel.connectors.memory.mongodb_atlas import MongoDBAtlasCollection + +# `hotel` is a class created with the @vectorstoremodel decorator +collection = MongoDBAtlasCollection( + collection_name="my_collection", + data_model_type=hotel +) +``` + +## Serialization + +Since the MongoDB Atlas connector needs a simple dict with the fields corresponding to the index as the input, the serialization is quite easy, it only uses a predetermined key `_id`, so we replace the key of the data model with that if it is not already `_id`. + +For more details on this concept see the [serialization documentation](./../serialization.md). ::: zone-end ::: zone pivot="programming-language-java" diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md index 52ea034a..608135d8 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md @@ -13,33 +13,51 @@ ms.service: semantic-kernel > [!WARNING] > The Semantic Kernel Vector Store functionality is in preview, and improvements that require breaking changes may still occur in limited circumstances before release. -::: zone pivot="programming-language-csharp" - ## Overview The Weaviate Vector Store connector can be used to access and manage data in Weaviate. The connector has the following characteristics. -| Feature Area | Support | -|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------| -| Collection maps to | Weaviate Collection | -| Supported key property types | Guid | -| Supported data property types |
    • string
    • byte
    • short
    • int
    • long
    • double
    • float
    • decimal
    • bool
    • DateTime
    • DateTimeOffset
    • Guid
    • *and enumerables of each of these types*
    | -| Supported vector property types |
    • ReadOnlyMemory\
    • ReadOnlyMemory\
    | -| Supported index types |
    • Hnsw
    • Flat
    • Dynamic
    | -| Supported distance functions |
    • CosineDistance
    • NegativeDotProductSimilarity
    • EuclideanSquaredDistance
    • Hamming
    • ManhattanDistance
    | -| Supported filter clauses |
    • AnyTagEqualTo
    • EqualTo
    | -| Supports multiple vectors in a record | Yes | -| IsFilterable supported? | Yes | -| IsFullTextSearchable supported? | Yes | -| StoragePropertyName supported? | No, use `JsonSerializerOptions` and `JsonPropertyNameAttribute` instead. [See here for more info.](#data-mapping) | +::: zone pivot="programming-language-csharp" + +| Feature Area | Support | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Collection maps to | Weaviate Collection | +| Supported key property types | Guid | +| Supported data property types |
    • string
    • byte
    • short
    • int
    • long
    • double
    • float
    • decimal
    • bool
    • DateTime
    • DateTimeOffset
    • Guid
    • *and enumerables of each of these types*
    | +| Supported vector property types |
    • ReadOnlyMemory\
    • ReadOnlyMemory\
    | +| Supported index types |
    • Hnsw
    • Flat
    • Dynamic
    | +| Supported distance functions |
    • CosineDistance
    • NegativeDotProductSimilarity
    • EuclideanSquaredDistance
    • Hamming
    • ManhattanDistance
    | +| Supported filter clauses |
    • AnyTagEqualTo
    • EqualTo
    | +| Supports multiple vectors in a record | Yes | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | Yes | +| StoragePropertyName supported? | No, use `JsonSerializerOptions` and `JsonPropertyNameAttribute` instead. [See here for more info.](#data-mapping) | +::: zone-end +::: zone pivot="programming-language-python" +| Feature Area | Support | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Collection maps to | Weaviate Collection | +| Supported key property types | Guid | +| Supported data property types |
    • string
    • byte
    • short
    • int
    • long
    • double
    • float
    • decimal
    • bool
    • *and iterables of each of these types*
    | +| Supported vector property types |
    • list[float]
    • list[int]
  • ndarray
    • | +| Supported index types |
    • Hnsw
    • Flat
    • Dynamic
    | +| Supported distance functions |
    • CosineDistance
    • NegativeDotProductSimilarity
    • EuclideanSquaredDistance
    • Hamming
    • ManhattanDistance
    | +| Supported filter clauses |
    • AnyTagEqualTo
    • EqualTo
    | +| Supports multiple vectors in a record | Yes | +| IsFilterable supported? | Yes | +| IsFullTextSearchable supported? | Yes | +::: zone-end +::: zone pivot="programming-language-java" +Coming soon. +::: zone-end ## Limitations Notable Weaviate connector functionality limitations. -| Feature Area | Workaround | -|------------------------------------------------------------------------| -----------------------------------------------------------------------------------------------| -| Using the 'vector' property for single vector objects is not supported | Use of the 'vectors' property is supported instead. | +| Feature Area | Workaround | +| ---------------------------------------------------------------------- | --------------------------------------------------- | +| Using the 'vector' property for single vector objects is not supported | Use of the 'vectors' property is supported instead. | > [!WARNING] > Weaviate requires collection names to start with an upper case letter. If you do not provide a collection name with an upper case letter, Weaviate will return an error when you try and create your collection. The error that you will see is `Cannot query field "mycollection" on type "GetObjectsObj". Did you mean "Mycollection"?` where `mycollection` is your collection name. In this example, if you change your collection name to `Mycollection` instead, this will fix the error. @@ -181,9 +199,64 @@ public class Hotel ::: zone-end ::: zone pivot="programming-language-python" -## Coming soon +## Getting Started -More info coming soon. +Add the Weaviate Vector Store connector dependencies to your project. + +```bash +pip install semantic-kernel[weaviate] +``` + +You can then create the vector store, it uses environment settings to connect: + +For using Weaviate Cloud: + +- url: WEAVIATE_URL +- api_key: WEAVIATE_API_KEY + +For using Weaviate Local (i.e. Weaviate in a Docker container): + +- local_host: WEAVIATE_LOCAL_HOST +- local_port: WEAVIATE_LOCAL_PORT +- local_grpc_port: WEAVIATE_LOCAL_GRPC_PORT + +If you want to use embedded: + +- use_embed: WEAVIATE_USE_EMBED + +These should be set exclusively, so only one set of the above is present, otherwise it will raise an exception. + +```python +from semantic_kernel.connectors.memory.weaviate import WeaviateStore + +store = WeaviateStore() +``` + +Alternatively, you can also pass in your own mongodb client if you want to have more control over the client construction: + +```python +import weaviate +from semantic_kernel.connectors.memory.weaviate import WeaviateStore + +client = weaviate.WeaviateAsyncClient(...) +store = WeaviateStore(async_client=client) +``` + +You can also create a collection directly, without the store. + +```python +from semantic_kernel.connectors.memory.weaviate import WeaviateCollection + +# `hotel` is a class created with the @vectorstoremodel decorator +collection = WeaviateCollection( + collection_name="my_collection", + data_model_type=hotel +) +``` + +## Serialization + +The Weaviate client returns it's own objects which are parsed and turned into dicts in the regular flow, for more details on this concept see the [serialization documentation](./../serialization.md). ::: zone-end ::: zone pivot="programming-language-java" From ed29edc78d76f582961cffe467bf765bcec5c9c7 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 26 Feb 2025 14:51:08 +0100 Subject: [PATCH 36/70] fixes --- .../out-of-the-box-connectors/chroma-connector.md | 2 +- .../out-of-the-box-connectors/mongodb-connector.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md index f16e802c..c02e9fd1 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md @@ -4,7 +4,7 @@ description: Contains information on how to use a Semantic Kernel Vector store c zone_pivot_groups: programming-languages author: eavanvalkenburg ms.topic: conceptual -ms.author: eavanvalkenburg +ms.author: edvan ms.date: 02/26/2025 ms.service: semantic-kernel --- diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md index e5e79881..152d579b 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md @@ -51,6 +51,7 @@ The MongoDB Vector Store connector can be used to access and manage data in Mong ::: zone pivot="programming-language-java" More info coming soon. ::: zone-end +::: zone pivot="programming-language-csharp" ## Getting started @@ -157,7 +158,7 @@ public class Hotel ## Getting started -Add the MongoDB Atlas Vector Store dependencies to your environment. It needs the `pymongo` package which is included in the mongo extra: +Add the MongoDB Atlas Vector Store dependencies to your environment. It needs the `pymongo` package which is included in the mongo extra: , you need to install with these extras: ```bash pip install semantic-kernel[mongo] From f37d616cd8b0eced2dc07704855e4d8e6a9ac151 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 26 Feb 2025 16:45:16 +0100 Subject: [PATCH 37/70] initial version of realtime docs --- semantic-kernel/concepts/ai-services/TOC.yml | 4 +- semantic-kernel/concepts/ai-services/index.md | 22 ++--- .../concepts/ai-services/realtime.md | 88 +++++++++++++++++++ 3 files changed, 103 insertions(+), 11 deletions(-) create mode 100644 semantic-kernel/concepts/ai-services/realtime.md diff --git a/semantic-kernel/concepts/ai-services/TOC.yml b/semantic-kernel/concepts/ai-services/TOC.yml index 8d24a54b..fd35b379 100644 --- a/semantic-kernel/concepts/ai-services/TOC.yml +++ b/semantic-kernel/concepts/ai-services/TOC.yml @@ -6,4 +6,6 @@ - name: Embedding generation href: embedding-generation/TOC.yml - name: AI Integrations - href: integrations.md \ No newline at end of file + href: integrations.md +- name: Realtime + href: realtime.md \ No newline at end of file diff --git a/semantic-kernel/concepts/ai-services/index.md b/semantic-kernel/concepts/ai-services/index.md index 3e473aec..2a2da7b2 100644 --- a/semantic-kernel/concepts/ai-services/index.md +++ b/semantic-kernel/concepts/ai-services/index.md @@ -14,21 +14,23 @@ One of the main features of Semantic Kernel is its ability to add different AI s Within Semantic Kernel, there are interfaces for the most popular AI tasks. In the table below, you can see the services that are supported by each of the SDKs. -| Services | C# | Python | Java | Notes | -|-----------------------------------|:----:|:------:|:----:|-------| -| [Chat completion](./chat-completion/index.md) | ✅ | ✅ | ✅ | -| Text generation | ✅ | ✅ | ✅ | -| Embedding generation (Experimental) | ✅ | ✅ | ✅ | -| Text-to-image (Experimental) | ✅ | ✅ | ❌ | -| Image-to-text (Experimental) | ✅ | ❌ | ❌ | -| Text-to-audio (Experimental) | ✅ | ✅ | ❌ | -| Audio-to-text (Experimental) | ✅ | ✅ | ❌ | +| Services | C# | Python | Java | Notes | +| --------------------------------------------- | :---: | :----: | :---: | ----- | +| [Chat completion](./chat-completion/index.md) | ✅ | ✅ | ✅ | +| Text generation | ✅ | ✅ | ✅ | +| Embedding generation (Experimental) | ✅ | ✅ | ✅ | +| Text-to-image (Experimental) | ✅ | ✅ | ❌ | +| Image-to-text (Experimental) | ✅ | ❌ | ❌ | +| Text-to-audio (Experimental) | ✅ | ✅ | ❌ | +| Audio-to-text (Experimental) | ✅ | ✅ | ❌ | +| Realtime (Experimental) | ❌ | ✅ | ❌ | > [!TIP] > In most scenarios, you will only need to add chat completion to your kernel, but to support multi-modal AI, you can add any of the above services to your kernel. ## Next steps + To learn more about each of the services, please refer to the specific articles for each service type. In each of the articles we provide sample code for adding the service to the kernel across multiple AI service providers. > [!div class="nextstepaction"] -> [Learn about chat completion](./chat-completion/index.md) \ No newline at end of file +> [Learn about chat completion](./chat-completion/index.md) diff --git a/semantic-kernel/concepts/ai-services/realtime.md b/semantic-kernel/concepts/ai-services/realtime.md new file mode 100644 index 00000000..4635a42f --- /dev/null +++ b/semantic-kernel/concepts/ai-services/realtime.md @@ -0,0 +1,88 @@ +--- +title: Realtime AI Integrations for Semantic Kernel +description: Learn about realtime AI integrations available in Semantic Kernel. +author: eavanvalkenburg +ms.topic: conceptual +ms.author: edvan +ms.date: 02/26/2025 +ms.service: semantic-kernel +--- + +# Realtime API integrations for Semantic Kernel + +The first realtime API integration for Semantic Kernel has been added, it is currently only available in Python and considered experimental. This is because the underlying services are still being developed and are subject to changes. + +## Realtime Client abstraction + +To support different realtime api's from different vendors, using different protocols, a new client abstraction has been added to the kernel. This client is used to connect to the realtime service and send and receive messages. +The client is responsible for handling the connection to the service, sending messages, and receiving messages. The client is also responsible for handling any errors that occur during the connection or message sending/receiving process. + +### Realtime API + +Any realtime client consists of the following methods: + +| Method | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------------ | +| `create_session` | Creates a new session | +| `update_session` | Updates an existing session | +| `delete_session` | Deletes an existing session | +| `receive` | This is a asynchronous generator method that listens for messages from the service and yields them as they arrive. | +| `send` | Sends a message to the service | + +## Python implementations + +The python version of semantic kernel currently supports the following realtime clients: + +| Client | Protocol | Description | +| ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OpenAI | Websocket | The OpenAI Realtime API is a websocket based api that allows you to send and receive messages in realtime, this connector uses the OpenAI Python package to connect and receive and send messages. | +| OpenAI | WebRTC | The OpenAI Realtime API is a WebRTC based api that allows you to send and receive messages in realtime, it needs a webRTC compatible audio track at session creation time. | +| Azure | Websocket | The Azure Realtime API is a websocket based api that allows you to send and receive messages in realtime, this uses the same package as the OpenAI websocket connector. | + +## Getting started + +To get started with the Realtime API, you need to install the `semantic-kernel` package with the `realtime` extra. + +```bash +pip install semantic-kernel[realtime] +``` + +Then you can create a kernel and add the realtime client to it. + +```python +from semantic_kernel.connectors.ai.open_ai import ( + AzureRealtimeWebsocket, + ListenEvents, + OpenAIRealtimeExecutionSettings, +) +from semantic_kernel.contents import RealtimeAudioEvent, RealtimeTextEvent + +# this will use environment variables to get the api key, endpoint, api version and deployment name. +realtime_client = AzureRealtimeWebsocket() +settings = OpenAIRealtimeExecutionSettings() +async with realtime_client(settings=settings, create_response=True): + async for event in realtime_client.receive(): + match event: + # receiving a piece of audio + case RealtimeAudioEvent(): + await audio_player.add_audio(event.audio) + # receiving a piece of audio transcript + case RealtimeTextEvent(): + # the model returns both audio and transcript of the audio, which we will print + print(event.text.text, end="") + case _: + # OpenAI Specific events + if event.service_type == ListenEvents.SESSION_UPDATED: + print("Session updated") + if event.service_type == ListenEvents.RESPONSE_CREATED: + print("\nMosscap (transcript): ", end="") +``` + +There are two important things to note, the first is that the `realtime_client` is an async context manager, this means that you can use it in an async function and use `async with` to create the session. +The second is that the `receive` method is an async generator, this means that you can use it in a for loop to receive messages as they arrive. + +In this simple example, we are passing the audio to a unspecified `audio_player` object, and printing the transcript as it arrives. + +There is also a `audio_output_callback` parameter on the client creation or on the `receive` method, this callback will be called first, and leads to smoother playback compared to the above example. + +See the samples in our repo [link to follow]. From 2891764d605c14bafbc740d451fa962a19a2e9f8 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 26 Feb 2025 16:48:03 +0100 Subject: [PATCH 38/70] extra info in table --- semantic-kernel/concepts/ai-services/realtime.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/semantic-kernel/concepts/ai-services/realtime.md b/semantic-kernel/concepts/ai-services/realtime.md index 4635a42f..65eddf90 100644 --- a/semantic-kernel/concepts/ai-services/realtime.md +++ b/semantic-kernel/concepts/ai-services/realtime.md @@ -33,11 +33,11 @@ Any realtime client consists of the following methods: The python version of semantic kernel currently supports the following realtime clients: -| Client | Protocol | Description | -| ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| OpenAI | Websocket | The OpenAI Realtime API is a websocket based api that allows you to send and receive messages in realtime, this connector uses the OpenAI Python package to connect and receive and send messages. | -| OpenAI | WebRTC | The OpenAI Realtime API is a WebRTC based api that allows you to send and receive messages in realtime, it needs a webRTC compatible audio track at session creation time. | -| Azure | Websocket | The Azure Realtime API is a websocket based api that allows you to send and receive messages in realtime, this uses the same package as the OpenAI websocket connector. | +| Client | Protocol | Modalities | Function calling enabled | Description | +| ------ | --------- | ------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OpenAI | Websocket | Text & Audio | Yes | The OpenAI Realtime API is a websocket based api that allows you to send and receive messages in realtime, this connector uses the OpenAI Python package to connect and receive and send messages. | +| OpenAI | WebRTC | Text & Audio | Yes | The OpenAI Realtime API is a WebRTC based api that allows you to send and receive messages in realtime, it needs a webRTC compatible audio track at session creation time. | +| Azure | Websocket | Text & Audio | Yes | The Azure Realtime API is a websocket based api that allows you to send and receive messages in realtime, this uses the same package as the OpenAI websocket connector. | ## Getting started From 02978dbcb1c964e492e212be19c8823091f65cab Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Wed, 26 Feb 2025 16:50:58 +0100 Subject: [PATCH 39/70] added link --- semantic-kernel/concepts/ai-services/index.md | 2 +- .../concepts/ai-services/integrations.md | 27 ++++++++++--------- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/semantic-kernel/concepts/ai-services/index.md b/semantic-kernel/concepts/ai-services/index.md index 2a2da7b2..9ce5d2fd 100644 --- a/semantic-kernel/concepts/ai-services/index.md +++ b/semantic-kernel/concepts/ai-services/index.md @@ -23,7 +23,7 @@ Within Semantic Kernel, there are interfaces for the most popular AI tasks. In t | Image-to-text (Experimental) | ✅ | ❌ | ❌ | | Text-to-audio (Experimental) | ✅ | ✅ | ❌ | | Audio-to-text (Experimental) | ✅ | ✅ | ❌ | -| Realtime (Experimental) | ❌ | ✅ | ❌ | +| [Realtime](./realtime.md) (Experimental) | ❌ | ✅ | ❌ | > [!TIP] > In most scenarios, you will only need to add chat completion to your kernel, but to support multi-modal AI, you can add any of the above services to your kernel. diff --git a/semantic-kernel/concepts/ai-services/integrations.md b/semantic-kernel/concepts/ai-services/integrations.md index a8d34ec5..d30a6984 100644 --- a/semantic-kernel/concepts/ai-services/integrations.md +++ b/semantic-kernel/concepts/ai-services/integrations.md @@ -18,21 +18,22 @@ With the available AI connectors, developers can easily build AI agents with swa ### AI Services -| Services | C# | Python | Java | Notes | -|-----------------------------------|:----:|:------:|:----:|-------| -| Text Generation | ✅ | ✅ | ✅ | Example: Text-Davinci-003 | -| Chat Completion | ✅ | ✅ | ✅ | Example: GPT4, Chat-GPT | -| Text Embeddings (Experimental) | ✅ | ✅ | ✅ | Example: Text-Embeddings-Ada-002 | -| Text to Image (Experimental) | ✅ | ✅ | ❌ | Example: Dall-E | -| Image to Text (Experimental) | ✅ | ❌ | ❌ | Example: Pix2Struct | -| Text to Audio (Experimental) | ✅ | ✅ | ❌ | Example: Text-to-speech | -| Audio to Text (Experimental) | ✅ | ✅ | ❌ | Example: Whisper | +| Services | C# | Python | Java | Notes | +| ------------------------------ | :---: | :----: | :---: | -------------------------------- | +| Text Generation | ✅ | ✅ | ✅ | Example: Text-Davinci-003 | +| Chat Completion | ✅ | ✅ | ✅ | Example: GPT4, Chat-GPT | +| Text Embeddings (Experimental) | ✅ | ✅ | ✅ | Example: Text-Embeddings-Ada-002 | +| Text to Image (Experimental) | ✅ | ✅ | ❌ | Example: Dall-E | +| Image to Text (Experimental) | ✅ | ❌ | ❌ | Example: Pix2Struct | +| Text to Audio (Experimental) | ✅ | ✅ | ❌ | Example: Text-to-speech | +| Audio to Text (Experimental) | ✅ | ✅ | ❌ | Example: Whisper | +| Realtime (Experimental) | ❌ | ✅ | ❌ | Example: gpt-4o-realtime-preview | ## Additional plugins If you want to extend the functionality of your AI agent, you can use plugins to integrate with other Microsoft services. Here are some of the plugins that are available for Semantic Kernel: -| Plugin | C# | Python | Java | Description | -| ---------- | :-: | :----: | :--: | ----------- | -| Logic Apps | ✅ | ✅ | ✅ | Build workflows within Logic Apps using its available connectors and import them as plugins in Semantic Kernel. [Learn more](../plugins/adding-logic-apps-as-plugins.md). | -| Azure Container Apps Dynamic Sessions | ✅ | ✅ | ❌ | With dynamic sessions, you can recreate the Code Interpreter experience from the Assistants API by effortlessly spinning up Python containers where AI agents can execute Python code. [Learn more](/azure/container-apps/sessions). | +| Plugin | C# | Python | Java | Description | +| ------------------------------------- | :---: | :----: | :---: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Logic Apps | ✅ | ✅ | ✅ | Build workflows within Logic Apps using its available connectors and import them as plugins in Semantic Kernel. [Learn more](../plugins/adding-logic-apps-as-plugins.md). | +| Azure Container Apps Dynamic Sessions | ✅ | ✅ | ❌ | With dynamic sessions, you can recreate the Code Interpreter experience from the Assistants API by effortlessly spinning up Python containers where AI agents can execute Python code. [Learn more](/azure/container-apps/sessions). | From 26fa90967da73031d994b08aa3f7b181a81ce3d4 Mon Sep 17 00:00:00 2001 From: Evan Mattson <35585003+moonbox3@users.noreply.github.com> Date: Fri, 28 Feb 2025 11:10:36 +0900 Subject: [PATCH 40/70] Update Agent Framework related doc and code samples. Add migration code for Python (#469) * Update OpenAI assistant related code samples. Add migration code for Python * improve migration guide * Update semantic-kernel/support/migration/openai-assistant-agent-migration-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update semantic-kernel/support/migration/openai-assistant-agent-migration-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Replace italics with code format. * update bookmarks * Update Python docs * Add dotnet migration guide. * update formatting in migration guide * fix headers * Fix header again * update guide to include rc * Small update to include new method get_response * Update important tags with some experimental (group chat) and some release candidate --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../Frameworks/agent/agent-architecture.md | 34 +- .../Frameworks/agent/agent-chat.md | 58 +- .../Frameworks/agent/agent-functions.md | 89 ++- .../Frameworks/agent/agent-streaming.md | 24 +- .../Frameworks/agent/agent-templates.md | 18 +- .../Frameworks/agent/assistant-agent.md | 95 ++- .../Frameworks/agent/chat-completion-agent.md | 79 ++- .../examples/example-agent-collaboration.md | 118 ++-- .../agent/examples/example-assistant-code.md | 181 +++-- .../examples/example-assistant-search.md | 152 +++-- .../agent/examples/example-chat-agent.md | 38 +- semantic-kernel/Frameworks/agent/index.md | 16 +- .../agent-framework-rc-migration-guide.md | 623 ++++++++++++++++++ semantic-kernel/support/migration/toc.yml | 4 +- 14 files changed, 1180 insertions(+), 349 deletions(-) create mode 100644 semantic-kernel/support/migration/agent-framework-rc-migration-guide.md diff --git a/semantic-kernel/Frameworks/agent/agent-architecture.md b/semantic-kernel/Frameworks/agent/agent-architecture.md index c3966fa8..b22c48ee 100644 --- a/semantic-kernel/Frameworks/agent/agent-architecture.md +++ b/semantic-kernel/Frameworks/agent/agent-architecture.md @@ -1,5 +1,5 @@ --- -title: Semantic Kernel Agent Architecture (Experimental) +title: Semantic Kernel Agent Architecture description: An overview of the architecture of the Semantic Kernel Agent Framework and how it aligns with core Semantic Kernel features. zone_pivot_groups: programming-languages author: crickman @@ -10,15 +10,15 @@ ms.service: semantic-kernel --- # An Overview of the Agent Architecture -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> Single-agent features, such as ChatCompletionAgent and OpenAIAssistantAgent, are in the release candidate stage. These features are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. However, agent chat patterns are still in the experimental stage. These patterns are under active development and may change significantly before advancing to the preview or release candidate stage. This article covers key concepts in the architecture of the Agent Framework, including foundational principles, design objectives, and strategic goals. ## Goals -The _Agent Framework_ was developed with the following key priorities in mind: +The `Agent Framework` was developed with the following key priorities in mind: - The _Semantic Kernel_ framework serves as the core foundation for implementing agent functionalities. - Multiple agents can collaborate within a single conversation, while integrating human input. @@ -28,7 +28,7 @@ The _Agent Framework_ was developed with the following key priorities in mind: ## Agent -The abstract _Agent_ class serves as the core abstraction for all types of agents, providing a foundational structure that can be extended to create more specialized agents. One key subclass is _Kernel Agent_, which establishes a direct association with a [_Kernel_](../../concepts/kernel.md) object. This relationship forms the basis for more specific agent implementations, such as the [_Chat Completion Agent_](./chat-completion-agent.md) and the [_OpenAI Assistant Agent_](./assistant-agent.md), both of which leverage the Kernel's capabilities to execute their respective functions. +The abstract `Agent` class serves as the core abstraction for all types of agents, providing a foundational structure that can be extended to create more specialized agents. One key subclass is _Kernel Agent_, which establishes a direct association with a [`Kernel`](../../concepts/kernel.md) object. This relationship forms the basis for more specific agent implementations, such as the [`ChatCompletionAgent`](./chat-completion-agent.md) and the [`OpenAIAssistantAgent`](./assistant-agent.md), both of which leverage the Kernel's capabilities to execute their respective functions. ::: zone pivot="programming-language-csharp" @@ -49,7 +49,7 @@ The abstract _Agent_ class serves as the core abstraction for all types of agent ::: zone-end -Agents can either be invoked directly to perform tasks or orchestrated within an [_Agent Chat_](./agent-chat.md), where multiple agents may collaborate or interact dynamically with user inputs. This flexible structure allows agents to adapt to various conversational or task-driven scenarios, providing developers with robust tools for building intelligent, multi-agent systems. +Agents can either be invoked directly to perform tasks or orchestrated within an [`AgentChat`](./agent-chat.md), where multiple agents may collaborate or interact dynamically with user inputs. This flexible structure allows agents to adapt to various conversational or task-driven scenarios, providing developers with robust tools for building intelligent, multi-agent systems. #### Deep Dive: @@ -64,7 +64,7 @@ Agents can either be invoked directly to perform tasks or orchestrated within an ## Agent Chat -The [_Agent Chat_](./agent-chat.md) class serves as the foundational component that enables agents of any type to engage in a specific conversation. This class provides the essential capabilities for managing agent interactions within a chat environment. Building on this, the [_Agent Group Chat_](./agent-chat.md#creating-an-agent-group-chat) class extends these capabilities by offering a stategy-based container, which allows multiple agents to collaborate across numerous interactions within the same conversation. +The [`AgentChat`](./agent-chat.md) class serves as the foundational component that enables agents of any type to engage in a specific conversation. This class provides the essential capabilities for managing agent interactions within a chat environment. Building on this, the [`AgentGroupChat`](./agent-chat.md#creating-an-agentgroupchat) class extends these capabilities by offering a stategy-based container, which allows multiple agents to collaborate across numerous interactions within the same conversation. This structure facilitates more complex, multi-agent scenarios where different agents can work together, share information, and dynamically respond to evolving conversations, making it an ideal solution for advanced use cases such as customer support, multi-faceted task management, or collaborative problem-solving environments. @@ -74,7 +74,7 @@ This structure facilitates more complex, multi-agent scenarios where different a ## Agent Channel -The _Agent Channel_ class enables agents of various types to participate in an [_Agent Chat_](./agent-chat.md). This functionality is completely hidden from users of the _Agent Framework_ and only needs to be considered by developers creating a custom [_Agent_](#agent). +The _Agent Channel_ class enables agents of various types to participate in an [`AgentChat`](./agent-chat.md). This functionality is completely hidden from users of the `Agent Framework` and only needs to be considered by developers creating a custom [`Agent`](#agent). ::: zone pivot="programming-language-csharp" @@ -96,14 +96,14 @@ The _Agent Channel_ class enables agents of various types to participate in an [ ## Agent Alignment with _Semantic Kernel_ Features -The _Agent Framework_ is built on the foundational concepts and features that many developers have come to know within the _Semantic Kernel_ ecosystem. These core principles serve as the building blocks for the Agent Framework’s design. By leveraging the familiar structure and capabilities of the _Semantic Kernel_, the Agent Framework extends its functionality to enable more advanced, autonomous agent behaviors, while maintaining consistency with the broader _Semantic Kernel_ architecture. This ensures a smooth transition for developers, allowing them to apply their existing knowledge to create intelligent, adaptable agents within the framework. +The `Agent Framework` is built on the foundational concepts and features that many developers have come to know within the _Semantic Kernel_ ecosystem. These core principles serve as the building blocks for the Agent Framework’s design. By leveraging the familiar structure and capabilities of the _Semantic Kernel_, the Agent Framework extends its functionality to enable more advanced, autonomous agent behaviors, while maintaining consistency with the broader _Semantic Kernel_ architecture. This ensures a smooth transition for developers, allowing them to apply their existing knowledge to create intelligent, adaptable agents within the framework. -### The _Kernel_ +### The `Kernel` -At the heart of the _Semantic Kernel_ ecosystem is the [_Kernel_](../../concepts/kernel.md), which serves as the core object that drives AI operations and interactions. To create any agent within this framework, a _Kernel instance_ is required as it provides the foundational context and capabilities for the agent’s functionality. The _Kernel_ acts as the engine for processing instructions, managing state, and invoking the necessary AI services that power the agent's behavior. +At the heart of the Semantic Kernel ecosystem is the [`Kernel`](../../concepts/kernel.md), which serves as the core object that drives AI operations and interactions. To create any agent within this framework, a _Kernel instance_ is required as it provides the foundational context and capabilities for the agent’s functionality. The `Kernel` acts as the engine for processing instructions, managing state, and invoking the necessary AI services that power the agent's behavior. -The [_Chat Completion Agent_](./chat-completion-agent.md) and [_OpenAI Assistant Agent_](./assistant-agent.md) articles provide specific details on how to create each type of agent. +The [`ChatCompletionAgent`](./chat-completion-agent.md) and [`OpenAIAssistantAgent`](./assistant-agent.md) articles provide specific details on how to create each type of agent. These resources offer step-by-step instructions and highlight the key configurations needed to tailor the agents to different conversational or task-based applications, demonstrating how the Kernel enables dynamic and intelligent agent behaviors across diverse use cases. #### Related API's: @@ -136,7 +136,7 @@ Plugins are a fundamental aspect of the _Semantic Kernel_, enabling developers t #### Example: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) #### Related API's: @@ -169,7 +169,7 @@ Plugins are a fundamental aspect of the _Semantic Kernel_, enabling developers t Agent messaging, including both input and response, is built upon the core content types of the _Semantic Kernel_, providing a unified structure for communication. This design choice simplifies the process of transitioning from traditional chat-completion patterns to more advanced agent-driven patterns in your application development. By leveraging familiar _Semantic Kernel_ content types, developers can seamlessly integrate agent capabilities into their applications without needing to overhaul existing systems. This streamlining ensures that as you evolve from basic conversational AI to more autonomous, task-oriented agents, the underlying framework remains consistent, making development faster and more efficient. -> Note: The [_OpenAI Assistant Agent_`_](./assistant-agent.md) introduced content types specific to its usage for _File References_ and _Content Annotation_: +> Note: The [`OpenAIAssistantAgent`](./assistant-agent.md) introduced content types specific to its usage for _File References_ and _Content Annotation_: #### Related API's: @@ -205,13 +205,13 @@ Agent messaging, including both input and response, is built upon the core conte ### [Templating](./agent-templates.md) -An agent's role is primarily shaped by the instructions it receives, which dictate its behavior and actions. Similar to invoking a _Kernel_ [prompt](../../concepts/prompts/index.md), an agent's instructions can include templated parameters—both values and functions—that are dynamically substituted during execution. This enables flexible, context-aware responses, allowing the agent to adjust its output based on real-time input. +An agent's role is primarily shaped by the instructions it receives, which dictate its behavior and actions. Similar to invoking a `Kernel` [prompt](../../concepts/prompts/index.md), an agent's instructions can include templated parameters—both values and functions—that are dynamically substituted during execution. This enables flexible, context-aware responses, allowing the agent to adjust its output based on real-time input. Additionally, an agent can be configured directly using a _Prompt Template Configuration_, providing developers with a structured and reusable way to define its behavior. This approach offers a powerful tool for standardizing and customizing agent instructions, ensuring consistency across various use cases while still maintaining dynamic adaptability. #### Example: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) #### Related API's: @@ -245,7 +245,7 @@ Additionally, an agent can be configured directly using a _Prompt Template Confi ### [Chat Completion](./chat-completion-agent.md) -The [_Chat Completion Agent_](./chat-completion-agent.md) is designed around any _Semantic Kernel_ [AI service](../../concepts/ai-services/chat-completion/index.md), offering a flexible and convenient persona encapsulation that can be seamlessly integrated into a wide range of applications. This agent allows developers to easily bring conversational AI capabilities into their systems without having to deal with complex implementation details. It mirrors the features and patterns found in the underlying [AI service](../../concepts/ai-services/chat-completion/index.md), ensuring that all functionalities—such as natural language processing, dialogue management, and contextual understanding—are fully supported within the [_Chat Completion Agent_](./chat-completion-agent.md), making it a powerful tool for building conversational interfaces. +The [`ChatCompletionAgent`](./chat-completion-agent.md) is designed around any _Semantic Kernel_ [AI service](../../concepts/ai-services/chat-completion/index.md), offering a flexible and convenient persona encapsulation that can be seamlessly integrated into a wide range of applications. This agent allows developers to easily bring conversational AI capabilities into their systems without having to deal with complex implementation details. It mirrors the features and patterns found in the underlying [AI service](../../concepts/ai-services/chat-completion/index.md), ensuring that all functionalities—such as natural language processing, dialogue management, and contextual understanding—are fully supported within the [`ChatCompletionAgent`](./chat-completion-agent.md), making it a powerful tool for building conversational interfaces. #### Related API's: diff --git a/semantic-kernel/Frameworks/agent/agent-chat.md b/semantic-kernel/Frameworks/agent/agent-chat.md index bf59e765..d0eb6c7c 100644 --- a/semantic-kernel/Frameworks/agent/agent-chat.md +++ b/semantic-kernel/Frameworks/agent/agent-chat.md @@ -8,10 +8,10 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# Exploring Agent Collaboration in _Agent Chat_ +# Exploring Agent Collaboration in `AgentChat` -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the experimental stage. Features at this stage are still under development and subject to change before advancing to the preview or release candidate stage. Detailed API documentation related to this discussion is available at: @@ -36,22 +36,22 @@ Detailed API documentation related to this discussion is available at: ::: zone-end -## What is _Agent Chat_? +## What is `AgentChat`? -_Agent Chat_ provides a framework that enables interaction between multiple agents, even if they are of different types. This makes it possible for a [_Chat Completion Agent_](./chat-completion-agent.md) and an [_OpenAI Assistant Agent_](./assistant-agent.md) to work together within the same conversation. _Agent Chat_ also defines entry points for initiating collaboration between agents, whether through multiple responses or a single agent response. +`AgentChat` provides a framework that enables interaction between multiple agents, even if they are of different types. This makes it possible for a [`ChatCompletionAgent`](./chat-completion-agent.md) and an [`OpenAIAssistantAgent`](./assistant-agent.md) to work together within the same conversation. `AgentChat` also defines entry points for initiating collaboration between agents, whether through multiple responses or a single agent response. -As an abstract class, _Agent Chat_ can be subclassed to support custom scenarios. +As an abstract class, `AgentChat` can be subclassed to support custom scenarios. -One such subclass, _Agent Group Chat_, offers a concrete implementation of _Agent Chat_, using a strategy-based approach to manage conversation dynamics. +One such subclass, `AgentGroupChat`, offers a concrete implementation of `AgentChat`, using a strategy-based approach to manage conversation dynamics. -## Creating an _Agent Group Chat_ +## Creating an `AgentGroupChat` -To create an _Agent Group Chat_, you may either specify the participating agents or create an empty chat and subsequently add agent participants. Configuring the _Chat-Settings_ and _Strategies_ is also performed during _Agent Group Chat_ initialization. These settings define how the conversation dynamics will function within the group. +To create an `AgentGroupChat`, you may either specify the participating agents or create an empty chat and subsequently add agent participants. Configuring the _Chat-Settings_ and _Strategies_ is also performed during `AgentGroupChat` initialization. These settings define how the conversation dynamics will function within the group. -> Note: The default _Chat-Settings_ result in a conversation that is limited to a single response. See [_Agent Chat_ Behavior](#defining-agent-group-chat-behavior) for details on configuring _Chat-Settings. +> Note: The default _Chat-Settings_ result in a conversation that is limited to a single response. See [`AgentChat` Behavior](#defining-agentgroupchat-behavior) for details on configuring _Chat-Settings. -#### Creating _Agent Group Chat_ with _Agents_: +#### Creating an `AgentGroupChat` with an `Agent`: ::: zone pivot="programming-language-csharp" ```csharp @@ -81,7 +81,7 @@ chat = AgentGroupChat(agents=[agent1, agent2]) ::: zone-end -#### Adding _Agents_ to a _Agent Group Chat_: +#### Adding an `Agent` to an `AgentGroupChat`: ::: zone pivot="programming-language-csharp" ```csharp @@ -120,13 +120,13 @@ chat.add_agent(agent=agent2) ::: zone-end -## Using _Agent Group Chat_ +## Using `AgentGroupChat` -_Agent Chat_ supports two modes of operation: _Single-Turn_ and _Multi-Turn_. In _single-turn_, a specific agent is designated to provide a response. In _multi-turn_, all agents in the conversation take turns responding until a termination criterion is met. In both modes, agents can collaborate by responding to one another to achieve a defined goal. +`AgentChat` supports two modes of operation: `Single-Turn` and `Multi-Turn`. In `single-turn`, a specific agent is designated to provide a response. In `multi-turn`, all agents in the conversation take turns responding until a termination criterion is met. In both modes, agents can collaborate by responding to one another to achieve a defined goal. ### Providing Input -Adding an input message to an _Agent Chat_ follows the same pattern as whit a _Chat History_ object. +Adding an input message to an `AgentChat` follows the same pattern as whit a `ChatHistory` object. ::: zone pivot="programming-language-csharp" ```csharp @@ -140,7 +140,7 @@ chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, "") ```python chat = AgentGroupChat() -await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content="")) +await chat.add_chat_message(message="") ``` ::: zone-end @@ -154,7 +154,7 @@ await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=" Note: The most recent message is provided first (descending order: newest to oldest). @@ -280,7 +280,7 @@ history = await chat.get_chat_messages() ::: zone-end -Since different agent types or configurations may maintain their own version of the conversation history, agent specific history is also available by specifing an agent. (For example: [_OpenAI Assistant_](./assistant-agent.md) versus [_Chat Completion Agent_](./chat-completion-agent.md).) +Since different agent types or configurations may maintain their own version of the conversation history, agent specific history is also available by specifing an agent. (For example: [`OpenAIAssistant`](./assistant-agent.md) versus [`ChatCompletionAgent`](./chat-completion-agent.md).) ::: zone pivot="programming-language-csharp" ```csharp @@ -319,7 +319,7 @@ history2 = await chat.get_chat_messages(agent=agent2) ::: zone-end -## Defining _Agent Group Chat_ Behavior +## Defining `AgentGroupChat` Behavior Collaboration among agents to solve complex tasks is a core agentic pattern. To use this pattern effectively, a system must be in place that not only determines which agent should respond during each turn but also assesses when the conversation has achieved its intended goal. This requires managing agent selection and establishing clear criteria for conversation termination, ensuring seamless cooperation between agents toward a solution. Both of these aspects are governed by the _Execution Settings_ property. @@ -329,7 +329,7 @@ The following sections, [Agent Selection](#agent-selection) and [Chat Terminatio In multi-turn invocation, agent selection is guided by a _Selection Strategy_. This strategy is defined by a base class that can be extended to implement custom behaviors tailored to specific needs. For convenience, two predefined concrete _Selection Strategies_ are also available, offering ready-to-use approaches for handling agent selection during conversations. -If known, an initial agent may be specified to always take the first turn. A history reducer may also be employed to limit token usage when using a strategy based on a _Kernel Function_. +If known, an initial agent may be specified to always take the first turn. A history reducer may also be employed to limit token usage when using a strategy based on a `KernelFunction`. ::: zone pivot="programming-language-csharp" @@ -414,14 +414,12 @@ REVIEWER_NAME = "Reviewer" WRITER_NAME = "Writer" agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, kernel=kernel, name=REVIEWER_NAME, instructions="", ) agent_writer = ChatCompletionAgent( - service_id=WRITER_NAME, kernel=kernel, name=WRITER_NAME, instructions="", @@ -472,7 +470,7 @@ chat = AgentGroupChat( In _multi-turn_ invocation, the _Termination Strategy_ dictates when the final turn takes place. This strategy ensures the conversation ends at the appropriate point. -This strategy is defined by a base class that can be extended to implement custom behaviors tailored to specific needs. For convenience, serveral predefined concrete _Selection Strategies_ are also available, offering ready-to-use approaches for defining termination criteria for an _Agent Chat_ conversations. +This strategy is defined by a base class that can be extended to implement custom behaviors tailored to specific needs. For convenience, serveral predefined concrete _Selection Strategies_ are also available, offering ready-to-use approaches for defining termination criteria for an `AgentChat` conversations. ::: zone pivot="programming-language-csharp" @@ -549,14 +547,12 @@ REVIEWER_NAME = "Reviewer" WRITER_NAME = "Writer" agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, kernel=kernel, name=REVIEWER_NAME, instructions="", ) agent_writer = ChatCompletionAgent( - service_id=WRITER_NAME, kernel=kernel, name=WRITER_NAME, instructions="", @@ -595,7 +591,7 @@ chat = AgentGroupChat( ### Resetting Chat Completion State -Regardless of whether _Agent Group Chat_ is invoked using the single-turn or multi-turn approach, the state of the _Agent Group Chat_ is updated to indicate it is _completed_ once the termination criteria is met. This ensures that the system recognizes when a conversation has fully concluded. To continue using an _Agent Group Chat_ instance after it has reached the _Completed_ state, this state must be reset to allow further interactions. Without resetting, additional interactions or agent responses will not be possible. +Regardless of whether `AgentGroupChat` is invoked using the single-turn or multi-turn approach, the state of the `AgentGroupChat` is updated to indicate it is _completed_ once the termination criteria is met. This ensures that the system recognizes when a conversation has fully concluded. To continue using an `AgentGroupChat` instance after it has reached the _Completed_ state, this state must be reset to allow further interactions. Without resetting, additional interactions or agent responses will not be possible. In the case of a multi-turn invocation that reaches the maximum turn limit, the system will cease agent invocation but will not mark the instance as _completed_. This allows for the possibility of extending the conversation without needing to reset the _Completion_ state. @@ -636,9 +632,9 @@ if chat.is_complete: ### Clear Full Conversation State -When done using an _Agent Chat_ where an [_OpenAI Assistant_](./assistant-agent.md) participated, it may be necessary to delete the remote _thread_ associated with the _assistant_. _Agent Chat_ supports resetting or clearing the entire conversation state, which includes deleting any remote _thread_ definition. This ensures that no residual conversation data remains linked to the assistant once the chat concludes. +When done using an `AgentChat` where an [`OpenAIAssistant`](./assistant-agent.md) participated, it may be necessary to delete the remote _thread_ associated with the _assistant_. `AgentChat` supports resetting or clearing the entire conversation state, which includes deleting any remote _thread_ definition. This ensures that no residual conversation data remains linked to the assistant once the chat concludes. -A full reset does not remove the _agents_ that had joined the _Agent Chat_ and leaves the _Agent Chat_ in a state where it can be reused. This allows for the continuation of interactions with the same agents without needing to reinitialize them, making future conversations more efficient. +A full reset does not remove the _agents_ that had joined the `AgentChat` and leaves the `AgentChat` in a state where it can be reused. This allows for the continuation of interactions with the same agents without needing to reinitialize them, making future conversations more efficient. ::: zone pivot="programming-language-csharp" ```csharp @@ -669,9 +665,9 @@ await chat.reset() ## How-To -For an end-to-end example for using _Agent Group Chat_ for _Agent_ collaboration, see: +For an end-to-end example for using `AgentGroupChat` for `Agent` collaboration, see: -- [How to Coordinate Agent Collaboration using _Agent Group Chat_](./examples/example-agent-collaboration.md) +- [How to Coordinate Agent Collaboration using `AgentGroupChat`](./examples/example-agent-collaboration.md) > [!div class="nextstepaction"] diff --git a/semantic-kernel/Frameworks/agent/agent-functions.md b/semantic-kernel/Frameworks/agent/agent-functions.md index 3ada7e4f..879703b6 100644 --- a/semantic-kernel/Frameworks/agent/agent-functions.md +++ b/semantic-kernel/Frameworks/agent/agent-functions.md @@ -1,5 +1,5 @@ --- -title: Configuring Agents with Semantic Kernel Plugins. (Experimental) +title: Configuring Agents with Semantic Kernel Plugins. description: Describes how to use Semantic Kernal plugins and function calling with agents. zone_pivot_groups: programming-languages author: crickman @@ -10,14 +10,14 @@ ms.service: semantic-kernel --- # Configuring Agents with Semantic Kernel Plugins -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## Functions and Plugins in Semantic Kernel -Function calling is a powerful tool that allows developers to add custom functionalities and expand the capabilities of AI applications. The _Semantic Kernel_ [Plugin](../../concepts/plugins/index.md) architecture offers a flexible framework to support [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md). For an _Agent_, integrating [Plugins](../../concepts/plugins/index.md) and [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is built on this foundational _Semantic Kernel_ feature. +Function calling is a powerful tool that allows developers to add custom functionalities and expand the capabilities of AI applications. The _Semantic Kernel_ [Plugin](../../concepts/plugins/index.md) architecture offers a flexible framework to support [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md). For an `Agent`, integrating [Plugins](../../concepts/plugins/index.md) and [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is built on this foundational _Semantic Kernel_ feature. -Once configured, an agent will choose when and how to call an available function, as it would in any usage outside of the _Agent Framework_. +Once configured, an agent will choose when and how to call an available function, as it would in any usage outside of the `Agent Framework`. ::: zone pivot="programming-language-csharp" @@ -46,11 +46,11 @@ Once configured, an agent will choose when and how to call an available function ## Adding Plugins to an Agent -Any [Plugin](../../concepts/plugins/index.md) available to an _Agent_ is managed within its respective _Kernel_ instance. This setup enables each _Agent_ to access distinct functionalities based on its specific role. +Any [Plugin](../../concepts/plugins/index.md) available to an `Agent` is managed within its respective `Kernel` instance. This setup enables each `Agent` to access distinct functionalities based on its specific role. -[Plugins](../../concepts/plugins/index.md) can be added to the _Kernel_ either before or after the _Agent_ is created. The process of initializing [Plugins](../../concepts/plugins/index.md) follows the same patterns used for any _Semantic Kernel_ implementation, allowing for consistency and ease of use in managing AI capabilities. +[Plugins](../../concepts/plugins/index.md) can be added to the `Kernel` either before or after the `Agent` is created. The process of initializing [Plugins](../../concepts/plugins/index.md) follows the same patterns used for any _Semantic Kernel_ implementation, allowing for consistency and ease of use in managing AI capabilities. -> Note: For a [_Chat Completion Agent_](./chat-completion-agent.md), the function calling mode must be explicitly enabled. [_OpenAI Assistant_](./assistant-agent.md) agent is always based on automatic function calling. +> Note: For a [`ChatCompletionAgent`](./chat-completion-agent.md), the function calling mode must be explicitly enabled. [`OpenAIAssistant`](./assistant-agent.md) agent is always based on automatic function calling. ::: zone pivot="programming-language-csharp" ```csharp @@ -85,18 +85,46 @@ ChatCompletionAgent CreateSpecificAgent(Kernel kernel, string credentials) ::: zone-end ::: zone pivot="programming-language-python" + +There are two ways to create a `ChatCompletionAgent` with plugins. + +#### Method 1: Specify Plugins via the Constructor + +You can directly pass a list of plugins to the constructor: + ```python +from semantic_kernel.agents import ChatCompletionAgent + +# Create the Chat Completion Agent instance by specifying a list of plugins +agent = ChatCompletionAgent( + service=AzureChatCompletion(), + instructions="", + plugins=[SamplePlugin()] +) +``` + +> [!TIP] +> By default, auto-function calling is enabled. To disable it, set the `function_choice_behavior` argument to `function_choice_behavior=FunctionChoiceBehavior.Auto(auto_invoke=False)` in the constructor. With this setting, plugins are still broadcast to the model, but they are not automatically invoked. If execution settings specify the same `service_id` or `ai_model_id` as the AI service configuration, the function calling behavior defined in the execution settings (via `KernelArguments`) will take precedence over the function choice behavior set in the constructor. + +#### Method 2: Configure the Kernel Manually + +If no kernel is provided via the constructor, one is automatically created during model validation. Any plugins passed in take precedence and are added to the kernel. For more fine-grained control over the kernel's state, follow these steps: + +```python +from semantic_kernel.agents import ChatCompletionAgent +from semantic_kernel.connectors.ai import FunctionChoiceBehavior +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings +from semantic_kernel.functions import KernelFunctionFromPrompt +from semantic_kernel.kernel import Kernel + # Create the instance of the Kernel kernel = Kernel() -# Define the service ID -service_id = "" - # Add the chat completion service to the Kernel -kernel.add_service(AzureChatCompletion(service_id=service_id)) +kernel.add_service(AzureChatCompletion()) -# Get the AI Service settings for the specified service_id -settings = kernel.get_prompt_execution_settings_from_service_id(service_id=service_id) +# Get the AI Service settings +settings = kernel.get_prompt_execution_settings_from_service_id() # Configure the function choice behavior to auto invoke kernel functions settings.function_choice_behavior = FunctionChoiceBehavior.Auto() @@ -106,13 +134,16 @@ kernel.add_plugin(SamplePlugin(), plugin_name="") # Create the agent agent = ChatCompletionAgent( - service_id=service_id, kernel=kernel, name=, instructions=, arguments=KernelArguments(settings=settings), ) ``` + +> [!TIP] +> If a `service_id` is not specified when adding a service to the kernel, it defaults to `default`. When configuring multiple AI services on the kernel, it’s recommended to differentiate them using the `service_id` argument. This allows you to retrieve execution settings for a specific `service_id` and tie those settings to the desired service. + ::: zone-end ::: zone pivot="programming-language-java" @@ -160,27 +191,35 @@ ChatCompletionAgent CreateSpecificAgent(Kernel kernel) ::: zone pivot="programming-language-python" ```python +from semantic_kernel.agents import ChatCompletionAgent +from semantic_kernel.connectors.ai import FunctionChoiceBehavior +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings +from semantic_kernel.functions import KernelFunctionFromPrompt +from semantic_kernel.kernel import Kernel + # Create the instance of the Kernel kernel = Kernel() -# Define the service ID -service_id = "" - # Add the chat completion service to the Kernel -kernel.add_service(AzureChatCompletion(service_id=service_id)) +kernel.add_service(AzureChatCompletion()) -# Get the AI Service settings for the specified service_id -settings = kernel.get_prompt_execution_settings_from_service_id(service_id=service_id) +# Create the AI Service settings +settings = AzureChatPromptExecutionSettings() # Configure the function choice behavior to auto invoke kernel functions settings.function_choice_behavior = FunctionChoiceBehavior.Auto() # Add the Plugin to the Kernel -kernel.add_plugin(SamplePlugin(), plugin_name="") +kernel.add_function( + plugin_name="", + function=KernelFunctionFromPrompt( + function_name="", + prompt="", + ) +) # Create the agent agent = ChatCompletionAgent( - service_id=service_id, kernel=kernel, name=, instructions=, @@ -198,14 +237,14 @@ agent = ChatCompletionAgent( ## Limitations for Agent Function Calling -When directly invoking a[_Chat Completion Agent_](./chat-completion-agent.md), all _Function Choice Behaviors_ are supported. However, when using an [_OpenAI Assistant_](./assistant-agent.md) or [_Agent Chat_](./agent-chat.md), only _Automatic_ [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is currently available. +When directly invoking a[`ChatCompletionAgent`](./chat-completion-agent.md), all _Function Choice Behaviors_ are supported. However, when using an [`OpenAIAssistant`](./assistant-agent.md) or [`AgentChat`](./agent-chat.md), only _Automatic_ [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is currently available. ## How-To For an end-to-end example for using function calling, see: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) > [!div class="nextstepaction"] diff --git a/semantic-kernel/Frameworks/agent/agent-streaming.md b/semantic-kernel/Frameworks/agent/agent-streaming.md index eac08b71..0c0c340b 100644 --- a/semantic-kernel/Frameworks/agent/agent-streaming.md +++ b/semantic-kernel/Frameworks/agent/agent-streaming.md @@ -1,5 +1,5 @@ --- -title: How to Stream Agent Responses. (Experimental) +title: How to Stream Agent Responses. description: Describes how to utilize streamed responses for agents and agent chat. zone_pivot_groups: programming-languages author: crickman @@ -10,8 +10,8 @@ ms.service: semantic-kernel --- # How to Stream Agent Responses -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## What is a Streamed Response? @@ -54,11 +54,11 @@ A streamed response delivers the message content in small, incremental chunks. T ## Streaming Agent Invocation -The _Agent Framework_ supports _streamed_ responses when using [_Agent Chat_](./agent-chat.md) or when directly invoking a [_Chat Completion Agent_](./chat-completion-agent.md) or [_OpenAI Assistant Agent_](./assistant-agent.md). In either mode, the framework delivers responses asynchronously as they are streamed. Alongside the streamed response, a consistent, non-streamed history is maintained to track the conversation. This ensures both real-time interaction and a reliable record of the conversation's flow. +The `Agent Framework` supports _streamed_ responses when using [`AgentChat`](./agent-chat.md) or when directly invoking a [`ChatCompletionAgent`](./chat-completion-agent.md) or [`OpenAIAssistantAgent`](./assistant-agent.md). In either mode, the framework delivers responses asynchronously as they are streamed. Alongside the streamed response, a consistent, non-streamed history is maintained to track the conversation. This ensures both real-time interaction and a reliable record of the conversation's flow. -### Streamed response from _Chat Completion Agent_ +### Streamed response from `ChatCompletionAgent` -When invoking a streamed response from a [_Chat Completion Agent_](./chat-completion-agent.md), the _Chat History_ is updated after the full response is received. Although the response is streamed incrementally, the history records only the complete message. This ensures that the _Chat History_ reflects fully formed responses for consistency. +When invoking a streamed response from a [`ChatCompletionAgent`](./chat-completion-agent.md), the `ChatHistory` is updated after the full response is received. Although the response is streamed incrementally, the history records only the complete message. This ensures that the `ChatHistory` reflects fully formed responses for consistency. ::: zone pivot="programming-language-csharp" ```csharp @@ -104,9 +104,9 @@ async for response in agent.invoke_stream(chat) ::: zone-end -### Streamed response from _OpenAI Assistant Agent_ +### Streamed response from `OpenAIAssistantAgent` -When invoking a streamed response from an [_OpenAI Assistant Agent_](./assistant-agent.md), an optional _Chat History_ can be provided to capture the complete messages for further analysis if needed. Since the assistant maintains the conversation state as a remote thread, capturing these messages is not always necessary. The decision to store and analyze the full response depends on the specific requirements of the interaction. +When invoking a streamed response from an [`OpenAIAssistantAgent`](./assistant-agent.md), an optional `ChatHistory` can be provided to capture the complete messages for further analysis if needed. Since the assistant maintains the conversation state as a remote thread, capturing these messages is not always necessary. The decision to store and analyze the full response depends on the specific requirements of the interaction. ::: zone pivot="programming-language-csharp" ```csharp @@ -139,7 +139,7 @@ agent = OpenAIAssistantAgent(...) thread_id = await agent.create_thread() # Add user message to the conversation -await agent.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content="")) +await agent.add_chat_message(message="") # Generate the streamed agent response(s) async for response in agent.invoke_stream(thread_id=thread_id): @@ -154,9 +154,9 @@ async for response in agent.invoke_stream(thread_id=thread_id): ::: zone-end -## Streaming with _Agent Chat_ +## Streaming with `AgentChat` -When using [_Agent Chat_](./agent-chat.md), the full conversation history is always preserved and can be accessed directly through the [_Agent Chat_](./agent-chat.md) instance. Therefore, the key difference between streamed and non-streamed invocations lies in the delivery method and the resulting content type. In both cases, users can still access the complete history, but streamed responses provide real-time updates as the conversation progresses. This allows for greater flexibility in handling interactions, depending on the application's needs. +When using [`AgentChat`](./agent-chat.md), the full conversation history is always preserved and can be accessed directly through the [`AgentChat`](./agent-chat.md) instance. Therefore, the key difference between streamed and non-streamed invocations lies in the delivery method and the resulting content type. In both cases, users can still access the complete history, but streamed responses provide real-time updates as the conversation progresses. This allows for greater flexibility in handling interactions, depending on the application's needs. ::: zone pivot="programming-language-csharp" ```csharp @@ -202,6 +202,8 @@ chat = AgentGroupChat( termination_strategy=DefaultTerminationStrategy(maximum_iterations=10), ) +await chat.add_chat_message("") + # Invoke agents last_agent = None async for response in chat.invoke_stream(): diff --git a/semantic-kernel/Frameworks/agent/agent-templates.md b/semantic-kernel/Frameworks/agent/agent-templates.md index e972ea8a..35c851d4 100644 --- a/semantic-kernel/Frameworks/agent/agent-templates.md +++ b/semantic-kernel/Frameworks/agent/agent-templates.md @@ -1,5 +1,5 @@ --- -title: Create an Agent from a Semantic Kernel Template (Experimental) +title: Create an Agent from a Semantic Kernel Template description: Describes how to use a Semantic Kernel template to define an agent. zone_pivot_groups: programming-languages author: crickman @@ -10,8 +10,8 @@ ms.service: semantic-kernel --- # Create an Agent from a Semantic Kernel Template -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## Prompt Templates in Semantic Kernel @@ -95,7 +95,7 @@ agent = ChatCompletionAgent( #### OpenAI Assistant Agent -Templated instructions are especially powerful when working with an [_OpenAI Assistant Agent_](./assistant-agent.md). With this approach, a single assistant definition can be created and reused multiple times, each time with different parameter values tailored to specific tasks or contexts. This enables a more efficient setup, allowing the same assistant framework to handle a wide range of scenarios while maintaining consistency in its core behavior. +Templated instructions are especially powerful when working with an [`OpenAIAssistantAgent`](./assistant-agent.md). With this approach, a single assistant definition can be created and reused multiple times, each time with different parameter values tailored to specific tasks or contexts. This enables a more efficient setup, allowing the same assistant framework to handle a wide range of scenarios while maintaining consistency in its core behavior. ::: zone pivot="programming-language-csharp" ```csharp @@ -208,7 +208,7 @@ agent = ChatCompletionAgent( ### Overriding Template Values for Direct Invocation -When invoking an agent directly, without using [_Agent Chat_](./agent-chat.md), the agent's parameters can be overridden as needed. This allows for greater control and customization of the agent's behavior during specific tasks, enabling you to modify its instructions or settings on the fly to suit particular requirements. +When invoking an agent directly, without using [`AgentChat`](./agent-chat.md), the agent's parameters can be overridden as needed. This allows for greater control and customization of the agent's behavior during specific tasks, enabling you to modify its instructions or settings on the fly to suit particular requirements. ::: zone pivot="programming-language-csharp" ```csharp @@ -263,6 +263,12 @@ chat = ChatHistory() override_arguments = KernelArguments(topic="Cat", length="3") +# Two ways to get a response from the agent + +# Get the response which returns a ChatMessageContent directly +response = await agent.get_response(chat, arguments=override_arguments) + +# or use the invoke method to return an AsyncIterable of ChatMessageContent async for response in agent.invoke(chat, arguments=override_arguments): # process agent response(s)... ``` @@ -280,7 +286,7 @@ async for response in agent.invoke(chat, arguments=override_arguments): For an end-to-end example for creating an agent from a _pmompt-template_, see: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) > [!div class="nextstepaction"] diff --git a/semantic-kernel/Frameworks/agent/assistant-agent.md b/semantic-kernel/Frameworks/agent/assistant-agent.md index e4d36c81..17ee3199 100644 --- a/semantic-kernel/Frameworks/agent/assistant-agent.md +++ b/semantic-kernel/Frameworks/agent/assistant-agent.md @@ -1,5 +1,5 @@ --- -title: Exploring the Semantic Kernel OpenAI Assistant Agent (Experimental) +title: Exploring the Semantic Kernel OpenAI Assistant Agent description: An exploration of the definition, behaviors, and usage patterns for a `OpenAIAssistantAgent` zone_pivot_groups: programming-languages author: crickman @@ -8,10 +8,10 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# Exploring the _Semantic Kernel_ _OpenAI Assistant Agent_ +# Exploring the _Semantic Kernel_ `OpenAIAssistantAgent` -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. Detailed API documentation related to this discussion is available at: @@ -24,7 +24,6 @@ Detailed API documentation related to this discussion is available at: ::: zone pivot="programming-language-python" -- [`open_ai_assistant_base`](/python/api/semantic-kernel/semantic_kernel.agents.open_ai.open_ai_assistant_base) - [`azure_assistant_agent`](/python/api/semantic-kernel/semantic_kernel.agents.open_ai.azure_assistant_agent) - [`open_ai_assistant_agent`](/python/api/semantic-kernel/semantic_kernel.agents.open_ai.open_ai_assistant_agent) @@ -46,9 +45,9 @@ The _OpenAI Assistant API_ is a specialized interface designed for more advanced - [Assistant API in Azure](/azure/ai-services/openai/assistants-quickstart) -## Creating an _OpenAI Assistant Agent_ +## Creating an `OpenAIAssistantAgent` -Creating an _OpenAI Assistant_ requires invoking a remote service, which is handled asynchronously. To manage this, the _OpenAI Assistant Agent_ is instantiated through a static factory method, ensuring the process occurs in a non-blocking manner. This method abstracts the complexity of the asynchronous call, returning a promise or future once the assistant is fully initialized and ready for use. +Creating an `OpenAIAssistant` requires invoking a remote service, which is handled asynchronously. To manage this, the `OpenAIAssistantAgent` is instantiated through a static factory method, ensuring the process occurs in a non-blocking manner. This method abstracts the complexity of the asynchronous call, returning a promise or future once the assistant is fully initialized and ready for use. ::: zone pivot="programming-language-csharp" ```csharp @@ -66,20 +65,40 @@ OpenAIAssistantAgent agent = ::: zone pivot="programming-language-python" ```python -azure_agent = await AzureAssistantAgent.create( - kernel=kernel, - service_id=service_id, - name="", - instructions="" +from semantic_kernel.agents.open_ai import AzureAssistantAgent, OpenAIAssistantAgent + +# Set up the client and model using Azure OpenAI Resources +client, model = AzureAssistantAgent.setup_resources() + +# Define the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, ) # or -openai_agent = await OpenAIAssistantAgent.create( - kernel=kernel, - service_id=service_id, - name="", - instructions="" +# Set up the client and model using OpenAI Resources +client, model = OpenAIAssistantAgent.setup_resources() + +# Define the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the OpenAIAssistantAgent instance using the client and the assistant definition +agent = OpenAIAssistantAgent( + client=client, + definition=definition, ) ``` ::: zone-end @@ -91,9 +110,9 @@ openai_agent = await OpenAIAssistantAgent.create( ::: zone-end -## Retrieving an _OpenAI Assistant Agent_ +## Retrieving an `OpenAIAssistantAgent` -Once created, the identifier of the assistant may be access via its identifier. This identifier may be used to create an _OpenAI Assistant Agent_ from an existing assistant definition. +Once created, the identifier of the assistant may be access via its identifier. This identifier may be used to create an `OpenAIAssistantAgent` from an existing assistant definition. ::: zone pivot="programming-language-csharp" @@ -110,11 +129,29 @@ OpenAIAssistantAgent agent = ::: zone pivot="programming-language-python" ```python -agent = await OpenAIAssistantAgent.retrieve(id=agent_id, kernel=kernel) +# Using Azure OpenAI Resources -# or +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + name="", + instructions="", +) -agent = await AzureAssistantAgent.retrieve(id=agent_id, kernel=kernel) +# Store the assistant ID +assistant_id = definition.id + +# Retrieve the assistant definition from the server based on the assistant ID +new_asst_definition = await client.beta.assistants.retrieve(assistant_id) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=new_asst_definition, +) ``` ::: zone-end @@ -125,9 +162,9 @@ agent = await AzureAssistantAgent.retrieve(id=agent_id, kernel=kernel) ::: zone-end -## Using an _OpenAI Assistant Agent_ +## Using an `OpenAIAssistantAgent` -As with all aspects of the _Assistant API_, conversations are stored remotely. Each conversation is referred to as a _thread_ and identified by a unique `string` identifier. Interactions with your _OpenAI Assistant Agent_ are tied to this specific thread identifier which must be specified when calling the agent/ +As with all aspects of the _Assistant API_, conversations are stored remotely. Each conversation is referred to as a _thread_ and identified by a unique `string` identifier. Interactions with your `OpenAIAssistantAgent` are tied to this specific thread identifier which must be specified when calling the agent/ ::: zone pivot="programming-language-csharp" ```csharp @@ -181,7 +218,7 @@ await agent.delete_thread(thread_id) ::: zone-end -## Deleting an _OpenAI Assistant Agent_ +## Deleting an `OpenAIAssistantAgent` Since the assistant's definition is stored remotely, it supports the capability to self-delete. This enables the agent to be removed from the system when it is no longer needed. @@ -217,12 +254,12 @@ is_deleted = agent._is_deleted ## How-To -For an end-to-end example for a _OpenAI Assistant Agent_, see: +For an end-to-end example for a `OpenAIAssistantAgent`, see: -- [How-To: _OpenAI Assistant Agent_ Code Interpreter](./examples/example-assistant-code.md) -- [How-To: _OpenAI Assistant Agent_ File Search](./examples/example-assistant-search.md) +- [How-To: `OpenAIAssistantAgent` Code Interpreter](./examples/example-assistant-code.md) +- [How-To: `OpenAIAssistantAgent` File Search](./examples/example-assistant-search.md) > [!div class="nextstepaction"] -> [Agent Collaboration in _Agent Chat_](./agent-chat.md) +> [Agent Collaboration in `AgentChat`](./agent-chat.md) diff --git a/semantic-kernel/Frameworks/agent/chat-completion-agent.md b/semantic-kernel/Frameworks/agent/chat-completion-agent.md index b3e7a40d..d1044239 100644 --- a/semantic-kernel/Frameworks/agent/chat-completion-agent.md +++ b/semantic-kernel/Frameworks/agent/chat-completion-agent.md @@ -1,5 +1,5 @@ --- -title: Exploring the Semantic Kernel Chat Completion Agent (Experimental) +title: Exploring the Semantic Kernel Chat Completion Agent description: An exploration of the definition, behaviors, and usage patterns for a Chat Completion Agent zone_pivot_groups: programming-languages author: crickman @@ -10,8 +10,8 @@ ms.service: semantic-kernel --- # Exploring the _Semantic Kernel_ Chat Completion Agent -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. Detailed API documentation related to this discussion is available at: @@ -76,7 +76,7 @@ Onnx|[`Microsoft.SemanticKernel.Connectors.Onnx`](/dotnet/api/microsoft.semantic ## Creating a Chat Completion Agent -A _chat completion agent_ is fundamentally based on an [AI services](../../concepts/ai-services/index.md). As such, creating an _chat completion agent_ starts with creating a [_Kernel_](../../concepts/kernel.md) instance that contains one or more chat-completion services and then instantiating the agent with a reference to that [_Kernel_](../../concepts/kernel.md) instance. +A _chat completion agent_ is fundamentally based on an [AI services](../../concepts/ai-services/index.md). As such, creating an _chat completion agent_ starts with creating a [`Kernel`](../../concepts/kernel.md) instance that contains one or more chat-completion services and then instantiating the agent with a reference to that [`Kernel`](../../concepts/kernel.md) instance. ::: zone pivot="programming-language-csharp" ```csharp @@ -104,11 +104,10 @@ ChatCompletionAgent agent = kernel = Kernel() # Add the AzureChatCompletion AI Service to the Kernel -kernel.add_service(AzureChatCompletion(service_id="")) +kernel.add_service(AzureChatCompletion()) # Create the agent agent = ChatCompletionAgent( - service_id="agent", kernel=kernel, name="", instructions="", @@ -125,9 +124,9 @@ agent = ChatCompletionAgent( ## AI Service Selection -No different from using _Semantic Kernel_ [AI services](../../concepts/ai-services/index.md) directly, a _chat completion agent_ support the specification of a _service-selector_. A _service-selector_ indentifies which [AI service](../../concepts/ai-services/index.md) to target when the [_Kernel_](../../concepts/kernel.md) contains more than one. +No different from using _Semantic Kernel_ [AI services](../../concepts/ai-services/index.md) directly, a `ChatCompletionAgent` supports the specification of a _service-selector_. A _service-selector_ indentifies which [AI service](../../concepts/ai-services/index.md) to target when the [`Kernel`](../../concepts/kernel.md) contains more than one. -> Note: If multiple [AI services](../../concepts/ai-services/index.md) are present and no _service-selector_ is provided, the same _default_ logic is applied for the agent that you'd find when using an [AI services](../../concepts/ai-services/index.md) outside of the _Agent Framework_ +> Note: If multiple [AI services](../../concepts/ai-services/index.md) are present and no _service-selector_ is provided, the same _default_ logic is applied for the agent that you'd find when using an [AI services](../../concepts/ai-services/index.md) outside of the `Agent Framework` ::: zone pivot="programming-language-csharp" ```csharp @@ -157,18 +156,26 @@ ChatCompletionAgent agent = ::: zone pivot="programming-language-python" ```python +from semantic_kernel.connectors.ai.open_ai import ( + AzureChatCompletion, + AzureChatPromptExecutionSettings, +) + # Define the Kernel kernel = Kernel() # Add the AzureChatCompletion AI Service to the Kernel -kernel.add_service(AzureChatCompletion(service_id="")) +kernel.add_service(AzureChatCompletion(service_id="service1")) +kernel.add_service(AzureChatCompletion(service_id="service2")) + +settings = AzureChatPromptExecutionSettings(service_id="service2") # Create the agent agent = ChatCompletionAgent( - service_id="agent", kernel=kernel, name="", instructions="", + arguments=KernelArguments(settings=settings) ) ``` ::: zone-end @@ -179,11 +186,12 @@ agent = ChatCompletionAgent( ::: zone-end -## Conversing with _Chat Completion Agent_ - -Conversing with your _Chat Completion Agent_ is based on a _Chat History_ instance, no different from interacting with a _Chat Completion_ [AI service](../../concepts/ai-services/index.md). +## Conversing with `ChatCompletionAgent` ::: zone pivot="programming-language-csharp" + +Conversing with your `ChatCompletionAgent` is based on a `ChatHistory` instance, no different from interacting with a _Chat Completion_ [AI service](../../concepts/ai-services/index.md). + ```csharp // Define agent ChatCompletionAgent agent = ...; @@ -203,6 +211,11 @@ await foreach (ChatMessageContent response in agent.InvokeAsync(chat)) ::: zone-end ::: zone pivot="programming-language-python" + +There are multiple ways to converse with a `ChatCompletionAgent`. + +The easiest is to call and await `get_response`: + ```python # Define agent agent = ChatCompletionAgent(...) @@ -213,10 +226,44 @@ chat = ChatHistory() # Add the user message chat.add_message(ChatMessageContent(role=AuthorRole.USER, content=input)) +# Generate the agent response +response = await agent.get_response(chat) +# response is a `ChatMessageContent` object +``` +Otherwise, calling the `invoke` method returns an `AsyncIterable` of `ChatMessageContent`. + +```python +# Define agent +agent = ChatCompletionAgent(...) + +# Define the chat history +chat = ChatHistory() + +# Add the user message +chat.add_user_message(ChatMessageContent(role=AuthorRole.USER, content=input)) + # Generate the agent response(s) async for response in agent.invoke(chat): # process agent response(s) ``` + +The `ChatCompletionAgent` also supports streaming in which the `invoke_stream` method returns an `AsyncIterable` of `StreamingChatMessageContent`: + +```python +# Define agent +agent = ChatCompletionAgent(...) + +# Define the chat history +chat = ChatHistory() + +# Add the user message +chat.add_message(ChatMessageContent(role=AuthorRole.USER, content=input)) + +# Generate the agent response(s) +async for response in agent.invoke_stream(chat): + # process agent response(s) +``` + ::: zone-end ::: zone pivot="programming-language-java" @@ -228,10 +275,10 @@ async for response in agent.invoke(chat): #### How-To: -For an end-to-end example for a _Chat Completion Agent_, see: +For an end-to-end example for a `ChatCompletionAgent`, see: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) > [!div class="nextstepaction"] -> [Exploring _OpenAI Assistant Agent_](./assistant-agent.md) +> [Exploring `OpenAIAssistantAgent`](./assistant-agent.md) diff --git a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md index fc11bf27..d557c7fc 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md +++ b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md @@ -10,12 +10,12 @@ ms.service: semantic-kernel --- # How-To: Coordinate Agent Collaboration using Agent Group Chat -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the experimental stage. Features at this stage are still under development and subject to change before advancing to the preview or release candidate stage. ## Overview -In this sample, we will explore how to use _Agent Group Chat_ to coordinate collboration of two different agents working to review and rewrite user provided content. Each agent is assigned a distinct role: +In this sample, we will explore how to use `AgentGroupChat` to coordinate collboration of two different agents working to review and rewrite user provided content. Each agent is assigned a distinct role: - **Reviewer**: Reviews and provides direction to _Writer_. - **Writer**: Updates user content based on _Reviewer_ input. @@ -61,7 +61,7 @@ The project file (`.csproj`) should contain the following `PackageReference` def ``` -The _Agent Framework_ is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): +The `Agent Framework` is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): ```xml @@ -81,24 +81,21 @@ Start by installing the Semantic Kernel Python package. pip install semantic-kernel ``` +Next add the required imports. + ```python import asyncio import os -import copy +from semantic_kernel import Kernel from semantic_kernel.agents import AgentGroupChat, ChatCompletionAgent -from semantic_kernel.agents.strategies.selection.kernel_function_selection_strategy import ( +from semantic_kernel.agents.strategies import ( KernelFunctionSelectionStrategy, -) -from semantic_kernel.agents.strategies.termination.kernel_function_termination_strategy import ( KernelFunctionTerminationStrategy, ) -from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.functions.kernel_function_decorator import kernel_function -from semantic_kernel.functions.kernel_function_from_prompt import KernelFunctionFromPrompt -from semantic_kernel.kernel import Kernel +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion +from semantic_kernel.contents import ChatHistoryTruncationReducer +from semantic_kernel.functions import KernelFunctionFromPrompt ``` ::: zone-end @@ -108,13 +105,12 @@ from semantic_kernel.kernel import Kernel ::: zone-end - ## Configuration -This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_. - ::: zone pivot="programming-language-csharp" +This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_. + ```powershell # OpenAI dotnet user-secrets set "OpenAISettings:ApiKey" "" @@ -173,7 +169,7 @@ public class Settings ::: zone-end ::: zone pivot="programming-language-python" -The quickest way to get started with the proper configuration to run the sample code is to create a `.env` file at the root of your project (where your script is run). +The quickest way to get started with the proper configuration to run the sample code is to create a `.env` file at the root of your project (where your script is run). The sample requires that you have Azure OpenAI or OpenAI resources available. Configure the following settings in your `.env` file for either Azure OpenAI or OpenAI: @@ -197,21 +193,20 @@ Once configured, the respective AI service classes will pick up the required var ::: zone-end - ## Coding The coding process for this sample involves: 1. [Setup](#setup) - Initializing settings and the plug-in. -2. [_Agent_ Definition](#agent-definition) - Create the two _Chat Completion Agent_ instances (_Reviewer_ and _Writer_). -3. [_Chat_ Definition](#chat-definition) - Create the _Agent Group Chat_ and associated strategies. +2. [`Agent` Definition](#agent-definition) - Create the two `ChatCompletionAgent` instances (_Reviewer_ and _Writer_). +3. [_Chat_ Definition](#chat-definition) - Create the `AgentGroupChat` and associated strategies. 4. [The _Chat_ Loop](#the-chat-loop) - Write the loop that drives user / agent interaction. The full example code is provided in the [Final](#final) section. Refer to that section for the complete implementation. ### Setup -Prior to creating any _Chat Completion Agent_, the configuration settings, plugins, and _Kernel_ must be initialized. +Prior to creating any `ChatCompletionAgent`, the configuration settings, plugins, and `Kernel` must be initialized. ::: zone pivot="programming-language-csharp" @@ -252,14 +247,12 @@ kernel = Kernel() ::: zone-end ::: zone pivot="programming-language-java" - > Agents are currently unavailable in Java. - ::: zone-end -Let's also create a second _Kernel_ instance via _cloning_ and add a plug-in that will allow the reivew to place updated content on the clip-board. - ::: zone pivot="programming-language-csharp" +Let's also create a second `Kernel` instance via _cloning_ and add a plug-in that will allow the reivew to place updated content on the clip-board. + ```csharp Kernel toolKernel = kernel.Clone(); toolKernel.Plugins.AddFromType(); @@ -313,7 +306,7 @@ private sealed class ClipboardAccess ### Agent Definition ::: zone pivot="programming-language-csharp" -Let's declare the agent names as `const` so they might be referenced in _Agent Group Chat_ strategies: +Let's declare the agent names as `const` so they might be referenced in `AgentGroupChat` strategies: ```csharp const string ReviewerName = "Reviewer"; @@ -374,7 +367,6 @@ ChatCompletionAgent agentReviewer = ::: zone pivot="programming-language-python" ```python agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, kernel=kernel, name=REVIEWER_NAME, instructions=""" @@ -425,7 +417,6 @@ ChatCompletionAgent agentWriter = The _Writer_ agent is similiar. It is given a single-purpose task, follow direction and rewrite the content. ```python agent_writer = ChatCompletionAgent( - service_id=WRITER_NAME, kernel=kernel, name=WRITER_NAME, instructions=""" @@ -446,9 +437,9 @@ Your sole responsibility is to rewrite content according to review suggestions. ### Chat Definition -Defining the _Agent Group Chat_ requires considering the strategies for selecting the _Agent_ turn and determining when to exit the _Chat_ loop. For both of these considerations, we will define a _Kernel Prompt Function_. +Defining the `AgentGroupChat` requires considering the strategies for selecting the `Agent` turn and determining when to exit the _Chat_ loop. For both of these considerations, we will define a _Kernel Prompt Function_. -The first to reason over _Agent_ selection: +The first to reason over `Agent` selection: ::: zone pivot="programming-language-csharp" @@ -481,8 +472,8 @@ KernelFunction selectionFunction = ::: zone pivot="programming-language-python" ```python selection_function = KernelFunctionFromPrompt( - function_name="selection", - prompt=f""" + function_name="selection", + prompt=f""" Examine the provided RESPONSE and choose the next participant. State only the name of the chosen participant without explanation. Never choose the participant named in the RESPONSE. @@ -499,7 +490,7 @@ Rules: RESPONSE: {{{{$lastmessage}}}} """ - ) +) ``` ::: zone-end @@ -532,11 +523,11 @@ KernelFunction terminationFunction = ::: zone pivot="programming-language-python" ```python - termination_keyword = "yes" +termination_keyword = "yes" - termination_function = KernelFunctionFromPrompt( - function_name="termination", - prompt=f""" +termination_function = KernelFunctionFromPrompt( + function_name="termination", + prompt=f""" Examine the RESPONSE and determine whether the content has been deemed satisfactory. If the content is satisfactory, respond with a single word without explanation: {termination_keyword}. If specific suggestions are being provided, it is not satisfactory. @@ -545,7 +536,7 @@ If no correction is suggested, it is satisfactory. RESPONSE: {{{{$lastmessage}}}} """ - ) +) ``` ::: zone-end @@ -575,7 +566,7 @@ history_reducer = ChatHistoryTruncationReducer(target_count=1) ::: zone-end -Finally we are ready to bring everything together in our _Agent Group Chat_ definition. +Finally we are ready to bring everything together in our `AgentGroupChat` definition. ::: zone pivot="programming-language-csharp" @@ -668,9 +659,9 @@ The `lastmessage` `history_variable_name` corresponds with the `KernelFunctionSe ### The _Chat_ Loop -At last, we are able to coordinate the interaction between the user and the _Agent Group Chat_. Start by creating creating an empty loop. +At last, we are able to coordinate the interaction between the user and the `AgentGroupChat`. Start by creating creating an empty loop. -> Note: Unlike the other examples, no external history or _thread_ is managed. _Agent Group Chat_ manages the conversation history internally. +> Note: Unlike the other examples, no external history or _thread_ is managed. `AgentGroupChat` manages the conversation history internally. ::: zone pivot="programming-language-csharp" ```csharp @@ -700,9 +691,9 @@ while not is_complete: Now let's capture user input within the previous loop. In this case: - Empty input will be ignored - The term `EXIT` will signal that the conversation is completed -- The term `RESET` will clear the _Agent Group Chat_ history +- The term `RESET` will clear the `AgentGroupChat` history - Any term starting with `@` will be treated as a file-path whose content will be provided as input -- Valid input will be added to the _Agent Group Chat_ as a _User_ message. +- Valid input will be added to the `AgentGroupChat` as a _User_ message. ```csharp Console.WriteLine(); @@ -753,9 +744,9 @@ chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, input)); Now let's capture user input within the previous loop. In this case: - Empty input will be ignored. - The term `exit` will signal that the conversation is complete. -- The term `reset` will clear the _Agent Group Chat_ history. +- The term `reset` will clear the `AgentGroupChat` history. - Any term starting with `@` will be treated as a file-path whose content will be provided as input. -- Valid input will be added to the _Agent Group Chat_ as a _User_ message. +- Valid input will be added to the `AgentGroupChat` as a _User_ message. The operation logic inside the while loop looks like: @@ -790,7 +781,7 @@ if user_input.startswith("@") and len(user_input) > 1: continue # Add the current user_input to the chat -await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=user_input)) +await chat.add_chat_message(message=user_input) ``` ::: zone-end @@ -800,7 +791,7 @@ await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=use ::: zone-end -To initate the _Agent_ collaboration in response to user input and display the _Agent_ responses, invoke the _Agent Group Chat_; however, first be sure to reset the _Completion_ state from any prior invocation. +To initate the `Agent` collaboration in response to user input and display the `Agent` responses, invoke the `AgentGroupChat`; however, first be sure to reset the _Completion_ state from any prior invocation. > Note: Service failures are being caught and displayed to avoid crashing the conversation loop. @@ -853,7 +844,6 @@ chat.is_complete = False ::: zone-end - ## Final ::: zone pivot="programming-language-csharp" @@ -1148,24 +1138,20 @@ import os from semantic_kernel import Kernel from semantic_kernel.agents import AgentGroupChat, ChatCompletionAgent -from semantic_kernel.agents.strategies.selection.kernel_function_selection_strategy import ( +from semantic_kernel.agents.strategies import ( KernelFunctionSelectionStrategy, -) -from semantic_kernel.agents.strategies.termination.kernel_function_termination_strategy import ( KernelFunctionTerminationStrategy, ) -from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.history_reducer.chat_history_truncation_reducer import ChatHistoryTruncationReducer -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.functions.kernel_function_from_prompt import KernelFunctionFromPrompt - -################################################################### -# The following sample demonstrates how to create a simple, # -# agent group chat that utilizes a Reviewer Chat Completion # -# Agent along with a Writer Chat Completion Agent to # -# complete a user's task. # -################################################################### +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion +from semantic_kernel.contents import ChatHistoryTruncationReducer +from semantic_kernel.functions import KernelFunctionFromPrompt + +""" +The following sample demonstrates how to create a simple, +agent group chat that utilizes a Reviewer Chat Completion +Agent along with a Writer Chat Completion Agent to +complete a user's task. +""" # Define agent names REVIEWER_NAME = "Reviewer" @@ -1185,7 +1171,6 @@ async def main(): # Create ChatCompletionAgents using the same kernel. agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, kernel=kernel, name=REVIEWER_NAME, instructions=""" @@ -1202,7 +1187,6 @@ RULES: ) agent_writer = ChatCompletionAgent( - service_id=WRITER_NAME, kernel=kernel, name=WRITER_NAME, instructions=""" @@ -1312,7 +1296,7 @@ RESPONSE: continue # Add the current user_input to the chat - await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=user_input)) + await chat.add_chat_message(message=user_input) try: async for response in chat.invoke(): diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index f8fab56a..be6fdc4d 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -1,5 +1,5 @@ --- -title: How-To: _OpenAI Assistant Agent_ Code Interpreter (Experimental) +title: How-To: `OpenAIAssistantAgent` Code Interpreter description: A step-by-step walk-through of defining and utilizing the code-interpreter tool of an OpenAI Assistant Agent. zone_pivot_groups: programming-languages author: crickman @@ -8,14 +8,14 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# How-To: _OpenAI Assistant Agent_ Code Interpreter +# How-To: `OpenAIAssistantAgent` Code Interpreter -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## Overview -In this sample, we will explore how to use the _code-interpreter_ tool of an [_OpenAI Assistant Agent_](../assistant-agent.md) to complete data-analysis tasks. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will generate both image and text responses. This will demonstrate the versatility of this tool in performing quantitative analysis. +In this sample, we will explore how to use the _code-interpreter_ tool of an [`OpenAIAssistantAgent`](../assistant-agent.md) to complete data-analysis tasks. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will generate both image and text responses. This will demonstrate the versatility of this tool in performing quantitative analysis. Streaming will be used to deliver the agent's responses. This will provide real-time updates as the task progresses. @@ -56,7 +56,7 @@ The project file (`.csproj`) should contain the following `PackageReference` def ``` -The _Agent Framework_ is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): +The `Agent Framework` is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): ```xml @@ -79,29 +79,27 @@ Additionally, copy the `PopulationByAdmin1.csv` and `PopulationByCountry.csv` da ::: zone-end ::: zone pivot="programming-language-python" + Start by creating a folder that will hold your script (`.py` file) and the sample resources. Include the following imports at the top of your `.py` file: ```python import asyncio import os -from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.streaming_file_reference_content import StreamingFileReferenceContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.kernel import Kernel +from semantic_kernel.agents.open_ai import AzureAssistantAgent +from semantic_kernel.contents import StreamingFileReferenceContent ``` Additionally, copy the `PopulationByAdmin1.csv` and `PopulationByCountry.csv` data files from the [_Semantic Kernel_ `learn_resources/resources` directory](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/learn_resources/resources). Add these files to your working directory. ::: zone-end + ::: zone pivot="programming-language-java" > Agents are currently unavailable in Java. ::: zone-end - ## Configuration This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_. @@ -164,6 +162,7 @@ public class Settings } ``` ::: zone-end + ::: zone pivot="programming-language-python" The quickest way to get started with the proper configuration to run the sample code is to create a `.env` file at the root of your project (where your script is run). @@ -198,17 +197,17 @@ Once configured, the respective AI service classes will pick up the required var The coding process for this sample involves: 1. [Setup](#setup) - Initializing settings and the plug-in. -2. [Agent Definition](#agent-definition) - Create the _OpenAI_Assistant_Agent_ with templatized instructions and plug-in. +2. [Agent Definition](#agent-definition) - Create the _OpenAI_Assistant`Agent` with templatized instructions and plug-in. 3. [The _Chat_ Loop](#the-chat-loop) - Write the loop that drives user / agent interaction. The full example code is provided in the [Final](#final) section. Refer to that section for the complete implementation. ### Setup -Prior to creating an _OpenAI Assistant Agent_, ensure the configuration settings are available and prepare the file resources. - ::: zone pivot="programming-language-csharp" +Prior to creating an `OpenAIAssistantAgent`, ensure the configuration settings are available and prepare the file resources. + Instantiate the `Settings` class referenced in the previous [Configuration](#configuration) section. Use the settings to also create an `OpenAIClientProvider` that will be used for the [Agent Definition](#agent-definition) as well as file-upload. ```csharp @@ -239,11 +238,13 @@ OpenAIFile fileDataCountryList = await fileClient.UploadFileAsync("PopulationByC ::: zone pivot="programming-language-python" +Prior to creating an `AzureAssistantAgent` or an `OpenAIAssistantAgent`, ensure the configuration settings are available and prepare the file resources. + > [!TIP] > You may need to adjust the file paths depending upon where your files are located. ```python -# Let's form the file paths that we will later pass to the assistant +# Let's form the file paths that we will use as part of file upload csv_file_path_1 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), "resources", @@ -256,7 +257,39 @@ csv_file_path_2 = os.path.join( "PopulationByCountry.csv", ) ``` -You may need to modify the path creation code based on the storage location of your CSV files. + +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Upload the files to the client +file_ids: list[str] = [] +for path in [csv_file_path_1, csv_file_path_2]: + with open(path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + file_ids.append(file.id) + +# Get the code interpreter tool and resources +code_interpreter_tools, code_interpreter_tool_resources = AzureAssistantAgent.configure_code_interpreter_tool( + file_ids=file_ids +) + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions=""" + Analyze the available data to provide an answer to the user's question. + Always format response using markdown. + Always include a numerical index that starts at 1 for any lists or tables. + Always sort lists in ascending order. + """, + name="SampleAssistantAgent", + tools=code_interpreter_tools, + tool_resources=code_interpreter_tool_resources, +) +``` + +We first set up the Azure OpenAI resources to obtain the client and model. Next, we upload the CSV files from the specified paths using the client's Files API. We then configure the `code_interpreter_tool` using the uploaded file IDs, which are linked to the assistant upon creation along with the model, instructions, and name. ::: zone-end @@ -270,7 +303,7 @@ You may need to modify the path creation code based on the storage location of y ::: zone pivot="programming-language-csharp" -We are now ready to instantiate an _OpenAI Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. +We are now ready to instantiate an `OpenAIAssistantAgent`. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. ```csharp Console.WriteLine("Defining agent..."); @@ -296,21 +329,13 @@ OpenAIAssistantAgent agent = ::: zone pivot="programming-language-python" -We are now ready to instantiate an _Azure Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. +We are now ready to instantiate an `AzureAssistantAgent`. The agent is configured with the client and the assistant definition. ```python -agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", - instructions=""" - Analyze the available data to provide an answer to the user's question. - Always format response using markdown. - Always include a numerical index that starts at 1 for any lists or tables. - Always sort lists in ascending order. - """, - enable_code_interpreter=True, - code_interpreter_filenames=[csv_file_path_1, csv_file_path_2], +# Create the agent using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, ) ``` ::: zone-end @@ -323,7 +348,7 @@ agent = await AzureAssistantAgent.create( ### The _Chat_ Loop -At last, we are able to coordinate the interaction between the user and the _Agent_. Start by creating an _Assistant Thread_ to maintain the conversation state and creating an empty loop. +At last, we are able to coordinate the interaction between the user and the `Agent`. Start by creating an _Assistant Thread_ to maintain the conversation state and creating an empty loop. Let's also ensure the resources are removed at the end of execution to minimize unnecessary charges. @@ -369,11 +394,10 @@ try: while not is_complete: # agent interaction logic here finally: - print("Cleaning up resources...") - if agent is not None: - [await agent.delete_file(file_id) for file_id in agent.code_interpreter_file_ids] - await agent.delete_thread(thread_id) - await agent.delete() + print("\nCleaning up resources...") + [await client.files.delete(file_id) for file_id in file_ids] + await client.beta.threads.delete(thread.id) + await client.beta.assistants.delete(agent.id) ``` ::: zone-end @@ -426,7 +450,7 @@ await agent.add_chat_message(thread_id=thread_id, message=ChatMessageContent(rol ::: zone-end -Before invoking the _Agent_ response, let's add some helper methods to download any files that may be produced by the _Agent_. +Before invoking the `Agent` response, let's add some helper methods to download any files that may be produced by the `Agent`. ::: zone pivot="programming-language-csharp" Here we're place file content in the system defined temporary directory and then launching the system defined viewer application. @@ -513,7 +537,7 @@ async def download_response_image(agent, file_ids: list[str]): ::: zone-end -To generate an _Agent_ response to user input, invoke the agent by specifying the _Assistant Thread_. In this example, we choose a streamed response and capture any generated _File References_ for download and review at the end of the response cycle. It's important to note that generated code is identified by the presence of a _Metadata_ key in the response message, distinguishing it from the conversational reply. +To generate an `Agent` response to user input, invoke the agent by specifying the _Assistant Thread_. In this example, we choose a streamed response and capture any generated _File References_ for download and review at the end of the response cycle. It's important to note that generated code is identified by the presence of a _Metadata_ key in the response message, distinguishing it from the conversational reply. ::: zone pivot="programming-language-csharp" ```csharp @@ -743,19 +767,16 @@ import asyncio import logging import os -from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.streaming_file_reference_content import StreamingFileReferenceContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.kernel import Kernel +from semantic_kernel.agents.open_ai import AzureAssistantAgent +from semantic_kernel.contents import StreamingFileReferenceContent logging.basicConfig(level=logging.ERROR) -################################################################### -# The following sample demonstrates how to create a simple, # -# OpenAI assistant agent that utilizes the code interpreter # -# to analyze uploaded files. # -################################################################### +""" +The following sample demonstrates how to create a simple, +OpenAI assistant agent that utilizes the code interpreter +to analyze uploaded files. +""" # Let's form the file paths that we will later pass to the assistant csv_file_path_1 = os.path.join( @@ -802,22 +823,43 @@ async def download_response_image(agent: AzureAssistantAgent, file_ids: list[str async def main(): - agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", + # Create the client using Azure OpenAI resources and configuration + client, model = AzureAssistantAgent.setup_resources() + + # Upload the files to the client + file_ids: list[str] = [] + for path in [csv_file_path_1, csv_file_path_2]: + with open(path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + file_ids.append(file.id) + + # Get the code interpreter tool and resources + code_interpreter_tools, code_interpreter_tool_resources = AzureAssistantAgent.configure_code_interpreter_tool( + file_ids=file_ids + ) + + # Create the assistant definition + definition = await client.beta.assistants.create( + model=model, instructions=""" - Analyze the available data to provide an answer to the user's question. - Always format response using markdown. - Always include a numerical index that starts at 1 for any lists or tables. - Always sort lists in ascending order. - """, - enable_code_interpreter=True, - code_interpreter_filenames=[csv_file_path_1, csv_file_path_2], + Analyze the available data to provide an answer to the user's question. + Always format response using markdown. + Always include a numerical index that starts at 1 for any lists or tables. + Always sort lists in ascending order. + """, + name="SampleAssistantAgent", + tools=code_interpreter_tools, + tool_resources=code_interpreter_tool_resources, + ) + + # Create the agent using the client and the assistant definition + agent = AzureAssistantAgent( + client=client, + definition=definition, ) print("Creating thread...") - thread_id = await agent.create_thread() + thread = await client.beta.threads.create() try: is_complete: bool = False @@ -829,14 +871,13 @@ async def main(): if user_input.lower() == "exit": is_complete = True + break - await agent.add_chat_message( - thread_id=thread_id, message=ChatMessageContent(role=AuthorRole.USER, content=user_input) - ) + await agent.add_chat_message(thread_id=thread.id, message=user_input) is_code = False last_role = None - async for response in agent.invoke_stream(thread_id=thread_id): + async for response in agent.invoke_stream(thread_id=thread.id): current_is_code = response.metadata.get("code", False) if current_is_code: @@ -858,16 +899,16 @@ async def main(): ]) if is_code: print("```\n") + print() await download_response_image(agent, file_ids) file_ids.clear() finally: print("\nCleaning up resources...") - if agent is not None: - [await agent.delete_file(file_id) for file_id in agent.code_interpreter_file_ids] - await agent.delete_thread(thread_id) - await agent.delete() + [await client.files.delete(file_id) for file_id in file_ids] + await client.beta.threads.delete(thread.id) + await client.beta.assistants.delete(agent.id) if __name__ == "__main__": @@ -885,5 +926,5 @@ You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/m > [!div class="nextstepaction"] -> [How-To: _OpenAI Assistant Agent_ Code File Search](./example-assistant-search.md) +> [How-To: `OpenAIAssistantAgent` Code File Search](./example-assistant-search.md) diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index e05c069c..1aad1696 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -1,5 +1,5 @@ --- -title: How-To: _OpenAI Assistant Agent_ File Search (Experimental) +title: How-To: `OpenAIAssistantAgent` File Search description: A step-by-step walk-through of defining and utilizing the file-search tool of an OpenAI Assistant Agent. zone_pivot_groups: programming-languages author: crickman @@ -8,14 +8,14 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# How-To: _OpenAI Assistant Agent_ File Search +# How-To: `OpenAIAssistantAgent` File Search -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## Overview -In this sample, we will explore how to use the _file-search_ tool of an [_OpenAI Assistant Agent_](../assistant-agent.md) to complete comprehension tasks. The approach will be step-by-step, ensuring clarity and precision throughout the process. As part of the task, the agent will provide document citations within the response. +In this sample, we will explore how to use the _file-search_ tool of an [`OpenAIAssistantAgent`](../assistant-agent.md) to complete comprehension tasks. The approach will be step-by-step, ensuring clarity and precision throughout the process. As part of the task, the agent will provide document citations within the response. Streaming will be used to deliver the agent's responses. This will provide real-time updates as the task progresses. @@ -54,7 +54,7 @@ The project file (`.csproj`) should contain the following `PackageReference` def ``` -The _Agent Framework_ is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): +The `Agent Framework` is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): ```xml @@ -86,11 +86,8 @@ Start by creating a folder that will hold your script (`.py` file) and the sampl import asyncio import os -from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.streaming_annotation_content import StreamingAnnotationContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.kernel import Kernel +from semantic_kernel.agents.open_ai import AzureAssistantAgent +from semantic_kernel.contents import StreamingAnnotationContent ``` Additionally, copy the `Grimms-The-King-of-the-Golden-Mountain.txt`, `Grimms-The-Water-of-Life.txt` and `Grimms-The-White-Snake.txt` public domain content from [_Semantic Kernel_ `LearnResources` Project](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/learn_resources/resources). Add these files in your project folder. @@ -201,14 +198,14 @@ Once configured, the respective AI service classes will pick up the required var The coding process for this sample involves: 1. [Setup](#setup) - Initializing settings and the plug-in. -2. [Agent Definition](#agent-definition) - Create the _Chat_Completion_Agent_ with templatized instructions and plug-in. +2. [Agent Definition](#agent-definition) - Create the _Chat_Completion`Agent` with templatized instructions and plug-in. 3. [The _Chat_ Loop](#the-chat-loop) - Write the loop that drives user / agent interaction. The full example code is provided in the [Final](#final) section. Refer to that section for the complete implementation. ### Setup -Prior to creating an _OpenAI Assistant Agent_, ensure the configuration settings are available and prepare the file resources. +Prior to creating an `OpenAIAssistantAgent`, ensure the configuration settings are available and prepare the file resources. ::: zone pivot="programming-language-csharp" @@ -225,6 +222,16 @@ OpenAIClientProvider clientProvider = ``` ::: zone-end + +::: zone pivot="programming-language-python" +The class method `setup_resources()` on the Assistant Agent handles creating the client and returning it and the model to use based on the desired configuration. Pydantic settings are used to load environment variables first from environment variables or from the `.env` file. One may pass in the `api_key`, `api_version`, `deployment_name` or `endpoint`, which will take precedence over any environment variables configured. + +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() +``` +::: zone-end + ::: zone pivot="programming-language-java" > Agents are currently unavailable in Java. @@ -248,8 +255,21 @@ string storeId = operation.VectorStoreId; ::: zone pivot="programming-language-python" ```python def get_filepath_for_filename(filename: str) -> str: - base_directory = os.path.dirname(os.path.realpath(__file__)) + base_directory = os.path.join( + os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", + ) return os.path.join(base_directory, filename) + +# Upload the files to the client +file_ids: list[str] = [] +for path in [get_filepath_for_filename(filename) for filename in filenames]: + with open(path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + file_ids.append(file.id) + +# Get the file search tool and resources +file_search_tools, file_search_tool_resources = AzureAssistantAgent.configure_file_search_tool(file_ids=file_ids) ``` ::: zone-end @@ -315,7 +335,7 @@ foreach (string fileName in _fileNames) ### Agent Definition -We are now ready to instantiate an _OpenAI Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _File Search_ tool enabled. Additionally, we explicitly associate the _Vector Store_ with the _File Search_ tool. +We are now ready to instantiate an `OpenAIAssistantAgent`. The agent is configured with its target model, _Instructions_, and the _File Search_ tool enabled. Additionally, we explicitly associate the _Vector Store_ with the _File Search_ tool. ::: zone pivot="programming-language-csharp" @@ -345,18 +365,24 @@ OpenAIAssistantAgent agent = ::: zone pivot="programming-language-python" ```python -agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, instructions=""" The document store contains the text of fictional stories. Always analyze the document store to provide an answer to the user's question. Never rely on your knowledge of stories not included in the document store. Always format response using markdown. """, - enable_file_search=True, - vector_store_filenames=[get_filepath_for_filename(filename) for filename in filenames], + name="SampleAssistantAgent", + tools=file_search_tools, + tool_resources=file_search_tool_resources, +) + +# Create the agent using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, ) ``` ::: zone-end @@ -369,7 +395,7 @@ agent = await AzureAssistantAgent.create( ### The _Chat_ Loop -At last, we are able to coordinate the interaction between the user and the _Agent_. Start by creating an _Assistant Thread_ to maintain the conversation state and creating an empty loop. +At last, we are able to coordinate the interaction between the user and the `Agent`. Start by creating an _Assistant Thread_ to maintain the conversation state and creating an empty loop. Let's also ensure the resources are removed at the end of execution to minimize unnecessary charges. @@ -458,6 +484,7 @@ if not user_input: if user_input.lower() == "exit": is_complete = True + break await agent.add_chat_message( thread_id=thread_id, message=ChatMessageContent(role=AuthorRole.USER, content=user_input) @@ -471,7 +498,7 @@ await agent.add_chat_message( ::: zone-end -Before invoking the _Agent_ response, let's add a helper method to reformat the unicode annotation brackets to ANSI brackets. +Before invoking the `Agent` response, let's add a helper method to reformat the unicode annotation brackets to ANSI brackets. ::: zone pivot="programming-language-csharp" ```csharp @@ -492,7 +519,7 @@ private static string ReplaceUnicodeBrackets(this string content) => ::: zone-end -To generate an _Agent_ response to user input, invoke the agent by specifying the _Assistant Thread_. In this example, we choose a streamed response and capture any associated _Citation Annotations_ for display at the end of the response cycle. Note each streamed chunk is being reformatted using the previous helper method. +To generate an `Agent` response to user input, invoke the agent by specifying the _Assistant Thread_. In this example, we choose a streamed response and capture any associated _Citation Annotations_ for display at the end of the response cycle. Note each streamed chunk is being reformatted using the previous helper method. ::: zone pivot="programming-language-csharp" ```csharp @@ -702,18 +729,26 @@ public static class Program ::: zone pivot="programming-language-python" ```python +# Copyright (c) Microsoft. All rights reserved. + import asyncio import os -from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.streaming_annotation_content import StreamingAnnotationContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.kernel import Kernel +from semantic_kernel.agents.open_ai import AzureAssistantAgent +from semantic_kernel.contents import StreamingAnnotationContent + +""" +The following sample demonstrates how to create a simple, +OpenAI assistant agent that utilizes the vector store +to answer questions based on the uploaded documents. +""" def get_filepath_for_filename(filename: str) -> str: - base_directory = os.path.dirname(os.path.realpath(__file__)) + base_directory = os.path.join( + os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", + ) return os.path.join(base_directory, filename) @@ -725,22 +760,48 @@ filenames = [ async def main(): - agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", + # Create the client using Azure OpenAI resources and configuration + client, model = AzureAssistantAgent.setup_resources() + + # Upload the files to the client + file_ids: list[str] = [] + for path in [get_filepath_for_filename(filename) for filename in filenames]: + with open(path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + file_ids.append(file.id) + + vector_store = await client.beta.vector_stores.create( + name="assistant_search", + file_ids=file_ids, + ) + + # Get the file search tool and resources + file_search_tools, file_search_tool_resources = AzureAssistantAgent.configure_file_search_tool( + vector_store_ids=vector_store.id + ) + + # Create the assistant definition + definition = await client.beta.assistants.create( + model=model, instructions=""" The document store contains the text of fictional stories. Always analyze the document store to provide an answer to the user's question. Never rely on your knowledge of stories not included in the document store. Always format response using markdown. """, - enable_file_search=True, - vector_store_filenames=[get_filepath_for_filename(filename) for filename in filenames], + name="SampleAssistantAgent", + tools=file_search_tools, + tool_resources=file_search_tool_resources, + ) + + # Create the agent using the client and the assistant definition + agent = AzureAssistantAgent( + client=client, + definition=definition, ) print("Creating thread...") - thread_id = await agent.create_thread() + thread = await client.beta.threads.create() try: is_complete: bool = False @@ -753,12 +814,10 @@ async def main(): is_complete = True break - await agent.add_chat_message( - thread_id=thread_id, message=ChatMessageContent(role=AuthorRole.USER, content=user_input) - ) + await agent.add_chat_message(thread_id=thread.id, message=user_input) footnotes: list[StreamingAnnotationContent] = [] - async for response in agent.invoke_stream(thread_id=thread_id): + async for response in agent.invoke_stream(thread_id=thread.id): footnotes.extend([item for item in response.items if isinstance(item, StreamingAnnotationContent)]) print(f"{response.content}", end="", flush=True) @@ -773,11 +832,10 @@ async def main(): ) finally: - print("Cleaning up resources...") - if agent is not None: - [await agent.delete_file(file_id) for file_id in agent.file_search_file_ids] - await agent.delete_thread(thread_id) - await agent.delete() + print("\nCleaning up resources...") + [await client.files.delete(file_id) for file_id in file_ids] + await client.beta.threads.delete(thread.id) + await client.beta.assistants.delete(agent.id) if __name__ == "__main__": @@ -795,5 +853,5 @@ You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/m > [!div class="nextstepaction"] -> [How to Coordinate Agent Collaboration using _Agent Group Chat_](./example-agent-collaboration.md) +> [How to Coordinate Agent Collaboration using `AgentGroupChat`](./example-agent-collaboration.md) diff --git a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md index ced3bb01..d24a85f8 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md +++ b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md @@ -1,5 +1,5 @@ --- -title: How-To: _Chat Completion Agent_ (Experimental) +title: How-To: `ChatCompletionAgent` description: A step-by-step walk-through of defining and utilizing the features of a Chat Completion Agent. zone_pivot_groups: programming-languages author: crickman @@ -8,14 +8,14 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# How-To: _Chat Completion Agent_ +# How-To: `ChatCompletionAgent` -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the experimental stage. Features at this stage are still under development and subject to change before advancing to the preview or release candidate stage. ## Overview -In this sample, we will explore configuring a plugin to access _GitHub_ API and provide templatized instructions to a [_Chat Completion Agent_](../chat-completion-agent.md) to answer questions about a _GitHub_ repository. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will provide document citations within the response. +In this sample, we will explore configuring a plugin to access _GitHub_ API and provide templatized instructions to a [`ChatCompletionAgent`](../chat-completion-agent.md) to answer questions about a _GitHub_ repository. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will provide document citations within the response. Streaming will be used to deliver the agent's responses. This will provide real-time updates as the task progresses. @@ -55,7 +55,7 @@ The project file (`.csproj`) should contain the following `PackageReference` def ``` -The _Agent Framework_ is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): +The `Agent Framework` is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): ```xml @@ -76,13 +76,11 @@ import sys from datetime import datetime from semantic_kernel.agents import ChatCompletionAgent -from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior +from semantic_kernel.connectors.ai import FunctionChoiceBehavior from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion -from semantic_kernel.contents.chat_history import ChatHistory -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.utils.author_role import AuthorRole +from semantic_kernel.contents import AuthorRole, ChatHistory, ChatMessageContent +from semantic_kernel.functions import KernelArguments from semantic_kernel.kernel import Kernel -from semantic_kernel.functions.kernel_arguments import KernelArguments # Adjust the sys.path so we can use the GitHubPlugin and GitHubSettings classes # This is so we can run the code from the samples/learn_resources/agent_docs directory @@ -201,14 +199,14 @@ Once configured, the respective AI service classes will pick up the required var The coding process for this sample involves: 1. [Setup](#setup) - Initializing settings and the plug-in. -2. [_Agent_ Definition](#agent-definition) - Create the _Chat Completion Agent_ with templatized instructions and plug-in. +2. [`Agent` Definition](#agent-definition) - Create the `ChatCompletionAgent` with templatized instructions and plug-in. 3. [The _Chat_ Loop](#the-chat-loop) - Write the loop that drives user / agent interaction. The full example code is provided in the [Final](#final) section. Refer to that section for the complete implementation. ### Setup -Prior to creating a _Chat Completion Agent_, the configuration settings, plugins, and _Kernel_ must be initialized. +Prior to creating a `ChatCompletionAgent`, the configuration settings, plugins, and `Kernel` must be initialized. ::: zone pivot="programming-language-csharp" @@ -293,7 +291,7 @@ settings.function_choice_behavior = FunctionChoiceBehavior.Auto() ### Agent Definition -Finally we are ready to instantiate a _Chat Completion Agent_ with its _Instructions_, associated _Kernel_, and the default _Arguments_ and _Execution Settings_. In this case, we desire to have the any plugin functions automatically executed. +Finally we are ready to instantiate a `ChatCompletionAgent` with its _Instructions_, associated `Kernel`, and the default _Arguments_ and _Execution Settings_. In this case, we desire to have the any plugin functions automatically executed. ::: zone pivot="programming-language-csharp" ```csharp @@ -328,7 +326,6 @@ Console.WriteLine("Ready!"); ::: zone pivot="programming-language-python" ```python agent = ChatCompletionAgent( - service_id="agent", kernel=kernel, name="SampleAssistantAgent", instructions=f""" @@ -358,7 +355,7 @@ agent = ChatCompletionAgent( ### The _Chat_ Loop -At last, we are able to coordinate the interaction between the user and the _Agent_. Start by creating a _Chat History_ object to maintain the conversation state and creating an empty loop. +At last, we are able to coordinate the interaction between the user and the `Agent`. Start by creating a `ChatHistory` object to maintain the conversation state and creating an empty loop. ::: zone pivot="programming-language-csharp" ```csharp @@ -386,7 +383,7 @@ while not is_complete: ::: zone-end -Now let's capture user input within the previous loop. In this case, empty input will be ignored and the term `EXIT` will signal that the conversation is completed. Valid input will be added to the _Chat History_ as a _User_ message. +Now let's capture user input within the previous loop. In this case, empty input will be ignored and the term `EXIT` will signal that the conversation is completed. Valid input will be added to the `ChatHistory` as a _User_ message. ::: zone pivot="programming-language-csharp" ```csharp @@ -429,9 +426,9 @@ history.add_message(ChatMessageContent(role=AuthorRole.USER, content=user_input) ::: zone-end -To generate a _Agent_ response to user input, invoke the agent using _Arguments_ to provide the final template parameter that specifies the current date and time. +To generate a `Agent` response to user input, invoke the agent using _Arguments_ to provide the final template parameter that specifies the current date and time. -The _Agent_ response is then then displayed to the user. +The `Agent` response is then then displayed to the user. ::: zone pivot="programming-language-csharp" ```csharp @@ -628,7 +625,6 @@ async def main(): # Create the agent agent = ChatCompletionAgent( - service_id="agent", kernel=kernel, name="SampleAssistantAgent", instructions=f""" @@ -682,6 +678,6 @@ You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/m > [!div class="nextstepaction"] -> [How-To: _OpenAI Assistant Agent_ Code Interpreter](./example-assistant-code.md) +> [How-To: `OpenAIAssistantAgent` Code Interpreter](./example-assistant-code.md) diff --git a/semantic-kernel/Frameworks/agent/index.md b/semantic-kernel/Frameworks/agent/index.md index 7d8299ea..67a76125 100644 --- a/semantic-kernel/Frameworks/agent/index.md +++ b/semantic-kernel/Frameworks/agent/index.md @@ -1,5 +1,5 @@ --- -title: Semantic Kernel Agent Framework (Experimental) +title: Semantic Kernel Agent Framework description: Introducing the Semantic Kernel Agent Framework zone_pivot_groups: programming-languages author: crickman @@ -10,10 +10,10 @@ ms.service: semantic-kernel --- # Semantic Kernel Agent Framework -> [!WARNING] -> The _Semantic Kernel Agent Framework_ is in preview and is subject to change. +> [!IMPORTANT] +> Single-agent features, such as ChatCompletionAgent and OpenAIAssistantAgent, are in the release candidate stage. These features are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. However, agent chat patterns are still in the experimental stage. These patterns are under active development and may change significantly before advancing to the preview or release candidate stage. -The _Semantic Kernel Agent Framework_ provides a platform within the Semantic Kernel eco-system that allow for the creation of AI **agents** and the ability to incorporate **agentic patterns** into any application based on the same patterns and features that exist in the core _Semantic Kernel_ framework. +The Semantic Kernel Agent Framework provides a platform within the Semantic Kernel eco-system that allow for the creation of AI **agents** and the ability to incorporate **agentic patterns** into any application based on the same patterns and features that exist in the core Semantic Kernel framework. ## What is an AI agent? @@ -21,7 +21,7 @@ An **AI agent** is a software entity designed to perform tasks autonomously or s Agents can send and receive messages, generating responses using a combination of models, tools, human inputs, or other customizable components. -Agents are designed to work collaboratively, enabling complex workflows by interacting with each other. The _Agent Framework_ allows for the creation of both simple and sophisticated agents, enhancing modularity and ease of maintenance +Agents are designed to work collaboratively, enabling complex workflows by interacting with each other. The `Agent Framework` allows for the creation of both simple and sophisticated agents, enhancing modularity and ease of maintenance ## What problems do AI agents solve? @@ -63,8 +63,8 @@ For .NET SDK, serveral NuGet packages are available. Package|Description --|-- -[Microsoft.SemanticKernel](https://www.nuget.org/packages/Microsoft.SemanticKernel)|This contains the core _Semantic Kernel_ libraries for getting started with the _Agent Framework_. This must be explicitly referenced by your application. -[Microsoft.SemanticKernel.Agents.Abstractions](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Abstractions)|Defines the core agent abstractions for the _Agent Framework_. Generally not required to be specified as it is included in both the `Microsoft.SemanticKernel.Agents.Core` and `Microsoft.SemanticKernel.Agents.OpenAI` packages. +[Microsoft.SemanticKernel](https://www.nuget.org/packages/Microsoft.SemanticKernel)|This contains the core _Semantic Kernel_ libraries for getting started with the `Agent Framework`. This must be explicitly referenced by your application. +[Microsoft.SemanticKernel.Agents.Abstractions](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Abstractions)|Defines the core agent abstractions for the `Agent Framework`. Generally not required to be specified as it is included in both the `Microsoft.SemanticKernel.Agents.Core` and `Microsoft.SemanticKernel.Agents.OpenAI` packages. [Microsoft.SemanticKernel.Agents.Core](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Core)|Includes the [`ChatCompletionAgent`](./chat-completion-agent.md) and [`AgentGroupChat`](./agent-chat.md) classes. [Microsoft.SemanticKernel.Agents.OpenAI](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.OpenAI)|Provides ability to use the [OpenAI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent`](./assistant-agent.md). @@ -74,7 +74,7 @@ Package|Description Module|Description --|-- -[semantic-kernel.agents](https://pypi.org/project/semantic-kernel/)|This is the _Semantic Kernel_ library for getting started with the _Agent Framework_. This must be explicitly referenced by your application. This module contains the [`ChatCompletionAgent`](./chat-completion-agent.md) and [`AgentGroupChat`](./agent-chat.md) classes, as well as the ability to use the [OpenAI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent` or `AzureOpenAssistant`](./assistant-agent.md). +[semantic-kernel.agents](https://pypi.org/project/semantic-kernel/)|This is the _Semantic Kernel_ library for getting started with the `Agent Framework`. This must be explicitly referenced by your application. This module contains the [`ChatCompletionAgent`](./chat-completion-agent.md) and [`AgentGroupChat`](./agent-chat.md) classes, as well as the ability to use the [OpenAI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent` or `AzureOpenAssistant`](./assistant-agent.md). ::: zone-end diff --git a/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md b/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md new file mode 100644 index 00000000..5dbc6bba --- /dev/null +++ b/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md @@ -0,0 +1,623 @@ +--- +title: Agent Framework Release Candidate Migration Guide +description: Describes the steps for developers to update their Agent Framework code to the latest abstractions. +zone_pivot_groups: programming-languages +author: moonbox3 +ms.topic: conceptual +ms.author: evmattso +ms.date: 02/26/2025 +ms.service: semantic-kernel +--- + +# Migration Guide for Updating from Old Code to New Code + +As we transition some agents from the experimental stage to the release candidate stage, we have updated the APIs to simplify and streamline their use. Refer to the specific scenario guide to learn how to update your existing code to work with the latest available APIs. + +::: zone pivot="programming-language-csharp" + +## OpenAIAssistantAgent C# Migration Guide + +We recently applied a significant shift around the [`OpenAIAssistantAgent`](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/src/Agents/OpenAI/OpenAIAssistantAgent.cs) in the _Semantic Kernel Agent Framework_. + +These changes were applied in: + +- [PR #10583](https://github.com/microsoft/semantic-kernel/pull/10583) +- [PR #10616](https://github.com/microsoft/semantic-kernel/pull/10616) +- [PR #10633](https://github.com/microsoft/semantic-kernel/pull/10633) + +These changes are intended to: + +- Align with the pattern for using for our [`AzureAIAgent`](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/src/Agents/AzureAI/AzureAIAgent.cs). +- Fix bugs around static initialization pattern. +- Avoid limiting features based on our abstraction of the underlying SDK. + +This guide provides step-by-step instructions for migrating your C# code from the old implementation to the new one. Changes include updates for creating assistants, managing the assistant lifecycle, handling threads, files, and vector stores. + +## 1. Client Instantiation + +Previously, `OpenAIClientProvider` was required for creating any `OpenAIAssistantAgent`. This dependency has been simplified. + +#### **New Way** +```csharp +OpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(endpointUrl)); +AssistantClient assistantClient = client.GetAssistantClient(); +``` + +#### **Old Way (Deprecated)** +```csharp +var clientProvider = new OpenAIClientProvider(...); +``` + +## 2. Assistant Lifecycle + +### **Creating an Assistant** +You may now directly instantiate an `OpenAIAssistantAgent` using an existing or new Assistant definition from `AssistantClient`. + +##### **New Way** +```csharp +Assistant definition = await assistantClient.GetAssistantAsync(assistantId); +OpenAIAssistantAgent agent = new(definition, client); +``` + +Plugins can be directly included during initialization: +```csharp +KernelPlugin plugin = KernelPluginFactory.CreateFromType(); +Assistant definition = await assistantClient.GetAssistantAsync(assistantId); +OpenAIAssistantAgent agent = new(definition, client, [plugin]); +``` + +Creating a new assistant definition using an extension method: +```csharp +Assistant assistant = await assistantClient.CreateAssistantAsync( + model, + name, + instructions: instructions, + enableCodeInterpreter: true); +``` + +##### **Old Way (Deprecated)** +Previously, assistant definitions were managed indirectly. + +## 3. Invoking the Agent + +You may specify `RunCreationOptions` directly, enabling full access to underlying SDK capabilities. + +#### **New Way** +```csharp +RunCreationOptions options = new(); // configure as needed +var result = await agent.InvokeAsync(options); +``` + +#### **Old Way (Deprecated)** +```csharp +var options = new OpenAIAssistantInvocationOptions(); +``` + +## 4. Assistant Deletion + +You can directly manage assistant deletion with `AssistantClient`. + +```csharp +await assistantClient.DeleteAssistantAsync(agent.Id); +``` + +## 5. Thread Lifecycle + +### **Creating a Thread** +Threads are now created directly using `AssistantClient`. + +##### **New Way** +```csharp +AssistantThread thread = await assistantClient.CreateThreadAsync(); +``` + +Using a convenience extension method: +```csharp +string threadId = await assistantClient.CreateThreadAsync(messages: [new ChatMessageContent(AuthorRole.User, "")]); +``` + +##### **Old Way (Deprecated)** +Previously, thread management was indirect or agent-bound. + +### **Thread Deletion** +```csharp +await assistantClient.DeleteThreadAsync(thread.Id); +``` + +## 6. File Lifecycle + +File creation and deletion now utilize `OpenAIFileClient`. + +### **File Upload** +```csharp +string fileId = await client.UploadAssistantFileAsync(stream, ""); +``` + +### **File Deletion** +```csharp +await client.DeleteFileAsync(fileId); +``` + +## 7. Vector Store Lifecycle + +Vector stores are managed directly via `VectorStoreClient` with convenient extension methods. + +### **Vector Store Creation** +```csharp +string vectorStoreId = await client.CreateVectorStoreAsync([fileId1, fileId2], waitUntilCompleted: true); +``` + +### **Vector Store Deletion** +```csharp +await client.DeleteVectorStoreAsync(vectorStoreId); +``` + +## Backwards Compatibility + +Deprecated patterns are marked with `[Obsolete]`. To suppress obsolete warnings (`CS0618`), update your project file as follows: + +```xml + + $(NoWarn);CS0618 + +``` + +This migration guide helps you transition smoothly to the new implementation, simplifying client initialization, resource management, and integration with the **Semantic Kernel .NET SDK**. + +::: zone-end +::: zone pivot="programming-language-python" + +For developers upgrading to Semantic Kernel Python 1.22.0 or later, the ChatCompletionAgent and OpenAI Assistant abstractions have been updated. + +These changes were applied in: + +- [PR #10666](https://github.com/microsoft/semantic-kernel/pull/10666) +- [PR #10667](https://github.com/microsoft/semantic-kernel/pull/10667) +- [PR #10701](https://github.com/microsoft/semantic-kernel/pull/10701) +- [PR #10707](https://github.com/microsoft/semantic-kernel/pull/10707) + +This guide provides step-by-step instructions for migrating your Python code from the old implementation to the new implementation. + +## `ChatCompletionAgent` + +The `ChatCompletionAgent` has been updated to simplify service configuration, plugin handling, and function calling behaviors. Below are the key changes you should consider when migrating. + +### 1. Specifying the Service + +You can now specify the service directly as part of the agent constructor: + +#### New Way + +```python +agent = ChatCompletionAgent( + service=AzureChatCompletion(), + name="", + instructions="", +) +``` + +Note: If both a kernel and a service are provided, the service will take precedence if it shares the same service_id or ai_model_id. Otherwise, if they are separate, the first AI service registered on the kernel will be used. + +#### Old Way (Still Valid) + +Previously, you would first add a service to a kernel and then pass the kernel to the agent: + +```python +kernel = Kernel() +kernel.add_service(AzureChatCompletion()) + +agent = ChatCompletionAgent( + kernel=kernel, + name="", + instructions="", +) +``` + +### 2. Adding Plugins + +Plugins can now be supplied directly through the constructor: + +#### New Way + +```python +agent = ChatCompletionAgent( + service=AzureChatCompletion(), + name="", + instructions="", + plugins=[SamplePlugin()], +) +``` + +#### Old Way (Still Valid) + +Plugins previously had to be added to the kernel separately: + +```python +kernel = Kernel() +kernel.add_plugin(SamplePlugin()) + +agent = ChatCompletionAgent( + kernel=kernel, + name="", + instructions="", +) +``` + +Note: Both approaches are valid, but directly specifying plugins simplifies initialization. + +### 3. Invoking the Agent + +You now have two ways to invoke the agent. The new method directly retrieves a single response, while the old method supports streaming. + +#### New Way (Single Response) + +```python +chat_history = ChatHistory() +chat_history.add_user_message("") +response = await agent.get_response(chat_history) +# response is of type ChatMessageContent +``` + +#### Old Way (Still Valid) + +```python +chat_history = ChatHistory() +chat_history.add_user_message("") +async for response in agent.invoke(chat_history): + # handle response +``` + +### 4. Controlling Function Calling + +Function calling behavior can now be controlled directly when specifying the service within the agent constructor: + +```python +agent = ChatCompletionAgent( + service=AzureChatCompletion(), + name="", + instructions="", + plugins=[MenuPlugin()], + function_choice_behavior=FunctionChoiceBehavior.Auto( + filters={"included_functions": ["get_specials", "get_item_price"]} + ), +) +``` + +Note: Previously, function calling configuration required separate setup on the kernel or service object. If execution settings specify the same `service_id` or `ai_model_id` as the AI service configuration, the function calling behavior defined in the execution settings (via `KernelArguments`) will take precedence over the function choice behavior set in the constructor. + +These updates enhance simplicity and configurability, making the ChatCompletionAgent easier to integrate and maintain. + +## `OpenAIAssistantAgent` + +The `AzureAssistantAgent` and `OpenAIAssistantAgent` changes include updates for creating assistants, creating threads, handling plugins, using the code interpreter tool, working with the file search tool, and adding chat messages to a thread. + +## Setting up Resources + +### Old Way + +The `AsyncAzureOpenAI` client was created as part of creating the Agent object. + +```python +agent = await AzureAssistantAgent.create( + deployment_name="optional-deployment-name", + api_key="optional-api-key", + endpoint="optional-endpoint", + ad_token="optional-ad-token", + ad_token_provider=optional_callable, + default_headers={"optional_header": "optional-header-value"}, + env_file_path="optional-env-file-path", + env_file_encoding="optional-env-file-encoding", + ..., +) +``` + +### New Way + +The agent provides a static method to create the required client for the specified resources, where method-level keyword arguments take precedence over environment variables and values in an existing `.env` file. + +```python +client, model = AzureAssistantAgent.setup_resources( + ad_token="optional-ad-token", + ad_token_provider=optional_callable, + api_key="optional-api-key", + api_version="optional-api-version", + base_url="optional-base-url", + default_headers="optional-default-headers", + deployment_name="optional-deployment-name", + endpoint="optional-endpoint", + env_file_path="optional-env-file-path", + env_file_encoding="optional-env-file-encoding", + token_scope="optional-token-scope", +) +``` + +## 1. Creating an Assistant + +### Old Way +```python +agent = await AzureAssistantAgent.create( + kernel=kernel, + service_id=service_id, + name=AGENT_NAME, + instructions=AGENT_INSTRUCTIONS, + enable_code_interpreter=True, +) +``` +or +```python +agent = await OpenAIAssistantAgent.create( + kernel=kernel, + service_id=service_id, + name=, + instructions=, + enable_code_interpreter=True, +) +``` + +### New Way +```python +# Azure AssistantAgent + +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the agent using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, +) +``` +or +```python +# OpenAI Assistant Agent + +# Create the client using OpenAI resources and configuration +client, model = OpenAIAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the agent using the client and the assistant definition +agent = OpenAIAssistantAgent( + client=client, + definition=definition, +) +``` + +## 2. Creating a Thread + +### Old Way +```python +thread_id = await agent.create_thread() +``` + +### New Way +```python +thread = await agent.client.beta.threads.create() +# Use thread.id for the thread_id string +``` + +## 3. Handling Plugins + +### Old Way +```python +# Create the instance of the Kernel +kernel = Kernel() + +# Add the sample plugin to the kernel +kernel.add_plugin(plugin=MenuPlugin(), plugin_name="menu") + +agent = await AzureAssistantAgent.create( + kernel=kernel, + name="", + instructions="" +) +``` +*Note: It is still possible to manage plugins via the kernel. If you do not supply a kernel, a kernel is automatically created at agent creation time and the plugins will be added to that instance.* + +### New Way +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the agent with plugins passed in as a list +agent = AzureAssistantAgent( + client=client, + definition=definition, + plugins=[MenuPlugin()], +) +``` + +Refer to the [sample implementation](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/getting_started_with_agents/openai_assistant/step2_plugins.py) for full details. + +## 4. Using the Code Interpreter Tool + +### Old Way +```python +csv_file_path = ... + +agent = await AzureAssistantAgent.create( + kernel=kernel, + name="", + instructions="", + enable_code_interpreter=True, + code_interpreter_filenames=[csv_file_path], +) +``` + +### New Way +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +csv_file_path = ... + +# Load the CSV file as a FileObject +with open(csv_file_path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + +# Get the code interpreter tool and resources +code_interpreter_tool, code_interpreter_tool_resource = AzureAssistantAgent.configure_code_interpreter_tool(file.id) + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + name="", + instructions=".", + tools=code_interpreter_tool, + tool_resources=code_interpreter_tool_resource, +) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, +) +``` + +Refer to the [sample implementation](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/agents/openai_assistant/openai_assistant_file_manipulation.py) for full details. + +## 5. Working with the File Search Tool + +### Old Way +```python +pdf_file_path = ... + +agent = await AzureAssistantAgent.create( + kernel=kernel, + service_id=service_id, + name=AGENT_NAME, + instructions=AGENT_INSTRUCTIONS, + enable_file_search=True, + vector_store_filenames=[pdf_file_path], +) +``` + +### New Way + +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +pdf_file_path = ... + +# Load the employees PDF file as a FileObject +with open(pdf_file_path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + +# Create a vector store specifying the file ID to be used for file search +vector_store = await client.beta.vector_stores.create( + name="step4_assistant_file_search", + file_ids=[file.id], +) + +file_search_tool, file_search_tool_resources = AzureAssistantAgent.configure_file_search_tool(vector_store.id) + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="Find answers to the user's questions in the provided file.", + name="FileSearch", + tools=file_search_tool, + tool_resources=file_search_tool_resources, +) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, +) +``` + +Refer to the [sample implementation](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/getting_started_with_agents/openai_assistant/step4_assistant_tool_file_search.py) for full details. + +## 6. Adding Chat Messages to a Thread + +### Old Way +```python +await agent.add_chat_message( + thread_id=thread_id, + message=ChatMessageContent(role=AuthorRole.USER, content=user_input) +) +``` + +### New Way +*Note: The old method still works if you pass in a `ChatMessageContent`, but you can now also pass a simple string.* +```python +await agent.add_chat_message( + thread_id=thread_id, + message=user_input, +) +``` + +## 7. Cleaning Up Resources + +### Old Way +```python +await agent.delete_file(file_id) +await agent.delete_thread(thread_id) +await agent.delete() +``` + +### New Way +```python +await client.files.delete(file_id) +await client.beta.threads.delete(thread.id) +await client.beta.assistants.delete(agent.id) +``` + +## Handling Structured Outputs + +### Old Way +*Unavailable in the old way* + +### New Way +```python +# Define a Pydantic model that represents the structured output from the OpenAI service +class ResponseModel(BaseModel): + response: str + items: list[str] + +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + name="", + instructions="", + response_format=AzureAssistantAgent.configure_response_format(ResponseModel), +) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, +) +``` +Refer to the [sample implementation](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/agents/openai_assistant/openai_assistant_structured_outputs.py) for full details. + +This migration guide should help you update your code to the new implementation, leveraging client-based configuration and enhanced features. + +::: zone-end +::: zone pivot="programming-language-java" +> Agents are unavailable in Java. +::: zone-end diff --git a/semantic-kernel/support/migration/toc.yml b/semantic-kernel/support/migration/toc.yml index 91c21c5f..1718b55c 100644 --- a/semantic-kernel/support/migration/toc.yml +++ b/semantic-kernel/support/migration/toc.yml @@ -9,4 +9,6 @@ - name: Memory Store to Vector Store Migration href: memory-store-migration.md - name: Kernel Events and Filters Migration - href: kernel-events-and-filters-migration.md \ No newline at end of file + href: kernel-events-and-filters-migration.md +- name: Agent Framework Release Candidate Migration Guide + href: agent-framework-rc-migration-guide.md \ No newline at end of file From 24962d0ecddb051e2e1cc30e57e780ca3e018ac5 Mon Sep 17 00:00:00 2001 From: Evan Mattson <35585003+moonbox3@users.noreply.github.com> Date: Fri, 28 Feb 2025 11:15:09 +0900 Subject: [PATCH 41/70] Update Agent Framework related doc and code samples. Add migration code for Python (#469) (#473) * Update OpenAI assistant related code samples. Add migration code for Python * improve migration guide * Update semantic-kernel/support/migration/openai-assistant-agent-migration-guide.md * Update semantic-kernel/support/migration/openai-assistant-agent-migration-guide.md * Replace italics with code format. * update bookmarks * Update Python docs * Add dotnet migration guide. * update formatting in migration guide * fix headers * Fix header again * update guide to include rc * Small update to include new method get_response * Update important tags with some experimental (group chat) and some release candidate --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../Frameworks/agent/agent-architecture.md | 34 +- .../Frameworks/agent/agent-chat.md | 58 +- .../Frameworks/agent/agent-functions.md | 89 ++- .../Frameworks/agent/agent-streaming.md | 24 +- .../Frameworks/agent/agent-templates.md | 18 +- .../Frameworks/agent/assistant-agent.md | 95 ++- .../Frameworks/agent/chat-completion-agent.md | 79 ++- .../examples/example-agent-collaboration.md | 118 ++-- .../agent/examples/example-assistant-code.md | 181 +++-- .../examples/example-assistant-search.md | 152 +++-- .../agent/examples/example-chat-agent.md | 38 +- semantic-kernel/Frameworks/agent/index.md | 16 +- .../agent-framework-rc-migration-guide.md | 623 ++++++++++++++++++ semantic-kernel/support/migration/toc.yml | 4 +- 14 files changed, 1180 insertions(+), 349 deletions(-) create mode 100644 semantic-kernel/support/migration/agent-framework-rc-migration-guide.md diff --git a/semantic-kernel/Frameworks/agent/agent-architecture.md b/semantic-kernel/Frameworks/agent/agent-architecture.md index c3966fa8..b22c48ee 100644 --- a/semantic-kernel/Frameworks/agent/agent-architecture.md +++ b/semantic-kernel/Frameworks/agent/agent-architecture.md @@ -1,5 +1,5 @@ --- -title: Semantic Kernel Agent Architecture (Experimental) +title: Semantic Kernel Agent Architecture description: An overview of the architecture of the Semantic Kernel Agent Framework and how it aligns with core Semantic Kernel features. zone_pivot_groups: programming-languages author: crickman @@ -10,15 +10,15 @@ ms.service: semantic-kernel --- # An Overview of the Agent Architecture -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> Single-agent features, such as ChatCompletionAgent and OpenAIAssistantAgent, are in the release candidate stage. These features are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. However, agent chat patterns are still in the experimental stage. These patterns are under active development and may change significantly before advancing to the preview or release candidate stage. This article covers key concepts in the architecture of the Agent Framework, including foundational principles, design objectives, and strategic goals. ## Goals -The _Agent Framework_ was developed with the following key priorities in mind: +The `Agent Framework` was developed with the following key priorities in mind: - The _Semantic Kernel_ framework serves as the core foundation for implementing agent functionalities. - Multiple agents can collaborate within a single conversation, while integrating human input. @@ -28,7 +28,7 @@ The _Agent Framework_ was developed with the following key priorities in mind: ## Agent -The abstract _Agent_ class serves as the core abstraction for all types of agents, providing a foundational structure that can be extended to create more specialized agents. One key subclass is _Kernel Agent_, which establishes a direct association with a [_Kernel_](../../concepts/kernel.md) object. This relationship forms the basis for more specific agent implementations, such as the [_Chat Completion Agent_](./chat-completion-agent.md) and the [_OpenAI Assistant Agent_](./assistant-agent.md), both of which leverage the Kernel's capabilities to execute their respective functions. +The abstract `Agent` class serves as the core abstraction for all types of agents, providing a foundational structure that can be extended to create more specialized agents. One key subclass is _Kernel Agent_, which establishes a direct association with a [`Kernel`](../../concepts/kernel.md) object. This relationship forms the basis for more specific agent implementations, such as the [`ChatCompletionAgent`](./chat-completion-agent.md) and the [`OpenAIAssistantAgent`](./assistant-agent.md), both of which leverage the Kernel's capabilities to execute their respective functions. ::: zone pivot="programming-language-csharp" @@ -49,7 +49,7 @@ The abstract _Agent_ class serves as the core abstraction for all types of agent ::: zone-end -Agents can either be invoked directly to perform tasks or orchestrated within an [_Agent Chat_](./agent-chat.md), where multiple agents may collaborate or interact dynamically with user inputs. This flexible structure allows agents to adapt to various conversational or task-driven scenarios, providing developers with robust tools for building intelligent, multi-agent systems. +Agents can either be invoked directly to perform tasks or orchestrated within an [`AgentChat`](./agent-chat.md), where multiple agents may collaborate or interact dynamically with user inputs. This flexible structure allows agents to adapt to various conversational or task-driven scenarios, providing developers with robust tools for building intelligent, multi-agent systems. #### Deep Dive: @@ -64,7 +64,7 @@ Agents can either be invoked directly to perform tasks or orchestrated within an ## Agent Chat -The [_Agent Chat_](./agent-chat.md) class serves as the foundational component that enables agents of any type to engage in a specific conversation. This class provides the essential capabilities for managing agent interactions within a chat environment. Building on this, the [_Agent Group Chat_](./agent-chat.md#creating-an-agent-group-chat) class extends these capabilities by offering a stategy-based container, which allows multiple agents to collaborate across numerous interactions within the same conversation. +The [`AgentChat`](./agent-chat.md) class serves as the foundational component that enables agents of any type to engage in a specific conversation. This class provides the essential capabilities for managing agent interactions within a chat environment. Building on this, the [`AgentGroupChat`](./agent-chat.md#creating-an-agentgroupchat) class extends these capabilities by offering a stategy-based container, which allows multiple agents to collaborate across numerous interactions within the same conversation. This structure facilitates more complex, multi-agent scenarios where different agents can work together, share information, and dynamically respond to evolving conversations, making it an ideal solution for advanced use cases such as customer support, multi-faceted task management, or collaborative problem-solving environments. @@ -74,7 +74,7 @@ This structure facilitates more complex, multi-agent scenarios where different a ## Agent Channel -The _Agent Channel_ class enables agents of various types to participate in an [_Agent Chat_](./agent-chat.md). This functionality is completely hidden from users of the _Agent Framework_ and only needs to be considered by developers creating a custom [_Agent_](#agent). +The _Agent Channel_ class enables agents of various types to participate in an [`AgentChat`](./agent-chat.md). This functionality is completely hidden from users of the `Agent Framework` and only needs to be considered by developers creating a custom [`Agent`](#agent). ::: zone pivot="programming-language-csharp" @@ -96,14 +96,14 @@ The _Agent Channel_ class enables agents of various types to participate in an [ ## Agent Alignment with _Semantic Kernel_ Features -The _Agent Framework_ is built on the foundational concepts and features that many developers have come to know within the _Semantic Kernel_ ecosystem. These core principles serve as the building blocks for the Agent Framework’s design. By leveraging the familiar structure and capabilities of the _Semantic Kernel_, the Agent Framework extends its functionality to enable more advanced, autonomous agent behaviors, while maintaining consistency with the broader _Semantic Kernel_ architecture. This ensures a smooth transition for developers, allowing them to apply their existing knowledge to create intelligent, adaptable agents within the framework. +The `Agent Framework` is built on the foundational concepts and features that many developers have come to know within the _Semantic Kernel_ ecosystem. These core principles serve as the building blocks for the Agent Framework’s design. By leveraging the familiar structure and capabilities of the _Semantic Kernel_, the Agent Framework extends its functionality to enable more advanced, autonomous agent behaviors, while maintaining consistency with the broader _Semantic Kernel_ architecture. This ensures a smooth transition for developers, allowing them to apply their existing knowledge to create intelligent, adaptable agents within the framework. -### The _Kernel_ +### The `Kernel` -At the heart of the _Semantic Kernel_ ecosystem is the [_Kernel_](../../concepts/kernel.md), which serves as the core object that drives AI operations and interactions. To create any agent within this framework, a _Kernel instance_ is required as it provides the foundational context and capabilities for the agent’s functionality. The _Kernel_ acts as the engine for processing instructions, managing state, and invoking the necessary AI services that power the agent's behavior. +At the heart of the Semantic Kernel ecosystem is the [`Kernel`](../../concepts/kernel.md), which serves as the core object that drives AI operations and interactions. To create any agent within this framework, a _Kernel instance_ is required as it provides the foundational context and capabilities for the agent’s functionality. The `Kernel` acts as the engine for processing instructions, managing state, and invoking the necessary AI services that power the agent's behavior. -The [_Chat Completion Agent_](./chat-completion-agent.md) and [_OpenAI Assistant Agent_](./assistant-agent.md) articles provide specific details on how to create each type of agent. +The [`ChatCompletionAgent`](./chat-completion-agent.md) and [`OpenAIAssistantAgent`](./assistant-agent.md) articles provide specific details on how to create each type of agent. These resources offer step-by-step instructions and highlight the key configurations needed to tailor the agents to different conversational or task-based applications, demonstrating how the Kernel enables dynamic and intelligent agent behaviors across diverse use cases. #### Related API's: @@ -136,7 +136,7 @@ Plugins are a fundamental aspect of the _Semantic Kernel_, enabling developers t #### Example: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) #### Related API's: @@ -169,7 +169,7 @@ Plugins are a fundamental aspect of the _Semantic Kernel_, enabling developers t Agent messaging, including both input and response, is built upon the core content types of the _Semantic Kernel_, providing a unified structure for communication. This design choice simplifies the process of transitioning from traditional chat-completion patterns to more advanced agent-driven patterns in your application development. By leveraging familiar _Semantic Kernel_ content types, developers can seamlessly integrate agent capabilities into their applications without needing to overhaul existing systems. This streamlining ensures that as you evolve from basic conversational AI to more autonomous, task-oriented agents, the underlying framework remains consistent, making development faster and more efficient. -> Note: The [_OpenAI Assistant Agent_`_](./assistant-agent.md) introduced content types specific to its usage for _File References_ and _Content Annotation_: +> Note: The [`OpenAIAssistantAgent`](./assistant-agent.md) introduced content types specific to its usage for _File References_ and _Content Annotation_: #### Related API's: @@ -205,13 +205,13 @@ Agent messaging, including both input and response, is built upon the core conte ### [Templating](./agent-templates.md) -An agent's role is primarily shaped by the instructions it receives, which dictate its behavior and actions. Similar to invoking a _Kernel_ [prompt](../../concepts/prompts/index.md), an agent's instructions can include templated parameters—both values and functions—that are dynamically substituted during execution. This enables flexible, context-aware responses, allowing the agent to adjust its output based on real-time input. +An agent's role is primarily shaped by the instructions it receives, which dictate its behavior and actions. Similar to invoking a `Kernel` [prompt](../../concepts/prompts/index.md), an agent's instructions can include templated parameters—both values and functions—that are dynamically substituted during execution. This enables flexible, context-aware responses, allowing the agent to adjust its output based on real-time input. Additionally, an agent can be configured directly using a _Prompt Template Configuration_, providing developers with a structured and reusable way to define its behavior. This approach offers a powerful tool for standardizing and customizing agent instructions, ensuring consistency across various use cases while still maintaining dynamic adaptability. #### Example: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) #### Related API's: @@ -245,7 +245,7 @@ Additionally, an agent can be configured directly using a _Prompt Template Confi ### [Chat Completion](./chat-completion-agent.md) -The [_Chat Completion Agent_](./chat-completion-agent.md) is designed around any _Semantic Kernel_ [AI service](../../concepts/ai-services/chat-completion/index.md), offering a flexible and convenient persona encapsulation that can be seamlessly integrated into a wide range of applications. This agent allows developers to easily bring conversational AI capabilities into their systems without having to deal with complex implementation details. It mirrors the features and patterns found in the underlying [AI service](../../concepts/ai-services/chat-completion/index.md), ensuring that all functionalities—such as natural language processing, dialogue management, and contextual understanding—are fully supported within the [_Chat Completion Agent_](./chat-completion-agent.md), making it a powerful tool for building conversational interfaces. +The [`ChatCompletionAgent`](./chat-completion-agent.md) is designed around any _Semantic Kernel_ [AI service](../../concepts/ai-services/chat-completion/index.md), offering a flexible and convenient persona encapsulation that can be seamlessly integrated into a wide range of applications. This agent allows developers to easily bring conversational AI capabilities into their systems without having to deal with complex implementation details. It mirrors the features and patterns found in the underlying [AI service](../../concepts/ai-services/chat-completion/index.md), ensuring that all functionalities—such as natural language processing, dialogue management, and contextual understanding—are fully supported within the [`ChatCompletionAgent`](./chat-completion-agent.md), making it a powerful tool for building conversational interfaces. #### Related API's: diff --git a/semantic-kernel/Frameworks/agent/agent-chat.md b/semantic-kernel/Frameworks/agent/agent-chat.md index bf59e765..d0eb6c7c 100644 --- a/semantic-kernel/Frameworks/agent/agent-chat.md +++ b/semantic-kernel/Frameworks/agent/agent-chat.md @@ -8,10 +8,10 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# Exploring Agent Collaboration in _Agent Chat_ +# Exploring Agent Collaboration in `AgentChat` -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the experimental stage. Features at this stage are still under development and subject to change before advancing to the preview or release candidate stage. Detailed API documentation related to this discussion is available at: @@ -36,22 +36,22 @@ Detailed API documentation related to this discussion is available at: ::: zone-end -## What is _Agent Chat_? +## What is `AgentChat`? -_Agent Chat_ provides a framework that enables interaction between multiple agents, even if they are of different types. This makes it possible for a [_Chat Completion Agent_](./chat-completion-agent.md) and an [_OpenAI Assistant Agent_](./assistant-agent.md) to work together within the same conversation. _Agent Chat_ also defines entry points for initiating collaboration between agents, whether through multiple responses or a single agent response. +`AgentChat` provides a framework that enables interaction between multiple agents, even if they are of different types. This makes it possible for a [`ChatCompletionAgent`](./chat-completion-agent.md) and an [`OpenAIAssistantAgent`](./assistant-agent.md) to work together within the same conversation. `AgentChat` also defines entry points for initiating collaboration between agents, whether through multiple responses or a single agent response. -As an abstract class, _Agent Chat_ can be subclassed to support custom scenarios. +As an abstract class, `AgentChat` can be subclassed to support custom scenarios. -One such subclass, _Agent Group Chat_, offers a concrete implementation of _Agent Chat_, using a strategy-based approach to manage conversation dynamics. +One such subclass, `AgentGroupChat`, offers a concrete implementation of `AgentChat`, using a strategy-based approach to manage conversation dynamics. -## Creating an _Agent Group Chat_ +## Creating an `AgentGroupChat` -To create an _Agent Group Chat_, you may either specify the participating agents or create an empty chat and subsequently add agent participants. Configuring the _Chat-Settings_ and _Strategies_ is also performed during _Agent Group Chat_ initialization. These settings define how the conversation dynamics will function within the group. +To create an `AgentGroupChat`, you may either specify the participating agents or create an empty chat and subsequently add agent participants. Configuring the _Chat-Settings_ and _Strategies_ is also performed during `AgentGroupChat` initialization. These settings define how the conversation dynamics will function within the group. -> Note: The default _Chat-Settings_ result in a conversation that is limited to a single response. See [_Agent Chat_ Behavior](#defining-agent-group-chat-behavior) for details on configuring _Chat-Settings. +> Note: The default _Chat-Settings_ result in a conversation that is limited to a single response. See [`AgentChat` Behavior](#defining-agentgroupchat-behavior) for details on configuring _Chat-Settings. -#### Creating _Agent Group Chat_ with _Agents_: +#### Creating an `AgentGroupChat` with an `Agent`: ::: zone pivot="programming-language-csharp" ```csharp @@ -81,7 +81,7 @@ chat = AgentGroupChat(agents=[agent1, agent2]) ::: zone-end -#### Adding _Agents_ to a _Agent Group Chat_: +#### Adding an `Agent` to an `AgentGroupChat`: ::: zone pivot="programming-language-csharp" ```csharp @@ -120,13 +120,13 @@ chat.add_agent(agent=agent2) ::: zone-end -## Using _Agent Group Chat_ +## Using `AgentGroupChat` -_Agent Chat_ supports two modes of operation: _Single-Turn_ and _Multi-Turn_. In _single-turn_, a specific agent is designated to provide a response. In _multi-turn_, all agents in the conversation take turns responding until a termination criterion is met. In both modes, agents can collaborate by responding to one another to achieve a defined goal. +`AgentChat` supports two modes of operation: `Single-Turn` and `Multi-Turn`. In `single-turn`, a specific agent is designated to provide a response. In `multi-turn`, all agents in the conversation take turns responding until a termination criterion is met. In both modes, agents can collaborate by responding to one another to achieve a defined goal. ### Providing Input -Adding an input message to an _Agent Chat_ follows the same pattern as whit a _Chat History_ object. +Adding an input message to an `AgentChat` follows the same pattern as whit a `ChatHistory` object. ::: zone pivot="programming-language-csharp" ```csharp @@ -140,7 +140,7 @@ chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, "") ```python chat = AgentGroupChat() -await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content="")) +await chat.add_chat_message(message="") ``` ::: zone-end @@ -154,7 +154,7 @@ await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=" Note: The most recent message is provided first (descending order: newest to oldest). @@ -280,7 +280,7 @@ history = await chat.get_chat_messages() ::: zone-end -Since different agent types or configurations may maintain their own version of the conversation history, agent specific history is also available by specifing an agent. (For example: [_OpenAI Assistant_](./assistant-agent.md) versus [_Chat Completion Agent_](./chat-completion-agent.md).) +Since different agent types or configurations may maintain their own version of the conversation history, agent specific history is also available by specifing an agent. (For example: [`OpenAIAssistant`](./assistant-agent.md) versus [`ChatCompletionAgent`](./chat-completion-agent.md).) ::: zone pivot="programming-language-csharp" ```csharp @@ -319,7 +319,7 @@ history2 = await chat.get_chat_messages(agent=agent2) ::: zone-end -## Defining _Agent Group Chat_ Behavior +## Defining `AgentGroupChat` Behavior Collaboration among agents to solve complex tasks is a core agentic pattern. To use this pattern effectively, a system must be in place that not only determines which agent should respond during each turn but also assesses when the conversation has achieved its intended goal. This requires managing agent selection and establishing clear criteria for conversation termination, ensuring seamless cooperation between agents toward a solution. Both of these aspects are governed by the _Execution Settings_ property. @@ -329,7 +329,7 @@ The following sections, [Agent Selection](#agent-selection) and [Chat Terminatio In multi-turn invocation, agent selection is guided by a _Selection Strategy_. This strategy is defined by a base class that can be extended to implement custom behaviors tailored to specific needs. For convenience, two predefined concrete _Selection Strategies_ are also available, offering ready-to-use approaches for handling agent selection during conversations. -If known, an initial agent may be specified to always take the first turn. A history reducer may also be employed to limit token usage when using a strategy based on a _Kernel Function_. +If known, an initial agent may be specified to always take the first turn. A history reducer may also be employed to limit token usage when using a strategy based on a `KernelFunction`. ::: zone pivot="programming-language-csharp" @@ -414,14 +414,12 @@ REVIEWER_NAME = "Reviewer" WRITER_NAME = "Writer" agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, kernel=kernel, name=REVIEWER_NAME, instructions="", ) agent_writer = ChatCompletionAgent( - service_id=WRITER_NAME, kernel=kernel, name=WRITER_NAME, instructions="", @@ -472,7 +470,7 @@ chat = AgentGroupChat( In _multi-turn_ invocation, the _Termination Strategy_ dictates when the final turn takes place. This strategy ensures the conversation ends at the appropriate point. -This strategy is defined by a base class that can be extended to implement custom behaviors tailored to specific needs. For convenience, serveral predefined concrete _Selection Strategies_ are also available, offering ready-to-use approaches for defining termination criteria for an _Agent Chat_ conversations. +This strategy is defined by a base class that can be extended to implement custom behaviors tailored to specific needs. For convenience, serveral predefined concrete _Selection Strategies_ are also available, offering ready-to-use approaches for defining termination criteria for an `AgentChat` conversations. ::: zone pivot="programming-language-csharp" @@ -549,14 +547,12 @@ REVIEWER_NAME = "Reviewer" WRITER_NAME = "Writer" agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, kernel=kernel, name=REVIEWER_NAME, instructions="", ) agent_writer = ChatCompletionAgent( - service_id=WRITER_NAME, kernel=kernel, name=WRITER_NAME, instructions="", @@ -595,7 +591,7 @@ chat = AgentGroupChat( ### Resetting Chat Completion State -Regardless of whether _Agent Group Chat_ is invoked using the single-turn or multi-turn approach, the state of the _Agent Group Chat_ is updated to indicate it is _completed_ once the termination criteria is met. This ensures that the system recognizes when a conversation has fully concluded. To continue using an _Agent Group Chat_ instance after it has reached the _Completed_ state, this state must be reset to allow further interactions. Without resetting, additional interactions or agent responses will not be possible. +Regardless of whether `AgentGroupChat` is invoked using the single-turn or multi-turn approach, the state of the `AgentGroupChat` is updated to indicate it is _completed_ once the termination criteria is met. This ensures that the system recognizes when a conversation has fully concluded. To continue using an `AgentGroupChat` instance after it has reached the _Completed_ state, this state must be reset to allow further interactions. Without resetting, additional interactions or agent responses will not be possible. In the case of a multi-turn invocation that reaches the maximum turn limit, the system will cease agent invocation but will not mark the instance as _completed_. This allows for the possibility of extending the conversation without needing to reset the _Completion_ state. @@ -636,9 +632,9 @@ if chat.is_complete: ### Clear Full Conversation State -When done using an _Agent Chat_ where an [_OpenAI Assistant_](./assistant-agent.md) participated, it may be necessary to delete the remote _thread_ associated with the _assistant_. _Agent Chat_ supports resetting or clearing the entire conversation state, which includes deleting any remote _thread_ definition. This ensures that no residual conversation data remains linked to the assistant once the chat concludes. +When done using an `AgentChat` where an [`OpenAIAssistant`](./assistant-agent.md) participated, it may be necessary to delete the remote _thread_ associated with the _assistant_. `AgentChat` supports resetting or clearing the entire conversation state, which includes deleting any remote _thread_ definition. This ensures that no residual conversation data remains linked to the assistant once the chat concludes. -A full reset does not remove the _agents_ that had joined the _Agent Chat_ and leaves the _Agent Chat_ in a state where it can be reused. This allows for the continuation of interactions with the same agents without needing to reinitialize them, making future conversations more efficient. +A full reset does not remove the _agents_ that had joined the `AgentChat` and leaves the `AgentChat` in a state where it can be reused. This allows for the continuation of interactions with the same agents without needing to reinitialize them, making future conversations more efficient. ::: zone pivot="programming-language-csharp" ```csharp @@ -669,9 +665,9 @@ await chat.reset() ## How-To -For an end-to-end example for using _Agent Group Chat_ for _Agent_ collaboration, see: +For an end-to-end example for using `AgentGroupChat` for `Agent` collaboration, see: -- [How to Coordinate Agent Collaboration using _Agent Group Chat_](./examples/example-agent-collaboration.md) +- [How to Coordinate Agent Collaboration using `AgentGroupChat`](./examples/example-agent-collaboration.md) > [!div class="nextstepaction"] diff --git a/semantic-kernel/Frameworks/agent/agent-functions.md b/semantic-kernel/Frameworks/agent/agent-functions.md index 3ada7e4f..879703b6 100644 --- a/semantic-kernel/Frameworks/agent/agent-functions.md +++ b/semantic-kernel/Frameworks/agent/agent-functions.md @@ -1,5 +1,5 @@ --- -title: Configuring Agents with Semantic Kernel Plugins. (Experimental) +title: Configuring Agents with Semantic Kernel Plugins. description: Describes how to use Semantic Kernal plugins and function calling with agents. zone_pivot_groups: programming-languages author: crickman @@ -10,14 +10,14 @@ ms.service: semantic-kernel --- # Configuring Agents with Semantic Kernel Plugins -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## Functions and Plugins in Semantic Kernel -Function calling is a powerful tool that allows developers to add custom functionalities and expand the capabilities of AI applications. The _Semantic Kernel_ [Plugin](../../concepts/plugins/index.md) architecture offers a flexible framework to support [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md). For an _Agent_, integrating [Plugins](../../concepts/plugins/index.md) and [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is built on this foundational _Semantic Kernel_ feature. +Function calling is a powerful tool that allows developers to add custom functionalities and expand the capabilities of AI applications. The _Semantic Kernel_ [Plugin](../../concepts/plugins/index.md) architecture offers a flexible framework to support [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md). For an `Agent`, integrating [Plugins](../../concepts/plugins/index.md) and [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is built on this foundational _Semantic Kernel_ feature. -Once configured, an agent will choose when and how to call an available function, as it would in any usage outside of the _Agent Framework_. +Once configured, an agent will choose when and how to call an available function, as it would in any usage outside of the `Agent Framework`. ::: zone pivot="programming-language-csharp" @@ -46,11 +46,11 @@ Once configured, an agent will choose when and how to call an available function ## Adding Plugins to an Agent -Any [Plugin](../../concepts/plugins/index.md) available to an _Agent_ is managed within its respective _Kernel_ instance. This setup enables each _Agent_ to access distinct functionalities based on its specific role. +Any [Plugin](../../concepts/plugins/index.md) available to an `Agent` is managed within its respective `Kernel` instance. This setup enables each `Agent` to access distinct functionalities based on its specific role. -[Plugins](../../concepts/plugins/index.md) can be added to the _Kernel_ either before or after the _Agent_ is created. The process of initializing [Plugins](../../concepts/plugins/index.md) follows the same patterns used for any _Semantic Kernel_ implementation, allowing for consistency and ease of use in managing AI capabilities. +[Plugins](../../concepts/plugins/index.md) can be added to the `Kernel` either before or after the `Agent` is created. The process of initializing [Plugins](../../concepts/plugins/index.md) follows the same patterns used for any _Semantic Kernel_ implementation, allowing for consistency and ease of use in managing AI capabilities. -> Note: For a [_Chat Completion Agent_](./chat-completion-agent.md), the function calling mode must be explicitly enabled. [_OpenAI Assistant_](./assistant-agent.md) agent is always based on automatic function calling. +> Note: For a [`ChatCompletionAgent`](./chat-completion-agent.md), the function calling mode must be explicitly enabled. [`OpenAIAssistant`](./assistant-agent.md) agent is always based on automatic function calling. ::: zone pivot="programming-language-csharp" ```csharp @@ -85,18 +85,46 @@ ChatCompletionAgent CreateSpecificAgent(Kernel kernel, string credentials) ::: zone-end ::: zone pivot="programming-language-python" + +There are two ways to create a `ChatCompletionAgent` with plugins. + +#### Method 1: Specify Plugins via the Constructor + +You can directly pass a list of plugins to the constructor: + ```python +from semantic_kernel.agents import ChatCompletionAgent + +# Create the Chat Completion Agent instance by specifying a list of plugins +agent = ChatCompletionAgent( + service=AzureChatCompletion(), + instructions="", + plugins=[SamplePlugin()] +) +``` + +> [!TIP] +> By default, auto-function calling is enabled. To disable it, set the `function_choice_behavior` argument to `function_choice_behavior=FunctionChoiceBehavior.Auto(auto_invoke=False)` in the constructor. With this setting, plugins are still broadcast to the model, but they are not automatically invoked. If execution settings specify the same `service_id` or `ai_model_id` as the AI service configuration, the function calling behavior defined in the execution settings (via `KernelArguments`) will take precedence over the function choice behavior set in the constructor. + +#### Method 2: Configure the Kernel Manually + +If no kernel is provided via the constructor, one is automatically created during model validation. Any plugins passed in take precedence and are added to the kernel. For more fine-grained control over the kernel's state, follow these steps: + +```python +from semantic_kernel.agents import ChatCompletionAgent +from semantic_kernel.connectors.ai import FunctionChoiceBehavior +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings +from semantic_kernel.functions import KernelFunctionFromPrompt +from semantic_kernel.kernel import Kernel + # Create the instance of the Kernel kernel = Kernel() -# Define the service ID -service_id = "" - # Add the chat completion service to the Kernel -kernel.add_service(AzureChatCompletion(service_id=service_id)) +kernel.add_service(AzureChatCompletion()) -# Get the AI Service settings for the specified service_id -settings = kernel.get_prompt_execution_settings_from_service_id(service_id=service_id) +# Get the AI Service settings +settings = kernel.get_prompt_execution_settings_from_service_id() # Configure the function choice behavior to auto invoke kernel functions settings.function_choice_behavior = FunctionChoiceBehavior.Auto() @@ -106,13 +134,16 @@ kernel.add_plugin(SamplePlugin(), plugin_name="") # Create the agent agent = ChatCompletionAgent( - service_id=service_id, kernel=kernel, name=, instructions=, arguments=KernelArguments(settings=settings), ) ``` + +> [!TIP] +> If a `service_id` is not specified when adding a service to the kernel, it defaults to `default`. When configuring multiple AI services on the kernel, it’s recommended to differentiate them using the `service_id` argument. This allows you to retrieve execution settings for a specific `service_id` and tie those settings to the desired service. + ::: zone-end ::: zone pivot="programming-language-java" @@ -160,27 +191,35 @@ ChatCompletionAgent CreateSpecificAgent(Kernel kernel) ::: zone pivot="programming-language-python" ```python +from semantic_kernel.agents import ChatCompletionAgent +from semantic_kernel.connectors.ai import FunctionChoiceBehavior +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion, AzureChatPromptExecutionSettings +from semantic_kernel.functions import KernelFunctionFromPrompt +from semantic_kernel.kernel import Kernel + # Create the instance of the Kernel kernel = Kernel() -# Define the service ID -service_id = "" - # Add the chat completion service to the Kernel -kernel.add_service(AzureChatCompletion(service_id=service_id)) +kernel.add_service(AzureChatCompletion()) -# Get the AI Service settings for the specified service_id -settings = kernel.get_prompt_execution_settings_from_service_id(service_id=service_id) +# Create the AI Service settings +settings = AzureChatPromptExecutionSettings() # Configure the function choice behavior to auto invoke kernel functions settings.function_choice_behavior = FunctionChoiceBehavior.Auto() # Add the Plugin to the Kernel -kernel.add_plugin(SamplePlugin(), plugin_name="") +kernel.add_function( + plugin_name="", + function=KernelFunctionFromPrompt( + function_name="", + prompt="", + ) +) # Create the agent agent = ChatCompletionAgent( - service_id=service_id, kernel=kernel, name=, instructions=, @@ -198,14 +237,14 @@ agent = ChatCompletionAgent( ## Limitations for Agent Function Calling -When directly invoking a[_Chat Completion Agent_](./chat-completion-agent.md), all _Function Choice Behaviors_ are supported. However, when using an [_OpenAI Assistant_](./assistant-agent.md) or [_Agent Chat_](./agent-chat.md), only _Automatic_ [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is currently available. +When directly invoking a[`ChatCompletionAgent`](./chat-completion-agent.md), all _Function Choice Behaviors_ are supported. However, when using an [`OpenAIAssistant`](./assistant-agent.md) or [`AgentChat`](./agent-chat.md), only _Automatic_ [Function Calling](../../concepts/ai-services/chat-completion/function-calling/index.md) is currently available. ## How-To For an end-to-end example for using function calling, see: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) > [!div class="nextstepaction"] diff --git a/semantic-kernel/Frameworks/agent/agent-streaming.md b/semantic-kernel/Frameworks/agent/agent-streaming.md index eac08b71..0c0c340b 100644 --- a/semantic-kernel/Frameworks/agent/agent-streaming.md +++ b/semantic-kernel/Frameworks/agent/agent-streaming.md @@ -1,5 +1,5 @@ --- -title: How to Stream Agent Responses. (Experimental) +title: How to Stream Agent Responses. description: Describes how to utilize streamed responses for agents and agent chat. zone_pivot_groups: programming-languages author: crickman @@ -10,8 +10,8 @@ ms.service: semantic-kernel --- # How to Stream Agent Responses -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## What is a Streamed Response? @@ -54,11 +54,11 @@ A streamed response delivers the message content in small, incremental chunks. T ## Streaming Agent Invocation -The _Agent Framework_ supports _streamed_ responses when using [_Agent Chat_](./agent-chat.md) or when directly invoking a [_Chat Completion Agent_](./chat-completion-agent.md) or [_OpenAI Assistant Agent_](./assistant-agent.md). In either mode, the framework delivers responses asynchronously as they are streamed. Alongside the streamed response, a consistent, non-streamed history is maintained to track the conversation. This ensures both real-time interaction and a reliable record of the conversation's flow. +The `Agent Framework` supports _streamed_ responses when using [`AgentChat`](./agent-chat.md) or when directly invoking a [`ChatCompletionAgent`](./chat-completion-agent.md) or [`OpenAIAssistantAgent`](./assistant-agent.md). In either mode, the framework delivers responses asynchronously as they are streamed. Alongside the streamed response, a consistent, non-streamed history is maintained to track the conversation. This ensures both real-time interaction and a reliable record of the conversation's flow. -### Streamed response from _Chat Completion Agent_ +### Streamed response from `ChatCompletionAgent` -When invoking a streamed response from a [_Chat Completion Agent_](./chat-completion-agent.md), the _Chat History_ is updated after the full response is received. Although the response is streamed incrementally, the history records only the complete message. This ensures that the _Chat History_ reflects fully formed responses for consistency. +When invoking a streamed response from a [`ChatCompletionAgent`](./chat-completion-agent.md), the `ChatHistory` is updated after the full response is received. Although the response is streamed incrementally, the history records only the complete message. This ensures that the `ChatHistory` reflects fully formed responses for consistency. ::: zone pivot="programming-language-csharp" ```csharp @@ -104,9 +104,9 @@ async for response in agent.invoke_stream(chat) ::: zone-end -### Streamed response from _OpenAI Assistant Agent_ +### Streamed response from `OpenAIAssistantAgent` -When invoking a streamed response from an [_OpenAI Assistant Agent_](./assistant-agent.md), an optional _Chat History_ can be provided to capture the complete messages for further analysis if needed. Since the assistant maintains the conversation state as a remote thread, capturing these messages is not always necessary. The decision to store and analyze the full response depends on the specific requirements of the interaction. +When invoking a streamed response from an [`OpenAIAssistantAgent`](./assistant-agent.md), an optional `ChatHistory` can be provided to capture the complete messages for further analysis if needed. Since the assistant maintains the conversation state as a remote thread, capturing these messages is not always necessary. The decision to store and analyze the full response depends on the specific requirements of the interaction. ::: zone pivot="programming-language-csharp" ```csharp @@ -139,7 +139,7 @@ agent = OpenAIAssistantAgent(...) thread_id = await agent.create_thread() # Add user message to the conversation -await agent.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content="")) +await agent.add_chat_message(message="") # Generate the streamed agent response(s) async for response in agent.invoke_stream(thread_id=thread_id): @@ -154,9 +154,9 @@ async for response in agent.invoke_stream(thread_id=thread_id): ::: zone-end -## Streaming with _Agent Chat_ +## Streaming with `AgentChat` -When using [_Agent Chat_](./agent-chat.md), the full conversation history is always preserved and can be accessed directly through the [_Agent Chat_](./agent-chat.md) instance. Therefore, the key difference between streamed and non-streamed invocations lies in the delivery method and the resulting content type. In both cases, users can still access the complete history, but streamed responses provide real-time updates as the conversation progresses. This allows for greater flexibility in handling interactions, depending on the application's needs. +When using [`AgentChat`](./agent-chat.md), the full conversation history is always preserved and can be accessed directly through the [`AgentChat`](./agent-chat.md) instance. Therefore, the key difference between streamed and non-streamed invocations lies in the delivery method and the resulting content type. In both cases, users can still access the complete history, but streamed responses provide real-time updates as the conversation progresses. This allows for greater flexibility in handling interactions, depending on the application's needs. ::: zone pivot="programming-language-csharp" ```csharp @@ -202,6 +202,8 @@ chat = AgentGroupChat( termination_strategy=DefaultTerminationStrategy(maximum_iterations=10), ) +await chat.add_chat_message("") + # Invoke agents last_agent = None async for response in chat.invoke_stream(): diff --git a/semantic-kernel/Frameworks/agent/agent-templates.md b/semantic-kernel/Frameworks/agent/agent-templates.md index e972ea8a..35c851d4 100644 --- a/semantic-kernel/Frameworks/agent/agent-templates.md +++ b/semantic-kernel/Frameworks/agent/agent-templates.md @@ -1,5 +1,5 @@ --- -title: Create an Agent from a Semantic Kernel Template (Experimental) +title: Create an Agent from a Semantic Kernel Template description: Describes how to use a Semantic Kernel template to define an agent. zone_pivot_groups: programming-languages author: crickman @@ -10,8 +10,8 @@ ms.service: semantic-kernel --- # Create an Agent from a Semantic Kernel Template -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## Prompt Templates in Semantic Kernel @@ -95,7 +95,7 @@ agent = ChatCompletionAgent( #### OpenAI Assistant Agent -Templated instructions are especially powerful when working with an [_OpenAI Assistant Agent_](./assistant-agent.md). With this approach, a single assistant definition can be created and reused multiple times, each time with different parameter values tailored to specific tasks or contexts. This enables a more efficient setup, allowing the same assistant framework to handle a wide range of scenarios while maintaining consistency in its core behavior. +Templated instructions are especially powerful when working with an [`OpenAIAssistantAgent`](./assistant-agent.md). With this approach, a single assistant definition can be created and reused multiple times, each time with different parameter values tailored to specific tasks or contexts. This enables a more efficient setup, allowing the same assistant framework to handle a wide range of scenarios while maintaining consistency in its core behavior. ::: zone pivot="programming-language-csharp" ```csharp @@ -208,7 +208,7 @@ agent = ChatCompletionAgent( ### Overriding Template Values for Direct Invocation -When invoking an agent directly, without using [_Agent Chat_](./agent-chat.md), the agent's parameters can be overridden as needed. This allows for greater control and customization of the agent's behavior during specific tasks, enabling you to modify its instructions or settings on the fly to suit particular requirements. +When invoking an agent directly, without using [`AgentChat`](./agent-chat.md), the agent's parameters can be overridden as needed. This allows for greater control and customization of the agent's behavior during specific tasks, enabling you to modify its instructions or settings on the fly to suit particular requirements. ::: zone pivot="programming-language-csharp" ```csharp @@ -263,6 +263,12 @@ chat = ChatHistory() override_arguments = KernelArguments(topic="Cat", length="3") +# Two ways to get a response from the agent + +# Get the response which returns a ChatMessageContent directly +response = await agent.get_response(chat, arguments=override_arguments) + +# or use the invoke method to return an AsyncIterable of ChatMessageContent async for response in agent.invoke(chat, arguments=override_arguments): # process agent response(s)... ``` @@ -280,7 +286,7 @@ async for response in agent.invoke(chat, arguments=override_arguments): For an end-to-end example for creating an agent from a _pmompt-template_, see: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) > [!div class="nextstepaction"] diff --git a/semantic-kernel/Frameworks/agent/assistant-agent.md b/semantic-kernel/Frameworks/agent/assistant-agent.md index e4d36c81..17ee3199 100644 --- a/semantic-kernel/Frameworks/agent/assistant-agent.md +++ b/semantic-kernel/Frameworks/agent/assistant-agent.md @@ -1,5 +1,5 @@ --- -title: Exploring the Semantic Kernel OpenAI Assistant Agent (Experimental) +title: Exploring the Semantic Kernel OpenAI Assistant Agent description: An exploration of the definition, behaviors, and usage patterns for a `OpenAIAssistantAgent` zone_pivot_groups: programming-languages author: crickman @@ -8,10 +8,10 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# Exploring the _Semantic Kernel_ _OpenAI Assistant Agent_ +# Exploring the _Semantic Kernel_ `OpenAIAssistantAgent` -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. Detailed API documentation related to this discussion is available at: @@ -24,7 +24,6 @@ Detailed API documentation related to this discussion is available at: ::: zone pivot="programming-language-python" -- [`open_ai_assistant_base`](/python/api/semantic-kernel/semantic_kernel.agents.open_ai.open_ai_assistant_base) - [`azure_assistant_agent`](/python/api/semantic-kernel/semantic_kernel.agents.open_ai.azure_assistant_agent) - [`open_ai_assistant_agent`](/python/api/semantic-kernel/semantic_kernel.agents.open_ai.open_ai_assistant_agent) @@ -46,9 +45,9 @@ The _OpenAI Assistant API_ is a specialized interface designed for more advanced - [Assistant API in Azure](/azure/ai-services/openai/assistants-quickstart) -## Creating an _OpenAI Assistant Agent_ +## Creating an `OpenAIAssistantAgent` -Creating an _OpenAI Assistant_ requires invoking a remote service, which is handled asynchronously. To manage this, the _OpenAI Assistant Agent_ is instantiated through a static factory method, ensuring the process occurs in a non-blocking manner. This method abstracts the complexity of the asynchronous call, returning a promise or future once the assistant is fully initialized and ready for use. +Creating an `OpenAIAssistant` requires invoking a remote service, which is handled asynchronously. To manage this, the `OpenAIAssistantAgent` is instantiated through a static factory method, ensuring the process occurs in a non-blocking manner. This method abstracts the complexity of the asynchronous call, returning a promise or future once the assistant is fully initialized and ready for use. ::: zone pivot="programming-language-csharp" ```csharp @@ -66,20 +65,40 @@ OpenAIAssistantAgent agent = ::: zone pivot="programming-language-python" ```python -azure_agent = await AzureAssistantAgent.create( - kernel=kernel, - service_id=service_id, - name="", - instructions="" +from semantic_kernel.agents.open_ai import AzureAssistantAgent, OpenAIAssistantAgent + +# Set up the client and model using Azure OpenAI Resources +client, model = AzureAssistantAgent.setup_resources() + +# Define the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, ) # or -openai_agent = await OpenAIAssistantAgent.create( - kernel=kernel, - service_id=service_id, - name="", - instructions="" +# Set up the client and model using OpenAI Resources +client, model = OpenAIAssistantAgent.setup_resources() + +# Define the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the OpenAIAssistantAgent instance using the client and the assistant definition +agent = OpenAIAssistantAgent( + client=client, + definition=definition, ) ``` ::: zone-end @@ -91,9 +110,9 @@ openai_agent = await OpenAIAssistantAgent.create( ::: zone-end -## Retrieving an _OpenAI Assistant Agent_ +## Retrieving an `OpenAIAssistantAgent` -Once created, the identifier of the assistant may be access via its identifier. This identifier may be used to create an _OpenAI Assistant Agent_ from an existing assistant definition. +Once created, the identifier of the assistant may be access via its identifier. This identifier may be used to create an `OpenAIAssistantAgent` from an existing assistant definition. ::: zone pivot="programming-language-csharp" @@ -110,11 +129,29 @@ OpenAIAssistantAgent agent = ::: zone pivot="programming-language-python" ```python -agent = await OpenAIAssistantAgent.retrieve(id=agent_id, kernel=kernel) +# Using Azure OpenAI Resources -# or +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + name="", + instructions="", +) -agent = await AzureAssistantAgent.retrieve(id=agent_id, kernel=kernel) +# Store the assistant ID +assistant_id = definition.id + +# Retrieve the assistant definition from the server based on the assistant ID +new_asst_definition = await client.beta.assistants.retrieve(assistant_id) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=new_asst_definition, +) ``` ::: zone-end @@ -125,9 +162,9 @@ agent = await AzureAssistantAgent.retrieve(id=agent_id, kernel=kernel) ::: zone-end -## Using an _OpenAI Assistant Agent_ +## Using an `OpenAIAssistantAgent` -As with all aspects of the _Assistant API_, conversations are stored remotely. Each conversation is referred to as a _thread_ and identified by a unique `string` identifier. Interactions with your _OpenAI Assistant Agent_ are tied to this specific thread identifier which must be specified when calling the agent/ +As with all aspects of the _Assistant API_, conversations are stored remotely. Each conversation is referred to as a _thread_ and identified by a unique `string` identifier. Interactions with your `OpenAIAssistantAgent` are tied to this specific thread identifier which must be specified when calling the agent/ ::: zone pivot="programming-language-csharp" ```csharp @@ -181,7 +218,7 @@ await agent.delete_thread(thread_id) ::: zone-end -## Deleting an _OpenAI Assistant Agent_ +## Deleting an `OpenAIAssistantAgent` Since the assistant's definition is stored remotely, it supports the capability to self-delete. This enables the agent to be removed from the system when it is no longer needed. @@ -217,12 +254,12 @@ is_deleted = agent._is_deleted ## How-To -For an end-to-end example for a _OpenAI Assistant Agent_, see: +For an end-to-end example for a `OpenAIAssistantAgent`, see: -- [How-To: _OpenAI Assistant Agent_ Code Interpreter](./examples/example-assistant-code.md) -- [How-To: _OpenAI Assistant Agent_ File Search](./examples/example-assistant-search.md) +- [How-To: `OpenAIAssistantAgent` Code Interpreter](./examples/example-assistant-code.md) +- [How-To: `OpenAIAssistantAgent` File Search](./examples/example-assistant-search.md) > [!div class="nextstepaction"] -> [Agent Collaboration in _Agent Chat_](./agent-chat.md) +> [Agent Collaboration in `AgentChat`](./agent-chat.md) diff --git a/semantic-kernel/Frameworks/agent/chat-completion-agent.md b/semantic-kernel/Frameworks/agent/chat-completion-agent.md index b3e7a40d..d1044239 100644 --- a/semantic-kernel/Frameworks/agent/chat-completion-agent.md +++ b/semantic-kernel/Frameworks/agent/chat-completion-agent.md @@ -1,5 +1,5 @@ --- -title: Exploring the Semantic Kernel Chat Completion Agent (Experimental) +title: Exploring the Semantic Kernel Chat Completion Agent description: An exploration of the definition, behaviors, and usage patterns for a Chat Completion Agent zone_pivot_groups: programming-languages author: crickman @@ -10,8 +10,8 @@ ms.service: semantic-kernel --- # Exploring the _Semantic Kernel_ Chat Completion Agent -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. Detailed API documentation related to this discussion is available at: @@ -76,7 +76,7 @@ Onnx|[`Microsoft.SemanticKernel.Connectors.Onnx`](/dotnet/api/microsoft.semantic ## Creating a Chat Completion Agent -A _chat completion agent_ is fundamentally based on an [AI services](../../concepts/ai-services/index.md). As such, creating an _chat completion agent_ starts with creating a [_Kernel_](../../concepts/kernel.md) instance that contains one or more chat-completion services and then instantiating the agent with a reference to that [_Kernel_](../../concepts/kernel.md) instance. +A _chat completion agent_ is fundamentally based on an [AI services](../../concepts/ai-services/index.md). As such, creating an _chat completion agent_ starts with creating a [`Kernel`](../../concepts/kernel.md) instance that contains one or more chat-completion services and then instantiating the agent with a reference to that [`Kernel`](../../concepts/kernel.md) instance. ::: zone pivot="programming-language-csharp" ```csharp @@ -104,11 +104,10 @@ ChatCompletionAgent agent = kernel = Kernel() # Add the AzureChatCompletion AI Service to the Kernel -kernel.add_service(AzureChatCompletion(service_id="")) +kernel.add_service(AzureChatCompletion()) # Create the agent agent = ChatCompletionAgent( - service_id="agent", kernel=kernel, name="", instructions="", @@ -125,9 +124,9 @@ agent = ChatCompletionAgent( ## AI Service Selection -No different from using _Semantic Kernel_ [AI services](../../concepts/ai-services/index.md) directly, a _chat completion agent_ support the specification of a _service-selector_. A _service-selector_ indentifies which [AI service](../../concepts/ai-services/index.md) to target when the [_Kernel_](../../concepts/kernel.md) contains more than one. +No different from using _Semantic Kernel_ [AI services](../../concepts/ai-services/index.md) directly, a `ChatCompletionAgent` supports the specification of a _service-selector_. A _service-selector_ indentifies which [AI service](../../concepts/ai-services/index.md) to target when the [`Kernel`](../../concepts/kernel.md) contains more than one. -> Note: If multiple [AI services](../../concepts/ai-services/index.md) are present and no _service-selector_ is provided, the same _default_ logic is applied for the agent that you'd find when using an [AI services](../../concepts/ai-services/index.md) outside of the _Agent Framework_ +> Note: If multiple [AI services](../../concepts/ai-services/index.md) are present and no _service-selector_ is provided, the same _default_ logic is applied for the agent that you'd find when using an [AI services](../../concepts/ai-services/index.md) outside of the `Agent Framework` ::: zone pivot="programming-language-csharp" ```csharp @@ -157,18 +156,26 @@ ChatCompletionAgent agent = ::: zone pivot="programming-language-python" ```python +from semantic_kernel.connectors.ai.open_ai import ( + AzureChatCompletion, + AzureChatPromptExecutionSettings, +) + # Define the Kernel kernel = Kernel() # Add the AzureChatCompletion AI Service to the Kernel -kernel.add_service(AzureChatCompletion(service_id="")) +kernel.add_service(AzureChatCompletion(service_id="service1")) +kernel.add_service(AzureChatCompletion(service_id="service2")) + +settings = AzureChatPromptExecutionSettings(service_id="service2") # Create the agent agent = ChatCompletionAgent( - service_id="agent", kernel=kernel, name="", instructions="", + arguments=KernelArguments(settings=settings) ) ``` ::: zone-end @@ -179,11 +186,12 @@ agent = ChatCompletionAgent( ::: zone-end -## Conversing with _Chat Completion Agent_ - -Conversing with your _Chat Completion Agent_ is based on a _Chat History_ instance, no different from interacting with a _Chat Completion_ [AI service](../../concepts/ai-services/index.md). +## Conversing with `ChatCompletionAgent` ::: zone pivot="programming-language-csharp" + +Conversing with your `ChatCompletionAgent` is based on a `ChatHistory` instance, no different from interacting with a _Chat Completion_ [AI service](../../concepts/ai-services/index.md). + ```csharp // Define agent ChatCompletionAgent agent = ...; @@ -203,6 +211,11 @@ await foreach (ChatMessageContent response in agent.InvokeAsync(chat)) ::: zone-end ::: zone pivot="programming-language-python" + +There are multiple ways to converse with a `ChatCompletionAgent`. + +The easiest is to call and await `get_response`: + ```python # Define agent agent = ChatCompletionAgent(...) @@ -213,10 +226,44 @@ chat = ChatHistory() # Add the user message chat.add_message(ChatMessageContent(role=AuthorRole.USER, content=input)) +# Generate the agent response +response = await agent.get_response(chat) +# response is a `ChatMessageContent` object +``` +Otherwise, calling the `invoke` method returns an `AsyncIterable` of `ChatMessageContent`. + +```python +# Define agent +agent = ChatCompletionAgent(...) + +# Define the chat history +chat = ChatHistory() + +# Add the user message +chat.add_user_message(ChatMessageContent(role=AuthorRole.USER, content=input)) + # Generate the agent response(s) async for response in agent.invoke(chat): # process agent response(s) ``` + +The `ChatCompletionAgent` also supports streaming in which the `invoke_stream` method returns an `AsyncIterable` of `StreamingChatMessageContent`: + +```python +# Define agent +agent = ChatCompletionAgent(...) + +# Define the chat history +chat = ChatHistory() + +# Add the user message +chat.add_message(ChatMessageContent(role=AuthorRole.USER, content=input)) + +# Generate the agent response(s) +async for response in agent.invoke_stream(chat): + # process agent response(s) +``` + ::: zone-end ::: zone pivot="programming-language-java" @@ -228,10 +275,10 @@ async for response in agent.invoke(chat): #### How-To: -For an end-to-end example for a _Chat Completion Agent_, see: +For an end-to-end example for a `ChatCompletionAgent`, see: -- [How-To: _Chat Completion Agent_](./examples/example-chat-agent.md) +- [How-To: `ChatCompletionAgent`](./examples/example-chat-agent.md) > [!div class="nextstepaction"] -> [Exploring _OpenAI Assistant Agent_](./assistant-agent.md) +> [Exploring `OpenAIAssistantAgent`](./assistant-agent.md) diff --git a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md index fc11bf27..d557c7fc 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md +++ b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md @@ -10,12 +10,12 @@ ms.service: semantic-kernel --- # How-To: Coordinate Agent Collaboration using Agent Group Chat -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the experimental stage. Features at this stage are still under development and subject to change before advancing to the preview or release candidate stage. ## Overview -In this sample, we will explore how to use _Agent Group Chat_ to coordinate collboration of two different agents working to review and rewrite user provided content. Each agent is assigned a distinct role: +In this sample, we will explore how to use `AgentGroupChat` to coordinate collboration of two different agents working to review and rewrite user provided content. Each agent is assigned a distinct role: - **Reviewer**: Reviews and provides direction to _Writer_. - **Writer**: Updates user content based on _Reviewer_ input. @@ -61,7 +61,7 @@ The project file (`.csproj`) should contain the following `PackageReference` def ``` -The _Agent Framework_ is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): +The `Agent Framework` is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): ```xml @@ -81,24 +81,21 @@ Start by installing the Semantic Kernel Python package. pip install semantic-kernel ``` +Next add the required imports. + ```python import asyncio import os -import copy +from semantic_kernel import Kernel from semantic_kernel.agents import AgentGroupChat, ChatCompletionAgent -from semantic_kernel.agents.strategies.selection.kernel_function_selection_strategy import ( +from semantic_kernel.agents.strategies import ( KernelFunctionSelectionStrategy, -) -from semantic_kernel.agents.strategies.termination.kernel_function_termination_strategy import ( KernelFunctionTerminationStrategy, ) -from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.functions.kernel_function_decorator import kernel_function -from semantic_kernel.functions.kernel_function_from_prompt import KernelFunctionFromPrompt -from semantic_kernel.kernel import Kernel +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion +from semantic_kernel.contents import ChatHistoryTruncationReducer +from semantic_kernel.functions import KernelFunctionFromPrompt ``` ::: zone-end @@ -108,13 +105,12 @@ from semantic_kernel.kernel import Kernel ::: zone-end - ## Configuration -This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_. - ::: zone pivot="programming-language-csharp" +This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_. + ```powershell # OpenAI dotnet user-secrets set "OpenAISettings:ApiKey" "" @@ -173,7 +169,7 @@ public class Settings ::: zone-end ::: zone pivot="programming-language-python" -The quickest way to get started with the proper configuration to run the sample code is to create a `.env` file at the root of your project (where your script is run). +The quickest way to get started with the proper configuration to run the sample code is to create a `.env` file at the root of your project (where your script is run). The sample requires that you have Azure OpenAI or OpenAI resources available. Configure the following settings in your `.env` file for either Azure OpenAI or OpenAI: @@ -197,21 +193,20 @@ Once configured, the respective AI service classes will pick up the required var ::: zone-end - ## Coding The coding process for this sample involves: 1. [Setup](#setup) - Initializing settings and the plug-in. -2. [_Agent_ Definition](#agent-definition) - Create the two _Chat Completion Agent_ instances (_Reviewer_ and _Writer_). -3. [_Chat_ Definition](#chat-definition) - Create the _Agent Group Chat_ and associated strategies. +2. [`Agent` Definition](#agent-definition) - Create the two `ChatCompletionAgent` instances (_Reviewer_ and _Writer_). +3. [_Chat_ Definition](#chat-definition) - Create the `AgentGroupChat` and associated strategies. 4. [The _Chat_ Loop](#the-chat-loop) - Write the loop that drives user / agent interaction. The full example code is provided in the [Final](#final) section. Refer to that section for the complete implementation. ### Setup -Prior to creating any _Chat Completion Agent_, the configuration settings, plugins, and _Kernel_ must be initialized. +Prior to creating any `ChatCompletionAgent`, the configuration settings, plugins, and `Kernel` must be initialized. ::: zone pivot="programming-language-csharp" @@ -252,14 +247,12 @@ kernel = Kernel() ::: zone-end ::: zone pivot="programming-language-java" - > Agents are currently unavailable in Java. - ::: zone-end -Let's also create a second _Kernel_ instance via _cloning_ and add a plug-in that will allow the reivew to place updated content on the clip-board. - ::: zone pivot="programming-language-csharp" +Let's also create a second `Kernel` instance via _cloning_ and add a plug-in that will allow the reivew to place updated content on the clip-board. + ```csharp Kernel toolKernel = kernel.Clone(); toolKernel.Plugins.AddFromType(); @@ -313,7 +306,7 @@ private sealed class ClipboardAccess ### Agent Definition ::: zone pivot="programming-language-csharp" -Let's declare the agent names as `const` so they might be referenced in _Agent Group Chat_ strategies: +Let's declare the agent names as `const` so they might be referenced in `AgentGroupChat` strategies: ```csharp const string ReviewerName = "Reviewer"; @@ -374,7 +367,6 @@ ChatCompletionAgent agentReviewer = ::: zone pivot="programming-language-python" ```python agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, kernel=kernel, name=REVIEWER_NAME, instructions=""" @@ -425,7 +417,6 @@ ChatCompletionAgent agentWriter = The _Writer_ agent is similiar. It is given a single-purpose task, follow direction and rewrite the content. ```python agent_writer = ChatCompletionAgent( - service_id=WRITER_NAME, kernel=kernel, name=WRITER_NAME, instructions=""" @@ -446,9 +437,9 @@ Your sole responsibility is to rewrite content according to review suggestions. ### Chat Definition -Defining the _Agent Group Chat_ requires considering the strategies for selecting the _Agent_ turn and determining when to exit the _Chat_ loop. For both of these considerations, we will define a _Kernel Prompt Function_. +Defining the `AgentGroupChat` requires considering the strategies for selecting the `Agent` turn and determining when to exit the _Chat_ loop. For both of these considerations, we will define a _Kernel Prompt Function_. -The first to reason over _Agent_ selection: +The first to reason over `Agent` selection: ::: zone pivot="programming-language-csharp" @@ -481,8 +472,8 @@ KernelFunction selectionFunction = ::: zone pivot="programming-language-python" ```python selection_function = KernelFunctionFromPrompt( - function_name="selection", - prompt=f""" + function_name="selection", + prompt=f""" Examine the provided RESPONSE and choose the next participant. State only the name of the chosen participant without explanation. Never choose the participant named in the RESPONSE. @@ -499,7 +490,7 @@ Rules: RESPONSE: {{{{$lastmessage}}}} """ - ) +) ``` ::: zone-end @@ -532,11 +523,11 @@ KernelFunction terminationFunction = ::: zone pivot="programming-language-python" ```python - termination_keyword = "yes" +termination_keyword = "yes" - termination_function = KernelFunctionFromPrompt( - function_name="termination", - prompt=f""" +termination_function = KernelFunctionFromPrompt( + function_name="termination", + prompt=f""" Examine the RESPONSE and determine whether the content has been deemed satisfactory. If the content is satisfactory, respond with a single word without explanation: {termination_keyword}. If specific suggestions are being provided, it is not satisfactory. @@ -545,7 +536,7 @@ If no correction is suggested, it is satisfactory. RESPONSE: {{{{$lastmessage}}}} """ - ) +) ``` ::: zone-end @@ -575,7 +566,7 @@ history_reducer = ChatHistoryTruncationReducer(target_count=1) ::: zone-end -Finally we are ready to bring everything together in our _Agent Group Chat_ definition. +Finally we are ready to bring everything together in our `AgentGroupChat` definition. ::: zone pivot="programming-language-csharp" @@ -668,9 +659,9 @@ The `lastmessage` `history_variable_name` corresponds with the `KernelFunctionSe ### The _Chat_ Loop -At last, we are able to coordinate the interaction between the user and the _Agent Group Chat_. Start by creating creating an empty loop. +At last, we are able to coordinate the interaction between the user and the `AgentGroupChat`. Start by creating creating an empty loop. -> Note: Unlike the other examples, no external history or _thread_ is managed. _Agent Group Chat_ manages the conversation history internally. +> Note: Unlike the other examples, no external history or _thread_ is managed. `AgentGroupChat` manages the conversation history internally. ::: zone pivot="programming-language-csharp" ```csharp @@ -700,9 +691,9 @@ while not is_complete: Now let's capture user input within the previous loop. In this case: - Empty input will be ignored - The term `EXIT` will signal that the conversation is completed -- The term `RESET` will clear the _Agent Group Chat_ history +- The term `RESET` will clear the `AgentGroupChat` history - Any term starting with `@` will be treated as a file-path whose content will be provided as input -- Valid input will be added to the _Agent Group Chat_ as a _User_ message. +- Valid input will be added to the `AgentGroupChat` as a _User_ message. ```csharp Console.WriteLine(); @@ -753,9 +744,9 @@ chat.AddChatMessage(new ChatMessageContent(AuthorRole.User, input)); Now let's capture user input within the previous loop. In this case: - Empty input will be ignored. - The term `exit` will signal that the conversation is complete. -- The term `reset` will clear the _Agent Group Chat_ history. +- The term `reset` will clear the `AgentGroupChat` history. - Any term starting with `@` will be treated as a file-path whose content will be provided as input. -- Valid input will be added to the _Agent Group Chat_ as a _User_ message. +- Valid input will be added to the `AgentGroupChat` as a _User_ message. The operation logic inside the while loop looks like: @@ -790,7 +781,7 @@ if user_input.startswith("@") and len(user_input) > 1: continue # Add the current user_input to the chat -await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=user_input)) +await chat.add_chat_message(message=user_input) ``` ::: zone-end @@ -800,7 +791,7 @@ await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=use ::: zone-end -To initate the _Agent_ collaboration in response to user input and display the _Agent_ responses, invoke the _Agent Group Chat_; however, first be sure to reset the _Completion_ state from any prior invocation. +To initate the `Agent` collaboration in response to user input and display the `Agent` responses, invoke the `AgentGroupChat`; however, first be sure to reset the _Completion_ state from any prior invocation. > Note: Service failures are being caught and displayed to avoid crashing the conversation loop. @@ -853,7 +844,6 @@ chat.is_complete = False ::: zone-end - ## Final ::: zone pivot="programming-language-csharp" @@ -1148,24 +1138,20 @@ import os from semantic_kernel import Kernel from semantic_kernel.agents import AgentGroupChat, ChatCompletionAgent -from semantic_kernel.agents.strategies.selection.kernel_function_selection_strategy import ( +from semantic_kernel.agents.strategies import ( KernelFunctionSelectionStrategy, -) -from semantic_kernel.agents.strategies.termination.kernel_function_termination_strategy import ( KernelFunctionTerminationStrategy, ) -from semantic_kernel.connectors.ai.open_ai.services.azure_chat_completion import AzureChatCompletion -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.history_reducer.chat_history_truncation_reducer import ChatHistoryTruncationReducer -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.functions.kernel_function_from_prompt import KernelFunctionFromPrompt - -################################################################### -# The following sample demonstrates how to create a simple, # -# agent group chat that utilizes a Reviewer Chat Completion # -# Agent along with a Writer Chat Completion Agent to # -# complete a user's task. # -################################################################### +from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion +from semantic_kernel.contents import ChatHistoryTruncationReducer +from semantic_kernel.functions import KernelFunctionFromPrompt + +""" +The following sample demonstrates how to create a simple, +agent group chat that utilizes a Reviewer Chat Completion +Agent along with a Writer Chat Completion Agent to +complete a user's task. +""" # Define agent names REVIEWER_NAME = "Reviewer" @@ -1185,7 +1171,6 @@ async def main(): # Create ChatCompletionAgents using the same kernel. agent_reviewer = ChatCompletionAgent( - service_id=REVIEWER_NAME, kernel=kernel, name=REVIEWER_NAME, instructions=""" @@ -1202,7 +1187,6 @@ RULES: ) agent_writer = ChatCompletionAgent( - service_id=WRITER_NAME, kernel=kernel, name=WRITER_NAME, instructions=""" @@ -1312,7 +1296,7 @@ RESPONSE: continue # Add the current user_input to the chat - await chat.add_chat_message(ChatMessageContent(role=AuthorRole.USER, content=user_input)) + await chat.add_chat_message(message=user_input) try: async for response in chat.invoke(): diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index f8fab56a..be6fdc4d 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -1,5 +1,5 @@ --- -title: How-To: _OpenAI Assistant Agent_ Code Interpreter (Experimental) +title: How-To: `OpenAIAssistantAgent` Code Interpreter description: A step-by-step walk-through of defining and utilizing the code-interpreter tool of an OpenAI Assistant Agent. zone_pivot_groups: programming-languages author: crickman @@ -8,14 +8,14 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# How-To: _OpenAI Assistant Agent_ Code Interpreter +# How-To: `OpenAIAssistantAgent` Code Interpreter -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## Overview -In this sample, we will explore how to use the _code-interpreter_ tool of an [_OpenAI Assistant Agent_](../assistant-agent.md) to complete data-analysis tasks. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will generate both image and text responses. This will demonstrate the versatility of this tool in performing quantitative analysis. +In this sample, we will explore how to use the _code-interpreter_ tool of an [`OpenAIAssistantAgent`](../assistant-agent.md) to complete data-analysis tasks. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will generate both image and text responses. This will demonstrate the versatility of this tool in performing quantitative analysis. Streaming will be used to deliver the agent's responses. This will provide real-time updates as the task progresses. @@ -56,7 +56,7 @@ The project file (`.csproj`) should contain the following `PackageReference` def ``` -The _Agent Framework_ is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): +The `Agent Framework` is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): ```xml @@ -79,29 +79,27 @@ Additionally, copy the `PopulationByAdmin1.csv` and `PopulationByCountry.csv` da ::: zone-end ::: zone pivot="programming-language-python" + Start by creating a folder that will hold your script (`.py` file) and the sample resources. Include the following imports at the top of your `.py` file: ```python import asyncio import os -from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.streaming_file_reference_content import StreamingFileReferenceContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.kernel import Kernel +from semantic_kernel.agents.open_ai import AzureAssistantAgent +from semantic_kernel.contents import StreamingFileReferenceContent ``` Additionally, copy the `PopulationByAdmin1.csv` and `PopulationByCountry.csv` data files from the [_Semantic Kernel_ `learn_resources/resources` directory](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/learn_resources/resources). Add these files to your working directory. ::: zone-end + ::: zone pivot="programming-language-java" > Agents are currently unavailable in Java. ::: zone-end - ## Configuration This sample requires configuration setting in order to connect to remote services. You will need to define settings for either _OpenAI_ or _Azure OpenAI_. @@ -164,6 +162,7 @@ public class Settings } ``` ::: zone-end + ::: zone pivot="programming-language-python" The quickest way to get started with the proper configuration to run the sample code is to create a `.env` file at the root of your project (where your script is run). @@ -198,17 +197,17 @@ Once configured, the respective AI service classes will pick up the required var The coding process for this sample involves: 1. [Setup](#setup) - Initializing settings and the plug-in. -2. [Agent Definition](#agent-definition) - Create the _OpenAI_Assistant_Agent_ with templatized instructions and plug-in. +2. [Agent Definition](#agent-definition) - Create the _OpenAI_Assistant`Agent` with templatized instructions and plug-in. 3. [The _Chat_ Loop](#the-chat-loop) - Write the loop that drives user / agent interaction. The full example code is provided in the [Final](#final) section. Refer to that section for the complete implementation. ### Setup -Prior to creating an _OpenAI Assistant Agent_, ensure the configuration settings are available and prepare the file resources. - ::: zone pivot="programming-language-csharp" +Prior to creating an `OpenAIAssistantAgent`, ensure the configuration settings are available and prepare the file resources. + Instantiate the `Settings` class referenced in the previous [Configuration](#configuration) section. Use the settings to also create an `OpenAIClientProvider` that will be used for the [Agent Definition](#agent-definition) as well as file-upload. ```csharp @@ -239,11 +238,13 @@ OpenAIFile fileDataCountryList = await fileClient.UploadFileAsync("PopulationByC ::: zone pivot="programming-language-python" +Prior to creating an `AzureAssistantAgent` or an `OpenAIAssistantAgent`, ensure the configuration settings are available and prepare the file resources. + > [!TIP] > You may need to adjust the file paths depending upon where your files are located. ```python -# Let's form the file paths that we will later pass to the assistant +# Let's form the file paths that we will use as part of file upload csv_file_path_1 = os.path.join( os.path.dirname(os.path.dirname(os.path.realpath(__file__))), "resources", @@ -256,7 +257,39 @@ csv_file_path_2 = os.path.join( "PopulationByCountry.csv", ) ``` -You may need to modify the path creation code based on the storage location of your CSV files. + +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Upload the files to the client +file_ids: list[str] = [] +for path in [csv_file_path_1, csv_file_path_2]: + with open(path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + file_ids.append(file.id) + +# Get the code interpreter tool and resources +code_interpreter_tools, code_interpreter_tool_resources = AzureAssistantAgent.configure_code_interpreter_tool( + file_ids=file_ids +) + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions=""" + Analyze the available data to provide an answer to the user's question. + Always format response using markdown. + Always include a numerical index that starts at 1 for any lists or tables. + Always sort lists in ascending order. + """, + name="SampleAssistantAgent", + tools=code_interpreter_tools, + tool_resources=code_interpreter_tool_resources, +) +``` + +We first set up the Azure OpenAI resources to obtain the client and model. Next, we upload the CSV files from the specified paths using the client's Files API. We then configure the `code_interpreter_tool` using the uploaded file IDs, which are linked to the assistant upon creation along with the model, instructions, and name. ::: zone-end @@ -270,7 +303,7 @@ You may need to modify the path creation code based on the storage location of y ::: zone pivot="programming-language-csharp" -We are now ready to instantiate an _OpenAI Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. +We are now ready to instantiate an `OpenAIAssistantAgent`. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. ```csharp Console.WriteLine("Defining agent..."); @@ -296,21 +329,13 @@ OpenAIAssistantAgent agent = ::: zone pivot="programming-language-python" -We are now ready to instantiate an _Azure Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. +We are now ready to instantiate an `AzureAssistantAgent`. The agent is configured with the client and the assistant definition. ```python -agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", - instructions=""" - Analyze the available data to provide an answer to the user's question. - Always format response using markdown. - Always include a numerical index that starts at 1 for any lists or tables. - Always sort lists in ascending order. - """, - enable_code_interpreter=True, - code_interpreter_filenames=[csv_file_path_1, csv_file_path_2], +# Create the agent using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, ) ``` ::: zone-end @@ -323,7 +348,7 @@ agent = await AzureAssistantAgent.create( ### The _Chat_ Loop -At last, we are able to coordinate the interaction between the user and the _Agent_. Start by creating an _Assistant Thread_ to maintain the conversation state and creating an empty loop. +At last, we are able to coordinate the interaction between the user and the `Agent`. Start by creating an _Assistant Thread_ to maintain the conversation state and creating an empty loop. Let's also ensure the resources are removed at the end of execution to minimize unnecessary charges. @@ -369,11 +394,10 @@ try: while not is_complete: # agent interaction logic here finally: - print("Cleaning up resources...") - if agent is not None: - [await agent.delete_file(file_id) for file_id in agent.code_interpreter_file_ids] - await agent.delete_thread(thread_id) - await agent.delete() + print("\nCleaning up resources...") + [await client.files.delete(file_id) for file_id in file_ids] + await client.beta.threads.delete(thread.id) + await client.beta.assistants.delete(agent.id) ``` ::: zone-end @@ -426,7 +450,7 @@ await agent.add_chat_message(thread_id=thread_id, message=ChatMessageContent(rol ::: zone-end -Before invoking the _Agent_ response, let's add some helper methods to download any files that may be produced by the _Agent_. +Before invoking the `Agent` response, let's add some helper methods to download any files that may be produced by the `Agent`. ::: zone pivot="programming-language-csharp" Here we're place file content in the system defined temporary directory and then launching the system defined viewer application. @@ -513,7 +537,7 @@ async def download_response_image(agent, file_ids: list[str]): ::: zone-end -To generate an _Agent_ response to user input, invoke the agent by specifying the _Assistant Thread_. In this example, we choose a streamed response and capture any generated _File References_ for download and review at the end of the response cycle. It's important to note that generated code is identified by the presence of a _Metadata_ key in the response message, distinguishing it from the conversational reply. +To generate an `Agent` response to user input, invoke the agent by specifying the _Assistant Thread_. In this example, we choose a streamed response and capture any generated _File References_ for download and review at the end of the response cycle. It's important to note that generated code is identified by the presence of a _Metadata_ key in the response message, distinguishing it from the conversational reply. ::: zone pivot="programming-language-csharp" ```csharp @@ -743,19 +767,16 @@ import asyncio import logging import os -from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.streaming_file_reference_content import StreamingFileReferenceContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.kernel import Kernel +from semantic_kernel.agents.open_ai import AzureAssistantAgent +from semantic_kernel.contents import StreamingFileReferenceContent logging.basicConfig(level=logging.ERROR) -################################################################### -# The following sample demonstrates how to create a simple, # -# OpenAI assistant agent that utilizes the code interpreter # -# to analyze uploaded files. # -################################################################### +""" +The following sample demonstrates how to create a simple, +OpenAI assistant agent that utilizes the code interpreter +to analyze uploaded files. +""" # Let's form the file paths that we will later pass to the assistant csv_file_path_1 = os.path.join( @@ -802,22 +823,43 @@ async def download_response_image(agent: AzureAssistantAgent, file_ids: list[str async def main(): - agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", + # Create the client using Azure OpenAI resources and configuration + client, model = AzureAssistantAgent.setup_resources() + + # Upload the files to the client + file_ids: list[str] = [] + for path in [csv_file_path_1, csv_file_path_2]: + with open(path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + file_ids.append(file.id) + + # Get the code interpreter tool and resources + code_interpreter_tools, code_interpreter_tool_resources = AzureAssistantAgent.configure_code_interpreter_tool( + file_ids=file_ids + ) + + # Create the assistant definition + definition = await client.beta.assistants.create( + model=model, instructions=""" - Analyze the available data to provide an answer to the user's question. - Always format response using markdown. - Always include a numerical index that starts at 1 for any lists or tables. - Always sort lists in ascending order. - """, - enable_code_interpreter=True, - code_interpreter_filenames=[csv_file_path_1, csv_file_path_2], + Analyze the available data to provide an answer to the user's question. + Always format response using markdown. + Always include a numerical index that starts at 1 for any lists or tables. + Always sort lists in ascending order. + """, + name="SampleAssistantAgent", + tools=code_interpreter_tools, + tool_resources=code_interpreter_tool_resources, + ) + + # Create the agent using the client and the assistant definition + agent = AzureAssistantAgent( + client=client, + definition=definition, ) print("Creating thread...") - thread_id = await agent.create_thread() + thread = await client.beta.threads.create() try: is_complete: bool = False @@ -829,14 +871,13 @@ async def main(): if user_input.lower() == "exit": is_complete = True + break - await agent.add_chat_message( - thread_id=thread_id, message=ChatMessageContent(role=AuthorRole.USER, content=user_input) - ) + await agent.add_chat_message(thread_id=thread.id, message=user_input) is_code = False last_role = None - async for response in agent.invoke_stream(thread_id=thread_id): + async for response in agent.invoke_stream(thread_id=thread.id): current_is_code = response.metadata.get("code", False) if current_is_code: @@ -858,16 +899,16 @@ async def main(): ]) if is_code: print("```\n") + print() await download_response_image(agent, file_ids) file_ids.clear() finally: print("\nCleaning up resources...") - if agent is not None: - [await agent.delete_file(file_id) for file_id in agent.code_interpreter_file_ids] - await agent.delete_thread(thread_id) - await agent.delete() + [await client.files.delete(file_id) for file_id in file_ids] + await client.beta.threads.delete(thread.id) + await client.beta.assistants.delete(agent.id) if __name__ == "__main__": @@ -885,5 +926,5 @@ You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/m > [!div class="nextstepaction"] -> [How-To: _OpenAI Assistant Agent_ Code File Search](./example-assistant-search.md) +> [How-To: `OpenAIAssistantAgent` Code File Search](./example-assistant-search.md) diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index e05c069c..1aad1696 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -1,5 +1,5 @@ --- -title: How-To: _OpenAI Assistant Agent_ File Search (Experimental) +title: How-To: `OpenAIAssistantAgent` File Search description: A step-by-step walk-through of defining and utilizing the file-search tool of an OpenAI Assistant Agent. zone_pivot_groups: programming-languages author: crickman @@ -8,14 +8,14 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# How-To: _OpenAI Assistant Agent_ File Search +# How-To: `OpenAIAssistantAgent` File Search -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. ## Overview -In this sample, we will explore how to use the _file-search_ tool of an [_OpenAI Assistant Agent_](../assistant-agent.md) to complete comprehension tasks. The approach will be step-by-step, ensuring clarity and precision throughout the process. As part of the task, the agent will provide document citations within the response. +In this sample, we will explore how to use the _file-search_ tool of an [`OpenAIAssistantAgent`](../assistant-agent.md) to complete comprehension tasks. The approach will be step-by-step, ensuring clarity and precision throughout the process. As part of the task, the agent will provide document citations within the response. Streaming will be used to deliver the agent's responses. This will provide real-time updates as the task progresses. @@ -54,7 +54,7 @@ The project file (`.csproj`) should contain the following `PackageReference` def ``` -The _Agent Framework_ is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): +The `Agent Framework` is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): ```xml @@ -86,11 +86,8 @@ Start by creating a folder that will hold your script (`.py` file) and the sampl import asyncio import os -from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.streaming_annotation_content import StreamingAnnotationContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.kernel import Kernel +from semantic_kernel.agents.open_ai import AzureAssistantAgent +from semantic_kernel.contents import StreamingAnnotationContent ``` Additionally, copy the `Grimms-The-King-of-the-Golden-Mountain.txt`, `Grimms-The-Water-of-Life.txt` and `Grimms-The-White-Snake.txt` public domain content from [_Semantic Kernel_ `LearnResources` Project](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/learn_resources/resources). Add these files in your project folder. @@ -201,14 +198,14 @@ Once configured, the respective AI service classes will pick up the required var The coding process for this sample involves: 1. [Setup](#setup) - Initializing settings and the plug-in. -2. [Agent Definition](#agent-definition) - Create the _Chat_Completion_Agent_ with templatized instructions and plug-in. +2. [Agent Definition](#agent-definition) - Create the _Chat_Completion`Agent` with templatized instructions and plug-in. 3. [The _Chat_ Loop](#the-chat-loop) - Write the loop that drives user / agent interaction. The full example code is provided in the [Final](#final) section. Refer to that section for the complete implementation. ### Setup -Prior to creating an _OpenAI Assistant Agent_, ensure the configuration settings are available and prepare the file resources. +Prior to creating an `OpenAIAssistantAgent`, ensure the configuration settings are available and prepare the file resources. ::: zone pivot="programming-language-csharp" @@ -225,6 +222,16 @@ OpenAIClientProvider clientProvider = ``` ::: zone-end + +::: zone pivot="programming-language-python" +The class method `setup_resources()` on the Assistant Agent handles creating the client and returning it and the model to use based on the desired configuration. Pydantic settings are used to load environment variables first from environment variables or from the `.env` file. One may pass in the `api_key`, `api_version`, `deployment_name` or `endpoint`, which will take precedence over any environment variables configured. + +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() +``` +::: zone-end + ::: zone pivot="programming-language-java" > Agents are currently unavailable in Java. @@ -248,8 +255,21 @@ string storeId = operation.VectorStoreId; ::: zone pivot="programming-language-python" ```python def get_filepath_for_filename(filename: str) -> str: - base_directory = os.path.dirname(os.path.realpath(__file__)) + base_directory = os.path.join( + os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", + ) return os.path.join(base_directory, filename) + +# Upload the files to the client +file_ids: list[str] = [] +for path in [get_filepath_for_filename(filename) for filename in filenames]: + with open(path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + file_ids.append(file.id) + +# Get the file search tool and resources +file_search_tools, file_search_tool_resources = AzureAssistantAgent.configure_file_search_tool(file_ids=file_ids) ``` ::: zone-end @@ -315,7 +335,7 @@ foreach (string fileName in _fileNames) ### Agent Definition -We are now ready to instantiate an _OpenAI Assistant Agent_. The agent is configured with its target model, _Instructions_, and the _File Search_ tool enabled. Additionally, we explicitly associate the _Vector Store_ with the _File Search_ tool. +We are now ready to instantiate an `OpenAIAssistantAgent`. The agent is configured with its target model, _Instructions_, and the _File Search_ tool enabled. Additionally, we explicitly associate the _Vector Store_ with the _File Search_ tool. ::: zone pivot="programming-language-csharp" @@ -345,18 +365,24 @@ OpenAIAssistantAgent agent = ::: zone pivot="programming-language-python" ```python -agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, instructions=""" The document store contains the text of fictional stories. Always analyze the document store to provide an answer to the user's question. Never rely on your knowledge of stories not included in the document store. Always format response using markdown. """, - enable_file_search=True, - vector_store_filenames=[get_filepath_for_filename(filename) for filename in filenames], + name="SampleAssistantAgent", + tools=file_search_tools, + tool_resources=file_search_tool_resources, +) + +# Create the agent using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, ) ``` ::: zone-end @@ -369,7 +395,7 @@ agent = await AzureAssistantAgent.create( ### The _Chat_ Loop -At last, we are able to coordinate the interaction between the user and the _Agent_. Start by creating an _Assistant Thread_ to maintain the conversation state and creating an empty loop. +At last, we are able to coordinate the interaction between the user and the `Agent`. Start by creating an _Assistant Thread_ to maintain the conversation state and creating an empty loop. Let's also ensure the resources are removed at the end of execution to minimize unnecessary charges. @@ -458,6 +484,7 @@ if not user_input: if user_input.lower() == "exit": is_complete = True + break await agent.add_chat_message( thread_id=thread_id, message=ChatMessageContent(role=AuthorRole.USER, content=user_input) @@ -471,7 +498,7 @@ await agent.add_chat_message( ::: zone-end -Before invoking the _Agent_ response, let's add a helper method to reformat the unicode annotation brackets to ANSI brackets. +Before invoking the `Agent` response, let's add a helper method to reformat the unicode annotation brackets to ANSI brackets. ::: zone pivot="programming-language-csharp" ```csharp @@ -492,7 +519,7 @@ private static string ReplaceUnicodeBrackets(this string content) => ::: zone-end -To generate an _Agent_ response to user input, invoke the agent by specifying the _Assistant Thread_. In this example, we choose a streamed response and capture any associated _Citation Annotations_ for display at the end of the response cycle. Note each streamed chunk is being reformatted using the previous helper method. +To generate an `Agent` response to user input, invoke the agent by specifying the _Assistant Thread_. In this example, we choose a streamed response and capture any associated _Citation Annotations_ for display at the end of the response cycle. Note each streamed chunk is being reformatted using the previous helper method. ::: zone pivot="programming-language-csharp" ```csharp @@ -702,18 +729,26 @@ public static class Program ::: zone pivot="programming-language-python" ```python +# Copyright (c) Microsoft. All rights reserved. + import asyncio import os -from semantic_kernel.agents.open_ai.azure_assistant_agent import AzureAssistantAgent -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.streaming_annotation_content import StreamingAnnotationContent -from semantic_kernel.contents.utils.author_role import AuthorRole -from semantic_kernel.kernel import Kernel +from semantic_kernel.agents.open_ai import AzureAssistantAgent +from semantic_kernel.contents import StreamingAnnotationContent + +""" +The following sample demonstrates how to create a simple, +OpenAI assistant agent that utilizes the vector store +to answer questions based on the uploaded documents. +""" def get_filepath_for_filename(filename: str) -> str: - base_directory = os.path.dirname(os.path.realpath(__file__)) + base_directory = os.path.join( + os.path.dirname(os.path.dirname(os.path.realpath(__file__))), + "resources", + ) return os.path.join(base_directory, filename) @@ -725,22 +760,48 @@ filenames = [ async def main(): - agent = await AzureAssistantAgent.create( - kernel=Kernel(), - service_id="agent", - name="SampleAssistantAgent", + # Create the client using Azure OpenAI resources and configuration + client, model = AzureAssistantAgent.setup_resources() + + # Upload the files to the client + file_ids: list[str] = [] + for path in [get_filepath_for_filename(filename) for filename in filenames]: + with open(path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + file_ids.append(file.id) + + vector_store = await client.beta.vector_stores.create( + name="assistant_search", + file_ids=file_ids, + ) + + # Get the file search tool and resources + file_search_tools, file_search_tool_resources = AzureAssistantAgent.configure_file_search_tool( + vector_store_ids=vector_store.id + ) + + # Create the assistant definition + definition = await client.beta.assistants.create( + model=model, instructions=""" The document store contains the text of fictional stories. Always analyze the document store to provide an answer to the user's question. Never rely on your knowledge of stories not included in the document store. Always format response using markdown. """, - enable_file_search=True, - vector_store_filenames=[get_filepath_for_filename(filename) for filename in filenames], + name="SampleAssistantAgent", + tools=file_search_tools, + tool_resources=file_search_tool_resources, + ) + + # Create the agent using the client and the assistant definition + agent = AzureAssistantAgent( + client=client, + definition=definition, ) print("Creating thread...") - thread_id = await agent.create_thread() + thread = await client.beta.threads.create() try: is_complete: bool = False @@ -753,12 +814,10 @@ async def main(): is_complete = True break - await agent.add_chat_message( - thread_id=thread_id, message=ChatMessageContent(role=AuthorRole.USER, content=user_input) - ) + await agent.add_chat_message(thread_id=thread.id, message=user_input) footnotes: list[StreamingAnnotationContent] = [] - async for response in agent.invoke_stream(thread_id=thread_id): + async for response in agent.invoke_stream(thread_id=thread.id): footnotes.extend([item for item in response.items if isinstance(item, StreamingAnnotationContent)]) print(f"{response.content}", end="", flush=True) @@ -773,11 +832,10 @@ async def main(): ) finally: - print("Cleaning up resources...") - if agent is not None: - [await agent.delete_file(file_id) for file_id in agent.file_search_file_ids] - await agent.delete_thread(thread_id) - await agent.delete() + print("\nCleaning up resources...") + [await client.files.delete(file_id) for file_id in file_ids] + await client.beta.threads.delete(thread.id) + await client.beta.assistants.delete(agent.id) if __name__ == "__main__": @@ -795,5 +853,5 @@ You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/m > [!div class="nextstepaction"] -> [How to Coordinate Agent Collaboration using _Agent Group Chat_](./example-agent-collaboration.md) +> [How to Coordinate Agent Collaboration using `AgentGroupChat`](./example-agent-collaboration.md) diff --git a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md index ced3bb01..d24a85f8 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md +++ b/semantic-kernel/Frameworks/agent/examples/example-chat-agent.md @@ -1,5 +1,5 @@ --- -title: How-To: _Chat Completion Agent_ (Experimental) +title: How-To: `ChatCompletionAgent` description: A step-by-step walk-through of defining and utilizing the features of a Chat Completion Agent. zone_pivot_groups: programming-languages author: crickman @@ -8,14 +8,14 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# How-To: _Chat Completion Agent_ +# How-To: `ChatCompletionAgent` -> [!WARNING] -> The *Semantic Kernel Agent Framework* is in preview and is subject to change. +> [!IMPORTANT] +> This feature is in the experimental stage. Features at this stage are still under development and subject to change before advancing to the preview or release candidate stage. ## Overview -In this sample, we will explore configuring a plugin to access _GitHub_ API and provide templatized instructions to a [_Chat Completion Agent_](../chat-completion-agent.md) to answer questions about a _GitHub_ repository. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will provide document citations within the response. +In this sample, we will explore configuring a plugin to access _GitHub_ API and provide templatized instructions to a [`ChatCompletionAgent`](../chat-completion-agent.md) to answer questions about a _GitHub_ repository. The approach will be broken down step-by-step to high-light the key parts of the coding process. As part of the task, the agent will provide document citations within the response. Streaming will be used to deliver the agent's responses. This will provide real-time updates as the task progresses. @@ -55,7 +55,7 @@ The project file (`.csproj`) should contain the following `PackageReference` def ``` -The _Agent Framework_ is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): +The `Agent Framework` is experimental and requires warning suppression. This may addressed in as a property in the project file (`.csproj`): ```xml @@ -76,13 +76,11 @@ import sys from datetime import datetime from semantic_kernel.agents import ChatCompletionAgent -from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior +from semantic_kernel.connectors.ai import FunctionChoiceBehavior from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion -from semantic_kernel.contents.chat_history import ChatHistory -from semantic_kernel.contents.chat_message_content import ChatMessageContent -from semantic_kernel.contents.utils.author_role import AuthorRole +from semantic_kernel.contents import AuthorRole, ChatHistory, ChatMessageContent +from semantic_kernel.functions import KernelArguments from semantic_kernel.kernel import Kernel -from semantic_kernel.functions.kernel_arguments import KernelArguments # Adjust the sys.path so we can use the GitHubPlugin and GitHubSettings classes # This is so we can run the code from the samples/learn_resources/agent_docs directory @@ -201,14 +199,14 @@ Once configured, the respective AI service classes will pick up the required var The coding process for this sample involves: 1. [Setup](#setup) - Initializing settings and the plug-in. -2. [_Agent_ Definition](#agent-definition) - Create the _Chat Completion Agent_ with templatized instructions and plug-in. +2. [`Agent` Definition](#agent-definition) - Create the `ChatCompletionAgent` with templatized instructions and plug-in. 3. [The _Chat_ Loop](#the-chat-loop) - Write the loop that drives user / agent interaction. The full example code is provided in the [Final](#final) section. Refer to that section for the complete implementation. ### Setup -Prior to creating a _Chat Completion Agent_, the configuration settings, plugins, and _Kernel_ must be initialized. +Prior to creating a `ChatCompletionAgent`, the configuration settings, plugins, and `Kernel` must be initialized. ::: zone pivot="programming-language-csharp" @@ -293,7 +291,7 @@ settings.function_choice_behavior = FunctionChoiceBehavior.Auto() ### Agent Definition -Finally we are ready to instantiate a _Chat Completion Agent_ with its _Instructions_, associated _Kernel_, and the default _Arguments_ and _Execution Settings_. In this case, we desire to have the any plugin functions automatically executed. +Finally we are ready to instantiate a `ChatCompletionAgent` with its _Instructions_, associated `Kernel`, and the default _Arguments_ and _Execution Settings_. In this case, we desire to have the any plugin functions automatically executed. ::: zone pivot="programming-language-csharp" ```csharp @@ -328,7 +326,6 @@ Console.WriteLine("Ready!"); ::: zone pivot="programming-language-python" ```python agent = ChatCompletionAgent( - service_id="agent", kernel=kernel, name="SampleAssistantAgent", instructions=f""" @@ -358,7 +355,7 @@ agent = ChatCompletionAgent( ### The _Chat_ Loop -At last, we are able to coordinate the interaction between the user and the _Agent_. Start by creating a _Chat History_ object to maintain the conversation state and creating an empty loop. +At last, we are able to coordinate the interaction between the user and the `Agent`. Start by creating a `ChatHistory` object to maintain the conversation state and creating an empty loop. ::: zone pivot="programming-language-csharp" ```csharp @@ -386,7 +383,7 @@ while not is_complete: ::: zone-end -Now let's capture user input within the previous loop. In this case, empty input will be ignored and the term `EXIT` will signal that the conversation is completed. Valid input will be added to the _Chat History_ as a _User_ message. +Now let's capture user input within the previous loop. In this case, empty input will be ignored and the term `EXIT` will signal that the conversation is completed. Valid input will be added to the `ChatHistory` as a _User_ message. ::: zone pivot="programming-language-csharp" ```csharp @@ -429,9 +426,9 @@ history.add_message(ChatMessageContent(role=AuthorRole.USER, content=user_input) ::: zone-end -To generate a _Agent_ response to user input, invoke the agent using _Arguments_ to provide the final template parameter that specifies the current date and time. +To generate a `Agent` response to user input, invoke the agent using _Arguments_ to provide the final template parameter that specifies the current date and time. -The _Agent_ response is then then displayed to the user. +The `Agent` response is then then displayed to the user. ::: zone pivot="programming-language-csharp" ```csharp @@ -628,7 +625,6 @@ async def main(): # Create the agent agent = ChatCompletionAgent( - service_id="agent", kernel=kernel, name="SampleAssistantAgent", instructions=f""" @@ -682,6 +678,6 @@ You may find the full [code](https://github.com/microsoft/semantic-kernel/blob/m > [!div class="nextstepaction"] -> [How-To: _OpenAI Assistant Agent_ Code Interpreter](./example-assistant-code.md) +> [How-To: `OpenAIAssistantAgent` Code Interpreter](./example-assistant-code.md) diff --git a/semantic-kernel/Frameworks/agent/index.md b/semantic-kernel/Frameworks/agent/index.md index 7d8299ea..67a76125 100644 --- a/semantic-kernel/Frameworks/agent/index.md +++ b/semantic-kernel/Frameworks/agent/index.md @@ -1,5 +1,5 @@ --- -title: Semantic Kernel Agent Framework (Experimental) +title: Semantic Kernel Agent Framework description: Introducing the Semantic Kernel Agent Framework zone_pivot_groups: programming-languages author: crickman @@ -10,10 +10,10 @@ ms.service: semantic-kernel --- # Semantic Kernel Agent Framework -> [!WARNING] -> The _Semantic Kernel Agent Framework_ is in preview and is subject to change. +> [!IMPORTANT] +> Single-agent features, such as ChatCompletionAgent and OpenAIAssistantAgent, are in the release candidate stage. These features are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. However, agent chat patterns are still in the experimental stage. These patterns are under active development and may change significantly before advancing to the preview or release candidate stage. -The _Semantic Kernel Agent Framework_ provides a platform within the Semantic Kernel eco-system that allow for the creation of AI **agents** and the ability to incorporate **agentic patterns** into any application based on the same patterns and features that exist in the core _Semantic Kernel_ framework. +The Semantic Kernel Agent Framework provides a platform within the Semantic Kernel eco-system that allow for the creation of AI **agents** and the ability to incorporate **agentic patterns** into any application based on the same patterns and features that exist in the core Semantic Kernel framework. ## What is an AI agent? @@ -21,7 +21,7 @@ An **AI agent** is a software entity designed to perform tasks autonomously or s Agents can send and receive messages, generating responses using a combination of models, tools, human inputs, or other customizable components. -Agents are designed to work collaboratively, enabling complex workflows by interacting with each other. The _Agent Framework_ allows for the creation of both simple and sophisticated agents, enhancing modularity and ease of maintenance +Agents are designed to work collaboratively, enabling complex workflows by interacting with each other. The `Agent Framework` allows for the creation of both simple and sophisticated agents, enhancing modularity and ease of maintenance ## What problems do AI agents solve? @@ -63,8 +63,8 @@ For .NET SDK, serveral NuGet packages are available. Package|Description --|-- -[Microsoft.SemanticKernel](https://www.nuget.org/packages/Microsoft.SemanticKernel)|This contains the core _Semantic Kernel_ libraries for getting started with the _Agent Framework_. This must be explicitly referenced by your application. -[Microsoft.SemanticKernel.Agents.Abstractions](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Abstractions)|Defines the core agent abstractions for the _Agent Framework_. Generally not required to be specified as it is included in both the `Microsoft.SemanticKernel.Agents.Core` and `Microsoft.SemanticKernel.Agents.OpenAI` packages. +[Microsoft.SemanticKernel](https://www.nuget.org/packages/Microsoft.SemanticKernel)|This contains the core _Semantic Kernel_ libraries for getting started with the `Agent Framework`. This must be explicitly referenced by your application. +[Microsoft.SemanticKernel.Agents.Abstractions](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Abstractions)|Defines the core agent abstractions for the `Agent Framework`. Generally not required to be specified as it is included in both the `Microsoft.SemanticKernel.Agents.Core` and `Microsoft.SemanticKernel.Agents.OpenAI` packages. [Microsoft.SemanticKernel.Agents.Core](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.Core)|Includes the [`ChatCompletionAgent`](./chat-completion-agent.md) and [`AgentGroupChat`](./agent-chat.md) classes. [Microsoft.SemanticKernel.Agents.OpenAI](https://www.nuget.org/packages/Microsoft.SemanticKernel.Agents.OpenAI)|Provides ability to use the [OpenAI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent`](./assistant-agent.md). @@ -74,7 +74,7 @@ Package|Description Module|Description --|-- -[semantic-kernel.agents](https://pypi.org/project/semantic-kernel/)|This is the _Semantic Kernel_ library for getting started with the _Agent Framework_. This must be explicitly referenced by your application. This module contains the [`ChatCompletionAgent`](./chat-completion-agent.md) and [`AgentGroupChat`](./agent-chat.md) classes, as well as the ability to use the [OpenAI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent` or `AzureOpenAssistant`](./assistant-agent.md). +[semantic-kernel.agents](https://pypi.org/project/semantic-kernel/)|This is the _Semantic Kernel_ library for getting started with the `Agent Framework`. This must be explicitly referenced by your application. This module contains the [`ChatCompletionAgent`](./chat-completion-agent.md) and [`AgentGroupChat`](./agent-chat.md) classes, as well as the ability to use the [OpenAI Assistant API](https://platform.openai.com/docs/assistants) via the [`OpenAIAssistantAgent` or `AzureOpenAssistant`](./assistant-agent.md). ::: zone-end diff --git a/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md b/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md new file mode 100644 index 00000000..5dbc6bba --- /dev/null +++ b/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md @@ -0,0 +1,623 @@ +--- +title: Agent Framework Release Candidate Migration Guide +description: Describes the steps for developers to update their Agent Framework code to the latest abstractions. +zone_pivot_groups: programming-languages +author: moonbox3 +ms.topic: conceptual +ms.author: evmattso +ms.date: 02/26/2025 +ms.service: semantic-kernel +--- + +# Migration Guide for Updating from Old Code to New Code + +As we transition some agents from the experimental stage to the release candidate stage, we have updated the APIs to simplify and streamline their use. Refer to the specific scenario guide to learn how to update your existing code to work with the latest available APIs. + +::: zone pivot="programming-language-csharp" + +## OpenAIAssistantAgent C# Migration Guide + +We recently applied a significant shift around the [`OpenAIAssistantAgent`](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/src/Agents/OpenAI/OpenAIAssistantAgent.cs) in the _Semantic Kernel Agent Framework_. + +These changes were applied in: + +- [PR #10583](https://github.com/microsoft/semantic-kernel/pull/10583) +- [PR #10616](https://github.com/microsoft/semantic-kernel/pull/10616) +- [PR #10633](https://github.com/microsoft/semantic-kernel/pull/10633) + +These changes are intended to: + +- Align with the pattern for using for our [`AzureAIAgent`](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/src/Agents/AzureAI/AzureAIAgent.cs). +- Fix bugs around static initialization pattern. +- Avoid limiting features based on our abstraction of the underlying SDK. + +This guide provides step-by-step instructions for migrating your C# code from the old implementation to the new one. Changes include updates for creating assistants, managing the assistant lifecycle, handling threads, files, and vector stores. + +## 1. Client Instantiation + +Previously, `OpenAIClientProvider` was required for creating any `OpenAIAssistantAgent`. This dependency has been simplified. + +#### **New Way** +```csharp +OpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(endpointUrl)); +AssistantClient assistantClient = client.GetAssistantClient(); +``` + +#### **Old Way (Deprecated)** +```csharp +var clientProvider = new OpenAIClientProvider(...); +``` + +## 2. Assistant Lifecycle + +### **Creating an Assistant** +You may now directly instantiate an `OpenAIAssistantAgent` using an existing or new Assistant definition from `AssistantClient`. + +##### **New Way** +```csharp +Assistant definition = await assistantClient.GetAssistantAsync(assistantId); +OpenAIAssistantAgent agent = new(definition, client); +``` + +Plugins can be directly included during initialization: +```csharp +KernelPlugin plugin = KernelPluginFactory.CreateFromType(); +Assistant definition = await assistantClient.GetAssistantAsync(assistantId); +OpenAIAssistantAgent agent = new(definition, client, [plugin]); +``` + +Creating a new assistant definition using an extension method: +```csharp +Assistant assistant = await assistantClient.CreateAssistantAsync( + model, + name, + instructions: instructions, + enableCodeInterpreter: true); +``` + +##### **Old Way (Deprecated)** +Previously, assistant definitions were managed indirectly. + +## 3. Invoking the Agent + +You may specify `RunCreationOptions` directly, enabling full access to underlying SDK capabilities. + +#### **New Way** +```csharp +RunCreationOptions options = new(); // configure as needed +var result = await agent.InvokeAsync(options); +``` + +#### **Old Way (Deprecated)** +```csharp +var options = new OpenAIAssistantInvocationOptions(); +``` + +## 4. Assistant Deletion + +You can directly manage assistant deletion with `AssistantClient`. + +```csharp +await assistantClient.DeleteAssistantAsync(agent.Id); +``` + +## 5. Thread Lifecycle + +### **Creating a Thread** +Threads are now created directly using `AssistantClient`. + +##### **New Way** +```csharp +AssistantThread thread = await assistantClient.CreateThreadAsync(); +``` + +Using a convenience extension method: +```csharp +string threadId = await assistantClient.CreateThreadAsync(messages: [new ChatMessageContent(AuthorRole.User, "")]); +``` + +##### **Old Way (Deprecated)** +Previously, thread management was indirect or agent-bound. + +### **Thread Deletion** +```csharp +await assistantClient.DeleteThreadAsync(thread.Id); +``` + +## 6. File Lifecycle + +File creation and deletion now utilize `OpenAIFileClient`. + +### **File Upload** +```csharp +string fileId = await client.UploadAssistantFileAsync(stream, ""); +``` + +### **File Deletion** +```csharp +await client.DeleteFileAsync(fileId); +``` + +## 7. Vector Store Lifecycle + +Vector stores are managed directly via `VectorStoreClient` with convenient extension methods. + +### **Vector Store Creation** +```csharp +string vectorStoreId = await client.CreateVectorStoreAsync([fileId1, fileId2], waitUntilCompleted: true); +``` + +### **Vector Store Deletion** +```csharp +await client.DeleteVectorStoreAsync(vectorStoreId); +``` + +## Backwards Compatibility + +Deprecated patterns are marked with `[Obsolete]`. To suppress obsolete warnings (`CS0618`), update your project file as follows: + +```xml + + $(NoWarn);CS0618 + +``` + +This migration guide helps you transition smoothly to the new implementation, simplifying client initialization, resource management, and integration with the **Semantic Kernel .NET SDK**. + +::: zone-end +::: zone pivot="programming-language-python" + +For developers upgrading to Semantic Kernel Python 1.22.0 or later, the ChatCompletionAgent and OpenAI Assistant abstractions have been updated. + +These changes were applied in: + +- [PR #10666](https://github.com/microsoft/semantic-kernel/pull/10666) +- [PR #10667](https://github.com/microsoft/semantic-kernel/pull/10667) +- [PR #10701](https://github.com/microsoft/semantic-kernel/pull/10701) +- [PR #10707](https://github.com/microsoft/semantic-kernel/pull/10707) + +This guide provides step-by-step instructions for migrating your Python code from the old implementation to the new implementation. + +## `ChatCompletionAgent` + +The `ChatCompletionAgent` has been updated to simplify service configuration, plugin handling, and function calling behaviors. Below are the key changes you should consider when migrating. + +### 1. Specifying the Service + +You can now specify the service directly as part of the agent constructor: + +#### New Way + +```python +agent = ChatCompletionAgent( + service=AzureChatCompletion(), + name="", + instructions="", +) +``` + +Note: If both a kernel and a service are provided, the service will take precedence if it shares the same service_id or ai_model_id. Otherwise, if they are separate, the first AI service registered on the kernel will be used. + +#### Old Way (Still Valid) + +Previously, you would first add a service to a kernel and then pass the kernel to the agent: + +```python +kernel = Kernel() +kernel.add_service(AzureChatCompletion()) + +agent = ChatCompletionAgent( + kernel=kernel, + name="", + instructions="", +) +``` + +### 2. Adding Plugins + +Plugins can now be supplied directly through the constructor: + +#### New Way + +```python +agent = ChatCompletionAgent( + service=AzureChatCompletion(), + name="", + instructions="", + plugins=[SamplePlugin()], +) +``` + +#### Old Way (Still Valid) + +Plugins previously had to be added to the kernel separately: + +```python +kernel = Kernel() +kernel.add_plugin(SamplePlugin()) + +agent = ChatCompletionAgent( + kernel=kernel, + name="", + instructions="", +) +``` + +Note: Both approaches are valid, but directly specifying plugins simplifies initialization. + +### 3. Invoking the Agent + +You now have two ways to invoke the agent. The new method directly retrieves a single response, while the old method supports streaming. + +#### New Way (Single Response) + +```python +chat_history = ChatHistory() +chat_history.add_user_message("") +response = await agent.get_response(chat_history) +# response is of type ChatMessageContent +``` + +#### Old Way (Still Valid) + +```python +chat_history = ChatHistory() +chat_history.add_user_message("") +async for response in agent.invoke(chat_history): + # handle response +``` + +### 4. Controlling Function Calling + +Function calling behavior can now be controlled directly when specifying the service within the agent constructor: + +```python +agent = ChatCompletionAgent( + service=AzureChatCompletion(), + name="", + instructions="", + plugins=[MenuPlugin()], + function_choice_behavior=FunctionChoiceBehavior.Auto( + filters={"included_functions": ["get_specials", "get_item_price"]} + ), +) +``` + +Note: Previously, function calling configuration required separate setup on the kernel or service object. If execution settings specify the same `service_id` or `ai_model_id` as the AI service configuration, the function calling behavior defined in the execution settings (via `KernelArguments`) will take precedence over the function choice behavior set in the constructor. + +These updates enhance simplicity and configurability, making the ChatCompletionAgent easier to integrate and maintain. + +## `OpenAIAssistantAgent` + +The `AzureAssistantAgent` and `OpenAIAssistantAgent` changes include updates for creating assistants, creating threads, handling plugins, using the code interpreter tool, working with the file search tool, and adding chat messages to a thread. + +## Setting up Resources + +### Old Way + +The `AsyncAzureOpenAI` client was created as part of creating the Agent object. + +```python +agent = await AzureAssistantAgent.create( + deployment_name="optional-deployment-name", + api_key="optional-api-key", + endpoint="optional-endpoint", + ad_token="optional-ad-token", + ad_token_provider=optional_callable, + default_headers={"optional_header": "optional-header-value"}, + env_file_path="optional-env-file-path", + env_file_encoding="optional-env-file-encoding", + ..., +) +``` + +### New Way + +The agent provides a static method to create the required client for the specified resources, where method-level keyword arguments take precedence over environment variables and values in an existing `.env` file. + +```python +client, model = AzureAssistantAgent.setup_resources( + ad_token="optional-ad-token", + ad_token_provider=optional_callable, + api_key="optional-api-key", + api_version="optional-api-version", + base_url="optional-base-url", + default_headers="optional-default-headers", + deployment_name="optional-deployment-name", + endpoint="optional-endpoint", + env_file_path="optional-env-file-path", + env_file_encoding="optional-env-file-encoding", + token_scope="optional-token-scope", +) +``` + +## 1. Creating an Assistant + +### Old Way +```python +agent = await AzureAssistantAgent.create( + kernel=kernel, + service_id=service_id, + name=AGENT_NAME, + instructions=AGENT_INSTRUCTIONS, + enable_code_interpreter=True, +) +``` +or +```python +agent = await OpenAIAssistantAgent.create( + kernel=kernel, + service_id=service_id, + name=, + instructions=, + enable_code_interpreter=True, +) +``` + +### New Way +```python +# Azure AssistantAgent + +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the agent using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, +) +``` +or +```python +# OpenAI Assistant Agent + +# Create the client using OpenAI resources and configuration +client, model = OpenAIAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the agent using the client and the assistant definition +agent = OpenAIAssistantAgent( + client=client, + definition=definition, +) +``` + +## 2. Creating a Thread + +### Old Way +```python +thread_id = await agent.create_thread() +``` + +### New Way +```python +thread = await agent.client.beta.threads.create() +# Use thread.id for the thread_id string +``` + +## 3. Handling Plugins + +### Old Way +```python +# Create the instance of the Kernel +kernel = Kernel() + +# Add the sample plugin to the kernel +kernel.add_plugin(plugin=MenuPlugin(), plugin_name="menu") + +agent = await AzureAssistantAgent.create( + kernel=kernel, + name="", + instructions="" +) +``` +*Note: It is still possible to manage plugins via the kernel. If you do not supply a kernel, a kernel is automatically created at agent creation time and the plugins will be added to that instance.* + +### New Way +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="", + name="", +) + +# Create the agent with plugins passed in as a list +agent = AzureAssistantAgent( + client=client, + definition=definition, + plugins=[MenuPlugin()], +) +``` + +Refer to the [sample implementation](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/getting_started_with_agents/openai_assistant/step2_plugins.py) for full details. + +## 4. Using the Code Interpreter Tool + +### Old Way +```python +csv_file_path = ... + +agent = await AzureAssistantAgent.create( + kernel=kernel, + name="", + instructions="", + enable_code_interpreter=True, + code_interpreter_filenames=[csv_file_path], +) +``` + +### New Way +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +csv_file_path = ... + +# Load the CSV file as a FileObject +with open(csv_file_path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + +# Get the code interpreter tool and resources +code_interpreter_tool, code_interpreter_tool_resource = AzureAssistantAgent.configure_code_interpreter_tool(file.id) + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + name="", + instructions=".", + tools=code_interpreter_tool, + tool_resources=code_interpreter_tool_resource, +) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, +) +``` + +Refer to the [sample implementation](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/agents/openai_assistant/openai_assistant_file_manipulation.py) for full details. + +## 5. Working with the File Search Tool + +### Old Way +```python +pdf_file_path = ... + +agent = await AzureAssistantAgent.create( + kernel=kernel, + service_id=service_id, + name=AGENT_NAME, + instructions=AGENT_INSTRUCTIONS, + enable_file_search=True, + vector_store_filenames=[pdf_file_path], +) +``` + +### New Way + +```python +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +pdf_file_path = ... + +# Load the employees PDF file as a FileObject +with open(pdf_file_path, "rb") as file: + file = await client.files.create(file=file, purpose="assistants") + +# Create a vector store specifying the file ID to be used for file search +vector_store = await client.beta.vector_stores.create( + name="step4_assistant_file_search", + file_ids=[file.id], +) + +file_search_tool, file_search_tool_resources = AzureAssistantAgent.configure_file_search_tool(vector_store.id) + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + instructions="Find answers to the user's questions in the provided file.", + name="FileSearch", + tools=file_search_tool, + tool_resources=file_search_tool_resources, +) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, +) +``` + +Refer to the [sample implementation](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/getting_started_with_agents/openai_assistant/step4_assistant_tool_file_search.py) for full details. + +## 6. Adding Chat Messages to a Thread + +### Old Way +```python +await agent.add_chat_message( + thread_id=thread_id, + message=ChatMessageContent(role=AuthorRole.USER, content=user_input) +) +``` + +### New Way +*Note: The old method still works if you pass in a `ChatMessageContent`, but you can now also pass a simple string.* +```python +await agent.add_chat_message( + thread_id=thread_id, + message=user_input, +) +``` + +## 7. Cleaning Up Resources + +### Old Way +```python +await agent.delete_file(file_id) +await agent.delete_thread(thread_id) +await agent.delete() +``` + +### New Way +```python +await client.files.delete(file_id) +await client.beta.threads.delete(thread.id) +await client.beta.assistants.delete(agent.id) +``` + +## Handling Structured Outputs + +### Old Way +*Unavailable in the old way* + +### New Way +```python +# Define a Pydantic model that represents the structured output from the OpenAI service +class ResponseModel(BaseModel): + response: str + items: list[str] + +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Create the assistant definition +definition = await client.beta.assistants.create( + model=model, + name="", + instructions="", + response_format=AzureAssistantAgent.configure_response_format(ResponseModel), +) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, +) +``` +Refer to the [sample implementation](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/concepts/agents/openai_assistant/openai_assistant_structured_outputs.py) for full details. + +This migration guide should help you update your code to the new implementation, leveraging client-based configuration and enhanced features. + +::: zone-end +::: zone pivot="programming-language-java" +> Agents are unavailable in Java. +::: zone-end diff --git a/semantic-kernel/support/migration/toc.yml b/semantic-kernel/support/migration/toc.yml index 91c21c5f..1718b55c 100644 --- a/semantic-kernel/support/migration/toc.yml +++ b/semantic-kernel/support/migration/toc.yml @@ -9,4 +9,6 @@ - name: Memory Store to Vector Store Migration href: memory-store-migration.md - name: Kernel Events and Filters Migration - href: kernel-events-and-filters-migration.md \ No newline at end of file + href: kernel-events-and-filters-migration.md +- name: Agent Framework Release Candidate Migration Guide + href: agent-framework-rc-migration-guide.md \ No newline at end of file From 8d59c5c3a3a878f90ccab733105ba7669e514ba7 Mon Sep 17 00:00:00 2001 From: Evan Mattson <35585003+moonbox3@users.noreply.github.com> Date: Fri, 28 Feb 2025 11:55:58 +0900 Subject: [PATCH 42/70] Update title (#474) --- .../support/migration/agent-framework-rc-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md b/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md index 5dbc6bba..a7eb9cfd 100644 --- a/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md +++ b/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md @@ -9,7 +9,7 @@ ms.date: 02/26/2025 ms.service: semantic-kernel --- -# Migration Guide for Updating from Old Code to New Code +# Agent Framework Release Candidate Migration Guide As we transition some agents from the experimental stage to the release candidate stage, we have updated the APIs to simplify and streamline their use. Refer to the specific scenario guide to learn how to update your existing code to work with the latest available APIs. From e96632decd0027ede30ecd8a60e4177a6d98093c Mon Sep 17 00:00:00 2001 From: Evan Mattson <35585003+moonbox3@users.noreply.github.com> Date: Fri, 28 Feb 2025 12:58:11 +0900 Subject: [PATCH 43/70] Merge main to live: updating Migration Guide title (#477) * Update Agent Framework related doc and code samples. Add migration code for Python (#469) * Update OpenAI assistant related code samples. Add migration code for Python * improve migration guide * Update semantic-kernel/support/migration/openai-assistant-agent-migration-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update semantic-kernel/support/migration/openai-assistant-agent-migration-guide.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Replace italics with code format. * update bookmarks * Update Python docs * Add dotnet migration guide. * update formatting in migration guide * fix headers * Fix header again * update guide to include rc * Small update to include new method get_response * Update important tags with some experimental (group chat) and some release candidate --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update title (#474) --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../support/migration/agent-framework-rc-migration-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md b/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md index 5dbc6bba..a7eb9cfd 100644 --- a/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md +++ b/semantic-kernel/support/migration/agent-framework-rc-migration-guide.md @@ -9,7 +9,7 @@ ms.date: 02/26/2025 ms.service: semantic-kernel --- -# Migration Guide for Updating from Old Code to New Code +# Agent Framework Release Candidate Migration Guide As we transition some agents from the experimental stage to the release candidate stage, we have updated the APIs to simplify and streamline their use. Refer to the specific scenario guide to learn how to update your existing code to work with the latest available APIs. From bdb611802db99b49de5dde32f7717c18c34b7ce7 Mon Sep 17 00:00:00 2001 From: Sophia Lagerkrans-Pandey <163188263+sophialagerkranspandey@users.noreply.github.com> Date: Fri, 28 Feb 2025 08:57:47 -0800 Subject: [PATCH 44/70] Update semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-ai-search-connector.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../out-of-the-box-connectors/azure-ai-search-connector.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-ai-search-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-ai-search-connector.md index 9f75aca2..a85ee0d4 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-ai-search-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/azure-ai-search-connector.md @@ -41,7 +41,7 @@ The Azure AI Search Vector Store connector can be used to access and manage data | Supported data property types |
    • string
    • int
    • long
    • double
    • float
    • bool
    • DateTimeOffset
    • *and iterables of each of these types*
    | | Supported vector property types | list[float], list[int], ndarray | | Supported index types |
    • Hnsw
    • Flat
    | -| Supported distance functions |
    • CosineSimilarity
    • DotProductSimilarity
    • EuclideanDistance
  • Hamming
    • | +| Supported distance functions |
    • CosineSimilarity
    • DotProductSimilarity
    • EuclideanDistance
    • Hamming
    | | Supported filter clauses |
    • AnyTagEqualTo
    • EqualTo
    | | Supports multiple vectors in a record | Yes | | IsFilterable supported? | Yes | From 3f2fcdbfda0626de92d0e710769424dd1134de42 Mon Sep 17 00:00:00 2001 From: Sophia Lagerkrans-Pandey <163188263+sophialagerkranspandey@users.noreply.github.com> Date: Fri, 28 Feb 2025 08:57:59 -0800 Subject: [PATCH 45/70] Update semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../out-of-the-box-connectors/mongodb-connector.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md index 152d579b..8671e1a3 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/mongodb-connector.md @@ -40,7 +40,7 @@ The MongoDB Vector Store connector can be used to access and manage data in Mong | Collection maps to | MongoDB Collection + Index | | Supported key property types | string | | Supported data property types |
    • string
    • int
    • long
    • double
    • float
    • decimal
    • bool
    • DateTime
    • *and iterables of each of these types*
    | -| Supported vector property types |
    • list[float]
    • list[int]
  • ndarray
    • | +| Supported vector property types |
    • list[float]
    • list[int]
    • ndarray
    | | Supported index types |
    • Hnsw
    • IvfFlat
    | | Supported distance functions |
    • CosineDistance
    • DotProductSimilarity
    • EuclideanDistance
    | | Supported filter clauses |
    • EqualTo
    • AnyTagsEqualTo
    | From 76657f9fce2a924dc54dbda356edcbf007063c0f Mon Sep 17 00:00:00 2001 From: Sophia Lagerkrans-Pandey <163188263+sophialagerkranspandey@users.noreply.github.com> Date: Fri, 28 Feb 2025 08:58:13 -0800 Subject: [PATCH 46/70] Update semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../out-of-the-box-connectors/weaviate-connector.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md index 574cb9d0..b3efc390 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/weaviate-connector.md @@ -39,7 +39,7 @@ The Weaviate Vector Store connector can be used to access and manage data in Wea | Collection maps to | Weaviate Collection | | Supported key property types | Guid | | Supported data property types |
    • string
    • byte
    • short
    • int
    • long
    • double
    • float
    • decimal
    • bool
    • *and iterables of each of these types*
    | -| Supported vector property types |
    • list[float]
    • list[int]
  • ndarray
    • | +| Supported vector property types |
    • list[float]
    • list[int]
    • ndarray
    | | Supported index types |
    • Hnsw
    • Flat
    • Dynamic
    | | Supported distance functions |
    • CosineDistance
    • NegativeDotProductSimilarity
    • EuclideanSquaredDistance
    • Hamming
    • ManhattanDistance
    | | Supported filter clauses |
    • AnyTagEqualTo
    • EqualTo
    | From 24c208a34b81bd7f18eb2593c8bfec1c78c15460 Mon Sep 17 00:00:00 2001 From: Sophia Lagerkrans-Pandey <163188263+sophialagerkranspandey@users.noreply.github.com> Date: Fri, 28 Feb 2025 08:58:23 -0800 Subject: [PATCH 47/70] Update semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../out-of-the-box-connectors/chroma-connector.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md index c02e9fd1..17dc15cc 100644 --- a/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md +++ b/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/chroma-connector.md @@ -33,7 +33,7 @@ following characteristics. | Collection maps to | Chroma collection | | Supported key property types | string | | Supported data property types | All types that are supported by System.Text.Json (either built-in or by using a custom converter) | -| Supported vector property types |
    • list[float]
    • list[int]
    • ndarray]
    | +| Supported vector property types |
    • list[float]
    • list[int]
    • ndarray
    | | Supported index types |
    • HNSW
    | | Supported distance functions |
    • CosineSimilarity
    • DotProductSimilarity
    • EuclideanSquaredDistance
    | | Supported filter clauses |
    • AnyTagEqualTo
    • EqualTo
    | From 46168824a7af450bb4e200ee31d4b519ce02fdb4 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Tue, 4 Mar 2025 10:30:33 +0100 Subject: [PATCH 48/70] extended docs --- .../concepts/ai-services/realtime.md | 128 ++++++++++++++++-- 1 file changed, 115 insertions(+), 13 deletions(-) diff --git a/semantic-kernel/concepts/ai-services/realtime.md b/semantic-kernel/concepts/ai-services/realtime.md index 65eddf90..2dc801ba 100644 --- a/semantic-kernel/concepts/ai-services/realtime.md +++ b/semantic-kernel/concepts/ai-services/realtime.md @@ -10,16 +10,16 @@ ms.service: semantic-kernel # Realtime API integrations for Semantic Kernel -The first realtime API integration for Semantic Kernel has been added, it is currently only available in Python and considered experimental. This is because the underlying services are still being developed and are subject to changes. +The first realtime API integration for Semantic Kernel have been added, it is currently only available in Python and considered experimental. This is because the underlying services are still being developed and are subject to changes and we might need to make breaking changes to the API in Semantic Kernel as we learn from customers how to use this and as we add other providers of these kinds of models and APIs. ## Realtime Client abstraction -To support different realtime api's from different vendors, using different protocols, a new client abstraction has been added to the kernel. This client is used to connect to the realtime service and send and receive messages. +To support different realtime APIs from different vendors, using different protocols, a new client abstraction has been added to the kernel. This client is used to connect to the realtime service and send and receive messages. The client is responsible for handling the connection to the service, sending messages, and receiving messages. The client is also responsible for handling any errors that occur during the connection or message sending/receiving process. ### Realtime API -Any realtime client consists of the following methods: +Any realtime client implements the following methods: | Method | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------ | @@ -29,9 +29,9 @@ Any realtime client consists of the following methods: | `receive` | This is a asynchronous generator method that listens for messages from the service and yields them as they arrive. | | `send` | Sends a message to the service | -## Python implementations +### Python implementations -The python version of semantic kernel currently supports the following realtime clients: +The python version of Semantic Kernel currently supports the following realtime clients: | Client | Protocol | Modalities | Function calling enabled | Description | | ------ | --------- | ------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -47,28 +47,32 @@ To get started with the Realtime API, you need to install the `semantic-kernel` pip install semantic-kernel[realtime] ``` -Then you can create a kernel and add the realtime client to it. +Depending on how you want to handle audio, you might need additional packages to interface with speakers and microphones, like `pyaudio` or `sounddevice`. + +### Websocket clients + +Then you can create a kernel and add the realtime client to it, this shows how to do that with a AzureRealtimeWebsocket connection, you can replace AzureRealtimeWebsocket with OpenAIRealtimeWebsocket without any further changes. ```python from semantic_kernel.connectors.ai.open_ai import ( AzureRealtimeWebsocket, + AzureRealtimeExecutionSettings, ListenEvents, - OpenAIRealtimeExecutionSettings, ) from semantic_kernel.contents import RealtimeAudioEvent, RealtimeTextEvent # this will use environment variables to get the api key, endpoint, api version and deployment name. realtime_client = AzureRealtimeWebsocket() -settings = OpenAIRealtimeExecutionSettings() +settings = AzureRealtimeExecutionSettings(voice='alloy') async with realtime_client(settings=settings, create_response=True): async for event in realtime_client.receive(): match event: - # receiving a piece of audio + # receiving a piece of audio (and send it to a undefined audio player) case RealtimeAudioEvent(): await audio_player.add_audio(event.audio) # receiving a piece of audio transcript case RealtimeTextEvent(): - # the model returns both audio and transcript of the audio, which we will print + # Semantic Kernel parses the transcript to a TextContent object captured in a RealtimeTextEvent print(event.text.text, end="") case _: # OpenAI Specific events @@ -81,8 +85,106 @@ async with realtime_client(settings=settings, create_response=True): There are two important things to note, the first is that the `realtime_client` is an async context manager, this means that you can use it in an async function and use `async with` to create the session. The second is that the `receive` method is an async generator, this means that you can use it in a for loop to receive messages as they arrive. -In this simple example, we are passing the audio to a unspecified `audio_player` object, and printing the transcript as it arrives. +### WebRTC client + +The setup of a WebRTC connection is a bit more complex and so we need a extra parameter when creating the client. This parameter, `audio_track` needs to be a object that implements the `MediaStreamTrack` protocol of the `aiortc` package, this is also demonstrated in the samples that are linked below. + +To create a client that uses WebRTC, you would do the following: + +```python +from semantic_kernel.connectors.ai.open_ai import ( + ListenEvents, + OpenAIRealtimeExecutionSettings, + OpenAIRealtimeWebRTC, +) +from aiortc.mediastreams import MediaStreamTrack + +class AudioRecorderWebRTC(MediaStreamTrack): + # implement the MediaStreamTrack methods. + +realtime_client = OpenAIRealtimeWebRTC(audio_track=AudioRecorderWebRTC()) +# Create the settings for the session +settings = OpenAIRealtimeExecutionSettings( + instructions=""" +You are a chat bot. Your name is Mosscap and +you have one goal: figure out what people need. +Your full name, should you need to know it, is +Splendid Speckled Mosscap. You communicate +effectively, but you tend to answer with long +flowery prose. +""", + voice="shimmer", +) +audio_player = AudioPlayer +async with realtime_client(settings=settings, create_response=True): + async for event in realtime_client.receive(): + match event.event_type: + # receiving a piece of audio (and send it to a undefined audio player) + case "audio": + await audio_player.add_audio(event.audio) + case "text": + # the model returns both audio and transcript of the audio, which we will print + print(event.text.text, end="") + case "service": + # OpenAI Specific events + if event.service_type == ListenEvents.SESSION_UPDATED: + print("Session updated") + if event.service_type == ListenEvents.RESPONSE_CREATED: + print("\nMosscap (transcript): ", end="") +``` + +Both of these samples receive the audio as RealtimeAudioEvent and then they pass that to a unspecified audio_player object. + +### Audio output callback + +Next to this we have a parameter called `audio_output_callback` on the `receive` method and on the class creation. This callback will be called first before any further handling of the audio and gets a `numpy` array of the audio data, instead of it being parsed into AudioContent and returned as a RealtimeAudioEvent that you can then handle, which is what happens above. This has shown to give smoother audio output because there is less overhead between the audio data coming in and it being given to the player. + +This example shows how to define and use the `audio_output_callback`: + +```python +from semantic_kernel.connectors.ai.open_ai import ( + ListenEvents, + OpenAIRealtimeExecutionSettings, + OpenAIRealtimeWebRTC, +) +from aiortc.mediastreams import MediaStreamTrack + +class AudioRecorderWebRTC(MediaStreamTrack): + # implement the MediaStreamTrack methods. + +class AudioPlayer: + async def play_audio(self, content: np.ndarray): + # implement the audio player + +realtime_client = OpenAIRealtimeWebRTC(audio_track=AudioRecorderWebRTC()) +# Create the settings for the session +settings = OpenAIRealtimeExecutionSettings( + instructions=""" +You are a chat bot. Your name is Mosscap and +you have one goal: figure out what people need. +Your full name, should you need to know it, is +Splendid Speckled Mosscap. You communicate +effectively, but you tend to answer with long +flowery prose. +""", + voice="shimmer", +) +audio_player = AudioPlayer +async with realtime_client(settings=settings, create_response=True): + async for event in realtime_client.receive(audio_output_callback=audio_player.play_audio): + match event.event_type: + # no need to handle case: "audio" + case "text": + # the model returns both audio and transcript of the audio, which we will print + print(event.text.text, end="") + case "service": + # OpenAI Specific events + if event.service_type == ListenEvents.SESSION_UPDATED: + print("Session updated") + if event.service_type == ListenEvents.RESPONSE_CREATED: + print("\nMosscap (transcript): ", end="") +``` -There is also a `audio_output_callback` parameter on the client creation or on the `receive` method, this callback will be called first, and leads to smoother playback compared to the above example. +### Samples -See the samples in our repo [link to follow]. +There are four samples in [our repo](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/concepts/realtime), they cover both the basics using both websockets and WebRTC, as well as a more complex setup including function calling. Finally there is a more [complex demo](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/demos/call_automation) that uses [Azure Communication Services](https://learn.microsoft.com/en-us/azure/communication-services/) to allow you to call your Semantic Kernel enhanced realtime API. From 7f46baeaa98d94cb518522122c341ec1f5284d45 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Tue, 4 Mar 2025 10:48:20 +0100 Subject: [PATCH 49/70] fixed link --- semantic-kernel/concepts/ai-services/realtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/ai-services/realtime.md b/semantic-kernel/concepts/ai-services/realtime.md index 2dc801ba..fca6caa6 100644 --- a/semantic-kernel/concepts/ai-services/realtime.md +++ b/semantic-kernel/concepts/ai-services/realtime.md @@ -187,4 +187,4 @@ async with realtime_client(settings=settings, create_response=True): ### Samples -There are four samples in [our repo](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/concepts/realtime), they cover both the basics using both websockets and WebRTC, as well as a more complex setup including function calling. Finally there is a more [complex demo](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/demos/call_automation) that uses [Azure Communication Services](https://learn.microsoft.com/en-us/azure/communication-services/) to allow you to call your Semantic Kernel enhanced realtime API. +There are four samples in [our repo](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/concepts/realtime), they cover both the basics using both websockets and WebRTC, as well as a more complex setup including function calling. Finally there is a more [complex demo](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/demos/call_automation) that uses [Azure Communication Services](/azure/communication-services/) to allow you to call your Semantic Kernel enhanced realtime API. From 6941538d8ef310f4a7ca7d6c966c15d717707e41 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Tue, 4 Mar 2025 10:51:12 +0100 Subject: [PATCH 50/70] fixed header --- semantic-kernel/concepts/ai-services/realtime.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/semantic-kernel/concepts/ai-services/realtime.md b/semantic-kernel/concepts/ai-services/realtime.md index fca6caa6..afdd4568 100644 --- a/semantic-kernel/concepts/ai-services/realtime.md +++ b/semantic-kernel/concepts/ai-services/realtime.md @@ -1,6 +1,6 @@ --- title: Realtime AI Integrations for Semantic Kernel -description: Learn about realtime AI integrations available in Semantic Kernel. +description: Learn about realtime multi-modal AI integrations available in Semantic Kernel. author: eavanvalkenburg ms.topic: conceptual ms.author: edvan @@ -8,7 +8,7 @@ ms.date: 02/26/2025 ms.service: semantic-kernel --- -# Realtime API integrations for Semantic Kernel +# Realtime Multi-modal APIs The first realtime API integration for Semantic Kernel have been added, it is currently only available in Python and considered experimental. This is because the underlying services are still being developed and are subject to changes and we might need to make breaking changes to the API in Semantic Kernel as we learn from customers how to use this and as we add other providers of these kinds of models and APIs. From 8d555834dc1a16468bfc30593c65e77c9618d433 Mon Sep 17 00:00:00 2001 From: Chris Rickman Date: Wed, 5 Mar 2025 08:20:16 -0800 Subject: [PATCH 51/70] Sync fork to branch --- semantic-kernel/Frameworks/agent/TOC.yml | 2 + .../Frameworks/agent/assistant-agent.md | 2 +- .../Frameworks/agent/azure-ai-agent.md | 506 ++++++++++++++++++ .../Frameworks/agent/chat-completion-agent.md | 6 +- 4 files changed, 512 insertions(+), 4 deletions(-) create mode 100644 semantic-kernel/Frameworks/agent/azure-ai-agent.md diff --git a/semantic-kernel/Frameworks/agent/TOC.yml b/semantic-kernel/Frameworks/agent/TOC.yml index c85787ea..2d6709d8 100644 --- a/semantic-kernel/Frameworks/agent/TOC.yml +++ b/semantic-kernel/Frameworks/agent/TOC.yml @@ -6,6 +6,8 @@ href: chat-completion-agent.md - name: OpenAI Assistant Agent href: assistant-agent.md +- name: Azure AI Agent + href: azure-ai-agent.md - name: Agent Collaboration href: agent-chat.md - name: Create an Agent from a Template diff --git a/semantic-kernel/Frameworks/agent/assistant-agent.md b/semantic-kernel/Frameworks/agent/assistant-agent.md index 17ee3199..c40b1926 100644 --- a/semantic-kernel/Frameworks/agent/assistant-agent.md +++ b/semantic-kernel/Frameworks/agent/assistant-agent.md @@ -8,7 +8,7 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# Exploring the _Semantic Kernel_ `OpenAIAssistantAgent` +# Exploring the Semantic Kernel `OpenAIAssistantAgent` > [!IMPORTANT] > This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. diff --git a/semantic-kernel/Frameworks/agent/azure-ai-agent.md b/semantic-kernel/Frameworks/agent/azure-ai-agent.md new file mode 100644 index 00000000..1eb27431 --- /dev/null +++ b/semantic-kernel/Frameworks/agent/azure-ai-agent.md @@ -0,0 +1,506 @@ +--- +title: Exploring the Semantic Kernel Azure AI Agent Agent +description: An exploration of the definition, behaviors, and usage patterns for an Azure AI Agent +zone_pivot_groups: programming-languages +author: moonbox3 +ms.topic: tutorial +ms.author: evmattso +ms.date: 03/05/2025 +ms.service: semantic-kernel +--- +# Exploring the Semantic Kernel `AzureAIAgent` + +> [!IMPORTANT] +> This feature is in the experimental stage. Features at this stage are still under development and subject to change before advancing to the preview or release candidate stage. + +Detailed API documentation related to this discussion is available at: + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" + +> Updated Semantic Kernel Python API Docs are coming soon. + +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +## What is an `AzureAIAgent`? + +An `AzureAIAgent` is a specialized agent within the Semantic Kernel framework, designed to provide advanced conversational capabilities with seamless tool integration. It automates tool calling, eliminating the need for manual parsing and invocation. The agent also securely manages conversation history using threads, reducing the overhead of maintaining state. Additionally, the `AzureAIAgent` supports a variety of built-in tools, including file retrieval, code execution, and data interaction via Bing, Azure AI Search, Azure Functions, and OpenAPI. + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" + +To set up the required resources, follow the "Quickstart: Create a new agent" guide [here](/azure/ai-services/agents/quickstart?pivots=programming-language-python-azure). + +You will need to install the optional Semantic Kernel azure dependencies if you haven't already via: + +```bash +pip install semantic-kernel[azure] +``` + +Before running an `AzureAIAgent`, modify your .env file to include: + +```bash +AZURE_AI_AGENT_PROJECT_CONNECTION_STRING = "" +AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME = "" +``` + +or + +```bash +AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME = "" +AZURE_AI_AGENT_ENDPOINT = "" +AZURE_AI_AGENT_SUBSCRIPTION_ID = "" +AZURE_AI_AGENT_RESOURCE_GROUP_NAME = "" +AZURE_AI_AGENT_PROJECT_NAME = "" +``` + +The project connection string is of the following format: `;;;`. See here for information on obtaining the values to populate the connection string. + +The `.env` should be placed in the root directory. + +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +## Configuring the AI Project Client + +Ensure that your `AzureAIAgent` resources are configured with at least a Basic or Standard SKU (the Standard SKU is required to do more advanced operations like AI Search). + +To begin, create the project client as follows: + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" + +```python +async with ( + DefaultAzureCredential() as creds, + AzureAIAgent.create_client(credential=creds) as client, +): + # Your operational code here +``` + +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +## Creating an `AzureAIAgent` + +To create an `AzureAIAgent`, you start by configuring and initializing the agent project through the Azure AI service and then integrate it with Semantic Kernel: + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" + +```python +from azure.identity.aio import DefaultAzureCredential +from semantic_kernel.agents.azure_ai import AzureAIAgent, AzureAIAgentSettings + +ai_agent_settings = AzureAIAgentSettings.create() + +async with ( + DefaultAzureCredential() as creds, + AzureAIAgent.create_client(credential=creds) as client, +): + # 1. Create an agent on the Azure AI agent service + agent_definition = await client.agents.create_agent( + model=ai_agent_settings.model_deployment_name, + name="", + instructions="", + ) + + # 2. Create a Semantic Kernel agent to use the Azure AI agent + agent = AzureAIAgent( + client=client, + definition=agent_definition, + ) +``` + +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +## Interacting with an `AzureAIAgent` + +Interaction with the `AzureAIAgent` is straightforward. The agent maintains the conversation history automatically using a thread: + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" + +```python +USER_INPUTS = ["Hello", "What's your name?"] + +thread = await client.agents.create_thread() + +try: + for user_input in USER_INPUTS: + await agent.add_chat_message(thread_id=thread.id, message=user_input) + response = await agent.get_response(thread_id=thread.id) + print(response) +finally: + await client.agents.delete_thread(thread.id) +``` + +Python also supports invoking an agent in a streaming and a non-streaming fashion: + +```python +# Streaming +for user_input in USER_INPUTS: + await agent.add_chat_message(thread_id=thread.id, message=user_input) + async for content in agent.invoke_stream(thread_id=thread.id): + print(content.content, end="", flush=True) +``` + +```python +# Non-streaming +for user_input in USER_INPUTS: + await agent.add_chat_message(thread_id=thread.id, message=user_input) + async for content in agent.invoke(thread_id=thread.id): + print(content.content) +``` +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +## Using Plugins with an `AzureAIAgent` + +Semantic Kernel supports extending an `AzureAIAgent` with custom plugins for enhanced functionality: + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" + +```python +from semantic_kernel.functions import kernel_function + +class SamplePlugin: + @kernel_function(description="Provides sample data.") + def get_data(self) -> str: + return "Sample data" + +ai_agent_settings = AzureAIAgentSettings.create() + +async with ( + DefaultAzureCredential() as creds, + AzureAIAgent.create_client(credential=creds) as client, + ): + agent_definition = await client.agents.create_agent( + model=ai_agent_settings.model_deployment_name, + ) + + agent = AzureAIAgent( + client=client, + definition=agent_definition, + plugins=[SamplePlugin()] + ) +``` +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +## Advanced Features + +An `AzureAIAgent` can leverage advanced tools such as code interpreters, file search, OpenAPI and Azure AI Search integration for dynamic and powerful interactions: + +### Code Interpreter + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" +```python +from azure.ai.projects.models import CodeInterpreterTool + +async with ( + DefaultAzureCredential() as creds, + AzureAIAgent.create_client(credential=creds) as client, + ): + code_interpreter = CodeInterpreterTool() + agent_definition = await client.agents.create_agent( + model=ai_agent_settings.model_deployment_name, + tools=code_interpreter.definitions, + tool_resources=code_interpreter.resources, + ) +``` +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +### File Search + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" +```python +from azure.ai.projects.models import FileSearchTool + +async with ( + DefaultAzureCredential() as creds, + AzureAIAgent.create_client(credential=creds) as client, + ): + file_search = FileSearchTool(vector_store_ids=[vector_store.id]) + agent_definition = await client.agents.create_agent( + model=ai_agent_settings.model_deployment_name, + tools=file_search.definitions, + tool_resources=file_search.resources, + ) +``` +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +### OpenAPI Integration + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" + +```python +from azure.ai.projects.models import OpenApiTool, OpenApiAnonymousAuthDetails + +async with ( + DefaultAzureCredential() as creds, + AzureAIAgent.create_client(credential=creds) as client, + ): + openapi_spec_file_path = "sample/filepath/..." + with open(os.path.join(openapi_spec_file_path, "spec_one.json")) as file_one: + openapi_spec_one = json.loads(file_one.read()) + with open(os.path.join(openapi_spec_file_path, "spec_two.json")) as file_two: + openapi_spec_two = json.loads(file_two.read()) + + # Note that connection or managed identity auth setup requires additional setup in Azure + auth = OpenApiAnonymousAuthDetails() + openapi_tool_one = OpenApiTool( + name="", + spec=openapi_spec_one, + description="", + auth=auth, + ) + openapi_tool_two = OpenApiTool( + name="", + spec=openapi_spec_two, + description="", + auth=auth, + ) + + agent_definition = await client.agents.create_agent( + model=ai_agent_settings.model_deployment_name, + tools=openapi_tool_one.definitions + openapi_tool_two.definitions, + ) +``` +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +### AzureAI Search + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" + +```python +from azure.ai.projects.models import AzureAISearchTool, ConnectionType + +async with ( + DefaultAzureCredential() as creds, + AzureAIAgent.create_client(credential=creds) as client, + ): + conn_list = await client.connections.list() + + ai_search_conn_id = "" + for conn in conn_list: + if conn.connection_type == ConnectionType.AZURE_AI_SEARCH: + ai_search_conn_id = conn.id + break + + ai_search = AzureAISearchTool( + index_connection_id=ai_search_conn_id, + index_name=AZURE_AI_SEARCH_INDEX_NAME, + ) + + agent_definition = await client.agents.create_agent( + model=ai_agent_settings.model_deployment_name, + instructions="Answer questions using your index.", + tools=ai_search.definitions, + tool_resources=ai_search.resources, + headers={"x-ms-enable-preview": "true"}, + ) +``` +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +### Retrieving Existing `AzureAIAgent` + +An existing agent can be retrieved and reused by specifying its assistant ID: + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" +```python +agent_definition = await client.agents.get_agent(assistant_id="your-agent-id") +agent = AzureAIAgent(client=client, definition=agent_definition) +``` +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +## Deleting an `AzureAIAgent` + +Agents and their associated threads can be deleted when no longer needed: + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" +```python +await client.agents.delete_thread(thread.id) +await client.agents.delete_agent(agent.id) +``` + +If working with a vector store or files, they can be deleted as well: + +```python +await client.agents.delete_file(file_id=file.id) +await client.agents.delete_vector_store(vector_store_id=vector_store.id) +``` + +> [!TIP] +> To remove a file from a vector store, use: +> ```python +> await client.agents.delete_vector_store_file(vector_store_id=vector_store.id, file_id=file.id) +> ``` +> This operation detaches the file from the vector store but does not permanently delete it. +> To fully delete the file, call: +> ```python +> await client.agents.delete_file(file_id=file.id) +> ``` + +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +## How-To + +For practical examples of using an `AzureAIAgent`, see our code samples on GitHub: + +::: zone pivot="programming-language-csharp" + +> TODO(crickman) Azure AI Agents are currently unavailable in .NET. + +::: zone-end + +::: zone pivot="programming-language-python" + +- [Getting Started with Azure AI Agents](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/getting_started_with_agents/azure_ai_agent) +- [Advanced Azure AI Agent Code Samples](https://github.com/microsoft/semantic-kernel/tree/main/python/samples/concepts/agents/azure_ai_agent) + +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + +> [!div class="nextstepaction"] +> [Agent Collaboration in `AgentChat`](./agent-chat.md) \ No newline at end of file diff --git a/semantic-kernel/Frameworks/agent/chat-completion-agent.md b/semantic-kernel/Frameworks/agent/chat-completion-agent.md index d1044239..7e95e1b4 100644 --- a/semantic-kernel/Frameworks/agent/chat-completion-agent.md +++ b/semantic-kernel/Frameworks/agent/chat-completion-agent.md @@ -8,7 +8,7 @@ ms.author: crickman ms.date: 09/13/2024 ms.service: semantic-kernel --- -# Exploring the _Semantic Kernel_ Chat Completion Agent +# Exploring the Semantic Kernel `ChatCompletionAgent` > [!IMPORTANT] > This feature is in the release candidate stage. Features at this stage are nearly complete and generally stable, though they may undergo minor refinements or optimizations before reaching full general availability. @@ -224,7 +224,7 @@ agent = ChatCompletionAgent(...) chat = ChatHistory() # Add the user message -chat.add_message(ChatMessageContent(role=AuthorRole.USER, content=input)) +chat.add_user_message(user_input)) # Generate the agent response response = await agent.get_response(chat) @@ -240,7 +240,7 @@ agent = ChatCompletionAgent(...) chat = ChatHistory() # Add the user message -chat.add_user_message(ChatMessageContent(role=AuthorRole.USER, content=input)) +chat.add_user_message(user_input) # Generate the agent response(s) async for response in agent.invoke(chat): From 1e2bd838eb8e16d8e96dc52aa173aae269a2e7d6 Mon Sep 17 00:00:00 2001 From: Chris Rickman Date: Wed, 5 Mar 2025 11:27:25 -0800 Subject: [PATCH 52/70] ChatCompletion tweak --- semantic-kernel/Frameworks/agent/chat-completion-agent.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/chat-completion-agent.md b/semantic-kernel/Frameworks/agent/chat-completion-agent.md index 7e95e1b4..f5a8aa81 100644 --- a/semantic-kernel/Frameworks/agent/chat-completion-agent.md +++ b/semantic-kernel/Frameworks/agent/chat-completion-agent.md @@ -1,5 +1,5 @@ --- -title: Exploring the Semantic Kernel Chat Completion Agent +title: Exploring the Semantic Kernel ChatCompletionAgent description: An exploration of the definition, behaviors, and usage patterns for a Chat Completion Agent zone_pivot_groups: programming-languages author: crickman @@ -74,7 +74,7 @@ Onnx|[`Microsoft.SemanticKernel.Connectors.Onnx`](/dotnet/api/microsoft.semantic ::: zone-end -## Creating a Chat Completion Agent +## Creating a `ChatCompletionAgent` A _chat completion agent_ is fundamentally based on an [AI services](../../concepts/ai-services/index.md). As such, creating an _chat completion agent_ starts with creating a [`Kernel`](../../concepts/kernel.md) instance that contains one or more chat-completion services and then instantiating the agent with a reference to that [`Kernel`](../../concepts/kernel.md) instance. From 469b32f227433400997224fe68fa7d33fbd690e2 Mon Sep 17 00:00:00 2001 From: Chris Rickman Date: Wed, 5 Mar 2025 11:36:27 -0800 Subject: [PATCH 53/70] Assistant overview update --- .../Frameworks/agent/assistant-agent.md | 36 ++++++++----------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/assistant-agent.md b/semantic-kernel/Frameworks/agent/assistant-agent.md index c40b1926..755850dc 100644 --- a/semantic-kernel/Frameworks/agent/assistant-agent.md +++ b/semantic-kernel/Frameworks/agent/assistant-agent.md @@ -51,15 +51,13 @@ Creating an `OpenAIAssistant` requires invoking a remote service, which is handl ::: zone pivot="programming-language-csharp" ```csharp -OpenAIAssistantAgent agent = - await OpenAIAssistantAgent.CreateAsync( - OpenAIClientProvider.ForAzureOpenAI(/*<...service configuration>*/), - new OpenAIAssistantDefinition("") - { - Name = "", - Instructions = "", - }, - new Kernel()); +AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient(); +Assistant assistant = + await this.AssistantClient.CreateAssistantAsync( + "", + "", + instructions: ""); +OpenAIAssistantAgent agent = new(assistant, client); ``` ::: zone-end @@ -119,11 +117,9 @@ Once created, the identifier of the assistant may be access via its identifier. For .NET, the agent identifier is exposed as a `string` via the property defined by any agent. ```csharp -OpenAIAssistantAgent agent = - await OpenAIAssistantAgent.RetrieveAsync( - OpenAIClientProvider.ForAzureOpenAI(/*<...service configuration>*/), - "", - new Kernel()); +AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient(); +Assistant assistant = await this.AssistantClient.GetAssistantAsync(""); +OpenAIAssistantAgent agent = new(assistant, client); ``` ::: zone-end @@ -220,20 +216,18 @@ await agent.delete_thread(thread_id) ## Deleting an `OpenAIAssistantAgent` -Since the assistant's definition is stored remotely, it supports the capability to self-delete. This enables the agent to be removed from the system when it is no longer needed. +Since the assistant's definition is stored remotely, it will persist if not deleted. +Deleting an assistant definition may be performed directly with the `AssistantClient`. -> Note: Attempting to use an agent instance after being deleted results in an exception. +> Note: Attempting to use an agent instance after being deleted will result in a service exception. ::: zone pivot="programming-language-csharp" For .NET, the agent identifier is exposed as a `string` via the [`Agent.Id`](/dotnet/api/microsoft.semantickernel.agents.agent.id) property defined by any agent. ```csharp -// Perform the deletion -await agent.DeleteAsync(); - -// Inspect whether an agent has been deleted -bool isDeleted = agent.IsDeleted(); +AssistantClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(...).GetAssistantClient(); +Assistant assistant = await this.AssistantClient.DeleteAssistantAsync(""); ``` ::: zone-end From dd3cb7758672146815e329a92278559e78b22bbb Mon Sep 17 00:00:00 2001 From: Chris Rickman Date: Wed, 5 Mar 2025 12:59:25 -0800 Subject: [PATCH 54/70] Update assistant "howto" --- .../Frameworks/agent/assistant-agent.md | 2 - .../examples/example-agent-collaboration.md | 4 - .../agent/examples/example-assistant-code.md | 115 +++++++++--------- .../examples/example-assistant-search.md | 110 ++++++++--------- 4 files changed, 114 insertions(+), 117 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/assistant-agent.md b/semantic-kernel/Frameworks/agent/assistant-agent.md index 755850dc..44fa6e9f 100644 --- a/semantic-kernel/Frameworks/agent/assistant-agent.md +++ b/semantic-kernel/Frameworks/agent/assistant-agent.md @@ -17,8 +17,6 @@ Detailed API documentation related to this discussion is available at: ::: zone pivot="programming-language-csharp" - [`OpenAIAssistantAgent`](/dotnet/api/microsoft.semantickernel.agents.openai.openaiassistantagent) -- [`OpenAIAssistantDefinition`](/dotnet/api/microsoft.semantickernel.agents.openai.openaiassistantdefinition) -- [`OpenAIClientProvider`](/dotnet/api/microsoft.semantickernel.agents.openai.openaiclientprovider) ::: zone-end diff --git a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md index d557c7fc..832b8fac 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md +++ b/semantic-kernel/Frameworks/agent/examples/example-agent-collaboration.md @@ -862,8 +862,6 @@ Try using these suggested inputs: 8. its good, but is it ready for my college professor? ```csharp -// Copyright (c) Microsoft. All rights reserved. - using System; using System.ComponentModel; using System.Diagnostics; @@ -1131,8 +1129,6 @@ You can try using one of the suggested inputs. As the agent chat begins, the age > You can reference any file by providing `@`. To reference the "WomensSuffrage" text from above, download it [here](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/learn_resources/resources/WomensSuffrage.txt) and place it in your current working directory. You can then reference it with `@WomensSuffrage.txt`. ```python -# Copyright (c) Microsoft. All rights reserved. - import asyncio import os diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index be6fdc4d..aadcba51 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -208,13 +208,12 @@ The full example code is provided in the [Final](#final) section. Refer to that Prior to creating an `OpenAIAssistantAgent`, ensure the configuration settings are available and prepare the file resources. -Instantiate the `Settings` class referenced in the previous [Configuration](#configuration) section. Use the settings to also create an `OpenAIClientProvider` that will be used for the [Agent Definition](#agent-definition) as well as file-upload. +Instantiate the `Settings` class referenced in the previous [Configuration](#configuration) section. Use the settings to also create an `AzureOpenAIClient` that will be used for the [Agent Definition](#agent-definition) as well as file-upload. ```csharp Settings settings = new(); -OpenAIClientProvider clientProvider = - OpenAIClientProvider.ForAzureOpenAI(new AzureCliCredential(), new Uri(settings.AzureOpenAI.Endpoint)); +AzureOpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(settings.AzureOpenAI.Endpoint)); ``` ::: zone-end @@ -226,11 +225,11 @@ OpenAIClientProvider clientProvider = ::: zone pivot="programming-language-csharp" -Use the `OpenAIClientProvider` to access an `OpenAIFileClient` and upload the two data-files described in the previous [Configuration](#configuration) section, preserving the _File Reference_ for final clean-up. +Use the `AzureOpenAIClient` to access an `OpenAIFileClient` and upload the two data-files described in the previous [Configuration](#configuration) section, preserving the _File Reference_ for final clean-up. ```csharp Console.WriteLine("Uploading files..."); -OpenAIFileClient fileClient = clientProvider.Client.GetOpenAIFileClient(); +OpenAIFileClient fileClient = client.GetOpenAIFileClient(); OpenAIFile fileDataCountryDetail = await fileClient.UploadFileAsync("PopulationByAdmin1.csv", FileUploadPurpose.Assistants); OpenAIFile fileDataCountryList = await fileClient.UploadFileAsync("PopulationByCountry.csv", FileUploadPurpose.Assistants); ``` @@ -303,27 +302,27 @@ We first set up the Azure OpenAI resources to obtain the client and model. Next, ::: zone pivot="programming-language-csharp" -We are now ready to instantiate an `OpenAIAssistantAgent`. The agent is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. +We are now ready to instantiate an `OpenAIAssistantAgent` by first creating an assistant definition. The assistant is configured with its target model, _Instructions_, and the _Code Interpreter_ tool enabled. Additionally, we explicitly associate the two data files with the _Code Interpreter_ tool. ```csharp Console.WriteLine("Defining agent..."); -OpenAIAssistantAgent agent = - await OpenAIAssistantAgent.CreateAsync( - clientProvider, - new OpenAIAssistantDefinition(settings.AzureOpenAI.ChatModelDeployment) - { - Name = "SampleAssistantAgent", - Instructions = - """ - Analyze the available data to provide an answer to the user's question. - Always format response using markdown. - Always include a numerical index that starts at 1 for any lists or tables. - Always sort lists in ascending order. - """, - EnableCodeInterpreter = true, - CodeInterpreterFileIds = [fileDataCountryList.Id, fileDataCountryDetail.Id], - }, - new Kernel()); +AssistantClient assistantClient = client.GetAssistantClient(); + Assistant assistant = + await assistantClient.CreateAssistantAsync( + settings.AzureOpenAI.ChatModelDeployment, + name: "SampleAssistantAgent", + instructions: + """ + Analyze the available data to provide an answer to the user's question. + Always format response using markdown. + Always include a numerical index that starts at 1 for any lists or tables. + Always sort lists in ascending order. + """, + enableCodeInterpreter: true, + codeInterpreterFileIds: [fileDataCountryList.Id, fileDataCountryDetail.Id]); + +// Create agent +OpenAIAssistantAgent agent = new(assistant, assistantClient); ``` ::: zone-end @@ -355,7 +354,7 @@ Let's also ensure the resources are removed at the end of execution to minimize ::: zone pivot="programming-language-csharp" ```csharp Console.WriteLine("Creating thread..."); -string threadId = await agent.CreateThreadAsync(); +AssistantThread thread = await assistantClient.CreateThreadAsync(); Console.WriteLine("Ready!"); @@ -374,8 +373,8 @@ finally Console.WriteLine("Cleaning-up..."); await Task.WhenAll( [ - agent.DeleteThreadAsync(threadId), - agent.DeleteAsync(), + assistantClient.DeleteThreadAsync(thread.Id), + assistantClient.DeleteAssistantAsync(assistant.Id), fileClient.DeleteFileAsync(fileDataCountryList.Id), fileClient.DeleteFileAsync(fileDataCountryDetail.Id), ]); @@ -424,7 +423,7 @@ if (input.Trim().Equals("EXIT", StringComparison.OrdinalIgnoreCase)) break; } -await agent.AddChatMessageAsync(threadId, new ChatMessageContent(AuthorRole.User, input)); +await agent.AddChatMessageAsync(thread.Id, new ChatMessageContent(AuthorRole.User, input)); Console.WriteLine(); ``` @@ -542,7 +541,7 @@ To generate an `Agent` response to user input, invoke the agent by specifying th ::: zone pivot="programming-language-csharp" ```csharp bool isCode = false; -await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(threadId)) +await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(thread.Id)) { if (isCode != (response.Metadata?.ContainsKey(OpenAIAssistantAgent.CodeInterpreterMetadataKey) ?? false)) { @@ -604,17 +603,21 @@ Try using these suggested inputs: ::: zone pivot="programming-language-csharp" ```csharp +using Azure.AI.OpenAI; +using Azure.Identity; +using Microsoft.SemanticKernel; +using Microsoft.SemanticKernel.Agents.OpenAI; +using Microsoft.SemanticKernel.ChatCompletion; +using OpenAI; +using OpenAI.Assistants; +using OpenAI.Files; using System; +using System.ClientModel; using System.Collections.Generic; using System.Diagnostics; using System.IO; using System.Linq; using System.Threading.Tasks; -using Azure.Identity; -using Microsoft.SemanticKernel; -using Microsoft.SemanticKernel.Agents.OpenAI; -using Microsoft.SemanticKernel.ChatCompletion; -using OpenAI.Files; namespace AgentsSample; @@ -625,35 +628,39 @@ public static class Program // Load configuration from environment variables or user secrets. Settings settings = new(); - OpenAIClientProvider clientProvider = - OpenAIClientProvider.ForAzureOpenAI(new AzureCliCredential(), new Uri(settings.AzureOpenAI.Endpoint)); + // Initialize the clients + AzureOpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(settings.AzureOpenAI.Endpoint)); + //OpenAIClient client = OpenAIAssistantAgent.CreateOpenAIClient(new ApiKeyCredential(settings.OpenAI.ApiKey))); + AssistantClient assistantClient = client.GetAssistantClient(); + OpenAIFileClient fileClient = client.GetOpenAIFileClient(); + // Upload files Console.WriteLine("Uploading files..."); - OpenAIFileClient fileClient = clientProvider.Client.GetOpenAIFileClient(); OpenAIFile fileDataCountryDetail = await fileClient.UploadFileAsync("PopulationByAdmin1.csv", FileUploadPurpose.Assistants); OpenAIFile fileDataCountryList = await fileClient.UploadFileAsync("PopulationByCountry.csv", FileUploadPurpose.Assistants); - Console.WriteLine("Defining agent..."); - OpenAIAssistantAgent agent = - await OpenAIAssistantAgent.CreateAsync( - clientProvider, - new OpenAIAssistantDefinition(settings.AzureOpenAI.ChatModelDeployment) - { - Name = "SampleAssistantAgent", - Instructions = + // Define assistant + Console.WriteLine("Defining assistant..."); + Assistant assistant = + await assistantClient.CreateAssistantAsync( + settings.AzureOpenAI.ChatModelDeployment, + name: "SampleAssistantAgent", + instructions: """ Analyze the available data to provide an answer to the user's question. Always format response using markdown. Always include a numerical index that starts at 1 for any lists or tables. Always sort lists in ascending order. """, - EnableCodeInterpreter = true, - CodeInterpreterFileIds = [fileDataCountryList.Id, fileDataCountryDetail.Id], - }, - new Kernel()); + enableCodeInterpreter: true, + codeInterpreterFileIds: [fileDataCountryList.Id, fileDataCountryDetail.Id]); + // Create agent + OpenAIAssistantAgent agent = new(assistant, assistantClient); + + // Create the conversation thread Console.WriteLine("Creating thread..."); - string threadId = await agent.CreateThreadAsync(); + AssistantThread thread = await assistantClient.CreateThreadAsync(); Console.WriteLine("Ready!"); @@ -676,12 +683,12 @@ public static class Program break; } - await agent.AddChatMessageAsync(threadId, new ChatMessageContent(AuthorRole.User, input)); + await agent.AddChatMessageAsync(thread.Id, new ChatMessageContent(AuthorRole.User, input)); Console.WriteLine(); bool isCode = false; - await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(threadId)) + await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(thread.Id)) { if (isCode != (response.Metadata?.ContainsKey(OpenAIAssistantAgent.CodeInterpreterMetadataKey) ?? false)) { @@ -709,8 +716,8 @@ public static class Program Console.WriteLine("Cleaning-up..."); await Task.WhenAll( [ - agent.DeleteThreadAsync(threadId), - agent.DeleteAsync(), + assistantClient.DeleteThreadAsync(thread.Id), + assistantClient.DeleteAssistantAsync(assistant.Id), fileClient.DeleteFileAsync(fileDataCountryList.Id), fileClient.DeleteFileAsync(fileDataCountryDetail.Id), ]); @@ -761,8 +768,6 @@ public static class Program ::: zone pivot="programming-language-python" ```python -# Copyright (c) Microsoft. All rights reserved. - import asyncio import logging import os diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index 1aad1696..80b8c2e0 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -209,16 +209,12 @@ Prior to creating an `OpenAIAssistantAgent`, ensure the configuration settings a ::: zone pivot="programming-language-csharp" -Instantiate the `Settings` class referenced in the previous [Configuration](#configuration) section. Use the settings to also create an `OpenAIClientProvider` that will be used for the [Agent Definition](#agent-definition) as well as file-upload and the creation of a `VectorStore`. +Instantiate the `Settings` class referenced in the previous [Configuration](#configuration) section. Use the settings to also create an `AzureOpenAIClient` that will be used for the [Agent Definition](#agent-definition) as well as file-upload and the creation of a `VectorStore`. ```csharp - Settings settings = new(); -OpenAIClientProvider clientProvider = - OpenAIClientProvider.ForAzureOpenAI( - new AzureCliCredential(), - new Uri(settings.AzureOpenAI.Endpoint)); +AzureOpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(settings.AzureOpenAI.Endpoint)); ``` ::: zone-end @@ -242,11 +238,11 @@ Now create an empty _Vector Store for use with the _File Search_ tool: ::: zone pivot="programming-language-csharp" -Use the `OpenAIClientProvider` to access a `VectorStoreClient` and create a `VectorStore`. +Use the `AzureOpenAIClient` to access a `VectorStoreClient` and create a `VectorStore`. ```csharp Console.WriteLine("Creating store..."); -VectorStoreClient storeClient = clientProvider.Client.GetVectorStoreClient(); +VectorStoreClient storeClient = client.GetVectorStoreClient(); CreateVectorStoreOperation operation = await storeClient.CreateVectorStoreAsync(waitUntilCompleted: true); string storeId = operation.VectorStoreId; ``` @@ -317,7 +313,7 @@ Now upload those files and add them to the _Vector Store_ by using the previousl Dictionary fileReferences = []; Console.WriteLine("Uploading files..."); -OpenAIFileClient fileClient = clientProvider.Client.GetOpenAIFileClient(); +OpenAIFileClient fileClient = client.GetOpenAIFileClient(); foreach (string fileName in _fileNames) { OpenAIFile fileInfo = await fileClient.UploadFileAsync(fileName, FileUploadPurpose.Assistants); @@ -339,27 +335,26 @@ We are now ready to instantiate an `OpenAIAssistantAgent`. The agent is configur ::: zone pivot="programming-language-csharp" -We will utilize the `OpenAIClientProvider` again as part of creating the `OpenAIAssistantAgent`: +We will utilize the `AzureOpenAIClient` again as part of creating the `OpenAIAssistantAgent`: ```csharp -Console.WriteLine("Defining agent..."); -OpenAIAssistantAgent agent = - await OpenAIAssistantAgent.CreateAsync( - clientProvider, - new OpenAIAssistantDefinition(settings.AzureOpenAI.ChatModelDeployment) - { - Name = "SampleAssistantAgent", - Instructions = +Console.WriteLine("Defining assistant..."); +Assistant assistant = + await assistantClient.CreateAssistantAsync( + settings.AzureOpenAI.ChatModelDeployment, + name: "SampleAssistantAgent", + instructions: """ The document store contains the text of fictional stories. Always analyze the document store to provide an answer to the user's question. Never rely on your knowledge of stories not included in the document store. Always format response using markdown. """, - EnableFileSearch = true, - VectorStoreId = storeId, - }, - new Kernel()); + enableFileSearch: true, + vectorStoreId: storeId); + +// Create agent +OpenAIAssistantAgent agent = new(assistant, assistantClient); ``` ::: zone-end @@ -402,7 +397,7 @@ Let's also ensure the resources are removed at the end of execution to minimize ::: zone pivot="programming-language-csharp" ```csharp Console.WriteLine("Creating thread..."); -string threadId = await agent.CreateThreadAsync(); +AssistantThread thread = await assistantClient.CreateThreadAsync(); Console.WriteLine("Ready!"); @@ -420,8 +415,8 @@ finally Console.WriteLine("Cleaning-up..."); await Task.WhenAll( [ - agent.DeleteThreadAsync(threadId), - agent.DeleteAsync(), + assistantClient.DeleteThreadAsync(thread.Id), + assistantClient.DeleteAssistantAsync(assistant.Id), storeClient.DeleteVectorStoreAsync(storeId), ..fileReferences.Select(fileReference => fileClient.DeleteFileAsync(fileReference.Key)) ]); @@ -471,7 +466,7 @@ if (input.Trim().Equals("EXIT", StringComparison.OrdinalIgnoreCase)) break; } -await agent.AddChatMessageAsync(threadId, new ChatMessageContent(AuthorRole.User, input)); +await agent.AddChatMessageAsync(thread.Id, new ChatMessageContent(AuthorRole.User, input)); Console.WriteLine(); ``` ::: zone-end @@ -524,7 +519,7 @@ To generate an `Agent` response to user input, invoke the agent by specifying th ::: zone pivot="programming-language-csharp" ```csharp List footnotes = []; -await foreach (StreamingChatMessageContent chunk in agent.InvokeStreamingAsync(threadId)) +await foreach (StreamingChatMessageContent chunk in agent.InvokeStreamingAsync(thread.Id)) { // Capture annotations for footnotes footnotes.AddRange(chunk.Items.OfType()); @@ -586,13 +581,18 @@ Try using these suggested inputs: ::: zone pivot="programming-language-csharp" ```csharp using System; +using System.ClientModel; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; +using Azure.AI.OpenAI; using Azure.Identity; using Microsoft.SemanticKernel; +using Microsoft.SemanticKernel.Agents; using Microsoft.SemanticKernel.Agents.OpenAI; using Microsoft.SemanticKernel.ChatCompletion; +using OpenAI; +using OpenAI.Assistants; using OpenAI.Files; using OpenAI.VectorStores; @@ -616,21 +616,21 @@ public static class Program // Load configuration from environment variables or user secrets. Settings settings = new(); - OpenAIClientProvider clientProvider = - OpenAIClientProvider.ForAzureOpenAI( - new AzureCliCredential(), - new Uri(settings.AzureOpenAI.Endpoint)); + // Initialize the clients + AzureOpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri(settings.AzureOpenAI.Endpoint)); + //OpenAIClient client = OpenAIAssistantAgent.CreateOpenAIClient(new ApiKeyCredential(settings.OpenAI.ApiKey))); + AssistantClient assistantClient = client.GetAssistantClient(); + OpenAIFileClient fileClient = client.GetOpenAIFileClient(); + VectorStoreClient storeClient = client.GetVectorStoreClient(); + // Create the vector store Console.WriteLine("Creating store..."); - VectorStoreClient storeClient = clientProvider.Client.GetVectorStoreClient(); CreateVectorStoreOperation operation = await storeClient.CreateVectorStoreAsync(waitUntilCompleted: true); string storeId = operation.VectorStoreId; - // Retain file references. - Dictionary fileReferences = []; - + // Upload files and retain file references. Console.WriteLine("Uploading files..."); - OpenAIFileClient fileClient = clientProvider.Client.GetOpenAIFileClient(); + Dictionary fileReferences = []; foreach (string fileName in _fileNames) { OpenAIFile fileInfo = await fileClient.UploadFileAsync(fileName, FileUploadPurpose.Assistants); @@ -638,28 +638,28 @@ public static class Program fileReferences.Add(fileInfo.Id, fileInfo); } - - Console.WriteLine("Defining agent..."); - OpenAIAssistantAgent agent = - await OpenAIAssistantAgent.CreateAsync( - clientProvider, - new OpenAIAssistantDefinition(settings.AzureOpenAI.ChatModelDeployment) - { - Name = "SampleAssistantAgent", - Instructions = + // Define assistant + Console.WriteLine("Defining assistant..."); + Assistant assistant = + await assistantClient.CreateAssistantAsync( + settings.AzureOpenAI.ChatModelDeployment, + name: "SampleAssistantAgent", + instructions: """ The document store contains the text of fictional stories. Always analyze the document store to provide an answer to the user's question. Never rely on your knowledge of stories not included in the document store. Always format response using markdown. """, - EnableFileSearch = true, - VectorStoreId = storeId, - }, - new Kernel()); + enableFileSearch: true, + vectorStoreId: storeId); + // Create agent + OpenAIAssistantAgent agent = new(assistant, assistantClient); + + // Create the conversation thread Console.WriteLine("Creating thread..."); - string threadId = await agent.CreateThreadAsync(); + AssistantThread thread = await assistantClient.CreateThreadAsync(); Console.WriteLine("Ready!"); @@ -681,11 +681,11 @@ public static class Program break; } - await agent.AddChatMessageAsync(threadId, new ChatMessageContent(AuthorRole.User, input)); + await agent.AddChatMessageAsync(thread.Id, new ChatMessageContent(AuthorRole.User, input)); Console.WriteLine(); List footnotes = []; - await foreach (StreamingChatMessageContent chunk in agent.InvokeStreamingAsync(threadId)) + await foreach (StreamingChatMessageContent chunk in agent.InvokeStreamingAsync(thread.Id)) { // Capture annotations for footnotes footnotes.AddRange(chunk.Items.OfType()); @@ -713,8 +713,8 @@ public static class Program Console.WriteLine("Cleaning-up..."); await Task.WhenAll( [ - agent.DeleteThreadAsync(threadId), - agent.DeleteAsync(), + assistantClient.DeleteThreadAsync(thread.Id), + assistantClient.DeleteAssistantAsync(assistant.Id), storeClient.DeleteVectorStoreAsync(storeId), ..fileReferences.Select(fileReference => fileClient.DeleteFileAsync(fileReference.Key)) ]); @@ -729,8 +729,6 @@ public static class Program ::: zone pivot="programming-language-python" ```python -# Copyright (c) Microsoft. All rights reserved. - import asyncio import os From aed7121129594e63bbdbc9d3195eadb06781be12 Mon Sep 17 00:00:00 2001 From: Chris Rickman Date: Wed, 5 Mar 2025 13:05:24 -0800 Subject: [PATCH 55/70] Update assistant retrieval with template --- .../Frameworks/agent/agent-templates.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/agent-templates.md b/semantic-kernel/Frameworks/agent/agent-templates.md index 35c851d4..dd7eb9f0 100644 --- a/semantic-kernel/Frameworks/agent/agent-templates.md +++ b/semantic-kernel/Frameworks/agent/agent-templates.md @@ -100,16 +100,17 @@ Templated instructions are especially powerful when working with an [`OpenAIAssi ::: zone pivot="programming-language-csharp" ```csharp // Retrieve an existing assistant definition by identifier -OpenAIAssistantAgent agent = - await OpenAIAssistantAgent.RetrieveAsync( - this.GetClientProvider(), - "", - new Kernel(), - new KernelArguments() - { - { "topic", "Dog" }, - { "length", "3" }, - }); +AzureOpenAIClient client = OpenAIAssistantAgent.CreateAzureOpenAIClient(new AzureCliCredential(), new Uri("")); +AssistantClient assistantClient = client.GetAssistantClient(); +Assistant assistant = await client.GetAssistantAsync(); +OpenAIAssistantAgent agent = new(assistant, assistantClient, new KernelPromptTemplateFactory(), PromptTemplateConfig.SemanticKernelTemplateFormat) +{ + Arguments = new KernelArguments() + { + { "topic", "Dog" }, + { "length", "3" }, + } +} ``` ::: zone-end From fbaaf72e7d70d2ab20614b5a7e9fa95e4a712b82 Mon Sep 17 00:00:00 2001 From: Sophia Lagerkrans-Pandey <163188263+sophialagerkranspandey@users.noreply.github.com> Date: Wed, 5 Mar 2025 16:05:54 -0800 Subject: [PATCH 56/70] Update semantic-kernel/concepts/ai-services/realtime.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- semantic-kernel/concepts/ai-services/realtime.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/semantic-kernel/concepts/ai-services/realtime.md b/semantic-kernel/concepts/ai-services/realtime.md index afdd4568..80eec9ad 100644 --- a/semantic-kernel/concepts/ai-services/realtime.md +++ b/semantic-kernel/concepts/ai-services/realtime.md @@ -10,8 +10,7 @@ ms.service: semantic-kernel # Realtime Multi-modal APIs -The first realtime API integration for Semantic Kernel have been added, it is currently only available in Python and considered experimental. This is because the underlying services are still being developed and are subject to changes and we might need to make breaking changes to the API in Semantic Kernel as we learn from customers how to use this and as we add other providers of these kinds of models and APIs. - +The first realtime API integration for Semantic Kernel has been added, it is currently only available in Python and considered experimental. This is because the underlying services are still being developed and are subject to changes and we might need to make breaking changes to the API in Semantic Kernel as we learn from customers how to use this and as we add other providers of these kinds of models and APIs. ## Realtime Client abstraction To support different realtime APIs from different vendors, using different protocols, a new client abstraction has been added to the kernel. This client is used to connect to the realtime service and send and receive messages. From fa454983a30bc2e3c69dda0a0f7ee118457273c6 Mon Sep 17 00:00:00 2001 From: eavanvalkenburg Date: Thu, 6 Mar 2025 15:08:22 +0100 Subject: [PATCH 57/70] add some agent language --- semantic-kernel/concepts/ai-services/realtime.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/ai-services/realtime.md b/semantic-kernel/concepts/ai-services/realtime.md index 80eec9ad..8f0e2c25 100644 --- a/semantic-kernel/concepts/ai-services/realtime.md +++ b/semantic-kernel/concepts/ai-services/realtime.md @@ -11,10 +11,11 @@ ms.service: semantic-kernel # Realtime Multi-modal APIs The first realtime API integration for Semantic Kernel has been added, it is currently only available in Python and considered experimental. This is because the underlying services are still being developed and are subject to changes and we might need to make breaking changes to the API in Semantic Kernel as we learn from customers how to use this and as we add other providers of these kinds of models and APIs. + ## Realtime Client abstraction To support different realtime APIs from different vendors, using different protocols, a new client abstraction has been added to the kernel. This client is used to connect to the realtime service and send and receive messages. -The client is responsible for handling the connection to the service, sending messages, and receiving messages. The client is also responsible for handling any errors that occur during the connection or message sending/receiving process. +The client is responsible for handling the connection to the service, sending messages, and receiving messages. The client is also responsible for handling any errors that occur during the connection or message sending/receiving process. Considering the way these models work, they can be considered agents more then regular chat completions, therefore they also take instructions, rather then a system message, they keep their own internal state and can be invoked to do work on our behalf. ### Realtime API From eb1019997ad9411fc7751b9c520174c4f475822a Mon Sep 17 00:00:00 2001 From: Tao Chen Date: Thu, 6 Mar 2025 14:17:53 -0800 Subject: [PATCH 58/70] Improve Python plugin docs part 1 --- .../concepts/plugins/adding-native-plugins.md | 28 +++++++++++++++++-- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/semantic-kernel/concepts/plugins/adding-native-plugins.md b/semantic-kernel/concepts/plugins/adding-native-plugins.md index 68d3dcba..58b17f75 100644 --- a/semantic-kernel/concepts/plugins/adding-native-plugins.md +++ b/semantic-kernel/concepts/plugins/adding-native-plugins.md @@ -110,10 +110,10 @@ class LightsPlugin: ::: zone-end +::: zone pivot="programming-language-csharp" > [!TIP] > Because the LLMs are predominantly trained on Python code, it is recommended to use snake_case for function names and parameters (even if you're using C# or Java). This will help the AI agent better understand the function and its parameters. -::: zone pivot="programming-language-csharp" > [!TIP] > Your functions can specify `Kernel`, `KernelArguments`, `ILoggerFactory`, `ILogger`, `IAIServiceSelector`, `CultureInfo`, `IFormatProvider`, `CancellationToken` as parameters and these will not be advertised to the LLM and will be automatically set when the function is called. > If you rely on `KernelArguments` instead of explicit input arguments then your code will be responsible for performing type conversions. @@ -156,14 +156,20 @@ public enum Brightness ::: zone pivot="programming-language-python" ```python +from enum import Enum from typing import TypedDict +class Brightness(Enum): + LOW = "low" + MEDIUM = "medium" + HIGH = "high" + class LightModel(TypedDict): id: int name: str is_on: bool | None - brightness: int | None - hex: str | None + brightness: Brightness | None + color: Annotated[str | None, "The color of the light with a hex code (ensure you include the # symbol)"] ``` ::: zone-end @@ -176,8 +182,24 @@ class LightModel(TypedDict): > [!NOTE] > While this is a "fun" example, it does a good job showing just how complex a plugin's parameters can be. In this single case, we have a complex object with _four_ different types of properties: an integer, string, boolean, and enum. Semantic Kernel's value is that it can automatically generate the schema for this object and pass it to the AI agent and marshal the parameters generated by the AI agent into the correct object. +::: zone pivot="programming-language-csharp" + +Once you're done authoring your plugin class, you can add it to the kernel using the `AddFromType<>` or `AddFromObject` methods. + +::: zone-end + +::: zone pivot="programming-language-python" + +Once you're done authoring your plugin class, you can add it to the kernel using the `add_plugin` method. + +::: zone-end + +::: zone pivot="programming-language-java" + Once you're done authoring your plugin class, you can add it to the kernel using the `AddFromType<>` or `AddFromObject` methods. +::: zone-end + > [!TIP] > When creating a function, always ask yourself "how can I give the AI additional help to use this function?" This can include using specific input types (avoid strings where possible), providing descriptions, and examples. From 79e8f9c328d8f6788b48e9cbb2c0d4410f79657a Mon Sep 17 00:00:00 2001 From: Chris Rickman Date: Thu, 6 Mar 2025 15:09:15 -0800 Subject: [PATCH 59/70] Updated AzureAIAgent and consistency updates --- .../Frameworks/agent/assistant-agent.md | 36 ++ .../Frameworks/agent/azure-ai-agent.md | 319 +++++++++++++----- .../Frameworks/agent/chat-completion-agent.md | 31 ++ 3 files changed, 308 insertions(+), 78 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/assistant-agent.md b/semantic-kernel/Frameworks/agent/assistant-agent.md index 44fa6e9f..31a6b0ea 100644 --- a/semantic-kernel/Frameworks/agent/assistant-agent.md +++ b/semantic-kernel/Frameworks/agent/assistant-agent.md @@ -43,6 +43,42 @@ The _OpenAI Assistant API_ is a specialized interface designed for more advanced - [Assistant API in Azure](/azure/ai-services/openai/assistants-quickstart) +## Preparing Your Development Environment + +To proceed with developing an `OpenAIAIAssistantAgent`, configure your development environment with the appropriate packages. + +::: zone pivot="programming-language-csharp" + +Add the `Microsoft.SemanticKernel.Agents.OpenAI` package to your project: + +```pwsh +dotnet add package Microsoft.SemanticKernel.Agents.AzureAI --prerelease +``` + +You may also want to include the `Azure.Identity` package: + +```pwsh +dotnet add package Azure.Identity +``` +::: zone-end + +::: zone pivot="programming-language-python" + +Install the `semantic-kernel` package with the optional _Azure_ dependencies: + +```bash +pip install semantic-kernel[azure] +``` + +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + + ## Creating an `OpenAIAssistantAgent` Creating an `OpenAIAssistant` requires invoking a remote service, which is handled asynchronously. To manage this, the `OpenAIAssistantAgent` is instantiated through a static factory method, ensuring the process occurs in a non-blocking manner. This method abstracts the complexity of the asynchronous call, returning a promise or future once the assistant is fully initialized and ready for use. diff --git a/semantic-kernel/Frameworks/agent/azure-ai-agent.md b/semantic-kernel/Frameworks/agent/azure-ai-agent.md index 1eb27431..e15aaa6d 100644 --- a/semantic-kernel/Frameworks/agent/azure-ai-agent.md +++ b/semantic-kernel/Frameworks/agent/azure-ai-agent.md @@ -17,7 +17,7 @@ Detailed API documentation related to this discussion is available at: ::: zone pivot="programming-language-csharp" -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +- [`OpenAIAssistantAgent`](dotnet/api/microsoft.semantickernel.agents.azureai) ::: zone-end @@ -37,43 +37,40 @@ Detailed API documentation related to this discussion is available at: An `AzureAIAgent` is a specialized agent within the Semantic Kernel framework, designed to provide advanced conversational capabilities with seamless tool integration. It automates tool calling, eliminating the need for manual parsing and invocation. The agent also securely manages conversation history using threads, reducing the overhead of maintaining state. Additionally, the `AzureAIAgent` supports a variety of built-in tools, including file retrieval, code execution, and data interaction via Bing, Azure AI Search, Azure Functions, and OpenAPI. -::: zone pivot="programming-language-csharp" +To use an `AzureAIAgent`, an _Azure AI Foundry Project_ must be utilized. The following articles provide an overview of the _Azure AI Foundry_, how to create and configure a project, and the agent service: -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +- [What is Azure AI Foundry?](azure/ai-foundry/what-is-ai-foundry) +- [The Azure AI Foundry SDK](azure/ai-foundry/how-to/develop/sdk-overview) +- [What is Azure AI Agent Service](azure/ai-services/agents/overview) +- [Quickstart: Create a new agent](azure/ai-services/agents/quickstart) -::: zone-end +## Preparing Your Development Environment -::: zone pivot="programming-language-python" +To proceed with developing an `AzureAIAgent`, configure your development environment with the appropriate packages. -To set up the required resources, follow the "Quickstart: Create a new agent" guide [here](/azure/ai-services/agents/quickstart?pivots=programming-language-python-azure). +::: zone pivot="programming-language-csharp" -You will need to install the optional Semantic Kernel azure dependencies if you haven't already via: +Add the `Microsoft.SemanticKernel.Agents.AzureAI` package to your project: -```bash -pip install semantic-kernel[azure] +```pwsh +dotnet add package Microsoft.SemanticKernel.Agents.AzureAI --prerelease ``` -Before running an `AzureAIAgent`, modify your .env file to include: +You may also want to include the `Azure.Identity` package: -```bash -AZURE_AI_AGENT_PROJECT_CONNECTION_STRING = "" -AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME = "" +```pwsh +dotnet add package Azure.Identity ``` -or - -```bash -AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME = "" -AZURE_AI_AGENT_ENDPOINT = "" -AZURE_AI_AGENT_SUBSCRIPTION_ID = "" -AZURE_AI_AGENT_RESOURCE_GROUP_NAME = "" -AZURE_AI_AGENT_PROJECT_NAME = "" -``` +::: zone-end -The project connection string is of the following format: `;;;`. See here for information on obtaining the values to populate the connection string. +::: zone pivot="programming-language-python" -The `.env` should be placed in the root directory. +Install the `semantic-kernel` package with the optional _Azure_ dependencies: +```bash +pip install semantic-kernel[azure] +``` ::: zone-end ::: zone pivot="programming-language-java" @@ -82,20 +79,46 @@ The `.env` should be placed in the root directory. ::: zone-end -## Configuring the AI Project Client -Ensure that your `AzureAIAgent` resources are configured with at least a Basic or Standard SKU (the Standard SKU is required to do more advanced operations like AI Search). +## Configuring the AI Project Client -To begin, create the project client as follows: +Accessing an `AzureAIAgent` first requires the creation of a project client that is configured for a specific _Foundry Project_, most commonly by providing a connection string ([The Azure AI Foundry SDK: Getting Started with Projects](azure/ai-foundry/how-to/develop/sdk-overview#get-started-with-projects)). ::: zone pivot="programming-language-csharp" -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +```c# +AIProjectClient client = AzureAIAgent.CreateAzureAIClient("", new AzureCliCredential()); +``` + +The `AgentsClient` may be accessed from the `AIProjectClient`: + +```c# +AgentsClient agentsClient = client.GetAgentsClient(); +``` ::: zone-end ::: zone pivot="programming-language-python" +Modify your the `.env` file in the root directory to include: + +```bash +AZURE_AI_AGENT_PROJECT_CONNECTION_STRING = "" +AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME = "" +``` + +or + +```bash +AZURE_AI_AGENT_ENDPOINT = "" +AZURE_AI_AGENT_SUBSCRIPTION_ID = "" +AZURE_AI_AGENT_RESOURCE_GROUP_NAME = "" +AZURE_AI_AGENT_PROJECT_NAME = "" +AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME = "" +``` + +Once the configuration is defined, the client may be created: + ```python async with ( DefaultAzureCredential() as creds, @@ -118,8 +141,20 @@ To create an `AzureAIAgent`, you start by configuring and initializing the agent ::: zone pivot="programming-language-csharp" -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +```c# +AIProjectClient client = AzureAIAgent.CreateAzureAIClient("", new AzureCliCredential()); +AgentsClient agentsClient = client.GetAgentsClient(); + +// 1. Define an agent on the Azure AI agent service +Agent definition = agentsClient.CreateAgentAsync( + "", + name: "", + description: "", + instructions: ""); +// 2. Create a Semantic Kernel agent based on the agent definition +AzureAIAgent agent = new(definition, agentsClient); +``` ::: zone-end ::: zone pivot="programming-language-python" @@ -134,14 +169,14 @@ async with ( DefaultAzureCredential() as creds, AzureAIAgent.create_client(credential=creds) as client, ): - # 1. Create an agent on the Azure AI agent service + # 1. Define an agent on the Azure AI agent service agent_definition = await client.agents.create_agent( model=ai_agent_settings.model_deployment_name, name="", instructions="", ) - # 2. Create a Semantic Kernel agent to use the Azure AI agent + # 2. Create a Semantic Kernel agent based on the agent definition agent = AzureAIAgent( client=client, definition=agent_definition, @@ -161,13 +196,26 @@ async with ( Interaction with the `AzureAIAgent` is straightforward. The agent maintains the conversation history automatically using a thread: ::: zone pivot="programming-language-csharp" - -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. - +```c# +AgentThread thread = await agentsClient.CreateThreadAsync(); +try +{ + ChatMessageContent message = new(AuthorRole.User, ""); + await agent.AddChatMessageAsync(threadId, message); + await foreach (ChatMessageContent response in agent.InvokeAsync(thread.Id)) + { + Console.WriteLine(response.Content); + } +} +finally +{ + await this.AgentsClient.DeleteThreadAsync(thread.Id); + await this.AgentsClient.DeleteAgentAsync(agent.Id); +} +``` ::: zone-end ::: zone pivot="programming-language-python" - ```python USER_INPUTS = ["Hello", "What's your name?"] @@ -182,22 +230,36 @@ finally: await client.agents.delete_thread(thread.id) ``` -Python also supports invoking an agent in a streaming and a non-streaming fashion: +Optionally, an agent may be invoked as: ```python -# Streaming for user_input in USER_INPUTS: await agent.add_chat_message(thread_id=thread.id, message=user_input) - async for content in agent.invoke_stream(thread_id=thread.id): - print(content.content, end="", flush=True) + async for content in agent.invoke(thread_id=thread.id): + print(content.content) ``` +::: zone-end + +An agent may also produce a _streamed_ response: + +::: zone pivot="programming-language-csharp" +```c# +ChatMessageContent message = new(AuthorRole.User, ""); +await agent.AddChatMessageAsync(threadId, message); +await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(thread.Id)) +{ + Console.Write(response.Content); +} +``` +::: zone-end + +::: zone pivot="programming-language-python" ```python -# Non-streaming for user_input in USER_INPUTS: await agent.add_chat_message(thread_id=thread.id, message=user_input) - async for content in agent.invoke(thread_id=thread.id): - print(content.content) + async for content in agent.invoke_stream(thread_id=thread.id): + print(content.content, end="", flush=True) ``` ::: zone-end @@ -212,13 +274,22 @@ for user_input in USER_INPUTS: Semantic Kernel supports extending an `AzureAIAgent` with custom plugins for enhanced functionality: ::: zone pivot="programming-language-csharp" - -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. - +```c# +Plugin plugin = KernelPluginFactory.CreateFromType(); +AIProjectClient client = AzureAIAgent.CreateAzureAIClient("", new AzureCliCredential()); +AgentsClient agentsClient = client.GetAgentsClient(); + +Agent definition = agentsClient.CreateAgentAsync( + "", + name: "", + description: "", + instructions: ""); + +AzureAIAgent agent = new(definition, agentsClient, plugins: [plugin]); +``` ::: zone-end ::: zone pivot="programming-language-python" - ```python from semantic_kernel.functions import kernel_function @@ -253,14 +324,39 @@ async with ( ## Advanced Features -An `AzureAIAgent` can leverage advanced tools such as code interpreters, file search, OpenAPI and Azure AI Search integration for dynamic and powerful interactions: +An `AzureAIAgent` can leverage advanced tools such as: -### Code Interpreter +- [Code Interpreter](#code-interpreter) +- [File Search](#file-search) +- [OpenAPI integration](#openapi-integration) +- [Azure AI Search integration](#azureai-search-integration) -::: zone pivot="programming-language-csharp" +### Code Interpreter -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +Code Interpreter allows the agents to write and run Python code in a sandboxed execution environment ([Azure AI Agent Service Code Interpreter](azure/ai-services/agents/how-to/tools/code-interpreter)). +::: zone pivot="programming-language-csharp" +```c# +AIProjectClient client = AzureAIAgent.CreateAzureAIClient("", new AzureCliCredential()); +AgentsClient agentsClient = client.GetAgentsClient(); + +Agent definition = agentsClient.CreateAgentAsync( + "", + name: "", + description: "", + instructions: "", + tools: [new CodeInterpreterToolDefinition()], + toolResources: + new() + { + CodeInterpreter = new() + { + FileIds = { ... }, + } + })); + +AzureAIAgent agent = new(definition, agentsClient); +``` ::: zone-end ::: zone pivot="programming-language-python" @@ -288,10 +384,31 @@ async with ( ### File Search -::: zone pivot="programming-language-csharp" +File search augments agents with knowledge from outside its model ([Azure AI Agent Service File Search Tool](azure/ai-services/agents/how-to/tools/file-search)). -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +::: zone pivot="programming-language-csharp" +```c# +AIProjectClient client = AzureAIAgent.CreateAzureAIClient("", new AzureCliCredential()); +AgentsClient agentsClient = client.GetAgentsClient(); + +Agent definition = agentsClient.CreateAgentAsync( + "", + name: "", + description: "", + instructions: "", + tools: [new FileSearchToolDefinition()], + toolResources: + new() + { + FileSearch = new() + { + VectorStoreIds = { ... }, + } + })); + +AzureAIAgent agent = new(definition, agentsClient); +``` ::: zone-end ::: zone pivot="programming-language-python" @@ -319,14 +436,34 @@ async with ( ### OpenAPI Integration -::: zone pivot="programming-language-csharp" - -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +Connects your agent to an external API ([How to use Azure AI Agent Service with OpenAPI Specified Tools](azure/ai-services/agents/how-to/tools/openapi-spec)). +::: zone pivot="programming-language-csharp" +```c# +AIProjectClient client = AzureAIAgent.CreateAzureAIClient("", new AzureCliCredential()); +AgentsClient agentsClient = client.GetAgentsClient(); + +string apiJsonSpecification = ...; // An Open API JSON specification + +Agent definition = agentsClient.CreateAgentAsync( + "", + name: "", + description: "", + instructions: "", + tools: [ + new OpenApiToolDefinition( + "", + "", + BinaryData.FromString(apiJsonSpecification), + new OpenApiAnonymousAuthDetails()) + ], +); + +AzureAIAgent agent = new(definition, agentsClient); +``` ::: zone-end ::: zone pivot="programming-language-python" - ```python from azure.ai.projects.models import OpenApiTool, OpenApiAnonymousAuthDetails @@ -368,16 +505,38 @@ async with ( ::: zone-end -### AzureAI Search - -::: zone pivot="programming-language-csharp" +### AzureAI Search Integration -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +Use an existing Azure AI Search index with with your agent ([Use an existing AI Search index](azure/ai-services/agents/how-to/tools/azure-ai-search)). +::: zone pivot="programming-language-csharp" +```c# +AIProjectClient client = AzureAIAgent.CreateAzureAIClient("", new AzureCliCredential()); +AgentsClient agentsClient = client.GetAgentsClient(); + +ConnectionsClient cxnClient = client.GetConnectionsClient(); +ListConnectionsResponse searchConnections = await cxnClient.GetConnectionsAsync(AzureAIP.ConnectionType.AzureAISearch); +ConnectionResponse searchConnection = searchConnections.Value[0]; + +Agent definition = agentsClient.CreateAgentAsync( + "", + name: "", + description: "", + instructions: "", + tools: [new AzureAIP.AzureAISearchToolDefinition()], + toolResources: new() + { + AzureAISearch = new() + { + IndexList = { new AzureAIP.IndexResource(searchConnection.Id, "") } + } + }); + +AzureAIAgent agent = new(definition, agentsClient); +``` ::: zone-end ::: zone pivot="programming-language-python" - ```python from azure.ai.projects.models import AzureAISearchTool, ConnectionType @@ -420,7 +579,10 @@ An existing agent can be retrieved and reused by specifying its assistant ID: ::: zone pivot="programming-language-csharp" -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +```c# +Agent definition = agentsClient.GetAgentAsync(""); +AzureAIAgent agent = new(definition, agentsClient); +``` ::: zone-end @@ -443,8 +605,10 @@ Agents and their associated threads can be deleted when no longer needed: ::: zone pivot="programming-language-csharp" -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. - +```c# +await agentsClient.DeleteThreadAsync(thread.Id); +await agentsClient.DeleteAgentAsync(agent.Id); +``` ::: zone-end ::: zone pivot="programming-language-python" @@ -453,24 +617,20 @@ await client.agents.delete_thread(thread.id) await client.agents.delete_agent(agent.id) ``` -If working with a vector store or files, they can be deleted as well: +If working with a vector store or files, they may be deleted as well: + +::: zone pivot="programming-language-csharp" +```c# +await agentsClient.DeleteVectorStoreAsync(""); +await agentsClient.DeleteFileAsync(""); +``` +::: zone-end +::: zone pivot="programming-language-python" ```python await client.agents.delete_file(file_id=file.id) await client.agents.delete_vector_store(vector_store_id=vector_store.id) ``` - -> [!TIP] -> To remove a file from a vector store, use: -> ```python -> await client.agents.delete_vector_store_file(vector_store_id=vector_store.id, file_id=file.id) -> ``` -> This operation detaches the file from the vector store but does not permanently delete it. -> To fully delete the file, call: -> ```python -> await client.agents.delete_file(file_id=file.id) -> ``` - ::: zone-end ::: zone pivot="programming-language-java" @@ -479,13 +639,16 @@ await client.agents.delete_vector_store(vector_store_id=vector_store.id) ::: zone-end +> More information on the _file search_ tool is described in the [Azure AI Agent Service file search tool](azure/ai-services/agents/how-to/tools/file-search) article. + ## How-To For practical examples of using an `AzureAIAgent`, see our code samples on GitHub: ::: zone pivot="programming-language-csharp" -> TODO(crickman) Azure AI Agents are currently unavailable in .NET. +- [Getting Started with Azure AI Agents](https://github.com/microsoft/semantic-kernel/tree/main/dotnet/samples/GettingStartedWithAgents/AzureAIAgent) +- [Advanced Azure AI Agent Code Samples](https://github.com/microsoft/semantic-kernel/tree/main/dotnet/samples/Concepts/Agents) ::: zone-end diff --git a/semantic-kernel/Frameworks/agent/chat-completion-agent.md b/semantic-kernel/Frameworks/agent/chat-completion-agent.md index 1ed293ef..fe38eb9a 100644 --- a/semantic-kernel/Frameworks/agent/chat-completion-agent.md +++ b/semantic-kernel/Frameworks/agent/chat-completion-agent.md @@ -74,6 +74,37 @@ Onnx|[`Microsoft.SemanticKernel.Connectors.Onnx`](/dotnet/api/microsoft.semantic ::: zone-end +## Preparing Your Development Environment + +To proceed with developing an `AzureAIAgent`, configure your development environment with the appropriate packages. + +::: zone pivot="programming-language-csharp" + +Add the `Microsoft.SemanticKernel.Agents.Core` package to your project: + +```pwsh +dotnet add package Microsoft.SemanticKernel.Agents.Core --prerelease +``` + +::: zone-end + +::: zone pivot="programming-language-python" + +Install the `semantic-kernel` package: + +```bash +pip install semantic-kernel +``` + +::: zone-end + +::: zone pivot="programming-language-java" + +> Agents are currently unavailable in Java. + +::: zone-end + + ## Creating a `ChatCompletionAgent` A _chat completion agent_ is fundamentally based on an [AI services](../../concepts/ai-services/index.md). As such, creating an _chat completion agent_ starts with creating a [`Kernel`](../../concepts/kernel.md) instance that contains one or more chat-completion services and then instantiating the agent with a reference to that [`Kernel`](../../concepts/kernel.md) instance. From 588d7a52eb0e0ea3f4dfd3e407b44df02a10b566 Mon Sep 17 00:00:00 2001 From: Tao Chen Date: Thu, 6 Mar 2025 15:32:23 -0800 Subject: [PATCH 60/70] Improve Python plugin docs part 2 --- .../concepts/plugins/adding-native-plugins.md | 55 ++++++++++++++++++- 1 file changed, 54 insertions(+), 1 deletion(-) diff --git a/semantic-kernel/concepts/plugins/adding-native-plugins.md b/semantic-kernel/concepts/plugins/adding-native-plugins.md index 58b17f75..790af385 100644 --- a/semantic-kernel/concepts/plugins/adding-native-plugins.md +++ b/semantic-kernel/concepts/plugins/adding-native-plugins.md @@ -18,6 +18,7 @@ Behind the scenes, Semantic Kernel will then use the descriptions you provide, a ## Providing the LLM with the right information When authoring a plugin, you need to provide the AI agent with the right information to understand the capabilities of the plugin and its functions. This includes: + - The name of the plugin - The names of the functions - The descriptions of the functions @@ -34,6 +35,7 @@ Below, we'll walk through the two different ways of providing your AI agent with The easiest way to create a native plugin is to start with a class and then add methods annotated with the `KernelFunction` attribute. It is also recommended to liberally use the `Description` annotation to provide the AI agent with the necessary information to understand the function. ::: zone pivot="programming-language-csharp" + ```csharp public class LightsPlugin { @@ -73,9 +75,11 @@ public class LightsPlugin } } ``` + ::: zone-end ::: zone pivot="programming-language-python" + ```python from typing import List, Optional, Annotated @@ -102,6 +106,7 @@ class LightsPlugin: return light return None ``` + ::: zone-end ::: zone pivot="programming-language-java" @@ -122,6 +127,7 @@ class LightsPlugin: If your function has a complex object as an input variable, Semantic Kernel will also generate a schema for that object and pass it to the AI agent. Similar to functions, you should provide `Description` annotations for properties that are non-obvious to the AI. Below is the definition for the `LightState` class and the `Brightness` enum. ::: zone pivot="programming-language-csharp" + ```csharp using System.Text.Json.Serialization; @@ -152,9 +158,11 @@ public enum Brightness High } ``` + ::: zone-end ::: zone pivot="programming-language-python" + ```python from enum import Enum from typing import TypedDict @@ -171,6 +179,7 @@ class LightModel(TypedDict): brightness: Brightness | None color: Annotated[str | None, "The color of the light with a hex code (ensure you include the # symbol)"] ``` + ::: zone-end ::: zone pivot="programming-language-java" @@ -204,6 +213,7 @@ Once you're done authoring your plugin class, you can add it to the kernel using > When creating a function, always ask yourself "how can I give the AI additional help to use this function?" This can include using specific input types (avoid strings where possible), providing descriptions, and examples. ::: zone pivot="programming-language-csharp" + #### Adding a plugin using the `AddFromObject` method The `AddFromObject` method allows you to add an instance of the plugin class directly to the plugin collection in case you want to directly control how the plugin is constructed. @@ -347,9 +357,11 @@ builder.Services.AddTransient((serviceProvider)=> { return new Kernel(serviceProvider, pluginCollection); }); ``` + ::: zone-end ::: zone pivot="programming-language-python" + #### Adding a plugin using the `add_plugin` method The `add_plugin` method allows you to add a plugin instance to the kernel. Below is an example of how you can construct the `LightsPlugin` class and add it to the kernel. @@ -371,8 +383,8 @@ lights_plugin = LightsPlugin(lights) # Add the plugin to the kernel kernel.add_plugin(lights_plugin) ``` -::: zone-end +::: zone-end ::: zone pivot="programming-language-java" @@ -519,7 +531,48 @@ This approach eliminates the need to manually provide and update the return type ::: zone-end +::: zone pivot="programming-language-python" + +### Providing more details about the functions + +When creating a plugin in Python, you can provide additional information about the functions in the `kernel_function` decorator. This information will be used by the AI agent to understand the functions better. + +```python + +from typing import List, Optional, Annotated + +class LightsPlugin: + def __init__(self, lights: List[LightModel]): + self._lights = lights + + @kernel_function(name="GetLights", description="Gets a list of lights and their current state") + async def get_lights(self) -> List[LightModel]: + """Gets a list of lights and their current state.""" + return self._lights + + @kernel_function(name="ChangeState", description="Changes the state of the light") + async def change_state( + self, + change_state: LightModel + ) -> Optional[LightModel]: + """Changes the state of the light.""" + for light in self._lights: + if light["id"] == change_state["id"]: + light["is_on"] = change_state.get("is_on", light["is_on"]) + light["brightness"] = change_state.get("brightness", light["brightness"]) + light["hex"] = change_state.get("hex", light["hex"]) + return light + return None +``` + +The sample above shows how to override the function name and provide a description for the function. By default, the function name is the name of the function and the description is empty. If the function name is descriptive enough, you won't need a description, which will save you tokens. However, if the function behavior is not obvious from the name, you should provide a description for the AI. + +Because the LLMs are predominantly trained on Python code, it is recommended to use function names that follow the [Python naming conventions](https://peps.python.org/pep-0008/#function-and-variable-names), which means you rarely need to override the function names if you follow the conventions in your Python code. + +::: zone-end + ## Next steps + Now that you know how to create a plugin, you can now learn how to use them with your AI agent. Depending on the type of functions you've added to your plugins, there are different patterns you should follow. For retrieval functions, refer to the [using retrieval functions](./using-data-retrieval-functions-for-rag.md) article. For task automation functions, refer to the [using task automation functions](./using-task-automation-functions.md) article. > [!div class="nextstepaction"] From 6dd37770fd269067c818778d99bd0bcb8c7636b3 Mon Sep 17 00:00:00 2001 From: Tao Chen Date: Thu, 6 Mar 2025 15:36:51 -0800 Subject: [PATCH 61/70] remove empty line --- semantic-kernel/concepts/plugins/adding-native-plugins.md | 1 - 1 file changed, 1 deletion(-) diff --git a/semantic-kernel/concepts/plugins/adding-native-plugins.md b/semantic-kernel/concepts/plugins/adding-native-plugins.md index 790af385..f2f8be4e 100644 --- a/semantic-kernel/concepts/plugins/adding-native-plugins.md +++ b/semantic-kernel/concepts/plugins/adding-native-plugins.md @@ -538,7 +538,6 @@ This approach eliminates the need to manually provide and update the return type When creating a plugin in Python, you can provide additional information about the functions in the `kernel_function` decorator. This information will be used by the AI agent to understand the functions better. ```python - from typing import List, Optional, Annotated class LightsPlugin: From c0014716eee426305cd238fafda6f46209884763 Mon Sep 17 00:00:00 2001 From: Chris Rickman Date: Thu, 6 Mar 2025 15:39:08 -0800 Subject: [PATCH 62/70] Fix errors --- .../Frameworks/agent/azure-ai-agent.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/azure-ai-agent.md b/semantic-kernel/Frameworks/agent/azure-ai-agent.md index e15aaa6d..3be48add 100644 --- a/semantic-kernel/Frameworks/agent/azure-ai-agent.md +++ b/semantic-kernel/Frameworks/agent/azure-ai-agent.md @@ -39,10 +39,11 @@ An `AzureAIAgent` is a specialized agent within the Semantic Kernel framework, d To use an `AzureAIAgent`, an _Azure AI Foundry Project_ must be utilized. The following articles provide an overview of the _Azure AI Foundry_, how to create and configure a project, and the agent service: -- [What is Azure AI Foundry?](azure/ai-foundry/what-is-ai-foundry) -- [The Azure AI Foundry SDK](azure/ai-foundry/how-to/develop/sdk-overview) -- [What is Azure AI Agent Service](azure/ai-services/agents/overview) -- [Quickstart: Create a new agent](azure/ai-services/agents/quickstart) +- [What is Azure AI Foundry?](/azure/ai-foundry/what-is-ai-foundry) +- [The Azure AI Foundry SDK](/azure/ai-foundry/how-to/develop/sdk-overview) +- [What is Azure AI Agent Service](/azure/ai-services/agents/overview) +- [Quickstart: Create a new agent](/azure/ai-services/agents/quickstart) + ## Preparing Your Development Environment @@ -82,7 +83,7 @@ pip install semantic-kernel[azure] ## Configuring the AI Project Client -Accessing an `AzureAIAgent` first requires the creation of a project client that is configured for a specific _Foundry Project_, most commonly by providing a connection string ([The Azure AI Foundry SDK: Getting Started with Projects](azure/ai-foundry/how-to/develop/sdk-overview#get-started-with-projects)). +Accessing an `AzureAIAgent` first requires the creation of a project client that is configured for a specific _Foundry Project_, most commonly by providing a connection string ([The Azure AI Foundry SDK: Getting Started with Projects](/azure/ai-foundry/how-to/develop/sdk-overview#get-started-with-projects)). ::: zone pivot="programming-language-csharp" @@ -333,7 +334,7 @@ An `AzureAIAgent` can leverage advanced tools such as: ### Code Interpreter -Code Interpreter allows the agents to write and run Python code in a sandboxed execution environment ([Azure AI Agent Service Code Interpreter](azure/ai-services/agents/how-to/tools/code-interpreter)). +Code Interpreter allows the agents to write and run Python code in a sandboxed execution environment ([Azure AI Agent Service Code Interpreter](/azure/ai-services/agents/how-to/tools/code-interpreter)). ::: zone pivot="programming-language-csharp" ```c# @@ -384,7 +385,7 @@ async with ( ### File Search -File search augments agents with knowledge from outside its model ([Azure AI Agent Service File Search Tool](azure/ai-services/agents/how-to/tools/file-search)). +File search augments agents with knowledge from outside its model ([Azure AI Agent Service File Search Tool](/azure/ai-services/agents/how-to/tools/file-search)). ::: zone pivot="programming-language-csharp" @@ -436,7 +437,7 @@ async with ( ### OpenAPI Integration -Connects your agent to an external API ([How to use Azure AI Agent Service with OpenAPI Specified Tools](azure/ai-services/agents/how-to/tools/openapi-spec)). +Connects your agent to an external API ([How to use Azure AI Agent Service with OpenAPI Specified Tools](/azure/ai-services/agents/how-to/tools/openapi-spec)). ::: zone pivot="programming-language-csharp" ```c# @@ -507,7 +508,7 @@ async with ( ### AzureAI Search Integration -Use an existing Azure AI Search index with with your agent ([Use an existing AI Search index](azure/ai-services/agents/how-to/tools/azure-ai-search)). +Use an existing Azure AI Search index with with your agent ([Use an existing AI Search index](/azure/ai-services/agents/how-to/tools/azure-ai-search)). ::: zone pivot="programming-language-csharp" ```c# @@ -616,6 +617,7 @@ await agentsClient.DeleteAgentAsync(agent.Id); await client.agents.delete_thread(thread.id) await client.agents.delete_agent(agent.id) ``` +::: zone-end If working with a vector store or files, they may be deleted as well: @@ -639,7 +641,7 @@ await client.agents.delete_vector_store(vector_store_id=vector_store.id) ::: zone-end -> More information on the _file search_ tool is described in the [Azure AI Agent Service file search tool](azure/ai-services/agents/how-to/tools/file-search) article. +> More information on the _file search_ tool is described in the [Azure AI Agent Service file search tool](/azure/ai-services/agents/how-to/tools/file-search) article. ## How-To From 129c980ce681d516709c62187d491ad0f6bd2fe6 Mon Sep 17 00:00:00 2001 From: Sophia Lagerkrans-Pandey <163188263+sophialagerkranspandey@users.noreply.github.com> Date: Thu, 6 Mar 2025 15:47:50 -0800 Subject: [PATCH 63/70] Update semantic-kernel/concepts/ai-services/realtime.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- semantic-kernel/concepts/ai-services/realtime.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/semantic-kernel/concepts/ai-services/realtime.md b/semantic-kernel/concepts/ai-services/realtime.md index 8f0e2c25..dd559e91 100644 --- a/semantic-kernel/concepts/ai-services/realtime.md +++ b/semantic-kernel/concepts/ai-services/realtime.md @@ -15,8 +15,7 @@ The first realtime API integration for Semantic Kernel has been added, it is cur ## Realtime Client abstraction To support different realtime APIs from different vendors, using different protocols, a new client abstraction has been added to the kernel. This client is used to connect to the realtime service and send and receive messages. -The client is responsible for handling the connection to the service, sending messages, and receiving messages. The client is also responsible for handling any errors that occur during the connection or message sending/receiving process. Considering the way these models work, they can be considered agents more then regular chat completions, therefore they also take instructions, rather then a system message, they keep their own internal state and can be invoked to do work on our behalf. - +The client is responsible for handling the connection to the service, sending messages, and receiving messages. The client is also responsible for handling any errors that occur during the connection or message sending/receiving process. Considering the way these models work, they can be considered agents more than regular chat completions, therefore they also take instructions, rather than a system message, they keep their own internal state and can be invoked to do work on our behalf. ### Realtime API Any realtime client implements the following methods: From b3b3786f70dce2c10fb11bf788af8000fcb36147 Mon Sep 17 00:00:00 2001 From: Chris Rickman Date: Thu, 6 Mar 2025 16:19:08 -0800 Subject: [PATCH 64/70] Fix link --- semantic-kernel/Frameworks/agent/azure-ai-agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/Frameworks/agent/azure-ai-agent.md b/semantic-kernel/Frameworks/agent/azure-ai-agent.md index 3be48add..851c2749 100644 --- a/semantic-kernel/Frameworks/agent/azure-ai-agent.md +++ b/semantic-kernel/Frameworks/agent/azure-ai-agent.md @@ -17,7 +17,7 @@ Detailed API documentation related to this discussion is available at: ::: zone pivot="programming-language-csharp" -- [`OpenAIAssistantAgent`](dotnet/api/microsoft.semantickernel.agents.azureai) +- [`OpenAIAssistantAgent`](/dotnet/api/microsoft.semantickernel.agents.azureai) ::: zone-end From fc595236f8f28c5059f9bb98b64a3ea49a0ed705 Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Fri, 7 Mar 2025 15:49:00 +0900 Subject: [PATCH 65/70] Cleanup --- .../Frameworks/agent/agent-templates.md | 29 +++++++++++-------- .../Frameworks/agent/assistant-agent.md | 2 +- .../Frameworks/agent/azure-ai-agent.md | 12 ++++---- 3 files changed, 24 insertions(+), 19 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/agent-templates.md b/semantic-kernel/Frameworks/agent/agent-templates.md index 2c9ce918..910d2454 100644 --- a/semantic-kernel/Frameworks/agent/agent-templates.md +++ b/semantic-kernel/Frameworks/agent/agent-templates.md @@ -76,10 +76,8 @@ ChatCompletionAgent agent = ::: zone pivot="programming-language-python" ```python -kernel = Kernel() - agent = ChatCompletionAgent( - kernel=kernel, + service=AzureChatCompletion(), # or other supported AI Services name="StoryTeller", instructions="Tell a story about {{$topic}} that is {{$length}} sentences long.", arguments=KernelArguments(topic="Dog", length="2"), @@ -116,9 +114,18 @@ OpenAIAssistantAgent agent = new(assistant, assistantClient, new KernelPromptTem ::: zone pivot="programming-language-python" ```python -agent = await OpenAIAssistantAgent.retrieve( - id=, - kernel=Kernel(), +# Create the client using Azure OpenAI resources and configuration +client, model = AzureAssistantAgent.setup_resources() + +# Retrieve the assistant definition from the server based on the assistant ID +definition = await client.beta.assistants.retrieve( + assistant_id="your-assistant-id", +) + +# Create the AzureAssistantAgent instance using the client and the assistant definition +agent = AzureAssistantAgent( + client=client, + definition=definition, arguments=KernelArguments(topic="Dog", length="3"), ) ``` @@ -131,9 +138,9 @@ agent = await OpenAIAssistantAgent.retrieve( ::: zone-end -## Agent Definition from a _Prompt Template_ +## Agent Definition from a Prompt Template -The same _Prompt Template Config_ used to create a _Kernel Prompt Function_ can also be leveraged to define an agent. This allows for a unified approach in managing both prompts and agents, promoting consistency and reuse across different components. By externalizing agent definitions from the codebase, this method simplifies the management of multiple agents, making them easier to update and maintain without requiring changes to the underlying logic. This separation also enhances flexibility, enabling developers to modify agent behavior or introduce new agents by simply updating the configuration, rather than adjusting the code itself. +The same Prompt Template Config_used to create a Kernel Prompt Function can also be leveraged to define an agent. This allows for a unified approach in managing both prompts and agents, promoting consistency and reuse across different components. By externalizing agent definitions from the codebase, this method simplifies the management of multiple agents, making them easier to update and maintain without requiring changes to the underlying logic. This separation also enhances flexibility, enabling developers to modify agent behavior or introduce new agents by simply updating the configuration, rather than adjusting the code itself. #### YAML Template @@ -193,7 +200,7 @@ data = yaml.safe_load(generate_story_yaml) prompt_template_config = PromptTemplateConfig(**data) agent = ChatCompletionAgent( - kernel=_create_kernel_with_chat_completion(), + service=AzureChatCompletion(), # or other supported AI services prompt_template_config=prompt_template_config, arguments=KernelArguments(topic="Dog", length="3"), ) @@ -250,10 +257,8 @@ await foreach (ChatMessageContent response in agent.InvokeAsync(chat, overrideAr ::: zone pivot="programming-language-python" ```python -kernel = Kernel() - agent = ChatCompletionAgent( - kernel=kernel, + service=AzureChatCompletion(), name="StoryTeller", instructions="Tell a story about {{$topic}} that is {{$length}} sentences long.", arguments=KernelArguments(topic="Dog", length="2"), diff --git a/semantic-kernel/Frameworks/agent/assistant-agent.md b/semantic-kernel/Frameworks/agent/assistant-agent.md index 31a6b0ea..b5dd3fbf 100644 --- a/semantic-kernel/Frameworks/agent/assistant-agent.md +++ b/semantic-kernel/Frameworks/agent/assistant-agent.md @@ -248,7 +248,7 @@ await agent.delete_thread(thread_id) ::: zone-end -## Deleting an `OpenAIAssistantAgent` +## Delete an `OpenAIAssistantAgent` Since the assistant's definition is stored remotely, it will persist if not deleted. Deleting an assistant definition may be performed directly with the `AssistantClient`. diff --git a/semantic-kernel/Frameworks/agent/azure-ai-agent.md b/semantic-kernel/Frameworks/agent/azure-ai-agent.md index 851c2749..842a5f16 100644 --- a/semantic-kernel/Frameworks/agent/azure-ai-agent.md +++ b/semantic-kernel/Frameworks/agent/azure-ai-agent.md @@ -37,7 +37,7 @@ Detailed API documentation related to this discussion is available at: An `AzureAIAgent` is a specialized agent within the Semantic Kernel framework, designed to provide advanced conversational capabilities with seamless tool integration. It automates tool calling, eliminating the need for manual parsing and invocation. The agent also securely manages conversation history using threads, reducing the overhead of maintaining state. Additionally, the `AzureAIAgent` supports a variety of built-in tools, including file retrieval, code execution, and data interaction via Bing, Azure AI Search, Azure Functions, and OpenAPI. -To use an `AzureAIAgent`, an _Azure AI Foundry Project_ must be utilized. The following articles provide an overview of the _Azure AI Foundry_, how to create and configure a project, and the agent service: +To use an `AzureAIAgent`, an Azure AI Foundry Project must be utilized. The following articles provide an overview of the Azure AI Foundry, how to create and configure a project, and the agent service: - [What is Azure AI Foundry?](/azure/ai-foundry/what-is-ai-foundry) - [The Azure AI Foundry SDK](/azure/ai-foundry/how-to/develop/sdk-overview) @@ -67,7 +67,7 @@ dotnet add package Azure.Identity ::: zone pivot="programming-language-python" -Install the `semantic-kernel` package with the optional _Azure_ dependencies: +Install the `semantic-kernel` package with the optional Azure dependencies: ```bash pip install semantic-kernel[azure] @@ -83,7 +83,7 @@ pip install semantic-kernel[azure] ## Configuring the AI Project Client -Accessing an `AzureAIAgent` first requires the creation of a project client that is configured for a specific _Foundry Project_, most commonly by providing a connection string ([The Azure AI Foundry SDK: Getting Started with Projects](/azure/ai-foundry/how-to/develop/sdk-overview#get-started-with-projects)). +Accessing an `AzureAIAgent` first requires the creation of a project client that is configured for a specific Foundry Project, most commonly by providing a connection string ([The Azure AI Foundry SDK: Getting Started with Projects](/azure/ai-foundry/how-to/develop/sdk-overview#get-started-with-projects)). ::: zone pivot="programming-language-csharp" @@ -242,7 +242,7 @@ for user_input in USER_INPUTS: ::: zone-end -An agent may also produce a _streamed_ response: +An agent may also produce a streamed response: ::: zone pivot="programming-language-csharp" ```c# @@ -574,7 +574,7 @@ async with ( ::: zone-end -### Retrieving Existing `AzureAIAgent` +### Retrieving an Existing `AzureAIAgent` An existing agent can be retrieved and reused by specifying its assistant ID: @@ -668,4 +668,4 @@ For practical examples of using an `AzureAIAgent`, see our code samples on GitHu ::: zone-end > [!div class="nextstepaction"] -> [Agent Collaboration in `AgentChat`](./agent-chat.md) \ No newline at end of file +> [Agent Collaboration in AgentChat](./agent-chat.md) \ No newline at end of file From 3ec294c4b0fcd70cd838eb28cb7a9009fc462168 Mon Sep 17 00:00:00 2001 From: Evan Mattson Date: Fri, 7 Mar 2025 17:40:18 +0900 Subject: [PATCH 66/70] update next step actions --- semantic-kernel/Frameworks/agent/assistant-agent.md | 4 ++-- semantic-kernel/Frameworks/agent/azure-ai-agent.md | 2 +- semantic-kernel/Frameworks/agent/chat-completion-agent.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/assistant-agent.md b/semantic-kernel/Frameworks/agent/assistant-agent.md index b5dd3fbf..aa888610 100644 --- a/semantic-kernel/Frameworks/agent/assistant-agent.md +++ b/semantic-kernel/Frameworks/agent/assistant-agent.md @@ -248,7 +248,7 @@ await agent.delete_thread(thread_id) ::: zone-end -## Delete an `OpenAIAssistantAgent` +## Deleting an `OpenAIAssistantAgent` Since the assistant's definition is stored remotely, it will persist if not deleted. Deleting an assistant definition may be performed directly with the `AssistantClient`. @@ -289,5 +289,5 @@ For an end-to-end example for a `OpenAIAssistantAgent`, see: > [!div class="nextstepaction"] -> [Agent Collaboration in `AgentChat`](./agent-chat.md) +> [Exploring the Azure AI Agent](./azure-ai-agent.md) diff --git a/semantic-kernel/Frameworks/agent/azure-ai-agent.md b/semantic-kernel/Frameworks/agent/azure-ai-agent.md index 842a5f16..8e9ebf3f 100644 --- a/semantic-kernel/Frameworks/agent/azure-ai-agent.md +++ b/semantic-kernel/Frameworks/agent/azure-ai-agent.md @@ -668,4 +668,4 @@ For practical examples of using an `AzureAIAgent`, see our code samples on GitHu ::: zone-end > [!div class="nextstepaction"] -> [Agent Collaboration in AgentChat](./agent-chat.md) \ No newline at end of file +> [Agent Collaboration in Agent Chat](./agent-chat.md) \ No newline at end of file diff --git a/semantic-kernel/Frameworks/agent/chat-completion-agent.md b/semantic-kernel/Frameworks/agent/chat-completion-agent.md index fe38eb9a..827f0b35 100644 --- a/semantic-kernel/Frameworks/agent/chat-completion-agent.md +++ b/semantic-kernel/Frameworks/agent/chat-completion-agent.md @@ -312,4 +312,4 @@ For an end-to-end example for a `ChatCompletionAgent`, see: > [!div class="nextstepaction"] -> [Exploring `OpenAIAssistantAgent`](./assistant-agent.md) +> [Exploring the OpenAI Assistant Agent`](./assistant-agent.md) From 9fd01ca21f260e216ccc74b02ac0ead9899d0c4f Mon Sep 17 00:00:00 2001 From: Chris <66376200+crickman@users.noreply.github.com> Date: Fri, 7 Mar 2025 14:06:11 -0800 Subject: [PATCH 67/70] Update semantic-kernel/Frameworks/agent/agent-templates.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- semantic-kernel/Frameworks/agent/agent-templates.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/agent-templates.md b/semantic-kernel/Frameworks/agent/agent-templates.md index 910d2454..b8d0a4ca 100644 --- a/semantic-kernel/Frameworks/agent/agent-templates.md +++ b/semantic-kernel/Frameworks/agent/agent-templates.md @@ -140,8 +140,7 @@ agent = AzureAssistantAgent( ## Agent Definition from a Prompt Template -The same Prompt Template Config_used to create a Kernel Prompt Function can also be leveraged to define an agent. This allows for a unified approach in managing both prompts and agents, promoting consistency and reuse across different components. By externalizing agent definitions from the codebase, this method simplifies the management of multiple agents, making them easier to update and maintain without requiring changes to the underlying logic. This separation also enhances flexibility, enabling developers to modify agent behavior or introduce new agents by simply updating the configuration, rather than adjusting the code itself. - +The same Prompt Template Config used to create a Kernel Prompt Function can also be leveraged to define an agent. This allows for a unified approach in managing both prompts and agents, promoting consistency and reuse across different components. By externalizing agent definitions from the codebase, this method simplifies the management of multiple agents, making them easier to update and maintain without requiring changes to the underlying logic. This separation also enhances flexibility, enabling developers to modify agent behavior or introduce new agents by simply updating the configuration, rather than adjusting the code itself. #### YAML Template ```yaml From 34768c3af3acd2b755923e78d6478ee91a901133 Mon Sep 17 00:00:00 2001 From: Chris <66376200+crickman@users.noreply.github.com> Date: Fri, 7 Mar 2025 14:06:18 -0800 Subject: [PATCH 68/70] Update semantic-kernel/Frameworks/agent/chat-completion-agent.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- semantic-kernel/Frameworks/agent/chat-completion-agent.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/chat-completion-agent.md b/semantic-kernel/Frameworks/agent/chat-completion-agent.md index 827f0b35..378c9550 100644 --- a/semantic-kernel/Frameworks/agent/chat-completion-agent.md +++ b/semantic-kernel/Frameworks/agent/chat-completion-agent.md @@ -255,8 +255,7 @@ agent = ChatCompletionAgent(...) chat = ChatHistory() # Add the user message -chat.add_user_message(user_input)) - +chat.add_user_message(user_input) # Generate the agent response response = await agent.get_response(chat) # response is a `ChatMessageContent` object From 6cd0488e232306767a941b6dca2ac54c6cc64458 Mon Sep 17 00:00:00 2001 From: Chris Rickman Date: Fri, 7 Mar 2025 14:08:39 -0800 Subject: [PATCH 69/70] Update example namespaces --- .../agent/examples/example-assistant-code.md | 2 -- .../agent/examples/example-assistant-search.md | 10 ++++------ 2 files changed, 4 insertions(+), 8 deletions(-) diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md index aadcba51..0ce0dfcc 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-code.md @@ -608,11 +608,9 @@ using Azure.Identity; using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.Agents.OpenAI; using Microsoft.SemanticKernel.ChatCompletion; -using OpenAI; using OpenAI.Assistants; using OpenAI.Files; using System; -using System.ClientModel; using System.Collections.Generic; using System.Diagnostics; using System.IO; diff --git a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md index ca565932..81bcc550 100644 --- a/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md +++ b/semantic-kernel/Frameworks/agent/examples/example-assistant-search.md @@ -580,21 +580,19 @@ Try using these suggested inputs: ::: zone pivot="programming-language-csharp" ```csharp -using System; -using System.ClientModel; -using System.Collections.Generic; -using System.Linq; -using System.Threading.Tasks; using Azure.AI.OpenAI; using Azure.Identity; using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.Agents; using Microsoft.SemanticKernel.Agents.OpenAI; using Microsoft.SemanticKernel.ChatCompletion; -using OpenAI; using OpenAI.Assistants; using OpenAI.Files; using OpenAI.VectorStores; +using System; +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; namespace AgentsSample; From 21a0f24ade2d3deaa657513924b791322b11ce62 Mon Sep 17 00:00:00 2001 From: Chris <66376200+crickman@users.noreply.github.com> Date: Fri, 7 Mar 2025 14:20:07 -0800 Subject: [PATCH 70/70] Update semantic-kernel/Frameworks/agent/chat-completion-agent.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- semantic-kernel/Frameworks/agent/chat-completion-agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/semantic-kernel/Frameworks/agent/chat-completion-agent.md b/semantic-kernel/Frameworks/agent/chat-completion-agent.md index 378c9550..c8d3b6d7 100644 --- a/semantic-kernel/Frameworks/agent/chat-completion-agent.md +++ b/semantic-kernel/Frameworks/agent/chat-completion-agent.md @@ -311,4 +311,4 @@ For an end-to-end example for a `ChatCompletionAgent`, see: > [!div class="nextstepaction"] -> [Exploring the OpenAI Assistant Agent`](./assistant-agent.md) +> [Exploring the OpenAI Assistant Agent](./assistant-agent.md)