Início rápido do Work IQ A2A

Pré-requisitos

• Habilitar seu locatário para o Work IQ
• .NET SDK versão 8 ou posterior para executar o código de exemplo

Registrar o aplicativo no Microsoft Entra

Registre um aplicativo com permissões para acessar o Work IQ. Ao registrar o aplicativo, você obtém dois valores: APP_ID e TENANT_ID. Use esses valores com o exemplo de A2A para testar a configuração do locatário.

Início Rápido: protocolo A2A

O protocolo Agent-to-Agent (A2A) é um padrão aberto para comunicação de agente. O Work IQ dá suporte a A2A v1.0 (este início rápido) e v0.3. O A2A-Version cabeçalho da solicitação controla a expediçã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 o padrão sem cabeçalho para compatibilidade com versões anteriores com clientes v0.3 existentes)

Obter o código de exemplo

Clone o repositório de exemplo usando o comando a seguir.

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

Executar o exemplo (com o SDK do A2A)

O dotnet/a2a exemplo usa o SDK do .NET A2A.

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

Executar o exemplo (HTTP bruto, sem SDK)

O dotnet/a2a-raw exemplo mostra o protocolo de conexão sem abstração do SDK. O uso desse exemplo é útil para portabilidade para idiomas non-.NET.

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

O que acontece

Quando você executa o exemplo, um prompt de entrada é exibido (caixa de diálogo WAM no Windows, navegador do sistema no macOS/Linux). Depois de entrar, digite uma mensagem no You > prompt e pressione Enter. A resposta do agente é exibida abaixo. Type 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 Work IQ aceita A2A v1.0 sobre JSON-RPC em https://workiq.svc.cloud.microsoft/a2a/. (A2A v1.0 também define uma associação REST em /v1/message:send; O QI de Trabalho pode expor essa associação REST em uma atualização futura.)

Gateway de QI de Trabalho

• Ponto de extremidade: https://workiq.svc.cloud.microsoft/a2a/
• Audiência do token: api://workiq.svc.cloud.microsoft
• Escopo: WorkIQAgent.Ask

Síncrona 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 da solicitação habilita nomes de método v1.0 (SendMessage) no gateway. Sem ele, o servidor usa como padrão a v0.3 e retorna um JSON-RPC -32601 "Method not found" para nomes de método v1.0.

A resposta é um envelope JSON-RPC contendo result.task 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 Work IQ requer que os metadados fundamentem consultas sensíveis ao Location tempo ("hoje" ou "esta semana") na hora local do usuário.

Conversas em várias etapas

Para manter o estado da conversa, passe a contextId resposta anterior na próxima mensagem.

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

Principais detalhes do protocolo (A2A v1.0)

• Envelope JSON-RPC necessário: cada solicitação deve incluir jsonrpc, id, methodparams, .
• POST para a URL base: o método (SendMessage) está dentro do corpo JSON-RPC, não do caminho da URL.
• Peças de presença de campo: as peças são objetos planos com um dos text, url, raw, ou data definido; sem kind discriminador.
• SCREAMING_SNAKE_CASE enumerações: uso deROLE_USER / ROLE_AGENTfunções; uso de estados TASK_STATE_WORKINGTASK_STATE_COMPLETED / / TASK_STATE_FAILED / etc.
• Wrapper de resultado: as respostas da tarefa aparecem em result.task.
• Despacho de versão:A2A-Version: 1.0 seleciona v1.0; Omitir o cabeçalho (ou enviar A2A-Version: 0.3) seleciona v0.3, o padrão sem cabeçalho.

Descoberta de agente

Para chamar um agente específico, passe sua ID de agente por meio do --agent-id. Você pode encontrar a ID de um agente de duas maneiras.

Recomendado: WorkIQ CLI list-agents (experimental)

A CLI do WorkIQ inclui um comando experimental list-agents que lista os agentes disponíveis para o usuário conectado.

workiq config set experimental=true
workiq list-agents

Cada linha mostra o nome de exibição, o provedor e o ID do agente (a segunda linha de cada entrada). Use essa ID com --agent-id ao executar o exemplo.

Alternativa: copiar da URL do Microsoft 365 Copilot

1. Acesse o site do Microsoft 365 Copilot Chat.
2. Selecione seu agente na navegação à esquerda.
3. A ID do agente aparece na barra de endereços do navegador após /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>.

Passe a ID do agente para o exemplo

Passe a ID do agente como um argumento para o exemplo

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

▶ Abra uma solicitação de inventário específica do agente na Demonstração interativa.

Recursos do A2A

Autenticação

Solução de problemas

Conteúdo relacionado

• Código de exemplo no GitHub
• Visão geral da API de QI de Trabalho
• Habilitar o Work IQ em seu locatário
• Especificação do protocolo A2A
• SDK .NET A2A
• Guia de migração do A2A v0.3 → v1.0