Agent Framework ile AG-UI Tümleştirmesi

AG-UI , gerçek zamanlı akış, durum yönetimi ve etkileşimli ui bileşenleri gibi gelişmiş özelliklere sahip web tabanlı yapay zeka aracısı uygulamaları oluşturmanıza olanak tanıyan bir protokoldür. Agent Framework AG-UI tümleştirmesi aracılarınız ve web istemcileriniz arasında sorunsuz bağlantı sağlar.

AG-UI nedir?

AG-UI, aşağıdakiler sağlayan yapay zeka aracısı arabirimleri oluşturmaya yönelik standartlaştırılmış bir protokoldür:

  • Uzak Aracı Barındırma: Yapay zeka aracılarını birden çok istemci tarafından erişilebilen web hizmetleri olarak dağıtma
  • Gerçek Zamanlı Akış: Anında geri bildirim için Sunucu Tarafından Gönderilen Olaylar (SSE) kullanarak aracı yanıtlarını akış halinde iletme
  • Standartlaştırılmış İletişim: Güvenilir aracı etkileşimleri için tutarlı ileti biçimi
  • Oturum Yönetimi: Birden çok istek arasında konuşma bağlamını muhafaza etmek
  • Gelişmiş Özellikler: İnsanlı süreç onayları, durum eşitlemesi ve özel UI oluşturma

AG-UI Ne Zaman Kullanılır?

Aşağıdaki durumlarda AG-UI kullanmayı göz önünde bulundurun:

  • Yapay zeka aracılarıyla etkileşim kuran web veya mobil uygulamalar oluşturma
  • Aracıları birden çok eşzamanlı kullanıcı tarafından erişilebilen hizmetler olarak dağıtma
  • Anında kullanıcı geri bildirimi sağlamak için aracı yanıtlarını gerçek zamanlı olarak akışla aktarın
  • Kullanıcıların yürütmeden önce eylemleri onayladığı onay iş akışlarını uygulama
  • Etkileşimli deneyimler için istemci ile sunucu arasındaki durumu eşitleme
  • Aracı araç çağrılarına göre özel kullanıcı arayüzü bileşenlerini oluşturma

AG-UI senaryoları

AG-UI yedi örnek senaryo tanımlar. MAF desteği SDK'ya göre değişir; geçerli destek düzeyi ve uygulama kılavuzu için bu sayfadaki dile özgü bölümü kullanın.

  1. Ajan Temelli Sohbet: Otomatik araç çağırma ile temel akışlı sohbet
  2. Arka Uç Araçlarının İşlenmesi: Araçlar arka uçta çalıştırılır ve sonuçlar istemciye iletilir.
  3. Döngüdeki İnsan: Kullanıcı onayı için işlev onayı istekleri
  4. Aracı Üretici Kullanıcı Arayüzü: İlerleme bilgileriyle uzun süre çalışan işlemler için asenkron araçlar
  5. Araç Tabanlı Oluşturucu Kullanıcı Arabirimi: Araç çağrılarına göre işlenen özel UI bileşenleri
  6. Paylaşılan Durum: İstemci ve sunucu arasında çift yönlü durum eşitlemesi
  7. Tahmine Dayalı Durum Güncelleştirmeleri: İyimser durum güncellemeleri olarak akış aracı değişkenlerini aktarın

CopilotKit ile ajan kullanıcı arayüzleri geliştirme

CopilotKit , standart AG-UI protokolüne göre aracı kullanıcı arabirimleri oluşturmak için zengin ui bileşenleri sağlar. CopilotKit; akış sohbet arabirimlerini, ön uç ve arka uç aracı çağrılarını, döngüdeki insan etkileşimlerini, üretken kullanıcı arabirimini, paylaşılan durumu ve çok daha fazlasını destekler. CopilotKit'in desteklediği çeşitli aracı kullanıcı arabirimi senaryolarının örneklerini AG-UI Dojo örnek uygulamasında görebilirsiniz.

Bir CopilotKit React ön ucunu bir Agent Framework AG-UI arka ucuna bağlamak için, uç noktanızı CopilotKit çalışma zamanı içinde bir HttpAgent olarak kaydedin. Bu, CopilotKit'in ön uç araçlarının AG-UI istemci araçları olarak akmasını sağlar ve tüm AG-UI özellikleri (akış, onaylar, durum eşitleme) otomatik olarak çalışır.

CopilotKit, tekerleği yeniden keşfetmeden şık bir kullanıcı deneyimi sunmanızı sağlarken temsilcinizin yeteneklerine odaklanmanıza yardımcı olur. Microsoft Agent Framework ve CopilotKit kullanmaya başlama hakkında daha fazla bilgi edinmek için CopilotKit için Microsoft Agent Framework tümleştirmesi belgelerine bakın.

.NET tümleştirmesi

.NET tümleştirmesi, bir MAF'ı AIAgent AG-UI HTTP uç noktası olarak sunar. Barındırma bağdaştırıcısı, ajanın yanıt akışını AG-UI olaylarına dönüştürür; araç yürütme ve onay gibi temel ajan davranışları MAF’in bir parçası olarak kalır.

.NET tümleştirmesini kullanarak:

AG-UI istemcileri, metin, araç, onay ve durumla ilgili olayların nasıl görüntüleneceğine karar verir.

Architecture

C# barındırma paketi, sıradan bir MAF aracısının çevresine ASP.NET Core uç noktası ekler:

AG-UI client -- HTTP POST / SSE --> MapAGUIServer --> AIAgent

MapAGUIServer AG-UI isteğini MAF iletilerine uyarlar ve seçenekleri çalıştırır. Ardından aracının akış yanıtını AG-UI .NET SDK'sını kullanarak AG-UI olaylara dönüştürür.

Installation

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

Sonraki Adımlar

AG-UI kullanmaya başlama

AG-UI ve Doğrudan Aracı Kullanımı karşılaştırması

Aracı Çerçeve'nin run ve run(..., stream=True) yöntemlerini kullanarak aracıları doğrudan uygulamanızda çalıştırabilirsiniz ancak AG-UI ek özellikler sağlar:

Özellik Doğrudan Aracı Kullanımı AG-UI Tümleştirmesi
Deployment Uygulamaya eklenmiş HTTP üzerinden uzak hizmet
İstemci Erişimi Tek uygulama Birden çok istemci (web, mobil)
Streaming İşlem içi eşzamansız yineleme Server-Sent Olayları (SSE)
Durum Yönetimi Uygulama-yönetimli Çift yönlü protokol düzeyinde eşitleme
İş Parçacığı Bağlamı Uygulama-yönetimli Protokol tarafından yönetilen iş parçacığı kimlikleri
Onay İş Akışları Özel uygulama Yerleşik protokol desteği

Mimariye Genel Bakış

AG-UI tümleştirmesi temiz, modüler bir mimari kullanır:

┌─────────────────┐
│  Web Client     │
│  (Browser/App)  │
└────────┬────────┘
         │ HTTP POST + SSE
         ▼
┌─────────────────────────┐
│  FastAPI Endpoint       │
│  (add_agent_framework_  │
│   fastapi_endpoint)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  AgentFrameworkAgent    │
│  (Protocol Wrapper)     │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Orchestrators          │
│  (Execution Flow Logic) │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Agent              │
│  (Agent Framework)      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│  Chat Client            │
│  (Azure OpenAI, etc.)   │
└─────────────────────────┘

Temel Bileşenler

  • FastAPI Uç Noktası: SSE akışını, yapılandırılabilir keep-alive yorumlarını ve istek yönlendirmesini işleyen HTTP uç noktası
  • AgentFrameworkAgent: Agent Framework aracılarını AG-UI protokole uyarlayan basit sarmalayıcı
  • Düzenleyiciler: Farklı yürütme akışlarını işleme (varsayılan, döngüde insan, durum yönetimi)
  • Olay Köprüsü: Agent Framework olaylarını AG-UI protokol olaylarına dönüştürür
  • İleti Bağdaştırıcıları: AG-UI ve Aracı Çerçevesi ileti biçimleri arasında çift yönlü dönüştürme
  • Onay Stratejileri: Etki alanına özgü onay iletileri için genişletilebilir stratejiler

Agent Framework'ın AG-UI'ye Dönüşümü

Agent Framework kavramlarının AG-UI nasıl eşlenir anlamak etkili tümleştirmeler oluşturmanıza yardımcı olur:

Ajan Çerçevesi Kavramı AG-UI Eşdeğeri Açıklama
Agent Aracı Uç Noktası Her bir araç bir HTTP uç noktası olur
agent.run() HTTP POST İsteği İstemci HTTP aracılığıyla ileti gönderir
agent.run(..., stream=True) Sunucu Tarafından Gönderilen Olaylar Yanıtları SSE aracılığıyla akışla aktarma
Aracı yanıt güncelleştirmeleri AG-UI Olayları TEXT_MESSAGE_CONTENT, TOOL_CALL_STARTvb.
İşlev araçları (@tool) Arka Uç Araçları Sunucuda yürütüldü, sonuçlar istemciye akışla aktarıldı
Araç onay modu İnsanın Döngü İçine Entegre Edilmesi Protokol aracılığıyla onay istekleri/yanıtları
Konuşma geçmişi Thread Yönetimi threadId istekler arasında bağlamı korur

Installation

AG-UI tümleştirme paketini yükleyin:

pip install agent-framework-ag-ui --pre

Bu, hem temel aracı çerçevesini hem de AG-UI tümleştirme bileşenlerini yükler.

Terminal iletisi anlık görüntülerini denetleme

Varsayılan olarak, AgentFrameworkAgent tam transkripti içeren bir terminal MESSAGES_SNAPSHOT olayı yayar. Bir HistoryProvider veya uygulamanız konuşma durumunu zaten yönetiyorsa, her çalıştırmanın sonunda istemci transkriptinin yeniden yazılmasını önlemek için ayarlayın emit_messages_snapshot=False :

from agent_framework_ag_ui import AgentFrameworkAgent

wrapped_agent = AgentFrameworkAgent(
    agent=agent,
    emit_messages_snapshot=False,
)

Bu ayar yalnızca terminal iletisi anlık görüntüsünü gizler. RUN_FINISHED dahil olmak üzere diğer akış üzerinden iletilen olaylar değişmeden kalır.

Sonraki Adımlar

AG-UI tümleştirmesini kullanmaya başlamak için:

  1. Başlarken: İlk AG-UI sunucunuzu ve istemcinizi oluşturma
  2. Arka Uç Aracı İşleme: Aracılarınıza işlev araçları ekleme
  3. İş akışları: AG-UI aracılığıyla çok aracılı iş akışlarını kullanıma sunma
  4. İnsan Katılımı: Onay iş akışlarını uygulayın
  5. MCP Uygulamaları Uyumluluğu: mcp uygulamalarını AG-UI uç noktanızla kullanma
  6. Durum Yönetimi: İstemci ve sunucu arasında durumu eşitleme

Ek Kaynaklar

Go, hem sunucular hem de istemciler için provider/aguiprovider aracılığıyla AG-UI’yi destekler.

import "github.com/microsoft/agent-framework-go/provider/aguiprovider"

mux := http.NewServeMux()
mux.Handle("/", aguiprovider.NewJSONHTTPHandler(myAgent, aguiprovider.HandlerConfig{}))

if err := http.ListenAndServe(":8888", mux); err != nil {
    log.Fatal(err)
}

Tip

Tam sunucu ve istemci örnekleri içinAG-UI Go örneklerine bakın.

  • Last updated on