Arbeits-IQ-API-Schnellstart (Vorschau)

Work IQ ist die KI-native Schnittstelle von Microsoft zu Microsoft 365 Work Intelligence. Damit können Sie Anwendungen erstellen, die E-Mails, Besprechungen, Dateien und Organisationswissen in natürlicher Sprache abfragen können. Grund für Ihre Microsoft 365-Daten.

In dieser Schnellstartanleitung wird das A2A-Protokoll (Agent-to-Agent) behandelt. A2A ist ein offener Standard für die Agent-Kommunikation und unterstützt den synchronen Modus für das Work IQ Gateway. Unterstützung für den Streamingmodus (server-sent events (SSE)) ist in Kürze verfügbar.

Voraussetzungen

• Ein Benutzer mit einer Microsoft 365 Copilot-Lizenz
• .NET SDK Version 8 oder höher zum Ausführen des Beispielcodes
• Ein Benutzer mit organization Administratorzugriff für das einmalige Work IQ-Setup

Aktivieren der Work IQ-API in Ihrem organization

⏱️ ~5 Minuten, einmalig pro organization.

In diesem Abschnitt werden zwei Dinge in Ihrem organization erstellt:

• Der Work IQ-Dienstprinzipal (stellt die Arbeits-IQ-Ressource bereit, damit Ihre Benutzer Token dafür anfordern können)
• Eine App-Registrierung , die Ihr Clientcode für die Authentifizierung verwendet, mit der WorkIQAgent.Ask delegierten Berechtigung

Sie (oder Ihr organization-Administrator) können den Microsoft Entra Admin Center oder die Azure CLI verwenden, um diesen Schritt auszuführen.

Sie sollten nun über zwei Werte verfügen: APP_ID und TENANT_ID. Übergeben Sie diese Werte über --appid und --tenantan das Beispiel.

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 Vorschauupdate 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. Es gibt zwei Möglichkeiten, die ID eines Agents zu finden.

Empfohlen: WorkIQ CLI list-agents (experimentell)

Die WorkIQ CLI liefert einen experimentellen list-agents Befehl, der die Agents ausgibt, 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 befindet sich 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 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
• A2A-Protokollspezifikation
• A2A .NET SDK
• Migrationsleitfaden für A2A v0.3 → v1.0