Comprensione del protocollo delle attività

Il protocollo di attività è un protocollo di comunicazione standard usato in Microsoft in molti SDK, servizi e client Microsoft. Il protocollo di attività viene usato da Microsoft 365 Copilot, Microsoft Copilot Studio e dall'Managed Disks. Il protocollo di attività definisce la struttura di un'attività Activity e come i messaggi, gli eventi e le interazioni passano da un canale al tuo codice e tutto il resto nel mezzo. Gli agenti possono connettersi a uno o più canali per interagire con gli utenti e lavorare con altri agenti. Il protocollo attività standardizza il protocollo di comunicazione con qualsiasi client in uso, inclusi i client Microsoft e non Microsoft, in modo che non sia necessario creare logica personalizzata per ogni canale.

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 limitate ai messaggi basati su testo. Possono includere vari tipi di interazione, ad esempio eventi come l'aggiunta o l'uscita di un utente per i client che supportano più utenti, indicatori di digitazione, caricamenti di file, azioni scheda ed eventi personalizzati che gli sviluppatori progettano.

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 in Activity Protocol 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 delle attività

Per completare le azioni dall'oggetto TurnContext , gli sviluppatori devono accedere ai dati all'interno dell'attività.

È possibile trovare una TurnContext classe in ogni versione della lingua di Managed Disks:

Note

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

Il TurnContext è un oggetto importante usato in ogni conversazione nel Managed Disks. 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. Usarlo per mantenere il contesto, inviare risposte appropriate e interagire con gli utenti nel client o nel 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 o ai metodi registrati. Questo oggetto di contesto esiste durante il singolo turno e viene quindi eliminato una volta terminato il turno.

Un turn viene definito come il viaggio di andata e ritorno di un messaggio inviato dal client che completa il percorso fino al codice. Il codice gestisce i dati e può facoltativamente inviare una risposta per completare il turno. Questo round trip può essere suddiviso nei passaggi seguenti:

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

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

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

  4. Il turno termina e l'oggetto 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à definisce ciò che il resto dell'attività richiede o prevede tra client, utenti e agenti.

Include:

  • Messaggio
  • AggiornamentoConversazione
  • Evento
  • Richiamo
  • Typing

Messaggio

Un tipo comune di attività è il tipo di messaggio di Activity. Questo Activity tipo 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);
});

AggiornamentoConversazione

Il tipo ConversationUpdate di Activity notifica all'agente quando i membri si uniscono o lasciano una conversazione. Non tutti i client supportano questa notifica, ma Microsoft Teams lo fa.

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

Eventi

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

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

  • Nome: nome o identificatore dell'evento dal client
  • Valore: 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)
});

Richiamo

Un tipo Invoke di Activity è un tipo specifico di attività che un client chiama in un agente per eseguire un comando o un'operazione. 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. Questa attività è comunemente osservata nelle conversazioni tra esseri umani nel client di Microsoft Teams, ad esempio. Le attività di digitazione non sono supportate in ogni client. 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, fornisce TurnContextpiù 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

Gli agenti spesso usano allegati che gli utenti (o anche altri agenti) inviano. Il client invia un'attività che include un Message allegato (non è un tipo specifico di attività). 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, il file viene spostato nella propria risorsa di archiviazione.

Per ricevere un allegato

Nel codice seguente viene illustrato 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 per l'allegato, il client invia una richiesta autenticata per recuperare il contenuto effettivo GET . 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 gli URL rimangano validi per molto tempo. Questa limitazione è il motivo per cui il passaggio alla propria risorsa di archiviazione è importante se è necessario fare riferimento al contenuto in un secondo momento.

Citazioni

È importante sapere che Attachment e Citation non sono dello stesso tipo di oggetto. I client, come Microsoft Teams, gestiscono le citazioni nei propri modi. Usano la proprietà Entities dell'oggetto Activity. È possibile aggiungere citazioni con activity.Entities.Add e aggiungere un nuovo Entity oggetto con la definizione specifica Citation in base al client. Viene serializzato come oggetto JSON che il client deserializza in base alla modalità di 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

Il Managed Disks viene creato come "Hub" usato dagli sviluppatori per creare agenti che possono funzionare con any client, inclusi i client supportati. Fornisce agli sviluppatori gli strumenti per creare il proprio adapter di canale usando lo stesso framework. Questa architettura 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.

È 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. È possibile accedere a questi dati dalla TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) proprietà eseguendo il cast su variabili per l'uso nel codice.

Le sezioni seguenti riassumono gli aspetti da considerare quando si lavora con client comuni.

Microsoft Teams

  • Supporta Schede adattive ricche di funzionalità avanzate.
  • Supporta gli aggiornamenti e le eliminazioni dei messaggi.
  • Include dati di canale specifici per le funzionalità di Teams, ad esempio menzioni e informazioni sulla riunione.
  • Supporta le attività di invocazione per i moduli di attività.

Microsoft 365 Copilot

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

chat Web/DirectLine

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

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

Canali non Microsoft

Questi canali includono Slack, Facebook e altro ancora.

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

Passaggi successivi

  • Last updated on