ai-agents-for-beginners

Microsoft Agent Framework’ü Keşfetmek

Agent Framework

Giriş

Bu ders şunları kapsayacaktır:

Öğrenme Hedefleri

Bu dersi tamamladıktan sonra şunları bileceksiniz:

Kod Örnekleri

Microsoft Agent Framework (MAF) için kod örnekleri bu depoda xx-python-agent-framework ve xx-dotnet-agent-framework dosyaları altında bulunabilir.

Microsoft Agent Framework’ü Anlamak

Framework Intro

Microsoft Agent Framework (MAF), Microsoft’un AI ajanları oluşturmak için birleşik çerçevesidir. Üretim ve araştırma ortamlarında görülen çeşitli ajanik kullanım durumlarını ele alacak esnekliği sunar:

AI Ajanları Üretimde sunabilmek için MAF ayrıca şu özelliklere de sahiptir:

Microsoft Agent Framework ayrıca birlikte çalışabilirliğe odaklanmıştır:

Şimdi Microsoft Agent Framework’ün bazı temel kavramlarına bu özelliklerin nasıl uygulandığına bakalım.

Microsoft Agent Framework’ün Temel Kavramları

Ajanlar

Agent Framework

Ajan Oluşturma

Ajan oluşturma, çıkarım servisi (LLM Sağlayıcısı), AI Ajan’ın izleyeceği talimatlar seti ve atanmış bir name tanımlanarak yapılır:

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent( instructions="You are good at recommending trips to customers based on their preferences.", name="TripRecommender" )

Yukarıdaki örnek Azure OpenAI kullanmakta ama ajanlar Microsoft Foundry Agent Service dahil çeşitli servislerle oluşturulabilir:

AzureAIAgentClient(async_credential=credential).create_agent( name="HelperAgent", instructions="You are a helpful assistant." ) as agent

OpenAI Responses, ChatCompletion API’ları

agent = OpenAIResponsesClient().create_agent( name="WeatherBot", instructions="You are a helpful weather assistant.", )

agent = OpenAIChatClient().create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

veya büyük bağlam pencereleri (204K token’a kadar) sunan OpenAI uyumlu API sağlayan MiniMax ile:

agent = OpenAIChatClient(base_url="https://api.minimax.io/v1", api_key=os.environ["MINIMAX_API_KEY"], model_id="MiniMax-M3").create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

veya A2A protokolü kullanarak uzaktaki ajanlar ile:

agent = A2AAgent( name=agent_card.name, description=agent_card.description, agent_card=agent_card, url="https://your-a2a-agent-host" )

Ajanları Çalıştırma

Ajanlar, yayın veya yayın akışı yanıtları için .run veya .run_stream metodlarıyla çalıştırılır.

result = await agent.run("What are good places to visit in Amsterdam?")
print(result.text)

async for update in agent.run_stream("What are the good places to visit in Amsterdam?"):
    if update.text:
        print(update.text, end="", flush=True)

Her ajan çalıştırma, ajan tarafından kullanılan max_tokens, çağrılabilecek tools ve hatta kullanılan model gibi parametreleri özelleştirmek için seçeneklere sahip olabilir.

Bu, kullanıcının görevinin tamamlanması için belirli model veya araçların gerektiği durumlarda faydalıdır.

Araçlar

Araçlar ajan tanımı yapılırken de tanımlanabilir:

def get_attractions( location: Annotated[str, Field(description="The location to get the top tourist attractions for")], ) -> str: """Get the top tourist attractions for a given location.""" return f"The top attractions for {location} are." 


# Bir ChatAgent doğrudan oluşturulurken

agent = ChatAgent( chat_client=OpenAIChatClient(), instructions="You are a helpful assistant", tools=[get_attractions]

ve ajan çalıştırılırken de:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Sadece bu çalışma için sağlanan araç )

Ajan İş Parçacıkları

Ajan İş Parçacıkları çoklu tur konuşmaları yönetmek için kullanılır. İş parçacıkları şu şekilde oluşturulabilir:

İş parçacığı oluşturma kodu aşağıdaki gibidir:

# Yeni bir iş parçacığı oluşturun.
thread = agent.get_new_thread() # İş parçacığı ile ajanı çalıştırın.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Ardından iş parçacığını daha sonra kullanmak üzere serileştirebilirsiniz:

# Yeni bir iş parçacığı oluştur.
thread = agent.get_new_thread() 

# İş parçacığı ile ajanı çalıştır.

response = await agent.run("Hello, how are you?", thread=thread) 

# Depolama için iş parçacığını serileştir.

serialized_thread = await thread.serialize() 

# Depolamadan yükledikten sonra iş parçacığı durumunu deserialize et.

resumed_thread = await agent.deserialize_thread(serialized_thread)

Ajan Middleware

Ajanlar, kullanıcının görevlerini tamamlamak için araçlar ve LLM’lerle etkileşir. Belirli senaryolarda bu etkileşimlerin arasında işlem yapmak veya izlemek isteyebiliriz. Ajan middleware bu işlemleri şöyle mümkün kılar:

Fonksiyon Middleware’i

Bu middleware, ajan ile çağrılacak fonksiyon/araç arasında bir eylemin gerçekleşmesini sağlar. Bir örnek olarak, fonksiyon çağrısı üzerine bazı loglama yapmak isteyebilirsiniz.

Aşağıdaki koddaki next, bir sonraki middleware veya gerçek fonksiyonun çağrılıp çağrılmayacağını tanımlar.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Ön işleme: Fonksiyon çalıştırılmadan önce loglama
    print(f"[Function] Calling {context.function.name}")

    # Bir sonraki middleware veya fonksiyon çalıştırmaya devam et
    await next(context)

    # Son işlem: Fonksiyon çalıştırıldıktan sonra loglama
    print(f"[Function] {context.function.name} completed")

Sohbet Middleware’i

Bu middleware, ajan ile LLM arasındaki istekler arasında bir işlem ya da loglama yapılmasını sağlar.

Bu, AI servisine gönderilen messages gibi önemli bilgileri içerir.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Ön işleme: AI çağrısından önce kayıt tut
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Bir sonraki ara katmana veya AI servisine devam et
    await next(context)

    # Son işlem: AI yanıtından sonra kayıt tut
    print("[Chat] AI response received")

Ajan Belleği

Agentic Memory dersinde anlatıldığı gibi, bellek ajanların farklı bağlamlar içinde çalışabilmesi için önemli bir bileşendir. MAF farklı tipte bellekler sunar:

Anlık Bellek Depolaması

Bu, uygulama çalışma zamanında iş parçacıklarında saklanan bellektir.

# Yeni bir iş parçacığı oluşturun.
thread = agent.get_new_thread() # İş parçacığı ile ajanı çalıştırın.
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Kalıcı Mesajlar

Bu bellek, farklı oturumlar arasında konuşma geçmişini saklamak için kullanılır. chat_message_store_factory ile tanımlanır:

from agent_framework import ChatMessageStore

# Özel bir mesaj deposu oluşturun
def create_message_store():
    return ChatMessageStore()

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a Travel assistant.",
    chat_message_store_factory=create_message_store
)

Dinamik Bellek

Bu bellek, ajanlar çalıştırılmadan önce bağlama eklenir. Bu bellekler mem0 gibi harici servislerde saklanabilir:

from agent_framework.mem0 import Mem0Provider

# Gelişmiş bellek yetenekleri için Mem0 kullanılıyor
memory_provider = Mem0Provider(
    api_key="your-mem0-api-key",
    user_id="user_123",
    application_id="my_app"
)

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant with memory.",
    context_providers=memory_provider
)

Ajan Gözlemlenebilirliği

Gözlemlenebilirlik, güvenilir ve sürdürülebilir ajanik sistemler kurmak için önemlidir. MAF, daha iyi gözlemlenebilirlik için OpenTelemetry ile izleme ve sayaçlar sağlar.

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # bir şey yap
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

İş Akışları

MAF, bir görevi tamamlamak için önceden tanımlı adımlar sunan iş akışları sağlar ve bu adımlar içinde AI ajanları bileşen olarak bulunur.

İş akışları, daha iyi kontrol akışı sağlayan farklı bileşenlerden oluşur. Ayrıca çoklu ajan orkestrasyonu ve iş akışı durumlarını kaydetmek için checkpointing sağlar.

Bir iş akışının temel bileşenleri:

Yürütücüler

Yürütücüler gelen mesajları alır, atanan görevleri yapar ve çıktı mesajı üretir. Bu, iş akışını büyük görevin tamamlanmasına doğru ilerletir. Yürütücüler AI ajan veya özel mantık olabilir.

Kenarlar

Kenarlar iş akışındaki mesaj akışını tanımlamak için kullanılır. Bunlar şu türlerde olabilir:

Doğrudan Kenarlar - Yürütücüler arasında basit birebir bağlantılar:

from agent_framework import WorkflowBuilder

builder = WorkflowBuilder()
builder.add_edge(source_executor, target_executor)
builder.set_start_executor(source_executor)
workflow = builder.build()

Koşullu Kenarlar - Belirli koşul karşılandığında etkinleşir. Örneğin, otel odaları müsait değilse, bir yürütücü diğer seçenekleri önerebilir.

Switch-case Kenarlar - Mesajları tanımlı koşullara göre farklı yürütücülere yönlendirir. Örneğin, seyahat müşterisi öncelikli erişime sahipse ve görevleri başka bir iş akışıyla ele alınacaksa.

Yayılma (Fan-out) Kenarlar - Tek bir mesajı birden çok hedefe gönderir.

Toplanma (Fan-in) Kenarlar - Farklı yürütücülerden gelen çoklu mesajları tek hedefe toplar.

Olaylar

İş akışlarına daha iyi gözlemlenebilirlik sağlamak için, MAF yürütmeye ilişkin yerleşik olaylar sunar:

Gelişmiş MAF Desenleri

Yukarıdaki bölümler Microsoft Agent Framework’ün ana kavramlarını kapsar. Daha karmaşık ajanlar oluştururken dikkate alabileceğiniz bazı gelişmiş desenler şunlardır:

Microsoft Foundry Üzerinde LangChain / LangGraph Ajanlarını Barındırmak

Microsoft Agent Framework çerçeve-uyumludur — yalnızca MAF ile yazılmış ajanlarla sınırlı değilsiniz. Zaten LangChain veya LangGraph ile yazılmış bir ajana sahipseniz, bunu Microsoft Foundry tarafından barındırılan ajan olarak çalıştırabilirsiniz; böylece Foundry çalışma zamanı, oturumlar, ölçeklendirme, kimlik ve protokol uç noktalarını yönetirken, ajan mantığınız LangGraph’da kalır.

Bu, Foundry’nin barındırdığı ajanların kullandığı protokoller üzerinden derlenmiş LangGraph grafiği sunan langchain_azure_ai.agents.hosting paketi ile yapılır.

1. Hosting eklentisini kurun:

pip install -U "langchain-azure-ai[hosting]>=1.2.4" azure-identity

hosting eklentisi Foundry protokol kütüphanelerini yükler: azure-ai-agentserver-responses (OpenAI uyumlu /responses uç noktası) ve azure-ai-agentserver-invocations (genel /invocations uç noktası).

2. Bir hosting protokolü seçin:

Protokol Host sınıfı Uç Nokta Kullanım Durumu
Responses ResponsesHostServer /responses OpenAI uyumlu sohbet, yayın akışı, yanıt geçmişi ve sohbet iş parçacığına ihtiyacınız varsa — konuşma ajanları için önerilen varsayılan.
Invocations InvocationsHostServer /invocations Özel JSON yapısı, webhook tarzı uç nokta veya konuşma dışı işlem gerekiyorsa.

Çünkü Responses API, Foundry’de ajan tarzı geliştirme için birincil APIdir, çoğu ajan için ResponsesHostServer ile başlayın.

3. Ortam değişkenlerini yapılandırın (az login yapın ki DefaultAzureCredential kimlik doğrulaması yapabilsin):

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export FOUNDRY_MODEL_NAME="gpt-5-mini"

Ajan daha sonra Foundry’de barındırılan ajan olarak çalıştığında, platform FOUNDRY_PROJECT_ENDPOINT değerini otomatik olarak enjekte eder.

4. Responses protokolü üzerinden bir LangGraph ajanı sunun:

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from langchain_azure_ai.agents.hosting import ResponsesHostServer

_AZURE_AI_SCOPE = "https://ai.azure.com/.default"


def build_chat_model() -> ChatOpenAI:
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
    deployment = os.environ.get("FOUNDRY_MODEL_NAME", "gpt-5-mini")
    credential = DefaultAzureCredential()
    project = AIProjectClient(endpoint=project_endpoint, credential=credential)
    openai_client = project.get_openai_client()
    token_provider = get_bearer_token_provider(credential, _AZURE_AI_SCOPE)

    # ChatOpenAI burada Foundry projesinin OpenAI uyumlu (Yanıtlar) uç noktasını hedefliyor.
    return ChatOpenAI(
        model=deployment,
        base_url=str(openai_client.base_url),
        api_key=token_provider,
    )


def main() -> None:
    graph = create_agent(build_chat_model(), tools=[])
    port = int(os.environ.get("PORT", "8088"))
    ResponsesHostServer(graph).run(port=port)


if __name__ == "__main__":
    main()

Yerelde python main.py ile çalıştırın, sonra http://localhost:8088/responses adresine bir Responses isteği gönderin.

Ana davranışlar:

Bu örneğin çalıştırılabilir versiyonu code-samples/14-langchain-hosted-agent.py dosyasında. Tam kılavuz (Invocations protokolü, özel istek şemaları ve sorun giderme) için Foundry barındırılan ajanlar olarak LangGraph ajanlarını barındırma sayfasına bakın.

Kod Örnekleri

Microsoft Agent Framework için kod örnekleri bu depoda xx-python-agent-framework ve xx-dotnet-agent-framework dosyaları altında bulunabilir.

Microsoft Agent Framework Hakkında Daha Fazla Sorunuz mu Var?

Diğer öğrenenlerle tanışmak, danışma saatlerine katılmak ve AI Ajanlar ile ilgili sorularınızı sormak için Microsoft Foundry Discord‘a katılın.

Önceki Ders

AI Ajanlar için Bellek

Sonraki Ders

Bilgisayar Kullanım Ajanları (CUA) Oluşturmak

Feragatname: Bu belge, AI çeviri hizmeti Co-op Translator kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz.

This site is open source. Improve this page.