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

• Azure Developer CLI (azd) 1.27.1 ou posterior.

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

  azd ext install microsoft.foundry
  

• Uma sessão azd autenticada. Inicie sessão depois de instalar a extensão:

  azd auth login
  

• Python 3.13 ou posterior.

• CLI do Azure instalado e autenticado:

  az login
  

• Os pacotes SDK em Python usados neste quickstart:

  pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv
  

• Um projeto Foundry já existente com um modelo implementado. O procedimento com o SDK do Python neste quickstart cria e encaminha uma versão alojada do agente, mas não gera a estrutura de base de um novo projeto Foundry nem cria uma implantação de modelo por si. Se precisar de todo o fluxo de trabalho de provisionamento, use o separador CLI do Azure Developer neste artigo.

• .NET 10 SDK.

• CLI do Azure instalado e autenticado:

  az login
  

• Os pacotes .NET usados neste guia de introdução rápida.

  dotnet add package Azure.AI.Projects --version 2.1.0-beta.4
  dotnet add package Azure.Identity
  

  Note

  As APIs de implementação do código-fonte estão atualmente disponíveis numa versão pré-lançamento de Azure.AI.Projects. O pacote estável 2.0.x não inclui estas APIs.

• Um projeto Foundry já existente com um modelo implementado. O caminho do SDK C# cria e encaminha uma versão de agente alojada, mas não cria um projeto Foundry ou uma implementação de modelo. Para o fluxo de trabalho de aprovisionamento completo, utilize o separador Azure Developer CLI.

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

• Aplicação GitHub Copilot.

• A extensão Microsoft Foundry Canvas. Para o instalar, na aplicação GitHub Copilot, abra Definições>Plugins, procure por microsoft-foundry e selecione Instalar. Para mais informações, consulte O que é o Microsoft Foundry Canvas?

• Azure Developer CLI (azd) 1.27.1 ou posterior. A tela é usada azd para testar e implementar o agente.

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

  azd ext install microsoft.foundry
  

• Um anfitrião de agente de programação com a Microsoft Foundry Skill instalada.

• CLI do Azure e Azure Developer CLI (azd) instalados e autenticados:

  az login
  azd auth login
  

Passo 1: Inicializar o agente de amostra

Inicialize um novo agente hospedado usando o exemplo básico do Agent Framework num diretório vazio:

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

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 project Foundry ou Utilizar um project Foundry já existente
• Inquilino: Selecione o seu inquilino Azure
• Subscrição: selecione a subscrição do Azure
• Location: Selecionar uma região Azure
• Modelo: Selecione o modelo padrão, gpt-5.4-mini, ou outro modelo a que possa aceder
• Versão do modelo: Selecione a opção padrão
• 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: Selecionar o predefinido, gpt-5.4-mini

Quando estiver concluído, verá a definição de agente de IA adicionada com sucesso ao seu projeto azd! Muda o diretório para a pasta agente recém-criada.

cd agent-framework-agent-basic-responses

Passo 2: Providenciar recursos do Azure

Providencie os recursos definidos em azure.yaml:

azd provision

Passo 3: Teste o agente localmente

azd ai agent run

Este comando cria um ambiente virtual, instala dependências, lança o agente usando a startupCommand definição em azure.yaml, e abre o inspetor de agentes no seu navegador para que possa conversar com o agente.

Passo 4: Implementar no Foundry Agent Service

Implementa o código-fonte do agente. azd empacota a fonte como ficheiro ZIP e carrega-a para o Foundry. O Foundry resolve dependências, constrói o agente hospedado remotamente e implementa-o:

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 5: Invoca o teu agente

1. 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.

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

   azd ai agent monitor --follow
   

Passo 1: Criar ou escolher um projeto Foundry

1. Abra o portal Foundry e crie um projeto Foundry, ou selecione um já existente.

2. No projeto, implemente um modelo capaz de chat, como gpt-5.4-mini.

3. Copie estes valores do portal:

   • Endpoint do Projeto na Descrição geral.
   • Nome de implementação a partir de Build>Deployments.

Passo 2: Descarregue o código básico do agente de exemplo

Clone o repositório de exemplos da Foundry.

git clone https://github.com/microsoft-foundry/foundry-samples.git

Passo 3: Criar um ambiente Python e configurar definições

Crie um ambiente virtual e instale os pacotes Python necessários para este quickstart.

Para macOS ou Linux:

python -m venv .venv
source .venv/bin/activate
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

Para Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

Crie uma pasta funcional para o script de implementação e depois crie um .env ficheiro nessa pasta:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_MODEL_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=basic-agent
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/01-basic/src/agent-framework-agent-basic-responses>

Passo 4: Implementar o agente alojado com Python

Crie um ficheiro com o nome deploy_hosted_agent.py na mesma pasta de trabalho que .env com o seguinte conteúdo:

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
  AgentEndpointConfig,
  CodeConfiguration,
  CodeDependencyResolution,
  FixedRatioVersionSelectionRule,
  HostedAgentDefinition,
  ProtocolConfiguration,
  ProtocolVersionRecord,
  ResponsesProtocolConfiguration,
  VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "basic-agent")
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
  zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
  excluded = {".git", ".venv", "__pycache__", ".env", "deploy_hosted_agent.py"}

  with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
    for path in source_dir.rglob("*"):
      if not path.is_file():
        continue
      if any(part in excluded for part in path.parts):
        continue
      zip_file.write(path, path.relative_to(source_dir))

  return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
  for attempt in range(60):
    time.sleep(10)
    details = project_client.agents.get_version(
      agent_name=agent_name,
      agent_version=version,
    )
    status = details["status"]
    print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

    if status == "active":
      return

    if status == "failed":
      raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

  raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
  code_zip_path.open("rb") as code_stream,
  DefaultAzureCredential() as credential,
  AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
  original_agent_endpoint = None
  created = None

  try:
    created = project_client.agents.create_version_from_code(
      agent_name=agent_name,
      description="Basic hosted agent deployed from local Python source.",
      definition=HostedAgentDefinition(
        cpu="0.5",
        memory="1Gi",
        code_configuration=CodeConfiguration(
          runtime="python_3_14",
          entry_point=["python", "main.py"],
          dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
        ),
        environment_variables={
          "FOUNDRY_PROJECT_ENDPOINT": endpoint,
          "FOUNDRY_MODEL_NAME": model_name,
        },
        protocol_versions=[
          ProtocolVersionRecord(protocol="responses", version="2.0.0")
        ],
      ),
      code=code_stream,
    )

    print(f"Created hosted agent version {created.version}")

    wait_for_active_version(project_client, created.version)

    original_agent_endpoint = project_client.agents.get(
      agent_name=agent_name
    ).agent_endpoint
    project_client.agents.update_details(
      agent_name=agent_name,
      agent_endpoint=AgentEndpointConfig(
        version_selector=VersionSelector(
          version_selection_rules=[
            FixedRatioVersionSelectionRule(
              agent_version=created.version,
              traffic_percentage=100,
            ),
          ]
        ),
        protocol_configuration=ProtocolConfiguration(
          responses=ResponsesProtocolConfiguration()
        ),
      ),
    )

    print(f"Agent endpoint configured for version {created.version}")

    with project_client.get_openai_client(agent_name=agent_name) as openai_client:
      response = openai_client.responses.create(
        input="Write a haiku about deploying cloud applications.",
      )

    print(f"Agent response: {response.output_text}")
  finally:
    if original_agent_endpoint is not None:
      project_client.agents.update_details(
        agent_name=agent_name,
        agent_endpoint=original_agent_endpoint,
      )
      print("Agent endpoint restored")

    if created is not None:
      project_client.agents.delete_version(
        agent_name=agent_name,
        agent_version=created.version,
        force=True,
      )
      print(f"Deleted hosted agent version {created.version}")

Executar o script:

python deploy_hosted_agent.py

O script zipa a fonte de exemplo, carrega-a como uma nova versão do agente hospedado, espera que a provisão seja concluída, encaminha temporariamente o endpoint do agente hospedado para essa versão, invoca o agente implementado e depois restaura a configuração anterior do endpoint e elimina a versão temporária.

Passo 5: Invoca o teu agente

Depois de o script terminar, use o agente hospedado de uma destas formas:

1. Edita deploy_hosted_agent.py e altera o input valor passado para openai_client.responses.create(...), e depois executa o script novamente.
2. Se pretender uma versão roteada persistente em vez de uma implementação temporária para validação, adapte o script para ignorar as etapas de restauro e delete_version(...) após analisar as implicações do encaminhamento do tráfego.
3. Se usaste o script de exemplo tal como está escrito, ele já restaura a configuração do endpoint e elimina a versão temporária do agente hospedado após a validação.
4. Se criaste um grupo de recursos dedicado para este quickstart, podes apagar o grupo de recursos do portal do Azure depois de já não precisares da implementação do projeto ou modelo.

Passo 1: Criar ou escolher um projeto Foundry

1. Abra o portal Foundry e crie um projeto Foundry, ou selecione um já existente.

2. No projeto, implemente um modelo capaz de chat, como gpt-5.4-mini.

3. Copie estes valores do portal:

   • Endpoint do Projeto na Descrição geral.
   • Nome de implementação a partir de Build>Deployments.

Passo 2: Descarregue o agente hello-world em C#

Clonar o repositório de exemplos da Foundry:

git clone https://github.com/microsoft-foundry/foundry-samples.git

A fonte do agente está em samples/csharp/hosted-agents/agent-framework/hello-world/src/hello-world-dotnet-agent-framework.

Passo 3: Criar um projeto de implementação em C#

Crie uma aplicação de consola e instale os pacotes necessários:

dotnet new console --name HostedAgentDeployer
cd HostedAgentDeployer
dotnet add package Azure.AI.Projects --version 2.1.0-beta.4
dotnet add package Azure.Identity

Defina os valores que a aplicação de implementação utiliza. No PowerShell, execute o seguinte:

$env:FOUNDRY_PROJECT_ENDPOINT = "<your-project-endpoint>"
$env:FOUNDRY_MODEL_NAME = "<your-model-deployment-name>"
$env:FOUNDRY_HOSTED_AGENT_NAME = "basic-agent"
$env:FOUNDRY_SAMPLE_PATH = "<full-path-to-hello-world-dotnet-agent-framework>"

Para macOS ou Linux, execute:

export FOUNDRY_PROJECT_ENDPOINT="<your-project-endpoint>"
export FOUNDRY_MODEL_NAME="<your-model-deployment-name>"
export FOUNDRY_HOSTED_AGENT_NAME="basic-agent"
export FOUNDRY_SAMPLE_PATH="<full-path-to-hello-world-dotnet-agent-framework>"

Passo 4: Implementar o agente alojado com C#

Substitua o conteúdo de Program.cs pelo seguinte código. O SDK .NET empacota e carrega o diretório de origem, por isso não precisas de criar o arquivo ZIP tu próprio.

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
  ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT isn't set.");
var modelName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL_NAME")
  ?? throw new InvalidOperationException("FOUNDRY_MODEL_NAME isn't set.");
var agentName = Environment.GetEnvironmentVariable("FOUNDRY_HOSTED_AGENT_NAME")
  ?? "basic-agent";
var samplePath = Environment.GetEnvironmentVariable("FOUNDRY_SAMPLE_PATH")
  ?? throw new InvalidOperationException("FOUNDRY_SAMPLE_PATH isn't set.");

AIProjectClient projectClient = new(
  endpoint: new Uri(projectEndpoint),
  tokenProvider: new DefaultAzureCredential());

HostedAgentDefinition definition = new(cpu: "0.5", memory: "1Gi")
{
  Versions =
  {
    new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0")
  },
  CodeConfiguration = new(
    runtime: "dotnet_10",
    entryPoint: ["dotnet", "hello-world.dll"],
    dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add(
  "FOUNDRY_PROJECT_ENDPOINT", projectEndpoint);
definition.EnvironmentVariables.Add(
  "AZURE_AI_MODEL_DEPLOYMENT_NAME", modelName);

ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;

try
{
  created = await projectClient.AgentAdministrationClient
    .CreateAgentVersionFromCodeAsync(
      agentName: agentName,
      filePath: samplePath,
      metadata: new AgentVersionFromCodeMetadata(definition));
  Console.WriteLine($"Created hosted agent version {created.Version}");

  for (var attempt = 1; attempt <= 60; attempt++)
  {
    await Task.Delay(TimeSpan.FromSeconds(10));
    created = await projectClient.AgentAdministrationClient
      .GetAgentVersionAsync(agentName, created.Version);
    Console.WriteLine(
      $"Provisioning status: {created.Status} (attempt {attempt}/60)");

    if (created.Status == AgentVersionStatus.Active)
    {
      break;
    }
    if (created.Status == AgentVersionStatus.Failed)
    {
      throw new InvalidOperationException("Hosted agent provisioning failed.");
    }
  }

  if (created.Status != AgentVersionStatus.Active)
  {
    throw new TimeoutException(
      "Timed out waiting for the hosted agent version to become active.");
  }

  ProjectsAgentRecord agent = await projectClient.AgentAdministrationClient
    .GetAgentAsync(agentName);
  originalEndpoint = agent.AgentEndpoint;

  AgentEndpointConfiguration endpoint = new()
  {
    VersionSelector = new(
      [new FixedRatioVersionSelectionRule(created.Version, 100)]),
    ProtocolConfiguration = new()
    {
      Responses = new ResponsesProtocolConfiguration()
    }
  };
  await projectClient.AgentAdministrationClient.PatchAgentAsync(
    agentName,
    new PatchAgentOptions { AgentEndpoint = endpoint });
  Console.WriteLine($"Agent endpoint configured for version {created.Version}");

  ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
    .GetProjectResponsesClientForAgentEndpoint(agentName);
  ResponseResult response = await responsesClient.CreateResponseAsync(
    "Write a haiku about deploying cloud applications.");
  Console.WriteLine($"Agent response: {response.GetOutputText()}");
}
finally
{
  if (originalEndpoint is not null)
  {
    await projectClient.AgentAdministrationClient.PatchAgentAsync(
      agentName,
      new PatchAgentOptions { AgentEndpoint = originalEndpoint });
    Console.WriteLine("Agent endpoint restored");
  }

  if (created is not null)
  {
    await projectClient.AgentAdministrationClient.DeleteAgentVersionAsync(
      agentName,
      created.Version,
      force: true);
    Console.WriteLine($"Deleted hosted agent version {created.Version}");
  }
}

O código segue os padrões de carregamento do código-fonte e de encaminhamento de pontos finais do exemplo do agente de código do SDK do Azure para .NET.

Execute a aplicação:

dotnet run

A aplicação carrega a fonte do agente C#, espera pelo provisionamento, encaminha o endpoint do agente para a nova versão, envia um prompt, restaura a rota anterior e apaga a versão temporária.

Passo 5: Invoca o teu agente

Após a conclusão da aplicação, utilize o agente hospedado de uma destas formas:

1. Em Program.cs, altere o prompt passado para CreateResponseAsync, e depois execute dotnet run novamente.
2. Para manter a versão roteada, remova o endpoint-restoration e as chamadas DeleteAgentVersionAsync após analisar o impacto do roteamento do tráfego.
3. Se usou a aplicação C# tal como está escrita, ela restaura a configuração do endpoint e apaga a versão temporária do agente hospedado após a validação.
4. Se criaste um grupo de recursos dedicado para este quickstart, apaga o grupo de recursos do portal do Azure quando já não precisares do projeto ou da implementação do modelo.

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 Avançar.
7. Escolha uma pasta para os ficheiros do projeto e introduza um nome para o agente.
8. Para Configuração de Ambiente, escolha Configurar com Microsoft Foundry. O conteúdo preenche-se 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. Abre-se uma webview 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 preenche automaticamente.
5. Selecione o botão Avançar.
6. A página de Revisão e Implementação preenche-se automaticamente.
7. Selecione o botão Implantar .

Quando a implementação termina, o agente aparece em Agentes Alojados no explorador Foundry Toolkit.

Passo 7: Invocar o seu agente

1. No explorador Foundry Toolkit, expanda Agentes Alojados 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..

O Microsoft Foundry Canvas guia-o na construção e implementação de um agente alojado a partir de um painel lateral na aplicação GitHub Copilot. À medida que fazes escolhas na tela, ele passa cada passo para o Copilot com o contexto relevante do teu projeto Foundry.

Passo 1: Abra a tela

1. Na aplicação GitHub Copilot, pede ao Copilot para criar um agente hospedado na Foundry. Por exemplo:

   Create a Foundry hosted agent using Microsoft Foundry Canvas
   

2. A tela abre-se no painel direito. Se não abrir automaticamente, abre-o pelo painel direito.

A tela guia-o por três fases, que correspondem aos seguintes passos:

• Crie um agente hospedado. Escolhe o teu projeto Foundry e diz ao Copilot o que queres construir. Podes começar com um prompt pré-escrito para acelerar as coisas.
• Constrói o agente alojado. Escolha o modelo, as caixas de ferramentas, as competências e os limites para o seu agente a partir dos recursos do seu projeto Foundry.
• Implantar e testar. Teste o agente localmente e, quando estiver satisfeito, implemente-o no Foundry Agent Service.

Passo 2: Ligar um projeto Foundry

1. Abre o menu do projeto canvas e inicia sessão no Azure se fores solicitado.
2. Selecione uma subscrição.
3. Selecione um projeto Foundry. A tela mantém esta seleção quando a reabrir.

Passo 3: Andaime o agente

Escolha como começar:

• Selecione Inspire-me para criar a estrutura de base de um agente alojado a partir de uma ideia gerada.
• Selecione o prompt de exemplo Hello World para começar a partir de um agente básico.

O Copilot estrutura o código do agente no seu espaço de trabalho com base na sua escolha.

Passo 4: Configurar o agente

Nesta fase, liga o agente aos recursos do seu projeto Foundry. Cada seleção envia um prompt para o Copilot, que atualiza o código do agente e a configuração para si:

1. Selecione um modelo implementado para fundamentar o raciocínio do agente.
2. Ligue as Foundry Toolboxes e as respetivas ferramentas para dotar o agente de capacidades, como invocar APIs ou executar código.
3. Ligue capacidades que agrupam lógica reutilizável para o agente utilizar.
4. Atribua proteções para aplicar controlos de segurança e de conteúdo.

Passo 5: Testar o agente localmente

1. Selecione Inspecionar Localmente. A tela corre azd ai agent run no terminal integrado do Copilot, espera pelo agente no porto 8088e integra o Agente Inspetor.

2. Envie um enunciado de teste, tais como:

   Write a haiku about deploying cloud applications.
   

3. Se o inspetor reportar um erro, copie a mensagem de erro na área de prompt do canvas e peça ao Copilot para corrigir o problema.

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

1. Selecione Implementar na Foundry. A tela usa azd e o Copilot para implementar o seu agente alojado.
2. Quando a implementação terminar, use os links na saída para abrir o playground de agentes no portal Foundry.

Passo 1: Abra um espaço de trabalho com a Foundry Skill

Abra uma pasta vazia no host do seu agente de programação, como o GitHub Copilot no Visual Studio Code, Copilot CLI ou Claude Code. Confirme que a microsoft-foundry competência está disponível antes de pedir ao agente de programação para criar recursos no Azure.

Se a capacidade não estiver disponível, siga Utilizar a capacidade Microsoft Foundry em agentes de programação.

Passo 2: Peça à habilidade para criar o agente hospedado

Pede ao teu agente de programação que use a capacidade para o fluxo de trabalho completo do agente hospedado:

Use the Microsoft Foundry Skill hosted-agent quick-start workflow to create my
first hosted agent end to end. Verify my environment first, and stop if I need
to sign in myself. Use Python 3.13, Agent Framework, the Responses API, the
Basic sample, and code deployment. Create a new Foundry project unless I provide
an existing project. Use the model deployment from the Basic sample unless I
provide an existing deployment. Test the agent locally, deploy it to Foundry
Agent Service, and invoke it with: "Write a haiku about deploying cloud
applications."

O agente de codificação deve inspecionar as ferramentas Foundry disponíveis quando as ferramentas MCP estiverem disponíveis, carregar o fluxo de trabalho de início rápido do agente hospedado e solicitar os valores em falta ou assumir valores predefinidos, como a subscrição, a região, o nome do projeto e se deve ser utilizado um projeto Foundry existente.

Passo 3: Rever e aprovar o plano

1. Revise o plano, ficheiros, comandos, recursos do Azure e atribuições de funções que o agente de programação propõe.
2. Para corresponder a este guia de introdução rápida, escolha Python 3.13, Agent Framework, Responses API, Basic código de exemplo e implementação de código.
3. Aprove a criação de recursos que suportem custos apenas depois de verificar a subscrição, região, grupo de recursos, implementação do modelo e quota.
4. Se o agente de programação lhe pedir para se autenticar, execute az login e azd auth login tu mesmo e, em seguida, peça ao agente de programação para continuar.

Passo 4: Deixe a competência criar a estrutura e testar o agente

Deixe o agente codificador criar o projeto do agente hospedado, fornecer recursos quando escolher um novo projeto Foundry, escrever valores do ambiente local, preparar o ambiente local e realizar um teste de fumo local. Para os agentes Python, o fluxo de trabalho de skill usa azd ai agent run para instalar dependências durante a primeira execução local.

O fluxo de trabalho deve também adicionar o ficheiro de orientação do projeto exigido pelo anfitrião do agente de codificação e verificar a sanidade da configuração gerada do projeto antes do teste local.

Se o teu agente de codificação anfitrião não conseguir manter um servidor local em execução para o teste rápido, usa o separador da CLI do Azure Developer neste artigo para obter os comandos de teste local. Só podes continuar a implementar depois de decidires validar o agente remotamente.

Passo 5: Implementar e invocar o agente hospedado

Depois de o teste local de fumo ser bem-sucedido, peça ao seu agente de codificação para concluir a implementação e a validação remota:

Continue with the Microsoft Foundry Skill workflow. Deploy the hosted agent to
Foundry Agent Service, show the deployment status and playground link, and invoke
it remotely with: "Write a haiku about deploying cloud applications." If the
skill workflow requires evaluation suite generation before the final summary,
submit the generation job and show me the follow-up eval command.

Quando o fluxo de trabalho termina, o agente de programação deve mostrar o nome do agente hospedado, a versão, o estado da implementação, o endpoint, a ligação para o playground, os recursos criados, a resposta ao prompt de teste e qualquer comando de seguimento da avaliação.

azd down

Quando o ambiente criou o projeto, azd lista os recursos, pede confirmação e apaga-os em cerca de 2-5 minutos.

1. Abre o portal do Azure e vai ao grupo de recursos que contém o teu agente.
2. Selecione Eliminar grupo de recursos, escreva o nome do grupo para confirmar e selecione Eliminar.

A tela de desenho cria um espaço de trabalho baseado em azd, por isso fazes a limpeza com azd down na pasta do espaço de trabalho.

azd down

Quando o ambiente criou o projeto, azd lista os recursos, pede confirmação e apaga-os em cerca de 2-5 minutos.

A Microsoft Foundry Skill não apaga recursos sozinha. Pode ajudar o seu agente de programação a identificar os recursos que este quickstart criou e a escolher o método certo de limpeza. Você ou o seu agente de programação continuam a executar o comando de limpeza depois de o rever e aprovar.

1. Na pasta do projeto do agente alojado, peça ao seu agente de programação para rever a limpeza:

   Use the Microsoft Foundry Skill to identify the Azure resources created for
   this quickstart. Confirm whether azd down is the right cleanup method for
   this project, and show me the resources before any deletion command runs.
   

2. Se o projeto agente alojado foi criado com azd e o grupo de recursos contém apenas recursos de início rápido, execute:

   azd down
   

3. Aprove a eliminação apenas depois de verificar o grupo de recursos e os recursos que o comando lista.

Se o seu agente de programação não conseguir executar comandos de limpeza, use o separador Azure Developer CLI neste artigo ou elimine o grupo de recursos do portal Azure.