Inicio rápido de Work IQ A2A

Requisitos previos

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

Registrar la aplicación en Microsoft Entra

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

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 mediante 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 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. 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, 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 de agente aparece 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
• Habilitación de Work IQ en el inquilino
• especificación del protocolo A2A
• SDK de .NET de A2A
• guía de migración de A2A v0.3 → v1.0