Ügynök végrehajtó

Amikor AI-ügynököt ad hozzá egy munkafolyamathoz, azt egy végrehajtóba kell burkolni, hogy a munkafolyamat-motor átirányíthassa az üzeneteket, kezelheti a munkamenet állapotát, és kezelheti a kimenetét. Az ügynök-végrehajtó az adaptációt kezelő beépített végrehajtó.

Áttekintés

Az ügynök-végrehajtó áthidalja az ügynök absztrakciója és a munkafolyamat-végrehajtási modell közötti szakadékot. Ez:

Beírt üzeneteket fogad a munkafolyamat-gráfból, és továbbítja őket a mögöttes ügynöknek.
Kezeli az ügynök munkamenet- és beszélgetési állapotát a futtatások között.
A munkafolyamat-végrehajtási mód (streamelés vagy nem streamelés) alapján igazítja a viselkedését.
Kimenetes eseményeket (AgentResponse vagy AgentResponseUpdate) ad vissza a munkafolyamat-hívónak megfigyelés céljából.
Üzeneteket küld a csatlakoztatott alsóbb rétegbeli végrehajtóknak a gráfon belüli folyamatos feldolgozás céljából.
Támogatja a hosszú ideig futó munkafolyamatok ellenőrzőpontozását.

Hogyan működik?

A C#-ban a munkafolyamat-motor belsőleg létrehoz egy AIAgentHostExecutor minden egyes AIAgent számára, amelyet hozzáadnak egy munkafolyamathoz. Ez a speciális végrehajtó kiterjeszti ChatProtocolExecutor és használja a turn token mintát:

Üzenetek gyorsítótárazása – az ügynöki végrehajtó összegyűjti azokat, amikor más végrehajtóktól érkeznek az üzenetek. Ha ForwardIncomingMessages engedélyezve van (az alapértelmezett), a rendszer a bejövő üzeneteket is továbbítja az alsóbb rétegbeli végrehajtóknak.
Turn token trigger – az ügynök csak egy TurnToken fogadása után dolgozza fel a gyorsítótárazott üzeneteket.
Ügynökhívás – a végrehajtó meghívja RunAsync (nem streameli) vagy RunStreamingAsync (streameli) a mögöttes ügynököt.
Kimeneti eredmény – ha engedélyezve vannak a streamelési események, minden növekményes AgentResponseUpdate kimenet munkafolyamat-kimenetként lesz kiállítva. Ha EmitAgentResponseEvents engedélyezve van, az összesítés AgentResponse munkafolyamat-kimenetként is létrejön.
Alsóbb rétegbeli üzenetküldés – az ügynök válaszüzenetei a csatlakoztatott alárendelt végrehajtóknak lesznek elküldve.
A jogkivonat átadása – a sor befejezése után a végrehajtó egy új TurnToken alsóbb réteget küld, hogy a lánc következő ügynöke megkezdhesse a feldolgozást.

Jótanács

Egyes forgatókönyvek esetében speciálisabb ügynök-végrehajtóra lehet szükség; Az átadási vezénylések például dedikált HandoffAgentExecutor , egyéni útválasztási logikát használnak.

Implicit és explicit létrehozás

Amikor átad egy AIAgent-t WorkflowBuilder-nek, a keretrendszer automatikusan becsomagolja egy AIAgentBinding-be, amely létrehozza az alapul szolgáló AIAgentHostExecutor-t. Nem szükséges közvetlenül példányosítani az ügynök végrehajtót.

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();

A segítő módszereket AgentWorkflowBuilder a gyakori mintákhoz is használhatja:

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

Egyéni konfiguráció

Az ügynök végrehajtójának viselkedésének testreszabásához használja a következőt BindAsExecutorAIAgentHostOptions:

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();

Bemeneti típusok

A C# ügynök-végrehajtója több bemeneti típust is elfogad: string, ChatMessageés IEnumerable<ChatMessage>. A sztringbemenetek automatikusan a ChatMessage szerepkörrel rendelkező User példányokká alakulnak. Az összes bejövő üzenet halmozódik fel, amíg meg nem érkezik egy TurnToken, és ekkor a végrehajtó feldolgozza a köteget. Ha ReassignOtherAgentsAsUsers engedélyezve van (az alapértelmezett), a rendszer a többi ügynöktől érkező üzeneteket hozzárendeli a User szerepkörhöz, így az alapul szolgáló modell felhasználói bemenetként kezeli őket, míg az aktuális ügynöktől érkező üzenetek megtartják a szerepkört Assistant .

Kimenet és láncolás

Miután az ügynök befejezte a körét, a végrehajtó:

Elküldi az ügynök válaszüzeneteit az összes csatlakoztatott alárendelt végrehajtónak.
Továbbít egy újat TurnToken , hogy a lánc következő ügynöke megkezdhesse a feldolgozást.

Ez egyszerűvé teszi a láncoló ügynököket – egyszerűen csatlakoztassa őket a szélekhez:

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

Streamelési viselkedés

A streamelési viselkedést a EmitAgentUpdateEvents opció AIAgentHostOptions szabályozza, vagy dinamikusan a TurnToken útján:

Ha engedélyezve van , a végrehajtó meghívja RunStreamingAsync az ügynököt, és mindegyik AgentResponseUpdate munkafolyamat-kimeneti eseményként jelenik meg. Ez valós idejű tokenenkénti frissítéseket biztosít.
Ha le van tiltva – a végrehajtó meghívja RunAsync, és egyetlen teljes választ hoz létre.

// 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));

Megosztott munkamenetek

Minden ügynök-végrehajtó alapértelmezés szerint saját munkamenetet tart fenn. Ha meg szeretne osztani egy munkamenetet az ügynökök között, konfigurálja az ügynököket egy közös munkamenet-szolgáltatóval, mielőtt hozzáadja őket a munkafolyamathoz.

Konfigurációs beállítások

AIAgentHostOptions szabályozza az ügynök végrehajtójának viselkedését:

Lehetőség	Alapértelmezett	Leírás
`EmitAgentUpdateEvents`	`null`	Streamelési frissítési eseményeket bocsát ki a végrehajtás során. `TurnToken` beállítás esetén elsőbbséget élvez. Ha mindkettő van `null`, a streamelés le van tiltva.
`EmitAgentResponseEvents`	`false`	Adja ki az összesített ügynökválaszt munkafolyamat-kimeneti eseményként.
`InterceptUserInputRequests`	`false`	Elfogja `UserInputRequestContent` és átirányítja munkafolyamat-üzenetként a kezeléshez.
`InterceptUnterminatedFunctionCalls`	`false`	A megfelelő eredmény nélküli `FunctionCallContent` elfogása és munkafolyamat-üzenetként történő továbbítása.
`ReassignOtherAgentsAsUsers`	`true`	Más ügynököktől érkező üzenetek hozzárendelése a `User` szerepkörhöz, hogy a modell felhasználói bemenetként kezelje őket.
`ForwardIncomingMessages`	`true`	A bejövő üzenetek továbbítása az alsóbb rétegbeli végrehajtóknak az ügynök által generált üzenetek előtt.

Ellenőrző pontok használata

Az ügynök-végrehajtó támogatja a hosszú ideig futó munkafolyamatok ellenőrzőpont-használatát. Ellenőrzőpont létrehozásakor a végrehajtó szerializálja a következőt:

Az ügynök munkamenet-állapota (via SerializeSessionAsync).
Az aktuális kör eseménykibocsátási konfigurációja (csak akkor jelenik meg, ha a kérelmek függőben vannak, és a végrehajtó még nem dolgozta fel a bejövő adatokat TurnToken).
Függőben lévő felhasználói bevitelkérések és függvényhívási kérések.

A visszaállítás során a végrehajtó deszerializálja a munkamenetet és a függőben lévő kérés állapotát, így a munkafolyamat onnan folytatódhat, ahonnan abbahagyta.

Hogyan működik?

A AgentExecutor osztály körülvesz egy ügynököt, amely a SupportsAgentRun protokollt implementálja. Amikor a végrehajtó üzenetet kap:

Üzenet normalizálása – a bemenet normalizálódik az objektumok listájában Message , és hozzáadódik a végrehajtó belső gyorsítótárához. A végrehajtó több bemeneti típust fogad el – str, Message, list[str | Message], AgentExecutorRequest és AgentExecutorResponse –, amelyek mindegyike egy dedikált kezelőhöz van irányítva, amely normalizálja a bemenetet a gyorsítótárazás előtt.
Ügynökhívás – a végrehajtó a gyorsítótárazott üzenetekkel hívja meg a hívásokat agent.run() , és automatikusan kiválasztja a streamelési vagy nem streamelési módot a munkafolyamat-végrehajtási mód alapján.
Kimeneti kibocsátás – streamelési módban mindegyik AgentResponseUpdate munkafolyamat-kimeneti eseményként lesz kibocsátva. Nem streamelési módban a szolgáltatás egyetlen egy AgentResponse eredményt ad.
Alsóbb rétegbeli küldés – az ügynök befejeződése után a végrehajtó egy üzenetet AgentExecutorResponse küld az összes csatlakoztatott alsóbb rétegbeli végrehajtónak. Ez a válasz magában foglalja a beszélgetés teljes előzményeit, lehetővé téve a zökkenőmentes összefűzést.
Gyorsítótár alaphelyzetbe állítása – A végrehajtó belső üzenetgyorsítótára az ügynök meghívása után törlődik, biztosítva, hogy minden ügynökhívás csak az utolsó hívás óta beérkezett új üzeneteket dolgozza fel.

Jótanács

Egyes forgatókönyvek esetében speciálisabb ügynök-végrehajtóra lehet szükség; Az átadási vezénylések például egy dedikált végrehajtót használnak egyéni útválasztási logikával.

Implicit és explicit létrehozás

A WorkflowBuilder automatikusan becsomagolja az ügynököket AgentExecutor példányokba, amikor közvetlenül adja át az ügynököt. A legtöbb munkafolyamat esetében elegendő az implicit létrehozás:

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()
)

Explicit létrehozás

Hozzon létre explicit módon, AgentExecutor amikor a következőkre van szüksége:

Munkamenet megosztása több ügynök között.
Adjon meg egy egyéni végrehajtóazonosítót az útválasztáshoz és a célzott futtatókörnyezeti kwargokhoz.
Hivatkozzon ugyanarra a végrehajtópéldányra több élben.

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()
)

Konstruktorparaméterek:

Paraméter	Típus	Leírás
`agent`	`SupportsAgentRun`	A burkolni kívánt ügynök.
`session`	`AgentSession \\| None`	Ügynök futtatásához használt munkamenet. Ha `None`, az ügynök új munkamenetet hoz létre.
`id`	`str \\| None`	Egyedi végrehajtóazonosító. Alapértelmezés szerint az ügynök neve, ha elérhető.
`context_mode`	`"full" \\| "last_agent" \\| "custom" \\| None`	A beszélgetési környezet kezelésének módját szabályozza, amikor egy felsőbb rétegbeli ügynöktől kap egy `AgentExecutorResponse` beszélgetést. Alapértelmezett érték, `"full"`amely biztosítja a felsőbb rétegbeli ügynök teljes beszélgetését (bemenet + válasz). Lásd környezetmódok.
`context_filter`	`Callable[[list[Message]], list[Message]] \\| None`	Egyéni szűrőfüggvény a belefoglalandó üzenetek kiválasztásához. Kötelező, ha `context_mode` van `"custom"`.

Jótanács

A végrehajtó azonosítója az a kulcs is, amelyet akkor használnak, amikor workflow.run(function_invocation_kwargs=...) vagy client_kwargs= célpontként megadása történik egyes ügynökök számára. Ha kihagyja id, a munkafolyamat a burkolt ügynök nevét használja.

Bemeneti típusok

Ez AgentExecutor több kezelőmetelyt határoz meg, mindegyik más bemeneti típust fogad el. A munkafolyamat-motor automatikusan küldi el a megfelelő kezelőt az üzenettípus alapján. Minden bemeneti típus aktiválja az ügynököt, hogy azonnal fusson, kivéve AgentExecutorRequest , ha a should_respond jelző szabályozza, hogy az ügynök fut-e, vagy egyszerűen gyorsítótárazza az üzeneteket:

Bemeneti típus	Kezelő	Eseményindítók ügynök	Leírás
`AgentExecutorRequest`	`run`	Conditional	A bemenet kanonikus típusa. Egy üzenetlistát és egy jelölőt `should_respond` tartalmaz, amely meghatározza, hogy az ügynök fut-e.
`str`	`from_str`	Mindig	Egy nyers sztringre vonatkozó kérést fogad el.
`Message`	`from_message`	Mindig	Egyetlen `Message` objektumot fogad el.
`list[str \\| Message]`	`from_messages`	Mindig	A sztringek vagy `Message` objektumok listáját fogadja el beszélgetési környezetként.
`AgentExecutorResponse`	`from_response`	Mindig	Elfogadja egy korábbi ügynök végrehajtójának válaszát, amely lehetővé teszi a közvetlen láncolást.

Az AgentExecutorRequest használata

A AgentExecutorRequest a kanonikus bemeneti típus, és a legnagyobb kontrollt biztosítja.

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)

A should_respond jelző azt szabályozza, hogy az ügynök azonnal feldolgozza-e az üzeneteket, vagy egyszerűen gyorsítótárazza őket későbbre:

True (alapértelmezett) – az ügynök futtatja és létrehozza a választ.
False — az üzenetek hozzáadódnak a cache-hez, de az ügynök nem fut. Ez akkor hasznos, ha a válasz aktiválása előtt előre betölti a beszélgetési környezetet.

Kimenet és láncolás

Az ügynök feladata befejeztével a végrehajtó egy downstream AgentExecutorResponse küld. Ez az adatosztály a következőket tartalmazza:

szakterület	Típus	Leírás
`executor_id`	`str`	A választ előállító végrehajtó azonosítója.
`agent_response`	`AgentResponse`	A mögöttes ügynök válasza (változatlan az ügyfél részéről).
`full_conversation`	`list[Message]`	A láncolás teljes beszélgetési környezete (korábbi bemenetek + ügynökkimenetek).

Az ügynök-végrehajtók láncolásakor az alsóbb rétegbeli végrehajtó megkapja a AgentExecutorResponse kezelőn keresztül.from_response Alapértelmezés szerint a full_conversation mezőt használja a teljes beszélgetési előzmények megőrzésére, megakadályozva, hogy az utólagos ügynökök elveszítsék a korábbi kontextust. Ezt a viselkedést a környezetmódokkal módosíthatja:

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()
)

Streamelési viselkedés

Az AgentExecutor automatikusan alkalmazkodik a munkafolyamat végrehajtási módjához:

stream=True — meghívja agent.run(stream=True) és minden AgentResponseUpdate munkafolyamat-kimeneti eseményként átad. A streamelés befejezése után a rendszer a frissítéseket teljes AgentResponse egészében összesíti az alsóbb rétegbeli küldéshez.
stream=False(alapértelmezett) – meghívja a agent.run(stream=False)-t és egyetlen AgentResponse-t ad meg munkafolyamat-kimeneti eseményként.

# 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}")

Kontextus módok

Ha az ügynökök össze vannak láncolva, a context_mode paraméter AgentExecutor szabályozza, hogy az ügynök milyen beszélgetési környezetet használ, amikor a feljebb lévő ügynöktől kap egy AgentExecutorResponse a from_response kezelőn keresztül.

Elérhető módok

Mód	Behavior
`"full"` (alapértelmezett)	Az ügynök a felsőbb rétegbeli ügynök teljes beszélgetését használja fel – mind a felsőbb rétegbeli ügynöknek küldött bemeneti üzeneteket, mind a válaszüzeneteket.
`"last_agent"`	Az ügynök csak a felsőbb rétegbeli ügynök válaszüzeneteit használja fel, kivéve a felsőbb rétegbeli ügynöknek küldött bemenetet.
`"custom"`	A felhasználó által megadott `context_filter` függvény határozza meg, hogy az ügynök mely üzeneteket használja fel. Ehhez a paraméterre `context_filter` van szükség.

`last_agent` mód használata

Akkor használható "last_agent" , ha minden ügynöknek kizárólag az előző ügynök kimenetének átalakítására kell összpontosítania, anélkül, hogy a korábbi beszélgetési fordulatok befolyásolták volna. Ez a fordítási folyamatok, a fokozatos pontosítás és a hasonló szekvenciális átalakítások esetében hasznos:

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()
)

A context_mode="last_agent"francia fordító csak az író válaszüzeneteit használja fel (kivéve az eredeti felhasználói kérést, amely az íróhoz került), a spanyol fordító pedig csak a francia fordító válaszüzeneteit használja fel.

`custom` mód használata

Az ügynök által használt környezet részletes szabályozásához használjon context_mode="custom" függvényt context_filter . A szűrő teljes egészében fogadja a beszélgetést list[Message], és a szűrt részhalmazt adja vissza:

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,
)

Környezeti módok a SequentialBuilderben

A SequentialBuilder orkesztráció egy kényelmes chain_only_agent_responses paramétert biztosít, amely konfigurálja az összes ügynök résztvevőjét, hogy használják context_mode="last_agent", így minden ügynök csak az előző ügynök válaszüzeneteit használja:

from agent_framework.orchestrations import SequentialBuilder

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

Egy teljes példáért lásd a sequential_chain_only_agent_responses.py fájlt az Agent Framework adattárában.

Megosztott munkamenetek

Alapértelmezés szerint mindegyik AgentExecutor létrehozza a saját munkamenetét. Ha több ügynök közötti munkamenetet szeretne megosztani (például egy közös beszélgetési szál fenntartásához), hozzon létre egy munkamenetet explicit módon, és adja át az egyes végrehajtóknak:

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)

Megjegyzés:

Nem minden ügynök támogatja a megosztott munkameneteket. Általában csak az azonos szolgáltatótípusú ügynökök oszthatnak meg munkameneteket.

Ellenőrző pontok használata

A AgentExecutor támogatja az állapot mentéséhez és visszaállításához szükséges ellenőrzőpontokat a hosszú ideig futó munkafolyamatokban. Ellenőrzőpont létrehozásakor a végrehajtó szerializálja a következőt:

A belső üzenet tároló.
A teljes beszélgetési előzmény.
Az ügynök munkamenetének állapota.
Függőben lévő felhasználói bemeneti kérések és válaszok.

A visszaállítás során a végrehajtó deszerializálja ezt az állapotot, így a munkafolyamat onnan folytatódhat, ahonnan abbahagyta.

Figyelmeztetés

A kiszolgálóoldali munkameneteket (például FoundryAgent) használó ügynökökkel való ellenőrzés korlátozásokkal rendelkezik. A kiszolgálóoldali munkamenet állapota nincs rögzítve az ellenőrzőpontokban, és az azt követő futtatásokkal módosítható. Érdemes lehet egyéni végrehajtót implementálni, ha megbízható ellenőrzőpontozásra van szüksége a kiszolgálóoldali munkamenetekkel.

Következő lépések

Ügynökök a munkafolyamatokban

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-05-11

Ügynök végrehajtó

Áttekintés

Hogyan működik?

Implicit és explicit létrehozás

Egyéni konfiguráció

Bemeneti típusok

Kimenet és láncolás

Streamelési viselkedés

Megosztott munkamenetek

Konfigurációs beállítások

Ellenőrző pontok használata

Hogyan működik?

Implicit és explicit létrehozás

Explicit létrehozás

Bemeneti típusok

Az AgentExecutorRequest használata

Kimenet és láncolás

Streamelési viselkedés

Kontextus módok

Elérhető módok

last_agent mód használata

custom mód használata

Környezeti módok a SequentialBuilderben

Megosztott munkamenetek

Ellenőrző pontok használata

Következő lépések

Visszajelzés

További források

`last_agent` mód használata

`custom` mód használata