Criar agentes hospedados com o Microsoft Foundry Toolkit para Visual Studio Code

Use o Kit de Ferramentas do Microsoft Foundry para Visual Studio Code para criar um fluxo de trabalho baseado em código a partir de um exemplo de Microsoft Agent Framework. Execute-o localmente com o Inspetor do Agente e, em seguida, implante seu código-fonte no Serviço do Agente do Foundry como um agente hospedado. Você mantém o código e suas dependências. A Foundry gerencia a infraestrutura de hospedagem e o dimensionamento.

Os fluxos de trabalho hospedados coordenam agentes no código. Eles diferem do serviço de fluxo de trabalho declarativo do Foundry desativado. Para outras rotas de criação, consulte Criar um agente.

Pré-requisitos

  • Instale Microsoft Foundry Toolkit para Visual Studio Code.

  • Selecione um projeto do Foundry com um modelo implantado. Use uma região de agente hospedado com suporte.

  • Permissão para usar o modelo e implantar agentes hospedados. Para implantação de código-fonte, a função Gerente de Projeto do Foundry no escopo do projeto inclui operações de agente e permissões de atribuição de funções. Consulte as permissões do agente hospedado.

    Importante

    As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

  • CLI do Azure para as etapas de autenticação local neste artigo.

  • Para a implantação de contêineres, o registro e o acesso à imagem exigidos pela configuração do Registro de Contêiner do Azure. Esses requisitos do Registro não se aplicam a uma implantação de código-fonte.

  • Python 3.13 para o ambiente de execução hospedado configurado para o exemplo.
  • A extensão Python para Visual Studio Code.

O caminho de implantação principal usa Código com modo de pacote remoto e não requer um build local do Docker. A execução local ainda envia solicitações ao modelo para o Foundry e pode gerar cobranças. Examine os limites de serviço e a disponibilidade e as notas de versão do Kit de Ferramentas para os recursos que você usa.

Criar um fluxo de trabalho do agente hospedado

Escolha um exemplo do Agent Framework que use o protocolo Respostas. Você não precisa criar um agente de prompt separado primeiro. Para comparar exemplos, o Construtor de Agentes e a codificação assistida por Copilot, consulte Escolher uma rota de criação.

Use o fluxo de trabalho multiagente (Agent Framework), que encadeia um redator, um revisor e um formatador. A resposta final vem do formatador. Examine o exemplo de fluxo de trabalho Python para a implementação completa e suas diretrizes de modelo.

Use o Fluxo de Trabalho de Tradução, que encadeia três agentes de tradução: inglês para francês, francês para espanhol e espanhol para inglês. Examine o exemplo de fluxo de trabalho do C# para obter a implementação completa.

  1. Na exibição Foundry Toolkit, selecione Developer Tools>>.

  2. Em Codificar um agente de exemplos, selecione Procurar todos os exemplos.

  3. Em Criar Agente Hospedado a partir de Exemplo, filtre por seu Idioma, Framework = e Tipo de Protocolo = . Pesquise por workflow.

    A captura de tela a seguir mostra a galeria com o Agente Hospedado Básico selecionado como exemplo. Para este guia, selecione o exemplo de fluxo de trabalho para seu idioma.

    Captura de tela da galeria de exemplos do agente hospedado com o Agente Hospedado Básico selecionado, exemplos de fluxo de trabalho e filtros de idioma, estrutura e protocolo.

  4. Selecione o exemplo de fluxo de trabalho para seu idioma.

  5. Selecione Próximo.

  6. Em Criar, escolha a Pasta da área de trabalho. Se a pasta já contiver arquivos, insira um Nome de Pasta para uma nova pasta filho.

  7. Se Configuração do ambiente aparecer, selecione Configurar com Microsoft Foundry e, em seguida, selecione sua assinatura e projeto. Quando um projeto padrão já está selecionado, o formulário usa esse projeto.

  8. Selecione uma implantação de modelo existente e compatível.

    A captura de tela a seguir mostra as configurações de projeto de exemplo com caminhos locais ocultos. Use seu próprio destino e a implantação de modelo exigida pelo seu exemplo.

    Captura de tela da guia Criar mostrando a pasta do workspace, o nome da pasta, a implantação do modelo e os controles de criação, com os caminhos locais ocultos.

  9. Examine o destino e selecione Criar.

  10. Abra o projeto gerado em Visual Studio Code e leia sua README.md.

Os blocos Agent Framework, Copilot SDK e LangGraph na tela Create Agent abrem a guia Create com um modelo inicial hello-world selecionado. Use Ver todos os exemplos para escolher um fluxo de trabalho em vez de um desses modelos iniciais. Você também pode abrir a galeria em Meus Recursos>Agentes>>.

Os nomes e os conteúdos de exemplo podem mudar dependendo do catálogo. Algumas versões rotulam esses fluxos de trabalho de exemplo. Use o link GitHub do exemplo para confirmar se você selecionou o fluxo de trabalho pretendido.

Ignorar por enquanto gera o código sem concluir a configuração do modelo. Se você escolher, configure os valores de projeto e modelo necessários antes de executar o exemplo. Implantar e usar um novo modelo, quando disponível, faz o provisionamento de uma implantação de modelo, não do agente hospedado. A criação dos arquivos de projeto local não implanta o agente.

Configurar o projeto local

Mantenha a pasta que contém azure.yaml aberta como pasta raiz do workspace. Verifique o caminho do project serviço de agente hospedado nesse arquivo para localizar seu diretório de origem.

Artefato Purpose
azure.yaml Declara o serviço de agente hospedado, o diretório de origem, o runtime, os protocolos e as configurações de implantação.
main.py ou Program.cs no diretório de origem Implementa o fluxo de trabalho e inicia seu servidor de respostas.
requirements.txt ou o arquivo .csproj Declara dependências para o idioma selecionado.
.env no diretório de origem Contém valores de projeto e modelo locais. O Kit de Ferramentas o cria de .env.example quando o exemplo fornece esse arquivo.
.vscode/launch.json e .vscode/tasks.json Configure o servidor local, o anexo do depurador e o Inspetor do Agente.

Layouts de exemplo podem ser alterados. Use os README.md e azure.yaml gerados, em vez de presumir que o código e o arquivo de ambiente estão na raiz do espaço de trabalho.

Instalar dependências

Use os arquivos de dependência do exemplo gerado. Mantenha o interpretador ou o SDK selecionado consistente com sua configuração de runtime.

  1. Execute Python: Criar Ambiente... na Paleta de Comandos para criar um ambiente virtual ou Python: Selecione Interpretador para selecionar um ambiente existente Python 3.13. Para configuração e seleção de ambientes, consulte Ambientes do Python no Visual Studio Code.

  2. Abra um terminal com esse ambiente ativo. Altere para o diretório de origem que contém main.py e requirements.txt.

  3. Instale os pacotes do exemplo:

    python -m pip install -r requirements.txt

    Os requisitos incluem debugpy, que a configuração F5 gerada utiliza. Referência: Dependências do fluxo de trabalho do Python.

  1. Execute C#: Verificar os requisitos do espaço de trabalho na Paleta de Comandos.

  2. Em um terminal, altere para o diretório de origem que contém o .csproj arquivo e restaure seus pacotes:

    dotnet restore

    Referência: dotnet restore.

Para controles e configuração do depurador, consulte depuração de C# no Visual Studio Code.

Definir o projeto e o modelo

Examine o .env arquivo no diretório de origem. Se ele não existir, crie-o com os valores exigidos pelo exemplo.

Variable Value
FOUNDRY_PROJECT_ENDPOINT O endpoint do seu projeto, na forma https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
AZURE_AI_MODEL_DEPLOYMENT_NAME O nome da implantação do modelo nesse projeto, e não apenas o nome do catálogo do modelo.

Ambos os exemplos de fluxo de trabalho carregam .env durante a inicialização. O endpoint do projeto não é um endpoint de uma conta do Azure OpenAI. Mantenha o arquivo fora do controle do código-fonte e não coloque credenciais no código do aplicativo.

Autenticar-se localmente

Os exemplos usam DefaultAzureCredential. Para o método de credenciais da CLI do Azure, faça login com uma conta que possa acessar o modelo do projeto:

az login

Referência: Entrar com a CLI do Azure.

O login no Kit de Ferramentas seleciona o projeto para as operações da extensão. O processo do agente local também precisa de uma credencial compatível. Para obter outras opções, consulte DefaultAzureCredential para Python ou cadeias de credenciais para .NET.

Executar o fluxo de trabalho hospedado localmente

Use a configuração de depuração gerada para iniciar o servidor HTTP e abrir o Inspetor do Agente. Abrir o Agent Inspector, por si só, não inicia o servidor.

Use esta solicitação de teste: Create a slogan for a new electric SUV that is affordable and fun to drive. O fluxo de trabalho retorna um slogan formatado depois que o redator, o revisor e o formatador concluírem.

Use esta solicitação de teste: The quick brown fox jumps over the lazy dog. o fluxo de trabalho executa sua cadeia de tradução e retorna uma resposta.

  1. Retorne ao workspace do projeto gerado.
  2. Defina um ponto de interrupção no código do fluxo de trabalho se desejar inspecionar a execução.
  3. Pressione F5. Se solicitado, selecione Debug Local Agent HTTP Server.
  4. Aguarde até que o servidor inicie e Agent Inspector abra.
  5. Envie a solicitação de teste para sua amostra.
  6. Inspecione a resposta e repita com outra solicitação. Se você definir um ponto de interrupção, inspecione os valores e continue a execução.

Depois que o exemplo funcionar, modifique o fluxo de trabalho e repita o teste local. Se você adicionar ferramentas, envie uma solicitação que exija um resultado de ferramenta real e inspecione a chamada. Uma resposta gerada apenas pelo modelo ou uma resposta simulada não comprova que a ferramenta real funciona.

A captura de tela mostra um agente local com ferramentas habilitadas, não nenhuma das duas amostras de fluxo de trabalho. O Agent Inspector exibe sua resposta e as chamadas de ferramenta com um gráfico em cascata de latência e uma linha do tempo da execução. Os detalhes de inspeção disponíveis dependem do agente em execução e de sua instrumentação.

Captura de tela do Agent Inspector conectado ao localhost na porta 8088 com o protocolo Responses, chamadas de ferramenta, um gráfico em cascata de latência e uma linha do tempo da execução.

Se você usar GitHub Copilot, poderá executar /validate-microsoft-foundry-hosted-agent em Copilot Chat para examinar o projeto em relação às práticas recomendadas do Foundry. Este comando chat abre um relatório; não é um comando de terminal ou um substituto para executar o fluxo de trabalho.

As tarefas geradas usam a porta 8088 para o servidor do agente. A depuração do Python também usa a porta 5679. Se a inicialização relatar um conflito de porta, interrompa o processo conflitante que você possui ou ajuste a configuração de tarefa gerada de forma consistente.

Executar sem o depurador

Para ser executado manualmente, abra um terminal no diretório de origem do exemplo com suas dependências, valores de ambiente e Azure credencial disponível.

python main.py

Referência: ponto de entrada do fluxo de trabalho Python.

Defina o endereço HTTP para o servidor local e execute-o:

$env:ASPNETCORE_URLS = "http://localhost:8088"
dotnet run

Referência: URLs do servidor do ASP.NET Core e dotnet run.

Em seguida , execute o Foundry Toolkit: Abra o Inspetor do Agente na Paleta de Comandos e conecte-se ao servidor local na porta 8088. Executar um exemplo com python ou dotnet run iniciar um processo local, não um contêiner.

Visualizar a execução do fluxo de trabalho do agente hospedado

Use o Agent Inspector para inspecionar os eventos, as respostas e as chamadas de ferramentas que seu agente em execução emite. Quando o runtime emite eventos de fluxo de trabalho, use a visualização do fluxo de trabalho para inspecionar a sequência de etapas.

Os detalhes disponíveis dependem da instrumentação da amostra. Siga as instruções de configuração de telemetria do exemplo para requisitos específicos do runtime.

Essas etapas usam o protocolo Respostas. Outros exemplos exigem clientes compatíveis com seu protocolo: a visualização HTTP Invocations não é um cliente WebSocket, e os exemplos de atividade em Python usam o Microsoft 365 Agents Playground. Siga as instruções de teste local do exemplo selecionado. Alterar um nome de protocolo na configuração não adiciona esse protocolo ao servidor. Consulte Escolher um protocolo de agente hospedado.

Implantar o agente hospedado

Depois que o fluxo de trabalho local se comportar conforme o esperado, implante-o no workspace do projeto. Python e C# compartilham o procedimento de implantação. Comece com o modo de pacote Código e Remoto para fazer upload do código-fonte e deixar o Foundry restaurar as dependências.

Preparar a configuração de implantação

Revise e salve o serviço de agente hospedado em azure.yaml. Preserve a configuração de protocolo do exemplo e declare a implantação do modelo e outras configurações de runtime necessárias lá.

A implantação resolve os valores de ambiente declarados a partir do .env do diretório de origem ou do ambiente do processo. Ele não encaminha todas as entradas locais .env . A plataforma fornece valores reservados de tempo de execução, como FOUNDRY_PROJECT_ENDPOINT; não os redeclare como configurações de implantação. Consulte variáveis de ambiente injetadas pela plataforma.

Examine as regras de ignorar do diretório de origem antes do empacotamento. Mantenha .envcredenciais, ambientes virtuais e caches fora do pacote. Para implantação por ZIP, um .agentignore na raiz da origem substitui as regras em .gitignore e .dockerignore; portanto, mantenha as exclusões necessárias se você adicionar esse arquivo.

Importante

Não confirme nem empacote segredos. O login local não transfere as permissões do usuário para o agente implantado. Configure o acesso para a identidade de execução do agente e as conexões compatíveis. Consulte as permissões do agente hospedado.

Implantar código-fonte usando o modo de pacote remoto

Use a raiz do espaço de trabalho gerada para que o kit de ferramentas possa ler a configuração do serviço e localizar o diretório de origem.

  1. Interrompa a sessão de depuração local.

  2. Selecione Ferramentas do Desenvolvedor>Compilar>Implantar no Microsoft Foundry. Você também pode executar o Foundry Toolkit: Implantar o Agente Hospedado na Paleta de Comandos.

    Captura de tela de Implantar no Microsoft Foundry em Build na seção Ferramentas de Desenvolvedor do Foundry Toolkit.

  3. Se Configuração do Projeto do Foundry aparecer, selecione a assinatura e o projeto e, em seguida, selecione Avançar. Caso contrário, confirme se o projeto padrão é o destino pretendido.

  4. No básico, selecione Código como Método de Implantação e Remoto como Modo de Pacote.

  5. Selecione Novo agente e insira o Nome do Agente Hospedado. Para atualizar um agente implantado, selecione o agente existente e escolha esse agente.

    Captura de tela do Basics com implantação de código, modo de pacote remoto e novo agente selecionado, com o nome do agente oculto.

  6. Selecione Próximo.

  7. Em Revisão + Implantação, verifique Idioma, Versão do Runtime, Ponto de Entrada e CPU e Memória no exemplo. Confirme se o diretório de origem corresponde ao caminho do project serviço.

    A captura de tela a seguir mostra um exemplo com Python 3.14 e seu ponto de entrada oculto, não as configurações para esses exemplos de fluxo de trabalho. Para Python, use Python 3.13 com python3 main.py. Para C#, use .NET 10 e o ponto de entrada detectado para o projeto gerado.

    Captura de tela de Revisão + Implantação mostrando Python 3.14 como exemplo, um ponto de entrada oculto, CPU e memória e controles de implantação.

  8. Selecione Implantar. Siga o progresso nas notificações e na saída.

  9. Continue a testar o fluxo de trabalho implantado.

Adapte o ambiente de execução à configuração de exemplo e ao seu ambiente local. Não aceite uma runtime diferente apenas porque é a opção padrão do assistente.

O Kit de Ferramentas salva as opções de implantação quando você envia o formulário. Essas configurações locais não provam que a implantação na nuvem foi bem-sucedida. Atualizar um agente existente cria uma nova versão em vez de alterar uma versão anterior em vigor.

Escolher outro modo de pacote ZIP

O Kit de Ferramentas oferece estas opções de empacotamento de código-fonte:

Modo de pacote O que acontece O que preparar
Remoto A origem dos pacotes do Kit de Ferramentas. O Foundry restaura as dependências do Python ou o projeto .NET durante o provisionamento. Origem, declarações de dependência e um ponto de entrada compatível.
Agrupado O Toolkit prepara o código-fonte e executa o Comando de Empacotamento localmente antes de criar o ZIP. A Foundry executa o pacote preparado. Dependências compatíveis do Linux e as ferramentas locais exigidas pelo comando. O comando Python padrão instala dependências compatíveis em packages/; o comando .NET cria a saída de compilação publicada.

Os runtimes zip selecionáveis são Python 3.13, Python 3.14 e .NET 10. Associe o runtime ao seu código e às suas dependências. Para layouts, limites e requisitos de serviço, consulte Implantar a partir do código-fonte. Para a política de suporte ao tempo de execução, consulte Tempos de execução de agente hospedado com suporte.

Implantar uma imagem de contêiner

Escolha Contêiner no Básico quando precisar de uma imagem de runtime personalizada ou já tiver uma imagem compatível.

Opção do Registro Comportamento do kit de ferramentas
ACR padrão Cria ou reutiliza um registro para o projeto selecionado e, em seguida, cria e envia a imagem por meio do Registro de Contêiner do Azure (ACR).
ACR personalizado Usa um registro existente selecionado e, em seguida, cria e envia a imagem por push por meio do ACR.
Imagem personalizada do ACR Usa uma referência de imagem do ACR pré-criada sem compilar nem fazer push do código-fonte.

Quanto às opções de build, examine o Dockerfile e o contexto de build antes de fazer a implantação. Se você gerar um Dockerfile no assistente, examine o arquivo e selecione Continuar e implantar. Essas opções usam builds remotos do ACR, não builds locais do Docker.

As opções de registro personalizado usam um registro da assinatura selecionada. O caminho de build do registro personalizado requer acesso à rede pública; o caminho da imagem predefinida tem requisitos de rede privada separados. Escolher uma imagem não configura a conectividade de rede.

Examine os requisitos de contêiner e as diretrizes de rede privada antes de usar um registro personalizado. Essas implantações visam o Serviço de Agente do Foundry, não o caminho de agente hospedado do Aplicativos de Contêiner do Azure, já descontinuado. Para migrar um agente antigo, siga as instruções em Migrar da versão prévia do agente hospedado.

Testar o fluxo de trabalho implantado

Uma solicitação de criação bem-sucedida não prova que o runtime está pronto ou que seu modelo e ferramentas são acessíveis. Teste a versão exata implantada.

  1. Em Meus recursos>>, selecione o nome do agente.
  2. Selecione a versão numerada que você acabou de implantar.
  3. Em Detalhes, aguarde até que o status da implantação indique que o agente está em execução. Se falhar, inspecione a saída da implantação antes de tentar novamente.
  4. Abra o Playground e envie a mesma solicitação que você testou localmente.
  5. Examine a resposta. Se você adicionou ferramentas, envie uma solicitação que exija essas ferramentas e inspecione as chamadas.

As execuções locais e de nuvem usam credenciais diferentes, ambientes de dependência e caminhos de rede. Uma resposta local bem-sucedida não garante uma resposta remota bem-sucedida.

Inspecionar e atualizar o agente implantado

Use o playground remoto para testar e inspecionar o agente implantado. Ao contrário do teste local com o Agent Inspector, as requisições neste playground são feitas no agente hospedado no Foundry.

  1. No Foundry Toolkit, selecione Ferramentas do Desenvolvedor>>.

    Captura de tela do Hosted Agent Playground em Build na seção Ferramentas de Desenvolvedor do Foundry Toolkit.

  2. Na lista suspensa Agente hospedado, selecione o agente implantado e a versão para inspecionar. Abra o Playground para enviar uma solicitação e exibir os detalhes da resposta e da sessão.

    A captura de tela a seguir mostra uma resposta ilustrativa de um agente implantado, não a saída esperada de nenhum dos dois exemplos de fluxo de trabalho. Identificadores de agente e sessão estão ocultos.

    Captura de tela do playground do hosted-agent remoto com uma resposta, detalhes da sessão e abas de inspeção, com identificadores do agente e da sessão ocultos.

Use esses controles para inspecionar e atualizar o agente. As abas disponíveis dependem de seu protocolo e dos serviços conectados.

Tarefa Ação
Examinar detalhes da implantação Abra Detalhes para ver o status, a configuração e o endpoint que pode ser copiado.
Testar uma versão Selecione uma versão numerada para requisições do Playground. Automático segue a seleção de versão do endpoint de serviço, que não é necessariamente a versão mais recente. O seletor não altera o roteamento para outros clientes.
Revisar logs de tempo de execução Abra sessões, selecione uma sessão e exiba seus logs. Os logs de runtime exigem uma sessão; a saída do build é separada. Parar um fluxo de log ou cancelar uma solicitação não interrompe o agente hospedado.
Recuperar código implantado Use Baixar ativo de código para uma implantação por ZIP. Uma implantação de imagem expõe a referência da imagem em vez de um projeto-fonte para download.
Comportamento de atualização Edite e teste o código local e repita o procedimento de implantação com o agente existente para criar uma nova versão.

Use Traces e Evaluation, quando disponíveis, para investigação e medição da qualidade além de uma única resposta bem-sucedida. Siga os pré-requisitos para rastreamento do agente hospedado e avaliação do agente hospedado.

A implantação fornece um endpoint ao agente para uso programático. Uma etapa de publicação separada não é necessária para acesso à API. A publicação no Teams ou Microsoft 365 é uma tarefa separada. Consulte o endpoint atual do agente e o modelo de publicação.

Troubleshooting

Use o erro relatado e a configuração de exemplo para identificar a etapa com falha.

Sintoma Ação
A inicialização local falha porque um pacote está ausente. Confirme o interpretador ou o SDK selecionado e instale as dependências do diretório de origem do exemplo.
O ponto de extremidade ou modelo do projeto não pode ser encontrado. Confira o FOUNDRY_PROJECT_ENDPOINT e o AZURE_AI_MODEL_DEPLOYMENT_NAME. Não substitua um endpoint de conta nem o nome do catálogo de modelos.
Falha na autenticação ou autorização. Verifique a credencial local e o acesso ao projeto. Revise as permissões do agente hospedado para os requisitos de implantação e identidade de tempo de execução.
O Agent Inspector não consegue se conectar. Confirme se o servidor foi iniciado e a porta 8088 está disponível. Abrir o Inspetor sozinho não inicia o servidor.
Uma implantação falhou. Examine o erro de implantação e a saída do build. Para o código, verifique o runtime, o ponto de entrada, o modo de pacote e ignore as regras. Para um contêiner, verifique as permissões de imagem e registro.
A resposta local funciona, mas a versão implantada falha. Compare o ambiente implantado e as permissões de identidade com a configuração local. Reteste a versão exata implementada.

Limpar os recursos

Interrompa a sessão de depuração local quando terminar. Se você não precisar mais do agente de teste implantado, siga Gerenciar agentes hospedados para removê-lo.

Excluir o agente remove suas versões e encerra as sessões ativas. Ele não remove todos os recursos de Azure associados.

Exclua apenas os recursos de nuvem criados para este exercício que nenhum outro aplicativo usa. Não exclua um projeto de Foundry compartilhado, uma implantação de modelo ou um registro de contêiner.

Conteúdo relacionado

Use estes guias para estender seu fluxo de trabalho:

  • Last updated on