Çalışan Aracılar

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 yöntemini kullanın run_stream .

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

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ırmayı özelleştirmek için anahtar sözcük bağımsız değişkenlerinin geçirilmesini destekler. Sağlanan belirli seçenekler aracı türüne bağlıdır, ancak ChatAgent hem hem de runrun_stream yöntemlerine geçirilebilecek birçok sohbet istemcisi parametresini destekler.

Için yaygın seçenekler ChatAgent şunlardır:

max_tokens: Oluşturulacak en fazla belirteç sayısı
temperature: Yanıt oluşturmada rastgeleliği denetler
model: Bu belirli çalıştırma için modeli geçersiz kıl
tools: Yalnızca bu çalıştırma için ek araçlar ekleyin
response_format: Yanıt biçimini belirtin (örneğin, yapılandırılmış çıktı)

# Run with custom options
result = await agent.run(
    "What is the weather like in Amsterdam?",
    temperature=0.3,
    max_tokens=150,
    model="gpt-4o"
)

# Streaming with custom options
async for update in agent.run_stream(
    "Tell me a detailed weather forecast",
    temperature=0.7,
    tools=[additional_weather_tool]
):
    if update.text:
        print(update.text, end="", flush=True)

Hem aracı düzeyinde varsayılanlar hem de çalışma düzeyi seçenekleri sağlandığında, çalıştırma düzeyi seçenekleri önceliklidir.

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 TextContenttoplayan bir Text özellik kullanılabilir.

Akış dışı durum için her şey tek bir AgentRunResponse nesnede döndürülür. AgentRunResponse ö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, AgentRunResponseUpdate 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 AgentRunResponse nesnede döndürülür. AgentRunResponse ö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 TextContentChatMessage öğelerin toplanması gerekir. Bunu basitleştirmek için, tüm yanıt türlerinde tüm TextContenttoplayan bir Text ö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, AgentRunResponseUpdate 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.

async for update in agent.run_stream("What is the weather like in Amsterdam?"):
    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}")

İ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 ChatMessage temsil edilir ve tüm içerik sınıfları temel BaseContent sınıftan devralır.

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

Türü	Description
`TextContent`	Aracıdan hem giriş hem de çıkış olabilecek metin içeriği. Genellikle bir aracıdan alınan metin sonucunu içerir.
`DataContent`	Veri URI'si olarak temsil edilen ikili içerik (örneğin, base64 ile kodlanmış görüntüler). Aracıya ve aracıdan ikili verileri geçirmek için kullanılabilir.
`UriContent`	Görüntü, ses dosyası veya belge gibi barındırılan içeriğe işaret eden bir URI.
`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 ChatMessage, TextContent, DataContent, UriContent

# Create a text message
text_message = ChatMessage(role="user", text="Hello!")

# Create a message with multiple content types
image_data = b"..."  # your image bytes
mixed_message = ChatMessage(
    role="user",
    contents=[
        TextContent("Analyze this image:"),
        DataContent(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 isinstance(content, TextContent):
            print(f"Text: {content.text}")
        elif isinstance(content, DataContent):
            print(f"Data URI: {content.uri}")
        elif isinstance(content, UriContent):
            print(f"External URI: {content.uri}")

Sonraki Adımlar

Çok Adımlı Konuşmalar ve Yazışma

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-01-08