Infraestrutura hospedada de agentes com a CLI do Azure Developer

A CLI do Azure Developer (azd) pode gerar infraestrutura em Bicep ou Terraform com base nos serviços declarados em azure.yaml. Escolha Terraform com azd ai agent init --infra=terraform, ou Bicep com --infra=bicep. Executar azd provision aplica a infraestrutura selecionada.

O provisionamento de infraestrutura e a implantação do agente são separados. Terraform ou Bicep gerencia os recursos de suporte do Azure; azd deploy cria a versão do plano de dados do agente hospedado. Para gerenciar o próprio agente com o Terraform em vez de azd, consulte Implantar um agente hospedado com o Terraform.

O que é provisionado

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

Quando você adiciona a infraestrutura do Bicep, os modelos são baseados no repositório azd-ai-starter-basic e criam os seguintes recursos do Azure:

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

• Configurações de funcionalidade do agente : declare os recursos Azure que contêm o estado do agente, os dados de vetor e os arquivos. Defina-os quando precisar de agentes para usar o armazenamento que você possui.
• Fundamentação com o Bing ou Fundamentação com Pesquisa Personalizada do Bing - para a ferramenta de busca na Web.
• Pesquisa de IA do Azure - para fundamentação com pesquisa.
• Armazenamento do Azure-- para operações de arquivo.

Estrutura do Projeto

Para 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 os parâmetros fluem

Para Bicep, o main.parameters.json arquivo 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 essas referências ${VAR} a partir do ambiente (.azure/<env>/.env) e as passa para a implantação no Bicep. As saídas da implantação, como o ponto de extremidade do projeto do Foundry, o nome da implantação do modelo e o ponto de extremidade do registro de contêiner, são gravadas novamente no ambiente para uso por azd deploy, azd ai agent run e os comandos de recurso azd ai.

Infraestrutura do Terraform

Para um novo projeto, azd ai agent init --infra=terraform gera arquivos como o seguinte:

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

Serviços baseados em contêiner também podem gerar container-registry.tf. Os projetos existentes podem manter sua infraestrutura e receber uma camada separada de Foundry sob infra/foundry/. Use o layout gerado real em vez de mover arquivos entre camadas.

A configuração do Terraform provisiona a conta do Foundry, o projeto, as implantações de modelo e os recursos relacionados exigidos pelos serviços selecionados. A criação do registro de contêiner depende do modo de implantação e da configuração da imagem.

main.tfvars.json associa entradas de infraestrutura a valores de ambiente do azd. outputs.tf expõe valores como o ponto de extremidade do projeto Foundry para o azd após o provisionamento. Essas associações fazem parte do fluxo de trabalho do azd; não suponha que um arquivo de parâmetro gerado funcione inalterado com um autônomo terraform apply.

Para personalizar a infraestrutura do Terraform, edite os arquivos gerados .tf , preserve as saídas necessárias para os serviços do agente e execute azd provision. Examine o plano do Terraform antes de aplicar alterações de infraestrutura.

Estado do Terraform e CI/CD

Os arquivos gerados não inicializam um back-end de estado remoto. Para implantações em equipe, configure o estado armazenado no Armazenamento do Azure, chaves de estado separadas para cada ambiente e as permissões necessárias para o backend antes de configurar o CI/CD.

Consulte Configurar CI/CD com Terraform para o fluxo de implantação e Usar Terraform com azd para a configuração de back-end.

Limitações da ejeção do Terraform

O caminho de ejeção do Terraform não dá suporte à configuração de serviço network: na extensão atual de agentes do Foundry. Examine as restrições de recursos existentes antes de ejetar um projeto que já tenha infraestrutura. Ejection não é uma migração genérica do estado do Bicep para o Terraform, e excluir recursos de produção não é um pré-requisito para adotar o Terraform.

Recursos existentes

Os modelos de Bicep dão suporte à conexão com recursos de Azure existentes em vez de criar novos. Isso é útil quando sua equipe já tem infraestrutura compartilhada.

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

Personalizar a infraestrutura

O infra/ diretório é uma 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. Adicione novos parâmetros a main.parameters.json com vinculações ${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 nos arquivos de Bicep persistem entre implantações.

Restrições de região

O modelo main.bicep restringe location às regiões em que há suporte para agentes hospedados. Se você precisar implantar em uma região que não esteja na lista de permissões, atualize o decorador @allowed em main.bicep.

Conteúdo relacionado

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