Comprendere il protocollo di attività

Il protocollo attività è un protocollo di comunicazione standard utilizzato da Microsoft in molti SDK, servizi e client Microsoft. Il protocollo attività è utilizzato da Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams e dall'SDK per agenti Microsoft 365. Il protocollo attività definisce la struttura di un Activity e il modo in cui messaggi, eventi e interazioni fluiscono da un canale al tuo codice e in ogni altro punto intermedio. Gli agenti possono connettersi a uno o più canali per interagire con gli utenti e collaborare con altri agenti. Il protocollo attività standardizza il protocollo di comunicazione con qualsiasi client tu stia lavorando, Microsoft e non Microsoft, così non devi creare logica personalizzata per ogni canale.

Che cos'è un'attività?

Un'Activity è un oggetto JSON strutturato che rappresenta qualsiasi interazione tra un utente e il tuo agente. Le attività non sono limitate ai messaggi testuali. Possono includere vari tipi di interazione, come eventi quali la partecipazione o l'abbandono di un utente per client che supportano più utenti, indicatori di digitazione, caricamenti di file, azioni sulle schede e eventi personalizzati definiti dagli sviluppatori.

Ogni attività comprende metadati relativi a:

  • Chi l'ha inviata (da)
  • Chi dovrebbe riceverla (destinatario)
  • Il contesto della conversazione
  • Il canale da cui proviene
  • 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 Attività sono:

Proprietà Descrizione
Id Generato generalmente dal canale se l'attività ha origine da un canale
Type Il tipo determina il significato di un'attività, ad esempio il tipo di messaggio
ChannelID Il ChannelID indica il canale da cui proviene l'attività. Ad esempio: msteams.
From Il mittente dell'attività (che può essere un utente o un agente)
Recipient Il destinatario dell'attività
Text Contenuto del testo del messaggio
Attachment Contenuti ricchi come schede, immagini di file

Accedere ai dati dell'attività

Per completare le azioni sull'oggetto TurnContext, gli sviluppatori devono accedere ai dati contenuti nell'attività.

Puoi trovare una classe TurnContext in ciascun linguaggio supportato dall'SDK per agenti Microsoft 365:

Nota

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

TurnContext è un oggetto importante utilizzato in ogni turno di conversazione nello SDK per agenti Microsoft 365. Fornisce accesso all'attività in arrivo, metodi per inviare risposte, gestione dello stato della conversazione e il contesto necessario per gestire un singolo turno di conversazione. Usalo per mantenere il contesto, inviare risposte appropriate e interagire con i tuoi utenti all'interno del loro client o canale in modo efficace. Ogni volta che il tuo agente riceve una nuova attività da un canale, l'Agents SDK crea una nuova istanza TurnContext e la passa ai tuoi gestori o metodi registrati. Questo oggetto contestuale esiste durante il singolo turno e viene eliminato una volta terminato il turno.

Un turno viene definito come il viaggio di andata e ritorno di un messaggio inviato dal client che completa il percorso fino al codice. Il tuo codice gestisce quei dati e può anche inviare una risposta per completare il turno. Quel viaggio di andata e ritorno può essere suddiviso nei seguenti passaggi:

  1. Attività in arrivo: l'utente invia un messaggio o esegue un'azione che crea un'attività.

  2. Il tuo codice riceve l'attività e l'agente la elabora usando TurnContext.

  3. L'agente invia una o più attività.

  4. Il turno termina e TurnContext viene eliminato.

Accesso ai dati da TurnContext, ad esempio:

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

Questo frammento di codice mostra un esempio di giro 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 classe TurnContext, le informazioni chiave comunemente utilizzate includono:

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

Tipi di attività

Il tipo di attività definisce ciò che il resto dell'attività richiede o si aspetta tra client, utenti e agenti.

tra cui:

  • Messaggio
  • ConversationUpdate
  • Evento
  • Richiamare
  • Digitazione

Messaggio

Un tipo comune di attività è il tipo Messaggio di Activity. Questo tipo di Activity può includere testo, allegati e azioni suggerite.

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 invia una notifica al tuo agente quando i membri si uniscono o abbandonano una conversazione. Non tutti i client supportano questa notifica, ma Microsoft Teams sì.

Il seguente frammento di codice accoglie 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.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Eventi

Il tipo Evento di Activity è un evento personalizzato che i canali o i client usano per inviare dati strutturati al tuo agente. Questi dati non sono predefiniti nella struttura del payload Activity.

È necessario creare un metodo o un gestore di route per il tipo Event specifico. Quindi, gestisci la logica desiderata in base a:

  • Nome: il nome dell'evento o l'identificatore proveniente dal client
  • Valore: il payload dell'evento, che di solito è 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)
});

Richiamare

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

Digitazione

Un tipo di digitazione di Activity è una classificazione dell'attività per indicare che un utente sta digitando in una conversazione. Questa attività è comunemente presente nelle conversazioni tra persone nel client Microsoft Teams, ad esempio. Le attività di digitazione non sono supportate in tutti i client. In particolare, Microsoft 365 Copilot non supporta 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 molteplici metodi per inviare 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

Gli agenti spesso lavorano con allegati che gli utenti (o anche altri agenti) inviano. Il client invia un'attività Message che include un allegato (non è un tipo specifico di attività). Il tuo codice deve gestire la ricezione del messaggio con l'allegato, leggere i metadati e recuperare in sicurezza il file dall'URL fornito dal client. Di solito, sposti il file nella tua archiviazione.

Per ricevere un allegato

Il seguente codice mostra come ricevere un allegato.

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 allegato, il client invia una richiesta autenticata GET per recuperare il contenuto effettivo. Ogni adattatore ha il suo modo per ottenere quei dati. Ad esempio, Teams, OneDrive e così via. È anche importante sapere che quegli URL sono generalmente di breve durata, quindi non dare per scontato che rimangano validi a lungo. Questa limitazione è il motivo per cui spostare i contenuti nel proprio storage è importante se devi fare riferimento ai contenuti in seguito.

Citazioni

È importante sapere che Allegato e Citazione non sono lo stesso tipo di oggetto. I client, come Microsoft Teams, gestiscono le citazioni a modo loro. Utilizzano la proprietà Entità di Activity. Puoi aggiungere citazioni tramite activity.Entities.Add e aggiungere un nuovo oggetto Entity che ha la definizione specifica Citation in base al client utilizzato. Viene serializzato come oggetto JSON che il client poi deserializza in base al modo in cui viene visualizzato nel client. Fondamentalmente, gli allegati sono messaggi e le citazioni possono fare riferimento agli allegati e sono un altro oggetto inviato in Entities del payload Activity.

Considerazioni specifiche del canale

L'SDK per agenti Microsoft 365 è progettato come un Hub che gli sviluppatori utilizzano per creare agenti in grado di lavorare con qualsiasi client, inclusi i client che supportiamo. Fornisce agli sviluppatori gli strumenti per creare il proprio adattatore di canale utilizzando lo stesso framework. Questa architettura offre agli sviluppatori grande flessibilità nella gestione degli agenti e consente ai client di collegarsi all'hub, che può includere uno o più client come Microsoft Teams, Slack e altri.

I diversi canali hanno diverse capacità e limitazioni.

Puoi verificare il canale da cui proviene l'attività ispezionando la proprietà channelId in Activity.

I canali includono dati specifici che non sono conformi al payload Activity generico tra tutti i canali. Puoi accedere a questi dati dalla proprietà TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) eseguendo il cast su variabili per l'uso nel codice.

Le sezioni seguenti sintetizzano le considerazioni da tenere presenti quando si lavora con client comuni.

Microsoft Teams

  • Supporta ricche schede adattive con funzionalità avanzate.
  • Supporta aggiornamenti ed eliminazione dei messaggi.
  • Dispone di dati di canale specifici relativi alle funzionalità di Teams, come le menzioni e le informazioni sulle riunioni.
  • Supporta attività di tipo "invoke" per i moduli attività.

Microsoft 365 Copilot

  • Principalmente incentrato sulle attività di messaggio.
  • Supporta citazioni e riferimenti nelle risposte.
  • Richiede risposte in streaming.
  • Supporto limitato per schede avanzate e schede adattive.

chat Web/DirectLine

chat Web è un protocollo HTTP che gli agenti possono utilizzare per comunicare tramite HTTPS.

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

Canali non Microsoft

Questi canali includono Slack, Facebook e altri.

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

Passaggi successivi

  • Last updated on