Início rápido da API de IQ de Trabalho (pré-visualização)

Importante

O QI de Trabalho está em pré-visualização pública. As funcionalidades e as APIs podem ser alteradas antes da disponibilidade geral e não têm um SLA definido.

O IQ de Trabalho é a interface nativa de IA da Microsoft para a inteligência de trabalho do Microsoft 365. Permite-lhe criar aplicações que podem consultar e-mails, reuniões, ficheiros e conhecimentos organizacionais com linguagem natural; baseado nos seus dados do Microsoft 365.

Este início rápido abrange o protocolo Agente a Agente (A2A). A2A é um padrão aberto para a comunicação do agente e suporta o modo síncrono em relação ao Gateway de IQ de Trabalho. O suporte para o modo de transmissão em fluxo (Eventos Enviados pelo Servidor (SSE)) estará disponível em breve.

Pré-requisitos

Ativar a API de QI de Trabalho na sua organização

⏱️ ~5 minutos, uma vez por organização.

Esta secção cria duas coisas na sua organização:

  • O principal de serviço do Work IQ (aprovisiona o recurso do IQ de Trabalho para que os utilizadores possam pedir tokens para o mesmo)
  • Um registo de aplicação que o código de cliente utiliza para autenticar, com a WorkIQAgent.Ask permissão delegada

O utilizador (ou o administrador da sua organização) pode utilizar o centro de administração do Microsoft Entra ou a CLI do Azure para concluir este passo.

Etapa 1. Criar o principal de serviço do IQ de Trabalho (Graph Explorer)

  1. Aceda ao Graph Explorer e inicie sessão com uma conta de administrador.

  2. Defina o método como POST e o URL como https://graph.microsoft.com/v1.0/servicePrincipals. O Grafo Explorer apresenta âmbitos relevantes com base no URL e no método, pelo que o URL tem de ser introduzido antes de dar consentimento no passo seguinte.

  3. Selecione Modificar permissões e consentimento para Application.ReadWrite.All. Este passo é uma ação de administrador única e concede o âmbito apenas para a sua própria sessão do Graph Explorer. Não altera as permissões em toda a organização.

  4. Introduza o seguinte no corpo do Pedido.

    {
  "appId": "fdcc1f02-fc51-4226-8753-f668596af7f7"
}

  5. Selecione Executar consulta. Uma resposta criada do 201 confirma o êxito. Um erro de conflito significa que o principal de serviço já existe. Não há problema em avançar para o passo seguinte.

Etapa 2. Criar o registo de aplicações

  1. Aceda ao centro de administração do Microsoft Entra. No painel de navegação esquerdo, selecione Entra ID e, em seguida, Registros de aplicativo.
  2. Selecione Novo registro.
  3. Adicione um nome descritivo, defina Tipos de conta suportados como Contas apenas neste diretório organizacional. Selecione Registrar.
  4. Copie o ID da Aplicação (cliente). Este valor é o seu APP_ID.
  5. Selecione Autenticação. Selecione Adicionar uma plataforma (ou Adicionar URI de Redirecionamento). Na caixa de diálogo, selecione Aplicações móveis e de ambiente de trabalho.
    • Selecione o URI sugerido: https://login.microsoftonline.com/common/oauth2/nativeclient.
    • Em URIs de redirecionamento personalizados, adicione os seguintes dois URIs um de cada vez (cada um na sua própria linha):
      • http://localhost
      • ms-appx-web://microsoft.aad.brokerplugin/<APP_ID> (onde <APP_ID> está o seu APP_ID)
    • Em Definições avançadas, defina Permitir fluxos de cliente público comoSim.
    • Selecione Salvar.
  6. Selecione Permissões de API, Adicionar uma permissão e, em seguida, APIs que a minha organização utiliza. Procure e Work IQ, em seguida, selecione Permissões delegadas. Selecione WorkIQAgent.Ask e, em seguida, selecione Adicionar permissões.
  7. Selecione Conceder consentimento do administrador para [o seu inquilino]. Reveja a caixa de diálogo de confirmação e selecione Sim.
  8. Copie o ID do Diretório (inquilino) da página de descrição geral do Microsoft Entra ID.

A permissão WorkIQAgent.Ask permite que a aplicação, em nome do utilizador com sessão iniciada, consulte as respetivas informações de trabalho do Microsoft 365 (correio, ficheiros, reuniões, conversas) através do IQ do Trabalho.

Agora deve ter dois valores: APP_ID e TENANT_ID. Transmita estes valores para o exemplo através de --appid e --tenant.

Dica

Criar um agente do lado do servidor (aplicação Web)? Este início rápido utiliza um registo de cliente público (móvel/ambiente de trabalho) para o caminho mais simples para um exemplo de trabalho. Se a sua aplicação for um serviço do lado do servidor que chama o IQ de Trabalho em nome de um utilizador final (por exemplo, um agente Web que inicia sessão do utilizador e, em seguida, reencaminha a respetiva identidade para o IQ de Trabalho), utilize um registo de cliente confidencial com um segredo ou certificado de cliente e troque o token do utilizador através do fluxo Em Nome de (OBO). A superfície da API de QI de Trabalho e a permissão delegada WorkIQAgent.Ask são as mesmas em ambos os fluxos.

Guia de introdução: 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 futura atualização de pré-visualização.)

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 Existem duas formas de encontrar o ID de um agente.

A CLI do WorkIQ envia um comando experimental list-agents que imprime 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 encontra-se na barra de endereço do browser 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>.

Transmitir o ID do agente para o exemplo

Importante

Trate todo o ID do agente como uma cadeia opaca. Não desconstrua nem analise os respetivos componentes. Transmita-o tal como está para a API.

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>

Observação

Alguns agentes do Microsoft 365 (nomeadamente Word, Excel e agentes do PowerPoint na IU do Copilot Chat) foram concebidos para serem executados no contexto desses produtos do Office e não produzem respostas úteis quando invocados sem cabeça através de A2A.

capacidades de A2A

Recursos Status
SendMessage (sincronizar) ✅ Disponível
Várias curvas (contextId) ✅ Disponível
Partes de texto ✅ Disponível
Citações ✅ Disponível (a forma de entrega está a ser modernizada; veja as notas de versão)

Autenticação

Método Plataforma Uso
WAM (Gestor de Conta do Windows) Windows --token WAM --appid <APP_ID> --tenant <TENANT_ID>
Browser interativo macOS, Linux Mesmo comando — o Cliente de Identidade da Microsoft reverte para um início de sessão no browser do sistema.
JWT pré-obtido Qualquer --token <JWT>(o token tem de ser emitido para a sua aplicação registada, não para um cliente arbitrário como o CLI do Azure)

Solução de problemas

Sintoma Correção
401 Unauthorized O token aud não corresponde api://workiq.svc.cloud.microsofta . Verifique a afirmação da audiência.
403 Forbidden (sem erro de âmbito) Utilizador em falta Microsoft 365 Copilot licença. Atribua e aguarde entre 15 e 30 minutos.
403 Forbidden com Required scopes = [...] Administração consentimento WorkIQAgent.Ask para não foi concedido. Execute novamente o consentimento do administrador (configuração do administrador, passo 6/Azure passo 3 da CLI).
WAM IncorrectConfiguration (3399614466) Falta o URI de redirecionamento do mediador no registo de aplicações. Lido ms-appx-web://microsoft.aad.brokerplugin/<APP_ID> e tente novamente.
O WAM continua a falhar depois de o URI de redirecionamento estar definido Aplicação de inquilino único + /common erro de correspondência de autoridade. Passe --tenant <TENANT_ID> para que o Cliente de Identidade da Microsoft utilize a autoridade específica do inquilino.
AADSTS65001: consent required Administração consentimento não foi concedido. Execute az ad app permission admin-consent --id <APP_ID>.
Vazio 200/ sem texto do agente Se a licença copilot do utilizador tiver sido atribuída recentemente, o índice pode demorar entre 15 e 30 minutos a criar. Se invocou um agente do Word/Excel/PowerPoint, esses agentes são executados no produto do Office e não produzem respostas A2A sem cabeça.

Conteúdo relacionado

  • Last updated on