Inicializar um projeto de agente hospedado com a CLI Azure Developer

Importante

Os itens marcados como pré-visualização neste artigo estão atualmente em pré-visualização. Esta pré-visualização é fornecida sem um acordo de nível de serviço, e a Microsoft não a recomenda para cargas de trabalho de produção. Certas funcionalidades podem não ser suportadas ou podem ter capacidades limitadas. Para mais informações, consulte Termos Suplementares de Utilização para Microsoft Azure Previews.

Utilize azd ai agent init para criar a estrutura de um projeto de agente alojado com os ficheiros necessários para compilar, testar e implementar um agente de IA no Microsoft Foundry. Neste artigo, escolhe um ponto de partida e inicializa o projeto a partir de um modelo, do seu próprio código ou contra um projeto Foundry existente.

Se usares um agente de programação como o GitHub Copilot, o Microsoft Foundry Skill pode ajudar-te a escolher um modelo inicial, a criar a estrutura do projeto e a interpretar a azdconfiguração gerada.

Pré-requisitos

Escolha um ponto de partida

Existem três formas de começar um projeto. Escolhe o caminho que se adequa à tua situação.

Consideração Comece a partir de um modelo Traga o seu próprio código Ligue um projeto existente
Melhor para Novos agentes, a aprender as ferramentas. Código de agente existente que queres alojar no Foundry. Agentes já a funcionar num projeto da Foundry.
Comando azd ai agent init num diretório vazio. azd ai agent init num diretório com código existente. azd ai agent init, depois seleciona um projeto existente.
O que obtém Um projeto totalmente estruturado: um único azure.yaml, código-fonte do agente em src/<agent-name>/ e um Dockerfile para implantação em contentores. A infraestrutura não inclui Bicep por predefinição e pode ser removida mais tarde. Uma entrada de serviço gerada azure.yaml e, para implementação em contentores, um Dockerfile que encapsula o seu código. A infraestrutura não inclui Bicep por predefinição e pode ser removida mais tarde. Um azure.yaml ligado por cabo ao teu projeto Foundry existente. A infraestrutura não inclui Bicep por predefinição e pode ser removida mais tarde.
Alterações de código Nenhum. Pronto para correr. Pode ser necessário um adaptador de protocolo. Nenhum.

Inicializar a partir de um template

Execute o assistente interativo num diretório vazio e selecione Começar de novo a partir de um modelo:

azd ai agent init

O mago guia-o pelas seguintes escolhas.

Prompt Description
Modelo de agente Escolha entre modelos organizados por framework e linguagem (Python ou .NET).
Subscrição do Azure A subscrição é utilizada para localizar ou criar um projeto Foundry.
Projeto de fundição Selecione um projeto existente ou crie um novo. Se criares um, também escolhes uma região.
Implantação do modelo Veja as definições do modelo do template. Ao adotar um template num projeto existente, use --model-deployment <name> para reutilizar explicitamente uma implantação.

O nome do agente é obtido a partir do modelo. A CLI cria um azd ambiente nomeado <directory>-dev e configura-o com detalhes do seu projeto Foundry selecionado. Os templates declaram as definições de origem do agente e de implementação em azure.yaml; os templates de contentor também incluem um Dockerfile.

Inicializar a partir de uma URL azure.yaml

Se tiver um exemplo específico de agente, aponte --template para o azure.yaml do exemplo. A CLI adota esse ficheiro como manifesto do projeto e descarrega a fonte do agente referenciado.

azd ai agent init --template https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml --src .

Para a adoção de modelos, --src seleciona o destino de todo o projeto, não apenas a origem do agente. O comando anterior escreve azure.yaml no diretório atual e preserva os caminhos de origem relativos do template. Sem --src, a inicialização pode criar um diretório com o nome do template. Execute os comandos subsequentes azd env, de provisionamento e de deployment a partir do diretório que contém o azure.yaml.

Os templates podem referenciar entradas externas, como um token GitHub ou um endpoint de serviço. Prepare esses valores antes da inicialização; a CLI solicita variáveis de ambiente não resolvidas e armazena-as no ambiente selecionado azd. Não faças commit de credenciais nem do diretório .azure.

Observação

A adoção do modelo requer um modelo completo azure.yaml. Para anexar uma definição direta de agente a um projeto existente, use agent add --file. Os wrappers parametrizados AgentManifest não são suportados por nenhum dos caminhos.

Utilize --template (-t) para um azure.yaml documento de projeto. --manifest (-m) é um alias obsoleto, não é compatível com o formato de manifesto anterior. Definições independentes de agentes, AgentManifest contentores e azureml:// ponteiros de manifestos não são aceites por este fluxo de trabalho.

Especificar um modelo

Escolha um modelo no momento inicial:

azd ai agent init --model gpt-4.1

Ou use uma implementação de modelo existente no seu projeto Foundry:

azd ai agent init --model-deployment my-deployment

Ao adotar um azure.yaml modelo, adicione --model-deployment <name> ao mesmo comando de inicialização e selecione o projeto existente. Este caminho não oferece atualmente um seletor interativo de implementação existente. Sem a substituição, a configuração adotada pode manter o modelo solicitado pelo template. Revise tanto a declaração de implementação do projeto como as definições do modelo do agente antes de executar azd provision.

Escolha um modo de implementação

Por defeito, azd ai agent init utiliza a implementação através de código para os projetos em Python e .NET. A implementação do código carrega o seu código-fonte para o servidor como um pacote ZIP. Para criar a estrutura de um projeto baseado em contentores, utilize --deploy-mode container:

azd ai agent init --deploy-mode container

Para implementar uma imagem de contentor pré-construída, passe --image e --agent-name. Esta opção ignora a seleção do modelo e da linguagem, a geração da estrutura de código, a geração do ficheiro Dockerfile e a configuração do Azure Container Registry.

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

Para inicialização de código-fonte não assistida, forneça --runtime e --entry-point com --deploy-mode code. O ficheiro gerado .agentignore utiliza a sintaxe .gitignore para excluir ficheiros do ZIP de implementação; reveja-o antes de carregar o código-fonte.

Navegue pelos modelos de forma não interativa

Para inspecionar o catálogo antes de gerar a estrutura, ou para controlar azd ai agent init a partir de um script, liste o catálogo:

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

Cada entrada inclui um initCommand pronto a executar que copias e executas no diretório onde pretendes gerar a estrutura.

Tip

Quando reutilizares um exemplo com uma identidade de agente do Foundry diferente, passa --agent-name <new-name> em azd ai agent init para que o nome escrito em azure.yaml não entre em conflito com o nome predefinido do exemplo.

Inicializar a partir de código existente

Se já tem código de agente em Python ou .NET, execute azd ai agent init dentro do diretório que já contém o seu código:

cd my-agent/
azd ai agent init

A CLI deteta os ficheiros existentes e gera uma azure.yaml entrada de serviço à volta deles sem sobrescrever o seu código. Para a implementação de contentores, também adiciona um Dockerfile. Por predefinição, a infraestrutura continua sem recurso ao Bicep, a menos que mais tarde opte por adicionar infraestrutura como código.

O seu código de agente deve cumprir o contrato de execução do agente hospedado:

  • Escuta na porta 8088.
  • Sirva uma sonda de saúde em GET /readiness.
  • Trate de um dos protocolos suportados (responses ou invocations).

Se o teu código ainda não falar um destes protocolos, adiciona um adaptador de protocolo, um wrapper de SDK leve que traduz entre o protocolo Foundry e a lógica do teu agente.

Utilize --src para especificar o diretório de origem ou destino para inicialização:

azd ai agent init --src src/my-agent

Adicionar um agente baseado em ficheiro a um projeto existente

Utilize agent add, em vez de adoção de template, quando tem uma definição direta de agente em YAML ou JSON:

azd ai agent add support-agent --file ./agents/support.yaml
azd deploy support-agent

support-agent é a chave de serviço em azure.yaml, não necessariamente o nome do agente Foundry. O comando adiciona ou atualiza o serviço usando uma raiz $ref relativa a azure.yaml. Valida localmente; não autentica, não copia código-fonte, não cria recursos remotos nem implementa.

O projeto deve declarar exatamente um serviço azure.ai.project. Utilize --project <service-key> para confirmar o serviço e --source <directory> para sobrescrever o diretório de origem do agente. O diretório já deve existir dentro do projeto.

Inicializar os agentes de prompt e de voz

A mesma extensão suporta agentes sem código-fonte alojado. Para um agente de prompts, escolha --kind prompt e forneça o seu nome, modelo e instruções:

azd ai agent init --kind prompt \
  --agent-name support-agent \
  --model <model-name> \
  --instructions "Answer support questions concisely."

Utilize --description para o resumo do agente de prompt. --rai-policy anexa uma política de conta existente pelo nome ou ID ARM; none herda a predefinição da conta. Esta opção não cria políticas e é ignorada para agentes alojados. Ao adotar um modelo, declare as políticas em azure.yaml em vez disso.

Para um agente de voz com prompts geridos:

azd ai agent init --kind prompt-voice --agent-name support-voice

O modelo de voz gerida está definido como gpt-realtime por predefinição e não requer uma implementação do modelo. Use --model e --voice para selecionar o modelo gerido e a voz de saída. Este caminho rejeita as definições de origem, protocolo, código e contentores. Implementa com azd provision e azd deploy, depois usa o endpoint de voz WebSocket a partir de azd ai agent show com um cliente Voice Live. O texto invoke não é uma aplicação de voz.

Para envolver um agente alojado com voz, adote um descritor completo azure.yaml que declara ambos os serviços. O serviço de voz utiliza conversationEngine.type: hosted_agent e conversationEngine.name para referenciar o serviço alvo alojado. Os campos targetAgent e modelType: hosted_agent anteriores não são suportados.

Liga-se a um projeto Foundry existente

Para gerir um projeto Foundry existente através de azd, execute o assistente e selecione a opção de ligação a um projeto existente. Também pode saltar a seleção interativa fornecendo diretamente o ID de recurso Azure do projeto:

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

Para encontrar o ID do projeto, abra o portal do Foundry, vá a Gerir>Detalhes do projeto e copie o valor de ID do Recurso.

Warning

Quando inicializa contra um projeto existente com --project-id, a ferramenta ignora as atribuições automáticas de funções que realiza ao criar um novo projeto. Certifica-te de que as funções exigidas já estão atribuídas. Para a matriz completa, veja Referência de permissões do agente hospedado.

Reveja o que foi criado

Por defeito, init cria a seguinte estrutura de projeto. Precisas de um Dockerfile apenas para a implementação de contentores:

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created when you pass --infra

Os modelos e exemplos disponibilizam um azure.yaml unificado na raiz do projeto. Durante o init, azd adota ou gera esse ficheiro. Por predefinição, não precisa de manter os ficheiros Bicep ou Terraform, a menos que opte por exportar a infraestrutura.

Para agentes Python, reveja o serviço de agente gerado e adicione PYTHONNOUSERSITE: "1" ao seu env mapa antes de testar ou implementar localmente. Instale dependências no ambiente virtual do agente ou na imagem do agente em vez do diretório do site do utilizador. Veja Configurar o arranque do Python.

Escolha a infraestrutura Terraform ou Bicep

Para gerir a infraestrutura com o Terraform, selecione-o quando inicializar o seu projeto:

azd ai agent init --infra=terraform

Infraestrutura e modo de implementação são escolhas independentes. Para um agente baseado em contentor com infraestrutura Terraform, utilize:

azd ai agent init --infra=terraform --deploy-mode container

Para um novo projeto, o comando escreve ficheiros Terraform em infra/ e configura o fornecedor de infraestrutura Terraform em azure.yaml. Num projeto com infraestrutura existente, a infraestrutura Foundry pode ser gerada como uma camada separada sob infra/foundry/. Revise a configuração gerada antes de provisionar.

Para escolher Bicep em alternativa, use --infra=bicep ou a forma abreviada --infra. Omitir --infra preserva o fluxo de trabalho padrão sem infraestrutura.

azd provision aplica a infraestrutura selecionada. azd deploy ainda assim cria a versão com agente hospedado; escolher Terraform não move a gestão de versões do agente para o estado Terraform.

Para estrutura e personalização de ficheiros, consulte Infraestrutura de agente hospedado. Antes de usar o Terraform numa pipeline, configure o CI/CD do Terraform e o estado remoto.