使用说明：创建你的第一个流程

警告

语义内核进程框架是实验性的，仍在开发中，可能会更改。

概述

语义内核进程框架是一种功能强大的业务流程 SDK，旨在简化 AI 集成进程的开发和执行。 无论你是管理简单的工作流还是复杂的系统，此框架都允许你定义一系列可以采用结构化方式执行的步骤，从而轻松灵活地增强应用程序的功能。

Process Framework 是为了扩展性而设计的，支持各种操作模式，例如顺序执行、并行处理、扇入扇出配置，甚至包括映射-化简策略。 这种适应性使它适用于各种实际应用程序，尤其是那些需要智能决策和多步骤工作流的应用程序。

入门指南

语义内核进程框架可用于将 AI 注入到可以考虑的任何业务流程中。 作为入门的演示示例，我们来看看如何构建一个过程来生成新产品的文档。

在开始之前，请确保已安装所需的语义内核包：

// Install the Semantic Kernel Process Framework Local Runtime package
dotnet add package Microsoft.SemanticKernel.Process.LocalRuntime --version 1.46.0-alpha
// or
// Install the Semantic Kernel Process Framework Dapr Runtime package
dotnet add package Microsoft.SemanticKernel.Process.Runtime.Dapr --version 1.46.0-alpha

pip install semantic-kernel==1.20.0

说明示例：为新产品生成文档

在此示例中，我们将利用语义内核进程框架开发自动化过程，以便为新产品创建文档。 此过程将从简单开始，并且随着我们的进展逐步演变，以涵盖更现实的情景。

首先，我们将使用一个非常基本的流程对文档过程进行建模：

1. GatherProductInfoStep：收集有关产品的信息。
2. GenerateDocumentationStep：要求 LLM 从步骤 1 中收集的信息生成文档。
3. PublishDocumentationStep：发布文档。

现在，我们了解我们的流程，让我们来构建它。

定义过程步骤

进程的每个步骤都由继承自基步骤类的类定义。 对于此过程，我们有三个步骤：

using Microsoft.SemanticKernel.ChatCompletion;
using Microsoft.SemanticKernel;

// A process step to gather information about a product
public class GatherProductInfoStep: KernelProcessStep
{
    [KernelFunction]
    public string GatherProductInformation(string productName)
    {
        Console.WriteLine($"{nameof(GatherProductInfoStep)}:\n\tGathering product information for product named {productName}");

        // For example purposes we just return some fictional information.
        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 process step to generate documentation for a product
public class GenerateDocumentationStep : KernelProcessStep<GeneratedDocumentationState>
{
    private GeneratedDocumentationState _state = new();

    private string systemPrompt =
            """
            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.
            """;

    // Called by the process runtime when the step instance is activated. Use this to load state that may be persisted from previous activations.
    override public ValueTask ActivateAsync(KernelProcessStepState<GeneratedDocumentationState> state)
    {
        this._state = state.State!;
        this._state.ChatHistory ??= new ChatHistory(systemPrompt);

        return base.ActivateAsync(state);
    }

    [KernelFunction]
    public async Task GenerateDocumentationAsync(Kernel kernel, KernelProcessStepContext context, string productInfo)
    {
        Console.WriteLine($"[{nameof(GenerateDocumentationStep)}]:\tGenerating documentation for provided productInfo...");

        // Add the new product info to the chat history
        this._state.ChatHistory!.AddUserMessage($"Product Info:\n{productInfo.Title} - {productInfo.Content}");

        // Get a response from the LLM
        IChatCompletionService chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();
        var generatedDocumentationResponse = await chatCompletionService.GetChatMessageContentAsync(this._state.ChatHistory!);

        DocumentInfo generatedContent = new()
        {
            Id = Guid.NewGuid().ToString(),
            Title = $"Generated document - {productInfo.Title}",
            Content = generatedDocumentationResponse.Content!,
        };

        this._state!.LastGeneratedDocument = generatedContent;

        await context.EmitEventAsync("DocumentationGenerated", generatedContent);
    }

    public class GeneratedDocumentationState
    {
        public DocumentInfo LastGeneratedDocument { get; set; } = new();
        public ChatHistory? ChatHistory { get; set; }
    }
}

// A process step to publish documentation
public class PublishDocumentationStep : KernelProcessStep
{
    [KernelFunction]
    public DocumentInfo PublishDocumentation(DocumentInfo document)
    {
        // For example purposes we just write the generated docs to the console
        Console.WriteLine($"[{nameof(PublishDocumentationStep)}]:\tPublishing product documentation approved by user: \n{document.Title}\n{document.Content}");
        return document;
    }
}

// Custom classes must be serializable
public class DocumentInfo
{
    public string Id { get; set; } = string.Empty;
    public string Title { get; set; } = string.Empty;
    public string Content { get; set; } = string.Empty;
}

上面的代码定义了流程所需的三个步骤。 下面列出了几个要点：

• 在语义内核中，KernelFunction 定义可由本机代码或 LLM 调用的代码块。 对于 Process 框架，KernelFunction是步骤的可调用成员，每个步骤都需要至少定义一个 KernelFunction。
• 流程框架支持有状态和无状态的步骤。 有状态步骤会自动检查进度，并在多个调用上保持状态。 GenerateDocumentationStep 提供了一个示例，其中使用 GeneratedDocumentationState 类来持久化 ChatHistory 和 LastGeneratedDocument 对象。
• 步骤可以通过对 EmitEventAsync 对象调用 KernelProcessStepContext 来手动发出事件。 若要获取 KernelProcessStepContext 实例只需将其添加为 KernelFunction 上的参数，框架将自动注入它。

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 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.
"""

    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}")

上面的代码定义了流程所需的三个步骤。 下面列出了几个要点：

• 在语义内核中，KernelFunction 定义可由本机代码或 LLM 调用的代码块。 对于 Process 框架，KernelFunction是步骤的可调用成员，每个步骤都需要至少定义一个 KernelFunction。
• 流程框架支持有状态和无状态的步骤。 有状态步骤会自动检查进度，并在多个调用上保持状态。 GenerateDocumentationStep 提供了一个示例，其中 GeneratedDocumentationState 类用于保存 ChatHistory 对象。
• 步骤可以通过对 emit_event 对象调用 KernelProcessStepContext 来手动发出事件。 若要获取 KernelProcessStepContext 实例只需将其添加为 KernelFunction 上的参数，框架将自动注入它。

定义进程流

// Create the process builder
ProcessBuilder processBuilder = new("DocumentationGeneration");

// Add the steps
var infoGatheringStep = processBuilder.AddStepFromType<GatherProductInfoStep>();
var docsGenerationStep = processBuilder.AddStepFromType<GenerateDocumentationStep>();
var docsPublishStep = processBuilder.AddStepFromType<PublishDocumentationStep>();

// Orchestrate the events
processBuilder
    .OnInputEvent("Start")
    .SendEventTo(new(infoGatheringStep));

infoGatheringStep
    .OnFunctionResult()
    .SendEventTo(new(docsGenerationStep));

docsGenerationStep
    .OnFunctionResult()
    .SendEventTo(new(docsPublishStep));

这里有几件事发生，让我们一起来逐步分析一下。

1. 创建构建器：进程使用构建器模式来简化连接各个部分的过程。 生成器提供用于管理流程中的步骤以及管理流程生命周期的方法。

2. 添加步骤：通过调用生成器的 AddStepFromType 方法将步骤添加到进程。 这样，进程框架就可以根据需要实例化实例来管理步骤的生命周期。 在本例中，我们已向该过程添加了三个步骤，并为每个步骤创建了一个变量。 这些变量为我们提供了每个步骤独特实例的句柄，我们可以使用这些实例来定义事件的协调。

3. 组织事件：这是定义事件从一个步骤到另一个步骤的路线。 在本例中，我们有以下路由：

   • 将具有 id = Start 的外部事件发送到进程时，此事件及其关联的数据将发送到 infoGatheringStep 步骤。
   • infoGatheringStep 运行完毕后，将返回的对象发送到 docsGenerationStep 步骤。
   • 最后，当 docsGenerationStep 完成运行后，将返回的对象发送到 docsPublishStep 步骤。

提示

进程框架中的事件路由： 你可能想知道如何将发送到步骤的事件路由到步骤中的内核函数（KernelFunctions）。 在上面的代码中，每个步骤只定义了一个 KernelFunction，并且每个 KernelFunction 只有一个参数（除了 Kernel 和步骤上下文，这些是特殊情况，稍后会详细讲解）。 当包含生成的文档的事件发送到 docsPublishStep 时，它将传递给 document 步骤的 PublishDocumentation KernelFunction docsGenerationStep 参数，因为没有其他选择。 但是，步骤可以有多个 KernelFunction，KernelFunction 可以具有多个参数，在这些高级方案中，需要指定目标函数和参数。

# 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_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()

这里有几件事发生，让我们一起来逐步分析一下。

1. 创建构建器：进程使用构建器模式来简化连接各个部分的过程。 生成器提供用于管理流程中的步骤以及管理流程生命周期的方法。

2. 添加步骤：通过调用 add_step 生成器的方法将步骤添加到进程，该方法将步骤类型添加到生成器。 这样，进程框架就可以根据需要实例化实例来管理步骤的生命周期。 在本例中，我们已向该过程添加了三个步骤，并为每个步骤创建了一个变量。 这些变量为我们提供了每个步骤独特实例的句柄，我们可以使用这些实例来定义事件的协调。

3. 组织事件：这是定义事件从一个步骤到另一个步骤的路线。 在本例中，我们有以下路由：

   • 向进程发送外部事件 id = Start 时，此事件及其关联的数据将被发送到 info_gathering_step。
   • info_gathering_step完成运行后，将返回的对象发送到docs_generation_step该对象。
   • 最后，完成运行后 docs_generation_step ，将返回的对象发送到该 docs_publish_step对象。

提示

进程框架中的事件路由： 你可能想知道如何将发送到步骤的事件路由到步骤中的内核函数（KernelFunctions）。 在上面的代码中，每个步骤只定义了一个 KernelFunction，并且每个 KernelFunction 只有一个参数（除了 Kernel 和步骤上下文，这些是特殊情况，稍后会详细讲解）。 将包含生成文档的事件发送到docs_publish_step时，事件会被传递给 docs 的参数 publish_documentation 内的 KernelFunction，因为没有其他的选项。 但是，步骤可以有多个 KernelFunction，KernelFunction 可以具有多个参数，在这些高级方案中，需要指定目标函数和参数。

生成并运行进程

// Configure the kernel with your LLM connection details
Kernel kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion("myDeployment", "myEndpoint", "myApiKey")
    .Build();

// Build and run the process
var process = processBuilder.Build();
await process.StartAsync(kernel, new KernelProcessEvent { Id = "Start", Data = "Contoso GlowBrew" });

我们将生成进程并调用 StartAsync 来运行它。 我们的进程需要一个名为 Start 的初始外部事件来启动事情，因此我们也提供了这一点。 运行此过程会显示控制台中的以下输出：

GatherProductInfoStep: Gathering product information for product named Contoso GlowBrew
GenerateDocumentationStep: Generating documentation for provided productInfo
PublishDocumentationStep: Publishing product documentation:

# GlowBrew: Your Ultimate Coffee Experience Awaits!

Welcome to the world of GlowBrew, where coffee brewing meets remarkable technology! At Contoso, we believe that your morning ritual shouldn't just include the perfect cup of coffee but also a stunning visual experience that invigorates your senses. Our revolutionary AI-driven coffee machine is designed to transform your kitchen routine into a delightful ceremony.

## Unleash the Power of GlowBrew

### Key Features

- **Luminous Brew Technology**
  - Elevate your coffee experience with our cutting-edge programmable LED lighting. GlowBrew allows you to customize your morning ambiance, creating a symphony of colors that sync seamlessly with your brewing process. Whether you need a vibrant wake-up call or a soothing glow, you can set the mood for any moment!

- **AI Taste Assistant**
  - Your taste buds deserve the best! With the GlowBrew built-in AI taste assistant, the machine learns your unique preferences over time and curates personalized brew suggestions just for you. Expand your coffee horizons and explore delightful new combinations that fit your palate perfectly.

- **Gourmet Aroma Diffusion**
  - Awaken your senses even before that first sip! The GlowBrew comes equipped with gourmet aroma diffusers that enhance the scent profile of your coffee, diffusing rich aromas that fill your kitchen with the warm, inviting essence of freshly-brewed bliss.

### Not Just Coffee - An Experience

With GlowBrew, it's more than just making coffee-it's about creating an experience that invigorates the mind and pleases the senses. The glow of the lights, the aroma wafting through your space, and the exceptional taste meld into a delightful ritual that prepares you for whatever lies ahead.

## Troubleshooting Made Easy

While GlowBrew is designed to provide a seamless experience, we understand that technology can sometimes be tricky. If you encounter issues with the LED lights, we've got you covered:

- **LED Lights Malfunctioning?**
  - If your LED lights aren't working as expected, don't worry! Follow these steps to restore the glow:
    1. **Reset the Lighting Settings**: Use the GlowBrew app to reset the lighting settings.
    2. **Check Connections**: Ensure that the LED connections inside the GlowBrew are secure.
    3. **Factory Reset**: If you're still facing issues, perform a factory reset to rejuvenate your machine.

With GlowBrew, you not only brew the perfect coffee but do so with an ambiance that excites the senses. Your mornings will never be the same!

## Embrace the Future of Coffee

Join the growing community of GlowBrew enthusiasts today, and redefine how you experience coffee. With stunning visual effects, customized brewing suggestions, and aromatic enhancements, it's time to indulge in the delightful world of GlowBrew-where every cup is an adventure!

### Conclusion

Ready to embark on an extraordinary coffee journey? Discover the perfect blend of technology and flavor with Contoso's GlowBrew. Your coffee awaits!

# 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()

我们将生成进程，并使用异步上下文管理器进行调用 start 以运行它。 我们的进程需要一个名为 Start 的初始外部事件来启动事情，因此我们也提供了这一点。 运行此过程会显示控制台中的以下输出：

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.

下一步是什么？

我们文档生成过程的第一个草稿正在运行，但仍有很大的改进空间。 至少一个生产版本需要以下内容：

• 一个校对代理，将对生成的文档进行评分，并验证这些文档是否符合我们的质量和准确性标准。
• 一个审批过程，其中文档仅在有人批准后发布（人类参与）。

将校对代理添加到我们的流程中...