Schnellstart: Arbeits-IQ A2A

Voraussetzungen

• Aktivieren Ihres Mandanten für Work IQ
• .NET SDK Version 8 oder höher zum Ausführen des Beispielcodes

Registrieren der Anwendung in Microsoft Entra

Registrieren Sie eine Anwendung mit Berechtigungen für den Zugriff auf Work IQ. Wenn Sie die App registrieren, erhalten Sie zwei Werte: APP_ID und TENANT_ID. Verwenden Sie diese Werte zusammen mit dem A2A Beispiel, um Ihre Mandantenkonfiguration zu testen.

Schnellstart: A2A-Protokoll

Das A2A-Protokoll (Agent-to-Agent) ist ein offener Standard für die Agent-Kommunikation. Work IQ unterstützt sowohl A2A v1.0 (in dieser Schnellstartanleitung) als auch v0.3. Der Anforderungsheader A2A-Version steuert die Versionsverteilung.

• A2A-Version: 1.0 – v1.0-Drahtformat (diese Schnellstartanleitung)
• A2A-Version: 0.3 (oder Header ausgelassen) – v0.3-Übertragungsformat (wird aus Gründen der Abwärtskompatibilität mit vorhandenen v0.3-Clients als Standardeinstellung ohne Header beibehalten)

Abrufen des Beispielcodes

Klonen Sie das Beispielrepository mit dem folgenden Befehl.

git clone https://github.com/microsoft/work-iq-samples.git
cd work-iq-samples

Ausführen des Beispiels (mit dem A2A SDK)

Im dotnet/a2a Beispiel wird das A2A .NET SDK verwendet.

cd dotnet/a2a
dotnet run -- --token WAM --appid <APP_ID> --tenant <TENANT_ID>

Ausführen des Beispiels (unformatiertes HTTP, kein SDK)

Das dotnet/a2a-raw Beispiel zeigt das Drahtprotokoll ohne SDK-Abstraktion. Die Verwendung dieses Beispiels ist für die Portierung in non-.NET Sprachen nützlich.

cd dotnet/a2a-raw
dotnet run -- --token WAM --appid <APP_ID> --tenant <TENANT_ID>

Folge

Wenn Sie das Beispiel ausführen, wird eine Anmeldeaufforderung angezeigt (WAM-Dialogfeld unter Windows, Systembrowser unter macOS/Linux). Geben Sie nach der Anmeldung an der Eingabeaufforderung eine Nachricht ein, und drücken Sie dieYou > EINGABETASTE. Die Antwort des Agents wird unten angezeigt. Geben Sie quit zum Beenden ein.

── READY — Work IQ Gateway — Sync — https://workiq.svc.cloud.microsoft/a2a/ ──
Type a message. 'quit' to exit.

You > Summarize my recent emails from Alice.
Agent > You've exchanged 8 emails with Alice this week. Key threads:
  - ...
  (2145 ms)

You > quit

So funktioniert es

Work IQ akzeptiert A2A v1.0 über JSON-RPC unter https://workiq.svc.cloud.microsoft/a2a/. (A2A v1.0 definiert auch eine REST-Bindung unter /v1/message:send; Work IQ macht diese REST-Bindung möglicherweise in einem zukünftigen Update verfügbar.)

Work IQ Gateway

• Endpunkt: https://workiq.svc.cloud.microsoft/a2a/
• Tokenzielgruppe: api://workiq.svc.cloud.microsoft
• Bereich: WorkIQAgent.Ask

Synchrone SendMessage

POST https://workiq.svc.cloud.microsoft/a2a/
Authorization: Bearer <token>
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": "<request-guid>",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "<message-guid>",
      "parts": [
        {
          "text": "What meetings do I have today?"
        }
      ],
      "metadata": {
        "Location": {
          "timeZoneOffset": -480,
          "timeZone": "America/Los_Angeles"
        }
      }
    }
  }
}

Der Anforderungsheader A2A-Version: 1.0 aktiviert v1.0-Methodennamen (SendMessage) auf dem Gateway. Andernfalls verwendet der Server standardmäßig v0.3 und gibt einen JSON-RPC -32601 "Method not found" für v1.0-Methodennamen zurück.

Die Antwort ist ein JSON-RPC-Umschlag mit result.task der Aufgabe des Agents und einem contextId für mehrere Durchläufe:

{
  "jsonrpc": "2.0",
  "id": "<request-guid>",
  "result": {
    "task": {
      "id": "<task-id>",
      "contextId": "ctx-1",
      "status": {
        "state": "TASK_STATE_COMPLETED"
      },
      "artifacts": [
        {
          "artifactId": "<artifact-id>",
          "name": "Answer",
          "parts": [
            {
              "text": "Today you have: 9 AM standup, 11 AM review with Dana, 2 PM customer call."
            }
          ]
        }
      ]
    }
  }
}

Work IQ erfordert, dass die Location Metadaten zeitkritische Abfragen ("heute" oder "diese Woche") zur Ortszeit des Benutzers erstellen.

Unterhaltungen mit mehreren Durchläufen

Um den Konversationszustand beizubehalten, übergeben Sie den contextId aus der vorherigen Antwort in der nächsten Nachricht.

{
  "jsonrpc": "2.0",
  "id": "<request-guid-2>",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "<message-guid-2>",
      "contextId": "ctx-1",
      "parts": [
        {
          "text": "Tell me more about the 2 PM customer call."
        }
      ]
    }
  }
}

Wichtige Protokolldetails (A2A v1.0)

• JSON-RPC-Umschlag erforderlich: Jede Anforderung muss , id, method, enthaltenjsonrpcparams.
• POST an Basis-URL: Die Methode (SendMessage) befindet sich im JSON-RPC-Text, nicht im URL-Pfad.
• Teile der Feldpräsenz: Teile sind flache Objekte mit einem von text, url, rawoder data festgelegt, ohne kind Unterscheidungszeichen.
• SCREAMING_SNAKE_CASE Enumerationen: Rollen verwendenROLE_USER / ROLE_AGENT; Status verwenden / TASK_STATE_WORKING / TASK_STATE_COMPLETEDTASK_STATE_FAILED / usw.
• Ergebniswrapper: Aufgabenantworten werden unter result.taskangezeigt.
• Versionsverteilung:A2A-Version: 1.0 wählt v1.0 aus; Wenn Sie den Header weglassen (oder senden), A2A-Version: 0.3wird v0.3 ausgewählt, der Standardwert ohne Header.

Agent-Ermittlung

Um einen bestimmten Agent aufzurufen, übergeben Sie dessen Agent-ID über --agent-id. Sie können die ID eines Agents auf zwei Arten finden.

Empfohlen: WorkIQ CLI list-agents (experimentell)

Die WorkIQ CLI enthält einen experimentellen list-agents Befehl, der die Agents auflistet, die für Ihren angemeldeten Benutzer verfügbar sind.

workiq config set experimental=true
workiq list-agents

Jede Zeile zeigt den Anzeigenamen, den Anbieter und die Agent-ID des Agents an (die zweite Zeile jedes Eintrags). Verwenden Sie diese ID mit --agent-id , wenn Sie das Beispiel ausführen.

Alternative: Kopieren aus der Microsoft 365 Copilot-URL

1. Wechseln Sie zur Microsoft 365 Copilot Chat Website: https://m365.cloud.microsoft/chat/.
2. Wählen Sie im linken Navigationsbereich Ihren Agent aus.
3. Die Agent-ID wird in der Adressleiste des Browsers nach /chat/agent/angezeigt:

https://m365.cloud.microsoft/chat/agent/P_c0fd1ab0-cbf3-7eb9-1a7d-2d823549ef31.8ad61c39-5b6e-447c-b26a-a64eee436502
                                       └──────────────────────────── agent ID ─────────────────────────────────────┘

Das Format ist <LETTER>_<opaqueValue1>.<opaqueValue2>.

Übergeben der Agent-ID an das Beispiel

Übergeben Sie die Agent-ID als Argument an das Beispiel.

dotnet run -- --token WAM --agent-id <AGENT_ID> --appid <APP_ID> --tenant <TENANT_ID>

A2A-Funktionen

Authentifizierung

Problembehandlung

Verwandte Inhalte

• Beispielcode auf GitHub
• Übersicht über die Arbeits-IQ-API
• Aktivieren des Arbeits-IQ in Ihrem Mandanten
• A2A-Protokollspezifikation
• A2A .NET SDK
• Migrationsleitfaden für A2A v0.3 → v1.0