Work IQ A2A-Schnellstart

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 mit dem A2A-Beispiel, um Ihre Mandantenkonfiguration zu testen.

Schnellstart: A2A-Protokoll

Das Agent-zu-Agent-Protokoll (A2A-Protokoll) ist ein offener Standard für die Agent-Kommunikation. Work IQ unterstützt sowohl A2A v1.0 (diese Schnellstart) als auch v0.3. Der Anforderungsheader steuert den A2A-Version Versionsversand.

• A2A-Version: 1.0 - v1.0 Drahtformat (dieser Schnellstart)
• A2A-Version: 0.3 (oder Header weggelassen) – v0.3-Drahtformat (beibehalten als Standard ohne Header für die Abwärtskompatibilität mit vorhandenen v0.3-Clients)

Beispielcode abrufen

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 nützlich für die Portierung in non-.NET Sprachen.

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

Folge

Wenn Sie das Beispiel ausführen, erscheint eine Anmeldeaufforderung (WAM-Dialogfeld unter Windows, Systembrowser unter macOS/Linux). Geben Sie nach der Anmeldung eine Nachricht an der You > Eingabeaufforderung ein, und drücken Sie die EINGABETASTE. Die Antwort des Agenten wird unten angezeigt. Type quit to exit.

── 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 bei /v1/message:send; Work IQ wird diese REST-Bindung möglicherweise in einem zukünftigen Update verfügbar machen.)

Work IQ Gateway

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

Synchron 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 A2A-Version: 1.0 Anforderungsheader aktiviert v1.0-Methodennamen (SendMessage) auf dem Gateway. Ohne diesen Wert ist der Server standardmäßig auf v0.3 festgelegt 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 Agenten und einem contextId für mehrere Runden:

{
  "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 benötigt die Location Metadaten, um zeitkritische Abfragen ("heute" oder "diese Woche") in der Ortszeit des Benutzers zu verankern.

Konversationen mit Mehrfachdurchläufen

Um den Konversationsstatus 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 enthalten jsonrpc, id, method, params.
• POST an Basis-URL: Die Methode (SendMessage) befindet sich im JSON-RPC-Text, nicht im URL-Pfad.
• Feldpräsenzteile: Teile sind flache Objekte mit einem von text, url, rawoder data Menge; kein kind Diskriminator.
• SCREAMING_SNAKE_CASE Enumerationen: Rollen verwendenROLE_USER / ROLE_AGENT; Zustände verwenden TASK_STATE_WORKING / / TASK_STATE_COMPLETEDTASK_STATE_FAILED / usw.
• Ergebnis-Wrapper: Aufgabenantworten werden unter result.taskangezeigt.
• Version Versand:A2A-Version: 1.0 wählt v1.0; Wenn Sie die Kopfzeile weglassen (oder A2A-Version: 0.3senden), wird v0.3 ausgewählt, die Standardeinstellung ohne Kopfzeile.

Agent-Ermittlung

Um einen bestimmten Agent aufzurufen, übergeben Sie seine Agent-ID durch --agent-id. Sie können die ID eines Agenten auf zwei Arten finden.

Empfohlen: WorkIQ CLI list-agents (experimentell)

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

workiq config set experimental=true
workiq list-agents

Jede Zeile zeigt den Anzeigenamen, den Anbieter und die Agent-ID des Agenten (die zweite Zeile jedes Eintrags). Verwenden Sie diese ID --agent-id beim Ausführen des Beispiels.

Alternative: Kopieren aus der Microsoft 365 Copilot-URL

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

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 der Agent-ID als Argument an das Beispiel

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

▶ Öffnen Sie in der interaktiven Demo eine agentspezifische Bestandseingabeaufforderung.

A2A-Funktionen

Authentifizierung

Problembehandlung

Verwandte Inhalte

• Beispielcode auf GitHub
• Übersicht über die Work IQ-API
• Aktivieren von Work IQ in Ihrem Mandanten
• Spezifikation des A2A-Protokolls
• A2A .NET SDK
• Migrationshandbuch für A2A v0.3 → v1.0