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

• Azure Developer CLI (azd) 1.27.1 ou posterior.

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

  azd ext install microsoft.foundry
  

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

  azd auth login
  

• Python 3.13 ou posterior.

• CLI do Azure instalado e autenticado:

  az login
  

• Os pacotes do SDK Python usados neste início rápido:

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

• Um projeto existente do Foundry com um modelo implantado. O caminho do SDK do Python neste guia de início rápido cria e roteia uma versão de agente hospedada, mas não cria um novo projeto do Foundry nem uma implantação de modelo para você. Se você precisar do fluxo de trabalho de provisionamento completo, use a guia do Azure Developer CLI neste artigo.

• .NET 10 SDK.

• CLI do Azure instalado e autenticado:

  az login
  

• Os pacotes de .NET usados neste início rápido.

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

  Note

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

• Um projeto existente do Foundry com um modelo implantado. O fluxo do SDK do C# cria e roteia uma versão hospedada do agente, mas ele não cria um projeto no Foundry nem uma implantação de modelo. Para o fluxo de trabalho de provisionamento completo, use a guia CLI do Desenvolvedor do Azure.

• Código do Visual Studio.
• Microsoft Foundry Toolkit para Visual Studio Code.

• aplicativo GitHub Copilot.

• A extensão Microsoft Foundry Canvas. Para instalá-lo, no aplicativo GitHub Copilot abrirPlug-ins de >, pesquise microsoft-foundrye selecione Instalar. Para obter mais informações, consulte O que é o Microsoft Foundry Canvas?

• Azure Developer CLI (azd) 1.27.1 ou posterior. A tela usa azd para testar e implantar o agente.

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

  azd ext install microsoft.foundry
  

• Um host para agente de codificação com a Microsoft Foundry Skill instalada.

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

  az login
  azd auth login
  

Etapa 1: inicializar o agente de exemplo

Inicialize um novo agente hospedado usando o exemplo básico do Agent Framework em um 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 o padrão, agent-framework-agent-basic-responses
• Projeto do Foundry: selecione Criar um novo projeto do Foundry ou Usar um projeto do Foundry existente
• Tenant: selecione seu locatário Azure
• Subscrição: selecione a subscrição do Azure
• Location: selecione uma região de Azure
• Modelo: selecione o padrão, gpt-5.4-mini ou outro modelo que você pode acessar
• Versão do modelo: selecione a opção padrão
• SKU do modelo: selecione uma opção com cota disponível que não seja o Lote, geralmente Standard ou GlobalStandard
• Capacidade de implantação: selecione o padrão, 10
• Nome da implantação: selecione o padrão, gpt-5.4-mini

Ao concluir, você verá a definição do agente de IA adicionada ao seu projeto azd com êxito! Altere o diretório para a pasta de agente recém-criada.

cd agent-framework-agent-basic-responses

Etapa 2: Provisionar recursos de Azure

Provisione os recursos definidos em azure.yaml:

azd provision

Etapa 3: Testar o agente localmente

azd ai agent run

Esse comando cria um ambiente virtual, instala dependências, inicia o agente usando o startupCommand definido azure.yamle abre o inspetor do agente no navegador para que você possa conversar com o agente.

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

Implante o código-fonte do agente. azd empacota a origem como um arquivo ZIP e o carrega no Foundry. A Foundry resolve dependências, cria o agente hospedado remotamente e o implanta:

azd deploy

Quando o comando termina, a saída mostra links para o playground do agente e o ponto de extremidade 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

Etapa 5: Invocar seu agente

1. Envie o mesmo prompt para o agente implantado:

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

   Você deverá ver uma resposta haiku dentro de alguns segundos.

2. (Opcional) Transmita logs de contêiner enquanto interage com o agente:

   azd ai agent monitor --follow
   

Etapa 1: Criar ou escolher um projeto do Foundry

1. Abra o portal do Foundry e crie um projeto de Foundry ou selecione um existente.

2. No projeto, implante um modelo compatível com chat, como gpt-5.4-mini.

3. Copie estes valores do portal:

   • Endpoint do projeto em Visão geral.
   • Nome da implantação de Build>Implantações.

Etapa 2: Baixar o código básico do agente de exemplo

Clone o repositório de exemplos do Foundry.

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

Etapa 3: Criar um ambiente Python e definir configurações

Crie um ambiente virtual e instale os pacotes de Python necessários para este início rápido.

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 de trabalho para o script de implantação e crie um .env arquivo 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>

Etapa 4: implantar o agente hospedado com Python

Crie um arquivo nomeado deploy_hosted_agent.py na mesma pasta .env de trabalho que 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 fecha a fonte de exemplo, carrega-a como uma nova versão do agente hospedado, aguarda a conclusão do provisionamento, roteia temporariamente o ponto de extremidade do agente hospedado para essa versão, invoca o agente implantado e restaura a configuração do ponto de extremidade anterior e exclui a versão temporária.

Etapa 5: Invocar seu agente

Após a conclusão do script, use o agente hospedado de qualquer uma destas maneiras:

1. Edite deploy_hosted_agent.py e altere o input valor passado para openai_client.responses.create(...), em seguida, execute o script novamente.
2. Se você quiser uma versão roteada persistente em vez de uma implantação de validação temporária, adapte o script para ignorar as etapas de restauração e delete_version(...) depois de revisar as implicações de roteamento de tráfego.
3. Se você usou o script de exemplo conforme fornecido, ele já restaura a configuração do endpoint e exclui a versão temporária do agente hospedado após a conclusão da validação.
4. Se você criou um grupo de recursos dedicado para este início rápido, poderá excluir o grupo de recursos do portal de Azure depois de não precisar mais do projeto ou da implantação do modelo.

Etapa 1: Criar ou escolher um projeto do Foundry

1. Abra o portal do Foundry e crie um projeto de Foundry ou selecione um existente.

2. No projeto, implante um modelo compatível com chat, como gpt-5.4-mini.

3. Copie estes valores do portal:

   • Endpoint do projeto em Visão geral.
   • Nome da implantação de Build>Implantações.

Etapa 2: Baixar o agente hello-world em C#

Clone o repositório de exemplos do Foundry:

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

O código-fonte do agente está em samples/csharp/hosted-agents/agent-framework/hello-world/src/hello-world-dotnet-agent-framework.

Etapa 3: Criar um projeto de implantação em C#

Crie um aplicativo de console 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 usados pelo aplicativo de implantação. 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>"

Etapa 4: Implantar o agente hospedado com C#

Substitua o conteúdo de Program.cs pelo seguinte código. O SDK do .NET empacota e faz upload do diretório-fonte, portanto você não precisa criar o arquivo ZIP por conta própria.

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 upload do código-fonte e roteamento de endpoint do exemplo de agente de código do SDK do Azure para .NET.

Execute o aplicativo:

dotnet run

O aplicativo carrega a origem do agente C#, aguarda o provisionamento, roteia o ponto de extremidade do agente para a nova versão, envia um prompt, restaura a rota anterior e exclui a versão temporária.

Etapa 5: Invocar seu agente

Após a conclusão do aplicativo, use o agente hospedado de qualquer uma destas maneiras:

1. Em Program.cs, altere o prompt enviado para CreateResponseAsync e execute dotnet run novamente.
2. Para manter a versão roteada, remova a restauração de endpoint e as chamadas DeleteAgentVersionAsync depois de analisar o impacto do roteamento de tráfego.
3. Se você usou o aplicativo C# conforme escrito, ele restaura a configuração do endpoint e exclui a versão temporária do agente hospedado após a validação.
4. Se você criou um grupo de recursos dedicado para este início rápido, exclua o grupo de recursos do portal Azure quando não precisar mais do projeto ou da implantação do modelo.

Etapa 1: Criar um projeto do Foundry

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

Etapa 2: Implantar um modelo

1. Abra a paleta de comandos e selecione Foundry Toolkit: Abrir Catálogo de Modelos.
2. gpt-4.1 Pesquise e selecione Implantar.
3. Na página de implantação do modelo, selecione Deploy para Microsoft Foundry.

Etapa 3: Criar um projeto de agente hospedado

1. Abra a paleta de comandos e selecione Foundry Toolkit: Criar um novo Agente Hospedado.
2. Selecione Python como o idioma.
3. Para o Framework, selecione a Estrutura do Agente.
4. Selecione a API de Respostas como o tipo de protocolo.
5. Selecione Básico como o código de exemplo.
6. Selecione o botão Avançar.
7. Escolha uma pasta para os arquivos de projeto e insira um nome para o agente.
8. Para a Instalação do Ambiente, escolha Configurar com o Microsoft Foundry. O conteúdo é preenchido automaticamente com o projeto e o modelo que você criou nas etapas 1 e 2.
9. Selecione o botão Criar.

Uma nova janela do VS Code se abre com o projeto como área de trabalho ativa.

Etapa 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

Etapa 5: Testar o agente localmente

Pressione F5 para iniciar o servidor HTTP local com a depuração habilitada. O Inspetor de Agente do Foundry Toolkit é aberto para testes interativos, e você pode definir pontos de interrupção no seu código.

Para executar o servidor sem depuração:

python main.py

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

Etapa 6: Implantar no Serviço do Foundry Agent

1. Abra a Paleta de Comandos e selecione Foundry Toolkit: Implantar Agente Hospedado. Um webview de implantação é aberto.
2. Para o Método de Implantação, selecione Código.
3. Selecione Remoto como o modo de pacote.
4. O Nome do Agente preenche automaticamente.
5. Selecione o botão Avançar.
6. A página Examinar e Implantar preenche automaticamente.
7. Selecione o botão Implantar .

Quando a implantação é finalizada, o agente aparece em Agentes Hospedados no explorador do Foundry Toolkit.

Etapa 7: Invocar seu agente

1. No explorador do Foundry Toolkit, expanda Agentes Hospedados e selecione seu agente. A página de detalhes mostra o status em Detalhes da Implantação.
2. Selecione a guia Playground e envie um prompt de teste, como Write a haiku about deploying cloud applications..

O Canvas do Microsoft Foundry orienta você na criação e implantação de um agente hospedado a partir de um painel lateral no aplicativo GitHub Copilot. À medida que você faz escolhas na tela, cada etapa é enviada para o Copilot com o contexto relevante do seu projeto no Foundry.

Etapa 1: Abrir a tela

1. No aplicativo GitHub Copilot, solicite Copilot criar um agente hospedado da Foundry. Por exemplo:

   Create a Foundry hosted agent using Microsoft Foundry Canvas
   

2. A tela é aberta no painel direito. Se ele não abrir automaticamente, abra-o no painel à direita.

O painel conduz você por três estágios, que correspondem às seguintes etapas:

• Crie um agente hospedado. Escolha seu projeto do Foundry e informe Copilot o que você deseja criar. Você pode começar de um prompt pré-escrito para acelerar as coisas.
• Crie o agente hospedado. Escolha o modelo, os conjuntos de ferramentas, as habilidades e os guardrails para seu agente a partir dos recursos no seu projeto do Foundry.
• Implantar e testar. Teste o agente localmente e, quando estiver satisfeito, implante-o no Serviço do Foundry Agent.

Etapa 2: Conectar um projeto do Foundry

1. Abra o menu do projeto de tela e entre no Azure se for solicitado.
2. Selecione uma assinatura.
3. Selecione um projeto do Foundry. A tela mantém essa seleção quando você a reabra.

Etapa 3: estruture o agente

Escolha como começar:

• Selecione Inspire-se para criar um agente hospedado a partir de uma ideia gerada.
• Selecione o prompt de exemplo hello world para começar de um agente básico.

O Copilot gera a estrutura básica do código do agente no seu espaço de trabalho de acordo com sua escolha.

Etapa 4: Configurar o agente

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

1. Selecione um modelo implantado para alimentar o raciocínio do agente.
2. Conecte Foundry Toolboxes e suas ferramentas para dar capacidades ao agente, como fazer chamadas a APIs ou executar código.
3. Conecte habilidades que agrupam lógica reutilizável para o agente utilizar.
4. Atribua proteções para aplicar controles de segurança e de conteúdo.

Etapa 5: Testar o agente localmente

1. Selecione Inspecionar Localmente. A tela executa azd ai agent run no terminal integrado do Copilot, aguarda o agente na porta 8088 e incorpora o Inspetor do Agente.

2. Envie um prompt de teste, como:

   Write a haiku about deploying cloud applications.
   

3. Se o inspetor relatar um erro, copie a mensagem de erro para a área de prompt da tela e peça ao Copilot para corrigir o problema.

Etapa 6: Implantar no Serviço do Foundry Agent

1. Selecione Implantar no Foundry. A tela usa azd e Copilot para implantar seu agente hospedado.
2. Quando a implantação terminar, use os links exibidos na saída para abrir o playground do agente no portal do Foundry.

Etapa 1: Abrir um espaço de trabalho com a Foundry Skill

Abra uma pasta vazia no host do agente de codificação, como GitHub Copilot em Visual Studio Code, Copilot CLI ou Claude Code. Confirme se a habilidade microsoft-foundry está disponível antes de pedir ao agente de código para criar recursos do Azure.

Se a habilidade não estiver disponível, consulte Usar a habilidade do Microsoft Foundry em agentes de codificação.

Etapa 2: peça para a habilidade criar o agente hospedado

Peça ao agente de codificação para usar a habilidade 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 do 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 ausentes ou usar valores padrão para eles, como a assinatura, a região, o nome do projeto e se deve usar um projeto existente do Foundry.

Etapa 3: Examinar e aprovar o plano

1. Examine o plano, os arquivos, os comandos, os recursos Azure e as atribuições de função que o agente de codificação propõe.
2. Para corresponder a este início rápido, escolha Python 3.13, Agent Framework, API de Respostas, Básico como código de exemplo e Código como implantação.
3. Aprove a criação de recursos que geram custos apenas após verificar a assinatura, a região, o grupo de recursos, a implantação do modelo e a cota.
4. Se o agente de programação pedir que você se autentique, execute você mesmo az login e azd auth login e, em seguida, peça ao agente de programação para continuar.

Etapa 4: permitir que a habilidade faça o scaffolding e teste o agente

Deixe que o agente de código crie o projeto do agente hospedado, provisione recursos quando você escolher um novo projeto do Foundry, grave os valores do ambiente local, prepare o ambiente local e execute um teste de fumaça local. Para agentes Python, o fluxo de trabalho da habilidade usa azd ai agent run para instalar dependências na primeira execução local.

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

Se o host do agente de codificação não puder manter um servidor local em execução para o teste de fumaça, use a guia CLI do desenvolvedor Azure neste artigo para os comandos de teste locais. Você só pode prosseguir com a implantação depois de decidir, em vez disso, validar o agente remotamente.

Etapa 5: Implantar e invocar o agente hospedado

Depois que o smoke test local for concluído com sucesso, peça ao agente de código para concluir a implantaçã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 for concluído, o agente de codificação deverá mostrar o nome do agente hospedado, a versão, o status da implantação, o endpoint, o link para o playground, os recursos criados, a resposta ao prompt de teste e qualquer comando de acompanhamento da avaliação.

azd down

Quando o ambiente criou o projeto, azd lista os recursos, solicita confirmação e os exclui em cerca de 2 a 5 minutos.

1. Abra o portal de Azure e vá para o grupo de recursos que contém seu agente.
2. Selecione Excluir grupo de recursos, digite o nome do grupo de recursos a ser confirmado e selecione Excluir.

A tela cria um espaço de trabalho baseado em azd, então você faz a limpeza com azd down da pasta do espaço de trabalho.

azd down

Quando o ambiente criou o projeto, azd lista os recursos, solicita confirmação e os exclui em cerca de 2 a 5 minutos.

A habilidade Microsoft Foundry não exclui recursos por si só. Ele pode ajudar seu agente de codificação a identificar os recursos que este início rápido criou e escolher o método de limpeza correto. Você ou o agente de codificação ainda executam o comando de limpeza depois de revisá-lo e aprová-lo.

1. Na pasta de projeto do agente hospedado, peça ao seu agente de codificação para revisar 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 do agente hospedado foi criado com azd e o grupo de recursos contém apenas recursos de início rápido, execute:

   azd down
   

3. Aprove a exclusão somente depois de verificar o grupo de recursos e os recursos que o comando lista.

Se o agente de código não puder executar comandos de limpeza, use a guia Azure Developer CLI neste artigo ou exclua o grupo de recursos no portal do Azure.