Microsoft Agent Framework'te Agent ve Workflow Kanalları

⏱️ 5 dk okuma📅 30 Ağustos 2026

Bir ajan veya iş akışı, ancak kullanıcıların ve diğer sistemlerin zaten kullandığı arayüzler üzerinden erişilebildiğinde işe yarar. Bu arayüz bir OpenAI Responses istemcisi, Telegram, A2A üzerinden başka bir ajan veya bir MCP istemcisi olabilir. Microsoft Agent Framework, Python tarafında bu ihtiyacı doğrudan karşılamak için channels yapısını devreye alıyor. Geliştirici böylece ajanını hangi kanallardan sunacağına ve bu kanalların nasıl davranacağına dair kontrolü elinde tutuyor.

Kanal odaklı paket yapısı

Yeni paketler, küçük ve paylaşımlı bir hosting çekirdeği ile kanala özgü entegrasyonların etrafında düzenlenmiş:

agent-framework-hosting: Ortak agent, workflow ve oturum durumu yardımcılarını sağlar.
agent-framework-hosting-responses: OpenAI Responses istek ve sonuçlarını dönüştürür.
agent-framework-hosting-telegram: Telegram güncellemelerini ve giden işlemleri çevirir.
agent-framework-hosting-a2a: Ajanları ve iş akışlarını yerel A2A SDK tiplerine bağlar.
agent-framework-hosting-mcp: Ajan ve iş akışlarını yerel MCP araçları olarak dışa açar.

Her paket yalnızca kendi protokol sınırıyla ilgilenir. Yönlendirme, kimlik doğrulama, yetkilendirme, depolama, arka plan işleme ve dağıtım gibi konular uygulamanın seçtiği web framework’ünde veya yerel SDK’da kalır. Bu sayede tek bir kanal eklenebilir ya da birkaç kanal bir arada sunulabilir; ajan veya iş akışını yeni bir uygulama çalışma zamanına taşımak veya aynı ajanı birden fazla SDK ile ayrı ayrı bakımlamak gerekmez.

Paylaşımlı hedef ve durum modeli

agent-framework-hosting paketi, tüm kanallarda kullanılan ortak temeli sağlar. AgentState, bir ajan hedefini kendi oturum deposuyla birlikte tutar; WorkflowState ise bir iş akışı hedefini instance, factory veya builder üzerinden çözümler:

from agent_framework_hosting import AgentState, WorkflowState
agent_state = AgentState(agent)
workflow_state = WorkflowState(workflow_builder, cache_target=False)

Her iki durum tipi de kanal işleyicilerine ve adaptörlerine hedeflerini çözümlemek için tutarlı bir yol sunar. Hedef doğrudan oluşturulabilir ya da senkron veya asenkron kurulum kodu üzerinden sağlanabilir; her istek için yeniden üretilebilir, önbelleğe de alınabilir.

Ajanlar için AgentState, uygulamanın belirlediği oturum kimliklerini AgentSession değerlerine eşler. Bir Responses çağıranının, Telegram kullanıcısının, A2A bağlamının veya MCP istemcisinin nasıl bir oturum kimliğine dönüşeceğine kendi başına karar vermez. Bu eşlemeyi uygulama tarafında siz kurarsınız; aşağıdaki resolve_session_id, Agent Framework tarafından sağlanan bir fonksiyon değil, örnek uygulama kodudur:

# Uygulamanın tanımladığı kimlik ve oturum eşlemesi.
session_id = resolve_session_id(authenticated_user, channel_identity)
session = await agent_state.get_or_create_session(session_id)

Aynı konuşmanın farklı kanallar arasında devam etmesini sağlayan mekanizma budur. Aynı kimliği doğrulanmış kullanıcı hem Responses’tan hem Telegram’dan aynı kanonik oturum kimliğine çözümlenirse, iki kanal da aynı AgentSession‘ı yükleyip günceller. Farklı kimliklere çözümlenirlerse geçmişleri ayrı kalır. Kimlik bağlama, yetkilendirme ve eşzamanlılık kontrolleri uygulamanın sorumluluğundadır.

İş akışları da WorkflowState üzerinden aynı hedef çözümleme modelini kullanır. Checkpoint depolaması ve kanal continuation ID’lerinin checkpoint’lere eşlenmesi uygulama tarafında kalır. Bu paylaşımlı katman sayesinde ajan veya iş akışı tanımı etrafındaki kanallardan bağımsız kalır; protokole özgü giriş ve çıkışları kanal paketleri üstlenir.

OpenAI Responses

Responses yardımcıları, gelen isteği Agent Framework çalıştırma değerlerine dönüştürür ve tamamlanan ya da akış halindeki sonucu tekrar Responses formatına çevirir:

from agent_framework_hosting_responses import (
create_response_id,
responses_from_run,
responses_session_id,
responses_to_run,
)
run = responses_to_run(body)
session_id, is_conversation = responses_session_id(body)
response_id = create_response_id()
session = await agent_state.get_or_create_session(session_id or response_id)
result = await (await agent_state.get_target()).run(
run["messages"],
session=session,
options=run["options"],
)
await agent_state.set_session(session_id if is_conversation else response_id, session)
response = responses_from_run(
result,
response_id=response_id,
conversation_id=session_id if is_conversation else None,
)

Response ve conversation ID’lerinin oturumlara nasıl eşleneceğine, çağıranın hangi istek seçeneklerini kontrol edebileceğine, ne zaman streaming yapılacağına, continuation ID’lerin nasıl yetkilendirileceğine ve oturum durumunun nerede saklanacağına uygulama karar verir. Çalıştırılabilir Responses agent örneği; yerel FastAPI yönlendirmesini, streaming’i, oturum devamlılığını ve uygulamaya ait bir seçenek politikasını gösteriyor. İş akışları da aynı Responses arayüzünü kullanabilir; bu durumda uygulama AgentSession yerine response ID’lerini workflow checkpoint’lerine eşler.

Telegram yardımcıları, yerel güncellemeleri Agent Framework girdisine dönüştürür ve streaming halindeki bir çalıştırmayı Telegram işlemlerine çevirir. Bu işlemleri uygulama, doğrudan HTTP çağrılarıyla ya da aiogram, python-telegram-bot gibi bir Telegram SDK’sı üzerinden yürütür.

Komutlar, webhook kimlik doğrulaması, polling, medya işleme, edit throttling ve teslim politikası standart uygulama kodu olarak kalır. Kanala özgü yönergeleri manuel olarak ya da bir context provider aracılığıyla ekleyebilir, örneğin yanıt formatını Telegram’a göre uyarlayabilirsiniz. Telegram örneği; aiogram ile hem polling hem webhook uygulamalarını, streaming edits, /new gibi komutları, medya dönüşümü, sohbet başına sıralama ve oturum sürekliliğini kapsıyor.

A2A ve MCP

A2A tarafında AgentA2AAdapter ve WorkflowA2AAdapter, yerel agent kartlarını üretir; ilan edilen giriş ve çıkış modlarını dönüşüm yardımcılarıyla hizalı tutar. Uygulama; yerel A2A executor’ını, görev yaşam döngüsünü, event queue’yu, route’ları ve task store’u sahiplenmeye devam eder. Örnek, bir Agent Framework ajanının yerel bir A2A sunucusu üzerinden nasıl sunulabileceğini gösteriyor.

MCP tarafında ise AgentMCPTool ve WorkflowMCPTool, Agent Framework hedeflerinden yerel araçlar türetir. Uygulamalar daha düşük seviyeli dönüşüm fonksiyonlarını FastMCP gibi bir sunucuyla veya doğrudan kayıtlı MCP işleyicileriyle de kullanabilir. MCP hosting örnekleri; manuel dönüşümü, FastMCP kullanımını, üretilen agent araçlarını, oturum farkındalıklı ajanları ve iş akışından türetilen araçları kapsıyor.

Kendi kanal karışımınızı kurmak

Aynı ajan veya iş akışı birden fazla kanala hizmet edebilir. Her kanalın kendi yetkilendirme kurallarına ve sunum yönergelerine sahip olması mümkün; temel hedef ve uygulama altyapısı bu sırada ortak kalır. Kanala özgü bir kimliği oturum kimliğine bağlayan resolver’ı geliştirici tanımlar. Birleşik bir resolver ile kullanıcı Responses istemcisinde başlayıp Telegram’da devam edebilir veya desteklenen diğer kanallar arasında geçiş yapabilir; yeni bir konuşma başlatması gerekmez. Aksi bir deneyim isteniyorsa kanal kimlikleri ayrı ad alanlarında da tutulabilir.

Bu esneklik uygulama framework’ü seçimi için de geçerli. Mevcut HTTP örnekleri FastAPI kullansa da yardımcılar protokol dönüşümü ve yürütme durumu sınırında çalıştığı için Django, Flask, başka bir Python web framework’ü, mevcut bir servis ya da yerel protokol SDK’sı ile entegre edilebilirler.

Sırada ne var?

Microsoft, bu yapıyı daha fazla kanal, ek yardımcılar ve barındırma sürecini kolaylaştıracak diğer özelliklerle genişletmeyi planladığını belirtiyor. Doğru yönde ilerlemek için kullanıcı geri bildirimini önemsediklerini de vurguluyor: neyin işe yaradığı, neyin yaramadığı ve senaryoyu uçtan uca tamamlamak için başka nelere ihtiyaç duyulduğu. Bu paketleri; kullanıcılarınızın ihtiyaç duyduğu protokoller ve kanallar üzerinden, halihazırda işlettiğiniz uygulama ve altyapı içinde bir Agent Framework ajanına veya iş akışına bağlanmak için kullanabilirsiniz.

Kaynaklar ve İleri Okuma

Bu yazı yapay zeka (büyük dil modelleri) ile hazırlanmış, insan editör tarafından incelenmiştir. İçerik üretim sürecimiz.

Aşkın KILIÇYazar

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.

AZ-305AZ-104AZ-500AZ-400DP-203AI-102