Como chamar agentes do Copilot Studio no Power Automate

O que você vai conseguir fazer ao final deste tutorial

Se a sua cooperativa já tem um agente do Copilot Studio respondendo associados sobre limite de crédito, prazo de proposta ou status de uma solicitação, em algum momento vai aparecer a pergunta óbvia: por que esse agente só funciona dentro da janela de chat? Por que o analista precisa abrir o Copilot Studio manualmente, colar o texto da solicitação e copiar a resposta de volta para o sistema?

A resposta é que, até pouco tempo, não existia uma ponte oficial entre cloud flows e agentes. Isso mudou com a ação Execute Agent and wait, disponível no conector Microsoft Copilot Studio dentro do Power Automate. Com ela, um fluxo disparado pela criação de um item numa lista de solicitações de crédito, pela chegada de um e-mail ou por uma linha nova no Dataverse pode chamar o agente, esperar a resposta e seguir o processo sem intervenção manual.

Este tutorial mostra o caminho exato para configurar essa chamada, incluindo os parâmetros de locale e conversation que determinam o idioma da resposta e a continuidade do diálogo. E mostra também onde esse caminho simplesmente não existe: agentes construídos no harness do GitHub Copilot não aparecem para essa ação, e tentar forçar essa integração é a armadilha mais comum de quem chega animado com a novidade.

Pré-requisitos

• Agente publicado no harness Standard do Copilot Studio. É o agente construído na tela clássica, com tópicos, orquestração generativa, ações e fontes de conhecimento. Mais adiante explico como confirmar isso antes de perder tempo configurando o fluxo.
• Licença de Power Automate com acesso a conector premium. O conector Microsoft Copilot Studio é classificado como premium. Isso significa plano Power Automate per user ou per flow ativo para o ambiente, além da licença de mensagens do Copilot Studio que cobre o consumo gerado pela chamada do fluxo (a conversa iniciada pela ação consome capacidade de mensagens da mesma forma que uma conversa humana no canal).
• Papel de Environment Maker no ambiente Dataverse onde o agente está publicado, para quem vai criar o fluxo.
• Compartilhamento do agente com o usuário ou a entidade de serviço dona do fluxo. Um agente publicado não fica automaticamente visível para todo mundo que tem acesso ao ambiente, é preciso compartilhar o registro do agente explicitamente.
• Mesmo ambiente para agente e fluxo. A ação lista agentes por ambiente selecionado, então fluxo e agente precisam viver no mesmo ambiente Dataverse, salvo uso de conexão cross-environment configurada à parte.

Sequência de seis passos para chamar um agente Standard do Copilot Studio a partir de um cloud flow no Power Automate

Passo a passo: conectando o cloud flow ao agente

1. Confirme que o agente foi construído no harness Standard

Antes de abrir o Power Automate, abra o agente no Copilot Studio e confira como ele foi criado. Se ele nasceu na experiência clássica, descrição em linguagem natural seguida da tela de Tópicos, Ações e Conhecimento, é harness Standard e segue este tutorial sem problema. Se ele foi criado ou editado por um fluxo de desenvolvimento assistido por GitHub Copilot CLI, Claude Code ou qualquer ferramenta de codificação agêntica usando o M365 Agents SDK, ele roda no harness do GitHub Copilot, e a seção mais adiante explica por que o caminho deste tutorial não se aplica a ele.

Na prática, para uma cooperativa, o agente Standard costuma ser o cenário de triagem de solicitações: ele lê a descrição do pedido de crédito, classifica a urgência, aponta documentos pendentes e devolve um resumo. Esse é o tipo de agente que queremos chamar de dentro de um processo automatizado.

2. Publique e compartilhe o agente com quem vai criar o fluxo

No Copilot Studio, vá em Seu agente > Publicar e confirme que a versão mais recente está publicada. Depois, em Configurações > Segurança > Compartilhar agente, adicione o usuário ou a entidade de serviço que será dona do cloud flow. Sem esse compartilhamento, o agente simplesmente não aparece no seletor do conector dentro do Power Automate, mesmo que ele exista no mesmo ambiente.

3. Crie o cloud flow no Power Automate

No Power Automate, vá em Meus fluxos > Novo fluxo > Fluxo de nuvem automatizado. Escolha o gatilho conforme o processo da cooperativa, por exemplo Quando um item é criado apontando para a lista do SharePoint onde a área de negócio registra solicitações de associados, ou Quando uma linha é adicionada se o registro já entra direto numa tabela do Dataverse.

4. Adicione a ação Execute Agent and wait

Clique em Nova etapa, pesquise por Copilot Studio e selecione o conector Microsoft Copilot Studio. Dentro dele, escolha a ação Execute Agent and wait. Essa ação é síncrona: o fluxo pausa a execução até o agente concluir o processamento da mensagem e devolver uma resposta, diferente de um disparo assíncrono que você teria que buscar depois.

5. Preencha ambiente, agente, mensagem, conversation e locale

O cartão da ação pede os seguintes campos:

• Ambiente: selecione o ambiente Dataverse onde o agente está publicado.
• Agente: um seletor carrega a lista de agentes Standard compartilhados com o dono do fluxo nesse ambiente. Se o agente que você precisa não aparece aqui, volte ao passo 2 antes de suspeitar de bug.
• Mensagem: o texto que vai para o agente. Use conteúdo dinâmico do gatilho, por exemplo o campo de descrição da solicitação de crédito.
• ID da conversa (conversation): deixe em branco para abrir uma conversa nova a cada execução. Preencha com um valor salvo de uma execução anterior quando precisar manter contexto entre chamadas, por exemplo quando o mesmo processo de análise de crédito aciona o agente mais de uma vez ao longo de dias diferentes e precisa lembrar o que já foi discutido. Nesse caso, grave o valor de saída ID da conversa numa coluna do Dataverse ligada ao registro da solicitação, e reaproveite esse valor na próxima chamada.
• Locale: o código de idioma, como pt-BR. Esse valor precisa corresponder a um dos idiomas configurados no agente em Configurações > Idiomas. Se a cooperativa atende cooperados de uma região com atendimento bilíngue, ou se o agente foi publicado só em português, mandar um locale não configurado gera erro em vez de fallback silencioso.

Em termos de definição subjacente do fluxo, essa ação equivale a uma chamada de conector com os seguintes parâmetros:

{
  "type": "OpenApiConnection",
  "inputs": {
    "host": {
      "apiId": "/providers/Microsoft.PowerApps/apis/shared_copilotstudio",
      "connection": "shared_copilotstudio",
      "operationId": "ExecuteAgentAndWait"
    },
    "parameters": {
      "environmentId": "a1b2c3d4-0000-0000-0000-000000000000",
      "agentIdentifier": "triagem_associados_credito",
      "conversationId": "@{body('Buscar_linha_Dataverse')?['cr_conversationid']}",
      "locale": "pt-BR",
      "text": "@{triggerBody()?['descricao_solicitacao']}"
    }
  },
  "runAfter": {}
}

Entender essa estrutura ajuda a ler o payload quando algo falha no histórico de execuções, já que o Power Automate mostra o JSON cru da chamada ali.

6. Trate a resposta do agente no restante do fluxo

A ação devolve, entre outras saídas, o texto final da resposta do agente e o ID da conversa usado. Use o texto de resposta para atualizar o registro no Dataverse, montar um cartão adaptativo no Teams para o analista responsável, ou decidir um ramo de condição, por exemplo encaminhar para aprovação manual quando o agente classifica a solicitação como de alto risco.

Um ponto de desenho importante aqui: construa o tópico ou a orquestração generativa do agente para concluir em um único turno quando chamado por este caminho. Se o tópico espera uma pergunta de acompanhamento do usuário antes de fechar a conversa, não existe um humano do outro lado para responder, e a ação vai esperar até o limite de tempo configurado e falhar.

Como validar que a chamada funcionou

Rode o fluxo manualmente com Testar > Manualmente ou dispare o gatilho real criando um item de teste na lista. No histórico de execução, abra a etapa Execute Agent and wait e confira três coisas: o corpo da requisição mostra o texto exato que foi enviado ao agente, a resposta traz o conteúdo gerado pelo agente de forma legível (não um erro ou um objeto vazio), e o status da etapa aparece como êxito, não como ignorado ou com aviso. Se o agente respondeu com uma pergunta em vez de uma conclusão, revise o design do tópico antes de considerar o fluxo pronto para produção.

Por que o mesmo caminho não funciona com agentes do harness do GitHub Copilot

Aqui está a armadilha que mais custa tempo. Um agente construído com assistência de GitHub Copilot CLI, usando o M365 Agents SDK para gerar código, teste e deploy de forma agêntica, não vive no mesmo catálogo que o conector Microsoft Copilot Studio consulta para popular o seletor de agentes. O seletor da ação Execute Agent and wait enumera agentes registrados como bots do harness Standard dentro do Dataverse do ambiente, e agentes do harness GitHub Copilot não aparecem nessa lista, mesmo que estejam publicados e visíveis dentro do próprio Copilot Studio.

Se você tentar contornar isso digitando manualmente o identificador do agente num campo de conteúdo dinâmico, a chamada falha porque o endpoint de execução desse harness é diferente do endpoint que o conector foi construído para alcançar. Não é uma permissão faltando, é uma rota que não existe.

A única forma suportada de orquestrar um agente desse tipo a partir de outro processo é de dentro do próprio Copilot Studio, usando o agent node dentro de um tópico ou de uma orquestração generativa de outro agente, o chamado padrão de agente chamando agente. Ou seja, se a cooperativa precisa que um agente de triagem acione, como sub-rotina, um agente construído no harness do GitHub Copilot, essa composição acontece dentro da tela de autoria do Copilot Studio, não dentro de um cloud flow do Power Automate.

Na prática de arquitetura, isso significa decidir cedo em que harness cada agente vai nascer, de acordo com quem vai consumi-lo. Agentes pensados para serem chamados por automações de processo de negócio, integrados a listas do SharePoint, tabelas do Dataverse ou fluxos de aprovação, ganham mais com o harness Standard, justamente porque é o único que o conector do Power Automate enxerga hoje.

Erros comuns

• "The specified agent could not be found in this environment." O agente selecionado foi construído no harness do GitHub Copilot, ou está publicado num ambiente diferente do selecionado no campo Ambiente.
• "Forbidden: the caller does not have permission to invoke this agent." O dono do fluxo, usuário ou entidade de serviço, não recebeu o compartilhamento do agente em Configurações > Segurança. Resolver isso não exige refazer a conexão, basta adicionar o acesso no agente.
• "The specified locale is not configured for this agent." O código de idioma enviado no campo locale não corresponde a nenhum idioma ativado nas configurações do agente. Confira a lista de idiomas publicados antes de fixar o valor no fluxo.
• Tempo limite da ação estourado sem mensagem clara. O tópico do agente ficou esperando uma resposta adicional do usuário que nunca chega, porque quem está do outro lado é um fluxo automatizado, não uma pessoa digitando. Redesenhe o tópico para fechar em um único turno quando acionado por esse canal.
• Agente não aparece no seletor mesmo publicado. Combinação mais provável de causas: falta de compartilhamento explícito do agente, ambiente errado selecionado, ou o agente de fato foi construído no harness do GitHub Copilot e nunca vai aparecer ali.

Fechamento

A ação Execute Agent and wait fecha uma lacuna real: ela transforma um agente que antes só existia como canal de chat num componente que qualquer cloud flow pode chamar, esperar e tratar como parte de um processo maior. Para uma cooperativa que já investiu em agentes de triagem, atendimento ou análise documental, essa é a diferença entre um experimento isolado e uma automação que efetivamente substitui um passo manual na operação.

Quando a decisão envolve escolher entre harness Standard e harness do GitHub Copilot para um novo agente, vale desenhar antes quem vai consumir esse agente e por qual caminho. Esse é exatamente o tipo de decisão de arquitetura que vale conversar com quem já implementou os dois caminhos em produção.