Autor: magoolation

Playlist completa no YouTube · Código .NET da aula 7 · Código Python da aula 7 · Slides da aula 7 (PDF)

O que a aula cobriu

A aula 7 pega o agente simples da aula 6 e dá a ele mais responsabilidade: ferramentas reais, um passo de aprovação humana antes de ações irreversíveis, acesso à documentação oficial via MCP hospedado, e um fluxo com três agentes trabalhando em sequência.

São quatro demos na mesma base de configuração das aulas anteriores (endpoint, identidade e AIProjectClient não mudam):

• Function calling: quatro ferramentas (consulta a uma base de conhecimento, previsão do tempo, calculadora e um envio de e-mail simulado) criadas com AIFunctionFactory.Create, cada uma documentada com atributos de descrição que o modelo lê para decidir quando chamar.
• Human-in-the-loop: a ferramenta de envio de e-mail é envolvida num wrapper de aprovação. O agente pausa, devolve um pedido de aprovação, e só continua a execução depois que uma pessoa confirma.
• MCP hospedado: o agente ganha acesso a um servidor MCP público de documentação da Microsoft, sem precisar de nenhuma integração customizada — é só mais uma ferramenta na lista.
• Workflow sequencial: três agentes (pesquisador, validador e redator) encadeados, cada um processando a saída do anterior e transmitindo seu resultado em streaming.

Três ideias para levar

1. O modelo nunca executa nada — a sua aplicação executa. Toda ferramenta que você expõe a um agente é só um método comum que a sua aplicação roda quando o modelo pede. Isso significa que validar os parâmetros, nunca devolver segredos e tratar erros com mensagens legíveis (em vez de deixar uma exceção estourar) é responsabilidade sua, não do modelo.

2. Aprovação é uma decisão de wrapper, não da ferramenta. A mesma função de envio de e-mail funciona com ou sem aprovação humana — o que muda é só a camada que envolve ela. Isso separa bem a lógica de negócio da política de segurança: você decide onde exigir aprovação sem tocar no código da ferramenta em si.

// A ferramenta de envio de e-mail só é executada depois de aprovação explícita
var emailTool = new ApprovalRequiredAIFunction(
    AIFunctionFactory.Create(EnviarEmailSimulado)
);

// O agente pausa e devolve um ToolApprovalRequestContent
// em vez de executar direto — a aplicação decide o que fazer com isso

3. Nem todo problema precisa de vários agentes conversando. O workflow sequencial da aula mostra o caso em que faz sentido ter mais de um agente — quando cada etapa precisa de um papel e um contexto diferentes. Mas vale sempre perguntar primeiro se um único agente, num loop simples, não resolveria o mesmo problema por um custo menor.

Antes de rodar

• Confirme que sua conta tem o papel Foundry User no recurso — sem ele, as chamadas à API retornam 403.
• Copie o launchSettings.template.json da aula 6 e ajuste só o nome do perfil.
• Configure as variáveis de ambiente FOUNDRY_ENDPOINT e FOUNDRY_MODEL — o modelo escolhido precisa suportar function calling (use algo da família GPT-5.x caso o agente nunca chame as ferramentas).
• Rode az login --tenant <id> antes do dotnet run, e defina AZURE_TENANT_ID e AZURE_TOKEN_CREDENTIALS=AzureCliCredential para autenticação mais previsível.
• Se o restore reclamar de versões conflitantes entre os pacotes de Workflows e de Foundry (erros NU1608/NU1605), pin as duas na mesma versão.
• A demo 3 precisa de saída de internet do serviço para alcançar o MCP hospedado — confirme que sua rede permite isso.

Se você está na trilha Python

O equivalente em Python está em Python/aula07-agentes-avancados, com main.py e um módulo próprio de ferramentas (ferramentas.py) espelhando as mesmas quatro demos. A lógica de validação de entrada e de não devolver segredos nas respostas das ferramentas vale igual nos dois ecossistemas — é decisão de arquitetura, não de linguagem.

Próximo passo

Na aula 8 fechamos a série com avaliação de agentes: como medir se o que construímos até aqui está realmente funcionando antes de colocar em produção.

Este é o sexto 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

As aulas 1 a 3 já tinham montado a base: mesmo modelo, mesmo recurso Foundry, mesma identidade e o AIProjectClient de sempre. A sexta aula não troca nada disso — ela envolve esse cliente com AsAIAgent(modelo, nome, instruções) e, de repente, você tem um agente. Com nome, com instruções fixas e, a partir daí, com memória de conversa. O agente roda no seu processo; nada é criado do lado do serviço. Não é um recurso novo para provisionar, é uma camada em cima do que já existia.

Três ideias para levar

1. Um agente é o cliente de sempre, só que com nome e instruções

Não existe um serviço de “agentes” separado para criar e gerenciar. AsAIAgent é um método de extensão sobre o client que você já usava desde a aula 3 — ele recebe o nome do deployment, um nome para o agente e as instruções (o equivalente ao system prompt) e devolve um objeto com os mesmos dois jeitos de responder que você já conhecia.

var agente = client.AsAIAgent(
    model: deploymentName,
    name: "Assistente de Férias",
    instructions: "Responda com base na política de férias da empresa.");

var sessao = agente.GetNewSession();
var resposta = await agente.RunAsync("Quantos dias de férias eu tenho por ano?", sessao);

2. RunAsync e RunStreamingAsync continuam sendo a escolha de sempre

RunAsync devolve a resposta completa de uma vez — cada chamada, isolada, começa do zero se você não passar uma sessão. RunStreamingAsync entrega token a token, do mesmo jeito que o streaming de chat das aulas anteriores. A novidade não está no transporte da resposta, está no que vem entre uma chamada e outra.

3. AgentSession tira de você a lista de mensagens

Até a aula 2, manter contexto significava você mesmo acumular uma lista de mensagens e reenviá-la inteira a cada chamada. Com AgentSession, essa lista passa a viver dentro da sessão: você guarda o objeto da sessão, não o histórico, e o framework decide o que mandar de volta ao modelo. Trocar de assunto no meio da conversa, pedir para o agente “lembrar” algo dito três perguntas atrás — isso deixa de ser código seu para ser comportamento do framework.

Antes de rodar

• Pré-requisitos de sempre: .NET SDK 10, az login no tenant certo e um recurso Foundry com um modelo já implantado — mas agora com a função Foundry User atribuída à sua identidade. Ser Owner da subscription não é suficiente; sem esse papel específico, as chamadas do agente voltam com 403.
• A configuração sai de variáveis de ambiente — FOUNDRY_ENDPOINT (o endpoint do projeto) e FOUNDRY_MODEL (o nome do deployment), opcionalmente AZURE_TENANT_ID e AZURE_TOKEN_CREDENTIALS — definidas num launchSettings.json local e fora do controle de versão.
• O único pacote novo é o Microsoft.Agents.AI.Foundry (ainda em prerelease), mais o Azure.Identity de sempre. Ele já traz consigo os pacotes Azure AI e Microsoft.Extensions.AI de que precisa. Adicionar esses pacotes de novo, manualmente, numa versão diferente da que o framework espera, costuma travar em runtime com MissingMethodException — e os erros do NuGet (NU1608/NU1605) no build já avisam antes disso.
• 404 geralmente é endpoint no formato errado; o aviso OPENAI001 aparece quando falta o NoWarn para a API ainda experimental.

Se você está na trilha Python

A mesma aula existe em Python 3.12+, na pasta aula06-agent-framework, com o mesmo AIProjectClient e o mesmo endpoint de projeto que você já vinha usando desde a aula 3. A ideia de sessão e a separação entre resposta completa e streaming se repete; o que muda é só a sintaxe. Fixar versões no requirements.txt continua valendo, pelo mesmo motivo da aula 5: evitar que uma atualização silenciosa do pacote mude o comportamento do agente entre uma aula e a próxima.

Próximo passo

Rode o exemplo sem passar uma sessão entre duas perguntas que dependem uma da outra — deixe ele “esquecer” de propósito — e depois rode de novo passando a mesma AgentSession nas duas chamadas. A diferença entre as duas execuções é a aula inteira resumida em uma demonstração. Na aula 7 esse agente ganha ferramentas, memória de longo prazo e aprende a trabalhar junto com outros agentes.

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

Este é o quinto 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 quinta aula pega o RAG da aula 4, que já funcionava, e faz a pergunta que a aula 4 não conseguia responder: funcionava bem? O corpus e o índice são os mesmos. O que entra é medição: um pipeline que devolve objeto em vez de texto, quatro métricas de qualidade calculadas por um modelo juiz, um conjunto de seis perguntas com gabarito e dois experimentos — a varredura de top-k e a comparação com e sem ranqueamento semântico — que terminam num relatório em Markdown. A ideia que sustenta a aula: RAG não termina quando a resposta aparece na tela; termina quando você consegue dizer, com número, se ela ficou melhor ou pior que ontem, e qual etapa mudou.

Três ideias para levar

1. Um pipeline que só imprime texto não pode ser avaliado

A mudança de arquitetura da aula cabe num tipo de retorno. PipelineRag.ResponderAsync devolve a resposta junto com os trechos recuperados, o contexto exato que foi para o modelo, o modo de busca, o top-k e a latência. Sem esses dados, não há o que comparar — e qualquer “acho que melhorou” vira opinião.

public sealed record RespostaRag(
    string Pergunta,
    string Texto,
    ChatResponse Bruta,
    IReadOnlyList<TrechoCitado> Trechos,
    string Contexto,
    IndiceRag.Modo Modo,
    int TopK,
    TimeSpan Latencia);

2. Groundedness e retrieval são separadas de propósito

As quatro métricas do Microsoft.Extensions.AI.Evaluation.Quality parecem medir a mesma coisa com nomes diferentes, mas cada uma compara um par distinto. Groundedness compara a resposta com o contexto recuperado; relevance, a resposta com a pergunta; retrieval, os trechos com a pergunta; correctness, a resposta com o gabarito. As três primeiras olham para a resposta, e retrieval olha para o que veio antes dela. Se a resposta piorou e o retrieval continua bom, o problema está no prompt ou na geração; se os dois caíram, está no chunking, no embedding ou no índice. O caso perigoso é relevance alta com groundedness baixa: a resposta parece ótima e é inventada.

Ao lado do juiz rodam duas conferências determinísticas, que não custam chamada de modelo: recuperou os documentos esperados? Recusou exatamente quando devia? Quando discordam do juiz, costumam estar certas. Metade de um diagnóstico de queda é um Contains.

3. Meça antes de acreditar — inclusive no slide

Na varredura de top-k (3, 5 e 10), quase todo mundo aposta que 10 é melhor. Com o corpus da aula, a curva sai plana: cinco documentos viram doze chunks, então top-k 10 traz quase tudo e só o custo em tokens sobe. Esse é o resultado certo, e ensina a ler a tabela — retrieval igual com mais tokens quer dizer que você está pagando por nada. Para ver a curva aparecer, basta reindexar com chunks menores. O mesmo vale para o ranqueador semântico: o ganho prometido nos slides vem de corpora grandes e heterogêneos, e num corpus de cinco documentos ele é pequeno, às vezes nulo. O juiz, por sua vez, também é um LLM — erra, é sensível ao próprio prompt e responde em inglês. Não é a verdade; é um instrumento barato o bastante para rodar a cada mudança.

Antes de rodar

• Os mesmos pré-requisitos da aula 4: .NET SDK 10, Azure CLI com az login no tenant certo, um recurso Foundry com deployments de chat e de embeddings e um Azure AI Search no SKU basic ou superior. Se a aula 4 já indexou, o índice desta aula já existe.
• O modelo juiz é, por padrão, o mesmo deployment de chat. A variável FOUNDRY_JUDGE_MODEL existe para usar outro modelo e reduzir o viés de um modelo se avaliar bem.
• O endpoint continua sendo o /openai/v1, como na aula 4, e as versões dos pacotes não devem ser alteradas. Os dois pacotes de avaliação entram sem mudar o pivô OpenAI 2.12.0, porque falam com o modelo por IChatClient — o argumento mais prático a favor da abstração.
• As opções que avaliam o conjunto inteiro fazem dezenas de chamadas ao juiz. Se aparecer 429, é cota do deployment: o código já limita a três perguntas simultâneas, e dá para baixar para uma.

Se você está na trilha Python

A mesma aula existe em Python 3.12+, na pasta aula05-rag-avancado, com o pacote azure-ai-evaluation fazendo o papel de juiz — groundedness, relevance, retrieval e similarity com o gabarito — e a mesma varredura de top-k e o mesmo relatório. Em Python não existe o problema de pivô: a versão Python usa o mesmo AIProjectClient e o mesmo endpoint de projeto das aulas anteriores. Fixar versões no requirements.txt continua valendo.

Próximo passo

Comece avaliando uma única pergunta: a sexta do conjunto, cujo assunto está no corpus mas cuja resposta não está. O sistema recusa, groundedness e correctness tiram nota máxima e retrieval tira nota baixa — porque os trechos, de fato, não respondem à pergunta. Métrica não é nota de prova; é instrumento, e quem interpreta é você. Depois rode a varredura de top-k, anote seu palpite antes e grave o relatório: é ele que você compara na semana seguinte. Na aula 6 saímos do RAG e construímos o primeiro agente com o Microsoft Agent Framework.

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

Este é o quarto 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 quarta aula junta as três anteriores — o modelo do Foundry e a abstração do Microsoft.Extensions.AI — com um índice vetorial no Azure AI Search. O corpus é um conjunto de políticas internas de uma empresa fictícia, escrito de propósito para que algumas perguntas só ele responda, e para que uma pergunta pareça estar nele e não esteja. É essa segunda situação que sustenta toda a discussão sobre groundedness: o modelo tem que saber admitir quando não sabe, mesmo com os documentos na mão.

Três ideias para levar

1. Chunking é um parâmetro, não um detalhe escondido

O projeto quebra o texto por parágrafo e junta vizinhos até ~800 caracteres — deliberadamente simples, e deliberadamente exposto como parâmetro. Mudar esse número e reindexar, ao vivo, é o experimento mais barato da aula: chunks pequenos demais perdem contexto, chunks grandes demais diluem o sinal na média.

// Chunking por parágrafo, até ~800 caracteres
var chunks = IndiceRag.Fatiar(\n    texto,\n    tamanhoAlvo: 800);

2. Keyword, vetorial e híbrida acertam coisas diferentes

A busca por palavra-chave (BM25) acerta códigos, siglas e nomes próprios, mas erra sinônimos. A busca vetorial acerta sentido e paráfrase, mas erra identificadores literais. A híbrida soma os dois com reranking semântico — acerta ambos os casos, ao custo de mais latência. Ver os três modos lado a lado, com os scores visíveis, é o que desfaz a ideia de que RAG é uma caixa-preta única.

3. RAG não é sempre a resposta certa

O roteiro de sala faz a mesma pergunta com e sem RAG, três vezes. A primeira mostra o modelo inventando um valor plausível sem os documentos, e citando a fonte certa com eles — o caso óbvio. A segunda mostra RAG atrapalhando: uma pergunta que o modelo já respondia bem ganha uma citação desnecessária, gastando tokens e latência à toa. A terceira é a que vale a aula: um assunto que está no corpus mas cuja resposta específica não está — e o comportamento certo é admitir a ausência, não inventar uma política inteira.

Antes de rodar

• .NET SDK 10 e Azure CLI instalados, com az login feito no tenant certo.
• Um recurso Foundry com dois deployments — um de chat e um de embeddings (text-embedding-3-small) — e um serviço Azure AI Search no SKU basic ou superior (o free não tem ranqueamento semântico).
• Os papéis Search Service Contributor e Search Index Data Contributor no Search, concedidos tanto à sua conta quanto à identidade gerenciada do recurso Foundry — são identidades diferentes, e esquecer a segunda é a causa mais comum de 403 no playground.
• Não altere as versões dos pacotes. O projeto converge para OpenAI 2.12.0; adicionar Azure.AI.Projects recria o conflito de pivô das aulas anteriores.

Se você está na trilha Python

A mesma aula existe em Python 3.12+, na pasta aula04-rag: chunking, embeddings e os três modos de busca — keyword, vetorial e híbrida com reranking — com o mesmo corpus e o mesmo roteiro de sala. A regra de fixar versões no requirements.txt continua valendo.

Próximo passo

Rode o console, indexe o corpus e compare os três modos de busca com uma pergunta que usa sinônimos — a diferença entre keyword e vetorial fica evidente em uma tela. Depois rode o roteiro de sala completo e observe a terceira pergunta: é o slide de groundedness. Na aula 5 entramos em RAG end-to-end com avaliação — groundedness, relevância e uma varredura de top-k.

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

Este é o terceiro 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 terceira aula é a aula da plataforma. Passamos pela arquitetura do Microsoft Foundry — a diferença entre recurso e projeto, os papéis de acesso (RBAC), as conexões com AI Search, Storage e Key Vault, o deploy de um modelo pelo portal e a escolha entre Standard e PTU — e depois voltamos ao código para fechar um ciclo que começou na aula 1. O programa desta aula usa o mesmo modelo, a mesma identidade, o mesmo SDK e o mesmo IChatClient da aula de Fundamentos, com uma única diferença: a resposta chega token a token, em vez de inteira, de uma vez só.

Três ideias para levar

1. Recurso, projeto e papel: a plataforma antes do código

No Foundry, o recurso é a unidade de infraestrutura — é nele que os modelos são implantados e que as conexões com outros serviços do Azure são registradas. O projeto é a unidade de trabalho, com endpoint próprio, e é a ele que a aplicação se conecta: o FOUNDRY_ENDPOINT de todas as aulas termina em /api/projects/<projeto>. E o papel que a sua identidade precisa ter é o Foundry User, atribuído no recurso: ser Owner da subscription concede Actions (criar e apagar), mas chamar o modelo exige DataActions. Quem aprende essa separação uma vez para de esbarrar em 403 Forbidden.

2. Streaming é uma troca de método, não de arquitetura

O setup é idêntico ao da aula 1 — AIProjectClient autenticado por DefaultAzureCredential, cliente de Responses para o deployment e conversão em IChatClient. A diferença cabe no laço final: GetResponseAsync vira GetStreamingResponseAsync, que devolve um IAsyncEnumerable<ChatResponseUpdate>. Cada atualização já traz o texto em .Text, sem testar tipo nenhum, e o mesmo laço funcionaria contra qualquer outro provedor.

ChatOptions options = new();

await foreach (ChatResponseUpdate update
    in chatClient.GetStreamingResponseAsync(prompt, options))
{
    Console.Write(update.Text);              // pedaço de texto

    if (update.ConversationId is not null)
    {
        options.ConversationId = update.ConversationId;   // elo da próxima pergunta
    }
}

Vale rodar esta demo e a de Fundamentos lado a lado, com a mesma pergunta: a percepção de latência muda sem que nada além do método chamado tenha mudado.

3. O contexto continua no serviço — e chega junto com o fluxo

Como na aula 1, o programa não guarda histórico: guarda apenas o ConversationId e o serviço cuida do resto. A sutileza do streaming é que esse id chega junto com as atualizações e só é definitivo no fim, por isso o código guarda o último valor não nulo em vez de assumir que ele veio na primeira. Comparado com a aula 2, onde o histórico vive numa lista no cliente, fica claro que a decisão de quem guarda o contexto é independente da decisão de como a resposta é consumida.

Antes de rodar

• .NET SDK 10 e Azure CLI instalados, com az login --tenant <tenant-id> feito no tenant certo.
• Um recurso Foundry com um modelo implantado e o papel Foundry User atribuído à sua conta — ser Owner da subscription não basta.
• As variáveis FOUNDRY_ENDPOINT (endpoint do projeto, terminando em /api/projects/<projeto>) e FOUNDRY_MODEL (nome do deployment) no seu launchSettings.json. Um único arquivo serve as três primeiras aulas — basta trocar o nome do perfil.
• Não altere as versões dos pacotes. O projeto converge para o pivô OpenAI 2.9.1; dotnet add package OpenAI, o Azure.AI.Extensions.OpenAI em prerelease ou o Microsoft.Extensions.AI.OpenAI sem versão compilam sem aviso e quebram em tempo de execução com MissingMethodException. O NoWarn de OPENAI001 no .csproj também não é opcional.

Se você está na trilha Python

A mesma aula existe em Python 3.12+: AIProjectClient com DefaultAzureCredential, cliente OpenAI obtido do projeto, stream=True para a resposta token a token e contexto no serviço via previous_response_id. A versão Python vai um pouco além: retry exponencial em erros transientes (429 e 5xx) com tenacity, contagem local de tokens com tiktoken para estimar custo antes de rodar em lote, e saída formatada com rich. As versões ficam fixadas no requirements.txt.

Próximo passo

Faça um diff entre o Program.cs desta aula e o da aula 1: as seções de setup são idênticas e a diferença cabe no laço final. Depois, se quiser ver o problema de versões ao vivo, rode dotnet add package OpenAI, compile com sucesso, veja o erro em tempo de execução e desfaça — ensina mais sobre grafo de dependências do que qualquer slide. Na aula 4 entramos em RAG, embeddings e Azure AI Search: como dar ao modelo o contexto da sua empresa sem treinar nada.

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