Criar fluxos de trabalho de agentes alojados no Visual Studio Code (pré-visualização)

• Python 3.12 ou superior.

• .NET 9 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 o seguinte pacote:

   pip install azure-ai-agentserver-agentframework
   

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:

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

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.

Pode executar o agente hospedado em modo interativo ou contentor.

Coloca o teu agente alojado no Agent Inspector

Para executar o seu agente hospedado localmente em Visual Studio Code, selecione a tecla F5. Isto abre o Inspetor de Agentes e executa a sua aplicação.

Isto irá:

1. Inicia o servidor agente: A agentdev CLI envolve o seu agente como um servidor HTTP na porta 8087, com o debugpy ligado na porta 5679.
2. Descobrir agentes: A interface recolhe agentes/fluxos de trabalho disponíveis a partir de /agentdev/entities.
3. Execução do stream: As entradas do chat vão para /v1/responses, que transmite eventos via SSE para visualização em tempo real.
4. Ativar a navegação por código: Clique duas vezes nos nós do fluxo de trabalho para abrir o ficheiro-fonte correspondente no editor.
5. Ative a conversa com o agente local e visualize as respostas, atingir pontos de interrupção para depuração, e assim por diante.

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

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.

Pode executar o agente hospedado em modo interativo ou contentor.

Execute o seu agente alojado em modo interativo

Execute o agente hospedado 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 Microsoft Foundry: Open Container Agent Playground Locally.
2. Use o comando seguinte para inicializar o agente hospedado containerizado.

   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

O Foundry Toolkit para Visual Studio Code fornece um grafo de execução em tempo real que mostra como os agentes no 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 fluxo de trabalho do seu agente alojado em tempo real:

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

2. Executa este comando: >Microsoft Foundry: 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 Foundry. 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 Visual Studio Code e execute o comando Microsoft Foundry: Deploy Hosted Agent.
2. Configure as definições de implementação selecionando o seu espaço de trabalho de destino, especificando o ficheiro agente do contentor (container.py), e definindo quaisquer outros parâmetros de implementação conforme necessário.
3. Após a implementação bem-sucedida, o agente hospedado aparece na secção Hosted Agents (Preview) da árvore de visualização da extensão Microsoft Foundry.
4. Selecione o agente implementado para aceder a informações detalhadas e funcionalidades de teste usando a interface integrada do playground.

1. Abra a Paleta de Comandos Visual Studio Code e execute o comando Microsoft Foundry: Deploy Hosted Agent.
2. Configure as definições de implementação selecionando o seu espaço de trabalho de destino, especificando o ficheiro agente do contentor (<your-project-name>.csproj), e definindo quaisquer outros parâmetros de implementação conforme necessário.
3. Após a implementação bem-sucedida, o agente hospedado aparece na secção Hosted Agents (Preview) da árvore de visualização da extensão Microsoft Foundry.
4. Selecione o agente implementado para aceder a informações detalhadas e funcionalidades de teste usando a interface integrada do playground.