Informazioni sul protocollo di attività

Il protocollo Activity è il protocollo di comunicazione e il protocollo standard usati in Microsoft in molti SDK, servizi e client Microsoft. Sono inclusi Microsoft 365 Copilot, Microsoft Copilot Studio e Microsoft 365 Agents SDK. Il protocollo Activity definisce la struttura di un oggetto Activity e il modo in cui i messaggi, gli eventi e le interazioni fluiscono dal canale, al tuo codice e in tutte le parti intermedie. Gli agenti possono connettersi a uno o più canali per interagire con gli utenti e lavorare con altri agenti. Il protocollo Activity standardizza il protocollo di comunicazione tra qualsiasi client con cui si lavora, inclusi i client Microsoft e di terze parti, quindi non è necessario creare logica personalizzata per ogni canale usato.

Che cos'è un'attività?

Un Activity oggetto è un oggetto JSON strutturato che rappresenta qualsiasi interazione tra un utente e l'agente. Le attività non sono solo messaggi basati su testo, ma possono includere vari tipi di interazione, tra cui eventi come l'aggiunta o l'uscita di un utente in sistemi che supportano più utenti, indicatori di digitazione, caricamenti di file, azioni su carta e eventi personalizzati progettati dagli sviluppatori.

Ogni attività include i metadati relativi a:

Chi l'ha inviata (da chi)
Chi deve riceverlo (destinatario)
Contesto della conversazione
Il canale da cui ha avuto origine
Tipo di interazione
Dati del payload

Schema dell'attività - Proprietà chiave

Questa specifica definisce il protocollo Attività: Protocollo attività - Attività. Alcune delle proprietà chiave definite nel protocollo Activity sono:

Proprietà	Description
`Id`	In genere è generato dal canale se proviene dallo stesso.
`Type`	Il tipo controlla il significato di un'attività, ad esempio il tipo di messaggio
`ChannelID`	Fa `ChannelID` riferimento al canale da cui ha avuto origine l'attività. Ad esempio: `msteams`.
`From`	Il mittente dell'attività (che può essere un utente o un agente)
`Recipient`	Destinatario previsto dell'attività
`Text`	Contenuto del testo del messaggio
`Attachment`	Contenuto avanzato, ad esempio schede, immagini di file

Accedere ai dati dell'attività

Gli sviluppatori devono accedere ai dati all'interno dell'attività per completare le azioni dall'oggetto TurnContext .

È possibile trovare una TurnContext classe in ogni versione della lingua di Microsoft 365 Agents SDK:

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Annotazioni

I frammenti di codice in questo articolo usano C#. La sintassi e la struttura API per le versioni JavaScript e Python sono simili.

TurnContext è un oggetto importante usato in ogni turno di conversazione in Microsoft 365 Agents SDK. Fornisce l'accesso all'attività in ingresso, ai metodi per l'invio di risposte, la gestione dello stato della conversazione e il contesto necessario per gestire un singolo turno di conversazione. Viene usato per mantenere il contesto, inviare risposte appropriate e interagire con gli utenti nel proprio client/canale in modo efficace. Ogni volta che l'agente riceve una nuova attività da un canale, Agents SDK crea una nuova TurnContext istanza e la passa ai gestori/metodi registrati. Questo oggetto di contesto esiste durante il singolo turno e quindi eliminato una volta terminato il turno.

Un turno viene definito come l'andata e ritorno di un messaggio inviato dal client che raggiunge il tuo codice; il codice gestisce i dati e può facoltativamente inviare una risposta per completare il processo. Il round trip può essere suddiviso in:

Attività in ingresso: l'utente invia un messaggio o esegue un'azione che crea un'attività.
Il codice riceve l'attività e l'agente lo elabora usando TurnContext.
L'agente invia una o più attività.
Il turno termina e TurnContext viene eliminato.

Accedere ai dati da TurnContext, ad esempio:

var messageText = turnContext.Activity.Text
var channelID = turnContext.Activity.ChannelId

Questo frammento di codice mostra un esempio di turno completo:

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

All'interno della TurnContext classe, le informazioni sulle chiavi comunemente usate includono:

Attività: il modo principale per ottenere informazioni dall'attività
Adapter: adattatore di canale che ha creato l'attività
TurnState: stato del turno

Tipi di attività

Il tipo di un'attività è importante perché definisce ciò che è necessario o previsto nel resto dell'attività tra client, utenti e agenti.

Message

Un tipo comune di attività è il tipo di messaggio di Activity, che può includere testo, allegati e azioni suggerite per denominare alcuni usi comuni per questo tipo.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

ConversationUpdate

Il tipo ConversationUpdate di Activity notifica all'agente quando i membri si uniscono o lasciano una conversazione. Non tutti i client supportano questa funzionalità, un client degno di nota che lo fa è Microsoft Teams.

Il frammento di codice seguente saluta i nuovi membri in una conversazione:

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Events

Il tipo di evento di Activity è un evento personalizzato che consente ai canali o ai client di inviare dati strutturati al tuo agente, che non è predefinito nella struttura del Activity payload.

È necessario creare un gestore di metodo/route per il tipo specifico Event e quindi gestire la logica desiderata in base a:

Name - nome dell'evento o identificatore dal client Value - Payload dell'evento che in genere è un oggetto JSON

agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>)
{
    var eventName = turnContext.Activity.Name
    var eventValue = turnContext.Activity.Value

    // custom event (E.g. a switch on eventName)
}

Invoke

Un tipo Invoke di Activity è un tipo specifico di attività che un client sta chiamando in un agente per eseguire un comando o un'operazione e non solo un messaggio. Esempi di questi tipi di attività sono comuni in Microsoft Teams per task/fetch e task/submit. Non tutti i canali supportano questi tipi di attività.

Typing

Un tipo di digitazione di Activity è una classificazione dell'attività per indicare che un utente sta digitando in una conversazione. Questo è comunemente osservato tra conversazioni umane nel client di Microsoft Teams, per esempio. Le attività di digitazione non sono supportate in ogni client e in particolare Microsoft 365 Copilot non supporta le attività di digitazione.

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken)

Creare e inviare attività

Per inviare risposte, "TurnContext" fornisce più metodi per l'invio di risposte all'utente.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken) // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken) // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken) // send multiple activities in an Activity array
}

Utilizzare gli allegati

È comune che gli agenti funzionino con allegati che sono stati inviati dagli utenti (o anche da altri agenti). Il client invia un'attività Message che include un allegato (non è un tipo specifico di attività) e il codice deve gestire la ricezione del messaggio con l'allegato, leggere i metadati e recuperare in modo sicuro il file dall'URL fornito dal client. In genere è consigliabile spostare il file nella propria risorsa di archiviazione.

Per ricevere un allegato

Il codice seguente illustra come ricevere e allegare

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count >0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        }
    }
}

In genere, per ricevere il documento sull'allegato, il client invia una richiesta autenticata GET per recuperare il contenuto effettivo. Ogni adattatore ha il proprio modo di ottenere tali dati, ad esempio Teams, OneDrive e così via. È anche importante sapere che questi URL sono in genere di breve durata e quindi non presupporre che rimangano lì, che è il motivo per cui passare alla propria risorsa di archiviazione è importante se è necessario fare riferimento a questo in un secondo momento.

Citazioni

È importante sapere che Attachment e Citation non sono dello stesso tipo di oggetto. Le citazioni sono gestite dai client, come Microsoft Teams, in modi specifici e usano la proprietà Entities di Activity e possono essere aggiunte con activity.Entities.Add per aggiungere un nuovo Entity oggetto con una definizione specifica Citation in base al client. Viene serializzato come oggetto JSON che il client deserializza in base al modo in cui esegue il rendering nel client. Fondamentalmente, gli allegati sono messaggi e le citazioni possono fare riferimento agli allegati e sono un altro oggetto inviato nel EntitiesActivity payload.

Considerazioni specifiche sul canale

Microsoft 365 Agents SDK è stato creato come "Hub" che consente agli sviluppatori di creare agenti che possono lavorare con qualsiasi client, inclusi i client che supportiamo, e fornisce agli sviluppatori gli strumenti per costruire il proprio adattatore di canale utilizzando lo stesso framework. Questo offre agli sviluppatori un'ampiezza quando si tratta di agenti e offre estendibilità ai client per connettersi a tale hub, che può essere uno o più client come Microsoft Teams, Slack e altro ancora.

Diversi canali hanno funzionalità e limitazioni diverse e di seguito è riportato un riepilogo delle considerazioni relative all'uso di client comuni.

È possibile controllare il canale da cui è stata ricevuta l'attività esaminando la channelId proprietà in Activity.

I canali includono dati specifici che non sono conformi al payload generico Activity in tutti i canali ed è possibile accedervi da TurnContext.Activity.ChannelData e, in particolare, eseguirne il cast alle variabili da usare nel codice.

Microsoft Teams

Supporta ricche schede adattive con funzionalità avanzate
Supporta gli aggiornamenti e le eliminazioni dei messaggi
Dispone di dati di canale specifici per le funzionalità di Teams (menzioni, informazioni sulle riunioni e così via)
Supporta le attività di invocazione per i moduli di attività

Microsoft 365 Copilot

Principalmente incentrato sulle attività dei messaggi
Supporta citazioni e riferimenti nelle risposte
Richiede risposte di streaming
Supporto limitato per schede ricche/schede adattive

WebChat/DirectLine

Web Chat è un protocollo HTTP usato per gli agenti per comunicare tramite HTTPS

Supporto completo per tutti i tipi di attività
Supporta i dati del canale personalizzati

Canali di terze parti

Tra cui Slack, Facebook e altro ancora.

Potrebbe avere un supporto limitato per determinati tipi di attività
Il rendering delle schede potrebbe essere diverso o non supportato
Controllare sempre la documentazione specifica del canale

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-21