Aracıları test edin, dağıtın ve entegre edin.

Tamamlandı

Tip

Daha fazla ayrıntı için Metin ve resimler sekmesine bakın!

Aracıları test etme, dağıtma ve yayımlama, geliştirme aşamasından üretime geçişte kritik adımlardır. Microsoft Foundry aracı davranışını doğrulamaya, Foundry projenize dağıtmaya ve aracıları dış tüketicilerin ve uygulamaların kullanabileceği çağrılabilir uç noktalar olarak yayımlamaya yönelik kapsamlı özellikler sağlar.

Ajanlar için test stratejileri

Kapsamlı test, aracılarınızın kullanıcılara ulaşmadan önce çeşitli senaryolarda güvenilir bir şekilde davranmasını sağlar. Hem Foundry portalı hem de Visual Studio Code uzantısı etkileşimli test için oyun alanları sağlar.

Oyun alanının etkili bir şekilde kullanılması:

• Mutlu yol testi - Ajanın yaygın ve beklenen istekleri doğru işlediğini doğrulayın.
• Sınır durum testi - Aracıların belirsizlikle nasıl başa çıktığını ortaya çıkarmak için belirsiz girişler, eksik bilgiler ve olağan dışı istekler üzerinde test yapın.
• Sınır testi - Kapsam dışı istekleri test ederek aracının yönergelerinde tanımlanan sınırlara saygılı olduğunu onaylayın.
• Çok aşamalı konuşma testi - Aracın birden çok değişimde bağlamı koruyup önceki yanıtlara dayanarak inşa ettiğini doğrulayın.
• Araç çağırma testi - Aracıların doğru zamanda doğru araçları çağırdığını ve sonuçları doğru şekilde birleştirip eklemedığını doğrulayın.

İyileştirmeleri izlemek ve regresyonları yakalamak için test sonuçlarını kaydedin.

Projenize ajan dağıtma

Microsoft Foundry, portaldan veya Visual Studio Code'dan aracı dağıtmayı destekler. Dağıtım aracı yapılandırmanızı Foundry projenize kaydeder, böylece test edebilir ve yineleyebilirsiniz.

Foundry portalından dağıtım

1. Dökümhane portalında temsilcinize gidin
2. Yapılandırma ve test sonuçlarının tatmin edici olduğunu doğrulayın
3. Aracı sayfasından Kaydet'i seçin
4. Sürüm ve dağıtım ayarlarını onaylama

Visual Studio Code'dan dağıtma

1. AI Araç Seti'nde ajanınızı açın
2. Yapılandırma değişikliklerini göndermek için Foundry'ye Kaydet'i seçin
3. Barındırılan aracılar için geliştirici araçlarında +Derleme menüsünü açın ve Microsoft Foundry'ye Dağıt'ı seçin
4. Kapsayıcı yapılandırmanızı seçin ve onaylayın

Her iki yaklaşım da aracınızı ekip üyelerinin erişebileceği ve testebileceği proje çalışma alanınızda tutar.

Aracıları bir uç noktaya yayınlamak

Yayımlama, bir aracıyı proje çalışma alanınızdan Aracı Uygulaması adlı yönetilen bir Azure kaynağına taşır. Bu adım, aracınızı kararlı bir uç nokta üzerinden dışarıdan çağrılabilen hale getiren adımdır.

Yayıncılığın oluşturdukları

Aracı (veya etmen) sürümünü yayımladığınızda Foundry şunları oluşturur:

• Aracı Uygulaması - Kendi çağırma URL'sine, kimlik doğrulama ilkesine ve Entra aracısı kimliğine sahip bir Azure kaynağı.
• Dağıtım - Başlatma/durdurma yaşam döngüsü yönetimi ile uygulamanın içindeki belirli bir aracı sürümünün çalışan örneği.

Dağıtım ve yayımlama arasındaki temel fark kapsamdır. Projeye etken dağıtım yapmak, etkenin projenizde kalmasını sağlar. Yayımlama, dış tüketicilerin Foundry projenize erişmeye gerek kalmadan çağırabileceği ayrılmış bir uç nokta oluşturur.

Dökümhane portalından yayımlama

1. Portalda yayımlamak istediğiniz aracı sürümünü seçin
2. Aracı Uygulaması ve dağıtımı oluşturmak için Yayımla'yı seçin

Visual Studio Code'dan yayımlama

1. Komut Paleti'ni (Ctrl+Shift+P) açın ve Microsoft Foundry: Barındırılan aracılar için Barındırılan Aracı Dağıtma'yı çalıştırın
2. Hedef çalışma alanını ve kapsayıcı yapılandırmasını seçin
3. Onaylayın ve dağıtın

Yayımladıktan sonra aracı, AI Toolkit uzantı ağacı görünümünün Barındırılan Aracılar (Önizleme) bölümünde görünür.

Aracı Uygulaması uç noktası

Yayımlanan aracılar, Yanıtlar API protokolunu kullanarak kararlı bir uç noktayı kullanıma sunar:

https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses

Bu URL, yeni aracı sürümlerini dağıttıkça bile aynı kalır, bu nedenle sonraki kullanıcılar güncellemelerden etkilenmez.

Kimlik doğrulaması ve kimlik

Aracı Uygulamaları kimlik doğrulaması için Microsoft Entra Id kullanır. Arayanların Agent Uygulama kaynağında Azure AI Kullanıcısı rolüne sahip olması gerekir. API anahtarı kimlik doğrulaması Aracı Uygulamaları için desteklenmez.

Önemli

Bir aracı yayımladığınızda, projenin paylaşılan kimliğinden ayrı olarak kendine ait Entra kimliğine sahip olur. İzinler otomatik olarak aktarılamaz. Ajanın eriştiği tüm kaynaklar için RBAC rollerini yeni ajan kimliğine yeniden atamanız gerekir. Bu adımı atlarsanız, geliştirme sırasında çalışan araç çağrıları, aracı yayımlandıktan sonra yetkilendirme hatalarıyla başarısız olur.

Uç noktayı doğrulama

Yayımladıktan sonra uç noktanın çalıştığını doğrulayın:

1. Erişim belirteci alma:

   az account get-access-token --resource https://ai.azure.com
   

2. Temsilci Uygulama uç noktasını çağırın.

   curl -X POST \
     "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
     -H "Authorization: Bearer <access-token>" \
     -H "Content-Type: application/json" \
     -d '{"input":"Say hello"}'
   

Eğer 403 Forbidden alırsanız, arayanın Aracı Uygulama kaynağı üzerinde Azure AI Kullanıcısı rolüne sahip olduğunu onaylayın.

Yayımlanan aracıları güncelleştirme

Yeni bir ajan sürümünü yayına almak için:

1. Geliştirme ortamınızda değişiklik yapın ve kapsamlı bir şekilde test edin
2. Dökümhane portalında, Aracı oyun alanından Güncelleştirmeleri Yayımla'yı seçin
3. Aracı Uygulaması 100% trafiği otomatik olarak yeni sürüme yönlendirir

Uç nokta URL'si değişmeden kaldığından, mevcut tümleştirmeler çalışmaya devam eder.

Tümleştirme kodu oluşturma

Microsoft Foundry VS Code uzantısı, uygulamanızı yayımlanmış bir aracıya bağlamak için örnek tümleştirme kodu oluşturur:

1. Kaynaklarım görünümünde dağıtılan aracınızı seçin
2. Kodu Görüntüle'yi seçin
3. Klasörünüzü seçin
4. Uzantı kimlik doğrulaması, bağlanma, ileti gönderme ve yanıtları işlemeye yönelik kod oluşturur

Entegrasyon desenleri

Yayımlanan aracıların entegrasyonu için yaygın yöntemler şunlardır:

• Web uygulamaları - Yanıtlar API'sinin uç noktasına kullanıcı iletileri gönderin ve yanıtları kullanıcı arabiriminizde görüntüleyin. Çok aşamalı etkileşimler için konuşma geçmişi istemci tarafında depolayın.
• API temelli iş akışları - Olaylar veya zamanlamalar tarafından tetiklenen arka uç hizmetlerinden aracı uç noktasını çağırın. Aşağı akış eylemlerini yönlendirmek için yanıtları program aracılığıyla işleyin.
• Sohbet botu arabirimleri - Kullanıcı oturumlarını konuşmalarla eşleyin. Uç nokta üzerinden gerçek zamanlı ileti değişimini işleme.
• Arka plan otomasyonu - Yinelenen görevler için aracı çağrılarını zamanlayın. Sistem verilerini aracılara aktarıp iş sistemlerini güncelleştirmek için çıkışları işleyin.

Üretimle ilgili dikkat edilmesi gerekenler

Üretimde aracı çalıştırmak için birkaç işletim alanına dikkat etmek gerekir:

• İzleme - Application Insights tümleştirmesini kullanarak yanıt sürelerini, araç çağırma başarı oranlarını, hata desenlerini ve belirteç tüketimini izleyin.
• Güvenlik - Kimlik doğrulaması için yönetilen kimlikleri kullanın, en az ayrıcalıklı erişim uygulayın ve veri saklama ilkeleri tanımlayın.
• Maliyet yönetimi - Belirteç kullanımını izleyin, yanıt uzunluğu sınırlarını ayarlayın ve beklenmeyen ani artışları önlemek için hız sınırlaması uygulayın.
• Hata işleme - Geçici hatalar için üstel geri alma ile yeniden deneme mantığını uygulayın. Geri çekilme stratejileriyle hız sınırlamayı işleyin. Aracılara göndermeden önce girişleri doğrulayın.
• Konuşma yönetimi - Aracı Uygulaması uç noktaları şu anda yalnızca durum bilgisi olmayan Yanıtlar API'sini desteklemektedir. Çok aşamalı deneyimler için konuşma geçmişini istemcinizde depolayın.