Microsoft Agent Framework: AG-UI, Bellek ve Dayanıklılık
Soruya yanıt veren ajan başlangıç noktası. İş bitiren bir ajanın kullanıcının etkileşime girebileceği bir arayüzü, mevcut konuşmanın ötesine geçen bir belleği, kod çalıştıracak uygun bir ortamı ve iş yarıda kesildiğinde toparlanma yolu olması gerekiyor. Microsoft Agent Framework’ün son güncellemeleri bu dört ihtiyacı.NET ve Python tarafında birlikte ele alıyor; ajanı uygulamaya bağlamaktan uzun ömürlü iş akışlarını kurtarmaya kadar uzanan yetenekler aşağıdaki örneklerde tek tek kullanılıyor.
Önce ortam hazırlığı
az login ile oturum açın. FOUNDRY_PROJECT_ENDPOINT değişkenine Foundry proje uç noktanızı, FOUNDRY_MODEL değişkenine dağıtılmış model adınızı verin.
Python tarafında AG-UI ve bellek örnekleri için gerekli paketler:
pip install --pre agent-framework-foundry agent-framework-ag-ui azure-identity aiohttp fastapi uvicornCodeAct örneği için, desteklenen bir platformda Hyperlight entegrasyonunu da kurmanız gerekiyor:
pip install --pre agent-framework-hyperlightBellek örneğinde FOUNDRY_MEMORY_STORE_NAME değişkeni, desteklenen sohbet ve gömme (embedding) model dağıtımlarıyla yapılandırılmış mevcut bir Foundry bellek deposuna işaret etmeli.
.NET tarafında yeni bir Blazor projesi ve bağımlılıklar:
dotnet new blazor -n FoundryAgUi
cd FoundryAgUi
dotnet add package Azure.Identity
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Microsoft.Agents.AI.Foundry --prerelease
dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prereleaseAG-UI ile ajanı etkileşimli arayüze bağlamak
İyi bir ajan arayüzü nihai yanıtı göstermekle yetinmez. Kullanıcı ilerlemeyi görmek, araç etkinliğini anlamak, eylemleri onaylamak ve çıkan sonuçla etkileşime girmek ister; AG-UI da bu etkileşim için olay tabanlı, açık bir protokol sunuyor. Microsoft Agent Framework entegrasyonu sayesinde ajanınızı bir AG-UI uç noktası üzerinden yayımlayabilir, uyumlu ön yüzlere bağlayabilirsiniz. CopilotKit ile geliştirilen uygulamalar bunlardan biri,.NET tarafında ajan arayüzleri kurmaya yarayan yeni Blazor AI bileşenleri de bir diğeri.
Python: FastAPI üzerinden yayımlama (kararlı sürüm)
Aşağıdaki dosyayı app.py olarak kaydedip uvicorn app:app --reload ile çalıştırabilirsiniz:
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI
from agent_framework import Agent
from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential
credential = AzureCliCredential()
agent = Agent(
client=FoundryChatClient(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
model=os.environ["FOUNDRY_MODEL"],
credential=credential,
),
name="ResearchAssistant",
instructions="Help users research topics and explain your findings.",
)
@asynccontextmanager
async def lifespan(app: FastAPI):
async with credential, agent:
yield
app = FastAPI(lifespan=lifespan)
add_agent_framework_fastapi_endpoint(app, agent, "/ag-ui")Entegrasyon, ajan yürütmesini akış halindeki yanıtlar, araç etkinliği ve desteklenen diğer etkileşimler için AG-UI olaylarına çeviriyor. Python tarafındaki son çalışmalar sohbetin ötesine geçiyor; iş akışı checkpoint’i ve kaldığı yerden devam, onay sürekliliğinde iyileştirme, paylaşılan ve öngörücü durum güncellemeleri, ajan tarafından üretilen arayüzler için isteğe bağlı A2UI entegrasyonu bunların arasında.
.NET: ASP.NET Core üzerinden Foundry bağlantılı ajan (public preview)
Bu örnek, Python örneğiyle aynı Foundry yapılandırmasını, ajan adını, yönergeleri ve /ag-ui uç noktasını kullanıyor. Program.cs dosyasını aşağıdakiyle değiştirip dotnet run diyebilirsiniz:
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAGUIServer();
AIAgent agent = new AIProjectClient(
new Uri(endpoint), new AzureCliCredential())
.AsAIAgent(
model: model,
name: "ResearchAssistant",
instructions: "Help users research topics and explain your findings.");
var app = builder.Build();
app.MapAGUIServer("/ag-ui", agent);
await app.RunAsync();Güncellenen.NET desteği, AG-UI olayları için soyutlamalar ile Microsoft.Extensions.AI tabanlı istemci/sunucu desteği sağlayan yeni AG-UI.NET SDK’sını kullanıyor..NET hosting entegrasyonu hala preview aşamasında. Her iki dil de etkileşimli ajan deneyimlerini destekliyor ama yetenekler birebir aynı değil, o yüzden özellik eşitliği varsaymak yerine kendi dilinizin örneklerine bakın.
Bu minimal uç noktalar üretime çıkmadan önce uygulama güvenliği gerektiriyor: çağıranı kimlik doğrulamadan geçirin, oturumlarına erişimi yetkilendirin. Bir thread kimliği yalnızca konuşmayı tanımlar, o konuşmaya kimin erişebileceğini belirlemez.
Aynı ajan mantığını farklı kanallarda kullanmak
AG-UI ajanı etkileşimli ön yüzlere bağlar. Yeni Python agent ve workflow channels paketleri ise başka bir entegrasyon problemini çözüyor, aynı ajan mantığını farklı protokoller ve yüzeyler üzerinden sunmayı. Paketler OpenAI Responses, Telegram, A2A ve MCP için yardımcılar içeriyor; bunların amaçları da ayrı ayrı: kullanıcılarla mesajlaşmak, API istemcilerine hizmet vermek, başka ajanlarla iletişim kurmak, yetenekleri araç olarak dışa açmak.
Paylaşılan oturum yardımcıları, ajana bakan kodu küçük tutuyor. Örneğin bir async fonksiyon içinde:
from agent_framework_hosting import AgentState
state = AgentState(agent)
session = await state.get_or_create_session("demo-session")
result = await agent.run(
"Summarize the research we have collected.",
session=session,
)
await state.set_session("demo-session", session)
print(result.text)Kanal kimliği ile yetkilendirilmiş oturum arasındaki eşleme, depolama ve eşzamanlılık politikası sizin uygulamanızın sorumluluğunda. Yukarıdaki sabit oturum kimliği yerel bir gösterim, üretim kimlik stratejisi değil. Bu ayrım sayesinde ajan mantığını yeniden kullanırken yönlendirme, kimlik doğrulama ve kalıcılık üzerindeki kontrolü bırakmış olmuyorsunuz.
Context provider ile bellek eklemek
Konuşma geçmişi söylenenleri saklar. Uzun vadeli bellek ise ajanın yeni bir konuşmaya, tüm dökümü yeniden oynatmadan işe yarar bilgiyi taşımasını sağlar. Foundry Agent Service içindeki bellek, Microsoft Agent Framework ile FoundryMemoryProvider üzerinden entegre oluyor; çalıştırmadan önce ilgili anıları getiriyor, sonrasında da asenkron bellek çıkarımı için konuşma bilgisini gönderiyor.
Aşağıdaki Python örneği hem model çıkarımını hem belleği Foundry projenize bağlıyor. Dosyayı memory_demo.py olarak kaydedin:
import argparse
import asyncio
import os
from agent_framework import Agent, InMemoryHistoryProvider
from agent_framework.foundry import FoundryChatClient, FoundryMemoryProvider
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential
async def main(message: str) -> None:
async with (
AzureCliCredential() as credential,
AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
allow_preview=True,
) as project_client,
):
memory = FoundryMemoryProvider(
project_client=project_client,
memory_store_name=os.environ["FOUNDRY_MEMORY_STORE_NAME"],
scope="demo-user",
update_delay=0,
)
async with Agent(
client=FoundryChatClient(
project_client=project_client,
model=os.environ["FOUNDRY_MODEL"],
),
instructions="Use relevant remembered preferences when helping the user.",
context_providers=[
memory,
InMemoryHistoryProvider(load_messages=False),
],
default_options={"store": False},
) as agent:
response = await agent.run(
message, session=agent.create_session()
)
print(response.text)
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("message")
asyncio.run(main(parser.parse_args().message))Önce bir tercih kaydedin:
python memory_demo.py "For project updates, I prefer a short summary followed by action items."Bellek çıkarımı tamamlandıktan sonra, ayrı bir süreçte aynı tercihi sorun:
python memory_demo.py "How should you format my next project update?"Her çağrı, aynı bellek kapsamıyla (scope) taze bir oturum oluşturur. Servis tarafındaki yanıt saklama ve yerel döküm yükleme devre dışı bırakıldığı için ikinci çağrı ilk konuşmayı tekrar oynatmaz. Bellek çıkarımı asenkron çalışır; update_delay=0 işlemeyi gruplama gecikmesi olmadan başlatır ama anında hatırlamayı garanti etmez.
Üretimde kapsamı kullanıcıdan gelen rastgele bir tanımlayıcı yerine kimliği doğrulanmış uygulama kimliğinden türetin. Üretime uygun bir credential kullanın, bellek saklama ve silme politikalarınızı uygulayın, hatırlama kalitesini de değerlendirin. Alternatif olarak, hibrit vektör ve tam metin getirme sunan Python-preview CosmosMemoryContextProvider entegrasyonuyla Azure Cosmos DB de kullanılabiliyor.
CodeAct ile çok adımlı işleri toplu yürütmek
Bazı ajan görevleri birbirine zincirlenebilen çok sayıda küçük işlemden oluşur. Her adımda modelden araç seçmesini, sonucu incelemesini, sonra yeni bir araç seçmesini istemek gereksiz gecikme ve token tüketimi yaratabilir. CodeAct, modelin uygun dizileri bir program olarak ifade etmesine ve tek bir birleşik sonuç almasına izin veriyor.
Aşağıdaki Python örneği saf hesaplama yapan bir araç ile Foundry bağlantılı bir model istemcisi kullanıyor. codeact_demo.py olarak kaydedip python codeact_demo.py ile çalıştırın:
import asyncio
import os
from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from agent_framework_hyperlight import HyperlightCodeActProvider
from azure.identity.aio import AzureCliCredential
@tool
def line_total(unit_price_cents: int, quantity: int) -> int:
"""Calculate a line total in cents."""
return unit_price_cents * quantity
async def main() -> None:
async with AzureCliCredential() as credential:
codeact = HyperlightCodeActProvider(
tools=[line_total],
approval_mode="never_require",
)
async with Agent(
client=FoundryChatClient(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
model=os.environ["FOUNDRY_MODEL"],
credential=credential,
),
name="OrderCalculator",
instructions="Use execute_code to combine calculations when useful.",
context_providers=[codeact],
) as agent:
response = await agent.run(
"Calculate the combined total for 12 items at 250 cents each "
"and 8 items at 175 cents each."
)
print(response.text)
if __name__ == "__main__":
asyncio.run(main())HyperlightCodeActProvider yürütme aracını ve yönergeleri sağlıyor, kayıtlı araçlar da üretilen koda call_tool(...) üzerinden açılıyor. Burada izolasyon sınırına dikkat etmek gerekiyor. Hyperlight yalnızca model tarafından üretilen kodu izole eder; kayıtlı uygulama araçları sizin uygulamanızın çalışma zamanında yürütülür, yani o araçların kendi izinleri ve sorumlulukları devam eder. Bu örnekte otomatik yürütmeye izin verilmesinin nedeni, tek aracın yalnızca aritmetik yapması. Tek tek onay gerektiren eylemler ise açıkça onay kapısı arkasında kalmalı.
CodeAct incelemesi, değerlendirdiği iş yükünde yaklaşık %50 daha düşük gecikme ve %60’tan fazla daha düşük token kullanımı bildiriyor. Bunları iş yüküne özgü sonuçlar olarak değerlendirin, ödünleşimi kendi uygulamanızda ölçün.
Uzun süren işleri kurtarılabilir hale getirmek
Zaman aşımı süresini uzatmak bir ajanı dayanıklı yapmaz. Uzun süren işlerin kurtarılabilir bir yürütme durumuna, sonuçlara yeniden bağlanma yoluna ve süreç durduğunda net bir davranışa ihtiyacı var. Agent Framework’ün Foundry Agent Service içindeki hosted agent’larla entegrasyonu, iş akışı checkpoint’lerini ve ajan oturumlarını dayanıklı arka plan yanıtlarına bağlıyor.
Python: dayanıklı arka plan yürütmesi
İş akışını oluşturduktan sonra Responses host’unu yapılandırın:
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.responses import ResponsesServerOptions
workflow_agent = workflow.as_agent(name="report-workflow")
server = ResponsesHostServer(
workflow_agent,
options=ResponsesServerOptions(resilient_background=True),
)
server.run()Tam Python örneği, kurtarmanın kolayca gözlemlenebilmesi için geri sayan bir iş akışı kuruyor. Arka plan isteği gönderip sunucuyu kesintiye uğratabilir, yeniden başlatıp yanıta tekrar bağlanabilirsiniz. O örnekte istek gövdesi şöyle:
{
"input": "Count down from 20",
"background": true,
"store": true,
"stream": true
}.NET: dayanıklı Responses host’u
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Agents.AI.Workflows;
AIAgent agent = workflow.AsAIAgent(
id: "report-workflow",
name: "report-workflow",
includeWorkflowOutputsInResponse: true);
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(
agent,
configure: options => options.ResilientBackground = true);
var app = builder.Build();
app.MapFoundryResponses();
await app.RunAsync();Kurtarma sırasında host kalıcı durumu yeniden yükler, kaydedilmiş yanıtla ilişkili iş akışı checkpoint’ini seçer. Yeniden başlatılan sürecin, eşleşen iş akışı ve executor kimliklerini yeniden kurması gerekiyor.
Önemli bir sınır var: kurtarma, dış etkilerin tam olarak bir kez çalıştırılacağı anlamına gelmez. Kesilen bir adım yeniden çalışabilir. Bir araç e-posta gönderiyor, ödeme alıyor ya da başka bir servise yazıyorsa o işlemi yeniden denemelere dayanıklı tasarlayın, örneğin aşağı akışta idempotency anahtarları kullanarak.
Azure Functions tarafında ise Agent Framework için Durable uzantısı ayrı bir dayanıklı yürütme yolu sunuyor. Geliştirme döngüsü de VS Code’a doğru genişliyor; Foundry Toolkit desteğiyle geliştiriciler uzun süren bir ajanı başlatıp etkileşimden ayrılabilecek, işi baştan başlatmadan ilerlemeyi veya sonuçları incelemek üzere yeniden bağlanabilecek.
Hangisinden başlamalı?
Bu yetenekler birbirine bağımlı değil, bileşilebilir. AG-UI ile ön yüzü bağlayabilir, bellek ekleyebilir, CodeAct’i değerlendirebilir veya dayanıklı iş akışı barındırmayı benimseyebilirsiniz; her özelliği diğerinin ön koşulu saymanız gerekmiyor. En pratik yol, kendi diliniz ve yürütme ortamınıza uygun bir örnekle başlayıp oradan ilerlemek. Varılmak istenen nokta ise kullanıcıların işi takip edebildiği, geliştiricilerin de davranışını anlayabildiği, kurtarabildiği ve iyileştirebildiği bir ajan.
Kaynaklar ve İleri Okuma
- What’s new in Microsoft Agent Framework: Interactive experiences, memory, and resilient execution (Dan Taylor)
- Foundry managed semantic memory dokümanı ve.NET örnekleri
- Quickstart: Responses API ile ajan kurmak (Python)
- Python AG-UI paketi ve hızlı başlangıçlar
- AG-UI etkileşimli Python örnekleri
- Agent Framework AG-UI entegrasyonu (C#)
- .NET için AG-UI örnekleri
- Responses hosting örneği
- Telegram hosting örneği
- Introducing agent and workflow channels
- Azure Cosmos DB bellek paketi
- Cosmos DB tabanlı bellek: teknik derinlemesine inceleme
- CodeAct with Hyperlight incelemesi
- Microsoft Agent Framework’te Agent ve Workflow Kanalları
- Microsoft Agent Framework için Cosmos DB Tabanlı Bellek
- Durable Workflows ile Microsoft Agent Framework
- Microsoft Agent Framework’te Asıl Değişim: Harness, Hosted Agents ve CodeAct
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
Yorum gönder