Início rápido do A2A do IQ de Trabalho

Pré-requisitos

• Ativar o IQ do seu inquilino para o Trabalho
• SDK .NET versão 8 ou posterior para executar o código de exemplo

Registar a aplicação no Microsoft Entra

Registe uma aplicação com permissões para aceder ao IQ do Trabalho. Quando regista a aplicação, obtém dois valores: APP_ID e TENANT_ID. Utilize estes valores com o exemplo de A2A para testar a configuração do inquilino.

Início Rápido: protocolo A2A

O protocolo Agente a Agente (A2A) é um padrão aberto para a comunicação do agente. O QI de Trabalho suporta A2A v1.0 (este início rápido) e v0.3. O A2A-Version cabeçalho do pedido controla a distribuição da versão.

• A2A-Version: 1.0 - formato de fio v1.0 (este início rápido)
• A2A-Version: 0.3 (ou cabeçalho omitido) – formato de fio v0.3 (mantido como a predefinição sem cabeçalho para retrocompatibilidade com clientes v0.3 existentes)

Obter o código de exemplo

Clone o repositório de exemplo com o seguinte comando.

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

Executar o exemplo (com o SDK A2A)

O dotnet/a2a exemplo utiliza o SDK .NET A2A.

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

Executar o exemplo (HTTP não processado, sem SDK)

O dotnet/a2a-raw exemplo mostra o protocolo de transmissão sem abstração do SDK. Utilizar este exemplo é útil para migrar para non-.NET idiomas.

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

O que acontece

Quando executa o exemplo, é apresentado um pedido de início de sessão (caixa de diálogo WAM no Windows, browser do sistema no macOS/Linux). Depois de iniciar sessão, escreva uma mensagem na You > linha de comandos e prima Enter. A resposta do agente é apresentada abaixo. Escreva quit para sair.

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

Como funciona

O IQ de Trabalho aceita A2A v1.0 em JSON-RPC em https://workiq.svc.cloud.microsoft/a2a/. (A2A v1.0 também define um enlace REST em /v1/message:send; O QI de Trabalho pode expor este enlace REST numa atualização futura.)

Gateway de IQ de Trabalho

• Ponto final: https://workiq.svc.cloud.microsoft/a2a/
• Público-alvo do token: api://workiq.svc.cloud.microsoft
• Escopo: WorkIQAgent.Ask

Síncrono 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"
        }
      }
    }
  }
}

O A2A-Version: 1.0 cabeçalho do pedido ativa os nomes dos métodos v1.0 (SendMessage) no gateway. Sem este, o servidor é predefinido como v0.3 e devolve um JSON-RPC -32601 "Method not found" para nomes de métodos v1.0.

A resposta é um envelope JSON-RPC que result.task contém a tarefa do agente e um contextId para várias voltas:

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

O QI de Trabalho requer que os Location metadados moam consultas sensíveis ao tempo ("hoje" ou "esta semana") na hora local do utilizador.

Conversações multiturno

Para manter o estado da conversação, transmita o contextId da resposta anterior na mensagem seguinte.

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

Detalhes do protocolo chave (A2A v1.0)

• Envelope JSON-RPC obrigatório: todos os pedidos têm de incluir jsonrpc, id, method, . params
• POST para URL de base: o método (SendMessage) está dentro do corpo JSON-RPC, não do caminho do URL.
• Partes de presença de campo: as partes são objetos planos com um de text, url, rawou data definido; sem kind discriminação.
• SCREAMING_SNAKE_CASE enumerações: as funções utilizam ROLE_USER / ROLE_AGENT; os estados utilizam / TASK_STATE_WORKING / TASK_STATE_COMPLETEDTASK_STATE_FAILED/etc.
• Wrapper de resultados: as respostas das tarefas são apresentadas em result.task.
• Distribuição de versões:A2A-Version: 1.0 seleciona v1.0; omitir o cabeçalho (ou enviar A2A-Version: 0.3) seleciona v0.3, a predefinição sem cabeçalho.

Deteção de agente

Para invocar um agente específico, transmita o respetivo ID de agente através de .--agent-id Pode encontrar o ID de um agente de duas formas.

Recomendado: CLI list-agents do WorkIQ (experimental)

A CLI do WorkIQ inclui um comando experimental list-agents que lista os agentes disponíveis para o utilizador com sessão iniciada.

workiq config set experimental=true
workiq list-agents

Cada linha mostra o nome a apresentar, o fornecedor e o ID do agente do agente (a segunda linha de cada entrada). Utilize esse ID ao --agent-id executar o exemplo.

Alternativa: copiar do URL do Microsoft 365 Copilot

1. Aceda ao site do Microsoft 365 Copilot Chat: https://m365.cloud.microsoft/chat/.
2. Selecione o agente no painel de navegação esquerdo.
3. O ID do agente aparece na barra de endereço do browser depois de /chat/agent/:

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

O formato é <LETTER>_<opaqueValue1>.<opaqueValue2>.

Transmitir o ID do agente para o exemplo

Transmitir o ID do agente como um argumento para o exemplo

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

capacidades de A2A

Autenticação

Solução de problemas

Conteúdo relacionado

• Código de exemplo no GitHub
• Descrição geral da API de QI de Trabalho
• Ativar o QI de Trabalho no seu inquilino
• especificação do protocolo A2A
• SDK .NET A2A
• guia de migração A2A v0.3 → v1.0