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

• Azure CLI do Desenvolvedor versão 1.24.0 ou posterior

• Código do Visual Studio
• Extensão do Microsoft Foundry Toolkit para Visual Studio Code

Permissão necessária

Você precisa do Azure AI Project Manager 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 do Azure AI 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:

Certifique-se de que a identidade gerenciada do Projeto do Foundry tenha a função de pull do ACR no Registro de Contêiner do Azure que você utiliza. Se você preferir e tiver acesso de Proprietário ou "Administrador de Acesso do Usuário", as ferramentas azd/vscode também poderão fazer esta atribuição para você. Usuário de IA do Azure para a identidade do agente criada pela plataforma (modelo de execução e acesso a 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 Python.
   • Agent Template - Selecione 'Agente básico (Respostas, Estrutura do Agente, Python)'
   • Configuração do Modelo – selecione para desenvolver um novo modelo na Foundry ou usar um existente de um projeto do Foundry existente.
   • Assinatura do Azure — selecione a assinatura na qual 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, use a flag --no-prompt com azd ai agent init. Você também deve fornecer todos os valores necessários como opções de linha de comando, em vez de responder a prompts interativos.

3. Provisione os recursos de Azure necessários:

   Nota

   Você precisa de acesso de Colaborador na sua assinatura do Azure para 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
   Implantação do 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; ver 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 consumo; 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

   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 são bloqueantes — o agente inicia e responde corretamente, apesar deles.

   Caso o agente não inicie, verifique estes problemas comuns:

   Erro	Solução
   AuthenticationError ou DefaultAzureCredential falha	Execute azd auth logout e depois azd auth login para atualizar a sessão.
   ResourceNotFound	Verifique se as URLs de 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 README.md para o conteúdo esperado. Os exemplos normalmente exigem um payload JSON, mas verifique o conteúdo de README.md daquela amostra para obter um exemplo específico:

   Você deve ver uma resposta do agente.

Etapa 3: Implantar no Serviço de Agente do Foundry

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 Foundry Project.

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 para 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 invoque a API.

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á aberta com a nova pasta de projeto do agente como 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 seu agente antes de implementar.

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 de Agente do Foundry

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 selecionando o ícone à esquerda. O agente aparece na barra lateral da exibição em árvore de 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 o agente hospedado na exibição em árvore dos 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 o agente hospedado na exibição em árvore dos 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 "Hello"

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.

Visualizar os logs dos contêineres do agente

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

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

2. Selecione a guia "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 em árvore dos Agentes Hospedados (Versão Prévia).

2. Selecione a guia "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.