Kendi kendini barındıran Agent Framework uygulamaları

Kendi kendine barındırma, kendi ASP.NET Core uygulamanızda, kapsayıcınızda, hizmetinizde veya çalışma zamanında bir Agent Framework aracısı veya iş akışı çalıştırmanıza olanak tanır. Uygulamanız yönlendirmeyi, kimliği, yetkilendirmeyi, istek ilkesini, depolamayı, dağıtımı ve ölçeklendirmeyi denetler. Desteklemeniz gereken istemcileri temel alarak konağa protokol tümleştirmeleri ekleyin.

Aracı uç noktasını mevcut uygulama altyapınızla tümleştirmeniz gerektiğinde bu seçeneği kullanın. Microsoft Foundry'nin aracıyı sizin için çalıştırmasını istiyorsanız bkz. Foundry Barındırılan Aracılar. Azure İşlevleri tetikleyicilerine veya kalıcı yürütmeye ihtiyacınız varsa Durable Extension'a bakın.

Önemli

.NET barındırma paketleri yayın öncesidir. Üretim dağıtımını güncelleştirmeden önce yayın öncesi sürümleri açıkça yükleyin ve sürüm notlarını gözden geçirin.

dotnet add package Microsoft.Agents.AI.Hosting --prerelease

Barındırma yardımcıları ne sağlar?

Paket, Microsoft.Agents.AI.Hosting aracıları ve iş akışlarını .NET genel ana bilgisayarla tümleştirir:

• AddAIAgent, bağımlılık enjeksiyonu ile adlandırılmış bir AIAgent kaydeder.
• AddWorkflow adlandırılmış bir iş akışını kaydeder. İş akışını standart aracı arayüzü üzerinden protokol entegrasyonlarına sunmak için AddAsAIAgent zincirleyin.
• IHostedAgentBuilder bu aracıyla ilişkili barındırma hizmetlerini yapılandırıyor.
• AgentSessionStore isteğe bağlı olarak bir uygulama veya protokol tarafından sağlanan devamlılık kimliğiyle örnekleri yükler ve kaydeder AgentSession .

Barındırma paketi bir HTTP sunucusu veya protokol kayıt defteri değildir. Uygulamanız barındırılan aracıları ve iş akışlarını seçer, hizmetlerini yapılandırıp ihtiyaç duyduğu protokol uç noktalarını ekler.

ASP.NET Core ile tümleştirmek

Paylaşılan barındırma paketi, .NET genel konağı ve bağımlılık eklemesini kullanır. HTTP sunucusu için bir ASP.NET Core uygulaması oluşturun ve kullanıma açmak istediğiniz uç noktalar için protokole özgü paketleri ekleyin. Bu paketler, bağımlılık enjeksiyonundan adlandırılmış AIAgent örneklerini çözümler ve ASP.NET Core rota eşlemeleri ekler.

Örneğin, OpenAI barındırma paketi, yapılandırılmış bir aracıyı Yanıtlar uç noktası aracılığıyla kullanıma sunabilir:

dotnet add package Microsoft.Agents.AI.Hosting.OpenAI --prerelease

using Microsoft.Agents.AI.Hosting;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

WebApplication app = builder.Build();
app.MapOpenAIResponses(hostedAgent);
app.Run();

Tam yapılandırma için bkz. OpenAI uyumlu uç noktalar .

Uygulamanız ara yazılım işlem hattından, kimlik doğrulamasından, yetkilendirmeden, istek doğrulamadan, izin verilen model seçeneklerinden ve dayanıklı depolamadan sorumludur. HTTP olmayan bir konak, ASP.NET Core protokol uç noktaları eklemeden paylaşılan barındırma hizmetlerini kullanabilir.

Sunucunuza protokol ekleme

Uygulamanızın ihtiyaç duyduğu protokol tümleştirmelerini seçin:

Protocol	Integration
OpenAI uyumlu uç noktalar	Sohbet Tamamlamaları ve Yanıtlarla uyumlu HTTP uç noktaları
A2A	Ajanlar arası keşif, mesajlaşma ve görev uç noktaları
AG-UI	Web aracısı uygulamaları için olay akışı uç noktaları

Barındırılan oturumları kalıcı hale getir

AgentSessionStore kalıcılık, bunu kullanan barındırma tümleştirmeleri için isteğe bağlıdır. Yapılandırılmış bir depo olmadan, bu tümleştirmeler her istek için yeni bir oturum oluşturabilir, ancak önceki bir istekten sunucuya ait oturum durumunu kurtaramaz.

Önemli

MAF genel amaçlı dayanıklı bir oturum deposu içermez. Üretim ortamı için, uygulamanıza uygun bir depolama altyapısıyla desteklenen bir AgentSessionStore gerçeklemesi sağlayın.

Durable uygulamanızı bağımlılık enjeksiyonu ile kaydedin ve bunu barındırılan aracıya verin. Geliştirme sırasında bellek içi depoyu koşullu olarak kullanabilirsiniz:

builder.Services.AddSingleton<AgentSessionStore, MyAgentSessionStore>();

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

if (builder.Environment.IsDevelopment())
{
    hostedAgent.WithInMemorySessionStore(withIsolation: false);
}
else
{
    hostedAgent.WithSessionStore((services, _) =>
        services.GetRequiredService<AgentSessionStore>());
}

Bu örnekte, MyAgentSessionStore uygulamanızın sağladığı dayanıklı gerçek­lemedir. Geliştirme dalı, tek bir güvenilen kullanıcıya sahip yerel bir ortam olduğunu varsayar ve yalıtımı devre dışı bırakabilen tek yoldur. Üretim dalı varsayılan yalıtım davranışını korur; Bir yalıtım anahtarı sağlayıcısını Güvenli oturum devamı bölümünde açıklandığı gibi yapılandırın.

InMemoryAgentSessionStore işlemden çıkıldığında ve uygulama örnekleri arasında durum paylaşmadığında tüm oturumları kaybeder. Oturumların korunmasını sağlamak için kalıcı depolama kullanan kendi AgentSessionStore çözümünüzü uygulayın.

AgentSessionStore, zaman uyumsuz kaydetme, alma ve silme işlemlerini gerçekleştirir. Ait olduğu AIAgent ile, barındırma tümleştirmesi veya uygulamaya ait bir rota tarafından seçilen opak bir devamlılık kimliğini alır ve her get işleminde bağımsız bir AgentSession örneği döndürmelidir. Devamlılık kimliğini özel depolama alanlarında opak bir anahtar olarak ele alın; kimliğin nasıl yorumlandığı protokole özgüdür.

Dayanıklı bir uygulama aşağıdaki yapıya sahiptir. Her saptamayı seçtiğiniz depolama sistemi işlemleriyle değiştirin:

public sealed class MyAgentSessionStore : AgentSessionStore
{
    public override ValueTask SaveSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        AgentSession session,
        CancellationToken cancellationToken = default)
    {
        // Persist the session using your storage system.
        throw new NotImplementedException();
    }

    public override ValueTask<AgentSession> GetSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Restore an independent session, or create one when no state exists.
        throw new NotImplementedException();
    }

    public override ValueTask DeleteSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Delete the stored session if it exists.
        throw new NotImplementedException();
    }
}

Hem agent.Id hem de opak sessionStoreId tarafından anahtarlanan kayıtlar. GetSessionAsync her çağrıda bağımsız bir oturum örneği döndürmelidir; serileştirilmiş durumu depolarken sahibi olan aracının oturum serileştirme API'lerini kullanın. Kalıcı oturumlar hassas veriler içerebilir, bu nedenle bunları uygun erişim denetimleri ve şifreleme ile koruyun.

AgentSessionStore, yalnızca konuşma mesajlarını değil, barındırılan bir isteğin seçtiği AgentSession öğesinin tamamını kalıcı olarak saklar. Ajan yığınına bağlı olarak, bir oturum hizmetin yönettiği bir konuşma kimliği, çerçevenin yönettiği sohbet geçmişi, bellek ya da bağlam sağlayıcısının durumu, kuyruğa alınmış iletiler, bekleyen onaylar ve çalıştırmalar arasında korunması gereken diğer durumları içerebilir.

Geçmiş sağlayıcıları konuşma iletilerinin nerede depolandığını denetler. Geçmiş oturum durumu içinde tutulduğunda, oturumu kalıcı hale getirmek bu geçmişi de kalıcı hale getirir. Harici bir geçmiş sağlayıcısı iletileri ayrı olarak depolar; oturum bir referansı veya ilgili sağlayıcı durumunu saklayabilir.

Güvenli oturum devamı

Devam kimliği, devam ettirilecek bir oturumu tanımlar; ancak çağrı yapanın o oturumun sahibi olduğunu kanıtlamaz. İstemci tarafından sağlanan kimlikleri kabul etmeden önce, kalıcı oturumları kimliği doğrulanmış bir kullanıcı, kiracı veya başka bir yetkilendirme sınırıyla sınırlayın. IsolationKeyScopedAgentSessionStore, AgentIsolationKeyProvider bir yalıtım anahtarı alır, bunu protokol sürdürme kimliğiyle birleştirir ve ortaya çıkan kapsamlandırılmış kimliği altyapıdaki depoya iletir. Sonuç olarak, iki farklı yalıtım anahtarı altında aynı devamlılık kimliği, depolanmış iki farklı oturuma karşılık gelir ve bir çağıran taraf yalnızca kendi yalıtım anahtarıyla kaydedilmiş oturumları alabilir.

Talep tabanlı kimlik doğrulaması kullanan ASP.NET Core uygulamalar için ön sürüm Microsoft.Agents.AI.Hosting.AspNetCore paketini yükleyin, talep tabanlı yalıtım sağlayıcısını kaydedin ve oturum deposunda yalıtımı etkin tutun:

dotnet add package Microsoft.Agents.AI.Hosting.AspNetCore --prerelease

builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();

Varsayılan olarak, UseClaimsBasedAgentIsolation, ClaimTypes.NameIdentifier claim’ini kullanır. Başka bir talebi yalnızca mağaza tarafından sunulan her arayan arasında kararlı ve benzersiz olduğunda yapılandırın. Yalıtım sağlayıcısı isteklerin kimliğini doğrulamaz; ASP.NET Core kimlik doğrulama ve yetkilendirmeyi ayrı ayrı yapılandırın. Varsayılan katı yalıtım davranışıyla, geçerli sorumlu yapılandırılmış talebi sağlamadığında oturum erişimi başarısız olur.

HTTP olmayan bir ana bilgisayar veya başka bir kiralama modeli için özel bir AgentIsolationKeyProvider kaydedin. Varsayılan WithInMemorySessionStore() ve WithSessionStore(...) aşırı yüklemeleri, yapılandırılmış depoyu IsolationKeyScopedAgentSessionStore içine sarar.

Sonraki Adımlar

OpenAI uyumlu uç nokta ekleme

Daha derine gidin:

• A2A ile ajanları barındırın
• AG-UI ile web aracısı uygulamaları oluşturma
• Foundry Barındırılan Aracılar

Uyarı

Kendi barındırmalı protokol yardımcıları şu anda Go için mevcut değil.

Kendi kendine barındırma, kendi web uygulamanızda, kapsayıcınızda, hizmetinizde veya çalışma zamanınızda bir Agent Framework aracısı veya iş akışı çalıştırmanıza olanak tanır. Uygulamanız yönlendirmeyi, kimliği, yetkilendirmeyi, istek ilkesini, depolamayı, dağıtımı ve ölçeklendirmeyi denetler. Desteklemeniz gereken istemcileri temel alarak bu sunucuya bir veya daha fazla protokol tümleştirmesi ekleyin.

Aracı uç noktasını mevcut uygulama altyapınızla tümleştirmeniz gerektiğinde bu seçeneği kullanın. Microsoft Foundry'nin aracıyı sizin için çalıştırmasını istiyorsanız bkz. Foundry Barındırılan Aracılar. Azure İşlevleri tetikleyicilerine veya kalıcı yürütmeye ihtiyacınız varsa Durable Extension'a bakın.

Bu paketlerin tasarımı, geliştirici için maksimum esneklik sağlayan şekilde tasarlanmıştır. Bu, Responses API ile bir aracıyı sunan bir ana bilgisayar oluşturmak ve parametreleri başka amaçlar için kötüye kullanmak istiyorsanız (yani temperature öğesini top_p öğesine eşlemek), bunu yapabileceğiniz anlamına gelir. Oturumları depolamak istemiyorsanız bunu yapabilirsiniz; çağıran tarafın aracının tüm çalıştırma sürecini kontrol etmesine izin vermek istiyorsanız, bunu da yapabilirsiniz. Önünüze engel çıkarmayacağız; yaygın kullanım senaryoları için yardımcı araçlar sunuyor, geri kalanını ise tam olarak ihtiyaç duyduğunuz host’u oluşturabilmeniz için size bırakıyoruz.

Önemli

agent-framework-hosting, agent-framework-hosting-responses, agent-framework-hosting-telegram, agent-framework-a2a, , agent-framework-hosting-a2ave agent-framework-hosting-mcp ön sürüm Python paketleridir. Üretim dağıtımını güncelleştirmeden önce yayın öncesi sürümleri açıkça yükleyin ve sürüm notlarını gözden geçirin.

pip install --pre agent-framework-hosting

Barındırma yardımcıları ne sağlar?

Genel barındırma paketi, uygulamaya ait bir sunucu için paylaşılan yürütme durumu sağlar:

• AgentState bir aracı hedefini ile SessionStore eşleştirip uygulama yeni bir anahtar seçtiğinde oturumlar oluşturur.
• SessionStore uygulama tarafından seçilen bir kimliğe göre oturumları depolar, alır ve siler. Varsayılan deposu işleme özeldir ve bir tahliye politikası yoktur.
• WorkflowState iş akışı hedeflerini çözümler. Uygulamanız, denetim noktası depolamasından ve bir istemci devam kimliğini denetim noktasına eşleyen tüm eşlemelerden sorumludur.

AgentState bir sunucu veya protokol kayıt defteri değildir. Uygulamanız yetkili bir oturum anahtarı seçer, hedefi çözümler ve çalıştırma sonrası durumunu kaydeder. Bir veya birden çok protokol uç noktası için aynı hedef ve paylaşılan uygulama altyapısını kullanabilir.

Oturum depolama alanını özelleştirme

SessionStore, getve set yöntemleriyle deleteküçük bir zaman uyumsuz depolama sınıfıdır. Varsayılan uygulama oturumları işlem belleğinde tutar. Nesneleri Redis' te, bir veritabanında, blob depolama alanında veya uygulamaya ait başka bir depoda depolamak AgentSession için bu yöntemleri alt sınıflayın ve geçersiz kılın, ardından örneği öğesine AgentState(session_store=...)geçirin.

SessionStore ve geçmiş sağlayıcıları, bir ajan konuşmasının ayrı bölümlerini kalıcı olarak saklar. Oturum deposu, oturum meta verileri ve sağlayıcı durumu dahil olmak üzere oturum kimliği başına bir oturum nesnesi kaydeder. Ayrı bir HistoryProvider, konuşmayı genellikle ileti başına bir kayıt olacak şekilde ayrı depolar. Ayrı iletiler eklemek, her adımın ardından giderek büyüyen bir oturum nesnesini yeniden yazmaktan genellikle daha verimli olduğundan, bu ayrım kalıcı ana bilgisayarlar için önerilir. Her aracı için, istenen geçmiş sağlayıcısı sınıfı context_providers parametresine geçirilerek bir geçmiş sağlayıcısı tanımlanır.

Uyarı

Varsayılan geçmiş sağlayıcısı: InMemoryHistoryProvider özel durumdur: konuşmanın tamamını içinde AgentSession.statedepolar. Bu sağlayıcı kullanıldığında, SessionStore konuşma oturum nesnesinin içinde kalır. Daha uzun konuşmalar veya üretim ortamında depolama için, oturum deposunun hafif oturum durumuna odaklı kalabilmesi amacıyla özel bir geçmiş sağlayıcısı kullanın.

Kendi çerçevenizi veya istemci kitaplığınızı getirme

Barındırma paketleri bir web çerçevesine veya istemci kitaplığına bağlı değildir. Örnekler, yardımcıların bunları gerektirmesinden değil, kısa ve çalıştırılabilir örnekler sunmaları nedeniyle FastAPI ve aiogram kullanır.

• HTTP uç noktaları için FastAPI, Starlette, Django, Flask, Azure İşlevleri veya başka bir çerçeve gibi uygulama çerçevenizin yönlendirme ve istek/yanıt API'lerini kullanın.
• Telegram gibi protokol istemcileri için bir protokol güncelleştirmesi sağlayabilen ve yardımcı tarafından üretilen işlemleri yürütebilen herhangi bir istemci kitaplığını kullanın.

Uygulama çerçevesini ve istemci kitaplığını seçer; Agent Framework paketleri yalnızca protokol verilerini dönüştürür ve isteğe bağlı yürütme durumunu yönetir. Yolları kaydetmez, arayanların kimliğini doğrulamaz, duruma erişimi yetkilendirmez, izin verilen model seçeneklerini belirlemez veya dayanıklı depolama sağlamaz.

Sunucunuza protokol ekleme

Bir veya daha fazla protokol tümleştirmesi seçin:

Protocol	Paket ve tümleştirme
OpenAI Yanıtları	agent-framework-hosting-responses
Telgraf	agent-framework-hosting-telegram
A2A	agent-framework-a2a veya agent-framework-hosting-a2a
MCP	agent-framework-hosting-mcp

Her protokol sayfası, kurulumunu açıklar. Ancak, bir veya daha fazla protokolün etkinleştirildiği ve çağrılabilir bir hedefe sahip tek bir ana makine oluşturmanıza olanak verecek şekilde tasarlanmıştır; yani bir aracı ya da iş akışı. Sizi tek bir web çerçevesiyle sınırlamadığımız için istediğiniz web çerçevesini seçebilir ve konağı bu protokollerle kolayca ayarlayabilirsiniz.

Güvenli oturum devamı

Protokol tarafından sağlanan her tanımlayıcıya güvenilmeyen girdi olarak davranın. Oturum, denetim noktası, görev veya başka bir durumu yüklemek için kimlik kullanmadan önce:

1. Çağıranın kimliğini doğrula.
2. Çağıranın başvurulan duruma erişmesine izin verin.
3. Kalıcı durumu kimliği doğrulanmış kiracı, kullanıcı veya çalışma alanına göre bölümlendirin.
4. Oturum ve denetim noktası durumunu yalnızca çalıştırma veya akış tamamlandıktan sonra kalıcı hale getirin.

Bu kendi kendine barındırma düzeni, uygulamanızın yalnızca ihtiyaç duyduğu protokol uç noktalarını ve ilkelerini uygulamasına olanak tanır; desteklenen her protokolün tam API yüzeyini uygulamayı denemez.

Sonraki Adımlar

OpenAI Yanıtları protokolunu ekleme

Daha derine gidin:

• Telgraf
• A2A
• MCP
• Foundry Barındırılan Aracılar