Compartilhar via

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

Crie, teste e implante fluxos de trabalho do hosted Foundry Agent usando a Microsoft Foundry for Visual Studio Code extension. 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, construa um agente no Serviço de Agente do Foundry 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, executá-lo localmente, visualizar a execução e implantá-lo em seu espaço de trabalho do Foundry.

Pré-requisitos

  • Um projeto do Foundry com um modelo implantado ou um recurso Azure OpenAI.
  • A extensão Microsoft Foundry for Visual Studio Code instalada.
  • A identidade gerenciada do projeto com as funções Azure AI User e AcrPull atribuídas. Atribua também a função acrPull à 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 a extensão Foundry for 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, o Assistente de Hotel do Agente Único ou o fluxo de trabalho do agente de Writer-Reviewer (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 projeto de agente hospedado. As dependências variam de acordo com a linguagem de programação selecionada quando você criou o project.

  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 project 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 submeta o arquivo .env ao 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)
  • Login de conta do Visual Studio Code
  • Visual Studio login da conta
  • Variáveis de ambiente para uma entidade de 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 seu agente hospedado no Inspetor do 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 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 visualização de respostas, atingindo pontos de interrupção para depuração, entre outras ações.

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 uma entidade de 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 a visualização funcione 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. Revise a resposta do agente na interface do playground.

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

A extensão Foundry 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. To do 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 quaisquer conflitos de porta, altere a porta de visualização definindo a variável de ambiente FOUNDRY_OTLP_PORT. Atualize o ponto de extremidade OTLP em seu programa conforme necessário.

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

  $env:FOUNDRY_OTLP_PORT="4318"

No seu programa, atualize o ponto de extremidade OTLP para usar o novo número da 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 testar funcionalidades usando a interface integrada de sandbox.
  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 testar funcionalidades usando a interface integrada de sandbox.

Conteúdo relacionado

  • Last updated on