Início rápido: Implemente o seu primeiro agente alojado

• Azure Developer CLI (AZD) 1.25.3 ou posterior.

• A azd microsoft.foundry extensão. Instala e verifica a extensão depois de o AZD estar instalado:

  azd ext install microsoft.foundry
  

• Iniciar sessão no Azure:

  azd auth login
  

• Visual Studio Code.
• Microsoft Foundry Toolkit para Visual Studio Code.

Passo 1: Estruturar o projeto de exemplo

Inicialize um novo projeto de agente alojado usando o manifesto básico de exemplo 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
• Inquilino: Selecione o seu inquilino Azure
• Subscrição: selecione a subscrição do Azure
• Location: Selecionar uma região Azure
• Modelo: Selecione o padrão, gpt-4.1-mini, ou outro modelo a que possa aceder.
• Versão do modelo: Selecione a opção predefinida.
• SKU do Modelo: Selecione uma opção com quota disponível que não seja Batch, normalmente 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 estiver concluído, deverá ver a definição de agente de IA adicionada com sucesso ao seu projeto azd!

Comandos não interativos

Também pode usar a --no-prompt flag para correr init num ambiente não interativo, como um agente de programação:

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>

Pode configurar as implementações do modelo ao editar a secção config em azure.yaml:

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

Passo 2: Providenciar recursos do Azure

Providencie os recursos definidos em azure.yaml:

azd provision

Este passo demora alguns minutos e cria os seguintes recursos. Para executar o provisionamento e a implementação ao mesmo tempo, pode usar azd up em vez disso.

Passo 3: Teste o agente localmente

1. Inicie o agente:

   azd ai agent run --no-inspector
   

   Este comando cria um ambiente virtual, instala dependências e lança o agente usando a startupCommand função definida em azure.yaml. Os pacotes de pré-visualização podem gerar avisos de conflito de versão de dependências do pip durante a instalação. Estes avisos não são impeditivos. O agente inicia e responde corretamente apesar disso.

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

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

   Deves ver uma resposta em haiku do agente.

Passo 4: Implementar no Foundry Agent Service

Construa e implemente o contentor do agente:

azd deploy

Quando o comando termina, a saída mostra hiperligações para o ambiente de teste do agente e para o ponto final 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

Passo 1: Criar um projeto Foundry

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

Passo 2: Implementar um modelo

1. Abra a Paleta de Comandos e selecione Foundry Toolkit: Abrir Catálogo de Modelos.
2. Procure gpt-4.1 e selecione Implementar.
3. Na página de implementação do modelo, selecione Deploy to Microsoft Foundry.

Passo 3: Criar um projeto de agente alojado

1. Abra a Paleta de Comandos e selecione Foundry Toolkit: Criar um novo Agente Alojado.
2. Selecione Python como linguagem.
3. Para "Framework", selecione Agent Framework.
4. Selecione a API de Respostas como tipo de protocolo.
5. Selecione Basic como código de exemplo.
6. Selecione o botão "Próximo".
7. Escolha uma pasta para os ficheiros do projeto e introduza um nome para o agente.
8. Para "Configuração do Ambiente", escolha Configurar com Microsoft Foundry, o conteúdo deve preencher automaticamente com o projeto e modelo que criou nos passos 1 e 2.
9. Selecione o botão "Criar".

Uma nova janela de VS Code abre-se com o projeto como espaço de trabalho ativo.

Passo 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

Passo 5: Testar o agente localmente

Prima F5 para iniciar o servidor HTTP local com a depuração ativada. O Foundry Toolkit Agent Inspector abre para testes interativos, e pode definir pontos de interrupção no seu código.

Para executar o servidor sem depuração:

python main.py

O agente ouve em http://localhost:8088/. Envie 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}'

Passo 6: Implementar no Serviço de Agentes do Foundry

1. Abra a Paleta de Comandos e selecione Foundry Toolkit: Deploy Hosted Agent. Será aberta uma visualização web de implantação.
2. Para "Método de Implementação", selecione Código.
3. Seleciona Remote como modo de pacote.
4. O "Nome do Agente" deve ser preenchido automaticamente.
5. Selecione o botão "Próximo".
6. Esta página "Rever e Implementar" deverá ser totalmente preenchida automaticamente.
7. Selecione o botão "Implementar".

Quando a implementação termina, o agente aparece em Agentes Hospedados (Pré-visualização) no explorador do Foundry Toolkit.

1. Verifique o estado do agente:

   azd ai agent show
   

   Verifique se o agente está "Ativo".

2. Envie o mesmo prompt ao agente destacado:

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

   Deves ver uma resposta de haiku dentro de alguns segundos.

3. (Opcional) Transmita os registos dos contentores enquanto interage com o agente:

   azd ai agent monitor --follow
   

   A plataforma injeta uma cadeia de ligação ao Application Insights no contentor, pelo que os rastreamentos do OpenTelemetry também aparecem no recurso do Application Insights aprovisionado anteriormente. Veja-os no portal Azure na secção Investigar>Pesquisa de transações ou Performance.

1. No explorador do Foundry Toolkit, expanda Agentes Alojados (Pré-visualização) e selecione o seu agente. A página de detalhes apresenta o estado em Detalhes da Implementação.
2. Selecione o separador Playground e envie um prompt de teste como Write a haiku about deploying cloud applications..

azd down

azd Lista os recursos que elimina e solicita confirmação. A limpeza demora cerca de 2 a 5 minutos.

1. Abra o portal Azure e navegue até ao grupo de recursos que contém o seu agente.
2. Selecione Eliminar grupo de recursos, escreva o nome do grupo para confirmar e selecione Eliminar.