Aracı Yürütücüsü

Bir iş akışına yapay zeka aracısı eklediğinizde, iş akışı altyapısının iletileri ona yönlendirebilmesi, oturum durumunu yönetebilmesi ve çıktısını işleyebilmesi için bir yürütücüye sarmalanması gerekir. Aracı Yürütücüsü, bu uyarlamayı işleyen yerleşik yürütücüdür.

Genel bakış

Aracı Yürütücüsü, aracı soyutlaması ile iş akışı yürütme modeli arasındaki boşluğu kapatır. O:

İş akışı grafiğinden yazılan iletileri alır ve temel alınan aracıya iletir.
Aracının oturum ve oturumlar arasındaki konuşma durumunu yönetir.
Davranışını iş akışı yürütme moduna (akış veya akış dışı) göre uyarlar.
İş akışı çağırana gözlem için çıkış olaylarını (AgentResponse veya AgentResponseUpdate) sunar.
Grafik içinde işlemeye devam etmek için bağlı aşağı akış yürütücülerine ileti gönderir.
Uzun süre çalışan iş akışları için denetim noktası oluşturmayı destekler.

Nasıl Çalışır?

C# dilinde, bir iş akışına eklenen her AIAgentHostExecutor için dahili olarak bir AIAgent oluşturulur. Bu özelleştirilmiş yürütücü bir ChatProtocolExecutor desenini genişletir ve kullanır:

İleti önbelleğe alma — diğer yürütücülerden iletiler geldikçe aracı yürütücüsü bunları toplar. Etkinleştirilirse ForwardIncomingMessages (varsayılan), gelen iletiler aşağı akış yürütücülerine de iletilir.
Belirteç tetikleyicisini döndürme — aracı önbelleğe alınan iletilerini yalnızca aldıktan TurnTokensonra işler.
Aracı çağırma — yürütücü, temel aracı üzerinde RunAsync (akış dışı) veya RunStreamingAsync (akış) yöntemlerini çağırır.
Çıkış verme — akış olayları etkinleştirildiyse, her artımlı AgentResponseUpdate çıkış bir iş akışı çıkışı olarak sunulur. Etkinleştirilirse EmitAgentResponseEvents , toplanan AgentResponse iş akışı çıkışı olarak da sunulur.
Aşağı akış mesajlaşması — aracının yanıt iletileri bağlı aşağı akış yürütücülerine gönderilir.
Belirteç geçişi — yürütücü, dönüşünü tamamladıktan sonra zincirdeki bir sonraki aracının işlemeye başlayabilmesi için yeni TurnToken bir mesaj gönderir.

Tip

Bazı senaryolar daha özelleştirilmiş bir aracı yürütücüsü gerektirebilir; örneğin, iletim düzenlemeleri özel yönlendirme mantığıyla ayrılmış bir HandoffAgentExecutor kullanır.

İmlicit ve Eksplicit Oluşturma

Bir AIAgent öğesini WorkflowBuilder öğesine geçirdiğinizde, framework bunu otomatik olarak bir AIAgentBinding içinde sarmalar ve temel AIAgentHostExecutor öğesini oluşturur. Ajan yürütücüsünün örneğini doğrudan oluşturmanız gerekmez.

AIAgent writerAgent = /* create your agent */;
AIAgent reviewerAgent = /* create your agent */;

// Agents are automatically wrapped — no manual executor creation required
var workflow = new WorkflowBuilder(writerAgent)
    .AddEdge(writerAgent, reviewerAgent)
    .Build();

Yaygın desenler için AgentWorkflowBuilder üzerindeki yardımcı yöntemleri de kullanabilirsiniz.

// Build a sequential pipeline of agents
var workflow = AgentWorkflowBuilder.BuildSequential(writerAgent, reviewerAgent);

Özel Yapılandırma

Aracının yürütücüsünün nasıl davranacağını özelleştirmek için BindAsExecutor ve AIAgentHostOptions kullanın.

var options = new AIAgentHostOptions
{
    EmitAgentUpdateEvents = true,
    EmitAgentResponseEvents = true,
    ReassignOtherAgentsAsUsers = true,
    ForwardIncomingMessages = true,
};

ExecutorBinding writerBinding = writerAgent.BindAsExecutor(options);
var workflow = new WorkflowBuilder(writerBinding)
    .AddEdge(writerBinding, reviewerAgent)
    .Build();

Giriş Türleri

C# içindeki aracı yürütücüsü birden çok giriş türünü kabul eder: string, ChatMessageve IEnumerable<ChatMessage>. Dize girişleri otomatik olarak ChatMessage örneklerine User rolüyle dönüştürülür. Bir `TurnToken` alınana kadar tüm gelen iletiler birikir ve bu noktada yürütücü, toplu işlemi işler. Etkinleştirildiğinde (varsayılan ayar olarak) ReassignOtherAgentsAsUsers, diğer aracılardan gelen iletiler User rolüne yeniden atanır, böylece temel model bunları kullanıcı girişi olarak değerlendirirken, geçerli aracıdan gelen iletiler Assistant rolünü korur.

Çıkış ve Zincirleme

Etmen dönüşünü tamamladıktan sonra yürütücü:

Aracının yanıt iletilerini tüm bağlı aşağı akış çalıştırıcılarına gönderir.
Zincirdeki bir sonraki temsilci işleme başlayabilsin diye yeni bir TurnToken iletir.

Bu, zincirleme aracılarını basitleştirir; bunları kenarlarla bağlamanız yeterlidir:

var workflow = new WorkflowBuilder(frenchTranslator)
    .AddEdge(frenchTranslator, spanishTranslator)
    .AddEdge(spanishTranslator, englishTranslator)
    .Build();

Akış Davranışı

Akış davranışı, EmitAgentUpdateEvents üzerindeki seçenek veya AIAgentHostOptions aracılığıyla dinamik olarak TurnToken üzerinden kontrol edilir.

Etkinleştirildiğinde — yürütücü, aracıyı çağırır RunStreamingAsync ve her AgentResponseUpdate birini iş akışı çıkış olayı olarak sunar. Bu, belirteç bazında gerçek zamanlı güncellemeler sağlar.
Devre dışı bırakıldığında — yürütücü RunAsync çağırır ve tek bir tam yanıt üretir.

// Enable streaming events at the configuration level
var options = new AIAgentHostOptions
{
    EmitAgentUpdateEvents = true,
};

// Or enable streaming dynamically via TurnToken
await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

Paylaşılan Oturumlar

Her ajan yürütücüsü, varsayılan olarak kendi oturumunu korur. Aracılar arasında oturum paylaşmak için, aracıları iş akışına eklemeden önce ortak bir oturum sağlayıcısıyla yapılandırın.

Yapılandırma Seçenekleri

AIAgentHostOptions aracı yürütücüsünün davranışını denetler:

Seçenek	Varsayılan	Açıklama
`EmitAgentUpdateEvents`	`null`	Yürütme sırasında akış güncelleme olaylarını yayınla. `TurnToken` ayarlanırsa öncelik kazanır. Her ikisi de `null`ise, akış devre dışı bırakılır.
`EmitAgentResponseEvents`	`false`	Toplanan ajan yanıtını bir iş akışı çıkış olayı olarak yayınla.
`InterceptUserInputRequests`	`false`	İşleme için bir iş akışı iletisi olarak `UserInputRequestContent` yakala ve yönlendir.
`InterceptUnterminatedFunctionCalls`	`false`	Karşılık gelen bir sonuç olmadan `FunctionCallContent`'yi yakala ve iş akışı iletisi olarak yönlendir.
`ReassignOtherAgentsAsUsers`	`true`	Modelin bunları kullanıcı girişi olarak kabul edebilmesi için `User` diğer aracılardan gelen iletileri role yeniden atayın.
`ForwardIncomingMessages`	`true`	Gelen iletileri, aracının oluşturduğu iletilerden önce aşağıya doğru yürütücülere iletin.

Kontrol noktası oluşturma

Aracı yürütücüsü, uzun süre çalışan iş akışları için denetim noktası oluşturmayı destekler. Denetim noktası alındığında yürütücü serileştirme işlemi yapar:

Ajanın oturum durumu (aracılığıyla SerializeSessionAsync).
Şimdiki dönüşün olay emisyon yapılandırması (yalnızca istekler beklemedeyken ve yürütücü gelen işlemi henüz gerçekleştirmemişken TurnToken bulunur).
Bekleyen tüm kullanıcı giriş istekleri ve işlev çağrısı istekleri.

Yedekleme sırasında, yürütücü oturumu ve bekleyen istek durumunu deserileştirerek iş akışının kaldığı yerden devam etmesini sağlar.

Nasıl Çalışır?

AgentExecutor sınıfı, SupportsAgentRun protokolünü uygulayan bir aracıyı sarmalar. Yürütücü bir ileti aldığında:

İleti normalleştirme — giriş normalleştirilerek bir nesne listesi haline getirilir ve yürütücünün iç önbelleğine eklenir. Yürütücü, str, Message, list[str | Message], AgentExecutorRequest ve AgentExecutorResponse gibi birden fazla giriş türünü kabul eder ve her biri, girişi önbelleğe almadan önce normalleştiren özel bir işleyiciye yönlendirilir.
Aracı çağırma — yürütücü önbelleğe alınmış iletilerle çağrı yaparak agent.run() iş akışı yürütme moduna göre akış veya akış dışı modu otomatik olarak seçer.
Çıkış emisyonu — akış modunda her AgentResponseUpdate biri bir iş akışı çıkış olayı olarak sunulur. Akışsız modda, yalnızca tek bir AgentResponse üretilir.
Aşağı akış dağıtımı — aracı tamamlandıktan sonra yürütücü, bağlı tüm aşağı akış yürütücülerine bir AgentExecutorResponse gönderir. Bu yanıt, sorunsuz zincirleme özelliğini etkinleştiren konuşma geçmişinin tamamını içerir.
Önbellek sıfırlama — aracı çağrıldıktan sonra yürütücüsü iç ileti önbelleği temizlenir ve her aracı çağrısının yalnızca son çağrıdan sonra alınan yeni iletileri işlemesini sağlar.

Tip

Bazı senaryolar daha özelleştirilmiş bir aracı yürütücüsü gerektirebilir; örneğin, iletim düzenlemelerinde özel yönlendirme mantığına sahip ayrılmış bir yürütücü kullanılır.

İmlicit ve Eksplicit Oluşturma

Aracıyı WorkflowBuilder doğrudan geçirdiğinizde aracıları AgentExecutor otomatik olarak örneklere sarmalar. Çoğu iş akışı için örtük oluşturma yeterlidir:

from agent_framework import WorkflowBuilder

writer_agent = client.as_agent(name="Writer", instructions="...")
reviewer_agent = client.as_agent(name="Reviewer", instructions="...")

# Agents are automatically wrapped — no manual AgentExecutor creation required
workflow = (
    WorkflowBuilder(start_executor=writer_agent)
    .add_edge(writer_agent, reviewer_agent)
    .build()
)

Belirgin Oluşturma

Şunu yapmanız gerektiğinde açıkça bir AgentExecutor oluşturun:

Oturumu birden çok temsilci arasında paylaşın.
Yönlendirme ve hedeflenen çalıştırma zamanı parametreleri için özel bir yürütücü kimliği sağlayın.
Birden çok kenarda aynı yürütücü örneğine başvurun.

from agent_framework import AgentExecutor

writer_executor = AgentExecutor(writer_agent, id="my-writer")
reviewer_executor = AgentExecutor(reviewer_agent, id="my-reviewer")

workflow = (
    WorkflowBuilder(start_executor=writer_executor)
    .add_edge(writer_executor, reviewer_executor)
    .build()
)

Oluşturucu parametreleri:

Parametre	Türü	Açıklama
`agent`	`SupportsAgentRun`	Sarmalanacak ajan.
`session`	`AgentSession \\| None`	Ajan çalıştırmaları için kullanılacak oturum. Eğer `None` ise, ajan tarafından yeni bir oturum oluşturulur.
`id`	`str \\| None`	Benzersiz yürütücü kimliği. Varsa, varsayılan olarak ajan adını kullanır.
`context_mode`	`"full" \\| "last_agent" \\| "custom" \\| None`	Konuşma bağlamının yukarı akış aracısından bir `AgentExecutorResponse` alındığında nasıl işleneceğini denetler. `"full"`Yukarı akış aracısının tam konuşmasını (giriş + yanıt) sağlayan varsayılan değeridir. Bkz. Bağlam Modları.
`context_filter`	`Callable[[list[Message]], list[Message]] \\| None`	Eklenecek iletileri seçmek için özel filtre işlevi. `context_mode` `"custom"` olduğunda gereklidir.

Tip

Yürütücü kimliği, tek tek aracıları hedeflediğinizde veya workflow.run(function_invocation_kwargs=...) hedeflediğinizde client_kwargs= kullanılan anahtardır. atlarsanız id, iş akışı sarmalanmış aracının adını kullanır.

Giriş Türleri

, AgentExecutor her biri farklı bir giriş türü kabul eden birden çok işleyici yöntemini tanımlar. İş akışı altyapısı, ileti türüne göre doğru işleyiciyi otomatik olarak gönderir. AgentExecutorRequest hariç tüm giriş türleri ajanı hemen çalışacak şekilde tetikler; burada should_respond bayrağı ajanı çalıştırıp çalıştırmamayı veya yalnızca mesajları önbelleğe almayı kontrol eder.

Giriş Türü	İşleyici	Tetikleyici Ajan	Açıklama
`AgentExecutorRequest`	`run`	Conditional	Kurallı giriş türü. İletilerin listesi ve aracın çalışıp çalışmayacağını kontrol eden bir `should_respond` bayrak içerir.
`str`	`from_str`	Her zaman	Ham dize istemini kabul eder.
`Message`	`from_message`	Her zaman	Tek `Message` bir nesneyi kabul eder.
`list[str \\| Message]`	`from_messages`	Her zaman	Konuşma bağlamı olarak dizelerin veya `Message` nesnelerin listesini kabul eder.
`AgentExecutorResponse`	`from_response`	Her zaman	Önceki bir aracı yürütücüsünün yanıtını kabul eder ve doğrudan zincirlemeyi etkinleştirir.

AgentExecutorRequest'in Kullanımı

AgentExecutorRequest kurallı giriş türüdür ve en fazla denetimi sağlar:

from agent_framework import AgentExecutorRequest, Message

# Create a request with messages
request = AgentExecutorRequest(
    messages=[Message(role="user", contents=["Hello, world!"])],
    should_respond=True,
)

# Run the workflow
result = await workflow.run(request)

bayrağı, should_respond aracının iletileri hemen işleyip işlemediğini veya yalnızca daha sonra önbelleğe alıp almadığını denetler:

True (varsayılan) — aracı çalışır ve bir yanıt üretir.
False — iletiler önbelleğe eklenir ancak aracı çalışmaz. Bu, bir yanıtı tetiklemeden önce konuşma bağlamı önceden yüklemek için kullanışlıdır.

Çıkış ve Zincirleme

Aracı tamamlandıktan sonra yürütücü aşağı akışa bir AgentExecutorResponse gönderir. Bu veri sınıfı şunu içerir:

Veri Alanı	Türü	Açıklama
`executor_id`	`str`	Yanıtı üreten yürütücü kimliği.
`agent_response`	`AgentResponse`	Temel ajan yanıtı (istemciden değiştirilmeden).
`full_conversation`	`list[Message]`	Zincirleme için tam konuşma bağlamı (önceki girişler ve etmen çıkışları).

Aracı yürütücülerini zincirlerken, alt akış yürütücüsü, AgentExecutorResponse aracını from_response işleyicisi üzerinden alır. Varsayılan olarak, konuşma geçmişinin tamamını korumak için full_conversation alanını kullanır, böylece sonraki ajanlar önceki bağlamı kaybetmez. Bağlam modlarıyla bu davranışı değiştirebilirsiniz:

spam_detector = AgentExecutor(create_spam_detector_agent())
email_assistant = AgentExecutor(create_email_assistant_agent())

# The email_assistant receives the spam_detector's full conversation context
workflow = (
    WorkflowBuilder(start_executor=spam_detector)
    .add_edge(spam_detector, email_assistant)
    .build()
)

Akış Davranışı

AgentExecutor otomatik olarak iş akışı yürütme moduna uyar.

stream=True, agent.run(stream=True) çağrılar ve her AgentResponseUpdate'yi bir iş akışı çıkış olayı olarak verir. Akış tamamlandıktan sonra, güncellemeler aşağı yönde dağıtım için tam bir AgentResponse olarak toplanır.
stream=False(varsayılan) — agent.run(stream=False) çağrılır ve bir AgentResponse, iş akışı çıkış olayı olarak üretilir.

# Streaming mode — receive incremental updates
events = workflow.run("Write a story about a cat.", stream=True)
async for event in events:
    if event.type == "output" and isinstance(event.data, AgentResponseUpdate):
        print(event.data.text, end="", flush=True)

# Non-streaming mode — receive complete response
result = await workflow.run("Write a story about a cat.")

# Retrieve AgentResponse objects from the result
outputs = result.get_outputs()
for output in outputs:
    if isinstance(output, AgentResponse):
        print(output.text)

Bağlam Modları

Aracılar birbirine zincirlendiğinde, AgentExecutor üzerindeki context_mode parametresi from_response işleyici aracılığıyla yukarı akış aracısından bir AgentExecutorResponse aldığında, aracının hangi görüşme bağlamını tükettiğini kontrol eder.

Kullanılabilir modlar

Modül	Behavior
`"full"` (varsayılan)	Aracı, hem yukarı akış aracısına sağlanan giriş iletileri hem de yanıt iletileri olmak üzere yukarı akış aracısının tam konuşmasını tüketir.
`"last_agent"`	Aracı, yukarı akış aracısına sağlanan girişi hariç tutarak yalnızca yukarı akış aracısının yanıt iletilerini kullanır.
`"custom"`	Kullanıcı tarafından sağlanan `context_filter` bir işlev, aracının hangi iletileri tüketeceğini belirler. parametresini `context_filter` gerektirir.

`last_agent` modunu kullanma

Her bir ajan, önceki ajanının çıktısını dönüştürmeye odaklanıp önceki sohbet geçmişinden etkilenmemesi gerektiğinde "last_agent" kullanın. Bu, çeviri işlem hatları, aşamalı iyileştirme ve benzer sıralı dönüştürmeler için kullanışlıdır:

from agent_framework import AgentExecutor, WorkflowBuilder

# Each agent consumes only the previous agent's response messages
french_executor = AgentExecutor(french_agent, context_mode="last_agent")
spanish_executor = AgentExecutor(spanish_agent, context_mode="last_agent")

workflow = (
    WorkflowBuilder(start_executor=writer_agent)
    .add_edge(writer_agent, french_executor)
    .add_edge(french_executor, spanish_executor)
    .build()
)

ile context_mode="last_agent", Fransızca çevirmen yalnızca yazarın yanıt iletilerini kullanır (yazara giriş yapılan özgün kullanıcı istemi hariç) ve İspanyolca çevirici yalnızca Fransızca çeviricinin yanıt iletilerini kullanır.

Modu kullanma `custom`

Bir ajanın hangi bağlamı tükettiği üzerinde ayrıntılı denetim için, context_mode="custom" öğesini bir context_filter işlevi ile kullanın. Filtre, konuşmanın tamamını olarak list[Message] alır ve filtrelenmiş alt kümeyi döndürür:

from agent_framework import AgentExecutor, Message

def keep_user_and_last_agent(messages: list[Message]) -> list[Message]:
    """Keep only user messages and the last agent's response."""
    user_msgs = [m for m in messages if m.role == "user"]
    agent_msgs = [m for m in messages if m.role == "assistant"]
    return user_msgs + agent_msgs[-1:] if agent_msgs else user_msgs

executor = AgentExecutor(
    my_agent,
    context_mode="custom",
    context_filter=keep_user_and_last_agent,
)

SequentialBuilder'da bağlam modları

Düzenleme, SequentialBuilder tüm aracı katılımcılarını kullanacak chain_only_agent_responsesşekilde yapılandıran kullanışlı context_mode="last_agent" bir parametre sağlar, böylece her aracı yalnızca önceki aracının yanıt iletilerini kullanır:

from agent_framework.orchestrations import SequentialBuilder

workflow = SequentialBuilder(
    participants=[writer, translator, reviewer],
    chain_only_agent_responses=True,
).build()

Tam bir örnek için bkz. Agent Framework deposundaki sequential_chain_only_agent_responses.py .

Paylaşılan Oturumlar

Varsayılan olarak, her AgentExecutor biri kendi oturumunu oluşturur. Bir oturumu birden fazla temsilci arasında paylaşmak için (örneğin, ortak bir konuşma yazışmasını sürdürmek amacıyla), oturumu açıkça oluşturun ve her bir yürütücüye iletin.

from agent_framework import AgentExecutor

# Create a shared session from one agent
shared_session = writer_agent.create_session()

# Both executors share the same session
writer_executor = AgentExecutor(writer_agent, session=shared_session)
reviewer_executor = AgentExecutor(reviewer_agent, session=shared_session)

Uyarı

Tüm aracılar paylaşılan oturumları desteklemez. Genellikle, yalnızca aynı sağlayıcı türündeki aracılar bir oturumu paylaşabilir.

Kontrol noktası oluşturma

, AgentExecutor uzun süre çalışan iş akışlarında durum kaydetme ve geri yükleme için denetim noktası oluşturmayı destekler. Denetim noktası alındığında yürütücü serileştirme işlemi yapar:

İç ileti önbelleği.
Konuşma geçmişinin tamamı.
Aracı oturum durumu.
Bekleyen tüm kullanıcı giriş istekleri ve yanıtları.

Geri yüklemede yürütücü bu durumu seri durumdan çıkararak iş akışının kaldığı yerden devam etmesini sağlar.

Uyarı

Sunucu tarafı oturumları (gibi FoundryAgent) kullanan aracılarla denetim noktası oluşturmanın sınırlamaları vardır. Sunucu tarafı oturum durumu denetim noktalarında yakalanmaz ve sonraki çalıştırmalar tarafından değiştirilebilir. Sunucu tarafı oturumlarla güvenilir denetim noktalarına ihtiyacınız varsa özel bir yürütücü uygulamayı göz önünde bulundurun.

Sonraki Adımlar

İş Akışlarında Aracılar

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-05-11

Aracı Yürütücüsü

Genel bakış

Nasıl Çalışır?

İmlicit ve Eksplicit Oluşturma

Özel Yapılandırma

Giriş Türleri

Çıkış ve Zincirleme

Akış Davranışı

Paylaşılan Oturumlar

Yapılandırma Seçenekleri

Kontrol noktası oluşturma

Nasıl Çalışır?

İmlicit ve Eksplicit Oluşturma

Belirgin Oluşturma

Giriş Türleri

AgentExecutorRequest'in Kullanımı

Çıkış ve Zincirleme

Akış Davranışı

Bağlam Modları

Kullanılabilir modlar

last_agent modunu kullanma

Modu kullanma custom

SequentialBuilder'da bağlam modları

Paylaşılan Oturumlar

Kontrol noktası oluşturma

Sonraki Adımlar

Geri Bildirim

Ek kaynaklar

`last_agent` modunu kullanma

Modu kullanma `custom`