Rubriques avancées sur l’orchestration de l’agent de noyau sémantique

Les développeurs peuvent obtenir le résultat d’un appel d’orchestration ultérieurement en appelant la GetValueAsync méthode sur l’objet résultat. Lorsque l’application est prête à traiter le résultat, l’appel peut ou non être terminé. Par conséquent, les développeurs peuvent éventuellement spécifier un délai d’expiration pour la GetValueAsync méthode. Si l’orchestration ne se termine pas dans le délai d’expiration spécifié, une exception de délai d’attente sera levée.

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

Si l’orchestration ne se termine pas dans le délai d’expiration spécifié, une exception de délai d’attente sera levée.

Les développeurs peuvent obtenir le résultat d’un appel d’orchestration ultérieurement en appelant la get méthode sur l’objet résultat. Lorsque l’application est prête à traiter le résultat, l’appel peut ou non être terminé. Par conséquent, les développeurs peuvent éventuellement spécifier un délai d’expiration pour la get méthode. Si l’orchestration ne se termine pas dans le délai d’expiration spécifié, une exception de délai d’attente sera levée.

value = await orchestration_result.get(timeout=60)

Si l’orchestration ne se termine pas dans le délai d’expiration spécifié, une exception de dépassement de délai est levée.

Pour voir les réponses de l'agent à l'intérieur d'une invocation, les développeurs peuvent fournir une ResponseCallback à l'orchestration. Cela permet aux développeurs d’observer les réponses de chaque agent pendant le processus d’orchestration. Les développeurs peuvent utiliser ce rappel pour les mises à jour de l’interface utilisateur, la journalisation ou d’autres fins.

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

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

Pour voir les réponses de l'agent à l'intérieur d'une invocation, les développeurs peuvent fournir un agent_response_callback à l'orchestration. Cela permet aux développeurs d’observer les réponses de chaque agent pendant le processus d’orchestration. Les développeurs peuvent utiliser ce rappel pour les mises à jour de l’interface utilisateur, la journalisation ou d’autres fins.

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

Pour les orchestrations qui prennent en charge les entrées utilisateur (par exemple, le passage et la conversation de groupe), fournissez un élément InteractiveCallback qui retourne une réponse ChatMessageContent de l'utilisateur. À l’aide de ce rappel, les développeurs peuvent implémenter une logique personnalisée pour collecter des entrées utilisateur, telles que l’affichage d’une invite d’interface utilisateur ou l’intégration à d’autres systèmes.

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

Pour les orchestrations qui prennent en charge les entrées utilisateur (par exemple, le passage et la conversation de groupe), fournissez un élément human_response_function qui retourne une réponse ChatMessageContent de l'utilisateur. À l’aide de ce rappel, les développeurs peuvent implémenter une logique personnalisée pour collecter des entrées utilisateur, telles que l’affichage d’une invite d’interface utilisateur ou l’intégration à d’autres systèmes.

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

Les développeurs peuvent transmettre des données structurées en tant qu’entrée aux orchestrations à l’aide d’une classe d’entrée fortement typée et en la spécifiant comme paramètre générique pour l’orchestration. Cela permet la sécurité des types et une plus grande flexibilité pour les orchestrations afin de gérer des structures de données complexes. Par exemple, pour trier les problèmes GitHub, définissez une classe pour l’entrée structurée :

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

Les développeurs peuvent ensuite utiliser ce type comme entrée d’une orchestration en lui fournissant le paramètre générique :

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

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

Transformations d’entrée personnalisées

Par défaut, l’orchestration utilise la transformation d’entrée intégrée, qui sérialise l’objet en JSON et l’encapsule dans un ChatMessageContent. Si vous souhaitez personnaliser la façon dont votre entrée structurée est convertie en type de message sous-jacent, vous pouvez fournir votre propre fonction de transformation d’entrée via la InputTransform propriété :

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

Cela vous permet de contrôler exactement la façon dont votre entrée typée est présentée aux agents, en activant des scénarios avancés tels que la mise en forme personnalisée, la sélection de champs ou l’entrée à plusieurs messages.

Les développeurs peuvent transmettre des données structurées en tant qu’entrée aux orchestrations en spécifiant un modèle Pydantic (ou n’importe quelle classe personnalisée) comme paramètre générique pour l’orchestration. Cela permet la sécurité des types et permet aux orchestrations de gérer des structures de données complexes.

Par exemple, pour trier les problèmes GitHub, définissez un modèle Pydantic pour l’entrée structurée :

from pydantic import BaseModel

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

Vous pouvez ensuite utiliser ce type comme entrée de votre orchestration en le fournissant comme paramètre générique :

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

Les agents et les orchestrations peuvent retourner des résultats structurés en spécifiant une classe de sortie fortement typée comme paramètre générique pour l’orchestration. Cela vous permet d’utiliser des résultats enrichis et structurés dans votre application, plutôt que du texte brut.

Par exemple, supposons que vous souhaitiez analyser un article et extraire des thèmes, des sentiments et des entités. Définissez une classe pour la sortie structurée :

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

Vous pouvez ensuite utiliser ce type comme sortie pour votre orchestration en le fournissant comme paramètre générique :

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

Transformations de sortie personnalisées

Par défaut, l’orchestration utilise la transformation de sortie intégrée, qui tente de désérialiser le contenu de réponse de l’agent à votre type de sortie. Pour les scénarios plus avancés, vous pouvez fournir une transformation de sortie personnalisée (par exemple, avec une sortie structurée par certains modèles).

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

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

Cette approche vous permet de recevoir et de traiter des données structurées directement à partir de l’orchestration, ce qui facilite la création de flux de travail et d’intégrations avancés.

Les agents et les orchestrations peuvent retourner des sorties structurées en spécifiant un modèle Pydantic (ou n’importe quelle classe personnalisée) comme type de sortie générique pour l’orchestration. Cela vous permet d’utiliser des résultats enrichis et structurés dans votre application, plutôt que du texte brut.

Par exemple, supposons que vous souhaitiez analyser un article et extraire des thèmes, des sentiments et des entités. Définissez un modèle Pydantic pour la sortie structurée :

from pydantic import BaseModel

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

Vous pouvez ensuite utiliser ce type comme sortie pour votre orchestration en le fournissant comme paramètre générique et en spécifiant une transformation de sortie :

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

Cette approche vous permet de recevoir et de traiter des données structurées directement à partir de l’orchestration, ce qui facilite la création de flux de travail et d’intégrations avancés.

Vous pouvez annuler une orchestration en appelant la Cancel méthode sur le gestionnaire de résultats. Cela arrête l’orchestration en propageant le signal à tous les agents, et il cesse de traiter d’autres messages.

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

Les développeurs peuvent annuler une orchestration en appelant la cancel méthode sur le gestionnaire de résultats. Cela arrête l’orchestration en propageant le signal à tous les agents, et il cesse de traiter d’autres messages.

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