Erstellen einer Agent-Konfigurationsoberfläche in Teams

Eine Agent-Konfigurationsoberfläche ermöglicht Benutzern, ihre Agent-Einstellungen direkt innerhalb des Kanal- oder Gruppenchatbereichs nach der Installation einzurichten und neu zu konfigurieren. Dies verbessert die operative Effizienz des Agenten von Anfang an. Durch die Agent-Konfiguration entfällt die Notwendigkeit wiederholter Benutzereingriffe, die zuvor den zeitnahen Nutzen von Apps behinderten und sich auf die Benutzererfahrung auswirkten.

Mit der Erfahrung der Agent-Konfiguration können Sie die kontinuierliche Relevanz und den Wert des Agents sicherstellen, da Benutzer dies tun können:

• Passen Sie den Agent während der Installation an seine spezifischen Workflows und Einstellungen an.
• Konfigurieren Sie die Einstellungen neu, um sie an sich ändernde Anforderungen nach der Installation anzupassen.

Beispielsweise kann ein Agent, der Nachrichtenthemen verfolgt und teilt oder GitHub-Repositorys überwacht, zunächst so eingerichtet werden, dass er den Benutzerabläufen entspricht. Später kann es einfach neu konfiguriert werden, um direkt aus dem Gruppenchat auf neue Themen oder Repositorys zu antworten, wodurch die Inhaltsverwaltung und Interaktion optimiert werden, ohne die Teams-Umgebung verlassen zu müssen. Diese flexible Konfigurationserfahrung verbessert die Benutzererfahrung und Produktivität erheblich, indem sie Agenten nahtlos in den täglichen Betrieb integriert.

Hier ist ein Beispiel, in dem ein Benutzer den Agent zu einem Gruppenchat hinzufügt und ihn dann so konfiguriert, dass er seinen spezifischen Anforderungen entspricht. Der Benutzer konfiguriert dann den Agent neu, um den Status zu ändern.

Konfigurieren

Neu konfigurieren

Informationen zum Konfigurieren des Agenten als Standardlanding-Funktion für eine App, die Bot- und Registerkartenfunktionen unterstützt, finden Sie unter Konfigurieren der Standardlanding-Funktion.

Erstellen einer Agent-Konfigurationsoberfläche

Beim Erstellen der Agent-Konfigurationsoberfläche müssen Sie sicherstellen, dass der Benutzer in der Lage sein muss, einen Agenten bei der ersten Installation zu konfigurieren und ihn jederzeit neu zu konfigurieren.

Gehen Sie folgendermaßen vor, um die Agent-Konfigurationsoberfläche zu erstellen:

1. Aktualisieren des App-Manifests

2. Bot konfigurieren

Aktualisieren des App-Manifests

Aktualisieren Sie in der App-Manifestdatei (früher als Teams-App-Manifest bezeichnet) die fetchTask Eigenschaft unter dem bots.configuration Objekt wie folgt:

"bots": [
    {
      "botId": "${{AAD_APP_CLIENT_ID}}",
     "needsChannelSelector": false,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ],
      "configuration":{
        "groupChat":{
          "fetchTask": true
        },
        "team":{
          "fetchTask": true
        }
      },
      "isNotificationOnly": false
    }
  ],

Weitere Informationen finden Sie unter App-Manifestschema.

Konfigurieren Ihres Agents

Wenn ein Benutzer den Agent im Kanal- oder Gruppenchat installiert, initiiert die fetchTask Eigenschaft in der App-Manifestdatei entweder config.fetch oder config.submit.

Wenn Sie die fetchTask Eigenschaft im App-Manifest auf Folgendes festlegen:

• false: Der Agent ruft weder einen Dialog noch eine adaptive Karte ab. Stattdessen muss der Agent ein statisches Dialogfeld oder eine statische Karte bereitstellen, die beim Aufrufen des Agenten verwendet wird. Weitere Informationen finden Sie unter Dialogfelder.

• true: Der Agent initiiert entweder config.fetch oder config.submit wie definiert. Wenn der Agent aufgerufen wird, können Sie je nach dem in channelData und userdata bereitgestellten Kontext eine adaptive Karte oder einen Dialog zurückgeben.

In der folgenden Tabelle ist der Antworttyp aufgeführt, der den Aufrufanforderungen zugeordnet ist:

• type: "continue": type: "continue" wird verwendet, um eine Fortsetzung eines Dialogfelds oder einer adaptiven Karte innerhalb einer Agentenkonfiguration zu definieren. Wenn der Typ auf continuefestgelegt ist, bedeutet dies, dass der Agent weitere Interaktionen vom Benutzer erwartet, um mit dem Konfigurationsprozess fortzufahren.

  Wenn der Benutzer die Konfiguration übermittelt, wird der config.submit Aufruf ausgelöst. Es liest die Eingabe des Benutzers und gibt eine andere adaptive Karte zurück. Sie können auch die Agent-Konfiguration aktualisieren, um ein Dialogfeld zurückzugeben.

teams.OnTaskFetch(async (context, cancellationToken) =>
{
    var card = new AdaptiveCard
    {
        Body = new List<CardElement>
        {
            new TextBlock("Configure your agent")
            {
                Weight = TextWeight.Bolder
            }
        },
        Actions = new List<Action>
        {
            new SubmitAction
            {
                Title = "Submit"
            }
        }
    };

    return TaskModuleResponse.CreateBuilder()
        .WithType(TaskModuleResponseTypes.Continue)
        .WithTitle("test card")
        .WithHeight("medium")
        .WithWidth("medium")
        .WithCard(TeamsAttachment.CreateBuilder()
            .WithAdaptiveCard(JsonSerializer.SerializeToElement(card))
            .Build())
        .Build();
});

app.OnConfigFetch(async (context) =>
{
    var card = new AdaptiveCard
    {
        Body = new List<CardElement>
        {
            new TextBlock("Configure your agent")
            {
                Weight = TextWeight.Bolder
            }
        },
        Actions = new List<Action>
        {
            new SubmitAction
            {
                Title = "Submit"
            }
        }
    };
    var taskInfo = new TaskInfo
    {
        Title = "test card",
        Width = new Union<int, Size>(600),
        Height = new Union<int, Size>(500),
        Card = new Attachment
        {
            ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
            Content = card
        }
    };
    return new ConfigTaskResponse(
        new ContinueTask(taskInfo)
    );
});

app.on('config.fetch', async ({ activity }) => {
const card = new AdaptiveCard(
 {
   type: 'TextBlock',
   text: 'Configure your agent',
   weight: 'Bolder',
 }
).withActions(
 new SubmitAction().withTitle('Submit')
);
return {
 config: {
   type: 'continue',
   value: {
     card: cardAttachment('adaptive', card),
     height: 500,
     width: 600,
     title: 'test card',
   },
 },
};
});

@app.on_config_open
async def handle_config_open(
 ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
 card = AdaptiveCard(
     body=[
         TextBlock(text="Configure your agent", weight="Bolder")
     ],
     actions=[
         SubmitAction(title="Submit")
     ]
 )

 return ConfigResponse(
     config=TaskModuleContinueResponse(
         value=CardTaskModuleTaskInfo(
             card=card_attachment(AdaptiveCardAttachment(content=card)),
             height=500,
             width=600,
             title="test card",
         )
     )
 )

• type: "auth": Sie können den Benutzer auch bitten, sich als Antwort auf die config.fetch Anforderung zu authentifizieren. Die type: "auth" Konfiguration fordert den Benutzer auf, sich über eine angegebene URL anzumelden, die mit einer gültigen Authentifizierungsseite verknüpft sein muss, die in einem Browser geöffnet werden kann. Die Authentifizierung ist für Szenarien unerlässlich, in denen der Agent die Authentifizierung des Benutzers erfordert. Es stellt sicher, dass die Identität des Benutzers verifiziert wird, während die Sicherheit und personalisierte Erfahrungen innerhalb der Funktionalität des Agenten aufrechterhalten werden.

  Hinweis

  Denn type: "auth" es wird nur die Authentifizierung durch Drittanbieter unterstützt. Einmaliges Anmelden (Single Sign-On, SSO) wird nicht unterstützt. Weitere Informationen zur Authentifizierung durch Dritte finden Sie unter Authentifizierung hinzufügen.

teams.OnTaskFetch(async (context, cancellationToken) =>
{
    return TaskModuleResponse.CreateBuilder()
        .WithType(TaskModuleResponseTypes.Continue)
        .WithTitle("Sign in to this app")
        .WithUrl("https://example.com/auth")
        .Build();
});

app.OnConfigFetch(async (context) =>
{
    return new ConfigAuthResponse(
        new ConfigAuth
        {
            SuggestedActions = new SuggestedActions
            {
                Actions = new List<CardAction>
                {
                    new CardAction
                    {
                        Type = "openUrl",
                        Value = "https://example.com/auth",
                        Title = "Sign in to this app"
                    }
                }
            }
        }
    );
});

app.on('config.fetch', async ({ activity }) => {
return {
 config: {
   type: 'auth',
   suggestedActions: {
     actions: [
       {
         type: 'openUrl',
         value: 'https://example.com/auth',
         title: 'Sign in to this app',
       },
     ],
   },
 },
};
});

@app.on_config_open
async def handle_config_open(
 ctx: ActivityContext[ConfigFetchInvokeActivity]
) -> ConfigInvokeResponse:
 return ConfigResponse(
     config=ConfigAuth(
         suggested_actions=SuggestedActions(
             to=[],
             actions=[
                 CardAction(
                     type="openUrl",
                     value="https://example.com/auth",
                     title="Sign in to this app",
                 )
             ],
         )
     )
 )

• type="message": Wenn der Typ auf Nachricht festgelegt ist, zeigt dies an, dass der Agent eine einfache Nachricht an den Benutzer zurücksendet, die das Ende der Interaktion anzeigt oder Informationen bereitstellt, ohne dass weitere Eingaben erforderlich sind.

teams.OnTaskSubmit(async (context, cancellationToken) =>
{
    return TaskModuleResponse.CreateBuilder()
        .WithType(TaskModuleResponseTypes.Message)
        .WithMessage("You have chosen to finish setting up agent")
        .Build();
});

app.OnConfigSubmit(async (context) =>
{
    return new ConfigTaskResponse(
        new MessageTask("You have chosen to finish setting up agent")
    );
});

app.on('config.submit', async ({ activity, send }) => {
return {
 config: {
   type: 'message',
   value: 'You have chosen to finish setting up agent',
 },
};
});

@app.on_config_submit
async def handle_config_submit(
 ctx: ActivityContext[ConfigSubmitInvokeActivity]
) -> ConfigInvokeResponse:
 return ConfigResponse(
     config=TaskModuleMessageResponse(
         value="You have chosen to finish setting up agent",
     )
 )

Wenn ein Benutzer den Agent neu konfiguriert, wird config.fetch die fetchTask Eigenschaft in der App-Manifestdatei in der Agentlogik initiiert. Der Benutzer kann die Agent-Einstellungen nach der Installation auf zwei Arten neu konfigurieren:

• @mention Der Agent im Bereich zum Verfassen von Nachrichten. Wählen Sie die Option Einstellungen aus, die über dem Bereich zum Verfassen von Nachrichten angezeigt wird. Ein Dialogfeld wird angezeigt, aktualisieren oder ändern Sie die Konfigurationseinstellungen des Agenten.

  

• Fahren Sie mit der Maus über den Agenten, um die Agentprofil-Karte zu öffnen. Um die Konfigurationseinstellungen des Agenten zu aktualisieren oder zu ändern, wählen Sie das Symbol "Einstellungen" auf der Agentprofil-Karte aus.

  

Bewährte Methoden

• Wenn Sie eine individuelle Konfiguration Ihres Agents auf Kanalebene wünschen, stellen Sie sicher, dass Sie die Konfiguration gemäß dem Kanal verfolgen. Konfigurationsdaten werden nicht gespeichert, und die Aufrufnutzlast enthält die ausreichenden channelData.

• Stellen Sie einen klaren und benutzerfreundlichen Dialog bereit, in dem der Benutzer aufgefordert wird, die erforderlichen Informationen einzugeben, damit der Agent ordnungsgemäß funktioniert, z. B. eine URL, ein Bereichspfad oder ein Dashboard-Link.

• Vermeiden Sie das Senden mehrerer Benachrichtigungen oder Konfigurationsanforderungen nach der Installation, da dies die Benutzer verwirren könnte.

Codebeispiel

Siehe auch

• Erstellen von Agents für Teams
• Adaptive Karten