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

• Azure Developer CLI versão 1.24.0 ou posterior

• Visual Studio Code
• Extensão Microsoft Foundry Toolkit para o Visual Studio Code

Permissão necessária

Precisas do Gestor de Projetos do Azure AI no escopo do projeto para criar e implementar agentes hospedados. Este papel inclui tanto as permissões do plano de dados para criar agentes como a capacidade de atribuir o papel de Utilizador IA Azure à identidade do agente criado pela plataforma. A identidade do agente precisa do Azure AI User no projeto para aceder a modelos e artefactos em tempo de execução.

Se utilizares azd ou a extensão Visual Studio Code, a ferramenta trata automaticamente da maioria das atribuições RBAC, incluindo:

Certifique-se de que a identidade gerida do Foundry Project tem a função de pull ACR no Azure Container Registry que utiliza. Se preferires e tiveres acesso como Proprietário ou "Administrador de Acesso ao Utilizador", então as ferramentas azd/vscode também podem fazer esta tarefa por ti. Azure AI User para a identidade de agente criada pela plataforma (modelo de execução e acesso à ferramenta)

Passo 1: Configurar o projeto de exemplo

Instale a extensão do agente CLI do Azure Developer e inicialize um novo projeto de agente alojado.

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

   azd ext install azure.ai.agents
   

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

   azd ext list
   

2. Inicialize um novo projeto agente alojado num diretório vazio:

   azd ai agent init
   

   O fluxo interativo guia-o pela seguinte configuração:

   • Language — Selecione a linguagem de programação para a qual quer código de exemplo, seja C# ou Python.
   • Modelo de Agente - Selecione um exemplo para começar.
   • Configuração do Modelo - Selecione implementar um novo modelo no Foundry ou usar um existente de um Projeto Foundry já existente.
   • Subscrição Azure — selecione a subscrição onde pretende que os recursos da Foundry sejam criados.
   • Localização — selecione uma região para os recursos.
   • SKU de modelo — selecione o SKU disponível para a sua região e subscrição.
   • Nome da implementação — insira um nome para a implementação do modelo.
   • Tamanho do contentor — selecione a CPU e a alocação de memória ou aceite os predefinidos.

   Importante

   Se selecionou um exemplo com ferramentas e não estiver a usar um servidor MCP, comente ou remova as seguintes linhas do agent.yaml ficheiro:

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

   Dica

   Se estiver a correr num ambiente não interativo, como um pipeline CI/CD ou uma sessão SSH, use o sinalizador --no-prompt com azd ai agent init. Deve também fornecer todos os valores necessários como sinalizadores de linha de comandos, em vez de responder a prompts interativos.

3. Provisionar os recursos Azure necessários:

   Nota

   Precisa de acesso Contributor na sua subscrição Azure para provisionamento de recursos.

   azd provision
   

   Este comando demora alguns minutos e cria os seguintes recursos:

   Recurso	Finalidade	Custo
   Grupo de recursos	Organiza todos os recursos relacionados na mesma área	Sem custos
   Implementação do modelo	Modelo utilizado pelo agente	Ver preços da fundição
   Projeto da fundição	Aloja o seu agente e fornece capacidades de IA	Baseada no consumo; ver Preços da fundição
   Azure Container Registry	Armazena as imagens do contentor do seu agente	Nível básico; ver preços ACR
   Espaço de Trabalho de Analítica de Logs	Gerir todos os dados de registo num só local	Sem custo direto. Ver custo do Log Analytics
   Application Insights	Monitoriza o desempenho do agente e os registos	Paga conforme o uso; veja preços do Azure Monitor
   Identidade gerida	Autentica o seu agente aos serviços do Azure	Sem custos

   Dica

   Executa azd down quando terminares este guia de início rápido para apagar recursos e parar de incorrer em custos.

Passo 2: Teste o agente localmente

Antes de implementar, verifica se o agente funciona localmente.

1. Inicie o agente localmente:

   azd ai agent run
   

   Este comando configura automaticamente o ambiente, instala dependências e inicia o agente. Utiliza o startupCommand definido em azure.yaml para lançar o seu agente.

   Nota

   Os pacotes de pré-visualização podem gerar avisos de conflito de versões de dependência do pip durante a configuração. Estes avisos não bloqueiam — o agente começa e responde corretamente apesar deles.

   Se o agente não conseguir arrancar, verifique estes problemas comuns:

   Erro	Solução
   AuthenticationError ou DefaultAzureCredential falha	Executa azd auth logout e depois azd auth login para atualizar a tua sessão.
   ResourceNotFound	Verifique se os URLs dos seus endpoints correspondem aos valores do portal Foundry.
   DeploymentNotFound	Verifique o nome da implementação em Build>Deployments.
   Connection refused	Certifique-se de que nenhum outro processo está a usar a porta 8088.

2. Num terminal separado, envie uma mensagem de teste ao agente local.

   Para agentes que usam a API Responses, pode enviar uma string como payload:

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

   Para os agentes que utilizam a API de Invocações, verifique a carga útil esperada no README.md. As amostras normalmente requerem uma carga útil JSON, mas reveja o que está na amostra README.md para um exemplo específico.

   Deves ver uma resposta do agente.

Passo 3: Implementar no Foundry Agent Service

Como já provisionaste a infraestrutura no Step 1, implementa o código do teu agente no Azure:

azd deploy

O contentor do agente é construído remotamente, por isso o Docker Desktop não é obrigatório na sua máquina.

Quando termina, a saída mostra uma ligação ao Agent Playground e ao endpoint 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

Passo 1: Criar um projeto 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 a sua subscrição do Azure.

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

4. Insira um nome para o recurso Foundry Project.

Quando a criação do projeto estiver concluída, continue para o passo seguinte e implemente um modelo.

Passo 2: Implementar um modelo

Use a extensão Microsoft Foundry Toolkit no VS Code para implementar 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 procure por gpt-4.1 e selecione o botão Deploy .

3. Na página de implementação do modelo, selecione o botão Deploy to Microsoft Foundry.

Depois de o modelo ser implementado com sucesso, passe para o passo seguinte e crie um projeto de Agente Alojado

Passo 3: Criar um projeto de Agente Alojado

Utilize a extensão Microsoft Foundry Toolkit no ambiente VS Code para iniciar um novo projeto de agente hospedado.

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

2. Seleciona o Framework que queres usar.

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

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

5. Seleciona o código de exemplo que queres usar.

6. Escolhe a pasta onde queres que os ficheiros do projeto sejam guardados.

7. Insira um nome para o agente alojado.

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

Passo 4: Instalar dependências

Recomenda-se 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

Instalação de Dependências

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

pip install -r requirements.txt

Consulte o requirement.txt para uma lista de pacotes obrigatórios.

Passo 5: Testar o agente localmente

Executa e testa o teu agente antes de o implementar.

Opção 1: Carregar em F5 (recomendado)

Pressiona F5 em VS Code para iniciar a depuração. Alternativamente, pode usar o menu de depuração do VS Code:

1. Abrir a vista Executar e Depurar (Ctrl+Shift+D / Cmd+Shift+D)
2. Selecione "Debug Local Workflow HTTP Server" no menu suspenso
3. Clique no botão verde Iniciar Depuração (ou pressione F5)

Isto irá:

1. Inicia o servidor HTTP com a depuração ativada
2. Abra o Foundry Toolkit Agent Inspector para testes interativos
3. Permite-te definir pontos de falha e inspecionar o fluxo de trabalho

Opção 2: Executar no Terminal

Executar como servidor HTTP (por defeito):

python main.py

Isto 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 procurar hotéis disponíveis que correspondam aos seus critérios.

Passo 6: Deslocar para o Serviço de Agentes da Fundição

Implementa o teu agente diretamente a partir do VS Code.

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

2. Selecione "Default ACR"

3. Selecione a configuração de CPU e Memória para o contentor do Agente Hospedado.

Mude para o explorador do Microsoft Foundry Toolkit selecionando o ícone à esquerda. O agente aparece na barra lateral da visualização em árvore dos Agentes Hospedados (Pré-visualização) após a conclusão da implantação.

Verificar o estado do agente

Verifique o estado do seu agente para confirmar que está a funcionar.

1. Selecione o seu agente alojado na vista de árvore de Agentes Hospedados (Pré-visualização).

2. Seleciona o agente que acabaste de implementar

A página de detalhes mostra o status na seção de Detalhes do Contentor.

Teste no playground usando VS Code

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

1. Selecione o seu agente alojado na vista de árvore de Agentes Hospedados (Pré-visualização).

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

Verificar o estado do agente

Verifique o estado do seu agente destacado:

azd ai agent show

Para mostrar a saída em formato de tabela:

azd ai agent show --output table

Se o seu projeto tiver múltiplos serviços de agentes, especifique o nome do agente como argumento posicional:

azd ai agent show <agent-name>

Testar o agente implementado

Envie uma mensagem de teste ao seu agente implementado usando o mesmo invoke comando usado anteriormente, mas sem a --local bandeira:

Para agentes que usam a API Responses, pode enviar uma string como payload:

azd ai agent invoke <payload>

Deves ver uma resposta do agente passados alguns segundos.

Ver registos do agente

Monitorize os registos em tempo real do seu 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 seu projeto tiver múltiplos serviços de agentes, especifique o nome do agente como argumento posicional:

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

Para pré-visualizar o que será eliminado, execute o down comando:

azd down

Quando estiver concluído, azd mostra-te todos os recursos que serão eliminados e pede-te para confirmar. Selecione yes continuar ou no cancelar.

O processo de limpeza demora aproximadamente 2 a 5 minutos.

Para eliminar os seus recursos, abra o portal Azure, navegue até ao seu grupo de recursos e elimine-o juntamente com todos os recursos contidos.

Consulte os registos de contentores do seu agente

Podes verificar os registos da consola e do sistema do contentor para resolver problemas.

1. Selecione o seu agente alojado na vista de árvore de Agentes Hospedados (Pré-visualização).

2. Selecione o separador "Playground" do seu agente alojado

3. Selecione a secção "Registos" nos detalhes da sessão.

Consulte os ficheiros de sessão do seu agente

Podes ver todos os ficheiros armazenados na pasta pessoal do teu agente baseado em ADC

1. Selecione o seu agente alojado na árvore de agentes hospedados (pré-visualização).

2. Selecione o separador "Playground" do seu agente alojado

3. Selecione a secção "ficheiros" nos detalhes da sessão.

Podes descarregar, carregar e criar pastas dentro da pasta atual, clicar numa pasta vai entrar na pasta, e clicar na barra de navegação superior volta a essa pasta.