10-01-04 — Conversão de Declarative para Custom Engine
TL;DR
Quando um declarative agent atinge seus limites (modelo engessado, RAG insuficiente, lógica complexa), a migração para custom engine é um processo gradual — não um restart. O caminho recomendado: mantenha o Copilot Studio como orquestrador e canal, substitua o LLM backend por Azure OpenAI próprio via M365 Agents SDK. Preserve topics existentes como wrappers para o novo engine.
Sinais de que é hora de migrar
Quando o declarative agent não é mais suficiente:
- Respostas genéricas demais — precisa de fine-tuning ou prompt engineering avançado
- RAG não atende — chunks muito grandes, relevância baixa, precisão insuficiente
- Lógica de negócio complexa — decisões com mais de 3 condições interdependentes
- Integração com sistemas .NET legados que não têm connector pronto
- Necessidade de controle de custo por chamada (o modelo padrão é caro para alto volume)
- SLA diferenciado — precisa garantir latência < 2s que o M365 Copilot não garante
Estratégia de migração gradual
flowchart LR
A[Declarative Agent] -->|Fase 1| B[Híbrido]
B -->|Fase 2| C[Custom Engine]
subgraph Fase 1 — Híbrido
B1[Topics simples → mantém declarative]
B2[Topics complexos → Action → sua API]
end
subgraph Fase 2 — Full Custom
C1[Copilot Studio como canal]
C2[M365 Agents SDK como engine]
C3[Azure OpenAI como LLM]
end
Passo a passo
Fase 1: Substituição pontual de topics
Para topics com lógica complexa, substitua o fluxo interno por uma chamada HTTP para sua API .NET. O agente ainda é declarativo no Copilot Studio, mas a lógica vive no seu código.
// Na sua API .NET — endpoint chamado pelo topic via HTTP Action
[ApiController]
[Route("api/agent")]
public class AgentController : ControllerBase
{
private readonly IKernel _kernel;
[HttpPost("analyze-ticket")]
public async Task AnalyzeTicket([FromBody] TicketRequest request)
{
// Lógica complexa que o Copilot Studio não suporta nativamente
var result = await _kernel.InvokeAsync("TicketPlugin", "Analyze",
new KernelArguments { ["ticket"] = request.Description });
return Ok(new { response = result.ToString(), confidence = 0.95 });
}
}
Fase 2: Migrar para M365 Agents SDK
Na fase 2, você substitui o core do agente pelo SDK. O Copilot Studio passa a ser apenas a camada de publicação e gestão de canais.
// Program.cs — agente com M365 Agents SDK
using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.BotBuilder;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient();
builder.Services.AddControllers();
// Registra o agente customizado
builder.AddAgent(sp =>
new AgentApplicationOptions {
StartTypingTimer = false
});
var app = builder.Build();
app.MapControllers();
app.MapAgentEndpoint("/api/messages"); // Ponto de entrada para Copilot Studio
app.Run();
O que NÃO migrar
Mantenha no Copilot Studio:
- Gestão de canais — publicação em Teams, Outlook, M365 Copilot continua via Copilot Studio
- Topics de sistema — Greeting, Goodbye, Escalate: não precisam de customização
- Analytics — o dashboard de analytics do Copilot Studio é valioso — preserve-o
- Autenticação — o SSO com Azure AD configurado no Copilot Studio continua funcionando
Checklist de migração
| Item | Status | Nota |
|---|---|---|
| Mapear todos os topics existentes | [ ] | Export via Copilot Studio |
| Identificar topics com lógica migravelal | [ ] | Priorizar por complexidade |
| Criar API .NET com endpoints equivalentes | [ ] | Swagger documentado |
| Configurar M365 Agents SDK | [ ] | Pacote NuGet |
| Testar SSO/autenticação | [ ] | Azure AD continua |
| Migrar knowledge sources para Azure AI Search | [ ] | Opcional mas recomendado |
| Atualizar topics no Copilot Studio | [ ] | Apontar para nova API |
Como isso se conecta
- 10-02-01 — M365 Agents SDK é o destino da migração
- 10-02-02 — Desenvolvimento .NET com o SDK
- Módulo 9 (Semantic Kernel) — SK substitui o orquestrador do Copilot Studio no custom engine