Criar fluxos de trabalho do agente hospedado no Visual Studio Code (versão prévia)

Crie, teste e implante fluxos de trabalho hosted Foundry Agent usando o Foundry Toolkit for Visual Studio Code. O kit de ferramentas suporta a criação de agentes a partir de modelos, o teste local e a depuração com o Inspetor do Agente para visualização e suporte ao rastreamento, e a implantação direta para o Serviço Foundry Agent no VS Code. Os fluxos de trabalho hospedados permitem que vários agentes colaborem em sequência, cada um com seu próprio modelo, ferramentas e instruções.

Antes de começar, crie um agente no Serviço do Foundry Agent usando a extensão. Em seguida, você pode adicionar fluxos de trabalho hospedados a esse agente.

Este artigo aborda a criação de um projeto de fluxo de trabalho, a execução dele localmente, a visualização da execução e a implantação no workspace do Foundry.

Pré-requisitos

  • Um projeto do Foundry com um modelo implantado ou um recurso Azure OpenAI.
  • O kit de ferramentas Foundry para Visual Studio Code instalado.
  • A identidade gerenciada do projeto com as funções atribuídas de Usuário de IA do Azure e AcrPull. Atribua também a acrPull função à identidade gerenciada do projeto Foundry em que você planeja implantar o agente hospedado.
  • Uma região com suporte para agentes hospedados.
  • Python 3,12 ou superior.

Criar um fluxo de trabalho do agente hospedado

Você pode usar o Foundry Toolkit para Visual Studio Code para criar fluxos de trabalho do agente hospedado. Um fluxo de trabalho do agente hospedado é uma sequência de agentes que trabalham juntos para realizar uma tarefa. Cada agente no fluxo de trabalho pode ter seu próprio modelo, ferramentas e instruções.

  1. Abra a paleta de comandos (Ctrl+Shift+P).

  2. Execute este comando: >Microsoft Foundry: Create a New Hosted Agent.

  3. Escolha uma estrutura, Microsoft Agent Framework ou LangGraph.

  4. Escolha um modelo, seja o Assistente de Hotel do Agente Único ou o fluxo de trabalho do Agente Escritor-Resenhista (vários agentes).

  5. Selecione uma linguagem de programação.

  6. Escolha um modelo, um que você já implantou em seu projeto ou navegue pelo catálogo de modelos.

  7. Selecione uma pasta na qual você deseja salvar seu novo fluxo de trabalho.

Os arquivos do projeto do agente hospedado são gerados na pasta selecionada com base na estrutura, no modelo e no idioma que você selecionou para começar. Você pode remover ou modificar esse código conforme necessário.

Instalar dependências

Instale as dependências necessárias para o seu projeto de agente hospedado. As dependências variam de acordo com a linguagem de programação selecionada quando você criou o projeto.

  1. Criar ambiente virtual.

     python -m venv .venv

  2. Ative o ambiente virtual.

    # PowerShell
./.venv/Scripts/Activate.ps1

# Windows cmd
.venv\Scripts\activate.bat

# Unix/MacOS
source .venv/bin/activate

  3. Instale o seguinte pacote:

    pip install azure-ai-agentserver-agentframework

  1. Vá para o diretório do projeto e execute este comando para obter os pacotes NuGet necessários:

    dotnet restore

Executar o fluxo de trabalho hospedado localmente

O projeto de fluxo de trabalho de exemplo cria um arquivo .env com as variáveis de ambiente necessárias. Crie ou atualize o arquivo .env com suas credenciais do Foundry:

PROJECT_ENDPOINT=https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>

MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

Importante

Nunca confirme o arquivo .env no controle de versão. Adicione-o ao arquivo .gitignore .

Autenticar seu agente hospedado

O exemplo de agente hospedado é autenticado usando DefaultAzureCredential. Configure seu ambiente de desenvolvimento para fornecer credenciais por meio de uma das fontes com suporte, por exemplo:

  • CLI do Azure (az login)
  • Visual Studio Code login da conta
  • Visual Studio login da conta
  • Variáveis de ambiente para um principal do serviço (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Confirme a autenticação localmente executando os comandos CLI do Azure az account show ou az account get-access-token antes de executar o exemplo.

Você pode executar o agente hospedado no modo interativo ou no modo de contêiner.

Execute o seu agente hospedado no Inspetor de Agente

Para executar o agente hospedado localmente no Visual Studio Code, selecione a chave F5. Isso abre o Inspetor do Agente e executa seu aplicativo.

Isso vai:

  1. Inicie o servidor do agente: A agentdev CLI encapsula seu agente como um servidor HTTP na porta 8087, com o debugpy anexado na porta 5679.
  2. Descobrir agentes: A interface do usuário busca agentes/fluxos de trabalho disponíveis de /agentdev/entities.
  3. Execução do fluxo: As entradas de chat vão para /v1/responses, que transmite eventos de volta por meio da SSE para visualização em tempo real.
  4. Habilitar a navegação de código: Clique duas vezes em nós de fluxo de trabalho para abrir o arquivo de origem correspondente no editor.
  5. Habilite o bate-papo com o agente local e visualize respostas, atingindo os pontos de interrupção para depuração e assim por diante.

O projeto de fluxo de trabalho de exemplo cria um arquivo .env com as variáveis de ambiente necessárias. Crie ou atualize o arquivo .env com suas credenciais do Foundry:

  1. Configure suas variáveis de ambiente com base em seu sistema operacional:

    $env:AZURE_AI_PROJECT_ENDPOINT="https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="your-deployment-name"

Autenticar seu agente hospedado

O exemplo de agente hospedado é autenticado usando DefaultAzureCredential. Configure seu ambiente de desenvolvimento para fornecer credenciais por meio de uma das fontes com suporte, por exemplo:

  • CLI do Azure (az login)
  • Visual Studio Code login da conta
  • Visual Studio login da conta
  • Variáveis de ambiente para um principal do serviço (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Confirme a autenticação localmente executando os comandos CLI do Azure az account show ou az account get-access-token antes de executar o exemplo.

Você pode executar o agente hospedado no modo interativo ou no modo de contêiner.

Executar seu agente hospedado no modo interativo

Execute o agente hospedado diretamente para desenvolvimento e teste:

dotnet restore
dotnet build
dotnet run

Executar seu agente hospedado no modo de contêiner

Dica

Abra o playground local antes de iniciar o agente de contêiner para garantir que as funcionalidades de visualização operem corretamente.

Para executar o agente no modo de contêiner:

  1. Abra a paleta de comandos Visual Studio Code e execute o comando Microsoft Foundry: Open Container Agent Playground Locally.
  2. Use o comando a seguir para inicializar o agente hospedado em contêineres. 
    dotnet restore
dotnet build
dotnet run
  3. Envie uma solicitação ao agente por meio da interface do playground. Por exemplo, insira um prompt como: "Crie um slogan para um novo SUV elétrico que seja acessível e divertido de dirigir".
  4. Examine a resposta do agente na interface do playground.

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

O Foundry Toolkit for Visual Studio Code fornece um grafo de execução em tempo real que mostra como os agentes em seu fluxo de trabalho interagem e colaboram. Habilite a observabilidade em seu projeto para usar essa visualização.

Adicione a seguinte referência ao arquivo csproj:

<ItemGroup>
    <PackageReference Include="OpenTelemetry" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
    <PackageReference Include="System.Diagnostics.DiagnosticSource" Version="9.0.10" />
</ItemGroup>

Atualize seu programa para incluir o seguinte snippet de código:

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4319";

var resourceBuilder = OpenTelemetry
    .Resources.ResourceBuilder.CreateDefault()
    .AddService("WorkflowSample");

var s_tracerProvider = OpenTelemetry
    .Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("Microsoft.Agents.AI.*") // All agent framework sources
    .SetSampler(new AlwaysOnSampler()) // Ensure all traces are sampled
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri(otlpEndpoint);
        options.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.Grpc;
    })
    .Build();

Monitorar e visualizar o fluxo de trabalho do agente hospedado

Para monitorar e visualizar a execução do fluxo de trabalho do agente hospedado em tempo real:

  1. Abra a paleta de comandos (Ctrl+Shift+P).

  2. Execute este comando: >Microsoft Foundry: Open Visualizer for Hosted Agents.

Uma nova aba é aberta no VS Code para exibir o grafo de execução. A visualização é atualizada automaticamente à medida que o fluxo de trabalho progride, para mostrar o fluxo entre os agentes e suas interações.

Conflitos de porta

Para conflitos de porta, você pode alterar a porta de visualização definindo-a nas configurações de extensão do Foundry. Para fazer isso, siga estas etapas:

  1. Na barra lateral esquerda do VS Code, selecione o ícone de engrenagem para abrir o menu de configurações.
  2. Selecione Extensions>Microsoft Foundry Configuration.
  3. Localize a Hosted Agent Visualization Port configuração e altere-a para um número de porta disponível.
  4. Reinicie o VS Code para aplicar as alterações.

Alterar a porta no código

Para qualquer conflito de portas, altere a porta de visualização definindo a variável de FOUNDRY_OTLP_PORT ambiente. Atualize o endpoint OTLP em seu programa conforme necessário.

Por exemplo, para alterar a porta para 4318, use este comando:

  $env:FOUNDRY_OTLP_PORT="4318"

Em seu programa, atualize o ponto de extremidade OTLP para usar o novo número de porta:

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4318";

Implantar o agente hospedado

Depois de testar o agente hospedado localmente, implante-o no workspace do Foundry para que outros membros da equipe e aplicativos possam usá-lo.

Importante

Certifique-se de conceder as permissões necessárias para implantar agentes hospedados em seu workspace do Foundry, conforme indicado nos pré-requisitos. Talvez seja necessário trabalhar com o administrador do Azure para obter as atribuições de função necessárias.

  1. Abra a paleta de comandos Visual Studio Code e execute o comando Microsoft Foundry: Deploy Hosted Agent.
  2. Defina as configurações de implantação selecionando seu workspace de destino, especificando o arquivo do agente de contêiner (container.py) e definindo quaisquer outros parâmetros de implantação, conforme necessário.
  3. Após a implantação bem-sucedida, o agente hospedado aparece na seção Hosted Agents (Preview) da exibição da árvore de extensão Microsoft Foundry.
  4. Selecione o agente implantado para acessar informações detalhadas e a funcionalidade de teste usando a interface de playground integrada.
  1. Abra a paleta de comandos Visual Studio Code e execute o comando Microsoft Foundry: Deploy Hosted Agent.
  2. Defina as configurações de implantação selecionando seu workspace de destino, especificando o arquivo do agente de contêiner (<your-project-name>.csproj) e definindo quaisquer outros parâmetros de implantação, conforme necessário.
  3. Após a implantação bem-sucedida, o agente hospedado aparece na seção Hosted Agents (Preview) da exibição da árvore de extensão Microsoft Foundry.
  4. Selecione o agente implantado para acessar informações detalhadas e a funcionalidade de teste usando a interface de playground integrada.

Conteúdo relacionado

  • Last updated on