Özel aracılar kaydet ve yönet

Microsoft Foundry Denetim Düzlemi, farklı platformlarda ve altyapılarda çalışan aracılar için merkezi yönetim ve gözlemlenebilirlik sağlar. İşlemleri hakkında görünürlük elde etmek ve davranışlarını denetlemek için Azure işlem hizmetlerinde veya diğer bulut ortamlarında çalışan özel aracıları kaydedebilirsiniz.

Bu makalede, özel bir ajanın Foundry Kontrol Düzlemi'ne nasıl kaydedileceği hakkında bilgi verilmektedir. Ajanınızı kayıt için yapılandırmayı, veri toplamayı ayarlamayı ve Foundry Kontrol Düzlemi'nin yönetim özelliklerini kullanmayı öğrenirsiniz.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı. Hesabınız yoksa ücretsiz deneme aboneliği içeren bir free Azure hesabı oluşturun.

• Bir Dökümhane projesi. Eğer yoksa, bir proje oluşturun.

• Foundry kaynağınızda yapılandırılmış bir yapay zeka ağ geçidi. Foundry, aracıları API'ler olarak kaydetmek için Azure API Management kullanır.

• Erişilebilir bir uç nokta aracılığıyla dağıttığınız ve kullanıma eklediğiniz bir aracı. Uç nokta genel bir uç nokta veya Foundry kaynağını dağıttığınız ağdan erişilebilen bir uç nokta olabilir.

Uyarı

Bu özellik yalnızca Dökümhane (yeni) portalında kullanılabilir. Foundry (yeni) kullandığınızı onaylamak için portal başlığında öğesini arayın.

Özel aracı ekleme

Özel bir aracıyı Foundry Kontrol Düzlemine kaydedebilirsiniz. Aracıyı seçtiğiniz teknolojide hem platform hem de altyapı çözümleri için geliştirin.

Özel bir aracı kaydettiğinizde, Foundry, aracınızla iletişimde ara sunucu olarak görev yapmak üzere API Management'ı kullanır, böylece erişimi kontrol edip etkinliği izleyebilir.

Aşağıdaki diyagramda, özel bir ajanı kaydettiğinizde ortaya çıkan mimari gösterilmektedir.

Temsilcinizi doğrulayın

Ajanınızın kayıt gereksinimlerini karşıladığını doğrulayın.

• Ajanınız özel ve benzersiz bir uç noktayı ortaya çıkarır.
• Foundry kaynağını dağıttığınız ağ aracının uç noktasına ulaşabilir.
• Aracı, desteklenen protokollerden birini kullanarak iletişim kurar: HTTP (genel) veya A2A (daha ayrıntılı).
• Aracınız, üretken yapay zeka çözümleri için OpenTelemetry semantik kurallarını kullanarak veri yayar (veya bu özelliğe ihtiyacınız yoktur).
• Kullanıcıların aracıyla iletişim kurmak için kullandığı uç noktayı yapılandırabilirsiniz. Bir aracıyı kaydettikten sonra, Foundry Denetim Düzlemi yeni bir URL oluşturur. İstemciler ve kullanıcılar aracıyla iletişim kurmak için bu URL'yi kullanmalıdır.

Foundry projeni hazırla

Bir Foundry project eklediğiniz özel aracıyı kaydetmeden önce project doğru yapılandırdığınızdan emin olun:

1. Microsoft Foundry'ye giriş yapın. Yeni Dökümhane anahtarının açık olduğundan emin olun. Bu aşamalar Foundry (yeni) konusuna yöneliktir.

   

2. AI ağ geçidinin projenizde yapılandırıldığından emin olun.

   1. Araç çubuğunda çalıştır'ı seçin.

   2. Sol bölmede Yönetici'yi seçin.

   3. AI Gateway sekmesini açın.

   4. Bölmede, bir Foundry kaynağıyla yapılandırılmış ve eşlenmiş tüm yapay zeka ağ geçitleri listelenir. Kullanmak istediğiniz Foundry kaynağının ilişkili bir yapay zeka ağ geçidine sahip olup olmadığını denetleyin.

      

   5. Kullanmak istediğiniz Foundry kaynağında yapılandırılmış bir yapay zeka ağ geçidi yoksa (listelenmiyorsa), AI Ağ Geçidi Ekle seçeneğini kullanarak bir ağ geçidi ekleyin.

      Yapay zeka ağ geçidi, ücretsiz olarak kurulabilir ve aracılarınız, araçlarınız ve modelleriniz için güvenlik, tanılama verileri ve hız sınırları gibi güçlü yönetim özelliklerinin kullanılmasını sağlar. Daha fazla bilgi için bkz. Yapay zeka ağ geçidi oluşturma.

3. Projede gözlemlenebilirliğin yapılandırılmış olduğundan emin olun. Foundry Control Plane, aracınızı tanılamanıza yardımcı olmak üzere veri yaymak için seçtiğiniz proje ile ilişkili Application Insights kaynağını kullanır.

   1. Araç çubuğunda çalıştır'ı seçin.

   2. Sol bölmede Yönetici'yi seçin.

   3. Tüm projeler altında, projenizi aramak için arama kutusunu kullanın.

   4. Projeyi seçin.

   5. Bağlı kaynaklar sekmesini seçin.

   6. AppInsights kategorisinde ilişkili bir kaynak olduğundan emin olun.

      

   7. İlişkili kaynak yoksa, Bağlantı> ekleApplication Insights'ı seçerek bir kaynak ekleyin.

Sizin projeniz gözlemlenebilirlik ve izleme amacıyla yapılandırılmıştır.

Aracıyı kaydet

1. Araç çubuğunda çalıştır'ı seçin.

2. Genel Bakış bölmesinde Aracıyı kaydet'i seçin.

   

3. Kayıt sihirbazı görüntülenir. İlk olarak, kaydetmek istediğiniz aracıyla ilgili ayrıntıları tamamlayın. Aşağıdaki özellikler, etmenin kendi platformunda çalışırken nasıl davrandığını açıklar:

   Mülkiyet	Description	Gerekli
   Aracı URL'si	Ajanınızın çalıştırıldığı ve istekleri aldığı uç nokta (URL). Genel olarak, ancak protokole bağlı olarak, istemcilerinizin kullandığı temel URL'yi belirtirsiniz. Örneğin, aracınız OpenAI Sohbet Tamamlamaları API'sini kullanıyorsa, istemciler genellikle eklediği için https://<host>/v1/ belirtirsiniz, /chat/completions kullanmadan.	Evet
   Protokol	Ajanınızın desteklediği iletişim protokolü. Genel olarak HTTP kullanın. Veya aracınız A2A'yı daha ayrıntılı olarak destekliyor ise bunu belirtiniz.	Evet
   A2A aracı kartı URL'si	Aracı kartının JSON belirtiminin yolu. Belirtmezseniz, sistem varsayılan /.well-known/agent-card.jsonkullanır.	Hayı
   OpenTelemetry Aracısı Kimliği	Ajanınızın, üretken yapay zeka için OpenTelemetry semantik kurallarına göre izleri yaymak için kullandığı ajan kimliği. İzlemeler, gen_ai.agents.id işlem adına sahip spanler için create_agent özniteliğinde bunu gösterir. Bu değeri belirtmezseniz sistem, bu yeni aracının rapor verdiği izlemeleri ve günlükleri bulmak için Aracı adı değerini kullanır.	Hayı
   Yönetici portalı URL'si	Bu aracı için daha fazla yönetim işlemi gerçekleştirebileceğiniz yönetim portalı URL'si. Dökümhane kolaylık sağlamak için bu değeri depolayabilir. Dökümhane, bu portal üzerinde doğrudan işlem gerçekleştirmek için herhangi bir erişime sahip değildir.	Hayı

4. Aracının DökümHane Denetim Düzlemi'nde nasıl görünmesini istediğinizi yapılandırın:

   Mülkiyet	Description	Gerekli
   Project	Ajanı kaydettiğiniz proje. Foundry, araca gelen uç noktayı yapılandırmak için projenin bulunduğu kaynakta yapılandırılan yapay zeka ağ geçidini kullanır. Yalnızca kaynaklarında yapay zeka ağ geçidi etkinleştirilmiş projeleri seçebilirsiniz. Herhangi bir yapay zeka ağ geçidi görmüyorsanız , Foundry kaynağınızda bir yapay zeka ağ geçidi yapılandırın. Seçilen projede Application Insights'ı yapılandırmanızı da öneririz. Foundry, izleri ve günlükleri toplamak için projenin Application Insights kaynağını kullanır.	Evet
   Aracı adı	Foundry'de görünmesini istediğiniz şekilde etkenin adı. OpenTelemetry Aracısı Kimliği için farklı bir değer belirtmezseniz sistem, Application Insights'ta ilgili izlemeleri ve günlükleri bulmak için de bu adı kullanabilir.	Evet
   Açıklama	Bu temsilci hakkında net bir açıklama.	Hayı

5. Değişiklikleri kaydedin.

6. Foundry yeni ajanı ekler. Aracı listesini denetlemek için sol bölmede Varlıklar'ı seçin.

7. Yalnızca özel aracıları göstermek için Kaynak filtresini kullanın ve Özel'i seçin.

   

İstemcileri aracıya bağlama

Ajanınızı Foundry'ye kaydettiğinizde, müşterilerinizin kullanması için yeni bir URL alırsınız. Foundry, aracınızla iletişim için ara sunucu olarak çalışarak erişimi denetleyebilir ve etkinliği izleyebilir.

İstemcilerinizin aracıyı çağırabilmesi için yeni URL'yi dağıtmak için:

1. Özel aracıyı seçin.

2. Ayrıntılar bölmesindeki Aracı URL'si altında Kopyala seçeneğini belirleyin.

   

3. Özgün uç nokta yerine aracıyı çağırmak için yeni URL'yi kullanın.

Bu örnekte, bir LangGraph aracısı dağıtacaksınız. Müşteriler LangGraph SDK'sını tüketmek için kullanır. İstemci yeni aracı URL değerini kullanır. Bu kod bir iş parçacığı oluşturur, hava durumuyla ilgili bir ileti gönderir ve yanıtı geri akışla aktarır.

from langgraph_sdk import get_client

client = get_client(url="https://apim-my-foundry-resource.azure-api.net/my-custom-agent/") 

async def stream_run():
   thread = await client.threads.create()
   input_data = {"messages": [{"role": "human", "content": "What's the weather in LA?"}]}
   
   async for chunk in client.runs.stream(thread['thread_id'], assistant_id="your_assistant_id", input=input_data):
       print(chunk)

Beklenen çıkış: Aracı, iletiyi işler ve yanıtları öbekler olarak geri akışla aktarır. Her bölüm, ajanın yürütülmesinden kısmi sonuçlar içerir. Bu sonuçlar, hava durumu işlevine yapılan araç çağrılarını ve Los Angeles hava durumu hakkındaki son yanıtı içerebilir.

Uyarı

Foundry aracınız için gelen istekler için ara sunucu işlevi görse de, özgün uç noktadaki özgün yetkilendirme ve kimlik doğrulama şeması yine de geçerlidir. Yeni uç noktayı kullandığınızda, özgün uç noktayı kullanıyorsanız aynı kimlik doğrulama mekanizmasını sağlayın.

Ajanı engelle ve engelini kaldır

Özel aracılar için Foundry'nin, aracının bulunduğu temel altyapıya erişimi bulunmamaktadır, bu nedenle başlatma ve durdurma işlemleri kullanılamaz. Ancak Foundry, istemciler tarafından tüketilemeyecek şekilde aracıya gelen istekleri engelleyebilir. Bu özellik, yanlış davranan bir aracıyı yöneticilerin devre dışı bırakmasına olanak tanır.

Ajanınıza gelen istekleri engellemek için:

1. Araç çubuğunda çalıştır'ı seçin.

2. Sol bölmede Varlıklar'ı seçin.

3. Engellemek istediğiniz aracıyı seçin. Bilgi bölmesi görüntülenir.

4. Durumu güncelleştir'i ve ardından Engelle'yi seçin.

   

5. İşlemi onaylayın.

Aracıyı engelledikten sonra, Foundry'deki aracının Durum değeri Engellenir. Bloklu durumundaki ajanlar kendi ilişkili altyapılarında çalışırlar ancak gelen istekleri alamazlar. Foundry aracı ile arabirim denemelerini engeller.

Temsilcinin engelini kaldırmak için:

1. Durumu güncelleştir'i ve ardından Engellemeyi Kaldır'ı seçin.

2. İşlemi onaylayın.

Aracı için tanılama verilerini etkinleştir

Foundry, aracıların ne yaptığını anlamak için OpenTelemetry açık standardını kullanır. Eğer projeniz Application Insights ile yapılandırılmışsa, Foundry varsayılan olarak istekleri Application Insights'a günlüğe kaydeder. Dökümhane aşağıdaki verileri hesaplamak için de kullanır:

• Runs
• Hata oranı
• Kullanım (varsa)

En iyi aslına uygunluk düzeyini elde etmek için Foundry, özel aracıların OpenTelemetry standardındaki üretken yapay zeka çözümlerine yönelik anlam kurallarına uymasını bekler.

Foundry'ye gönderilen izlemeleri ve günlükleri görüntüleme

1. Araç çubuğunda çalıştır'ı seçin.

2. Sol bölmede Varlıklar'ı seçin.

3. Ajanı seçin.

4. İzlemeler bölümünde, acente uç noktasına yapılan her HTTP çağrısı için bir kayıt gösterilir.

   Ayrıntıları görmek için bir girdi seçin.

   

   Tavsiye

   Bu örnekte, istemcilerin yeni ajan uç noktasını kullanarak ajanla nasıl iletişim kurduğunu görebilirsiniz. Örnekte, LangChain'den Aracı Protokolü ile sunulan bir aracı gösterilmektedir. İstemciler yolunu /runs/streamkullanır.

Bu örnekte izleme, HTTP gönderisinin dışında hiçbir ayrıntı içermez. Ajan kodu başka bir izleme içermez. Sonraki bölümde kodunuzu nasıl enstrümante edip araç çağrıları ve büyük dil modeli (LLM) kullanımları gibi ayrıntıları alacağınızı öğreneceksiniz.

Özel kod ajanlarını enstrüman etme

Aracınızı özel kod kullanarak oluşturursanız, çözümünüzü izlemek için OpenTelemetry standardına göre izlemeleri yaymak ve bunları Application Insights'a göndermek üzere enstrümante edin. Enstrümanlaştırma, Foundry'nin aracınızın ne yaptığını ayrıntılı bir şekilde anlaması için erişimi sağlar.

Projenizin Application Insights kaynağına araç anahtarını kullanarak izlemeler gönderin. Project ile ilişkili enstrümantasyon anahtarını almak için Project'inizde izlemeyi etkinleştirin altındaki yönergeleri izleyin.

Bu örnekte, OpenTelemetry standardında izler yayması için LangGraph ile geliştirilmiş bir ajanı yapılandıracaksınız. İzleyici, araç çağrıları ve model etkileşimleri de dahil olmak üzere tüm aracı işlemlerini yakalar. İzleyici daha sonra işlemleri izleme için Application Insights'a gönderir.

Bu kod langchain-azure-ai paketini kullanır. Çözümünüzün kullandığı programlama diline ve çerçeveye bağlı olarak OpenTelemetry ile belirli çözümleri izleme yönergeleri için bkz. Dil API'leri ve SDK'ları.

pip install -U langchain-azure-ai[opentelemetry]

Ardından, aracınızı yapılandırın:

from langchain.agents import create_agent
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

application_insights_connection_string = 'InstrumentationKey="12345678...'

tracer = AzureAIOpenTelemetryTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.1",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
).with_config({ "callbacks": [tracer] })

Beklenen çıkış: Aracı, OpenTelemetry izlemelerini Application Insights'a otomatik olarak yayarken normal şekilde çalışır. İzlemeler işlem adlarını, süreleri, model çağrılarını, araç çağrılarını ve belirteç kullanımını içerir. Bu izlemeleri Dökümhane portalındaki İzlemeler bölümünde görüntüleyebilirsiniz.

Tavsiye

connection string APPLICATIONINSIGHTS_CONNECTION_STRING ortam değişkenini kullanarak Application Insights'a geçirebilirsiniz.

Enstrüman platformu çözümleri

Aracınız OpenTelemetry'yi destekleyen ancak Application Insights'ı desteklemeyen bir platform çözümünde çalışıyorsa, openTelemetry toplayıcısını dağıtın ve yazılımınızı OTLP verilerini toplayıcıya gönderecek şekilde yapılandırın (standart OpenTelemetry yapılandırması).

Verileri Application Insights'a iletmek için bağlantı dizesi kullanarak toplayıcıyı Azure Monitor dışa aktarımcısı ile yapılandırın. Uygulama hakkında ayrıntılı bilgi için bkz. Configure Azure Monitor OpenTelemetry.

İzleme sorunlarını giderme

İzlemeleri görmüyorsanız aşağıdaki öğeleri denetleyin:

• Aracınızı kaydettirdiğiniz proje, Application Insights ile yapılandırılmıştır. Application Insights'ı özel aracıyı kaydettikten sonra yapılandırdıysanız aracının kaydını kaldırıp yeniden kaydetmeniz gerekir. Application Insights yapılandırması, kayıt sonrasında değiştirdiyseniz otomatik olarak güncelleştirilmez.
• Aracıyı (altyapısında çalışan) izleri Application Insights'a gönderecek şekilde yapılandırdınız ve sizin projenizde kullandığınız aynı Application Insights kaynağını kullanıyorsunuz.
• Araçlar, üretici yapay zeka için OpenTelemetry semantik kurallarına uyar.
• İzlemeler, operation="create_agent" ve gen_ai.agents.id="<agent-id>" (veya gen_ai.agents.name="<agent-id>") özniteliklerini içeren span'ları içerir. İkinci öznitelikte, "<agent-id>" kayıt sırasında yapılandırdığınız OpenTelemetry Aracısı Kimliği değeridir.

İlgili içerik

• Microsoft Foundry Denetim Düzlemi nedir?
• Filo genelindeki aracıların sağlığını ve performansını izleyin
• Model maliyetini ve performansını iyileştirme