Criar fluxos de trabalho de agentes alojados na extensão Microsoft Foundry Toolkit for Visual Studio Code

• Python 3.13 ou superior.

• .NET 10 SDK ou posterior.

1. Crie um ambiente virtual.

    python -m venv .venv
   

2. Ativa 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á ao diretório do seu projeto e execute este comando para obter os pacotes NuGet necessários:

   dotnet restore
   

O projeto de workflow de exemplo cria um ficheiro .env com as variáveis de ambiente necessárias. Crie ou atualize o ficheiro .env com as suas credenciais 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>

Autentique o seu agente alojado

O exemplo de agente hospedado autentica-se usando DefaultAzureCredential. Configure o seu ambiente de desenvolvimento para fornecer credenciais através de uma das fontes suportadas, por exemplo:

• CLI do Azure (az login)
• Início de sessão de conta no Visual Studio Code
• Início de sessão no Visual Studio
• Variáveis de ambiente para um principal 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 a amostra.

Podes executar o agente Hosted em modo interativo ou contentor.

Coloca o teu agente alojado no Agent Inspector

Prima F5 para iniciar o servidor HTTP local com a depuração ativada. O Foundry Toolkit Agent Inspector abre para testes interativos, e pode definir pontos de interrupção no seu código.

Para executar o servidor sem depuração:

python main.py

O agente ouve em http://localhost:8088/. Envie 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 workflow de exemplo cria um ficheiro .env com as variáveis de ambiente necessárias. Crie ou atualize o ficheiro .env com as suas credenciais Foundry:

1. Configura as variáveis do teu ambiente com base no teu sistema operativo:

   • 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"
   

Autentique o seu agente alojado

O exemplo de agente hospedado autentica-se usando DefaultAzureCredential. Configure o seu ambiente de desenvolvimento para fornecer credenciais através de uma das fontes suportadas, por exemplo:

• CLI do Azure (az login)
• Início de sessão de conta no Visual Studio Code
• Início de sessão no Visual Studio
• Variáveis de ambiente para um principal 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 a amostra.

Podes executar o agente Hosted em modo interativo ou contentor.

Execute o seu agente alojado em modo interativo

Execute o agente Alojado diretamente para desenvolvimento e teste:

dotnet restore
dotnet build
dotnet run

Execute o seu agente hospedado em modo contentor

Para executar o agente em modo contentor:

1. Abra a Paleta de Comandos Visual Studio Code e execute o comando Foundry Toolkit: Open Container Agent Playground Locally.
2. Utilize o seguinte comando para inicializar o agente alojado contentorizado.

   dotnet restore
   dotnet build
   dotnet run
   

3. Envie um pedido ao agente através da interface do playground. Por exemplo, introduza um prompt como: "Crie um slogan para um novo SUV elétrico que seja acessível e divertido de conduzir."
4. Veja a resposta do agente na interface do playground.

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

A extensão Microsoft Foundry Toolkit for Visual Studio Code fornece um gráfico de execução em tempo real que mostra como os agentes do seu fluxo de trabalho interagem e colaboram. Ative a observabilidade no seu projeto para usar esta visualização.

Adicione a seguinte referência ao seu ficheiro 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 o seu programa para incluir o seguinte excerto 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();

Monitorize e visualize o fluxo de trabalho do seu agente hospedado

Para monitorizar e visualizar a execução do seu fluxo de trabalho de agente alojado em tempo real:

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

2. Executa este comando: >Foundry Toolkit: Open Visualizer for Hosted Agents.

Abre-se um novo separador em VS Code para mostrar o gráfico de execução. A visualização atualiza-se automaticamente à medida que o seu fluxo de trabalho avança, para mostrar o fluxo entre os agentes e as suas interações.

Conflitos portuários

Para conflitos de porta, podes alterar a porta de visualização definindo-a nas definições da extensão Microsoft Foundry Toolkit para o Visual Studio Code. Para isso, siga estes passos:

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

Alterar porta no código

Para quaisquer conflitos de porta, altere a porta de visualização definindo a FOUNDRY_OTLP_PORT variável de ambiente. Atualize o endpoint OTLP no seu programa em conformidade.

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

  $env:FOUNDRY_OTLP_PORT="4318"

No seu programa, atualize o endpoint OTLP para usar o novo número de porta:

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

1. Abra a Paleta de Comandos e selecione Foundry Toolkit: Deploy Hosted Agent. Será aberta uma visualização web de implantação.
2. Para "Método de Implementação", selecione Código ou Contentor.
3. Ao implementar com "Code", em "Package Mode", selecione Remoto ou Local.
4. Se implementar com "Contentor", selecione uma das seguintes opções: Default ACR, Custom ACR ou Customer ACR Image.
5. O "Nome do Agente" deve ser preenchido automaticamente.
6. Selecione o botão "Próximo".
7. Esta página "Rever e Implementar" deverá ser totalmente preenchida automaticamente.
8. Selecione o botão "Implementar".
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 Implementação", selecione Código ou Contentor.
3. Ao implementar com "Code", em "Package Mode", selecione Remoto ou Local.
4. Se implementar com "Contentor", selecione uma das seguintes opções: Default ACR, Custom ACR ou Customer ACR Image.
5. O "Nome do Agente" deve ser preenchido automaticamente.
6. Selecione o botão "Próximo".
7. Esta página "Rever e Implementar" deverá ser totalmente preenchida automaticamente.
8. Selecione o botão "Implementar".