Inicio rápido de Work IQ A2A

Requisitos previos

• Habilitar el inquilino para Work IQ
• SDK de .NET versión 8 o posterior para ejecutar el código de ejemplo

Registro de la aplicación en Microsoft Entra

Registro de una aplicación con permisos para acceder a Work IQ. Al registrar la aplicación, obtendrá dos valores: APP_ID y TENANT_ID. Use estos valores con el ejemplo de A2A para probar la configuración del inquilino.

Inicio rápido: Protocolo A2A

El protocolo de agente a agente (A2A) es un estándar abierto para la comunicación de agentes. Work IQ es compatible con A2A v1.0 (este inicio rápido) y v0.3. El A2A-Version encabezado de solicitud controla la distribución 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 (mantenido como predeterminado sin encabezado para la compatibilidad con versiones anteriores de los 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 dotnet/a2a el ejemplo se usa el SDK de .NET de A2A.

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

Ejecutar el ejemplo (HTTP sin procesar, sin SDK)

En dotnet/a2a-raw el ejemplo se muestra el protocolo de conexión sin abstracción de SDK. El uso de este ejemplo es útil para la portabilidad 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 sobre JSON-RPC en https://workiq.svc.cloud.microsoft/a2a/. (A2A v1.0 también define un enlace REST en /v1/message:send; Work IQ podría exponer este enlace REST en una actualización futura).

Puerta de enlace de Work IQ

• Punto de conexión: https://workiq.svc.cloud.microsoft/a2a/
• Audiencia simbólica: 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 se establece de forma predeterminada en 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 que result.task 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."
            }
          ]
        }
      ]
    }
  }
}

Work IQ requiere que los Location metadatos establezcan consultas con distinción de tiempo ("hoy" o "esta semana") en la hora local del usuario.

Conversaciones de varios turnos

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

{
  "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 clave del protocolo (A2A v1.0)

• Sobre JSON-RPC requerido: cada solicitud debe incluir jsonrpc, id, method, params.
• POST en la URL base: el método (SendMessage) está dentro del cuerpo de JSON-RPC, no en la ruta de la 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: roles use ROLE_USER / ROLE_AGENT; estados use / TASK_STATE_WORKING / TASK_STATE_COMPLETEDTASK_STATE_FAILED / etc.
• Contenedor de resultados: las respuestas de la tarea aparecen en result.task.
• Versión de distribución:A2A-Version: 1.0 selecciona v1.0; Omitir el encabezado (o enviar A2A-Version: 0.3) selecciona v0.3, el valor predeterminado sin encabezado.

Detección de agente

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

Recomendado: CLI list-agents de WorkIQ (experimental)

La CLI de WorkIQ incluye un comando experimental list-agents que enumera 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 del agente, el proveedor y el identificador de agente (la segunda línea de cada entrada). Use ese identificador cuando --agent-id ejecute el ejemplo.

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

1. Ve al sitio web de Microsoft 365 Copilot Chat.
2. Seleccione su agente en el panel de navegación izquierdo.
3. El ID de agente aparece en la barra de direcciones del navegador después /chat/agent/de :

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 ID de agente a la instancia de ejemplo

Pasar el id. de agente como argumento al ejemplo

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

▶ Abra una solicitud de inventario específica del agente en la demostración interactiva.

Capacidades de A2A

Autenticación

Solución de problemas

Contenido relacionado

• Código de ejemplo en GitHub
• Información general sobre la API de Work IQ
• Habilitar Work IQ en el inquilino
• Especificación del protocolo A2A
• A2A .NET SDK
• Guía de migración de A2A v0.3 → v1.0