Inicio rápido de Work IQ API (versión preliminar)

Work IQ es la interfaz nativa de inteligencia artificial de Microsoft para La inteligencia artificial de Microsoft 365. Permite crear aplicaciones que pueden consultar correos electrónicos, reuniones, archivos y conocimientos de la organización mediante lenguaje natural; base en los datos de Microsoft 365.

En este inicio rápido se describe el protocolo agente a agente (A2A). A2A es un estándar abierto para la comunicación del agente y admite el modo sincrónico en work IQ Gateway. La compatibilidad con el modo de streaming (eventos enviados por el servidor (SSE)) estará disponible próximamente.

Requisitos previos

• Un usuario con una licencia de Microsoft 365 Copilot
• SDK de .NET versión 8 o posterior para ejecutar el código de ejemplo
• Un usuario con acceso de administrador de la organización para la configuración de Work IQ de un solo uso

Habilitación de Work IQ API en su organización

⏱️ ~5 minutos, una sola vez por organización.

En esta sección se crean dos cosas en la organización:

• La entidad de servicio Work IQ (aprovisiona el recurso Work IQ para que los usuarios puedan solicitar tokens para él)
• Un registro de aplicación que el código de cliente usa para autenticarse, con el WorkIQAgent.Ask permiso delegado

Usted (o el administrador de la organización) puede usar el Centro de administración Microsoft Entra o la CLI de Azure para completar este paso.

Ahora debe tener dos valores: APP_ID y TENANT_ID. Pase estos valores al ejemplo a través de --appid y --tenant.

Inicio rápido: protocolo de A2A

El protocolo agente a agente (A2A) es un estándar abierto para la comunicación del agente. Work IQ admite A2A v1.0 (este inicio rápido) y v0.3. El A2A-Version encabezado de solicitud controla el envío de versiones.

• A2A-Version: 1.0 - Formato de cable v1.0 (este inicio rápido)
• A2A-Version: 0.3 (o encabezado omitido): formato de conexión v0.3 (se mantiene como el valor predeterminado sin encabezado para la compatibilidad con versiones anteriores con clientes v0.3 existentes)

Obtener el código de ejemplo

Clone el repositorio de ejemplo con el siguiente comando.

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

Ejecutar el ejemplo (con el SDK de A2A)

En el ejemplo se dotnet/a2a usa el SDK de .NET de A2A.

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

Ejecute el ejemplo (HTTP sin formato, sin SDK)

En el ejemplo se dotnet/a2a-raw muestra el protocolo de conexión sin abstracción del SDK. El uso de este ejemplo es útil para migrar a non-.NET idiomas.

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

Qué ocurre

Al ejecutar el ejemplo, aparece un mensaje de inicio de sesión (cuadro de diálogo WAM en Windows, explorador del sistema en macOS/Linux). Después de iniciar sesión, escriba un mensaje en el símbolo del You > sistema y presione Entrar. La respuesta del agente aparece a continuación. Escriba quit para salir.

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

Cómo funciona

Work IQ acepta A2A v1.0 a través de JSON-RPC en https://workiq.svc.cloud.microsoft/a2a/. (A2A v1.0 también define un enlace REST en /v1/message:send; El IQ de trabajo podría exponer este enlace REST en una actualización en versión preliminar futura).

Puerta de enlace de IQ de trabajo

• Punto de conexión: https://workiq.svc.cloud.microsoft/a2a/
• Público de token: api://workiq.svc.cloud.microsoft
• Ámbito: WorkIQAgent.Ask

Sincrónico 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"
        }
      }
    }
  }
}

El A2A-Version: 1.0 encabezado de solicitud habilita los nombres de método v1.0 (SendMessage) en la puerta de enlace. Sin él, el servidor tiene como valor predeterminado v0.3 y devuelve un JSON-RPC -32601 "Method not found" para los nombres de método v1.0.

La respuesta es un sobre JSON-RPC con result.task que contiene la tarea del agente y un contextId para varios turnos:

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

El IQ de trabajo requiere los Location metadatos para poner en tierra las consultas sensibles a la hora ("hoy" o "esta semana") en la hora local del usuario.

Conversaciones de varios turnos

Para mantener el estado de la conversación, pase de contextId la respuesta anterior en el mensaje siguiente.

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

Detalles del protocolo clave (A2A v1.0)

• Se requiere un sobre JSON-RPC: cada solicitud debe incluir jsonrpc, id, method, params.
• POST a dirección URL base: el método (SendMessage) está dentro del cuerpo JSON-RPC, no la ruta de acceso de la dirección URL.
• Partes de presencia de campo: las partes son objetos planos con uno de text, url, rawo data establecido; sin kind discriminador.
• SCREAMING_SNAKE_CASE enumeraciones: los roles usan ROLE_USER / ROLE_AGENT; los estados usan / TASK_STATE_WORKING / TASK_STATE_COMPLETEDTASK_STATE_FAILED /, etc.
• Contenedor de resultados: las respuestas de tarea aparecen en result.task.
• Distribución de versiones:A2A-Version: 1.0 selecciona v1.0; Si se omite el encabezado (o se envía A2A-Version: 0.3), se selecciona v0.3, el valor predeterminado sin encabezado.

Detección de agentes

Para invocar un agente específico, pase su identificador de agente a través de --agent-id. Hay dos maneras de encontrar el identificador de un agente.

Recomendado: CLI list-agents de WorkIQ (experimental)

La CLI de WorkIQ incluye un comando experimental list-agents que imprime los agentes disponibles para el usuario que ha iniciado sesión.

workiq config set experimental=true
workiq list-agents

Cada fila muestra el nombre para mostrar, el proveedor y el identificador del agente del agente (la segunda línea de cada entrada). Use ese identificador con --agent-id al ejecutar el ejemplo.

Alternativa: copia desde la dirección URL de Microsoft 365 Copilot

1. Vaya al sitio web de Microsoft 365 Copilot Chat: https://m365.cloud.microsoft/chat/.
2. Seleccione el agente en el panel de navegación izquierdo.
3. El identificador del agente está en la barra de direcciones del explorador después de /chat/agent/:

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

El formato es <LETTER>_<opaqueValue1>.<opaqueValue2>.

Pasar el identificador de agente al ejemplo

Pasar el identificador de agente como argumento al ejemplo

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

funcionalidades de A2A

Autenticación

Solución de problemas

Contenido relacionado

• Código de ejemplo en GitHub
• Introducción a work IQ API
• especificación del protocolo A2A
• SDK de .NET de A2A
• guía de migración de A2A v0.3 → v1.0