Exekutor agenta

Když do pracovního postupu přidáte agenta AI, musí být zabalený do exekutoru, aby modul pracovního postupu mohl směrovat zprávy do něj, spravovat stav relace a zpracovávat jeho výstup. Agent Executor je integrovaný exekutor, který zpracovává tuto adaptaci.

Přehled

Agent Executor přemísní mezeru mezi abstrakcí agenta a modelem provádění pracovního postupu. Ono:

Přijímá zadané zprávy z grafu pracovního postupu a předává je podkladovému agentu.
Spravuje stav relace a konverzační stav agenta mezi spuštěními.
Přizpůsobí své chování podle režimu provádění pracovního postupu (streamování nebo nestreamování).
Poskytuje výstupní události (AgentResponse nebo AgentResponseUpdate) volajícímu pracovního postupu pro pozorování.
Odesílá zprávy připojeným podřízeným exekutorům pro průběžné zpracování v grafu.
Podporuje vytváření kontrolních bodů pro dlouhotrvající pracovní postupy.

Jak to funguje

V jazyce C# modul pracovního postupu interně vytvoří pro každý AIAgentHostExecutor přidaný AIAgent pracovní postup. Tento specializovaný exekutor rozšiřuje ChatProtocolExecutor a používá vzor tokenu turn :

Ukládání zpráv do mezipaměti – když zprávy přicházejí z jiných exekutorů, exekutor agent je shromažďuje. Pokud ForwardIncomingMessages je tato možnost povolená (výchozí), příchozí zprávy se přeposílají také podřízeným exekutorům.
Aktivační událost tokenu turn – agent zpracovává zprávy uložené v mezipaměti až po přijetí TurnToken.
Vyvolání agenta – vykonavatel volá RunAsync (bez streamingu) nebo RunStreamingAsync (streaming) na podkladovém agentovi.
Výsledek výstupu – pokud jsou povolené události streamování, každý přírůstkový AgentResponseUpdate výstup se vrátí jako výstup pracovního postupu. Pokud EmitAgentResponseEvents je tato možnost povolená, agregovaná AgentResponse hodnota se také zobrazí jako výstup pracovního postupu.
Zasílání zpráv po toku dolů – odpovědní zprávy agenta se odesílají do připojených exekutorů po toku dolů.
Předání tokenu – po dokončení svého tahu exekutor odešle nový TurnToken dále po proudu, aby další agent v řetězci mohl začít zpracovávat.

Návod

Některé scénáře mohou vyžadovat specializovanějšího vykonavatele agenta; například orchestrace předání používají vyhrazený HandoffAgentExecutor s vlastní logikou směrování.

Implicitní a explicitní vytvoření

Když předáte AIAgent do WorkflowBuilder, rámec ho automaticky zabalí do AIAgentBinding, což vytvoří základní AIAgentHostExecutor. Není nutné instancovat exekutor agenta přímo.

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

Pomocné metody AgentWorkflowBuilder můžete použít také pro běžné vzory:

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

Vlastní konfigurace

Pokud chcete přizpůsobit chování exekutoru agenta, použijte BindAsExecutor s AIAgentHostOptions:

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

Vstupní typy

Exekutor agenta v jazyce C# přijímá více typů vstupu: string, ChatMessagea IEnumerable<ChatMessage>. Řetězcové vstupy se automaticky převedou na ChatMessage instance s User rolí. Všechny příchozí zprávy se shromáždí, dokud není přijato TurnToken, kdy spouštěč zpracuje dávku. Pokud je ReassignOtherAgentsAsUsers povoleno (výchozí), zprávy z jiných agentů se znovu přiřazují k roli User, aby s nimi podkladový model zacházel jako se vstupy uživatelů, zatímco zprávy od aktuálního agenta zachovají roli Assistant.

Výstup a řetězení

Jakmile agent dokončí svoji operaci, exekutor:

Odešle agentovy odpovědi všem připojeným podřízeným vykonavatelům.
Předá novou TurnToken, aby další agent v řetězci mohl začít se zpracováním.

Díky tomu je řetězení agentů jednoduché – jednoduše je propojte hranami.

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

Chování streamování

Chování streamování je řízeno EmitAgentUpdateEvents možností na AIAgentHostOptions, nebo dynamicky prostřednictvím TurnToken:

Pokud je povoleno – exekutor volá RunStreamingAsync na agentovi a každý AgentResponseUpdate vrátí jako výstupní událost pracovního postupu. Poskytuje aktualizace jednotlivých tokenů v reálném čase.
Když je zakázáno – vykonavatel volá a vytvoří jedinou úplnou odpověď.

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

Sdílené relace

Každý exekutor agenta ve výchozím nastavení udržuje vlastní relaci. Pokud chcete sdílet relaci mezi agenty, před přidáním do pracovního postupu nakonfigurujte agenty s běžným poskytovatelem relací.

Možnosti konfigurace

AIAgentHostOptions ovládá chování spouštěče agenta:

Možnost	Výchozí	Description
`EmitAgentUpdateEvents`	`null`	Generování událostí aktualizace streamování během provádění `TurnToken` má přednost, pokud je nastavena. Pokud jsou oba `null`, streamování je zakázáno.
`EmitAgentResponseEvents`	`false`	Vygenerujte agregovanou odpověď agenta jako výstupní událost pracovního postupu.
`InterceptUserInputRequests`	`false`	Zachyťte `UserInputRequestContent` a směrujte to jako zprávu pracovního postupu ke zpracování.
`InterceptUnterminatedFunctionCalls`	`false`	Zachyťte `FunctionCallContent` bez odpovídajícího výsledku; přesměrujte je jako zprávu pracovního postupu.
`ReassignOtherAgentsAsUsers`	`true`	Znovu přiřaďte zprávy z jiných agentů k `User` roli, aby s nimi model zachází jako se vstupy uživatelů.
`ForwardIncomingMessages`	`true`	Před vygenerovanými zprávami agenta přeposílejte příchozí zprávy do podřízených vykonavatelů.

Vytváření kontrolních bodů

Exekutor agenta podporuje vytváření kontrolních bodů pro dlouhotrvající pracovní postupy. Při vytvoření kontrolního bodu vykonavatel provádí serializaci:

Stav sezení agenta (prostřednictvím SerializeSessionAsync).
Konfigurace emisí událostí aktuálního turnu (pouze v době, kdy jsou požadavky čekající na vyřízení a exekutor ještě nepředal svůj příchozí TurnToken).
Všechny nevyřízené žádosti o zadání uživatele a žádosti o volání funkcí.

Při obnovení exekutor deserializuje relaci a stav čekající žádosti, což umožňuje pracovnímu postupu pokračovat tam, kde skončil.

Jak to funguje

Třída AgentExecutor zabalí agenta, který implementuje SupportsAgentRun protokol. Když exekutor obdrží zprávu:

Normalizace zpráv – vstup je normalizován do seznamu Message objektů a přidán do interní mezipaměti exekutoru. Exekutor přijímá více vstupních typů – str, Message, list[str | Message]AgentExecutorRequest, a AgentExecutorResponse – každý směrovaný na vyhrazenou obslužnou rutinu, která normalizuje vstup před uložením do mezipaměti.
Vyvolání agenta – volání exekutoru agent.run() se zprávami uloženými v mezipaměti, automaticky vybírá režim streamování nebo režimu bez streamování na základě režimu provádění pracovního postupu.
Výstupní emise – v režimu streamování se každá AgentResponseUpdate z nich vydává jako výstupní událost pracovního postupu. V režimu bez streamování se získá jeden AgentResponse.
Doručení ke koncovým příjemcům — po dokončení agenta exekutor odešle AgentExecutorResponse všem připojeným podřízeným exekutorům. Tato odpověď zahrnuje celou historii konverzací a umožňuje bezproblémové řetězení.
Resetování mezipaměti – interní mezipaměť zpráv exekutoru se po spuštění agenta vymaže, což zajišťuje, že při každém spuštění agenta se zpracovávají pouze nové zprávy přijaté od posledního spuštění.

Návod

Některé scénáře mohou vyžadovat specializovanější vykonavatel agenta; například orchestrace předání používají vyhrazeného vykonavatele s vlastní logikou směrování.

Implicitní a explicitní vytvoření

Automaticky WorkflowBuilder zabalí agenty do AgentExecutor instancí, když předáte agenta přímo. Pro většinu pracovních postupů stačí implicitní vytvoření:

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

Explicitní vytvoření

Explicitně vytvořte AgentExecutor , když potřebujete:

Sdílejte relaci mezi více agenty.
Zadejte vlastní ID exekutora pro směrování a specifické klíčové argumenty při runtime.
Odkazujte na stejnou instanci exekutoru ve více hranách.

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

Parametry konstruktoru:

Parametr	Typ	Description
`agent`	`SupportsAgentRun`	Agent, který se má zabalit.
`session`	`AgentSession \\| None`	Relace, která se má použít pro spuštění agenta. Pokud `None`, je vytvořena nová relace z agenta.
`id`	`str \\| None`	Jedinečné ID exekutoru Výchozí hodnota se nastaví na jméno agenta, pokud je k dispozici.
`context_mode`	`"full" \\| "last_agent" \\| "custom" \\| None`	Určuje způsob zpracování kontextu konverzace při příjmu `AgentExecutorResponse` z upstreamového agenta. Výchozí hodnota je `"full"`, která poskytuje úplnou konverzaci od upstreamového agenta (vstup + odpověď). Viz kontextové režimy.
`context_filter`	`Callable[[list[Message]], list[Message]] \\| None`	Funkce vlastního filtru pro výběr zpráv, které mají být zahrnuty. Vyžaduje se, pokud `context_mode` je `"custom"`.

Návod

ID exekutoru je také klíč použitý při cílení workflow.run(function_invocation_kwargs=...) nebo client_kwargs= na jednotlivé agenty. Pokud vynecháte id, pracovní postup použije název zabaleného agenta.

Vstupní typy

Definuje AgentExecutor několik obslužných metod, z nichž každá přijímá jiný typ vstupu. Engine pracovního postupu automaticky přiřadí správného zpracovatele na základě typu zprávy. Všechny vstupní typy aktivují, aby se agent spustil okamžitě, s výjimkou AgentExecutorRequest toho, kde should_respond příznak určuje, jestli agent běží nebo jednoduše ukládá zprávy do mezipaměti:

Typ vstupu	Zpracovatel	Spouštěče agenta	Description
`AgentExecutorRequest`	`run`	Podmíněný	Kanonický typ vstupu. Obsahuje seznam zpráv a `should_respond` příznak, který určuje, jestli se agent spouští.
`str`	`from_str`	Vždy	Přijme nezpracovaný řetězcový vstup.
`Message`	`from_message`	Vždy	Přijímá jeden `Message` objekt.
`list[str \\| Message]`	`from_messages`	Vždy	Přijme seznam řetězců nebo `Message` objektů jako kontext konverzace.
`AgentExecutorResponse`	`from_response`	Vždy	Přijetí odpovědi předchozího spouštěče agenta, která umožňuje přímé navazování.

Použití AgentExecutorRequest

AgentExecutorRequest je kanonický typ vstupu a poskytuje největší kontrolu:

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)

Příznak should_respond řídí, jestli agent zpracuje zprávy okamžitě nebo je jednoduše uloží do mezipaměti pro pozdější použití:

True (výchozí) – agent se spustí a vytvoří odpověď.
False — zprávy se přidají do mezipaměti, ale agent se nespustí. To je užitečné při předběžném načtení kontextu konverzace před aktivací odpovědi.

Výstup a řetězení

Po dokončení agenta exekutor odešle AgentExecutorResponse dalšímu procesu. Tato třída dat obsahuje:

Pole	Typ	Description
`executor_id`	`str`	ID exekutoru, který vytvořil odpověď.
`agent_response`	`AgentResponse`	Odpověď základního agenta (nezměněná od klienta)
`full_conversation`	`list[Message]`	Úplný kontext konverzace (předchozí vstupy + výstupy agenta) pro zřetězování.

Při řetězení výkonných procesů agenta obdrží podřízený výkonný proces AgentExecutorResponse prostřednictvím obslužného mechanismu from_response. Ve výchozím nastavení používá full_conversation pole k zachování úplné historie konverzací, což brání tomu, aby podřízení agenti ztratili předchozí kontext. Toto chování můžete změnit pomocí kontextových režimů:

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

Chování streamování

Automaticky se přizpůsobí režimu provádění pracovního postupu:

stream=True — volá agent.run(stream=True) a každý AgentResponseUpdate předává jako výstupní událost pracovního postupu. Po dokončení streamování se aktualizace agregují do úplného AgentResponse pro následné zpracování.
stream=False (výchozí) — volá agent.run(stream=False) a generuje jednu AgentResponse jako výstupní událost pracovního postupu.

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

Kontextové režimy

Když jsou agenti zřetězení dohromady, parametr na AgentExecutor určuje, jaký kontext konverzace agent využívá, když obdrží zprávu od nadřazeného agenta prostřednictvím obslužné rutiny from_response.

Dostupné režimy

Mode	Behavior
`"full"` (výchozí)	Agent využívá úplnou konverzaci upstreamového agenta – jak vstupní zprávy poskytované upstreamovým agentem, tak jeho odpovědní zprávy.
`"last_agent"`	Agent zpracovává pouze odpovědi od nadřazeného agenta, s výjimkou vstupu, který byl poskytnut nadřazenému agentovi.
`"custom"`	Funkce poskytovaná `context_filter` uživatelem určuje, které zprávy agent spotřebuje. Vyžaduje parametr `context_filter` .

Použití režimu `last_agent`

Použijte "last_agent", když by se každý agent měl soustředit výhradně na transformaci výstupu předchozího agenta, aniž by byl ovlivněn předchozími konverzačními tahy. To je užitečné pro překladové postupy, progresivní upřesnění a podobné sekvenční transformace:

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

S context_mode="last_agent" francouzský překladatel spotřebovává pouze odpovědi spisovatele (s výjimkou původní výzvy uživatele, která byla vložena do spisovatelova vstupu), a španělský překladatel spotřebovává pouze zprávy s odpověďmi francouzského překladatele.

Použití `custom` režimu

Pro jemně odstupňovanou kontrolu nad tím, jaký kontext agent využívá, použijte context_mode="custom" s context_filter funkcí. Filtr obdrží úplnou konverzaci jako podmnožinu list[Message] a vrátí filtrovanou podmnožinu:

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

Režimy kontextu v nástroji SequentialBuilder

Orchestrace SequentialBuilder poskytuje vhodný chain_only_agent_responses parametr, který konfiguruje všechny agentní účastníky tak, aby používali context_mode="last_agent", takže každý agent využívá pouze zprávy odpovědí předchozího agenta:

from agent_framework.orchestrations import SequentialBuilder

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

Úplný příklad najdete v tématu sequential_chain_only_agent_responses.py v úložišti Agent Framework.

Sdílené relace

Ve výchozím nastavení každá AgentExecutor vytvoří vlastní relaci. Pokud chcete sdílet relaci mezi několika agenty (například pro zachování společného vlákna konverzace), vytvořte relaci explicitně a předejte ji každému exekutoru:

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)

Poznámka:

Ne všichni agenti podporují sdílené sezení. Relaci můžou obvykle sdílet jenom agenti stejného typu poskytovatele služeb.

Vytváření kontrolních bodů

Podporuje AgentExecutor vytváření kontrolních bodů pro ukládání a obnovení stavu v dlouhotrvajících pracovních postupech. Při vytvoření kontrolního bodu vykonavatel provádí serializaci:

Interní mezipaměť zpráv.
Úplná historie konverzací.
Stav relace agenta.
Všechny čekající požadavky a odpovědi na vstup uživatele.

Při obnovení vykonávač deserializuje tento stav, což umožní pracovnímu postupu pokračovat tam, kde skončil.

Výstraha

Vytváření kontrolních bodů prostřednictvím agentů používajících relace na straně serveru (například FoundryAgent) má určité omezení. Stav relace na straně serveru se nezachytává v kontrolních bodech a lze ho upravit následnými spuštěními. Pokud potřebujete spolehlivé vytváření kontrolních bodů s relacemi na straně serveru, zvažte implementaci vlastního exekutoru.

Další kroky

Agenti v pracovních postupech

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-05-11

Exekutor agenta

Přehled

Jak to funguje

Implicitní a explicitní vytvoření

Vlastní konfigurace

Vstupní typy

Výstup a řetězení

Chování streamování

Sdílené relace

Možnosti konfigurace

Vytváření kontrolních bodů

Jak to funguje

Implicitní a explicitní vytvoření

Explicitní vytvoření

Vstupní typy

Použití AgentExecutorRequest

Výstup a řetězení

Chování streamování

Kontextové režimy

Dostupné režimy

Použití režimu last_agent

Použití custom režimu

Režimy kontextu v nástroji SequentialBuilder

Sdílené relace

Vytváření kontrolních bodů

Další kroky

Váš názor

Další materiály

Použití režimu `last_agent`

Použití `custom` režimu