Agente declarativo, Copilot Studio ou Agents SDK: qual usar em cada caso

Uma empresa de energia com 3.000 funcionários recebeu três pedidos de agente na mesma semana. O comercial queria um assistente que redigisse propostas no padrão da casa. O RH queria um agente que respondesse sobre políticas e abrisse chamado quando a resposta não bastasse. O atendimento queria um agente no portal do cliente, com dados do ERP e um modelo ajustado ao vocabulário do setor. A pergunta da TI foi direta: dá para fazer os três no Copilot Studio?

Dava, e seria a escolha errada para dois deles. Este post explica as quatro formas de construir um agente para o Microsoft 365 Copilot (a documentação mais recente o chama de Microsoft Copilot), o que cada uma entrega e como decidimos nesse caso.

As quatro opções em um parágrafo cada

Agent Builder fica dentro do app do Copilot (microsoft365.com/chat, office.com/chat e Teams). Você descreve o agente em linguagem natural, ajusta as instruções, aponta sites do SharePoint e Copilot connectors (antes Graph connectors), testa e compartilha. Ele não cria ações que integrem sistemas externos; para isso, a própria tela oferece copiar o agente para o Copilot Studio. O resultado é um agente declarativo, usado dentro do Copilot (inclusive no app do Teams); ele não funciona em chats 1:1 ou em grupo do Teams.

Agente declarativo com o Microsoft 365 Agents Toolkit (antes Teams Toolkit) é o mesmo tipo de agente, descrito em um arquivo JSON chamado manifesto, versionado em Git e empacotado como app do Microsoft 365. O dev controla cada campo, adiciona plugins de API ou servidores MCP como ações e publica pelo processo de apps da organização. Em novembro de 2026 a Microsoft mantém em preview o Work IQ Dev Tools, uma linha de comando para esse mesmo ciclo de vida.

Copilot Studio é a ferramenta low-code: conhecimento, tópicos, orquestração generativa, ações com conectores da Power Platform, agent flows e publicação em vários canais (Teams e Copilot, SharePoint, site próprio, WhatsApp via Azure Communication Services, Facebook e, por meio do Azure Bot Service, Slack, Telegram e outros). Traz ambientes, soluções e pipelines da Power Platform para ALM. A cobrança é em Copilot Credits.

Microsoft 365 Agents SDK é um framework de código (C# com .NET 8, JavaScript com Node.js e Python 3.9 a 3.11, segundo a visão geral no Learn) para agentes conversacionais. Ele recebe a mensagem de qualquer canal, normaliza em um objeto Activity, chama o handler que você escreveu e devolve a resposta no formato do canal. Ele não traz modelo nem orquestrador: você escolhe (Azure AI Foundry, Agent Framework, LangChain ou uma chamada direta a uma API). Você hospeda, em geral no Azure App Service, e conecta aos canais pelo Azure Bot Service. No vocabulário do Microsoft 365, esse é um "custom engine agent".

Agente declarativo: o manifesto

Um agente declarativo é um arquivo de configuração. Nome (até 100 caracteres), descrição (até 1.000), instruções (até 8.000), uma lista de capacidades e até 12 sugestões de conversa. O Copilot lê isso e passa a se comportar como o agente descrito, usando o próprio modelo e o próprio orquestrador. Não há servidor, deploy nem custo de hospedagem. O manifesto abaixo é o do assistente de propostas do comercial, no esquema 1.9, o mais recente em novembro de 2026.

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.9/schema.json",
  "version": "v1.9",
  "name": "Assistente de propostas",
  "description": "Ajuda o time comercial a redigir e revisar propostas no padrão da empresa.",
  "instructions": "Você redige e revisa propostas comerciais. Use apenas os modelos e as tabelas de preço da biblioteca Propostas. Cite o documento de origem em cada trecho. Se o pedido não for sobre proposta, diga que está fora do seu escopo.",
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        { "url": "https://contoso.sharepoint.com/sites/Comercial/Propostas" }
      ]
    },
    {
      "name": "WebSearch",
      "sites": [{ "url": "https://www.contoso.com/produtos" }]
    }
  ],
  "conversation_starters": [
    { "title": "Nova proposta", "text": "Monte o esqueleto de uma proposta de manutenção preventiva por 12 meses." },
    { "title": "Revisar texto", "text": "Revise o texto que vou colar e aponte o que foge do padrão da empresa." }
  ]
}

Três detalhes do esquema mudam o resultado. Em OneDriveAndSharePoint, se você omitir tanto items_by_url quanto items_by_sharepoint_ids, o agente pesquisa todo o SharePoint e OneDrive a que o usuário tem acesso; aponte sempre a biblioteca. Em WebSearch, a lista sites aceita até quatro URLs com no máximo dois segmentos de caminho; sem a lista, o agente busca na web inteira. E cada tipo de capacidade só pode aparecer uma vez no array. O esquema 1.9 acrescentou agent_skills (pastas com um arquivo SKILL.md) e a capacidade Fabric.

Copilot Studio: quando a lógica e os canais pesam

O agente de políticas do RH precisava de duas coisas que um declarativo não entrega: uma ação de "abrir chamado" no sistema de tickets quando a resposta não resolve, e um relatório de quais perguntas ficam sem resposta. No Copilot Studio isso é um tópico com um conector (ou um agent flow) e o painel de análise. O conhecimento ficou em duas bibliotecas do SharePoint, com a permissão de quem pergunta respeitada porque o agente autentica com o Microsoft Entra. Em conhecimento do agente no Copilot Studio está o detalhe de cada fonte.

O custo é em Copilot Credits. Em novembro de 2026, o pacote de 25.000 créditos custa US$ 200 por mês (R$ 1.145,10 na tabela brasileira, sem impostos) e o pay-as-you-go sai a US$ 0,01 por crédito na assinatura do Azure. Uma resposta generativa consome 2 créditos, uma ação de agente 5 e o tenant graph grounding 10. Para quem tem licença do Microsoft 365 Copilot e usa o agente no Teams, no Copilot ou no SharePoint, autenticado com a própria conta, a documentação marca essas taxas como sem cobrança; ficam de fora Computer-Using Agents, agentes autônomos e agent flows com outros gatilhos. A conta completa está em Copilot Studio: o que é, como é cobrado e quando faz sentido.

Um caminho frequente é começar no Agent Builder e, quando aparece a primeira ação, copiar o agente para o Copilot Studio. A cópia preserva instruções e fontes; a partir dali o agente passa a viver em um ambiente da Power Platform, com solução, pipeline e as políticas de dados do tenant.

Agents SDK: quando você precisa do loop

O agente do portal do cliente tinha três exigências que apontam para código: um canal fora do Microsoft 365 (o portal), um modelo ajustado ao vocabulário do setor e consultas ao ERP com regras de negócio que ninguém queria manter em tópicos. O Agents SDK cuida da camada de mensagens, estado e canais; o que o agente diz é problema do orquestrador que você conectar. O esqueleto abaixo é o do quickstart oficial em JavaScript, com os nomes do nosso caso. Em TypeScript e C# a forma é a mesma: uma classe que estende AgentApplication e registra handlers por tipo de atividade.

// index.mjs
import { startServer } from "@microsoft/agents-hosting-express";
import { AgentApplication, MemoryStorage } from "@microsoft/agents-hosting";

class AgenteAtendimento extends AgentApplication {
  constructor(storage) {
    super({ storage });
    this.onConversationUpdate("membersAdded", this.boasVindas);
    this.onActivity("message", this.responder);
  }

  boasVindas = async (context) =>
    context.sendActivity("Olá. Pergunte sobre pedidos, prazos e faturas.");

  responder = async (context, state) => {
    const pergunta = context.activity.text;
    // Troque a linha abaixo pela chamada ao seu orquestrador
    // (Azure AI Foundry, Agent Framework, LangChain ou uma API própria).
    const resposta = "Você perguntou: " + pergunta;
    await context.sendActivity(resposta);
  };
}

// Sobe um servidor Express em http://localhost:3978/api/messages
startServer(new AgenteAtendimento(new MemoryStorage()));

Para rodar: npm install @microsoft/agents-hosting-express, depois node index.mjs. O Microsoft 365 Agents Playground (pacote @microsoft/teams-app-test-tool) abre um chat local apontando para a porta 3978, sem registrar nada no Azure. Em produção, o mesmo código vai para o App Service, ganha um registro no Azure Bot Service e, a partir dele, aparece no Teams, no Copilot, no portal e no que mais for preciso.

Quem usa um agente desses no Copilot Chat não precisa de licença do Copilot; se o agente ler SharePoint ou Copilot connectors para usuários sem licença, a documentação prevê cobrança por consumo em Copilot Credits. O custo principal muda de lugar: App Service, Azure Bot Service, o modelo no Azure AI Foundry (a documentação mais recente o chama de Microsoft Foundry) e o tempo do time que mantém a aplicação. Para dados do Microsoft 365, o agente usa as APIs do Graph e a Retrieval API, com as permissões do usuário autenticado. Se a sua orquestração já existe no Foundry, há um caminho mais curto: publicar o agente do Foundry direto no Copilot e no Teams pelo portal, que provisiona o Bot Service e o registro no Entra.

Como decidir

A ordem das perguntas importa. Primeiro, quem mantém: se a resposta for "a área", pare no Agent Builder ou no Copilot Studio. Depois, onde estão os dados: SharePoint e Dataverse favorecem declarativo e Copilot Studio; ERP e bancos próprios, Copilot Studio com conector ou SDK. Em seguida, os canais: tudo dentro do Microsoft 365 dispensa código; portal, app próprio ou WhatsApp com regras complexas pedem Copilot Studio ou SDK. Por fim, o modelo: se precisa ser um modelo específico, com ajuste fino ou avaliação própria, é Foundry com SDK ou Foundry publicado no Copilot.

Na empresa de energia, o desenho ficou assim: o assistente de propostas virou um agente declarativo criado pelo próprio comercial no Agent Builder, com o manifesto exportado e guardado pela TI. O agente de políticas do RH foi feito no Copilot Studio, com duas bibliotecas como fonte, uma ação de abrir chamado e publicação no Teams. O agente do portal do cliente foi escrito com o Agents SDK em C#, modelo no Foundry e deploy no App Service, publicado no portal e também no Teams para o time de atendimento. Três agentes, três ferramentas, um mesmo conjunto de regras de governança.

O próximo passo prático é listar os agentes que a empresa quer nos próximos seis meses e responder, para cada um, as quatro perguntas acima. Em Copilot connectors e grounding está como levar dados de fora do Microsoft 365 para os agentes declarativos e do Copilot Studio. Se quiser ajuda para desenhar essa arquitetura, a consultoria em Copilot Studio começa exatamente por esse mapa.