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

Use o Microsoft Foundry Toolkit para Visual Studio Code para criar um fluxo de trabalho baseado em código a partir de um exemplo do Microsoft Agent Framework. Executa-o localmente com o Agent Inspector e depois implementa o código-fonte no Foundry Agent Service como agente hospedado. Mantém o código e as suas dependências. A Foundry gere a infraestrutura de alojamento e a escalabilidade.

Fluxos de trabalho alojados coordenam agentes no código. Diferem do serviço declarativo de fluxo de trabalho da Foundry, que está a ser retirado. Para outras rotas de criação, veja Criar um agente.

Pré-requisitos

  • Instale o Microsoft Foundry Toolkit para Visual Studio Code.

  • Selecione um projeto Foundry com um modelo implementado. Use uma região de agente hospedado suportada.

  • Permissão para usar o modelo e implementar agentes alojados. Para a implantação de código-fonte, a função Gestor de Projetos do Foundry, ao nível do projeto, inclui permissões para operações de agente e atribuição de funções. Ver permissões do agente alojado.

    Importante

    As funções RBAC do Foundry foram recentemente renomeadas. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Poderá ainda ver os nomes anteriores em alguns locais enquanto esta alteração de nome está a ser implementada. Os IDs das funções e as permissões principais não são alterados por esta mudança de nome.

  • CLI do Azure para os passos de autenticação local neste artigo.

  • Para a implementação de contentores, o registo e o acesso à imagem são necessários para a configuração do Azure Container Registry. Estes requisitos de registo não se aplicam a uma implementação de código-fonte.

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

A principal via de implementação usa Code com o modo de pacote Remote e não requer uma compilação local em Docker. A execução local continua a enviar pedidos ao modelo para o Foundry e pode originar custos. Revise os limites de serviço e a disponibilidade e as notas de lançamento do Toolkit para as funcionalidades que utiliza.

Criar um fluxo de trabalho de agente alojado

Escolha um exemplo de Agent Framework que utilize o protocolo Responses. Não precisas de criar um agente de prompts separado primeiro. Para comparar amostras, Agent Builder e programação assistida pelo Copilot, consulte Escolher uma rota de criação.

Utilize Multi-Agent Workflow (Agent Framework), que encadeia um redator, um revisor e um formatador. A resposta final vem do formatador. Revise o exemplo de fluxo de trabalho em Python para a implementação completa e as suas orientações para o modelo.

Use o Translation Workflow, que encadeia três agentes de tradução: inglês para francês, francês para espanhol e espanhol para inglês. Revise o exemplo do fluxo de trabalho em C# para a implementação completa.

  1. Na vista Foundry Toolkit, selecione Ferramentas de Programador>Compilar>Criar Agente.

  2. Em Codificar um agente a partir de exemplos, selecione Explorar todos os exemplos.

  3. No Create Hosted Agent from Sample, filtre pela sua Linguagem, Framework = Agent Framework eRespostas do Tipo = de Protocolo. Pesquise por workflow.

    A captura de ecrã seguinte mostra a galeria com o Agente Hospedado Básico selecionado como exemplo. Para este guia, selecione o exemplo de fluxo de trabalho para a sua língua.

    Captura de ecrã da galeria de exemplos do agente hospedado com o Agente Básico selecionado, exemplos de workflow e filtros de linguagem, framework e protocolo.

  4. Seleciona o exemplo de fluxo de trabalho para a tua língua.

  5. Selecione Avançar.

  6. Em Create, selecione a Pasta do espaço de trabalho. Se a pasta já tiver ficheiros, introduza um Nome de Pasta para uma nova pasta filha.

  7. Se aparecer Configuração do Ambiente, selecione Configurar com a Microsoft Foundry e depois selecione a sua subscrição e projeto. Quando um projeto padrão já está selecionado, o formulário usa esse projeto.

  8. Selecione uma Implementação de Modelo compatível existente.

    A captura de ecrã seguinte mostra exemplos de definições de projeto com caminhos locais ocultos. Utilize o seu próprio destino e a implementação do modelo exigida pelo seu exemplo.

    Captura de ecrã do separador Criar a mostrar a pasta do espaço de trabalho, o nome da pasta, a implantação do modelo e os controlos de criação, com os caminhos locais ocultos.

  9. Revise o destino e depois selecione Criar.

  10. Abra o projeto gerado no Visual Studio Code e leia o respetivo README.md.

Os mosaicos Agent Framework, Copilot SDK e LangGraph na página Create Agent abrem o separador Create com o modelo inicial hello-world selecionado. Use Navegar por todas as amostras para escolher um fluxo de trabalho em vez de um desses iniciais. Também pode abrir a galeria em Meus Recursos>Agentes>Hospedados>Adicionar Agente Hospedado.

Os nomes e conteúdos dos exemplos podem mudar com o catálogo. Algumas versões designam estes exemplos como Fluxos de Trabalho. Use o link do GitHub do exemplo para confirmar que selecionou o fluxo de trabalho pretendido.

Por agora, o Skip gera o código sem completar a configuração do modelo. Se escolheres, configura os valores necessários do projeto e do modelo antes de executar a amostra. Implementar e usar um novo modelo, quando disponível, aprovisiona a implementação de um modelo, não o agente alojado. A criação dos ficheiros locais do projeto não instala o agente.

Configurar o projeto local

Mantém a pasta que contém azure.yaml aberta como raiz do espaço de trabalho. Verifique o caminho do project serviço de agente hospedado nesse ficheiro para encontrar o seu diretório de origem.

Artifact Purpose
azure.yaml Declara o serviço do agente hospedado, diretório de origem, tempo de execução, protocolos e definições de implementação.
main.py ou Program.cs no diretório de origem Implementa o fluxo de trabalho e inicia o seu servidor de Respostas.
requirements.txt ou o ficheiro .csproj Define as dependências para a linguagem selecionada.
.env no diretório de origem Contém os valores locais do projeto e do modelo. O Toolkit cria-o a partir .env.example do momento em que a amostra fornece esse ficheiro.
.vscode/launch.json e .vscode/tasks.json Configura o servidor local, o anexo do depurador e o Agent Inspector.

Os esquemas de exemplo podem mudar. Utilize os elementos gerados README.md e azure.yaml em vez de assumir que o código e o ficheiro de ambiente estão na raiz da área de trabalho.

Instalar dependências

Use os ficheiros de dependências do exemplo gerado. Mantenha o interpretador ou SDK selecionado consistente com a sua configuração em tempo de execução.

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

  2. Abrir um terminal com esse ambiente ativo. Altera 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 de fluxos de trabalho em Python.

  1. Execute C#: Verifique os requisitos do espaço de trabalho a partir da paleta de comandos.

  2. Num terminal, muda para o diretório de origem que contém o .csproj ficheiro e restaura os seus pacotes:

    dotnet restore

    Referência: dotnet restore.

Para controlos e configuração do depurador, veja depuração em C# no Visual Studio Code.

Define o projeto e o modelo

Revise o .env ficheiro no diretório de origem. Se não existir, cria-a com os valores exigidos pela amostra.

Variable Value
FOUNDRY_PROJECT_ENDPOINT O seu endpoint do projeto, na forma https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
AZURE_AI_MODEL_DEPLOYMENT_NAME O nome da implementaçã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 conta OpenAI do Azure. Mantenha o ficheiro fora do controlo de versões e não coloque credenciais no código da sua aplicação.

Autenticar localmente

As amostras utilizam DefaultAzureCredential. Para o caminho das credenciais do CLI do Azure, inicie sessão com uma conta que possa aceder ao modelo do projeto:

az login

Referência: Iniciar sessão com CLI do Azure.

O login do toolkit seleciona o projeto para operações de extensão. O processo de agente local também exige uma credencial comprovada. Para outras opções, consulte DefaultAzureCredential para Python ou cadeias de credenciais para .NET.

Executa o teu fluxo de trabalho alojado localmente

Use a configuração de depuração gerada para iniciar o servidor HTTP e abrir o Agent Inspector. Abrir o Agent Inspector sozinho não inicia o servidor.

Use este pedido de teste: Create a slogan for a new electric SUV that is affordable and fun to drive. O fluxo de trabalho devolve um slogan formatado depois de o escritor, revisor e formatador terminarem.

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

  1. Voltar ao espaço de trabalho do projeto gerado.
  2. Defina um ponto de interrupção no código do fluxo de trabalho se quiser inspecionar a execução.
  3. Pressione F5. Se lhe for pedido, selecione Debug Local Agent HTTP Server.
  4. Espera que o servidor inicie e o Agent Inspector abra.
  5. Envie o pedido de teste para a sua amostra.
  6. Inspecione a resposta e repita com outra solicitação. Se definires um ponto de interrupção, inspeciona os valores e continua a execução.

Depois de a amostra funcionar, modifique o fluxo de trabalho e repita o teste local. Se adicionar ferramentas, envie uma solicitação que exija um resultado real da ferramenta e inspecione a chamada. Uma resposta apenas com modelo ou uma resposta simulada não prova que a ferramenta real funcione.

A captura de ecrã mostra um agente local ativado por ferramentas, não um exemplo de workflow. O Agent Inspector apresenta as suas respostas e chamadas de ferramenta com uma cascata de latência e uma linha temporal de execução. Os detalhes de inspeção disponíveis dependem do agente em funcionamento e da sua instrumentação.

Captura de ecrã do Agent Inspector ligado a localhost na porta 8088, com o protocolo Responses, invocações de ferramentas, um gráfico em cascata da latência e uma cronologia da execução.

Se usares o GitHub Copilot, podes correr /validate-microsoft-foundry-hosted-agent no Copilot Chat para rever o projeto de acordo com as melhores práticas da Foundry. Este comando Chat abre um relatório; não é um comando terminal nem substitui a execução do fluxo de trabalho.

As tarefas geradas usam a porta 8088 para o servidor agente. A depuração em Python também utiliza a porta 5679. Se, ao iniciar, for reportado um conflito de porta, pare o processo em conflito que lhe pertence ou ajuste de forma consistente a configuração da tarefa gerada.

Executar sem o depurador

Para executar manualmente, abra um terminal no diretório fonte do exemplo com as suas dependências, valores de ambiente e credenciais do Azure disponíveis.

python main.py

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

Defina o endereço HTTP do servidor local e depois execute-o:

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

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

Depois executa o Foundry Toolkit: Open Agent Inspector a partir da Paleta de Comandos e liga-te ao servidor local na porta 8088. Executar uma amostra com python ou dotnet run inicia um processo local, não um contentor.

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

Use o Agent Inspector para inspecionar os eventos, respostas e chamadas de ferramentas que o seu agente em execução emite. Quando o ambiente de execução emite eventos do fluxo de trabalho, utilize 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 de tempo de execução.

Estes passos utilizam o protocolo Respostas. Outros exemplos precisam de clientes que correspondam ao seu protocolo: a vista HTTP Invocations não é um cliente WebSocket, e exemplos de Python Activity usam o Microsoft 365 Agents Playground. Siga as instruções de teste local da amostra selecionada. Mudar o nome de um protocolo na configuração não adiciona esse protocolo ao teu servidor. Consulte Escolher um protocolo de agente hospedado.

Implementar o agente alojado

Depois de o fluxo de trabalho local se comportar como esperado, implemente-o a partir do espaço de trabalho do projeto. Python e C# partilham o procedimento de implementação. Comece com o modo de pacote Código e Remoto para carregar o código-fonte e permitir que o Foundry restaure as dependências.

Preparar a configuração de implantação

Revise e guarde o serviço de agente alojado em azure.yaml. Preservar a configuração do protocolo do exemplo e declarar a implementação do modelo e as outras definições de tempo de execução necessárias aí.

A implementação resolve valores declarados do ambiente a partir dos diretórios .env de origem ou do ambiente do processo. Não encaminha todas as entradas locais .env. A plataforma fornece valores de execução reservados como FOUNDRY_PROJECT_ENDPOINT; não os redeclare como definições de implantação. Ver variáveis de ambiente injetadas pela plataforma.

Revise as regras de ignorar do diretório de origem antes de empacotar. Mantenha .env, credenciais, ambientes virtuais e caches fora do pacote. Para a implementação por ZIP, um .agentignore source-root substitui as regras em .gitignore e .dockerignore, por isso, mantenha as exclusões necessárias caso adicione esse ficheiro.

Importante

Não comprometas nem embales segredos. O login local não transfere as permissões do seu utilizador para o agente implementado. Configure o acesso da identidade de execução do agente e das ligações suportadas. Consulte as permissões do agente alojado.

Deploy source com modo de pacote remoto

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

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

  2. Selecione Ferramentas> de DesenvolvimentoConstruir>Implementar para o Microsoft Foundry. Também pode executar o Foundry Toolkit: Deploy Hosted Agent a partir da Command Palette.

    Captura de ecrã de Deploy to Microsoft Foundry em Build na secção Ferramentas para Desenvolvedores do Foundry Toolkit.

  3. Se aparecer Foundry Project Setup, selecione a subscrição e o projeto e, em seguida, selecione Seguinte. Caso contrário, confirme que o projeto padrão é o destino pretendido.

  4. Em Básicos, selecione Código como Método de Implementação e Remoto como Modo Pacote.

  5. Selecione Novo Agente e introduza o Nome do Agente Alojado. Para atualizar um agente implementado, selecione Agente existente e escolha esse agente em vez disso.

    Captura de ecrã das definições básicas, com a implementação com código, o modo de pacote remoto e o novo agente selecionados, com o nome do agente oculto.

  6. Selecione Avançar.

  7. Em Revisão + Implementação, verifique Linguagem, Versão em Tempo de Execução, Ponto de Entrada, CPU e Memória com a amostra. Confirme se o diretório de origem corresponde ao caminho do project serviço.

    A captura de ecrã seguinte mostra um exemplo com Python 3.14 e o seu ponto de entrada oculto, não as definições para estes exemplos de workflow. Para Python, use Python 3.13 com python3 main.py. Para C#, usa .NET 10 e o ponto de entrada detetado para o teu projeto gerado.

    Captura de ecrã de Review + Deploy mostrando Python 3.14 como exemplo, um ponto de entrada oculto, CPU e memória, e controlos Deploy.

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

  9. Continue a testar o fluxo de trabalho implementado.

Ajusta o tempo de execução à configuração da amostra e ao ambiente local. Não aceite um ambiente de execução diferente apenas porque é a opção predefinida do assistente.

O Toolkit guarda as escolhas de implementação quando submete o formulário. Essas definições locais não provam que a implementação na cloud tenha sido bem-sucedida. Atualizar um agente existente cria uma nova versão em vez de alterar uma versão anterior.

Escolha outro modo de pacote ZIP

O Toolkit oferece estas opções de embalagem de código-fonte:

Modo de pacote O que acontece O que preparar
Controlo remoto O código-fonte dos pacotes do Toolkit. O Foundry restaura os requisitos do Python ou do projeto .NET durante o provisionamento. Fonte, declarações de dependência e um ponto de entrada compatível.
Agrupados O Toolkit prepara o código-fonte e executa o Package Command localmente antes de criar o ficheiro ZIP. O Foundry executa o pacote preparado. Dependências Linux compatíveis 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 publicação.

Os runtimes ZIP selecionáveis são Python 3.13, Python 3.14 e .NET 10. Ajusta o tempo de execução ao teu código e dependências. Para layouts, limites e requisitos de serviço, veja Deploy a partir do código-fonte. Para conhecer a política de suporte para o runtime, consulte Runtimes suportados dos agentes alojados.

Implantar uma imagem de contentor

Escolha Container no Basics quando precisar de uma imagem de runtime personalizada ou já tiver uma imagem compatível.

Escolha do registo Comportamento do kit de ferramentas
ACR predefinido Cria ou reutiliza um registo para o projeto selecionado, depois constrói e envia a imagem através do Azure Container Registry (ACR).
ACR personalizado Usa um registo existente que selecionas, depois constrói e envia a imagem através do ACR.
Imagem ACR personalizada Usa uma referência de imagem ACR pré-construída sem construir ou enviar o código-fonte.

Para as opções de compilação, reveja o Dockerfile e o contexto da compilação antes de implementar. Se gerares um Dockerfile no assistente, revê o ficheiro e seleciona Continuar e implementa. Estas opções usam compilações remotas ACR, não compilações locais Docker.

As opções de repositório personalizado utilizam um repositório na subscrição selecionada. A abordagem de compilação a partir de um registo personalizado requer acesso à rede pública; a abordagem de imagem pré-construída tem requisitos separados para a rede privada. Escolher uma imagem não configura a conectividade da rede.

Consulte os requisitos de contentores e as orientações para redes privadas antes de usar um registo personalizado. Estas implementações visam o Foundry Agent Service, e não o antigo caminho do Azure Container Apps hosted-agent. Para mover um agente mais antigo, siga Migrar a partir da pré-visualização do agente hospedado.

Teste o fluxo de trabalho implementado

Um pedido de criação bem-sucedido não prova que o runtime está pronto ou que o seu modelo e ferramentas são acessíveis. Teste a versão exata implementada em produção.

  1. Em Os Meus Recursos>Agentes>Agente Alojado, selecione o nome do agente.
  2. Seleciona a versão numerada que acabaste de implementar.
  3. No separador Detalhes, aguarde até que o estado da implementação indique que o agente está em execução. Se falhar, verifique o resultado da implementação antes de tentar novamente.
  4. Abre o Playground e envia o mesmo pedido que testaste localmente.
  5. Veja a resposta. Se adicionaste ferramentas, envia um pedido que precise dessas ferramentas e inspeciona as chamadas.

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

Inspecionar e atualizar o agente implementado

Utilize o ambiente de teste remoto para testar e inspecionar o seu agente implementado. Ao contrário dos testes locais com o Agent Inspector, as solicitações neste playground são executadas no agente alojado no Foundry.

  1. No Foundry Toolkit, selecione Ferramentas de Programador>Compilação>Ambiente de Testes do Agente Alojado.

    Captura de ecrã do Hosted Agent Playground na secção Build na secção Ferramentas para Desenvolvedores do Foundry Toolkit.

  2. Na lista pendente Agente alojado, selecione o agente implementado e a versão para inspecionar. Abra o Playground para enviar um pedido e ver a resposta e os detalhes da sessão.

    A captura de ecrã seguinte mostra a resposta ilustrativa de um agente implementado, não o resultado esperado de qualquer um dos exemplos de workflow. Os identificadores de agente e sessão estão ocultos.

    Captura de ecrã do playground remoto do agente hospedado com uma resposta, detalhes da sessão e separadores de inspeção, com os identificadores do agente e da sessão ocultos.

Utilize estes controlos para inspecionar e atualizar o agente. Os separadores disponíveis dependem do seu protocolo e dos serviços ligados.

Task Action
Rever os detalhes de implementação Abra Detalhes para o estado, a configuração e o endpoint que pode ser copiado.
Testar uma versão Selecione uma versão numerada para pedidos no playground. Automático segue a seleção da versão do endpoint de serviço, que não é necessariamente a versão mais recente. O seletor não altera o encaminhamento para outros clientes.
Ver registos de execução Abra as Sessões, selecione uma sessão e veja os seus registos. Os registos de execução exigem uma sessão; o resultado da compilação é separado. Parar um fluxo de registo ou cancelar um pedido não impede o agente alojado.
Recuperar código implementado Use o recurso do código de download para uma implementação ZIP. Uma implementação de imagem expõe a referência da imagem em vez de um projeto fonte descarregável.
Atualizar comportamento Edite e teste o código local, depois repita o procedimento de implementação com o agente existente para criar uma nova versão.

Use Traces and Evaluation, quando disponível, para investigação e medição de qualidade para além de uma resposta bem-sucedida. Siga os pré-requisitos para rastreio de agentes hospedados e avaliação de agentes hospedados.

A implementação fornece ao agente um endpoint para utilização programática. Não é necessário um passo de publicação separado para o acesso à API. Publicar no Teams ou no Microsoft 365 é uma tarefa separada. Veja o endpoint atual do agente e o modelo de publicação.

Troubleshooting

Utilize o erro reportado e a configuração da amostra para identificar o passo falhado.

Symptom Action
A startup local falha porque falta um pacote. Confirme o interpretador ou SDK selecionado, depois instale as dependências a partir do diretório de origem do exemplo.
O endpoint ou modelo do projeto não pode ser encontrado. Verifique o FOUNDRY_PROJECT_ENDPOINT e o AZURE_AI_MODEL_DEPLOYMENT_NAME. Não substitua um endpoint de conta ou um nome de catálogo de modelos.
A autenticação ou autorização falha. Verifique a credencial local e o acesso ao projeto. Revise as permissões dos agentes hospedados para os requisitos de implementação e identidade em tempo de execução.
O Agente Inspetor não consegue ligar. Confirma que o servidor arrancou e que a porta 8088 está disponível. Abrir o Inspector sozinho não inicia o servidor.
Uma implementação falha. Revê o erro de implementação e o resultado da compilação. Para o código, verifica o runtime, o ponto de entrada, o modo de pacote e ignora as regras. Para um contentor, verifica as permissões de imagem e de registo.
A resposta local funciona, mas a versão implementada falha. Compare as permissões do ambiente e identidade implementadas com a configuração local. Testa novamente a versão exata implementada.

Limpeza de recursos

Pare a sessão local de depuração quando terminar. Se já não precisar do agente de teste implementado, siga Gerenciar agentes hospedados para o remover.

Eliminar o agente remove as suas versões e termina as sessões ativas. Não remove todos os recursos Azure associados.

Elimine apenas os recursos cloud criados para este exercício que nenhuma outra aplicação utiliza. Não apague um projeto partilhado do Foundry, a implementação de modelos ou o registo de contentores.

Conteúdo relacionado

Use estes guias para prolongar o seu fluxo de trabalho:

  • Last updated on