Démarrage rapide Work IQ A2A

Configuration requise

• Activer votre client pour Work IQ
• SDK .NET version 8 ou ultérieure pour exécuter l’exemple de code

Enregistrer l’application dans Microsoft Entra

Inscrivez une application avec des autorisations pour accéder à Work IQ. Lorsque vous inscrivez l’application, vous obtenez deux valeurs : APP_ID et TENANT_ID. Utilisez ces valeurs avec l’exemple A2A pour tester la configuration de votre locataire.

Démarrage rapide : protocole A2A

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

• A2A-Version: 1.0 - V1.0 Wire Format (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 une compatibilité descendante avec les clients v0.3 existants)

Obtenir l’exemple de code

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

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

Exécuter l’exemple (avec le SDK A2A)

L’exemple dotnet/a2a utilise le Kit de développement logiciel (SDK) .NET A2A.

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

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

L’exemple dotnet/a2a-raw montre le protocole filaire sans abstraction 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 sous Windows, navigateur système sous macOS/Linux). Après vous être connecté, tapez un message à l’invite You > , puis appuyez sur Entrée. La réponse de l’agent apparaît ci-dessous. Type quit pour 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 à https://workiq.svc.cloud.microsoft/a2a/. (A2A v1.0 définit également une liaison REST à /v1/message:send; Work IQ pourrait exposer cette liaison REST dans une prochaine mise à jour.)

Passerelle Work IQ

• Point de terminaison : https://workiq.svc.cloud.microsoft/a2a/
• Public de 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 prend par défaut la version v0.3 et renvoie un JSON-RPC -32601 "Method not found" pour les noms de méthode v1.0.

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

{
  "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 exige que les Location métadonnées groundent les requêtes temporelles (« aujourd’hui » ou « cette semaine ») à l’heure locale de l’utilisateur.

Conversations à plusieurs tours

Pour conserver l’état de la conversation, transmettez la contextId 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 clé (A2A v1.0)

• Enveloppe JSON-RPC requise : chaque demande doit inclure jsonrpc, id, method, params.
• POST vers l’URL de base : la méthode (SendMessage) se trouve à l’intérieur du corps JSON-RPC, pas dans le chemin d’URL.
• Parties de présence de champ : les parties sont des objets plats avec l’un des , url, raw, ou data ensemble ; pas kind de textdiscriminateur.
• 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 aux tâches apparaissent sous result.task.
• Distribution de version :A2A-Version: 1.0 sélectionne v1.0 ; Omettre l’en-tête (ou l’envoi A2A-Version: 0.3) sélectionne v0.3, la valeur par défaut sans en-tête.

Découverte d’agent

Pour appeler un agent spécifique, transmettez son ID d’agent via --agent-id. Vous pouvez trouver l’ID d’un agent de deux manières.

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

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

workiq config set experimental=true
workiq list-agents

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

Solution alternative : copiez à partir de l’URL de Microsoft 365 Copilot

1. Accédez au site web Microsoft 365 Copilot Chat.
2. Sélectionnez votre agent dans le volet de navigation de gauche.
3. L’ID d’agent s’affiche 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>.

Transmettre l’ID d’agent à l’exemple

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

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

▶ Ouvrez une invite d’inventaire spécifique à l’agent dans la démonstration interactive.

Fonctionnalités A2A

Authentification

Résolution des problèmes

Contenu connexe

• Exemple de code sur GitHub
• Vue d’ensemble de l’API Work IQ
• Activer Work IQ dans votre client
• Spécification du protocole A2A
• SDK .NET A2A
• Guide de migration A2A v0.3 → v1.0