Capacitação Microsoft AI — Aula 7: agentes avançados, ferramentas e aprovação humana

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

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.