.NET AI Technology Selection: escolha a camada antes de implementar

ANÁLISE EDITORIAL

Adicionar inteligência artificial a uma aplicação .NET não começa com a escolha de um modelo. Começa com uma pergunta mais básica: o problema pede uma previsão sobre dados estruturados, uma resposta em linguagem natural, busca em documentos, execução de ferramentas, inferência de um modelo já treinado ou operação local? Escolher a camada errada aumenta custo, acoplamento e superfície de falha antes mesmo do primeiro teste.

A .NET AI Technology Selection, mantida pela equipe .NET no repositório oficial dotnet/skills, funciona como um roteador técnico. Ela separa ML.NET, Microsoft.Extensions.AI, Microsoft Agent Framework, GitHub Copilot SDK, ONNX Runtime, Microsoft.Extensions.VectorData e OllamaSharp conforme o tipo de tarefa e o nível de orquestração necessário.

Esta curadoria fixou o commit fbeeafe261b0fe704b9a95c58fd9fdbe34e96964, observado em 7 de setembro de 2026. O pacote hospedado pelo Bastidores contém somente SKILL.md, sete referências Markdown exigidas pelo arquivo principal, a licença MIT e ORIGEM.md. Não inclui código de projeto, pacotes NuGet, modelos, dados, executáveis, credenciais, builds ou testes.

Ilustração editorial exclusiva do Bastidores da IA. A capa representa rotas abstratas para diferentes tipos de carga de IA antes de uma validação final. Não é captura de tela, interface real, diagrama oficial, benchmark, selo ou certificação.

O que esta Skill faz de verdade

O SKILL.md auditado começa classificando a tarefa. Classificação, regressão, clustering, detecção de anomalias e recomendação sobre dados estruturados seguem para ML.NET. Geração ou resumo em uma chamada direta seguem para IChatClient, pela abstração Microsoft.Extensions.AI. Um fluxo com ferramentas, iterações e vários passos muda de categoria e pode justificar Microsoft Agent Framework.

Outras rotas são igualmente específicas. Um modelo treinado que já existe em ONNX pede ONNX Runtime. Execução local de um modelo de linguagem pode usar OllamaSharp por trás da mesma abstração de chat. Busca semântica e RAG acrescentam ingestão, embeddings, armazenamento vetorial, filtro de relevância e atribuição de fontes. Extensões do ambiente GitHub Copilot usam o Copilot SDK, não um cliente genérico de LLM.

A Skill também limita a profundidade da resposta. Se o pedido é apenas comparação, plano ou arquitetura, o agente deve parar na decisão e não criar projeto nem executar comandos. Se o pedido inclui implementação, ele abre somente a referência da rota escolhida. Esse carregamento progressivo evita misturar exemplos de sete tecnologias em uma resposta que precisava de uma só.

Para quem serve

Serve a desenvolvedores e arquitetos que mantêm aplicações .NET 8 ou superiores e precisam introduzir recursos de IA sem transformar toda necessidade em chatbot. É especialmente útil durante refinamento técnico, prova de conceito, revisão de arquitetura e triagem de uma solicitação ampla como “adicione IA ao produto”.

Também ajuda equipes que herdaram uma integração direta com um provedor e querem separar regra de negócio, abstração de modelo, armazenamento, orquestração e hospedagem. O mapa atual do ecossistema .NET + AI faz distinção semelhante entre Microsoft.Extensions.AI, ingestão de dados, vetores, Agent Framework, Copilot SDK e opções de execução.

A finalidade não repete a Agents Best Practices. Aquela Skill projeta o harness completo de um agente, com permissões, ferramentas, memória e avaliações. A candidata desta página decide qual tecnologia .NET atende ao problema antes da implementação. Também é mais ampla que um guia isolado de RAG ou ML.NET, pois sua entrega principal é uma escolha justificada entre rotas.

Compatibilidade e pré-requisitos

O frontmatter da Skill restringe o uso a aplicações .NET 8+. Essa é uma condição do arquivo auditado, não uma afirmação de que toda biblioteca mencionada compartilha exatamente o mesmo suporte. O guia oficial para aplicações .NET com IA deve ser confrontado com a versão real do projeto e com a documentação do pacote escolhido.

Para um plano, bastam o código ou a arquitetura atual, o formato dos dados, o resultado esperado e os limites de implantação. Para implementar, também são necessários SDK do .NET, acesso ao feed NuGet, ambiente de teste, configuração segura e documentação vigente do provedor. Serviços hospedados podem exigir conta, endpoint, modelo habilitado e cobrança. Modelos locais exigem armazenamento, memória e capacidade compatível no hardware de destino.

A Skill não atende projetos em .NET Framework, ETL puro sem componente de IA ou treinamento profundo personalizado. Para o último caso, ela sugere treinar fora da aplicação e exportar para ONNX quando a necessidade no .NET for somente inferência. Essa orientação deve ser validada contra o contrato de entrada, pré-processamento e saída do modelo.

Instalação recomendada

O README oficial documenta um marketplace próprio para Codex e a instalação individual por URL. Para avaliar somente esta Skill, use um projeto de teste e fixe a pasta auditada:

$skill-installer install https://github.com/dotnet/skills/tree/fbeeafe261b0fe704b9a95c58fd9fdbe34e96964/plugins/dotnet-ai/skills/technology-selection

Leia a origem do instalador, confira o diretório de destino e compare os arquivos gravados. A alternativa do marketplace instala um conjunto maior e deve ser escolhida somente quando a equipe quer administrar o plugin .NET completo. Registrar um marketplace não concede acesso automático aos repositórios, feeds ou contas, mas amplia a quantidade de instruções disponíveis ao agente.

O ZIP local do Bastidores é um recorte documental. Extraia-o preservando SKILL.md ao lado da pasta references. Não copie apenas o arquivo principal se pretende pedir implementação, porque ele aponta para sete referências relativas. Mantenha LICENSE e ORIGEM.md para conservar licença, commit, escopo e hash da auditoria.

Configuração antes do primeiro uso

Descreva o problema sem começar por uma ferramenta. Informe o tipo de entrada, a decisão ou saída esperada, frequência, volume, latência, privacidade, necessidade de operação offline, orçamento e ambiente de hospedagem. Diga explicitamente se a tarefa pede somente decisão arquitetural ou autoriza alteração de código.

Para dados estruturados, registre a coluna alvo, exemplos, métrica aceitável e separação entre treino e teste. Para texto generativo, registre provedor permitido, modelo, formato de saída, timeout e fallback. Para RAG, informe corpus, atualização, estratégia de ingestão, armazenamento vetorial e requisito de citação. Para agentes, liste ferramentas, aprovação, número máximo de iterações e teto de custo.

Separe configuração e segredo. Chaves não devem aparecer em appsettings.json versionado, exemplos ou prompts. O projeto deve carregar credenciais por user-secrets, variável protegida ou cofre adequado. Um plano pode ser produzido sem nenhuma chave. A presença de um exemplo de pacote não autoriza instalar dependências nem chamar serviços.

Primeiro uso seguro

Comece com uma solicitação de arquitetura, sem escrita: “classifique esta tarefa, escolha a menor camada .NET adequada, explique por que as outras rotas não se aplicam e liste as verificações antes de implementar”. Forneça um cenário pequeno, por exemplo classificar chamados por categoria usando dados já rotulados. A resposta correta deve considerar ML.NET antes de sugerir um LLM.

Faça um segundo teste com uma função de resumo de texto sem ferramentas. Nesse caso, o agente deve escolher Microsoft.Extensions.AI e IChatClient, não Agent Framework. Compare a decisão com a referência LLM integration e com a documentação oficial antes de copiar qualquer versão de pacote.

Só depois autorize uma implementação mínima em branch isolada. Exija diff, build e testes existentes. Não conecte dados privados no primeiro ensaio. Se a rota depender de nuvem, use uma conta de desenvolvimento com orçamento limitado. Se depender de modelo local, meça memória e latência no hardware real antes de tratar “local” como sinônimo de barato ou rápido.

Como o fluxo deve funcionar

1. Defina a tarefa: descreva entrada, saída, qualidade, volume, latência, privacidade e custo.
2. Classifique a carga: separe ML tabular, LLM direto, agente, RAG, ONNX, Copilot ou modelo local.
3. Escolha a menor camada: não use orquestração quando uma chamada direta ou uma função determinística resolve.
4. Registre a justificativa: diga por que a rota escolhida atende e por que as alternativas foram descartadas.
5. Abra a referência certa: em implementação, leia somente o arquivo da ramificação selecionada.
6. Confirme versões: verifique pacotes NuGet, status de prévia, compatibilidade e notas de versão atuais.
7. Proteja configuração: mantenha segredos fora do código e defina timeout, cancelamento e limites.
8. Implemente o menor recorte: altere uma branch ou cópia controlada, sem ampliar o objetivo.
9. Valide: execute build, testes existentes e métricas adequadas ao tipo de solução.
10. Documente o limite: registre o que não foi medido, o que depende de provedor e o que ainda precisa de revisão.

A rota de ML clássico está detalhada em classic-ml.md. Agentes usam agentic.md. RAG usa rag.md. As três não devem ser abertas por rotina se o pedido não pede código.

Resultado esperado

Em uma tarefa de seleção, a entrega esperada é curta e auditável: classificação do problema, tecnologia escolhida, justificativa, pré-requisitos, riscos, perguntas abertas e próximo teste. Uma boa resposta não termina em “use IA”. Ela identifica, por exemplo, ML.NET para classificação tabular, IChatClient para uma interação direta ou Microsoft Agent Framework quando existe um loop real de ferramentas.

Em uma implementação, o resultado deve respeitar a abstração escolhida, registrar versões e manter o provedor fora da regra de negócio quando a rota usa Microsoft.Extensions.AI. ML.NET precisa de semente, conjunto de teste e métricas reais. RAG precisa de ingestão, cache de embeddings, limiar de relevância e fontes. ONNX precisa validar nomes, tipos e dimensões do modelo e reutilizar a sessão.

A Skill não garante desempenho, economia, segurança ou adequação regulatória. Ela oferece um ponto de partida para não começar pela tecnologia mais chamativa. O aceite continua dependendo de dados do projeto, testes reproduzíveis e revisão do time responsável.

Permissões, privacidade e riscos

O pacote baixado é somente texto. O uso funcional, porém, pode levar o agente a ler e editar código, instalar pacotes, executar dotnet build e testes, abrir rede, acessar modelos locais ou enviar dados a serviços externos. Conceda essas permissões separadamente e somente depois de aprovar a rota escolhida.

As referências usam versões amplas como 9.*, 4.* e pacotes em prévia. Isso é orientação do commit auditado, não um lockfile pronto para produção. Revalide cada pacote e evite atualizar toda a solução para acomodar um exemplo. O overview oficial do ML.NET e a documentação de cada componente devem prevalecer sobre um trecho desatualizado.

Em modelos hospedados, proteja chaves, dados enviados, logs e localização do processamento. Em execução local, examine licença e origem do modelo, consumo de disco, memória e exposição do endpoint. Em agentes, aplique limite de iterações, ferramentas tipadas, aprovação e teto de custo fora do prompt. Código gerado permanece código não revisado até passar por inspeção, build e testes.

Erros comuns

• LLM para qualquer previsão: teste primeiro se o problema é estruturado e cabe em ML.NET ou em uma regra determinística.
• Agent Framework para uma resposta simples: use IChatClient quando não existe orquestração de vários passos.
• RAG tratado como prompt grande: separe ingestão, chunking, embeddings, busca, relevância e atribuição.
• ONNX sem contrato: valide entradas, dimensões, pré-processamento e saídas antes de servir inferência.
• Local sem medição: Ollama exige modelo presente e hardware compatível; meça latência e memória.
• Versão curinga copiada: fixe versões compatíveis e revise componentes em prévia.
• Chave no repositório: mova segredo para configuração protegida e troque credenciais já expostas.
• Plano que vira código: mantenha o agente sem escrita quando o pedido é somente decisão.
• Métrica inventada: relate apenas build, teste, custo, qualidade e latência realmente observados.
• Abstrações misturadas: não combine cliente HTTP cru e Microsoft.Extensions.AI na mesma regra de negócio sem motivo documentado.

Versão, licença e origem verificadas

Em 7 de setembro de 2026, a API pública do GitHub registrou 5.382 estrelas, repositório público, não arquivado, branch padrão main e HEAD fbeeafe261b0fe704b9a95c58fd9fdbe34e96964. O blob do arquivo principal é 836b3d667406f530cbbfb3106abceff9200e3005. O commit auditado alterou o repositório no mesmo dia da consulta.

O repositório possui a tag v1.0.0, mas ela é anterior ao commit auditado. Há também uma release operacional chamada skill-validator-nightly. O SKILL.md não declara uma versão semântica própria, por isso a curadoria usa commit e blob como identificadores e não chama a Skill de versão 1.0.0.

A licença MIT permite redistribuição com preservação do aviso. O ZIP tem 12.975 bytes e SHA-256 1a684846dc3b47926632381357a518e9ecf9cd8b247f9960f587a11cc8100144. Ele contém exatamente dez arquivos: SKILL.md, sete referências Markdown, LICENSE e ORIGEM.md.

Checklist antes de automatizar

• Definir problema, entrada, saída, dados, volume, latência e privacidade.
• Escolher entre ML.NET, MEAI, Agent Framework, Copilot SDK, RAG, ONNX e Ollama.
• Registrar por que a menor camada atende ao requisito.
• Manter plano e implementação como autorizações separadas.
• Fixar commit da Skill e versões dos pacotes escolhidos.
• Revisar status de prévia e compatibilidade com o projeto real.
• Manter chaves e endpoints fora do código versionado.
• Limitar rede, arquivos, comandos, custo e dados do primeiro teste.
• Executar build e testes existentes após qualquer alteração.
• Medir somente métricas apropriadas e realmente observadas.
• Registrar limites, fallback e critérios de rollback.

Fontes primárias

• Repositório oficial dotnet/skills
• Pasta da Skill no commit auditado
• SKILL.md fixado
• Referência de ML.NET
• Referência de Microsoft.Extensions.AI
• Referência de Agent Framework
• Referência de RAG e vetores
• Referência do GitHub Copilot SDK
• Referência de ONNX Runtime
• Referência de OllamaSharp
• Microsoft Learn, desenvolver aplicações .NET com IA
• Microsoft Learn, ecossistema .NET + AI
• Microsoft Learn, visão geral do ML.NET
• Microsoft Learn, visão geral do Agent Framework
• ONNX Runtime, início com C#
• Repositório oficial OllamaSharp