Criar fluxos de trabalho do agente hospedado na extensão Microsoft Foundry Toolkit for Visual Studio Code

• Python 3,13 ou superior.

• .NET 10 SDK ou posterior.

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 os pacotes necessários:

   pip install -r requirements.txt
   

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

   dotnet restore
   

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:

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

AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-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)
• 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

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}'

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:

   • Windows (PowerShell)
   • Windows (prompt de comando)
   • macOS/Linux (Bash)

   $env:FOUNDRY_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)
• 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.

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

Para executar o agente no modo de contêiner:

1. Abra a paleta de comandos Visual Studio Code e execute o comando Foundry Toolkit: 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 Microsoft 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: >Foundry Toolkit: 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

Em caso de conflitos de porta, você pode alterar a porta da visualização definindo-a nas configurações da extensão Microsoft Foundry Toolkit for Visual Studio Code. 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";

1. Abra a Paleta de Comandos e selecione Foundry Toolkit: Implantar Agente Hospedado. Um WebView de implantação será aberto.
2. Para "Método de Implantação", selecione Código ou Contêiner.
3. Se estiver implantando com "Code", para "Modo de Pacote", selecione Remoto ou Local.
4. Se estiver implantando com "Contêiner", selecione ACR Padrão, ACR Personalizado ou Imagem do ACR do Cliente.
5. O "Nome do Agente" deve ser preenchido automaticamente.
6. Selecione o botão "Avançar".
7. Esta página "Revisar e Implantar" deve ser totalmente preenchida automaticamente.
8. Selecione o botão "Implantar".
9. Abra a paleta de comandos Visual Studio Code e execute o comando Foundry Toolkit: Deploy Hosted Agent.

1. Abra a paleta de comandos Visual Studio Code e execute o comando Foundry Toolkit: Deploy Hosted Agent.
2. Para "Método de Implantação", selecione Código ou Contêiner.
3. Se estiver implantando com "Code", para "Modo de Pacote", selecione Remoto ou Local.
4. Se estiver implantando com "Contêiner", selecione ACR Padrão, ACR Personalizado ou Imagem do ACR do Cliente.
5. O "Nome do Agente" deve ser preenchido automaticamente.
6. Selecione o botão "Avançar".
7. Esta página "Revisar e Implantar" deve ser totalmente preenchida automaticamente.
8. Selecione o botão "Implantar".