Çalıştırılan Etmenler

Temel Aracı soyutlaması, aracıyı çalıştırmak için çeşitli seçenekleri kullanıma sunar. Arayanlar sıfır, bir veya çok giriş iletisi sağlamayı seçebilir. Arayanlar akışla akış dışı arasında da seçim yapabilir. Şimdi farklı kullanım senaryolarını inceleyelim.

Akış ve akış dışı

Microsoft Agent Framework, aracı çalıştırmak için hem akış hem de akış dışı yöntemleri destekler.

Akış olmayanlar için yöntemini kullanın RunAsync .

Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

Akış için yöntemini kullanın RunStreamingAsync .

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.Write(update);
}

Akış olmayanlar için yöntemini kullanın run .

result = await agent.run("What is the weather like in Amsterdam?")
print(result.text)

Akış için ile stream=Trueyöntemini kullanınrun. Bu, zaman uyumsuz olarak yinelenebilen bir ResponseStream nesne döndürür:

async for update in agent.run("What is the weather like in Amsterdam?", stream=True):
    if update.text:
        print(update.text, end="", flush=True)

ResponseStream

tarafından ResponseStreamrun(..., stream=True) döndürülen nesne iki tüketim desenini destekler:

Desen 1: Zaman uyumsuz yineleme — gerçek zamanlı görüntü için gelen işlem güncelleştirmeleri:

response_stream = agent.run("Tell me a story", stream=True)
async for update in response_stream:
    if update.text:
        print(update.text, end="", flush=True)

Desen 2: Doğrudan sonlandırma — yinelemeyi atlayın ve tam yanıtı alın:

response_stream = agent.run("Tell me a story", stream=True)
final = await response_stream.get_final_response()
print(final.text)

Desen 3: Birleştirilmiş — gerçek zamanlı görüntü için yineleyin ve ardından toplanan sonucu alın:

response_stream = agent.run("Tell me a story", stream=True)

# First, iterate to display streaming output
async for update in response_stream:
    if update.text:
        print(update.text, end="", flush=True)

# Then get the complete response (uses already-collected updates, does not re-iterate)
final = await response_stream.get_final_response()
print(f"\n\nFull response: {final.text}")
print(f"Messages: {len(final.messages)}")

Aracı çalıştırma seçenekleri

Temel aracı soyutlaması, her aracı çalıştırması için bir seçenekler nesnesi geçirilmesine izin verir, ancak bir çalıştırmayı soyutlama düzeyinde özelleştirme özelliği oldukça sınırlıdır. Aracılar önemli ölçüde farklılık gösterebilir ve bu nedenle yaygın özelleştirme seçenekleri yoktur.

Çağıranın üzerinde çalıştığı aracı türünü bildiği durumlarda, çalıştırmayı özelleştirmeye izin vermek için türe özgü seçenekleri geçirmek mümkündür.

Örneğin, burada aracı a'dır ChatClientAgent ve öğesinden ChatClientAgentRunOptionsdevralan bir AgentRunOptions nesneyi geçirmek mümkündür. Bu, çağıranın, üzerinde oluşturulduğuna geçirilmeden önce herhangi bir aracı düzeyi seçeneğiyle birleştirilmiş özel ChatOptions sağlamasına IChatClientChatClientAgent olanak tanır.

var chatOptions = new ChatOptions() { Tools = [AIFunctionFactory.Create(GetWeather)] };
Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", options: new ChatClientAgentRunOptions(chatOptions)));

Python aracıları, her çalıştırmanın parametresi aracılığıyla özelleştirilmesini options destekler. Seçenekler TypedDict olarak geçirilir ve hem yapım zamanında (aracılığıyla default_options) hem de çalıştırma başına (aracılığıyla options) ayarlanabilir. Her sağlayıcının, sağlayıcıya özgü ayarlar için tam IDE otomatik tamamlama ve tür denetimi sağlayan kendi TypedDict sınıfı vardır.

Yaygın seçenekler şunlardır:

max_tokens: Oluşturulacak en fazla belirteç sayısı
temperature: Yanıt oluşturmada rastgeleliği denetler
model_id: Bu belirli çalıştırma için modeli geçersiz kıl
top_p: Çekirdek örnekleme parametresi
response_format: Yanıt biçimini belirtin (örneğin, yapılandırılmış çıkış)

Uyarı

tools ve instructions parametreleri doğrudan anahtar sözcük bağımsız değişkenleri olarak kalır ve sözlük aracılığıyla options geçirılmaz.

from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions

# Set default options at construction time
agent = OpenAIChatClient().as_agent(
    instructions="You are a helpful assistant",
    default_options={
        "temperature": 0.7,
        "max_tokens": 500
    }
)

# Run with custom options (overrides defaults)
# OpenAIChatOptions provides IDE autocomplete for all OpenAI-specific settings
options: OpenAIChatOptions = {
    "temperature": 0.3,
    "max_tokens": 150,
    "model_id": "gpt-4o",
    "presence_penalty": 0.5,
    "frequency_penalty": 0.3
}

result = await agent.run(
    "What is the weather like in Amsterdam?",
    options=options
)

# Streaming with custom options
async for update in agent.run(
    "Tell me a detailed weather forecast",
    stream=True,
    options={"temperature": 0.7, "top_p": 0.9},
    tools=[additional_weather_tool]  # tools is still a keyword argument
):
    if update.text:
        print(update.text, end="", flush=True)

Her sağlayıcının, sağlayıcı tarafından desteklenen tüm seçenekleri kullanıma sunan kendi TypedDict sınıfı (örneğin, OpenAIChatOptions, AnthropicChatOptions, OllamaChatOptions) vardır.

Hem hem de default_options çalıştırma options başına sağlandığında, çalıştırma başına seçenekler önceliklidir ve varsayılan değerlerle birleştirilir.

Yanıt türleri

Aracılardan hem akış hem de akış dışı yanıtlar aracı tarafından üretilen tüm içeriği içerir. İçerik, aracıdan elde edilen sonuç (yani kullanıcı sorusunun yanıtı) olmayan veriler içerebilir. Döndürülen diğer verilere örnek olarak işlev aracı çağrıları, işlev aracı çağrılarının sonuçları, muhakeme metni, durum güncelleştirmeleri ve daha birçok örnek verilebilir.

Döndürülen tüm içerik sonuç olmadığından, sonucu diğer içerikten yalıtmaya çalışırken belirli içerik türlerinin aranması önemlidir.

Yanıttan metin sonucunu ayıklamak için tüm öğelerdeki tüm TextContentChatMessages öğelerin toplanması gerekir. Bunu basitleştirmek için, tüm yanıt türlerinde tüm Texttoplayan bir TextContent özellik kullanılabilir.

Akış dışı durum için her şey tek bir AgentResponse nesnede döndürülür. AgentResponse özelliği aracılığıyla oluşturulan iletilere erişime Messages izin verir.

var response = await agent.RunAsync("What is the weather like in Amsterdam?");
Console.WriteLine(response.Text);
Console.WriteLine(response.Messages.Count);

Akış durumu için, AgentResponseUpdate nesneler üretildikçe akışa alınır. Her güncelleştirme aracıdan elde edilen sonucun bir bölümünü ve ayrıca diğer çeşitli içerik öğelerini içerebilir. Akış dışı duruma benzer şekilde, güncelleştirmede yer alan sonucun bölümünü almak ve özelliği aracılığıyla Text ayrıntıya inmek için özelliğini kullanmak Contents mümkündür.

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.WriteLine(update.Text);
    Console.WriteLine(update.Contents.Count);
}

Akış dışı durum için her şey tek bir AgentResponse nesnede döndürülür. AgentResponse özelliği aracılığıyla oluşturulan iletilere erişime messages izin verir.

Yanıttan metin sonucunu ayıklamak için tüm öğelerdeki tüm TextContentMessage öğelerin toplanması gerekir. Bunu basitleştirmek için, tüm yanıt türlerinde tüm Texttoplayan bir TextContent özellik kullanılabilir.

response = await agent.run("What is the weather like in Amsterdam?")
print(response.text)
print(len(response.messages))

# Access individual messages
for message in response.messages:
    print(f"Role: {message.role}, Text: {message.text}")

Akış durumu için nesneler tarafından AgentResponseUpdaterun(..., stream=True)döndürülen aracılığıyla ResponseStream üretildiği için akışa alınır. Her güncelleştirme aracıdan elde edilen sonucun bir bölümünü ve ayrıca diğer çeşitli içerik öğelerini içerebilir. Akış dışı duruma benzer şekilde, güncelleştirmede yer alan sonucun bölümünü almak ve özelliği aracılığıyla text ayrıntıya inmek için özelliğini kullanmak contents mümkündür.

response_stream = agent.run("What is the weather like in Amsterdam?", stream=True)
async for update in response_stream:
    print(f"Update text: {update.text}")
    print(f"Content count: {len(update.contents)}")

    # Access individual content items
    for content in update.contents:
        if hasattr(content, 'text'):
            print(f"Content: {content.text}")

# Get the aggregated final response after streaming
final = await response_stream.get_final_response()
print(f"Complete text: {final.text}")

İleti türleri

Aracılardan gelen giriş ve çıkışlar ileti olarak temsil edilir. İletiler içerik öğelerine ayrılır.

Microsoft Agent Framework, soyutlamalar tarafından Microsoft.Extensions.AI sağlanan ileti ve içerik türlerini kullanır. İletiler sınıfı tarafından ChatMessage temsil edilir ve tüm içerik sınıfları temel AIContent sınıftan devralır.

Farklı içerik türlerini temsil etmek için kullanılan çeşitli AIContent alt sınıflar vardır. Bazıları temel Microsoft.Extensions.AI soyutlamaların bir parçası olarak sağlanır, ancak sağlayıcılar gerektiğinde kendi türlerini de ekleyebilir.

bazı popüler türler Microsoft.Extensions.AIşunlardır:

Türü	Description
TextContent	Hem bir kullanıcıdan veya geliştiriciden giriş hem de aracıdan çıkış olabilecek metin içeriği. Genellikle bir aracıdan alınan metin sonucunu içerir.
DataContent	Hem giriş hem de çıkış olabilecek ikili içerik. Aracıya görüntü, ses veya video verilerini geçirmek için kullanılabilir (burada desteklenir).
UriContent	Genellikle resim, ses veya video gibi barındırılan içeriğe işaret eden bir URL.
FunctionCallContent	Çıkarım hizmeti tarafından işlev aracını çağırma isteği.
FunctionResultContent	İşlev aracı çağırma işleminin sonucu.

Python Agent Framework, paketten agent_framework ileti ve içerik türlerini kullanır. İletiler sınıfı tarafından Message temsil edilir ve tüm içerik sınıfları temel Content sınıftan devralır.

Farklı içerik türlerini temsil etmek için kullanılan çeşitli Content alt sınıflar vardır:

Türü	Description
`Content`	Fabrika yöntemleriyle birleştirilmiş içerik türü (`Content.from_text()`, `Content.from_data()`, `Content.from_uri()`). `type` İçerik türünü ("text", "data", "uri") denetlemek için özelliğini kullanın.
`FunctionCallContent`	Yapay zeka hizmetinin işlev aracını çağırma isteği.
`FunctionResultContent`	İşlev aracı çağırma işleminin sonucu.
`ErrorContent`	İşleme başarısız olduğunda hata bilgileri.
`UsageContent`	Yapay zeka hizmetinden belirteç kullanımı ve faturalama bilgileri.

Farklı içerik türleriyle şu şekilde çalışabilirsiniz:

from agent_framework import Message, Content

# Create a text message
text_message = Message(role="user", contents=["Hello!"])

# Create a message with multiple content types
image_data = b"..."  # your image bytes
mixed_message = Message(
    role="user",
    contents=[
        Content.from_text("Analyze this image:"),
        Content.from_data(data=image_data, media_type="image/png"),
    ]
)

# Access content from responses
response = await agent.run("Describe the image")
for message in response.messages:
    for content in message.contents:
        if content.type == "text":
            print(f"Text: {content.text}")
        elif content.type == "data":
            print(f"Data URI: {content.uri}")
        elif content.type == "uri":
            print(f"External URI: {content.uri}")

Sonraki Adımlar

Multimodal

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-02-13