Démarrage rapide de l’API Work IQ (préversion)

Work IQ est l’interface native IA de Microsoft pour l’intelligence de travail Microsoft 365. Il vous permet de créer des applications qui peuvent interroger des e-mails, des réunions, des fichiers et des connaissances organisationnelles à l’aide du langage naturel ; base dans vos données Microsoft 365.

Ce guide de démarrage rapide couvre le protocole Agent à Agent (A2A). A2A est une norme ouverte pour la communication de l’agent et prend en charge le mode synchrone sur work IQ Gateway. La prise en charge du mode de diffusion en continu (événements envoyés par le serveur (SSE)) sera bientôt disponible.

Configuration requise

• Un utilisateur disposant d’une licence Microsoft 365 Copilot
• Sdk .NET version 8 ou ultérieure pour l’exécution de l’exemple de code
• Un utilisateur disposant d’un accès administrateur organization pour la configuration one-time Work IQ

Activer l’API Work IQ dans votre organization

⏱️ Environ 5 minutes, une fois par organization.

Cette section crée deux éléments dans votre organization :

• Le principal du service Work IQ (approvisionne la ressource Work IQ afin que vos utilisateurs puissent demander des jetons pour celle-ci)
• Une inscription d’application que votre code client utilise pour l’authentification, avec l’autorisation WorkIQAgent.Ask déléguée

Vous (ou votre administrateur organization) pouvez utiliser l’centre d’administration Microsoft Entra ou l’interface CLI Azure pour effectuer cette étape.

Vous devez maintenant avoir deux valeurs : APP_ID et TENANT_ID. Transmettez ces valeurs à l’exemple via --appid et --tenant.

Démarrage rapide : protocole A2A

Le protocole agent à agent (A2A) est une norme ouverte pour la communication de l’agent. Work IQ prend en charge A2A v1.0 (ce démarrage rapide) et v0.3. L’en-tête A2A-Version de requête contrôle la répartition des versions.

• A2A-Version: 1.0 - Format de fil v1.0 (ce guide de démarrage rapide)
• A2A-Version: 0.3 (ou en-tête omis) : format de fil v0.3 (conservé comme valeur par défaut sans en-tête pour la compatibilité descendante avec les clients v0.3 existants)

Obtenir l’exemple de code

Clonez l’exemple de référentiel avec la commande suivante.

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

Exécuter l’exemple (avec le Kit de développement logiciel (SDK) A2A)

L’exemple dotnet/a2a utilise le sdk .NET A2A.

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

Exécuter l’exemple (HTTP brut, pas de SDK)

L’exemple dotnet/a2a-raw montre le protocole filaire sans abstraction du KIT de développement logiciel (SDK). L’utilisation de cet exemple est utile pour le portage vers non-.NET langues.

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

Action exécutée

Lorsque vous exécutez l’exemple, une invite de connexion s’affiche (boîte de dialogue WAM sur Windows, navigateur système sur macOS/Linux). Après vous être connecté, tapez un message à l’invite You > et appuyez sur Entrée. La réponse de l’agent apparaît ci-dessous. Tapez quit à quitter.

── 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

Mode de fonctionnement

Work IQ accepte A2A v1.0 sur JSON-RPC à l’adresse https://workiq.svc.cloud.microsoft/a2a/. (A2A v1.0 définit également une liaison REST à /v1/message:send; Work IQ peut exposer cette liaison REST dans une prochaine préversion.)

Work IQ Gateway

• Terminaison: https://workiq.svc.cloud.microsoft/a2a/
• Audience du jeton : api://workiq.svc.cloud.microsoft
• Portée :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"
        }
      }
    }
  }
}

L’en-tête A2A-Version: 1.0 de requête active les noms de méthode v1.0 (SendMessage) sur la passerelle. Sans elle, le serveur utilise la valeur par défaut v0.3 et retourne un JSON-RPC -32601 "Method not found" pour les noms de méthodes v1.0.

La réponse est une enveloppe JSON-RPC contenant result.task la tâche de l’agent et un contextId pour plusieurs tour :

{
  "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 nécessite que les Location métadonnées soient mises au sol pour les requêtes sensibles au temps (« aujourd’hui » ou « cette semaine ») dans l’heure locale de l’utilisateur.

Conversations multitours

Pour maintenir l’état de la conversation, transmettez le contextId à partir de la réponse précédente dans le message suivant.

{
  "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."
        }
      ]
    }
  }
}

Détails du protocole de clé (A2A v1.0)

• Enveloppe JSON-RPC requise : chaque requête doit inclure jsonrpc, id, method, params.
• POST vers l’URL de base : la méthode (SendMessage) se trouve dans le corps JSON-RPC, et non dans le chemin d’URL.
• Parties de présence de champ : les parties sont des objets plats avec l’un des textéléments , url, rawou data définis ; aucun kind discriminateur.
• SCREAMING_SNAKE_CASE énumérations : les rôles utilisent ROLE_USER / ROLE_AGENT; les états utilisent / TASK_STATE_WORKING / TASK_STATE_COMPLETEDTASK_STATE_FAILED / etc.
• Wrapper de résultats : les réponses de tâche apparaissent sous result.task.
• Distribution de version :A2A-Version: 1.0 sélectionne la version 1.0 ; Omettre l’en-tête (ou envoyer A2A-Version: 0.3) sélectionne v0.3, la valeur par défaut sans en-tête.

Découverte de l’agent

Pour appeler un agent spécifique, passez son ID d’agent via --agent-id. Il existe deux façons de rechercher l’ID d’un agent.

Recommandé : Cli list-agents WorkIQ (expérimental)

L’interface CLI WorkIQ fournit une commande expérimentale list-agents qui imprime les agents disponibles pour votre utilisateur connecté.

workiq config set experimental=true
workiq list-agents

Chaque ligne affiche le nom complet, le fournisseur et l’ID de l’agent (la deuxième ligne de chaque entrée). Utilisez cet ID avec --agent-id lors de l’exécution de l’exemple.

Alternative : copier à partir de l’URL Microsoft 365 Copilot

1. Accédez au site web Microsoft 365 Copilot Chat : https://m365.cloud.microsoft/chat/.
2. Sélectionnez votre agent dans le volet de navigation de gauche.
3. L’ID de l’agent se trouve dans la barre d’adresses du navigateur après /chat/agent/:

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

Le format est <LETTER>_<opaqueValue1>.<opaqueValue2>.

Passer l’ID de l’agent à l’exemple

Passez l’ID d’agent en tant qu’argument à l’exemple

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

A2A fonctionnalités

Authentification

Résolution des problèmes

Contenu connexe

• Exemple de code sur GitHub
• Vue d’ensemble des API Work IQ
• spécification du protocole A2A
• A2A SDK .NET
• Guide de migration A2A v0.3 → v1.0