Aracılığıyla paylaş

Visual Studio Code'da barındırılan aracı iş akışları oluşturma (önizleme)

Visual Studio Code için Microsoft Foundry uzantısını kullanarak barındırılan Foundry Aracısı iş akışları oluşturun, test edin ve dağıtın. Barındırılan iş akışları, her biri kendi modeli, araçları ve yönergeleriyle birden çok aracının sırayla işbirliği yapmasına olanak tanır.

Başlamadan önce, uzantıyı kullanarak Foundry Ajan Hizmeti'nde bir ajan oluşturun. Ardından bu aracıya barındırılan iş akışları ekleyebilirsiniz.

Bu makale, bir iş akışı projesi oluşturmayı, yerel olarak çalıştırmayı, yürütmeyi görselleştirmeyi ve Foundry çalışma alanınıza dağıtmayı kapsar.

Önkoşullar

  • Python 3.10 veya üzeri.

Barındırılan bir aracı için iş akışı oluşturun

Barındırılan aracı iş akışları oluşturmak için Visual Studio Code için Foundry uzantısını kullanabilirsiniz. Barındırılan ajan iş akışı, bir görevi tamamlamak için birlikte çalışan ajanlardan oluşan bir diziyi ifade eder. İş akışındaki her aracı kendi modeline, araçlarına ve yönergelerine sahip olabilir.

  1. Komut paletini açın (Ctrl+Shift+P).

  2. Şu komutu çalıştırın: >Microsoft Foundry: Create a New Hosted Agent.

  3. Bir programlama dili seçin.

  4. Yeni iş akışınızı kaydetmek istediğiniz klasörü seçin.

  5. İş akışı projeniz için bir ad girin.

Kullanmaya başlamanız için örnek bir kod dosyası da dahil olmak üzere barındırılan aracı projeniz için gerekli dosyaları içeren yeni bir klasör oluşturulur.

Bağımlılıkları yükleme

Barındırılan aracı projeniz için gerekli bağımlılıkları yükleyin. Bağımlılıklar, projeyi oluştururken seçtiğiniz programlama diline göre değişir.

  1. Sanal ortam oluşturma.

     python -m venv .venv

  2. Sanal ortamı etkinleştirin.

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

# Windows cmd
.venv\Scripts\activate.bat

# Unix/MacOS
source .venv/bin/activate

  3. Aşağıdaki paketi yükleyin:

    pip install azure-ai-agentserver-agentframework

  1. Proje dizininize gidin ve gerekli NuGet paketlerini almak için şu komutu çalıştırın:

    dotnet restore

Barındırılan iş akışınızı yerel olarak çalıştırma

Örnek iş akışı projesi, gerekli ortam değişkenleriyle bir .env dosyası oluşturur. .env dosyasını Foundry kimlik bilgilerinizle oluşturun veya güncelleştirin:

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

AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

Önemli

.env dosyasını hiçbir zaman sürüm denetimine işlemeyin. Dosyanıza .gitignore ekleyin.

Barındırılan aracınızın kimliğini doğrulama

Barındırılan aracı örneği DefaultAzureCredential kullanarak kimlik doğrulaması yapar. Geliştirme ortamınızı desteklenen kaynaklardan biri aracılığıyla kimlik bilgileri sağlayacak şekilde yapılandırın, örneğin:

  • Azure CLI (az login)
  • Visual Studio Code hesabıyla oturum açma
  • Visual Studio hesabıyla oturum açma
  • Hizmet sorumlusu için ortam değişkenleri (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Örneği çalıştırmadan önce Azure CLI az account show veya az account get-access-token komutlarını çalıştırarak kimlik doğrulamasını yerel olarak onaylayın.

Barındırılan aracıyı etkileşimli modda veya kapsayıcı modunda çalıştırabilirsiniz.

Barındırılan aracınızı etkileşimli modda çalıştırma

Hata ayıklamayı başlatmak için VS Code'da F5 tuşuna basın. Alternatif olarak VS Code hata ayıklama menüsünü de kullanabilirsiniz:

  1. Çalıştır ve Hata Ayıkla görünümünü açın (Ctrl+Shift+D / Cmd+Shift+D)
  2. Açılan listeden "Yerel İş Akışı HTTP Sunucusunda Hata Ayıkla" seçeneğini belirleyin
  3. Yeşil Hata Ayıklamayı Başlat düğmesini seçin (veya F5 tuşuna basın)

Bu şunları yapacaktır:

  1. Hata ayıklama etkinken HTTP sunucusunu başlatma
  2. Etkileşimli test için AI Toolkit Aracı Denetçisi'ni açın
  3. Kesme noktaları ayarlamanıza ve iş akışı yürütmesini gerçek zamanlı olarak incelemenize olanak tanır.

Barındırılan aracınızı kapsayıcı modunda çalıştırma

Tavsiye

Görselleştirmenin doğru çalıştığından emin olmak için kapsayıcı aracısını başlatmadan önce yerel oyun parkını açın.

Barındırılan aracıyı kapsayıcı modunda çalıştırmak için:

  1. Visual Studio Code Komut Paleti'ni açın ve Microsoft Foundry: Open Container Agent Playground Locally komutunu yürütün.
  2. main.py kapsayıcılı barındırılan aracıyı başlatmak için çalıştırın.
  3. Oyun alanı arabirimi aracılığıyla aracıya bir istek gönderin. Örneğin, "Uygun fiyatlı ve sürüşü eğlenceli yeni bir elektrikli SUV için bir slogan oluşturun" gibi bir istem girin.
  4. Oyun alanı arabiriminde aracının yanıtını gözden geçirin.

Örnek iş akışı projesi, gerekli ortam değişkenleriyle bir .env dosyası oluşturur. .env dosyasını Foundry kimlik bilgilerinizle oluşturun veya güncelleştirin:

  1. ortam değişkenlerinizi işletim sisteminize göre ayarlayın:

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

Barındırılan aracınızın kimliğini doğrulama

Barındırılan aracı örneği DefaultAzureCredential kullanarak kimlik doğrulaması yapar. Geliştirme ortamınızı desteklenen kaynaklardan biri aracılığıyla kimlik bilgileri sağlayacak şekilde yapılandırın, örneğin:

  • Azure CLI (az login)
  • Visual Studio Code hesabıyla oturum açma
  • Visual Studio hesabıyla oturum açma
  • Hizmet sorumlusu için ortam değişkenleri (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Örneği çalıştırmadan önce Azure CLI az account show veya az account get-access-token komutlarını çalıştırarak kimlik doğrulamasını yerel olarak onaylayın.

Barındırılan aracıyı etkileşimli modda veya kapsayıcı modunda çalıştırabilirsiniz.

Barındırılan aracınızı etkileşimli modda çalıştırma

Barındırılan aracıyı doğrudan geliştirme ve test için çalıştırın:

dotnet restore
dotnet build
dotnet run

Barındırılan aracınızı kapsayıcı modunda çalıştırma

Tavsiye

Görselleştirmenin doğru çalıştığından emin olmak için kapsayıcı aracısını başlatmadan önce yerel oyun parkını açın.

Aracıyı kapsayıcı modunda çalıştırmak için:

  1. Visual Studio Code Komut Paleti'ni açın ve Microsoft Foundry: Open Container Agent Playground Locally komutunu yürütün.
  2. Kapsayıcılı barındırılan aracıyı başlatmak için aşağıdaki komutu kullanın. 
    dotnet restore
dotnet build
dotnet run
  3. Oyun alanı arabirimi aracılığıyla aracıya bir istek gönderin. Örneğin, "Uygun fiyatlı ve sürüşü eğlenceli yeni bir elektrikli SUV için bir slogan oluşturun" gibi bir istem girin.
  4. Oyun alanı arabiriminde aracının yanıtını gözden geçirin.

Barındırılan aracı iş akışı yürütmesini görselleştir

Visual Studio Code için Foundry uzantısı, iş akışınızdaki aracıların nasıl etkileşime geçtiğini ve işbirliği yaptığını gösteren gerçek zamanlı bir yürütme grafiği sağlar. Bu görselleştirmeyi kullanmak için projenizde gözlemlenebilirliği etkinleştirin.

Aşağıdaki kod parçacığını ekleyerek iş akışlarınızda görselleştirmeyi etkinleştirin:

from agent_framework.observability import setup_observability
setup_observability(vs_code_extension_port=4319) # Default port is 4319

Csproj dosyanıza aşağıdaki başvuruyu ekleyin:

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

Programınızı aşağıdaki kod parçacığını içerecek şekilde güncelleştirin:

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();

Barındırılan aracı iş akışınızı izleme ve görselleştirme

Barındırılan aracı iş akışı yürütmenizi gerçek zamanlı olarak izlemek ve görselleştirmek için:

  1. Komut paletini açın (Ctrl+Shift+P).

  2. Şu komutu çalıştırın: >Microsoft Foundry: Open Visualizer for Hosted Agents.

YÜRÜTME grafını görüntülemek için VS Code'da yeni bir sekme açılır. Görselleştirme, aracılar ve etkileşimleri arasındaki akışı göstermek için iş akışınız ilerledikçe otomatik olarak güncelleştirilir.

Bağlantı noktası çakışmaları

Bağlantı noktası çakışmaları için, görselleştirme bağlantı noktasını Foundry uzantısı ayarlarında ayarlayarak değiştirebilirsiniz. Bunu yapmak için şu adımları uygulayın:

  1. VS Code'un sol kenar çubuğunda dişli simgesini seçerek ayarlar menüsünü açın.
  2. öğesini seçin Extensions>Microsoft Foundry Configuration.
  3. Hosted Agent Visualization Port Ayarı bulun ve kullanılabilir bir bağlantı noktası numarasıyla değiştirin.
  4. Değişiklikleri uygulamak için VS Code'ı yeniden başlatın.

Koddaki bağlantı noktasını değiştirme

Ortam değişkenini ayarlayarak FOUNDRY_OTLP_PORT görselleştirme bağlantı noktasını değiştirin. workflow.py dosyasındaki gözlemlenebilirlik bağlantı noktasını uygun şekilde güncelleştirin.

Örneğin, bağlantı noktasını 4318 olarak değiştirmek için şu komutu kullanın:

  export FOUNDRY_OTLP_PORT=4318

içinde workflow.py, gözlemlenebilirlik yapılandırmasındaki bağlantı noktası numarasını güncelleştirin:

  setup_observability(vs_code_extension_port=4318)

Tavsiye

Daha fazla hata ayıklama bilgisi etkinleştirmek için enable_sensitive_data=True parametresini setup_observability işleve ekleyin.

Tüm bağlantı noktası çakışmaları için ortam değişkenini ayarlayarak FOUNDRY_OTLP_PORT görselleştirme bağlantı noktasını değiştirin. Programınızdaki OTLP uç noktasını uygun şekilde güncelleştirin.

Örneğin, bağlantı noktasını 4318 olarak değiştirmek için şu komutu kullanın:

  $env:FOUNDRY_OTLP_PORT="4318"

Programınızda OTLP uç noktasını yeni bağlantı noktası numarasını kullanacak şekilde güncelleştirin:

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

Sunucuda barındırılan ajanı dağıt

Barındırılan aracınızı yerel olarak test ettikten sonra, diğer ekip üyelerinin ve uygulamaların kullanabilmesi için bu aracıyı Foundry çalışma alanınıza dağıtın.

Önemli

Önkoşullar bölümünde belirtildiği gibi, Foundry çalışma alanınızda barındırılan aracıları dağıtmak için gerekli izinleri verdiğinizden emin olun. Gerekli rol atamalarını almak için Azure yöneticinizle birlikte çalışmanız gerekebilir.

  1. Visual Studio Code Komut Paleti'ni Microsoft Foundry: Deploy Hosted Agent açın ve komutunu çalıştırın.
  2. Hedef çalışma alanınızı seçerek, kapsayıcı aracısı dosyasını ()container.py belirterek ve gerektiğinde diğer dağıtım parametrelerini tanımlayarak dağıtım ayarlarını yapılandırın.
  3. Başarılı bir dağıtımın ardından, barındırılan aracı Microsoft Foundry uzantısı ağaç görünümünün Hosted Agents (Preview) bölümünde görünür.
  4. Tümleşik oyun alanı arabirimini kullanarak ayrıntılı bilgilere erişmek ve işlevselliği test etmek için dağıtılan aracıyı seçin.
  1. Visual Studio Code Komut Paleti'ni Microsoft Foundry: Deploy Hosted Agent açın ve komutunu çalıştırın.
  2. Hedef çalışma alanınızı seçerek, kapsayıcı aracısı dosyasını ()<your-project-name>.csproj belirterek ve gerektiğinde diğer dağıtım parametrelerini tanımlayarak dağıtım ayarlarını yapılandırın.
  3. Başarılı bir dağıtımın ardından, barındırılan aracı Microsoft Foundry uzantısı ağaç görünümünün Hosted Agents (Preview) bölümünde görünür.
  4. Tümleşik oyun alanı arabirimini kullanarak ayrıntılı bilgilere erişmek ve işlevselliği test etmek için dağıtılan aracıyı seçin.

İlgili içerik

  • Last updated on