Infraestrutura de agente hospedado com o Azure Developer CLI

A CLI do Azure Developer (azd) pode gerar infraestruturas Bicep ou Terraform a partir dos serviços declarados em azure.yaml. Escolha Terraform com azd ai agent init --infra=terraform, ou Bicep com --infra=bicep. A execução azd provision aplica-se à infraestrutura selecionada.

O provisionamento de infraestrutura e a implementação de agentes são separados. O Terraform ou Bicep gere o suporte aos recursos do Azure; azd deploy cria a versão do plano de dados com agente hospedado. Para gerir o agente em si com Terraform em vez de azd, veja Implementar um agente hospedado com Terraform.

O que é provisionado

Por defeito, azd ai agent init não cria ficheiros de infraestrutura como código. Use --infra ou --infra=bicep para adicionar infraestrutura Bicep. Use --infra=terraform para adicionar infraestrutura Terraform e definir infra.provider: terraform.

Quando adicionas a infraestrutura do Bicep, os templates baseiam-se no repositório azd-ai-starter-basic e criam os seguintes recursos do Azure:

Os templates criam mais recursos condicionalmente, com base nos serviços e dependências declarados em azure.yaml:

• Definições de capacidades do agente — declare os recursos do Azure que contêm o estado do agente, dados vetoriais e ficheiros. Define-os quando precisar que os agentes usem o armazenamento que possui.
• Ancoragem com o Bing ou Ancoragem com a Pesquisa Personalizada do Bing — para a ferramenta de pesquisa na web.
• Pesquisa de IA do Azure -- para fundamentação da pesquisa.
• Armazenamento do Azure -- para operações de ficheiros.

Estrutura do projeto

Para o Bicep, um projeto gerado tem a seguinte estrutura:

infra/
|-- main.bicep                 # Main deployment template (subscription-scoped)
|-- main.parameters.json       # Parameter bindings to azd environment variables
|-- abbreviations.json         # Naming convention abbreviations
\-- core/
    |-- ai/                    # Foundry account, project, and connections
    |-- host/                  # Container registry
    |-- monitor/               # Application Insights and Log Analytics
    |-- search/                # Azure AI Search (conditional)
    \-- storage/               # Azure Storage (conditional)

Como fluem os parâmetros

Para o Bicep, o ficheiro main.parameters.json mapeia azd variáveis de ambiente para parâmetros:

{
  "environmentName": { "value": "${AZURE_ENV_NAME}" },
  "location": { "value": "${AZURE_LOCATION}" },
  "aiFoundryResourceName": { "value": "${AZURE_AI_ACCOUNT_NAME}" },
  "aiProjectDeploymentsJson": { "value": "${AI_PROJECT_DEPLOYMENTS=[]}" }
}

Durante azd provision, azd resolve estas referências ${VAR} a partir do ambiente (.azure/<env>/.env) e passa-as para a implementação em Bicep. As saídas da implementação, como o ponto final do projeto Foundry, o nome da implementação do modelo e o ponto final do registo de contentores, são gravadas novamente no ambiente para serem utilizadas por azd deploy, azd ai agent run e pelos comandos de recursos azd ai.

Infraestrutura Terraform

Para um novo projeto, azd ai agent init --infra=terraform gera ficheiros como os seguintes:

infra/
|-- main.tf
|-- provider.tf
|-- variables.tf
|-- outputs.tf
|-- main.tfvars.json
\-- .azd-foundry

Os serviços baseados em contentores também podem gerar container-registry.tf. Os projetos existentes podem manter a sua infraestrutura e receber uma camada Foundry separada sob infra/foundry/. Use o layout gerado em vez de mover ficheiros entre camadas.

A configuração do Terraform prevê a conta Foundry, projeto, implementações de modelos e recursos relacionados exigidos pelos serviços selecionados. A criação do registo de contentores depende do modo de implementação e da configuração da imagem.

main.tfvars.json Liga entradas de infraestrutura aos valores do ambiente AZD. outputs.tf expõe valores como o endpoint do projeto Foundry ao azd após o provisionamento. Estas ligações fazem parte do fluxo de trabalho azd; não assumas que um ficheiro de parâmetros gerado funciona inalterado com um arquivo independente terraform apply.

Para personalizar a infraestrutura do Terraform, edite os ficheiros gerados .tf, mantenha os resultados necessários para os serviços do seu agente e execute azd provision. Revise o plano Terraform antes de aplicar alterações na infraestrutura.

Estado de terraformação e CI/CD

Os ficheiros gerados não arrancam um backend de estado remoto. Para implementações em equipa, configure o estado apoiado pelo Armazenamento do Azure, chaves de estado separadas para cada ambiente e as permissões de backend necessárias antes de configurar CI/CD.

Veja Configurar CI/CD com o Terraform para o processo de implementação e Utilizar o Terraform com o azd para a configuração do back-end.

Limitações de remoção do Terraform

O caminho de ejeção do Terraform não suporta a configuração de serviços network: na extensão atual dos agentes do Foundry. Revise as limitações dos recursos existentes antes de expulsar um projeto que já tenha infraestrutura. A ejeção não é uma migração geral de estado do Bicep para o Terraform, e eliminar recursos de produção não é um pré-requisito para adotar o Terraform.

Recursos existentes

Os templates Bicep suportam a ligação a recursos existentes do Azure em vez de criar novos. Isto é útil quando a sua equipa já tem infraestrutura partilhada.

Defina estas variáveis com azd env set antes de executar azd provision.

Personalize a infraestrutura

O infra/ diretório é a infraestrutura padrão azd . Para adicionar ou alterar recursos do Bicep:

1. Editar infra/main.bicep ou adicionar novos módulos em infra/core/.
2. Adicionar novos parâmetros a main.parameters.json com associações de ${VAR}.
3. Defina as variáveis de ambiente correspondentes azd com azd env set.
4. Execute azd provision para aplicar as alterações.

As alterações aos ficheiros Bicep persistem ao longo das implementações.

Restrições regionais

O modelo main.bicep restringe location às regiões em que os agentes alojados são suportados. Se precisares de implementar numa região que não está na lista de regiões permitidas, atualiza o decorador @allowed em main.bicep.

Conteúdo relacionado

• Referência azure.yaml para agentes hospedados
• Configurar CI/CD para agentes alojados
• azd-ai-starter-basic repository