Inicializar um projeto de agente hospedado com a CLI Azure Developer

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

• As extensões Foundry da CLI do Azure Developer foram instaladas.
• Uma sessão Azure autenticada (azd auth login).
• Acesso de colaborador na sua subscrição do Azure.

Escolha um ponto de partida

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

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.

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. Cada modelo inclui código-fonte do agente, um Dockerfile e um ficheiro azure.yaml que funciona como manifesto unificado do projeto azd e da configuração do agente alojado.

Inicializar a partir de uma URL azure.yaml

Se tiver um exemplo específico de agente, aponte -m 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 -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml

A opção -m continua a aceitar um URL do manifesto antigo do agente, mas os exemplos atuais publicam um azure.yaml unificado.

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

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

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.

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. A infraestrutura mantém-se sem bíceps por defeito, a menos que depois ejetes a 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.

Para adicionar um agente a um projeto existente azd , init deteta o projeto e adiciona uma nova entrada de serviço ao seu projeto existente azure.yaml. Use --src para especificar um subdiretório:

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

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.

Reveja o que foi criado

Após a conclusão de init, o diretório do seu projeto contém a seguinte estrutura:

.
|-- 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 only after you eject infrastructure

Os modelos e exemplos disponibilizam um azure.yaml unificado na raiz do projeto. Durante o init, azd adota ou gera esse ficheiro. Trabalha com azure.yaml daqui para a frente. A infraestrutura é sem bíceps por defeito. Ejeta infraestrutura apenas quando precisares de gerir diretamente os ficheiros IaC gerados.

Conteúdo relacionado

• Início rápido: Implemente o seu primeiro agente alojado
• Crie o azure.yaml para agentes hospedados
• Referência azure.yaml para agentes hospedados
• Infraestrutura de agente hospedado com o Azure Developer CLI