Inicializar um projeto de agente hospedado com a CLI do desenvolvedor do Azure

Use azd ai agent init para estruturar um projeto de agente hospedado com os arquivos necessários para criar, testar e implantar um agente de IA para Microsoft Foundry. Neste artigo, você escolhe um ponto de partida e inicializa o projeto a partir de um modelo, do seu próprio código ou com base em um projeto Foundry existente.

Se você usar um agente de codificação como GitHub Copilot, o Microsoft Foundry Skill poderá ajudá-lo a escolher um modelo inicial, estruturar o projeto e interpretar a configuração geradaazd.

Pré-requisitos

• As extensṍes do Azure Developer CLI Foundry instaladas.
• Uma sessão de Azure autenticada (azd auth login).
• Acesso de Colaborador na sua assinatura do Azure.

Escolher um ponto de partida

Há três maneiras de começar um projeto. Escolha o caminho que corresponde à sua situação.

Inicializar a partir de um modelo

Execute o assistente interativo em um diretório vazio e selecione Iniciar um novo projeto a partir de um modelo:

azd ai agent init

O assistente orienta você pelas seguintes opções.

O nome do agente vem do modelo. A CLI cria um ambiente azd chamado <directory>-dev e o configura com as informações do projeto Foundry selecionado. Cada modelo inclui o código-fonte do agente, um arquivo Dockerfile e um arquivo azure.yaml que atua como o manifesto unificado do projeto para o projeto azd e a configuração do agente hospedado.

Inicialize a partir de uma URL azure.yaml.

Se você tiver um exemplo de agente específico, aponte -m para o azure.yaml do exemplo. A CLI adota esse arquivo como o manifesto do projeto e baixa a origem 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 ainda aceita uma URL de manifesto de agente legado, mas os exemplos atuais publicam um azure.yaml unificado.

Especificar um modelo

Escolha um modelo no momento da inicialização:

azd ai agent init --model gpt-4.1

Ou use uma implantação de modelo existente em seu projeto do Foundry:

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

Escolher um modo de implantação

Por padrão, azd ai agent init usa a implantação via código para projetos em Python e .NET. A implantação do código envia seu código-fonte em um pacote ZIP. Em vez disso, para estruturar um projeto baseado em contêiner, passe --deploy-mode container:

azd ai agent init --deploy-mode container

Para implantar uma imagem de contêiner predefinida, passe --image e --agent-name. Essa opção omite a seleção de template e idioma, a criação da estrutura do código, a geração do Dockerfile e a configuração do Registro de Contêiner do Azure.

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

Procurar modelos sem interação

Para inspecionar o catálogo antes de gerar a estrutura ou para controlar azd ai agent init por meio 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 comando pronto para executar initCommand que você copia e executa no diretório em que você deseja gerar a estrutura.

Inicializar a partir de código existente

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

cd my-agent/
azd ai agent init

A CLI detecta os arquivos existentes e gera uma entrada de serviço azure.yaml para eles sem sobrescrever seu código. Para implantação em contêiner, ele também adiciona um Dockerfile. A infraestrutura permanece sem o bicep por padrão, a menos que você remova a infraestrutura como código posteriormente.

O código do agente deve atender ao contrato de runtime do agente hospedado:

• Ouça na porta 8088.
• Atender uma investigação de integridade em GET /readiness.
• Manipular um dos protocolos com suporte (responses ou invocations).

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

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

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

Conectar-se a um projeto de Foundry existente

Para gerenciar um projeto existente do Foundry por meio de azd, execute o assistente e selecione a opção de se conectar a um projeto existente. Você também pode ignorar a seleção interativa fornecendo a ID do recurso Azure do projeto diretamente:

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

Para localizar o ID do projeto, abra o portal Foundry, acesse Gerenciar>Detalhes do projeto e copie o valor da ID do recurso.

Revisar o que é 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

Modelos e exemplos publicam um azure.yaml unificado na raiz do projeto. Durante a inicialização, azd adota ou gera esse arquivo. Você trabalhará com azure.yaml daqui para frente. A infraestrutura não utiliza o bicep por padrão. Ejete a infraestrutura somente quando precisar gerenciar os arquivos IaC gerados diretamente.

Conteúdo relacionado

• Início Rápido: Implantar seu primeiro agente hospedado
• Criar azure.yaml para agentes hospedados
• referência do azure.yaml para agentes hospedados
• Infraestrutura de agente hospedada com a CLI do Azure Developer