microsoft-foundry

Visão geral

O que é o skill microsoft-foundry?

O skill microsoft-foundry é um conjunto selecionado de fluxos de trabalho e docs de referência que orientam você pelo ciclo de vida completo de agentes do Azure AI Foundry. Ele é focado em implantação e operação na prática:

• Criação de agentes prompt e hosted
• Construção de imagens Docker e push para o Azure Container Registry (ACR)
• Implantação de agentes no Azure AI Foundry
• Configuração de projects, RBAC, quota e connections
• Execução de evaluation datasets e gerenciamento de agent-metadata.yaml
• Configuração de agentes em ambientes standard e private-network
• Ativação de observability, tracing e troubleshooting

Todo o conteúdo vem do repositório microsoft/azure-skills e é estruturado para que você consiga operacionalizar agentes no Azure AI Foundry sem precisar fazer engenharia reversa do layout do repositório.

Para quem é esse skill?

Use microsoft-foundry se você é:

• Um(a) engenheiro(a) de backend ou de plataforma responsável por implantar e operar agentes do Azure AI Foundry
• Um(a) engenheiro(a) de IA/ML levando protótipos para um projeto Foundry em produção
• Um(a) desenvolvedor(a) integrando agentes Foundry com serviços existentes, SDKs ou ferramentas MCP
• Um(a) responsável técnico que precisa dimensionar RBAC, cota, rede privada e configuração de ambiente

Se você só precisa de implantação básica de infraestrutura Azure (App Service, Functions, web apps genéricas), esse skill não é o ideal — use em vez disso um skill de implantação Azure mais genérico.

Quais problemas o microsoft-foundry resolve?

O skill foi criado para resolver desafios recorrentes como:

• "Como estruturo meu repositório de agente para o Foundry?"
  Use as orientações em references/agent-metadata-contract.md para o layout de .foundry/ e os campos de agent-metadata.yaml.

• "Como crio e implanto agentes de forma consistente?"
  Use os fluxos foundry-agent/create e foundry-agent/deploy para criar agentes prompt/hosted, montar containers, enviar para o ACR e iniciar containers de agente.

• "Como configuro projects, connections, RBAC e quota?"
  Siga project/create, rbac/rbac.md e quota/quota.md para configurar projetos, atribuir funções e planejar capacidade.

• "Como avalio e observo meus agentes?"
  Use foundry-agent/eval-datasets, foundry-agent/observe e foundry-agent/trace para rodar evals em lote, gerenciar datasets e evaluators e conectar a recursos de observability.

• "Como lido com setups standard vs private-network?"
  Use references/standard-agent-setup.md e references/private-network-standard-agent-setup.md para escolher e configurar o modelo de rede correto.

Quando o microsoft-foundry é uma boa escolha?

Use este skill quando você precisar:

• Implantar agentes prompt ou hosted no Azure AI Foundry
• Padronizar a estrutura de projetos de agente com .foundry/agent-metadata.yaml
• Integrar ferramentas MCP e SDKs do Azure em um fluxo de trabalho repetível
• Gerenciar RBAC, quota e planejamento de capacidade para cargas de agentes
• Executar evaluation datasets e acompanhar resultados entre ambientes
• Configurar observability com Application Insights e traces
• Implantar em configurações standard ou private-network (VNet)

Não use este skill quando você só precisar de:

• Implantação genérica de apps Azure (web apps, Functions, App Service)
• Preparação de alto nível de conta ou assinatura Azure

Nesses casos, complemente este skill com skills mais gerais de implantação/preparação Azure ou use um skill dedicado como azure-deploy / azure-prepare.

Como usar

Instalação

Para adicionar microsoft-foundry a partir do repositório microsoft/azure-skills, instale com:

npx skills add https://github.com/microsoft/azure-skills --skill microsoft-foundry

Isso torna os fluxos de trabalho e o conteúdo de referência do microsoft-foundry disponíveis para seu agente ou ambiente de ferramentas. Após a instalação, o ponto de entrada principal é o arquivo SKILL.md na pasta skills/microsoft-foundry.

Estrutura do repositório e pastas principais

Depois de instalar o skill ou abri-lo no repositório, você verá a seguinte estrutura:

• SKILL.md – índice principal do skill e lista de sub-skills
• foundry-agent/ – fluxos de trabalho ponta a ponta para agentes individuais
  • create/ – criação de agentes prompt ou hosted
  • deploy/ – build e deploy de agentes, incluindo containers e ACR
  • eval-datasets/ – gerenciamento de eval datasets e execuções de avaliação
  • invoke/ – invocação de agentes existentes
  • observe/ – fluxos de configuração de observability e monitoramento
  • trace/ – coleta de trace e criação de datasets a partir de traces
  • troubleshoot/ – orientações de troubleshooting para execuções com falha
• project/
  • create/ – criação e configuração de projetos Azure AI Foundry
  • connections.md – orientações para connections em nível de projeto
• rbac/
  • rbac.md – funções RBAC, permissões e padrões comuns
• quota/
  • quota.md – guia de quota e planejamento de capacidade
  • references/ – capacidade, resolução de erros, otimização
• references/
  • agent-metadata-contract.md – layout de .foundry/ e agent-metadata.yaml
  • auth-best-practices.md – padrões de autenticação Azure e RBAC
  • standard-agent-setup.md – configuração de agentes standard (não isolados)
  • private-network-standard-agent-setup.md – configuração com VNet/private-link
  • sdk/ – referências de operações via SDK para quando ferramentas MCP não estiverem disponíveis

Comece por SKILL.md para entender os sub-skills e depois aprofunde na pasta do cenário específico.

Fluxo de trabalho rápido: do projeto ao agente implantado

Esta seção descreve um caminho prático usando o conteúdo do skill microsoft-foundry.

1. Criar ou preparar seu projeto Foundry

1. Abra project/create/create-foundry-project.md.
2. Siga as etapas para:
   • Criar um Azure AI Foundry project
   • Confirmar o project endpoint (por exemplo, https://<resource>.services.ai.azure.com/api/projects/<project>)
   • Vincular as connections necessárias (Cosmos DB, Storage, Azure AI Search etc.) conforme exigido para o setup standard
3. Revise project/connections.md para garantir que suas connections de thread storage, file storage e vector store estejam corretamente configuradas, especialmente se você pretende usar standard agent setup.

2. Configurar RBAC e autenticação

1. Leia rbac/rbac.md para verificar:
   • Quais funções são necessárias (Owner, Contributor, User Access Administrator etc.) no resource group e nos recursos Foundry
   • Como atribuir funções seguindo as práticas recomendadas de RBAC no Azure
2. Abra references/auth-best-practices.md e aplique as recomendações:
   • Use managed identities e Azure RBAC em produção
   • Restrinja DefaultAzureCredential ao desenvolvimento local
   • Escolha o tipo de credencial correto para produção, CI/CD e ambientes de desenvolvimento

Isso garante que suas implantações e operações de agentes possam se autenticar de forma confiável, sem segredos em código.

3. Decidir entre basic, standard e private-network setup

1. Abra references/standard-agent-setup.md para entender:
   • Diferenças entre setups Basic e Standard
   • Connections necessárias para o setup standard: Cosmos DB, Azure Storage, Azure AI Search e, opcionalmente, Azure AI Services
   • Pré-requisitos como funções de RBAC no resource group
2. Se você precisar de isolamento total de rede, leia references/private-network-standard-agent-setup.md:
   • Requisitos de VNet e subnets (subnet de agente e subnet de private endpoint)
   • Alinhamento de região entre recursos Foundry e a VNet
   • Uso do Bicep template oficial para private-network standard agent setup

Escolha o setup que atende aos seus requisitos de conformidade e rede antes de seguir para a criação do agente.

4. Padronizar o layout do projeto do agente

1. Abra references/agent-metadata-contract.md e alinhe seu projeto ao layout documentado:

   <agent-root>/
     .foundry/
       agent-metadata.yaml
       datasets/
       evaluators/
       results/
   

2. Certifique-se de que agent-metadata.yaml contenha definições de ambiente com campos como:

   • defaultEnvironment
   • environments.<name>.projectEndpoint
   • environments.<name>.agentName
   • environments.<name>.azureContainerRegistry (para hosted agents)
   • environments.<name>.observability.* (para Application Insights)
   • environments.<name>.testCases[] para pacotes de avaliação

Esse arquivo se torna a fonte de verdade para a configuração específica de ambiente, e o restante dos fluxos de trabalho do microsoft-foundry assume que ele existe e está correto.

5. Criar um agente prompt ou hosted

1. Para prompt agents, abra foundry-agent/create/create-prompt.md:

   • Entenda a diferença entre prompt agents e workflows
   • Siga as etapas para resolver o contexto do projeto (endpoint, credenciais)
   • Use ferramentas MCP quando disponíveis e recorra ao SDK azure-ai-projects conforme documentado
   • Informe nome do agente, deployment do modelo e instructions, além de ferramentas opcionais (file search, code interpreter etc.)

2. Para hosted agents, abra foundry-agent/create/create.md:

   • Escolha se está criando um novo agente (greenfield) ou convertendo um projeto existente (brownfield)
   • Selecione framework e linguagem com base nos caminhos de exemplo fornecidos (frameworks em Python ou C#, como Microsoft Agent Framework ou LangGraph)
   • Use a orientação para integrar com o repositório foundry-samples quando necessário

Ao final desta etapa, você deve ter um projeto de agente compatível com Foundry pronto para implantação.

6. Fazer build e implantar o agente

1. Abra foundry-agent/deploy/deploy.md.
2. Siga o fluxo de trabalho que cobre:
   • Varredura do projeto e coleta de variáveis de ambiente
   • Geração de Dockerfile e uso de docker / az acr para hosted agents
   • Uso de ferramentas MCP como agent_update, agent_container_control e agent_container_status_get
   • Criação ou atualização do deployment e início/parada dos containers de agente
3. Não execute azd up, azd deploy, az acr build ou docker build isoladamente sem revisar este guia — o skill coordena esses comandos como parte de um pipeline de deployment completo.

Concluída essa etapa, seu agente deve estar implantado e acessível pelo Azure AI Foundry.

7. Invocar e testar o agente

1. Abra foundry-agent/invoke/invoke.md.
2. Use os padrões documentados para:
   • Resolver o ambiente e o endpoint corretos a partir de agent-metadata.yaml
   • Invocar o agente com payloads de exemplo ou personalizados
   • Verificar se respostas, ferramentas e estado estão se comportando conforme esperado

Este é um bom momento para fazer smoke tests antes de rodar suítes de avaliação completas.

8. Avaliar e iterar

1. Abra foundry-agent/eval-datasets/eval-datasets.md.
2. Use as orientações para:
   • Gerenciar datasets e evaluators em .foundry/datasets e .foundry/evaluators
   • Executar fluxos de avaliação usando as definições de testCases do agent-metadata.yaml
   • Armazenar saídas em .foundry/results e comparar resultados por ambiente ou versão de agente
3. Itere em prompts ou instructions e rode novamente as avaliações para acompanhar a evolução ao longo do tempo.

Observability, tracing e troubleshooting

Observability e monitoramento

1. Abra foundry-agent/observe/observe.md.
2. Configure observability com base nas orientações:
   • Anexe Application Insights usando o resource ID e a connection string descritos em agent-metadata-contract.md
   • Use os dashboards ou consultas recomendados para monitorar latência, erros e throughput

Isso permite monitorar o comportamento em produção e correlacionar com mudanças de deployment.

Tracing e criação de datasets a partir de traces

1. Abra foundry-agent/trace/trace.md.
2. Use os fluxos documentados para:
   • Coletar traces dos seus agentes
   • Selecionar e organizar datasets a partir de traces e armazená-los em .foundry/datasets
   • Alimentar esses datasets nos fluxos de avaliação para testes mais realistas

Isso é especialmente útil quando você quer transformar tráfego real de usuários em cenários de avaliação.

Troubleshooting de deployments e problemas em runtime

1. Abra foundry-agent/troubleshoot/troubleshoot.md.
2. Siga os guias de troubleshooting para problemas como:
   • Falhas de deployment e erros de inicialização de container
   • Endpoints, credenciais ou connections configurados incorretamente
   • Erros de quota ou capacidade (consulte também quota/quota.md e quota/references/*.md)

Use isso em conjunto com logs e telemetria do Application Insights para diagnosticar e resolver problemas.

Quota, capacidade e otimização

1. Abra quota/quota.md para uma visão geral de:
   • Como a quota é aplicada a modelos e deployments no Azure AI Foundry
   • Como raciocinar sobre capacidade entre ambientes e regiões
2. Revise os arquivos em quota/references/:
   • capacity-planning.md – ajuda a estimar capacidade para agentes com base no uso
   • error-resolution.md – mapeia erros comuns relacionados a quota para correções recomendadas
   • optimization.md – sugere maneiras de ajustar workloads para caber dentro dos limites de quota

Esse conteúdo ajuda a evitar surpresas em escala e manter os agentes responsivos.

FAQ

O microsoft-foundry é obrigatório para usar o Azure AI Foundry?

Não. Você pode usar o Azure AI Foundry diretamente pelo portal Azure, CLI ou SDKs. O skill microsoft-foundry é um guia estruturado que empacota práticas recomendadas, fluxos de trabalho e referências em um só lugar, para que você configure projects, agentes e ambientes de forma mais consistente.

Posso usar o microsoft-foundry para outros serviços Azure que não sejam Foundry?

Use este skill quando seu objetivo principal for implantar e operar agentes e projetos do Azure AI Foundry. Para implantação genérica de web apps, APIs ou outros serviços PaaS (App Service, Functions, containers genéricos), prefira um skill ou guia dedicado de deployment Azure.

O microsoft-foundry oferece suporte a agentes prompt e hosted?

Sim. O skill tem conteúdo dedicado para ambos:

• foundry-agent/create/create-prompt.md cobre prompt agents.
• foundry-agent/create/create.md e foundry-agent/deploy/deploy.md cobrem hosted agents, incluindo containerização, ACR e gerenciamento do ciclo de vida dos containers.

Como o microsoft-foundry trata autenticação e segurança?

Segurança e autenticação são tratados em references/auth-best-practices.md e rbac/rbac.md:

• Use managed identities e Azure RBAC em produção
• Reserve DefaultAzureCredential para desenvolvimento local
• Escolha credenciais adequadas para CI/CD e ambientes on-premises

Siga esses docs antes de conectar SDKs ou ferramentas MCP para evitar configurações inseguras ou frágeis.

Eu preciso usar ferramentas MCP ou posso depender só de SDKs?

O conteúdo foi escrito para funcionar com ferramentas MCP quando disponíveis, mas também documenta alternativas via SDK na pasta references/sdk. Por exemplo, create-prompt.md explica como usar o SDK azure-ai-projects quando ferramentas MCP não estiverem presentes.

Como sei se a estrutura do meu projeto de agente está correta?

Compare seu projeto com references/agent-metadata-contract.md. Verifique se você tem:

• Um diretório .foundry/ na raiz do agente
• Um agent-metadata.yaml válido com environments e test cases
• Pastas datasets/, evaluators/ e results/ conforme descrito

Se você seguir esse contrato, o restante dos fluxos de trabalho do microsoft-foundry ficará alinhado ao layout do seu projeto.

Posso usar o microsoft-foundry com setups de rede privada (VNet)?

Sim. references/private-network-standard-agent-setup.md traz orientações detalhadas sobre:

• Configuração necessária de VNet e subnets
• Restrições de região entre recursos Foundry e a VNet
• Uso do Bicep template oficial para private-network standard agent setup

Use esse documento em conjunto com references/standard-agent-setup.md quando for necessário manter o tráfego em rede privada.

Por onde começar no repositório após a instalação?

Depois de instalar o skill, comece por:

1. SKILL.md – visão geral de alto nível de todos os sub-skills
2. project/create/create-foundry-project.md – para configurar seu projeto Foundry
3. references/agent-metadata-contract.md – para padronizar o layout do agente
4. foundry-agent/create/ e foundry-agent/deploy/ – para criar e implantar seu primeiro agente

A partir daí, avance para eval-datasets, observe, trace, rbac e quota conforme a necessidade do seu cenário.