10-01-01 — Declarative vs Custom Engine Agents

⏱ 15 minFontes validadas em: 2026-04-29

TL;DR

Declarative agents rodam sobre o M365 Copilot como extensões configuradas via YAML/JSON — sem código de LLM, usam o modelo da Microsoft. Custom engine agents você controla o modelo, o orquestrador e a lógica — mais poder, mais responsabilidade. A escolha é simples: se cabe no Copilot Studio low-code com GPT-4o da Microsoft, use declarative. Se precisa de modelo próprio, RAG avançado ou lógica complexa, use custom engine.

O que são Declarative Agents

Declarative agents são a forma mais simples de estender o M365 Copilot. Você define comportamento via manifest (JSON) e instructions (texto), sem escrever código de LLM. O agente roda sobre a infraestrutura do Microsoft 365 Copilot — mesmo modelo, mesmo grounding, mesma compliance.

Insight: Um declarative agent é essencialmente um system prompt + fontes de conhecimento empacotados como app Teams. Perfeito para personas corporativas (ex: "Assistente RH da Impar") que devem seguir políticas da empresa.

Estrutura de um Declarative Agent

// declarativeAgent.json (manifest simplificado)
{
  "schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.4/schema.json",
  "version": "v1.4",
  "name": "Assistente RH Impar",
  "description": "Responde dúvidas sobre políticas de RH",
  "instructions": "Você é o assistente de RH da Impar. Responda com base nos documentos de políticas. Seja conciso e formal.",
  "capabilities": [
    {
      "name": "OneDriveAndSharePoint",
      "items_by_url": [
        { "url": "https://impar.sharepoint.com/sites/RH/Shared%20Documents" }
      ]
    }
  ]
}

O que são Custom Engine Agents

Custom engine agents você traz seu próprio modelo (Azure OpenAI, outros), seu próprio orquestrador (Semantic Kernel, AutoGen, LangChain) e sua própria lógica de RAG. O Copilot Studio (ou M365 Agents SDK) serve como camada de hosting e publicação, não como LLM.

Atenção: Custom engine agents têm latência e custo maiores. Você paga pelos tokens do seu Azure OpenAI e pela capacidade do Copilot Studio. Só vale quando o modelo padrão não atende.

Comparativo

graph LR subgraph Declarative DA[Manifest JSON] --> CS[Copilot Studio] CS --> M365[M365 Copilot LLM] M365 --> R[Resposta] end subgraph Custom Engine CE[Código .NET/Python] --> SK[Semantic Kernel] SK --> AOAI[Azure OpenAI GPT-4o] AOAI --> R2[Resposta] SK --> RAG[RAG / Tools] end

Aspecto	Declarative	Custom Engine
Código necessário	Nenhum (só JSON/texto)	Sim (.NET, Python, JS)
Modelo LLM	Controlado pela Microsoft	Você escolhe
RAG avançado	Limitado ao que o Copilot suporta	Total controle
Custo	Incluído no M365 Copilot	Azure OpenAI separado
Compliance M365	Nativa (DLP, auditoria)	Responsabilidade sua
Time-to-market	Horas	Dias/semanas
Canais suportados	M365 Copilot, Teams	Teams, Web, qualquer canal

Quando usar cada um

Regra prática para CEOs de .NET:

Use declarative quando o caso de uso é grounding em documentos corporativos + persona específica. Ex: assistente jurídico, assistente de onboarding.
Use custom engine quando você precisa de: modelo fine-tuned, lógica de negócio complexa, integração com sistemas legados .NET, ou SLA diferenciado.

Ciclo de vida no Copilot Studio

flowchart TD A[Criar no Copilot Studio] --> B{Tipo?} B -->|Declarative| C[Configurar Manifest + Instructions] B -->|Custom Engine| D[Conectar ao seu Bot/API] C --> E[Publicar no M365] D --> E E --> F[Distribuir via Teams App]

Arquitetura de referência

A Microsoft publicou em 2025 o Agents SDK para padronizar a criação de custom engine agents. O SDK abstrai a camada de comunicação com canais (Teams, Web Chat, Outlook) e deixa você focar na lógica do agente.

Microsoft Build 2025: A Microsoft anunciou que todos os agentes criados no Copilot Studio a partir de 2025 são baseados no novo agent framework, que unifica declarative e custom engine sob o mesmo modelo de distribuição via Teams App Store.

Como isso se conecta

10-01-02 — Topics e triggers são o mecanismo de controle dentro do Copilot Studio para declarative agents
10-02-01 — M365 Agents SDK é o SDK oficial para custom engine agents
10-01-04 — Como migrar de declarative para custom engine quando o projeto cresce
Módulo 9 (Semantic Kernel) — SK é o orquestrador preferido para custom engine agents em .NET