Zaawansowane tematy dotyczące orkiestracji agenta rdzenia semantycznego

Deweloperzy mogą uzyskać wynik wywołania orkiestracji później, wywołując metodę GetValueAsync w obiekcie result. Gdy aplikacja jest gotowa do przetworzenia wyniku, wywołanie może lub nie zostało ukończone. W związku z tym deweloperzy mogą opcjonalnie określić limit czasu dla GetValueAsync metody . Jeśli aranżacja nie zostanie ukończona w określonym przedziale czasu, zostanie zgłoszony wyjątek limitu czasu.

string output = await result.GetValueAsync(TimeSpan.FromSeconds(60));

Jeśli aranżacja nie zostanie ukończona w określonym przedziale czasu, zostanie zgłoszony wyjątek limitu czasu.

Deweloperzy mogą uzyskać wynik wywołania orkiestracji później, wywołując metodę get w obiekcie result. Gdy aplikacja jest gotowa do przetworzenia wyniku, wywołanie może lub nie zostało ukończone. W związku z tym deweloperzy mogą opcjonalnie określić limit czasu dla get metody . Jeśli aranżacja nie zostanie ukończona w określonym przedziale czasu, zostanie zgłoszony wyjątek limitu czasu.

value = await orchestration_result.get(timeout=60)

Jeśli aranżacja nie zostanie ukończona w określonym przedziale czasu, zostanie zgłoszony wyjątek limitu czasu.

Aby wyświetlić odpowiedzi agenta wewnątrz wywołania, deweloperzy mogą przekazać ResponseCallback do orkiestracji. Dzięki temu deweloperzy mogą obserwować odpowiedzi poszczególnych agentów podczas procesu aranżacji. Deweloperzy mogą używać tego wywołania zwrotnego do aktualizacji interfejsu użytkownika, rejestrowania lub innych celów.

public ValueTask ResponseCallback(ChatMessageContent response)
{
    Console.WriteLine($"# {response.AuthorName}\n{response.Content}");
    return ValueTask.CompletedTask;
}

SequentialOrchestration orchestration = new SequentialOrchestration(
    analystAgent, writerAgent, editorAgent)
{
    ResponseCallback = ResponseCallback,
};

Aby zobaczyć odpowiedzi agenta wewnątrz wywołania, deweloperzy mogą dostarczyć agent_response_callback do orkiestracji. Dzięki temu deweloperzy mogą obserwować odpowiedzi poszczególnych agentów podczas procesu aranżacji. Deweloperzy mogą używać tego wywołania zwrotnego do aktualizacji interfejsu użytkownika, rejestrowania lub innych celów.

def agent_response_callback(message: ChatMessageContent) -> None:
    print(f"# {message.name}\n{message.content}")

sequential_orchestration = SequentialOrchestration(
    members=agents,
    agent_response_callback=agent_response_callback,
)

W przypadku orkiestracji, które obsługują dane wejściowe użytkownika (np. przekazywanie i czat grupowy), należy podać element InteractiveCallback, który zwraca element ChatMessageContent od użytkownika. Korzystając z tego wywołania zwrotnego, deweloperzy mogą implementować logikę niestandardową w celu zbierania danych wejściowych użytkownika, takich jak wyświetlanie komunikatu interfejsu użytkownika lub integrowanie z innymi systemami.

HandoffOrchestration orchestration = new(...)
{
    InteractiveCallback = () =>
    {
        Console.Write("User: ");
        string input = Console.ReadLine();
        return new ChatMessageContent(AuthorRole.User, input);
    }
};

W przypadku orkiestracji, które obsługują dane wejściowe użytkownika (np. przekazywanie i czat grupowy), należy podać element human_response_function, który zwraca element ChatMessageContent od użytkownika. Korzystając z tego wywołania zwrotnego, deweloperzy mogą implementować logikę niestandardową w celu zbierania danych wejściowych użytkownika, takich jak wyświetlanie komunikatu interfejsu użytkownika lub integrowanie z innymi systemami.

def human_response_function() -> ChatMessageContent:
    user_input = input("User: ")
    return ChatMessageContent(role=AuthorRole.USER, content=user_input)

handoff_orchestration = HandoffOrchestration(
    ...,
    agent_response_callback=agent_response_callback,
)

Deweloperzy mogą przekazywać dane ustrukturyzowane jako dane wejściowe do aranżacji przy użyciu silnie typizowanej klasy wejściowej i określać je jako ogólny parametr aranżacji. Umożliwia to bezpieczeństwo typów i większą elastyczność orkiestracji przy obsłudze złożonych struktur danych. Aby na przykład sklasyfikować problemy z usługą GitHub, zdefiniuj klasę dla danych wejściowych ze strukturą:

public sealed class GithubIssue
{
    public string Id { get; set; } = string.Empty;
    public string Title { get; set; } = string.Empty;
    public string Body { get; set; } = string.Empty;
    public string[] Labels { get; set; } = [];
}

Deweloperzy mogą następnie używać tego typu jako danych wejściowych do aranżacji, podając go jako parametr ogólny:

HandoffOrchestration<GithubIssue, string> orchestration =
    new(...);

GithubIssue input = new GithubIssue { ... };
var result = await orchestration.InvokeAsync(input, runtime);

Niestandardowe przekształcenia danych wejściowych

Domyślnie orkiestracja będzie używać wbudowanej transformacji wejściowej, która serializuje obiekt w formacie JSON i opakowuje go w formacie ChatMessageContent. Jeśli chcesz dostosować sposób konwersji danych wejściowych ze strukturą na odpowiedni typ komunikatu, możesz podać swoją własną funkcję transformacji danych wejściowych za pośrednictwem właściwości InputTransform.

HandoffOrchestration<GithubIssue, string> orchestration =
    new(...)
    {
        InputTransform = (issue, cancellationToken) =>
        {
            // For example, create a chat message with a custom format
            var message = new ChatMessageContent(AuthorRole.User, $"[{issue.Id}] {issue.Title}\n{issue.Body}");
            return ValueTask.FromResult<IEnumerable<ChatMessageContent>>([message]);
        },
    };

Dzięki temu można kontrolować dokładnie sposób prezentowania wpisanych danych wejściowych agentom, umożliwiając zaawansowane scenariusze, takie jak formatowanie niestandardowe, wybór pola lub wprowadzanie wielu komunikatów.

Deweloperzy mogą przekazywać dane ustrukturyzowane jako dane wejściowe do aranżacji, określając model Pydantic (lub dowolną klasę niestandardową) jako ogólny parametr aranżacji. Umożliwia to bezpieczeństwo typów i umożliwia orkiestracji obsługę złożonych struktur danych.

Aby na przykład przeprowadzić triage problemów z usługą GitHub, zdefiniuj model Pydantic dla strukturyzowanych danych wejściowych:

from pydantic import BaseModel

class GithubIssue(BaseModel):
    id: str
    title: str
    body: str
    labels: list[str] = []

Następnie możesz użyć tego typu jako danych wejściowych do aranżacji, podając go jako parametr ogólny:

from semantic_kernel.agents import HandoffOrchestration

def custom_input_transform(input_message: GithubIssue) -> ChatMessageContent:
    return ChatMessageContent(role=AuthorRole.USER, content=f"[{input_message.id}] {input_message.title}\n{input_message.body}")


handoff_orchestration = HandoffOrchestration[GithubIssue, ChatMessageContent](
    ...,
    input_transform=custom_input_transform,
)

GithubIssueSample = GithubIssue(
    id="12345",
    title="Bug: ...",
    body="Describe the bug...",
    labels=[],
)

orchestration_result = await handoff_orchestration.invoke(
    task=GithubIssueSample,
    runtime=runtime,
)

Agenci i orkiestracje mogą zwracać ustrukturyzowane dane wyjściowe, określając silnie typizowaną klasę danych wyjściowych jako ogólny parametr aranżacji. Umożliwia to pracę z zaawansowanymi, ustrukturyzowanymi wynikami w aplikacji, a nie tylko zwykłym tekstem.

Załóżmy na przykład, że chcesz przeanalizować artykuł i wyodrębnić motywy, tonacje i jednostki. Zdefiniuj klasę dla danych wyjściowych ze strukturą:

public sealed class Analysis
{
    public IList<string> Themes { get; set; } = [];
    public IList<string> Sentiments { get; set; } = [];
    public IList<string> Entities { get; set; } = [];
}

Następnie możesz użyć tego typu jako dane wyjściowe orkiestracji, podając go jako parametr ogólny.

ConcurrentOrchestration<string, Analysis> orchestration =
    new(agent1, agent2, agent3)
    {
        ResultTransform = outputTransform.TransformAsync, // see below
    };

// ...
OrchestrationResult<Analysis> result = await orchestration.InvokeAsync(input, runtime);
Analysis output = await result.GetValueAsync(TimeSpan.FromSeconds(60));

Niestandardowe przekształcenia danych wyjściowych

Domyślnie orkiestracja będzie używać wbudowanej transformacji wyjściowej, która próbuje deserializować zawartość odpowiedzi agenta na typ danych wyjściowych. W przypadku bardziej zaawansowanych scenariuszy można udostępnić niestandardową transformację danych wyjściowych (na przykład ze ustrukturyzowanymi danymi wyjściowymi według niektórych modeli).

StructuredOutputTransform<Analysis> outputTransform =
    new(chatCompletionService, new OpenAIPromptExecutionSettings { ResponseFormat = typeof(Analysis) });

ConcurrentOrchestration<string, Analysis> orchestration =
    new(agent1, agent2, agent3)
    {
        ResultTransform = outputTransform.TransformAsync,
    };

Takie podejście umożliwia odbieranie i przetwarzanie danych ustrukturyzowanych bezpośrednio z aranżacji, co ułatwia tworzenie zaawansowanych przepływów pracy i integracji.

Agenci i aranżacje mogą zwracać ustrukturyzowane dane wyjściowe, określając model Pydantic (lub dowolną klasę niestandardową) jako ogólny typ danych wyjściowych aranżacji. Umożliwia to pracę z zaawansowanymi, ustrukturyzowanymi wynikami w aplikacji, a nie tylko zwykłym tekstem.

Załóżmy na przykład, że chcesz przeanalizować artykuł i wyodrębnić motywy, tonacje i jednostki. Zdefiniuj model Pydantic dla danych wyjściowych ze strukturą:

from pydantic import BaseModel

class ArticleAnalysis(BaseModel):
    themes: list[str]
    sentiments: list[str]
    entities: list[str]

Następnie możesz użyć tego typu jako danych wyjściowych aranżacji, podając go jako parametr ogólny i określając przekształcenie danych wyjściowych:

from semantic_kernel.agents import ConcurrentOrchestration
from semantic_kernel.agents.orchestration.tools import structured_outputs_transform
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

# `structured_outputs_transform` is a built-in transform that uses the structured output

concurrent_orchestration = ConcurrentOrchestration[str, ArticleAnalysis](
    members=agents,
    output_transform=structured_outputs_transform(ArticleAnalysis, AzureChatCompletion()),
)

...

orchestration_result = await concurrent_orchestration.invoke(
    task="article text",
    runtime=runtime,
)

value = await orchestration_result.get(timeout=20)

# `value` is now an instance of ArticleAnalysis

Takie podejście umożliwia odbieranie i przetwarzanie danych ustrukturyzowanych bezpośrednio z aranżacji, co ułatwia tworzenie zaawansowanych przepływów pracy i integracji.

Orkiestrację można anulować, wywołując metodę Cancel w procedurze obsługi wyników. Spowoduje to zatrzymanie koordynacji przez propagowanie sygnału do wszystkich agentów, co zatrzyma przetwarzanie kolejnych komunikatów.

var resultTask = orchestration.InvokeAsync(input, runtime);
resultTask.Cancel();

Deweloperzy mogą anulować aranżację, wywołując metodę cancel w procedurze obsługi wyników. Spowoduje to zatrzymanie koordynacji przez propagowanie sygnału do wszystkich agentów, co zatrzyma przetwarzanie kolejnych komunikatów.

orchestration_result = await orchestration.invoke(task=task, runtime=runtime)
orchestration_result.cancel()