Início Rápido: Implantar seu primeiro agente hospedado

• CLI do Azure Developer (AZD) 1.25.3 ou posterior.

• A extensão azd microsoft.foundry Instale e verifique a extensão após a instalação do AZD:

  azd ext install microsoft.foundry
  

• Entre no Azure:

  azd auth login
  

• Código do Visual Studio.
• Microsoft Foundry Toolkit for Visual Studio Code.

Etapa 1: Estruturar o projeto de exemplo

Inicialize um novo projeto de agente hospedado usando o manifesto de exemplo básico do Agent Framework:

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

O fluxo interativo solicita:

• Nome do agente: personalize o nome ou aceite as respostas padrão, agent-framework-agent-basic-responses
• Foundry Project: selecione Criar um novo projeto do Foundry
• Tenant: selecione seu locatário Azure
• Subscrição: selecione a subscrição do Azure
• Location: selecione uma região de Azure
• Modelo: selecione o padrão, gpt-4.1-mini ou outro modelo que você pode acessar.
• Versão do modelo: selecione a opção padrão.
• SKU do modelo: selecione uma opção com cota disponível que não seja o Lote, geralmente Standard ou GlobalStandard
• Capacidade de implantação: selecione o padrão, 10
• Nome da implantação: selecione o padrão, gpt-4.1-mini

Quando concluída, você deverá ver a definição do agente de IA adicionada ao seu projeto azd com êxito!.

Comandos não interativos

Você também pode usar a opção --no-prompt para executar init em um ambiente não interativo, como um agente de código:

azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/agent.manifest.yaml" --no-prompt

Antes de continuar, defina AZURE_SUBSCRIPTION_ID e AZURE_LOCATION:

azd env set AZURE_SUBSCRIPTION_ID <subscription-id>
azd env set AZURE_LOCATION <region>

Você pode configurar implantações de modelo editando a config seção em azure.yaml:

deployments:
    - name: <deployment-name>
      model:
        name: <model-name>
        format: OpenAI
        version: <model-version>
      sku:
        name: GlobalStandard
        capacity: 1

Etapa 2: Provisionar recursos de Azure

Provisione os recursos definidos em azure.yaml:

azd provision

Essa etapa leva alguns minutos e cria os recursos a seguir. Para executar o provisionamento e fazer o deploy de uma só vez, você pode usar azd up em vez disso.

Etapa 3: Testar o agente localmente

1. Inicie o agente:

   azd ai agent run --no-inspector
   

   Esse comando cria um ambiente virtual, instala dependências e inicia o agente usando o startupCommand definido em azure.yaml. Pacotes de pré-visualização podem gerar avisos de conflito de versão de dependência do pip durante a configuração. Esses avisos não bloqueiam. O agente inicia e responde corretamente apesar disso.

2. Em um terminal separado, envie um prompt de teste:

   azd ai agent invoke --local "Write a haiku about deploying cloud applications."
   

   Você deve ver uma resposta haiku do agente.

Etapa 4: Implantar no Serviço do Foundry Agent

Compile e implante o contêiner do agente:

azd deploy

Quando o comando termina, a saída exibe links para o playground do agente e o endpoint do agente:

Deploying services (azd deploy)

  Done: Deploying service basic-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/basic-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/basic-agent/versions/1

Etapa 1: Criar um projeto do Foundry

1. Abra a Paleta de Comandos (Ctrl+Shift+P) e selecione Foundry Toolkit: Criar Project.
2. Selecione sua assinatura Azure.
3. Crie um novo grupo de recursos ou selecione um existente.
4. Insira um nome para o projeto Foundry.

Etapa 2: Implantar um modelo

1. Abra a paleta de comandos e selecione Foundry Toolkit: Abrir Catálogo de Modelos.
2. gpt-4.1 Pesquise e selecione Implantar.
3. Na página de implantação do modelo, selecione Deploy para Microsoft Foundry.

Etapa 3: Criar um projeto de agente hospedado

1. Abra a paleta de comandos e selecione Foundry Toolkit: Criar um novo Agente Hospedado.
2. Selecione o Python como o idioma.
3. Para "Framework", selecione o Agent Framework.
4. Selecione a API de Respostas como o tipo de protocolo.
5. Selecione Básico como o código de exemplo.
6. Selecione o botão "Avançar".
7. Escolha uma pasta para os arquivos de projeto e insira um nome para o agente.
8. Para "Configuração do ambiente", escolha Configurar com o Microsoft Foundry; o conteúdo deve ser preenchido automaticamente com o projeto e o modelo que você criou nas etapas 1 e 2.
9. Selecione o botão "Criar".

Uma nova janela do VS Code se abre com o projeto como área de trabalho ativa.

Etapa 4: Instalar dependências

Crie um ambiente virtual e instale os requisitos.

Para macOS ou Linux:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Para Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Etapa 5: Testar o agente localmente

Pressione F5 para iniciar o servidor HTTP local com a depuração habilitada. O Inspetor de Agente do Foundry Toolkit é aberto para testes interativos, e você pode definir pontos de interrupção no seu código.

Para executar o servidor sem depuração:

python main.py

O agente escuta.http://localhost:8088/ Enviar um prompt de teste com curl (ou qualquer cliente HTTP):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

Etapa 6: Implantar no Serviço do Foundry Agent

1. Abra a Paleta de Comandos e selecione Foundry Toolkit: Implantar Agente Hospedado. Um WebView de implantação será aberto.
2. Para "Método de Implantação", selecione Código.
3. Selecione Remoto como o modo de pacote.
4. O "Nome do Agente" deve ser preenchido automaticamente.
5. Selecione o botão "Avançar".
6. Esta página "Revisar e Implantar" deve ser totalmente preenchida automaticamente.
7. Selecione o botão "Implantar".

Quando a implantação for concluída, o agente aparecerá em Hosted Agents (Preview) no explorador do Foundry Toolkit.

1. Verifique o status do agente:

   azd ai agent show
   

   Verifique se o agente está "Ativo".

2. Envie o mesmo prompt para o agente implantado:

   azd ai agent invoke "Write a haiku about deploying cloud applications."
   

   Você deverá ver uma resposta haiku dentro de alguns segundos.

3. (Opcional) Transmita logs de contêiner enquanto interage com o agente:

   azd ai agent monitor --follow
   

   A plataforma injeta uma cadeia de conexão do Application Insights no contêiner, de modo que os rastreamentos do OpenTelemetry também apareçam no recurso do Application Insights provisionado anteriormente. Exiba-os no portal Azure em Investigate>Transaction search ou Performance.

1. No Explorador do Foundry Toolkit, expanda Agentes Hospedados (Preview) e selecione seu agente. A página de detalhes mostra o status em Detalhes da Implantação.
2. Selecione a guia Playground e envie um prompt de teste, como Write a haiku about deploying cloud applications..

azd down

azd lista os recursos excluídos e solicita confirmação. A limpeza leva cerca de 2 a 5 minutos.

1. Abra o portal Azure e navegue até o grupo de recursos que contém o agente.
2. Selecione Excluir grupo de recursos, digite o nome do grupo de recursos a ser confirmado e selecione Excluir.