Autor: magoolation

Segundo artigo da série que acompanha as aulas da Capacitação Microsoft AI 2026. Na aula 1 chegamos ao modelo com a montagem mínima; nesta aula a montagem é exatamente a mesma — o que muda é o que colocamos no contexto.

• ▶️ Gravação da aula e playlist completa no YouTube
• 💻 Código da aula (.NET) · versão Python
• 📑 Slides em PDF

O que a aula cobriu

Como um modelo grande de linguagem funciona por dentro — tokens, probabilidade, janela de contexto — e o que isso significa para quem escreve o prompt. Depois, três técnicas na prática, todas sobre os mesmos três chamados de suporte, para que a comparação seja honesta: chat com histórico no cliente, few-shot e saída estruturada.

Três ideias para levar

1. Quem guarda o histórico: o serviço ou o cliente?

Na aula 1 o programa guardava só um ConversationId e o serviço lembrava a conversa. Aqui fazemos o oposto: uma List<ChatMessage> que cresce a cada turno e é enviada inteira. Mesmo IChatClient, mesmo endpoint, mesma identidade. A escolha não é de tecnologia, é de arquitetura: histórico no cliente dá controle total sobre o que entra no contexto (e sobre o custo em tokens); histórico no serviço simplifica o código e facilita retomar conversas.

2. Few-shot não é um recurso da API, é uma conversa fictícia

Em vez de descrever o formato de resposta que você quer, você mostra: monta uma conversa em que o assistente “já respondeu” daquele jeito e entrega como se tivesse acontecido. O modelo continua o padrão. Na demo, zero-shot devolve markdown livre; few-shot devolve Acesso | Alta | ... em uma linha.

List<ChatMessage> exemplos =
[
    new(ChatRole.System, "Você classifica chamados de suporte. Responda SEMPRE em uma única linha, no formato: Categoria | Urgência | Resumo."),
    new(ChatRole.User, "O sistema fechou sozinho quando cliquei em salvar."),
    new(ChatRole.Assistant, "Erro | Alta | Aplicação encerra ao salvar."),
    // ... mais dois pares
];

List<ChatMessage> mensagens = [.. exemplos, new ChatMessage(ChatRole.User, chamado)];
var resposta = await chatClient.GetResponseAsync(mensagens);

3. Saída estruturada: um record em vez de texto solto

Quando a resposta vai alimentar código — e não uma pessoa — pedir “com jeitinho” não basta. GetResponseAsync<T>() gera um JSON Schema a partir do seu record, envia junto com o prompt e desserializa a resposta. O modelo fica obrigado pelo serviço a produzir JSON válido naquele formato.

record TriagemChamado(string Categoria, string Urgencia, string Resumo, bool RequerAtencaoImediata);

var resposta = await chatClient.GetResponseAsync<TriagemChamado>(mensagens);
TriagemChamado triagem = resposta.Result;

Antes de rodar

• Tudo o que valia na aula 1: .NET 10, Azure CLI com az login, papel Foundry User, FOUNDRY_ENDPOINT (do projeto) e FOUNDRY_MODEL (nome do deployment).
• Os pacotes são os mesmos e nas mesmas versões. Microsoft.Extensions.AI e Microsoft.Extensions.AI.OpenAI ficam em 10.4.1 — é a única versão compatível com o OpenAI 2.9.1 que os pacotes Azure exigem. Subir sem --version compila e quebra em runtime.
• O <NoWarn>OPENAI001</NoWarn> no .csproj não é opcional: AsIChatClient() ainda é experimental e o SDK promove o aviso a erro.

Se você está na trilha Python

As três demos existem em Python: histórico numa lista de mensagens, few-shot do mesmo jeito, e saída estruturada com Pydantic no lugar do record. Mesmo AIProjectClient e mesmo endpoint da aula 1.

Próximo passo

Rode a demo 2 duas vezes com o mesmo chamado — uma zero-shot, outra few-shot — e compare as respostas. Depois troque um dos exemplos do few-shot e veja como o modelo segue o novo padrão. Na aula 3 entramos no Microsoft Foundry de verdade: recurso, projeto, deploy de modelos e o SDK com resposta em streaming.

Dúvidas ou algo que não funcionou? Deixe nos comentários ou abra uma issue no repositório.

Este é o primeiro de oito artigos que acompanham as aulas da Capacitação Microsoft AI 2026, que Otávio Lourenço da Silva e eu ministramos ao vivo entre agosto e setembro. As gravações continuam no ar; os artigos existem para quem prefere ler, revisar ou copiar o código com calma.

• ▶️ Gravação da aula e playlist completa no YouTube
• 💻 Código da aula (.NET) · versão Python
• 📑 Slides em PDF

O que a aula cobriu

A primeira aula constrói a base que todas as outras usam: o que é IA generativa e onde ela se encaixa no ecossistema Microsoft (Copilot, Microsoft Foundry, Azure), e o caminho mínimo — e correto — entre uma aplicação e um modelo hospedado no Foundry. Saímos da aula com um chat de console funcionando, e com três decisões de arquitetura que se repetem em todo o curso.

Três ideias para levar

1. Autenticação sem segredo

Não existe chave de API no código. O Foundry SDK autentica sempre por Entra ID: DefaultAzureCredential descobre quem você é a partir do ambiente (az login na sua máquina, identidade gerenciada em produção) e o mesmo código roda nos dois lugares sem alteração. Não há segredo para vazar em log, repositório ou print de tela.

O tropeço clássico vem logo depois: ser Owner da subscription não basta. O Azure separa permissões de gerenciamento (criar e apagar recursos) de permissões de dados (conversar com o modelo). Owner tem as primeiras e nenhuma das segundas — você autentica com sucesso e recebe 403 Forbidden. O papel que resolve é o Foundry User, atribuído no recurso Foundry.

2. Uma abstração entre você e o fornecedor

Entramos pelo AIProjectClient (o Foundry SDK), pegamos um cliente de Responses para o deployment do modelo e o convertemos em um IChatClient de Microsoft.Extensions.AI. Daí para cima, o código não menciona mais nem Azure nem OpenAI. Trocar o modelo por um Ollama local é mexer nestas três linhas — e em nada mais.

AIProjectClient projectClient = new(
    endpoint: new Uri(endpoint),
    tokenProvider: new DefaultAzureCredential());
ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient
    .GetProjectResponsesClientForModel(model);
IChatClient chatClient = responseClient.AsIChatClient(model);

3. Contexto mantido pelo serviço

O chat lembra o que foi dito antes, mas o programa não guarda histórico nenhum: ele guarda apenas um ChatOptions.ConversationId e o serviço cuida do resto. Na aula 2 fazemos o oposto — o histórico numa lista que cresce no cliente — com o mesmo IChatClient, justamente para comparar as duas estratégias.

Antes de rodar

• .NET SDK 10 e Azure CLI instalados, com az login feito no tenant certo.
• Um recurso Foundry com um modelo implantado e o papel Foundry User atribuído à sua conta.
• As variáveis FOUNDRY_ENDPOINT (endpoint do projeto) e FOUNDRY_MODEL (nome do deployment, não o nome comercial do modelo) no seu launchSettings.json.
• Não altere as versões dos pacotes. O projeto converge para um pivô único (OpenAI 2.9.1); subir qualquer pacote compila e quebra em tempo de execução. O README da aula explica a matriz de versões.

Se você está na trilha Python

A mesma aula existe em Python 3.12+: AIProjectClient, cliente OpenAI e contexto no serviço via previous_response_id. Em Python não existe o problema do pivô de versões do .NET, e um único endpoint do projeto serve todas as aulas — mas a regra de fixar versões no requirements.txt continua valendo.

Próximo passo

Rode o chat, faça duas perguntas encadeadas e confirme que o modelo lembra a primeira. Depois abra o Program.cs e leia os comentários — eles foram escritos para serem lidos, não só para explicar o código. Na aula 2 entramos em LLMs e engenharia de prompts: contexto no cliente, few-shot e saída estruturada.

Dúvidas ou algo que não funcionou? Deixe nos comentários ou abra uma issue no repositório.

Este artigo foi publicado em 2019. Ferramentas e versões citadas podem ter mudado desde então; a reflexão permanece.