Quickstart: Configurar recursos do Microsoft Foundry

Neste quickstart, crias um projeto Microsoft Foundry e implementas um modelo. Se estiver a gerir uma equipa, também concede acesso aos membros da equipa. Depois de completar estes passos, você ou a sua equipa podem começar a construir aplicações de IA usando o modelo implementado.

Para o desenvolvimento de agentes, estabeleça também ligação ao Azure Monitor Application Insights para armazenar vestígios de agentes.

Dica

Este quickstart mostra-te como criar recursos para construir um agente com uma configuração básica. Para cenários mais avançados que utilizam os teus próprios recursos, vê Configurar o teu ambiente para desenvolvimento de agentes.

Pré-requisitos

• Uma conta no Azure com uma subscrição ativa. Se não tiveres uma, cria uma conta Azure free, que inclui uma subscrição de teste gratuita.
• Se está a criar o projeto para si mesmo:
  • Aceder a uma função que lhe permita criar um recurso Foundry, como Foundry Account Owner ou Foundry Owner na subscrição ou grupo de recursos. Para mais informações sobre permissões, consulte Controlo de acesso baseado em funções para Microsoft Foundry.

    Importante

    As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

• Se está a criar o projeto para uma equipa:
  • Acesso a um papel que permita completar atribuições de funções, como Proprietário. Para mais informações sobre permissões, consulte Controlo de acesso baseado em funções para Microsoft Foundry.
  • Uma lista de endereços de email de utilizadores ou IDs de grupos de segurança Microsoft Entra para membros da equipa que necessitem de acesso.
• Para visualizar os rastros do agente: acesso de leitura ao recurso do Application Insights ligado, como Log Analytics Reader. Um administrador pode conceder este acesso. Consulte Conceder acesso a rastreios para requisitos de tabela protegida e espaço de trabalho.
• Para atribuir papéis de leitor de traços: Microsoft.Authorization/roleAssignments/write tenha a permissão no âmbito alvo. Colaborador por si só não concede esta permissão. Se não conseguires atribuir funções, pede a um administrador para atribuir o acesso necessário.

Se usar a CLI do Azure em vez do portal, a função Contributor ou Owner no grupo de recursos é suficiente para criar o recurso e o projeto. Ainda precisas de um papel que possa atribuir funções, como Proprietário, para dar acesso aos membros da equipa.

Selecione o seu método preferido usando os seguintes separadores:

CLI do Azure

• Instale a CLI do Azure versão 2.80.0 ou posterior. Verifica a tua versão com az version, e executa az upgrade se precisares de uma mais recente.

  A versão 2.80.0 adicionou os az cognitiveservices account project comandos que estes passos utilizam. Numa versão anterior, os comandos falham com unrecognized arguments ou 'project' is misspelled or not recognized by the system.

• Iniciar sessão no Azure:

  az login
  

Portal da plataforma Foundry

• Acesso ao portal Microsoft Foundry.

Crie um projeto

Crie um projeto Foundry para organizar o seu trabalho. O projeto contém modelos, agentes e outros recursos que a sua equipa utiliza.

Dica

Crie o seu projeto na região West US 3 se quiser experimentar um modelo instantâneo (pré-visualização).

CLI do Azure

Note

Estes passos requerem a versão 2.80.0 ou posterior da CLI do Azure e o papel de Contribuidor ou Proprietário no grupo de recursos. Corre az version para verificar a tua versão e az upgrade se precisas de uma mais recente. Executa az login para iniciares sessão antes de começares. Para regiões suportadas, veja Apoio regional.

1. Cria um grupo de recursos ou usa um já existente. Por exemplo, crie my-foundry-rg em eastus:

   az group create --name my-foundry-rg --location eastus
   

   Verifique se o grupo de recursos existe:

   az group show --name my-foundry-rg --query properties.provisioningState --output tsv
   

   A saída mostra Succeeded.

2. Crie o recurso Foundry com a gestão de projetos ativada. Por exemplo, crie my-foundry-resource no my-foundry-rg grupo de recursos:

   az cognitiveservices account create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --kind AIServices \
       --sku S0 \
       --location eastus \
       --custom-domain my-foundry-resource \
       --assign-identity \
       --allow-project-management true
   

   Use estes valores:

   Parameter	Purpose
   --assign-identity	Cria a identidade gerida que a gestão de projetos exige. Sem ela, a criação do projeto falha devido a um erro que indica que uma identidade gerida deve ser ativada no recurso.
   --allow-project-management	Permite o gerenciamento de projetos. Não podes mudar esta definição depois de criares o recurso.
   --custom-domain	Deve ser globalmente único. Se my-foundry-resource for tomado, o comando falha com CustomDomainInUse. Escolha um nome diferente e execute o comando novamente.

3. Cria um projeto. Por exemplo, crie my-foundry-project em :my-foundry-resource

   az cognitiveservices account project create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --location eastus
   

4. Verifique se o recurso está provisionado:

   az cognitiveservices account show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --query properties.provisioningState --output tsv
   

   O resultado deve mostrar Succeeded. Se o resultado apresentar um estado diferente, verifique as suas permissões, a disponibilidade na sua região e as quotas de recursos. Para mais ajuda, consulte Criar um recurso multi-serviço.

5. Verifique se o projeto foi criado:

   az cognitiveservices account project show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --query properties.provisioningState --output tsv
   

   O resultado deve mostrar Succeeded. Se o comando falhar com uma mensagem a indicar que uma identidade gerida deve ser ativada, confirme que criou o recurso com --assign-identity.

Referência: az cognitiveservices account project

Portal da plataforma Foundry

1. Iniciar sessão no Microsoft Foundry. Certifica-te de que a opção New Foundry está ativada. Estes passos referem-se à Foundry (nova).

   

2. Cria um projeto.

   • Se esta for a sua primeira utilização do Foundry, será solicitado a criar ou procurar um projeto para continuar. Selecione Criar um novo projeto no menu suspenso.
   • Se já tiver um projeto carregado, selecione o nome no canto superior esquerdo e depois selecione Criar novo projeto.

3. Insira um nome de projeto, como my-foundry-project.

4. Selecione Opções Avançadas para configurar o grupo de recursos e a localização:

   • Grupo de recursos: Crie um novo grupo de recursos ou selecione um já existente. Se criares um novo grupo de recursos, podes gerir o projeto e todos os seus recursos de forma mais fácil em conjunto.
   • Localização: Selecione a região mais próxima da sua equipa.

5. Selecione Criar projeto.

   Aguarde que o projeto seja criado. Quando a página de visão geral do projeto aparece, o seu projeto está pronto.

Ligar o Application Insights para rastreio do agente

Antes de executares um quickstart de agente, completa esta configuração no portal da Foundry.

Revise a segurança e privacidade do rastreio , a retenção e o custo dos dados antes de ativar o rastreio.

Siga as instruções em Connect Application Insights to your Foundry project. Verifique e reutilize uma conexão existente.

Note

Se a sua ligação atual usa Project Managed Identity, ou se a sua organização exigir ingestão apenas Entra, mantenha a configuração aprovada. Consulte Configurar autenticação Microsoft Entra para ingestão de traços.

Para agentes alojados na Foundry, a ligação permite o rastreio do lado do servidor. Para agentes a correr na sua própria aplicação, configure também o rastreamento do lado do cliente.

Conceder acesso a rastreios

A pessoa ou grupo que visualiza os rastreios necessita do Log Analytics Reader no recurso conexo Application Insights, ou de acesso herdado equivalente. Para tabelas de rastreamento protegidas, conceda também o Leitor de Dados de Monitorização Privilegiada.

Consulte Pré-requisitos de Rastreio e Atribuir papéis Azure usando o portal Azure para instruções detalhadas.

Para consultas com âmbito de espaço de trabalho ou espaços de trabalho que requerem permissões de espaço de trabalho, veja Gerir o acesso a espaços de trabalho do Log Analytics.

Verifique o seu primeiro trace de agente

Continue com a implementação do modelo ou com o quickstart do seu agente. Após a sua primeira solicitação do agente, siga o Verify tracing works para confirmar que aparece um novo rasto. Uma resposta bem-sucedida, por si só, não confirma que os vestígios foram armazenados.

Se não aparecer rasto, veja Resolução de problemas de rastreio.

Implementar um modelo

Implementa um modelo que possas usar. Este exemplo usa gpt-5-mini, mas pode escolher qualquer modelo disponível.

Dica

Para experimentar um modelo de acesso instantâneo (pré-visualização), pode saltar este passo.

CLI do Azure

1. Liste os modelos disponíveis na sua região para confirmar o nome e a versão do modelo:

   az cognitiveservices model list \
       --location eastus \
       --query "[?model.name=='gpt-5-mini'].{version:model.version,skus:join(',',model.skus[].name)}" \
       --output table
   

2. Implementar o modelo:

   az cognitiveservices account deployment create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --deployment-name gpt-5-mini \
       --model-name gpt-5-mini \
       --model-version "2025-08-07" \
       --model-format OpenAI \
       --sku-capacity 10 \
       --sku-name GlobalStandard
   

   Se o comando falhar com DeploymentModelNotSupported, o modelo, versão ou SKU não estão disponíveis na sua região. Use a saída do passo anterior para escolher uma combinação suportada.

3. Verifique se a implementação foi bem-sucedida:

   az cognitiveservices account deployment show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --deployment-name gpt-5-mini \
       --query properties.provisioningState --output tsv
   

   A saída mostra Succeeded quando a implementação está pronta.

Referência: implementação da conta az cognitiveservices

Portal da plataforma Foundry

1. Selecione Build no canto superior direito da navegação, depois Modelos no painel esquerdo.
2. Selecione Implantar>Implantar um modelo base para visualizar os modelos disponíveis.
3. Procura por gpt-5-mini.
4. Seleciona as definições de Deploy>Default para adicioná-las ao teu projeto.
5. Note o nome da implementação (por exemplo, gpt-5-mini). A tua equipa precisa deste nome para usar o modelo.

Obtenha os detalhes da ligação ao seu projeto

Necessitas que o endpoint do teu projeto seja acessível a partir do código. Se estiver a administrar este projeto para outros, envie-lhes este endpoint juntamente com o nome da implementação.

CLI do Azure

Obtenha o endpoint do projeto:

az cognitiveservices account project show \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --project-name my-foundry-project \
    --query 'properties.endpoints."AI Foundry API"' --output tsv

A saída é o endpoint do teu projeto, na forma https://my-foundry-resource.services.ai.azure.com/api/projects/my-foundry-project. Utilize este valor noutros guias de início rápido e tutoriais.

Portal da plataforma Foundry

1. Inicia sessão no Microsoft Foundry usando a tua conta Azure.
2. Selecione o seu projeto.
3. Encontre o endpoint do seu projeto no ecrã de boas-vindas do projeto.
4. Copie o valor do endpoint. Usas este valor em outros tutoriais e inícios rápidos.

Para administradores - conceder acesso

Se estiver a administrar uma equipa, atribua o papel de Utilizador do Foundry aos membros da equipa para que possam usar o projeto e os modelos implementados. Esta função fornece as permissões mínimas necessárias para construir e testar aplicações de IA. Para outras funções que possa precisar de atribuir, veja Controlo de acesso baseado em funções para Microsoft Foundry.

CLI do Azure

1. Obtenha o ID do recurso do projeto:

   PROJECT_ID=$(az cognitiveservices account project show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --query id -o tsv)
   

2. Atribua a função Foundry User a um membro da equipa:

   Importante

   As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

   az role assignment create \
       --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
       --assignee "user@contoso.com" \
       --assignee-principal-type User \
       --scope $PROJECT_ID
   

Note

Como as funções RBAC do Foundry foram recentemente renomeadas, utilize o ID de definição de função (GUID) em vez do nome da função no seu código para evitar problemas durante a implementação da alteração de nome:

• Utilizador do Foundry: 53ca6127-db72-4b80-b1b0-d745d6d5456d
• Proprietário da Fundição: c883944f-8b7b-4483-af10-35834be79c4a
• Proprietário da Conta Foundry: e47c6f54-e4a2-4754-9501-8e0985b135e1
• Gestor de Projeto do Foundry: eadc314b-1a2d-4efa-be10-5d325db5065e

Para adicionar um grupo de segurança em vez de um utilizador individual:

az role assignment create \
    --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
    --assignee-object-id "<security-group-object-id>" \
    --assignee-principal-type Group \
    --scope $PROJECT_ID

1. Verifique a atribuição de funções:

   az role assignment list \
       --scope $PROJECT_ID \
       --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
       --output table
   

Referência: az role assignment

Portal da plataforma Foundry

1. No portal da Foundry, selecione Gerir no canto superior direito da navegação.
2. Selecione Project details no painel esquerdo.
3. Selecione o separador Utilizadores.
4. Selecionar Adicionar utilizador no canto superior direito.
5. Introduza o endereço de email do membro da equipa.
6. Selecionar Adicionar.

Repita estes passos para cada membro da equipa ou grupo de segurança.

Dica

Para adicionar vários utilizadores ao mesmo tempo, use um grupo de segurança Microsoft Entra em vez de endereços de email individuais.

Verificar o acesso dos membros da equipa

Peça a um membro da equipa para verificar o seu acesso, iniciando sessão no Microsoft Foundry e selecionando o projeto da lista de projetos.

Se o membro da equipa não conseguir aceder ao projeto, verifique se a atribuição de funções foi concluída com sucesso. Verifique se usou o endereço de email correto ou o ID do grupo de segurança. Certifique-se de que a conta Azure do membro da equipa está no mesmo tenant da Microsoft Entra.

Para confirmar que o modelo implementado está disponível, peça ao membro da equipa para selecionar Construir na navegação superior direita e depois Modelos no painel esquerdo.

Liberar recursos

Quando já não quiser este projeto, elimine o grupo de recursos para eliminar todos os recursos associados a ele.

CLI do Azure

az group delete --name my-foundry-rg --yes --no-wait

A eliminação é executada em segundo plano. Para confirmar que o grupo de recursos desapareceu, execute:

az group exists --name my-foundry-rg

A saída mostra false quando a eliminação termina.

Portal da plataforma Foundry

No portal Azure, encontre e selecione o seu grupo de recursos. Selecione Eliminar e confirme a eliminação do grupo de recursos e de todos os seus recursos associados.

Próximo passo

Início rápido do Microsoft Foundry