Graph-Anrufbot

Überblick

Dieser Ansatz macht den Agenten zu einer anrufbaren Teams-Identität. Ein Nutzer sucht ihn per Namen und ruft ihn im 1:1-Gespräch an. Der Agent antwortet in Echtzeit – ohne Telefonnummer, PSTN oder Communications Credits. Dies ist der einzige Ansatz, bei dem ein Anruf per Namen möglich ist, und der aufwendigste im Betrieb.

Er nutzt einen Microsoft Graph-Echtzeit-Medienbot (die Cloud Communications Calling-Plattform). Das Media SDK (Microsoft.Skype.Bots.Media) unterstützt nur .NET auf Windows Server – für Roh-Audio in Teams-Anrufen gibt es keinen Linux- oder Nicht-.NET-Weg.

Funktionsweise

Der Bot antwortet mit anwendungsgehosteten Medien, empfängt 50 Audio-Frames pro Sekunde (20 ms PCM mit 16 kHz), verbindet sie über einen WebSocket mit dem ElevenLabs-Agenten und streamt das Audio des Agenten zurück in den Anruf.

Anforderungen

1. Eine Azure Bot-Registrierung + App (Entra-App-Registrierung).
2. Graph-Anwendungsberechtigungen mit Admin-Einwilligung: Calls.AccessMedia.All (Rohmedien) plus Calls.Initiate.All.
3. Eine Windows Server-VM (≥ 2 physische Kerne – z. B. Standard_D4s_v3) mit öffentlicher IP und offenen Medienports.
4. Ein von einer CA signiertes TLS-Zertifikat auf einer öffentlichen FQDN für den Medien-/Signalisierungsendpunkt (die Medienplattform lehnt selbstsignierte Zertifikate ab).
5. Ein ElevenLabs-Agent, der auf beiden Seiten auf PCM 16000 Hz eingestellt ist: TTS-Ausgabeformat im Tab Voice, Audioformat für Nutzereingaben im Tab Advanced.

Berechtigungen und Rollen

Schritt 1 – Bot + Graph-Berechtigungen registrieren

Erstellen Sie eine App-Registrierung und einen daran gebundenen Azure Bot. Erteilen und genehmigen Sie anschließend die Anrufberechtigungen (für die Einwilligung benötigen Sie Global Admin / Privileged Role Admin):

APPID=$(az ad app create --display-name "ElevenLabs Teams Agent" \
  --sign-in-audience AzureADMyOrg --query appId -o tsv)
az ad sp create --id "$APPID"
# create a client secret and record it
az ad app credential reset --id "$APPID" --display-name bot --query password -o tsv
# Azure Bot bound to the app
az bot create --resource-group $RG --name el-teams-agent-bot \
  --app-type SingleTenant --appid "$APPID" --tenant-id $TENANT \
  --endpoint "https://YOUR_FQDN/api/messages" --sku S1

Erteilen Sie die beiden Graph-Anwendungsrollen und die Admin-Einwilligung (erfordert Global Admin / Privileged Role Admin). Prüfen Sie anschließend, ob die Zuweisungen erfolgt sind:

# Graph app roles: Calls.AccessMedia.All, Calls.Initiate.All
az ad app permission add --id "$APPID" --api 00000003-0000-0000-c000-000000000000 \
  --api-permissions a7a681dc-756e-4909-b988-f160edc6655f=Role \
    284383ee-7f6e-4e40-a2a8-e85dcb029101=Role
az ad app permission admin-consent --id "$APPID"
# Verify — should print both role ids
az rest --method GET \
  --url "https://graph.microsoft.com/v1.0/servicePrincipals(appId='$APPID')/appRoleAssignments" \
  --query "value[].appRoleId" -o tsv

GRAPH_SP=$(az ad sp show --id 00000003-0000-0000-c000-000000000000 --query id -o tsv)
BOT_SP=$(az ad sp show --id "$APPID" --query id -o tsv)
for ROLE in a7a681dc-756e-4909-b988-f160edc6655f 284383ee-7f6e-4e40-a2a8-e85dcb029101; do
  az rest --method POST \
    --url "https://graph.microsoft.com/v1.0/servicePrincipals/$GRAPH_SP/appRoleAssignedTo" \
    --body "{\"principalId\": \"$BOT_SP\", \"resourceId\": \"$GRAPH_SP\", \"appRoleId\": \"$ROLE\"}"
done

Prüfen Sie im Portal im Entra Admin Center unter App registrations → Ihre App → API permissions: Beide Berechtigungen sollten mit grünen Häkchen als Granted angezeigt werden.

Schritt 2 – Windows-VM, Zertifikat und Ports bereitstellen

az vm create -g $RG -n teams-media-bot --image Win2022Datacenter \
  --size Standard_D4s_v3 --admin-username azureuser --admin-password '<strong-pw>' \
  --public-ip-sku Standard --public-ip-address-dns-name elevenmediabot
az vm open-port -g $RG -n teams-media-bot --port 80,443,8445,9441 --priority 300

Auf der VM (der native Code der Medienplattform benötigt diese Komponenten – Windows Server enthält sie standardmäßig nicht):

# VC++ runtime + Media Foundation feature (required by NativeMedia.dll)
choco install -y vcredist140
Install-WindowsFeature Server-Media-Foundation
# CA cert for the VM's FQDN via win-acme (HTTP-01), then import to LocalMachine\My
& wacs.exe --target manual --host <vm-fqdn>.cloudapp.azure.com `
  --validation selfhosting --store pfxfile --pfxfilepath C:\bot\certs --accepttos

Öffnen Sie dieselben Ports in der Windows-Firewall und notieren Sie sich den Fingerabdruck des Zertifikats. Der Bot bindet Kestrel (443 + einen Benachrichtigungsport) und die Medienplattform (8445) daran.

Schritt 3 – Bot erstellen und ausführen

Starten Sie mit Microsofts microsoft-graph-comms-samples PublicSamples/EchoBot. Es zielt auf net6.0 und wird mit dem .NET SDK erstellt (keine Visual Studio Build Tools erforderlich):

git clone --depth 1 https://github.com/microsoftgraph/microsoft-graph-comms-samples.git C:\bot\samples
cd C:\bot\samples\Samples\PublicSamples\EchoBot\src
dotnet build EchoBot.sln -c Release

Konfigurieren Sie den Abschnitt AppSettings in appsettings.json mit Ihrer AadAppId, Ihrem AadAppSecret, ServiceDnsName/MediaDnsName (der FQDN der VM), CertificateThumbprint und den Ports (Anrufe 443, Benachrichtigungen 9441, Medien 8445). Fügen Sie für die folgende ElevenLabs-Bridge zwei Einstellungen hinzu: ElevenLabsAgentId und ElevenLabsOrigin (wss://api.elevenlabs.io oder Ihren Residency-Host). Führen Sie sie als geplante Windows-Aufgabe bzw. Dienst aus, damit sie Neustarts übersteht.

$s = New-ScheduledTaskSettingsSet -ExecutionTimeLimit (New-TimeSpan -Seconds 0) `
  -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) -StartWhenAvailable
Set-ScheduledTask -TaskName EchoBot -Settings $s

Echo durch ElevenLabs ersetzen

Die Audioschnittstelle von EchoBot ist klar: SpeechService.AppendAudioBuffer(in) und ein OnSendMediaBufferEventArgs(out)-Ereignis. Ersetzen Sie den Azure-Speech-Body durch eine ElevenLabs-Agent-WebSocket-Bridge mit derselben Oberfläche:

public class SpeechService
{
    private readonly AppSettings _settings;
    private readonly ILogger _logger;
    private ClientWebSocket _ws;
    private bool _started;
    private bool _connecting;
    public event EventHandler<MediaStreamEventArgs> SendMediaBuffer; // agent audio -> call
    public event EventHandler FlushMedia;                            // barge-in: drop queued audio
    public SpeechService(AppSettings settings, ILogger logger) { _settings = settings; _logger = logger; }
    // Caller audio -> ElevenLabs
    public async Task AppendAudioBuffer(AudioMediaBuffer buffer)
    {
        if (!_started)
        {
            if (_connecting) return;            // a connect attempt is already in flight
            _connecting = true;
            try { await Connect(); _started = true; }
            catch (Exception ex) { _logger.Error(ex, "ElevenLabs connect failed; retry on next frame"); return; }
            finally { _connecting = false; }
        }
        if (_ws?.State != WebSocketState.Open || buffer.Length <= 0) return;
        var pcm = new byte[buffer.Length];
        Marshal.Copy(buffer.Data, pcm, 0, (int)buffer.Length);
        var msg = JsonSerializer.Serialize(new { user_audio_chunk = Convert.ToBase64String(pcm) });
        await _ws.SendAsync(Encoding.UTF8.GetBytes(msg), WebSocketMessageType.Text, true, default);
    }
    private async Task Connect()
    {
        _ws = new ClientWebSocket();
        // ElevenLabsOrigin: wss://api.elevenlabs.io, or a residency host (.eu./.in./.sg.)
        var url = $"{_settings.ElevenLabsOrigin}/v1/convai/conversation?agent_id={_settings.ElevenLabsAgentId}";
        await _ws.ConnectAsync(new Uri(url), default);
        await _ws.SendAsync(Encoding.UTF8.GetBytes(
            JsonSerializer.Serialize(new { type = "conversation_initiation_client_data" })),
            WebSocketMessageType.Text, true, default);
        _ = Task.Run(ReceiveLoop);
    }
    private async Task ReceiveLoop()
    {
        var buf = new byte[32768]; var sb = new StringBuilder();
        while (_ws.State == WebSocketState.Open)
        {
            sb.Clear(); WebSocketReceiveResult r;
            do { r = await _ws.ReceiveAsync(buf, default); sb.Append(Encoding.UTF8.GetString(buf, 0, r.Count)); }
            while (!r.EndOfMessage);
            using var doc = JsonDocument.Parse(sb.ToString());
            var type = doc.RootElement.GetProperty("type").GetString();
            if (type == "audio")            // ElevenLabs audio -> call
                Emit(Convert.FromBase64String(doc.RootElement
                    .GetProperty("audio_event").GetProperty("audio_base_64").GetString()));
            else if (type == "ping")
                await _ws.SendAsync(Encoding.UTF8.GetBytes(JsonSerializer.Serialize(new {
                    type = "pong", event_id = doc.RootElement.GetProperty("ping_event").GetProperty("event_id").GetInt32() })),
                    WebSocketMessageType.Text, true, default);
            else if (type == "interruption")  // barge-in: drop any agent audio still queued
                FlushMedia?.Invoke(this, EventArgs.Empty);
        }
    }
    // slice PCM into 20 ms / 640-byte frames the media platform expects
    private void Emit(byte[] pcm)
    {
        var all = new List<AudioMediaBuffer>(); long tick = DateTime.Now.Ticks;
        for (int off = 0; off < pcm.Length; off += 640)
        {
            var frame = new byte[640];
            Array.Copy(pcm, off, frame, 0, Math.Min(640, pcm.Length - off));
            all.AddRange(Utilities.CreateAudioMediaBuffers(frame, tick, _logger));
            tick += 20 * 10000;
        }
        if (all.Count > 0) SendMediaBuffer?.Invoke(this, new MediaStreamEventArgs { AudioMediaBuffers = all });
    }
}

Beide Seiten verwenden PCM mit 16 kHz und Mono. Daher ist es ein Base64-Passthrough – stellen Sie den Agenten auf pcm_16000 ein. Bei einer ElevenLabs-interruption (Unterbrechung) löst die Bridge FlushMedia aus. Verbinden Sie dies mit Ihrem Medienstream, damit ausstehende AudioMediaBuffer verworfen werden. Andernfalls spricht der Agent weiter über den Anrufer hinweg. Die vollständige Nachrichtenreferenz finden Sie in der WebSocket-Dokumentation. Das Auflegen am Anrufende und die Warmübergabe werden in den folgenden Abschnitten behandelt.

Schritt 4 – In Teams anrufbar machen

1. Aktivieren Sie Calling im Teams-Kanal des Azure Bots und setzen Sie den Calling-Webhook auf https://YOUR_FQDN/api/calling:

   az bot msteams create -g $RG -n el-teams-agent-bot \
     --enable-calling --calling-web-hook "https://YOUR_FQDN/api/calling"

   Im Portal finden Sie dies unter Ihrer Azure-Bot-Ressource → Channels → Microsoft Teams → Tab Calling:

   

   

2. Erstellen Sie ein Teams-App-Manifest mit bots[0].supportsCalling: true und der App-ID des Bots und laden Sie es quer (Apps → Manage your apps → Upload a custom app), oder veröffentlichen Sie es ohne Benutzeroberfläche organisationsweit: New-TeamsApp -DistributionMethod organization -Path ./bot-app.zip (MicrosoftTeams-PowerShell-Modul).

Suchen Sie die App in Teams per Namen und rufen Sie sie an – der Bot antwortet und der ElevenLabs-Agent spricht.

Textchat (derselbe Bot)

Derselbe Azure Bot kann in Teams auch auf Text antworten — Nutzer können den Agenten also anrufen oder mit ihm chatten. Anrufe und Nachrichten sind unabhängige Kanäle des Bots: Der Calling-Webhook verarbeitet Sprache, und ein Bot-Framework-Messaging-Endpunkt (/api/messages) verarbeitet Chats.

Richten Sie den Messaging-Endpunkt des Bots auf den Host, der ihn bereitstellt (den Medienbot oder einen anderen Dienst — es muss nicht die Windows-VM sein):

az bot update -g $RG -n el-teams-agent-bot --endpoint "https://YOUR_FQDN/api/messages"

Implementieren Sie den Endpunkt mit dem Bot Framework SDK und leiten Sie jede Nachricht im Textmodus über denselben für Sprache verwendeten Conversation-WebSocket an den Agenten weiter — senden Sie ein user_message-Event und lesen Sie das agent_response-Event. Aktivieren Sie zuerst das Feld erste Nachricht in den Override-Einstellungen des Agenten — der folgende Code überschreibt es mit einem leeren Wert, sodass die Antwort auf die Nachricht des Nutzers und nicht die Begrüßung des Agenten zurückgegeben wird:

public class ChatBot : ActivityHandler
{
    private readonly AppSettings _settings;
    public ChatBot(AppSettings settings) => _settings = settings;
    protected override async Task OnMessageActivityAsync(
        ITurnContext<IMessageActivity> turn, CancellationToken ct)
    {
        var reply = await AskAgent(turn.Activity.Text, ct);
        await turn.SendActivityAsync(MessageFactory.Text(reply), ct);
    }
    private async Task<string> AskAgent(string text, CancellationToken ct)
    {
        using var ws = new ClientWebSocket();
        var url = $"{_settings.ElevenLabsOrigin}/v1/convai/conversation?agent_id={_settings.ElevenLabsAgentId}";
        await ws.ConnectAsync(new Uri(url), ct);
        // Suppress the agent's greeting: with no override, the first agent_response is the
        // configured first message, not the answer to this user_message.
        await Send(ws, new
        {
            type = "conversation_initiation_client_data",
            conversation_config_override = new { agent = new { first_message = "" } },
        }, ct);
        await Send(ws, new { type = "user_message", text }, ct);
        var buf = new byte[16384]; var sb = new StringBuilder();
        while (ws.State == WebSocketState.Open)
        {
            sb.Clear(); WebSocketReceiveResult r;
            do { r = await ws.ReceiveAsync(buf, ct); sb.Append(Encoding.UTF8.GetString(buf, 0, r.Count)); }
            while (!r.EndOfMessage);
            using var doc = JsonDocument.Parse(sb.ToString());
            switch (doc.RootElement.GetProperty("type").GetString())
            {
                case "agent_response":
                    return doc.RootElement.GetProperty("agent_response_event")
                              .GetProperty("agent_response").GetString();
                case "ping":
                    await Send(ws, new { type = "pong", event_id = doc.RootElement
                        .GetProperty("ping_event").GetProperty("event_id").GetInt32() }, ct);
                    break;
            }
        }
        return "Sorry, I couldn't reach the agent.";
    }
    private static Task Send(ClientWebSocket ws, object msg, CancellationToken ct) =>
        ws.SendAsync(Encoding.UTF8.GetBytes(JsonSerializer.Serialize(msg)),
            WebSocketMessageType.Text, true, ct);
}

Registrieren Sie ihn auf die übliche Weise (einen CloudAdapter, den Bot über AddTransient<IBot, ChatBot>() und einen /api/messages-Controller) und fügen Sie dem Bot-Eintrag des Manifests Chat-Bereiche hinzu:

"bots": [
  { "botId": "YOUR_APP_ID", "supportsCalling": true, "scopes": ["personal", "team", "groupChat"] }
]

Anruf beenden

Wenn ElevenLabs die Conversation beendet (das Tool Anruf beenden schließt den WebSocket), legen Sie die Teams-Verbindung auf:

await this.Call.DeleteAsync(); // after a short delay so the goodbye audio finishes

Warme Übergabe an einen Mitarbeiter

Der Agent löst ein benutzerdefiniertes transfer_to_human-Client-Tool aus; der Bot lädt einen Teams-Nutzer in den laufenden Anruf ein (beratendes Hinzufügen) und tritt dann zurück:

var target = new IdentitySet { User = new Identity { Id = humanObjectId } };
await this.Call.Participants.InviteAsync(target, replacesCallId: null);
// suppress the end-call hangup while transferring, and mute the bot

Fehlerbehebung

Nützliche Links

• Übersicht zu Anruf- und Besprechungsbots
• Konzepte für Echtzeitmedien
• Einen Calling-Bot registrieren
• microsoft-graph-comms-samples (EchoBot)
• call: Übergabe (beratend)
• Agent-WebSocket-Protokoll