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

• Azure CLI do Desenvolvedor versão 1.24.0 ou posterior

• Visual Studio Code
• Microsoft Foundry Toolkit for Visual Studio Code extension

Permissão necessária

Você precisa do Gerente de Projeto Azure AI no escopo do projeto para criar e implantar agentes hospedados. Essa função inclui as permissões do plano de dados para criar agentes e a capacidade de atribuir a função de usuário de IA Azure à identidade do agente criada pela plataforma. A identidade do agente precisa do usuário de IA do Azure no projeto para acessar modelos e artefatos em tempo de execução.

Se você usar o azd ou a extensão do VS Code, a ferramenta manipulará a maioria das atribuições de RBAC automaticamente, incluindo:

Verifique se a identidade gerenciada do Project do Foundry tem a função de pull do ACR no Registro de Contêiner do Azure que você usa. Se você preferir e tiver acesso de proprietário ou "Administrador de Acesso do Usuário", as ferramentas azd/vscode também poderão realizar essa atribuição para você. Usuário do Azure AI para a identidade de agente criada pela plataforma (modelo de tempo de execução e acesso às ferramentas)

Etapa 1: Configurar o projeto de exemplo

Instale a extensão do agente da CLI do desenvolvedor do Azure e inicialize um novo projeto de agente hospedado.

1. Instale a extensão ai agent para a CLI do Desenvolvedor do Azure:

   azd ext install azure.ai.agents
   

   Para verificar se a extensão está instalada, execute:

   azd ext list
   

2. Inicialize um novo projeto de agente hospedado em um diretório vazio:

   azd ai agent init
   

   O fluxo interativo orienta você pela seguinte configuração:

   • Language — selecione para qual linguagem de programação você deseja obter código de exemplo, C# ou Python.
   • Modelo de Agente – Selecione um exemplo para começar.
   • Model Configuration – selecione para implantar um novo modelo no Foundry ou usar um existente de um projeto Foundry existente.
   • Assinatura Azure — selecione a assinatura onde você deseja que os recursos do Foundry sejam criados.
   • Local – selecione uma região para os recursos.
   • SKU do modelo – selecione a SKU disponível para sua região e assinatura.
   • Nome da implantação – insira um nome para a implantação do modelo.
   • Tamanho do contêiner – selecione a alocação de CPU e memória ou aceite os padrões.

   Importante

   Se você selecionou um exemplo com ferramentas e não está usando um servidor MCP, comente ou remova as seguintes linhas no agent.yaml arquivo:

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

   Dica

   Se você estiver executando em um ambiente não interativo, como um pipeline de CI/CD ou uma sessão SSH, utilize a flag --no-prompt com azd ai agent init. Você também deve fornecer todos os valores necessários como sinalizadores de linha de comando em vez de responder a prompts interativos.

3. Provisione os recursos de Azure necessários:

   Nota

   Você precisa de acesso Contributor à sua assinatura do Azure para o provisionamento de recursos.

   azd provision
   

   Esse comando leva alguns minutos e cria os seguintes recursos:

   Recurso	Propósito	Custo
   Grupo de recursos	Organiza todos os recursos relacionados na mesma área	Sem custo
   Implementação de modelo	Modelo usado pelo agente	Consulte os preços do Foundry
   Projeto de fundimento	Hospeda seu agente e fornece recursos de IA	Baseado em consumo; ver Preços do Foundry
   Registro de Contêiner do Azure	Armazena as imagens de contêiner do agente	Camada básica; consulte preços do ACR
   Workspace do Log Analytics	Gerenciar todos os dados de log em um só lugar	Sem custo direto. Veja custo do Log Analytics
   Application Insights	Monitora o desempenho e os logs do agente	Pagamento conforme o uso; consulte preços do Azure Monitor
   Identidade gerenciada	Autentica seu agente nos serviços do Azure	Sem custo

   Dica

   Execute azd down quando concluir este início rápido para excluir recursos e parar de incorrer em encargos.

Etapa 2: Testar o agente localmente

Antes de implantar, verifique se o agente funciona localmente.

1. Inicie o agente localmente:

   azd ai agent run
   

   Esse comando configura automaticamente o ambiente, instala dependências e inicia o agente. Ele usa o startupCommand definido em azure.yaml para iniciar seu agente.

   Nota

   Os pacotes de visualização podem produzir avisos de conflito de versão de dependência pip durante a configuração. Esses avisos não são bloqueadores – o agente inicia e responde corretamente, apesar deles.

   Se o agente não iniciar, verifique estes problemas comuns:

   Erro	Solução
   AuthenticationError ou DefaultAzureCredential falha	Execute azd auth logout e azd auth login para atualizar sua sessão.
   ResourceNotFound	Verifique se as URLs do endpoint correspondem aos valores no portal do Foundry.
   DeploymentNotFound	Verifique o nome da implantação em Build>Implantações.
   Connection refused	Verifique se nenhum outro processo está usando a porta 8088.

2. Em um terminal separado, envie uma mensagem de teste para o agente local.

   Para agentes que usam a API de Respostas, você pode enviar uma cadeia de caracteres como o conteúdo:

   azd ai agent invoke --local "What is Microsoft Foundry?"
   

   Para agentes que usam a API de Invocações, verifique o conteúdo esperado no README.md. Os exemplos normalmente exigem uma carga JSON, mas analise o conteúdo do README.md para esse exemplo específico:

   Você deve ver uma resposta do agente.

Etapa 3: Implantar no Serviço do Foundry Agent

Como você já provisionou a infraestrutura na Etapa 1, implante o código do agente para Azure:

azd deploy

O contêiner do agente é criado remotamente, portanto, a Área de Trabalho do Docker não é necessária em seu computador.

Quando concluída, a saída mostra um link para o Agent Playground e o ponto de extremidade para invocar o agente programaticamente:

Deploying services (azd deploy)

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

Etapa 1: Criar um projeto do Foundry

Use a extensão Microsoft Foundry Toolkit no VS Code para criar um novo recurso Microsoft Foundry Project.

1. Abra a Paleta de Comandos (Ctrl+Shift+P) e selecione Microsoft Foundry: Criar Project.

2. Selecione sua assinatura Azure.

3. Crie um novo grupo de recursos ou selecione um existente.

4. Insira um nome para o recurso do Projeto Foundry.

Depois que a criação do projeto for concluída, prossiga para a próxima etapa e implante um modelo.

Etapa 2: Implantar um modelo

Use a extensão Microsoft Foundry Toolkit no VS Code para implantar um modelo no Foundry.

1. Abra a paleta de comandos (Ctrl+Shift+P) e selecione Microsoft Foundry: Open Model Catalog.

2. Navegue pelo catálogo de modelos ou pesquise por gpt-4.1 e selecione o botão Implantar .

3. Na página Implantação de modelo, selecione o botão Implantar no Microsoft Foundry.

Depois que o modelo for implantado com êxito, vá para a próxima etapa e crie um projeto do Hosted Agent

Etapa 3: Criar um projeto do Agente Hospedado

Use a extensão Microsoft Foundry Toolkit no VS Code para estruturar um novo projeto de agente hospedado.

1. Abra a paleta de comandos (Ctrl+Shift+P) e selecione Microsoft Foundry: Create new Hosted Agent.

2. Selecione a Estrutura que você deseja usar.

3. Selecione uma linguagem de programação, Python ou C#.

4. Selecione a API de Respostas ou a API de Invocação.

5. Selecione o código de exemplo que você deseja usar.

6. Escolha a pasta na qual deseja que os arquivos do projeto sejam salvos.

7. Insira um nome para o agente hospedado.

Uma nova janela do VS Code será iniciada com a pasta de projeto do novo agente como o workspace ativo.

Etapa 4: Instalar dependências

É recomendável usar um ambiente virtual para isolar as dependências do projeto:

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Instalando dependências

Instale as dependências de Python necessárias usando pip:

pip install -r requirements.txt

Consulte o requirement.txt para obter uma lista de pacotes necessários.

Etapa 5: Testar o agente localmente

Execute e teste o seu agente antes de implantar.

Opção 1: Pressione F5 (recomendado)

Pressione F5 no VS Code para iniciar a depuração. Como alternativa, você pode usar o menu de depuração do VS Code:

1. Abra a exibição Executar e Depurar (Ctrl+Shift+D /Cmd+Shift+D)
2. Selecione "Depurar Servidor HTTP de Fluxo de Trabalho Local" na lista suspensa
3. Clique no botão verde Iniciar depuração (ou pressione F5)

Isso vai:

1. Iniciar o servidor HTTP com a depuração habilitada
2. Abra o Inspetor do Agente do Kit de Ferramentas do Foundry para teste interativo
3. Permitir que você defina pontos de interrupção e inspecione o fluxo de trabalho

Opção 2: Executar no Terminal

Executar como servidor HTTP (padrão):

python main.py

Isso iniciará o agente hospedado localmente em http://localhost:8088/.

PowerShell (Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

O agente usará a get_available_hotels ferramenta para pesquisar hotéis disponíveis que correspondam aos seus critérios.

Etapa 6: Implantar no Serviço do Foundry Agent

Implante seu agente diretamente do VS Code.

1. Abra a Paleta de Comandos (Ctrl+Shift+P) e selecione Microsoft Foundry: Implantar Agente Hospedado.

2. Selecione "ACR Padrão"

3. Selecione a configuração de CPU e memória para o contêiner do Agente Hospedado.

Alterne para o explorador do Microsoft Foundry Toolkit clicando no ícone à esquerda. O agente é exibido na barra lateral de visualização em árvore Agentes Hospedados (Versão Prévia) após a conclusão da implantação.

Verificar o status do agente

Verifique o status do agente para confirmar se ele está em execução.

1. Selecione seu agente hospedado na exibição de árvore Agentes Hospedados (Versão Prévia).

2. Selecione o agente que você acabou de implantar

A página de detalhes mostra o Status na seção Detalhes do Contêiner.

Testar no ambiente de teste usando o VS Code

Microsoft Foundry Toolkit for VS Code inclui um playground integrado para conversar e interagir com seu agente.

1. Selecione seu agente hospedado na exibição de árvore Agentes Hospedados (Versão Prévia).

2. Selecione a opção Playground e digite uma mensagem e envie para testar seu agente.

Verificar o status do agente

Verifique o status do agente implantado:

azd ai agent show

Para exibir a saída no formato de tabela:

azd ai agent show --output table

Se o projeto tiver vários serviços de agente, especifique o nome do agente como um argumento posicional:

azd ai agent show <agent-name>

Testar o agente implantado

Envie uma mensagem de teste para o agente implantado usando o mesmo invoke comando usado anteriormente, mas sem o --local sinalizador:

Para agentes que usam a API de Respostas, você pode enviar uma cadeia de caracteres como o conteúdo:

azd ai agent invoke <payload>

Você deverá ver uma resposta do agente após alguns segundos.

Exibir logs do agente

Monitore os logs ao vivo do agente:

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

Se o projeto tiver vários serviços de agente, especifique o nome do agente como um argumento posicional:

azd ai agent monitor <agent-name> --follow

Para visualizar o que será excluído, execute o down comando:

azd down

Quando concluído, azd mostra todos os recursos que serão excluídos e solicita que você confirme. Selecione yes para continuar ou no cancelar.

O processo de limpeza leva aproximadamente de 2 a 5 minutos.

Para excluir seus recursos, abra o Azure portal, navegue até o grupo de recursos e exclua-o junto com todos os recursos contidos.

Exibir os logs de contêiner do agente

Você pode verificar os logs do console e do sistema do contêiner para solucionar problemas.

1. Selecione seu agente hospedado na exibição de árvore Agentes Hospedados (Versão Prévia).

2. Selecione a aba "Playground" do agente hospedado

3. Selecione a seção "Logs" nos detalhes da sessão.

Exibir os arquivos de sessão do seu agente

Você pode exibir todos os arquivos armazenados no diretório base do agente baseado em ADC

1. Selecione o agente hospedado na exibição de árvore Agentes Hospedados (Versão Prévia).

2. Selecione a aba "Playground" do agente hospedado

3. Selecione a seção "arquivos" nos detalhes da sessão.

Você pode baixar, carregar e criar pastas dentro da pasta atual, clicar em uma pasta entrará na pasta e clicar na barra de navegação superior retornará à pasta.