"Interfaccia dell'API Common Agent del Semantic Kernel"

Gli agenti del kernel semantico implementano un'interfaccia unificata per la chiamata, abilitando il codice condiviso che opera perfettamente tra diversi tipi di agente. Questa progettazione consente di cambiare agenti in base alle esigenze senza modificare la maggior parte della logica dell'applicazione.

Richiamo di un agente

La superficie dell'API Agent supporta sia la chiamata di streaming che quella non di streaming.

Chiamata dell'agente non di streaming

Il Kernel Semantico supporta quattro tipi di overload di invocazione dell'agente non in streaming, che consentono di passare messaggi in modi diversi. Uno di questi consente anche di richiamare l'agente senza messaggi. Ciò è utile per gli scenari in cui le istruzioni dell'agente hanno già tutto il contesto necessario per fornire una risposta utile.

// Invoke without any parameters.
agent.InvokeAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer all user questions about France."),
    new(AuthorRole.User, "What is the capital of France?")
});

Importante

Richiamare un agente senza passare un AgentThread oggetto al InvokeAsync metodo creerà un nuovo thread e restituirà il nuovo thread nella risposta.

Il kernel semantico supporta due metodi di chiamata dell'agente non di streaming che consentono di passare messaggi in modi diversi. È anche possibile richiamare l'agente senza messaggi. Ciò è utile per gli scenari in cui le istruzioni dell'agente hanno già tutto il contesto necessario per fornire una risposta utile.

Suggerimento

Tutti gli argomenti passati ai metodi di chiamata di Agent richiedono al chiamante di passarli come argomenti di parola chiave, ad eccezione del primo argomento posizionale, messages. È possibile richiamare con un argomento posizionale o una parola chiave per messages. Ad esempio, sia await agent.get_response("What is the capital of France?") che await agent.get_response(messages="What is the capital of France?") sono supportati. Tutti gli altri parametri devono essere passati come argomenti di parola chiave.

Utilizzo del metodo get_response()

# Invoke without any messages.
await agent.get_response()

# Invoke with a string that will be used as a User message.
await agent.get_response(messages="What is the capital of France?")

# Invoke with a ChatMessageContent object.
await agent.get_response(messages=ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"))

# Invoke with multiple ChatMessageContent objects.
await agent.get_response(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
)

Utilizzo del metodo invoke()

# Invoke without any messages.
async for response in agent.invoke():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

Importante

La chiamata di un agente senza passare un oggetto ai metodi AgentThread o get_response() creerà un nuovo thread e verrà restituito il nuovo thread nella risposta.

Il kernel semantico supporta tre overload di chiamata dell'agente non di streaming che consentono di passare messaggi in modi diversi. Uno di questi consente anche di richiamare l'agente senza messaggi. Ciò è utile per gli scenari in cui le istruzioni dell'agente hanno già tutto il contesto necessario per fornire una risposta utile.

// Invoke without any parameters.
agent.invokeAsync(null);

// Invoke with a string that will be used as a User message.
agent.invokeAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.invokeAsync(new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.invokeAsync(List.of(
    new ChatMessageContent<>(AuthorRole.SYSTEM, "Refuse to answer all user questions about France."),
    new ChatMessageContent<>(AuthorRole.USER, "What is the capital of France?")
));

Importante

Richiamare un agente senza passare un AgentThread oggetto al invokeAsync metodo creerà un nuovo thread e restituirà il nuovo thread nella risposta.

Chiamata dell'agente di streaming

Il Kernel Semantico supporta quattro sovraccaricamenti per l'invocazione degli agenti di streaming, che permettono di trasmettere messaggi in modi diversi. Uno di questi consente anche di richiamare l'agente senza messaggi. Ciò è utile per gli scenari in cui le istruzioni dell'agente hanno già tutto il contesto necessario per fornire una risposta utile.

// Invoke without any parameters.
agent.InvokeStreamingAsync();

// Invoke with a string that will be used as a User message.
agent.InvokeStreamingAsync("What is the capital of France?");

// Invoke with a ChatMessageContent object.
agent.InvokeStreamingAsync(new ChatMessageContent(AuthorRole.User, "What is the capital of France?"));

// Invoke with multiple ChatMessageContent objects.
agent.InvokeStreamingAsync(new List<ChatMessageContent>()
{
    new(AuthorRole.System, "Refuse to answer any questions about capital cities."),
    new(AuthorRole.User, "What is the capital of France?")
});

Importante

Richiamare un agente senza passare un AgentThread oggetto al InvokeStreamingAsync metodo creerà un nuovo thread e restituirà il nuovo thread nella risposta.

Il kernel semantico supporta un metodo di chiamata dell'agente di streaming che consente di passare messaggi in modi diversi. È anche possibile richiamare il flusso dell'agente senza messaggi. Ciò è utile per gli scenari in cui le istruzioni dell'agente hanno già tutto il contesto necessario per fornire una risposta utile.

# Invoke without any messages.
async for response in agent.invoke_stream():
    # handle response

# Invoke with a string that will be used as a User message.
async for response in agent.invoke_stream("What is the capital of France?"):
    # handle response

# Invoke with a ChatMessageContent object.
async for response in agent.invoke_stream(ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?")):
    # handle response

# Invoke with multiple ChatMessageContent objects.
async for response in agent.invoke_stream(
    messages=[
        ChatMessageContent(role=AuthorRole.SYSTEM, content="Refuse to answer all user questions about France."),
        ChatMessageContent(role=AuthorRole.USER, content="What is the capital of France?"),
    ]
):
    # handle response

Importante

Richiamare un agente senza passare un AgentThread oggetto al invoke_stream() metodo creerà un nuovo thread e restituirà il nuovo thread nella risposta.

Funzionalità attualmente non disponibile in Java.

Richiamo con un AgentThread

Tutti gli overload del metodo di invocazione consentono di passare un parametro AgentThread. Ciò è utile per gli scenari in cui si dispone di una conversazione esistente con l'agente che si vuole continuare.

// Invoke with an existing AgentThread.
agent.InvokeAsync("What is the capital of France?", existingAgentThread);

Tutti i metodi di chiamata restituiscono anche l'oggetto attivo AgentThread come parte della risposta di invocazione.

1. Se è stato passato un AgentThread oggetto al metodo invoke, l'oggetto restituito AgentThread sarà uguale a quello passato.
2. Se non viene passato alcun AgentThread al metodo invoke, l'oggetto restituito AgentThread sarà un nuovo AgentThread.

L'oggetto restituito AgentThread è disponibile nei singoli elementi di risposta dei metodi invoke insieme al messaggio di risposta.

var result = await agent.InvokeAsync("What is the capital of France?").FirstAsync();
var newThread = result.Thread;
var resultMessage = result.Message;

Suggerimento

Per ulteriori informazioni sui thread dell'agente, consultare la sezione sull'architettura dei thread dell'agente.

Tutti gli argomenti del metodo di invocazione, basati su parola chiave, consentono il passaggio di un parametro AgentThread. Ciò è utile per gli scenari in cui si dispone di una conversazione esistente con l'agente che si vuole continuare.

# Invoke with an existing AgentThread.
agent.get_response("What is the capital of France?", thread=existing_agent_thread)

Tutti i metodi di chiamata restituiscono anche l'oggetto attivo AgentThread come parte della risposta di invocazione.

1. Se è stato passato un AgentThread oggetto al metodo invoke, l'oggetto restituito AgentThread sarà uguale a quello passato.
2. Se non viene passato alcun AgentThread al metodo invoke, l'oggetto restituito AgentThread sarà un nuovo AgentThread.

L'oggetto restituito AgentThread è disponibile nei singoli elementi di risposta dei metodi invoke insieme al messaggio di risposta.

response = await agent.get_response("What is the capital of France?")
new_thread = response.thread
response_message = response.message

Suggerimento

Per ulteriori informazioni sui thread dell'agente, consultare la sezione sull'architettura dei thread dell'agente.

Due overload del metodo di chiamata consentono di passare un AgentThread parametro. Ciò è utile per gli scenari in cui si dispone di una conversazione esistente con l'agente che si vuole continuare.

// Invoke with an existing AgentThread.
agent.invokeAsync("What is the capital of France?", existingAgentThread);

Questi metodi di chiamata restituiscono anche l'oggetto attivo AgentThread come parte della risposta di invocazione.

1. Se è stato passato un AgentThread oggetto al metodo invoke, l'oggetto restituito AgentThread sarà una nuova istanza con i messaggi precedenti e nuovi.
2. Se non viene passato alcun AgentThread al metodo invoke, l'oggetto restituito AgentThread sarà un nuovo AgentThread.

L'oggetto restituito AgentThread è disponibile nei singoli elementi di risposta dei metodi invoke insieme al messaggio di risposta.

var result = agent.invokeAsync("What is the capital of France?").block().get(0);
var newThread = result.getThread();
var resultMessage = result.getMessage();

Suggerimento

Per ulteriori informazioni sui thread dell'agente, consultare la sezione sull'architettura dei thread dell'agente.

Richiamo con opzioni

Tutti gli overload del metodo di invocazione consentono di passare un parametro AgentInvokeOptions. Questa classe di opzioni consente di specificare eventuali impostazioni facoltative.

// Invoke with additional instructions via options.
agent.InvokeAsync("What is the capital of France?", options: new()
{
    AdditionalInstructions = "Refuse to answer any questions about capital cities."
});

Ecco l'elenco delle opzioni supportate.

Proprietà dell'opzione	Descrizione
Kernel (nucleo del sistema operativo)	Eseguire l'override del kernel predefinito usato dall'agente per questa chiamata.
ArgomentiDelKernel	Eseguire l'override degli argomenti del kernel predefiniti usati dall'agente per questa chiamata.
Istruzioni Aggiuntive	Fornire ulteriori istruzioni oltre al manuale delle istruzioni dell'agente originale, che si applicano solo per questa invocazione.
OnIntermediateMessage	Callback che può ricevere tutti i messaggi completamente formati generati internamente all'agente, inclusi i messaggi di chiamata di funzione e invocazione di funzione. Questa operazione può essere usata anche per ricevere messaggi completi durante una chiamata di streaming.

Richiamo con opzioni

Un sovraccarico del metodo di invocazione consente di passare un parametro AgentInvokeOptions. Questa classe di opzioni consente di specificare eventuali impostazioni facoltative.

// Invoke with additional instructions via options.
agent.invokeAsync("What is the capital of France?",
    null, // null AgentThread
    AgentInvokeOptions.builder()
        .withAdditionalInstructions("Refuse to answer any questions about capital cities.")
        .build()
);

Ecco l'elenco delle opzioni supportate.

Proprietà dell'opzione	Descrizione
Kernel (nucleo del sistema operativo)	Eseguire l'override del kernel predefinito usato dall'agente per questa chiamata.
ArgomentiDelKernel	Eseguire l'override degli argomenti del kernel predefiniti usati dall'agente per questa chiamata.
Istruzioni Aggiuntive	Fornire ulteriori istruzioni oltre al manuale delle istruzioni dell'agente originale, che si applicano solo per questa invocazione.
InvocationContext	Eseguire l'override del contesto di chiamata predefinito usato dall'agente per questa chiamata.

Gestione delle istanze di AgentThread

È possibile creare manualmente un'istanza AgentThread e passarla all'agente su invoke oppure consentire all'agente di creare automaticamente un'istanza AgentThread alla chiamata. Un AgentThread oggetto rappresenta un thread in tutti i relativi stati, inclusi: non ancora creati, attivi ed eliminati.

AgentThread I tipi con un'implementazione lato server verranno creati al primo utilizzo e non devono essere creati manualmente. È tuttavia possibile eliminare un thread usando la AgentThread classe .

// Delete a thread.
await agentThread.DeleteAsync();

# Delete a thread
await agent_thread.delete()

// Delete a thread.
agentThread.deleteAsync().block();

Suggerimento

Per ulteriori informazioni sui thread dell'agente, consultare la sezione sull'architettura dei thread dell'agente.

Passaggi successivi

Configurare gli agenti con plug-in

Esplorare l'agente di completamento della chat