Erweiterte Themen der semantischen Orchestrierung von Kernel-Agenten

Entwickler können das Ergebnis eines Orchestrierungsaufrufs später abrufen, indem Sie die GetValueAsync Methode für das Ergebnisobjekt aufrufen. Wenn die Anwendung bereit ist, das Ergebnis zu verarbeiten, kann der Aufruf abgeschlossen sein oder nicht abgeschlossen sein. Daher können Entwickler optional ein Timeout für die GetValueAsync Methode angeben. Wenn die Orchestrierung nicht innerhalb des angegebenen Timeouts abgeschlossen ist, wird eine Timeoutausnahme ausgelöst.

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

Wenn die Orchestrierung nicht innerhalb des angegebenen Timeouts abgeschlossen ist, wird eine Timeoutausnahme ausgelöst.

Entwickler können das Ergebnis eines Orchestrierungsaufrufs später abrufen, indem Sie die get Methode für das Ergebnisobjekt aufrufen. Wenn die Anwendung bereit ist, das Ergebnis zu verarbeiten, kann der Aufruf abgeschlossen sein oder nicht abgeschlossen sein. Daher können Entwickler optional ein Timeout für die get Methode angeben. Wenn die Orchestrierung nicht innerhalb des angegebenen Timeouts abgeschlossen ist, wird eine Timeoutausnahme ausgelöst.

value = await orchestration_result.get(timeout=60)

Wenn die Orchestrierung nicht innerhalb des angegebenen Timeouts abgeschlossen ist, wird eine Timeoutausnahme ausgelöst.

Um Agentantworten innerhalb eines Aufrufs anzuzeigen, können Entwickler eine ResponseCallback der Orchestrierung übergeben. Auf diese Weise können Entwickler die Antworten jedes Agents während des Orchestrierungsprozesses beobachten. Entwickler können diesen Rückruf für Ui-Updates, Protokollierung oder andere Zwecke verwenden.

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

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

Um Agentantworten innerhalb eines Aufrufs zu sehen, können Entwickler ein agent_response_callback in die Orchestrierung einfügen. Auf diese Weise können Entwickler die Antworten jedes Agents während des Orchestrierungsprozesses beobachten. Entwickler können diesen Rückruf für Ui-Updates, Protokollierung oder andere Zwecke verwenden.

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,
)

Stellen Sie für Orchestrierungen, die Benutzereingaben unterstützen (z. B. Übergabe und Gruppenchat), eine InteractiveCallback bereit, die eine ChatMessageContent vom Benutzer zurückgibt. Mithilfe dieses Rückrufs können Entwickler benutzerdefinierte Logik implementieren, um Benutzereingaben zu sammeln, z. B. das Anzeigen einer Benutzeroberflächenaufforderung oder die Integration in andere Systeme.

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

Stellen Sie für Orchestrierungen, die Benutzereingaben unterstützen (z. B. Übergabe und Gruppenchat), eine human_response_function bereit, die eine ChatMessageContent vom Benutzer zurückgibt. Mithilfe dieses Rückrufs können Entwickler benutzerdefinierte Logik implementieren, um Benutzereingaben zu sammeln, z. B. das Anzeigen einer Benutzeroberflächenaufforderung oder die Integration in andere Systeme.

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,
)

Entwickler können strukturierte Daten als Eingabe an Orchestrierungen übergeben, indem sie eine stark typisierte Eingabeklasse verwenden und als generischer Parameter für die Orchestrierung angeben. Dies ermöglicht die Typsicherheit und mehr Flexibilität für Orchestrierungen, um komplexe Datenstrukturen zu verarbeiten. Um z. B. GitHub-Probleme zu triagen, definieren Sie eine Klasse für die strukturierte Eingabe:

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; } = [];
}

Entwickler können diesen Typ dann als Eingabe für eine Orchestrierung verwenden, indem Sie ihn als generischen Parameter angeben:

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

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

Benutzerdefinierte Eingabetransformationen

Standardmäßig verwendet die Orchestrierung die integrierte Eingabetransformation, die das Objekt in JSON serialisiert und in ein ChatMessageContent. Wenn Sie anpassen möchten, wie ihre strukturierte Eingabe in den zugrunde liegenden Nachrichtentyp konvertiert wird, können Sie ihre eigene Eingabetransformationsfunktion über die InputTransform Eigenschaft bereitstellen:

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]);
        },
    };

Auf diese Weise können Sie genau steuern, wie Ihre eingegebenen Eingaben den Agents angezeigt werden, wodurch erweiterte Szenarien wie benutzerdefinierte Formatierung, Feldauswahl oder Mehrnachrichteneingabe ermöglicht werden.

Entwickler können strukturierte Daten als Eingabe an Orchestrierungen übergeben, indem sie ein Pydantisches Modell (oder eine beliebige benutzerdefinierte Klasse) als generischen Parameter für die Orchestrierung angeben. Dies ermöglicht die Typsicherheit und ermöglicht es den Orchestrierungen, komplexe Datenstrukturen zu verarbeiten.

Um z. B. GitHub-Probleme zu triagen, definieren Sie ein Pydantisches Modell für die strukturierte Eingabe:

from pydantic import BaseModel

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

Sie können diesen Typ dann als Eingabe für Ihre Orchestrierung verwenden, indem Sie ihn als generischen Parameter angeben:

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,
)

Agents und Orchestrierungen können strukturierte Ausgaben zurückgeben, indem eine streng typisierte Ausgabeklasse als generischer Parameter für die Orchestrierung angegeben wird. Auf diese Weise können Sie mit umfangreichen, strukturierten Ergebnissen in Ihrer Anwendung arbeiten und nicht nur mit Nur-Text.This enables you to work with rich, structured results in your application, rather than just plain text.

Angenommen, Sie möchten einen Artikel analysieren und Themen, Stimmungen und Entitäten extrahieren. Definieren sie eine Klasse für die strukturierte Ausgabe:

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

Sie können diesen Typ dann als Ausgabe für Ihre Orchestrierung verwenden, indem Sie ihn als generischen Parameter angeben:

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));

Benutzerdefinierte Ausgabetransformationen

Standardmäßig verwendet die Orchestrierung die integrierte Ausgabetransformation, die versucht, den Antwortinhalt des Dienstes auf Ihren Ausgabetyp zu deserialisieren. Für komplexere Szenarien können Sie eine benutzerdefinierte Ausgabetransformation (z. B. mit strukturierter Ausgabe durch einige Modelle) bereitstellen.

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

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

Mit diesem Ansatz können Sie strukturierte Daten direkt aus der Orchestrierung empfangen und verarbeiten, sodass erweiterte Workflows und Integrationen einfacher erstellt werden können.

Agents und Orchestrierungen können strukturierte Ausgaben zurückgeben, indem ein Pydantic-Modell (oder eine beliebige benutzerdefinierte Klasse) als generischer Ausgabetyp für die Orchestrierung angegeben wird. Auf diese Weise können Sie mit umfangreichen, strukturierten Ergebnissen in Ihrer Anwendung arbeiten und nicht nur mit Nur-Text.This enables you to work with rich, structured results in your application, rather than just plain text.

Angenommen, Sie möchten einen Artikel analysieren und Themen, Stimmungen und Entitäten extrahieren. Definieren Sie ein Pydantisches Modell für die strukturierte Ausgabe:

from pydantic import BaseModel

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

Sie können diesen Typ dann als Ausgabe für Ihre Orchestrierung verwenden, indem Sie ihn als generischen Parameter angeben und eine Ausgabetransformation angeben:

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

Mit diesem Ansatz können Sie strukturierte Daten direkt aus der Orchestrierung empfangen und verarbeiten, sodass erweiterte Workflows und Integrationen einfacher erstellt werden können.

Sie können eine Orchestrierung abbrechen, indem Sie die Cancel Methode für den Ergebnishandler aufrufen. Dadurch wird die Orchestrierung beendet, indem das Signal an alle Agents weitergegeben wird, und sie beenden die Verarbeitung weiterer Nachrichten.

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

Entwickler können eine Orchestrierung abbrechen, indem sie die cancel Methode für den Ergebnishandler aufrufen. Dadurch wird die Orchestrierung beendet, indem das Signal an alle Agents weitergegeben wird, und sie beenden die Verarbeitung weiterer Nachrichten.

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