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

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:

1. İ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.
2. Belirteç tetikleyicisini döndürme — aracı önbelleğe alınan iletilerini yalnızca aldıktan TurnTokensonra işler.
3. Aracı çağırma — yürütücü, temel aracı üzerinde RunAsync (akış dışı) veya RunStreamingAsync (akış) yöntemlerini çağırır.
4. Çı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.
5. Aşağı akış mesajlaşması — aracının yanıt iletileri bağlı aşağı akış yürütücülerine gönderilir.
6. 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.

İ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ü:

1. Aracının yanıt iletilerini tüm bağlı aşağı akış çalıştırıcılarına gönderir.
2. 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:

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:

1. İ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.
2. 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.
3. Çıkış emisyonu — akış modunda her AgentResponseUpdate biri bir iş akışı çıkış olayı olarak sunulur. Akışsız modda, yalnızca tek bir AgentResponse üretilir.
4. 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.
5. Ö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.

İ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:

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.

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:

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 terminal AgentResponse objects from the result
outputs = result.get_outputs()
for output in outputs:
    if isinstance(output, AgentResponse):
        print(output.text)

# Retrieve intermediate outputs (progress / observational emissions)
intermediate_outputs = result.get_intermediate_outputs()
for item in intermediate_outputs:
    print(f"Intermediate: {item}")

Bağlam Modları

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

Kullanılabilir modlar

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.

custom modunu kullanma

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)

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.

Nasıl Çalışır?

Go, aracıları workflow/agentworkflow ile iş akışı yürütücüleri olarak barındırır. Barındırılan yürütücü aşağıdaki dönüş belirteci desenini kullanır:

1. Mesaj arabelleğe alma — diğer işleyicilerden mesajlar geldikçe, barındırılan aracı bunları toplar. İleti iletme etkinse (varsayılan), gelen iletiler de aşağı akış yürütücülerine iletilir.
2. Belirteç tetikleyicisini döndürme — barındırılan aracı önbelleğe alınmış iletilerini yalnızca aldıktan workflow.TurnTokensonra işler.
3. Aracı çağırma — yürütücü, temel aracıyı Run aracılığıyla çağırır ve akış davranışını agentworkflow.Config ya da TurnToken içinden seçer.
4. Çıkış verme — güncelleştirme olayları etkinleştirildiyse, her *agent.ResponseUpdate biri bir iş akışı çıkışı olarak sunulur. Yanıt olayları etkinleştirilirse, toplanan *agent.Response iş akışı çıkışı olarak sunulur.
5. Aşağı akış mesajlaşması — aracının yanıt iletileri bağlı aşağı akış yürütücülerine gönderilir.
6. Tur belirteci aktarma — tur tamamlandıktan sonra yürütücü, sıradaki barındırılan aracının işlemeye başlayabilmesi için aşağı akışa yeni bir workflow.TurnToken gönderir.

Özel Yapılandırma

agentworkflow.New ve bir agentworkflow.Config değeriyle bağlama oluşturarak barındırılan ajan yürütücüsünün nasıl davranacağını özelleştirin:

hostedAgent := agentworkflow.New(myAgent, agentworkflow.Config{
    EmitUpdateEvents: true,
    DisableForwardIncomingMessages: true,
})

wf, err := workflow.NewBuilder(hostedAgent).
    WithOutputFrom(hostedAgent).
    Build()
if err != nil {
    return err
}

Giriş Türleri

Barındırılan ajan yürütücüsü, string, *message.Message, []*message.Message ve iter.Seq[*message.Message] girdilerini kabul eder. Dize girdileri, User rolüne sahip message.Message örneklerine dönüştürülür. Mesaj girdileri, yürütücü bir workflow.TurnToken alana kadar arabelleğe alınır; bu da barındırılan temsilcinin biriken toplu işi işlemesini tetikler.

run, err := inproc.Default.RunStreaming(ctx, wf, nil)
if err != nil {
    return err
}
defer run.Close(ctx)

if err := run.SendMessage(ctx, "Summarize this deployment plan."); err != nil {
    return err
}
if err := run.SendMessage(ctx, message.NewText("Include risk notes.")); err != nil {
    return err
}
if err := run.SendMessage(ctx, []*message.Message{message.NewText("Keep it concise.")}); err != nil {
    return err
}

emitEvents := true
if err := run.SendMessage(ctx, workflow.TurnToken{EmitEvents: &emitEvents}); err != nil {
    return err
}

Çıkış ve Zincirleme

Barındırılan aracı, turunu tamamladıktan sonra bağlı alt akış yürütücülerine aracının yanıt iletilerini ve yeni bir tur belirtecini gönderir. Bu, zincirleme aracılarını basitleştirir:

french := agentworkflow.New(frenchAgent, agentworkflow.Config{})
spanish := agentworkflow.New(spanishAgent, agentworkflow.Config{})
english := agentworkflow.New(englishAgent, agentworkflow.Config{})

wf, err := workflow.NewBuilder(french).
    AddEdge(french, spanish).
    AddEdge(spanish, english).
    Build()
if err != nil {
    return err
}

Akış Davranışı

Aracı yanıtı güncellemelerini iş akışı çıktı olayları aracılığıyla yayınlamak için, agentworkflow.Config üzerinde EmitUpdateEvents ayarlayın veya EmitEvents ayarlanmış olarak bir workflow.TurnToken gönderin.

hostedAgent := agentworkflow.New(myAgent, agentworkflow.Config{
    EmitUpdateEvents: true,
})

wf, err := workflow.NewBuilder(hostedAgent).
    WithOutputFrom(hostedAgent).
    Build()
if err != nil {
    return err
}

run, err := inproc.Default.RunStreaming(ctx, wf, message.NewText("Write a status update."))
if err != nil {
    return err
}
defer run.Close(ctx)

emitEvents := true
if err := run.SendMessage(ctx, workflow.TurnToken{EmitEvents: &emitEvents}); err != nil {
    return err
}

for evt, err := range run.WatchStream(ctx) {
    if err != nil {
        return err
    }
    if output, ok := evt.(workflow.OutputEvent); ok {
        if update, ok := output.Output.(*agent.ResponseUpdate); ok {
            fmt.Print(update.String())
        }
    }
}

Yapılandırma Seçenekleri

agentworkflow.Config barındırılan aracı yürütücüsunun davranışını denetler:

hostedAgent := agentworkflow.New(myAgent, agentworkflow.Config{
    EmitUpdateEvents:                  true,
    EmitResponseEvents:                true,
    InterceptUserInputRequests:        true,
    InterceptUnterminatedFunctionCalls: true,
    DisableReassignOtherAgentsAsUsers: false,
    DisableForwardIncomingMessages:    false,
})

Kontrol noktası oluşturma

Barındırılan aracılar, iş akışı denetim noktası oluşturmaya katılır. agentworkflow.New denetim noktasını kaydeder ve yürütücüye kancaları geri yükler. Bir denetim noktası alındığında konak şunları depolar:

• Barındırılan aracının agent.Session JSON durumu.
• Geçerli dönüşün olay emisyonu ayarı.
• Beklemedeki araç onayı ve işlev çağrısı isteğinin durumu.

Geri yükleme sırasında ana bilgisayar, iş akışı devam etmeden önce aracı oturumunu yeniden oluşturur ve bekleyen istek işleyicilerini geri yükler. Denetim noktası oluşturmayı iş akışı yürütme ortamı aracılığıyla etkinleştirin; örneğin inproc.Default.WithCheckpointing(...) ile, agentworkflow.Config seçeneği gerekmez.

checkpointManager := checkpoint.NewInMemoryManager()
environment := inproc.Default.WithCheckpointing(checkpointManager)

var checkpoints []workflow.CheckpointInfo
run, err := environment.RunStreaming(ctx, wf, message.NewText("Start the review."))
if err != nil {
    return err
}
defer run.Close(ctx)

emitEvents := true
if err := run.SendMessage(ctx, workflow.TurnToken{EmitEvents: &emitEvents}); err != nil {
    return err
}

for evt, err := range run.WatchUntilHalt(ctx) {
    if err != nil {
        return err
    }
    if completed, ok := evt.(workflow.SuperStepCompletedEvent); ok && completed.CompletionInfo != nil {
        if completed.CompletionInfo.CheckpointInfo != nil {
            checkpoints = append(checkpoints, *completed.CompletionInfo.CheckpointInfo)
        }
    }
}

if len(checkpoints) == 0 {
    return fmt.Errorf("no checkpoints were created")
}

resumedRun, err := environment.ResumeStreaming(ctx, wf, checkpoints[len(checkpoints)-1])
if err != nil {
    return err
}
defer resumedRun.Close(ctx)