O guia de início rápido para o Microsoft Foundry Agent Service é escrito para Python. Ele esconde a complexidade de infraestrutura do Azure dentro de um scaffolding tão denso que você pode terminar o tutorial sem saber quais recursos foram realmente criados. Se você desenvolve em .NET, começa com uma desvantagem: os exemplos apontam para a direção errada, os nomes dos pacotes mudam sem aviso e o recente rebranding de Azure AI Foundry para Microsoft Foundry deixou dois conjuntos de documentação competindo nos resultados de busca.

Recentemente, construí meu primeiro agente em C#. O serviço funciona bem assim que você remove o ruído e separa as etapas essenciais da confusão da versão preview. Aqui está o mapa que eu gostaria de ter tido no primeiro dia.

Os Quatro Recursos de que Você Realmente Precisa

Você não precisa de uma dúzia de serviços do Azure para executar um Prompt Agent básico. Você precisa de exatamente quatro coisas, e a CLI as torna visíveis de uma forma que os notebooks de Python não fazem.

Primeiro, um recurso Foundry com o tipo AIServices. Ele atua como a capacidade pai para os modelos que você chamará. Segundo, um projeto dentro desse recurso. O projeto é o escopo onde residem as definições do seu agente, os threads de conversa e as configurações de implantação. Terceiro, um modelo implantado. Sem uma implantação ativa, o agente não tem um endpoint para invocar. Quarto, uma atribuição de função (role assignment) para sua própria identidade, para que o SDK possa se autenticar no projeto.

É só isso. Sem cluster Kubernetes, sem computação personalizada, sem cache Redis gerenciado manualmente para o histórico de conversas.

Prompt Agents versus Hosted Agents

O Foundry oferece duas maneiras de executar agentes. Não escolha por padrão a opção mais complexa.

Prompt Agents são o caminho mais simples. Você escolhe um modelo, escreve as instruções do sistema e o Foundry executa o agente para você. Você não gerencia computação, contêineres ou lógica de roteamento. Isso é ideal para ferramentas internas, bots de helpdesk e respostas diretas a perguntas sobre documentos.

Hosted Agents exigem que você escreva o código da aplicação, o empacote como um contêiner e o conecte ao Foundry. Você escolhe este caminho apenas quando precisa de uma lógica de negócio personalizada que o Foundry não consegue expressar por meio de prompts e ferramentas integradas, como chamar uma API interna com autenticação não padronizada.

Este guia foca em Prompt Agents porque eles são a maneira mais rápida de validar se sua configuração .NET está correta antes de você investir em arquivos Docker e orquestração.

Configuração via Linha de Comando

Usar a CLI força você a ver cada recurso, que é exatamente o que o guia de início rápido de Python obscurece. Crie um grupo de recursos em East US 2. A escolha da região é importante aqui. O Foundry lança o suporte a ferramentas de forma desigual, e o East US 2 possui atualmente o conjunto mais amplo. Se você escolher uma região que não possua o interpretador de código ou as ferramentas de busca de arquivos, sua chamada de criação de agente falhará com um erro obscuro sobre capacidades não suportadas.

Crie o recurso Foundry com a flag --allow-project-management. Sem essa flag, o recurso permanece um endpoint de serviços cognitivos independente e não aceitará as implantações com escopo de projeto que os agentes exigem. Em seguida, crie o projeto, implante seu modelo e atribua a si mesmo a função Foundry User.

Use o GUID da função estável em vez do nome de exibição:

53ca6127-db72-4b80-b1b0-d745d6d5456d

Os nomes das funções se propagam pelo Azure Active Directory em velocidades diferentes, dependendo do tenant. Uma organização vê o Foundry User no portal hoje; outra não o verá por dias. O GUID aponta diretamente para a definição e não falhará durante a implementação. Esse único detalhe pode economizar uma hora de depuração de erros de "permissão negada" que parecem problemas de política, mas são, na verdade, problemas de resolução de rótulos.

Evite o Pacote NuGet Errado

É aqui que os desenvolvedores .NET costumam ficar presos. Você verá referências a Azure.AI.Projects.OpenAI em trechos de código mais antigos. Esse pacote é apenas para preview e se sobrepõe ao Azure.AI.Extensions.OpenAI. Ambos definem métodos de extensão e tipos em namespaces semelhantes. Se você os instalar lado a lado, sua compilação falhará com erros de referência ambígua que