Pracovní postupy rozhraní Microsoft Agent Framework – Pozorovatelnost

Pozorovatelnost poskytuje přehled o interním stavu a chování pracovních postupů během provádění. To zahrnuje protokolovací, metrické a trasovací možnosti, které pomáhají s monitorováním a laděním pracovních postupů.

Návod

Pozorovatelnost je funkce pro celou architekturu a není omezena na pracovní postupy. Další informace naleznete v tématu Pozorovatelnost.

Kromě standardní telemetrie GenAI emitují pracovní postupy Agent Framework další časové úseky, protokoly a metriky, které poskytují podrobnější přehled o jejich provádění. Tyto funkce pozorovatelnosti pomáhají vývojářům pochopit tok zpráv, výkon exekutorů a případné chyby, ke kterým může dojít.

Povolit pozorovatelnost

Pokyny k povolení pozorovatelnosti v aplikacích najdete v tématu Povolení pozorovatelnosti .

Pokyny k povolení pozorovatelnosti v aplikacích najdete v tématu Povolení pozorovatelnosti .

Rozsahy pracovních postupů

Během provádění pracovního postupu se vysílají následující rozsahy:

Název rozsahu	Description
workflow.build	Vygenerováno pro každé sestavení pracovního postupu.
workflow.session	Vnější rozpětí představující celou životnost provádění pracovního postupu od spuštění do zastavení nebo chyby.
workflow_invoke	Vygenerováno pro každý cyklus vstup-zastavení v rámci relace pracovního postupu.
executor.process {executor_id}	Vygenerováno pro každý exekutor zpracovávající zprávu. ID exekutoru se připojí k názvu rozsahu.
edge_group.process	Emitováno pro každou skupinu hraničních bodů, která zpracovává zprávu.
message.send	Vygenerováno pro každou zprávu odeslanou z exekutoru do jiného exekutoru.

Během provádění pracovního postupu se vysílají následující úseky:

Název rozsahu	Description
workflow.build	Vygenerováno pro každé sestavení pracovního postupu.
workflow.run	Vygenerováno pro každé spuštění pracovního postupu.
executor.process {executor_id}	Vygenerováno pro každý exekutor zpracovávající zprávu. ID exekutoru je připojeno k názvu úseku.
edge_group.process {edge_group_type}	Vysílá se pro každou skupinu ověřových uzlů, která zpracovává zprávu. Typ skupiny okrajů se připojí k názvu rozsahu.
message.send	Vygenerováno pro každou zprávu odeslanou z exekutoru do jiného exekutoru.

Atributy spanu

Spans má atributy, které poskytují další kontext operace. Následující atributy jsou přiřazeny úsekům pracovního postupu:

Vlastnost	Rozpětí	Description
workflow.id	workflow.build, workflow.session	Jedinečný identifikátor pracovního postupu.
workflow.name	workflow.session	Název pracovního postupu.
workflow.description	workflow.session	Popis pracovního postupu.
workflow.definition	workflow.build	Definice JSON grafu pracovního postupu.
session.id	workflow.session	Jedinečný identifikátor relace.
executor.id	executor.process	Jedinečný identifikátor exekutoru.
executor.type	executor.process	Název typu exekutoru.
executor.input	executor.process	Vstupní zpráva. Nastaví se jenom v případech, kdy jsou povolená citlivá data.
executor.output	executor.process	Výstup vykonávacího modulu. Nastaví se jenom v případech, kdy jsou povolená citlivá data.
message.type	executor.process, message.send	Název typu zprávy.
message.content	message.send	Obsah zprávy. Nastaví se jenom v případech, kdy jsou povolená citlivá data.
message.source_id	message.send	ID exekutoru, který zprávu odeslal.
message.target_id	message.send	ID cílového exekutoru, pokud je zadáno.
edge_group.type	edge_group.process	Typ skupiny okrajů.
edge_group.delivered	edge_group.process	Zda byla zpráva doručena (logická hodnota).
edge_group.delivery_status	edge_group.process	Výsledek doručení (viz Stav doručení skupiny Edge).
error.type	Jakýkoli rozsah chyby	Název typu výjimky.

Vlastnost	Rozpětí	Description
workflow.id	workflow.build, workflow.run	Jedinečný identifikátor pracovního postupu.
workflow.name	workflow.run	Název pracovního postupu.
workflow.description	workflow.run	Popis pracovního postupu.
workflow.definition	workflow.build	Definice JSON grafu pracovního postupu.
workflow_builder.name	workflow.build	Název tvůrce pracovních postupů.
workflow_builder.description	workflow.build	Popis tvůrce pracovních postupů.
executor.id	executor.process	Jedinečný identifikátor exekutoru.
executor.type	executor.process	Název typu exekutoru.
message.type	executor.process, message.send	Název typu zprávy.
message.payload_type	executor.process	Typ datové části zprávy
message.destination_executor_id	message.send	ID cílového exekutoru, pokud je zadáno.
message.source_id	edge_group.process	ID exekutoru, který zprávu odeslal.
message.target_id	edge_group.process	ID cílového exekutoru, pokud je zadáno.
edge_group.type	edge_group.process	Typ skupiny okrajů.
edge_group.id	edge_group.process	Jedinečný identifikátor skupiny okrajů.
edge_group.delivered	edge_group.process	Zda byla zpráva doručena (logická hodnota).
edge_group.delivery_status	edge_group.process	Výsledek doručení (viz Stav doručení skupiny Edge).

Span Events

Události rozpětí jsou strukturované položky protokolu připojené k rozpětím a poskytují časovou osu klíčových momentů v rámci každého rozpětí.

Název události	Rozpětí	Description
build.started	workflow.build	Emitováno, když začne proces sestavení.
build.validation_completed	workflow.build	Vydáno po úspěšném ověření sestavení.
build.completed	workflow.build	Po úspěšném dokončení sestavení se vygeneruje.
build.error	workflow.build	Vygenerováno při selhání sestavení.
session.started	workflow.session	Vyvoláno při zahájení relace pracovního postupu.
session.completed	workflow.session	K vyvolání dojde při dokončení relace pracovního postupu.
session.error	workflow.session	Vysílá se, když session pracovního procesu narazí na chybu.
workflow.started	workflow_invoke	Vygenerováno při zahájení vyvolání pracovního postupu.
workflow.completed	workflow_invoke	Po dokončení vyvolání pracovního postupu se vygeneruje.
workflow.error	workflow_invoke	Dojde k vyvolání, když pracovní postup narazí na chybu.

Název události	Rozpětí	Description
build.started	workflow.build	Vygenerováno při zahájení procesu sestavení.
build.validation_completed	workflow.build	Vygenerováno při průchodu ověřením sestavení.
build.completed	workflow.build	Po úspěšném dokončení sestavení se vygeneruje.
build.error	workflow.build	Vygenerováno při selhání sestavení.
workflow.started	workflow.run	Emitováno při začátku spuštění pracovního postupu.
workflow.completed	workflow.run	Vysílá se, když se dokončí spuštění pracovního postupu.
workflow.error	workflow.run	Vygenerováno při spuštění pracovního postupu dojde k chybě.

Propojení mezi úseky

Když exekutor odešle zprávu jinému exekutoru, message.send rozsah je vytvořen jako podřízený executor.process rozsah. executor.process Rozsah cílového exekutoru však není podřízeným rozsahemmessage.send, protože provádění není vnořené. executor.process Místo toho je rozsah cílového exekutoru propojený s message.send rozsahem zdrojového exekutoru. Toto propojení vytvoří trasovatelnou cestu prováděním pracovního postupu, aniž by to znamenalo vnořenou hierarchii volání.

Stejný přístup propojování se vztahuje na edge_group.process rozsahy, které jsou propojeny se zdrojovým message.send rozsahem pro sledování kauzality. To podporuje scénáře, ve kterých více zdrojových rozsahů přispívá k jednomu rozsahu zpracování.

Stav doručení Edge Group

Zpracování hraničních skupin zahrnuje atributy stavu doručení, které označují výsledek směrování zpráv prostřednictvím každé hraniční skupiny. Atribut edge_group.delivery_status je nastaven na jednu z následujících hodnot:

Stav	Description
delivered	Zpráva byla doručena cílovému exekutoru.
dropped type mismatch	Cílový exekutor nemůže zpracovat typ zprávy.
dropped target mismatch	Zpráva určila cíl, který neodpovídá této hraně.
dropped condition false	Podmínka pro směrování na hraně byla vyhodnocena jako nepravdivá.
exception	Během zpracování na okraji došlo k výjimce.
buffered	Zpráva byla vyrovnána a čekala na další zprávy (fan-in).

Logický edge_group.delivered atribut poskytuje rychlou kontrolu, jestli byla zpráva úspěšně doručena.

Konfigurace telemetrie

Telemetrii pracovního postupu je možné povolit prostřednictvím WithOpenTelemetry metody rozšíření v tvůrci pracovních postupů. Třída WorkflowTelemetryOptions poskytuje jemně odstupňovanou kontrolu nad tím, které rozsahy se vygenerují:

Možnost	Výchozí	Description
EnableSensitiveData	false	Zahrnuje nezpracované vstupy, výstupy a obsah zpráv v atributech span.
DisableWorkflowBuild	false	Zakáže workflow.build rozsahy.
DisableWorkflowRun	false	Zakáže workflow.session a workflow_invoke rozsahy.
DisableExecutorProcess	false	executor.process Zakáže rozsahy.
DisableEdgeGroupProcess	false	Zakáže rozsahy edge_group.process.
DisableMessageSend	false	Zakáže message.send spany.

Výstraha

Povolení citlivých dat způsobí zahrnutí nezpracovaných zpráv, vstupů exekutorů a výstupů exekutoru do telemetrie. Tuto možnost povolte jenom v zabezpečených prostředích, kde jsou telemetrická data správně chráněná.

Telemetrie pracovního postupu je povolená prostřednictvím globální enable_instrumentation() funkce. Pokud je instrumentace povolená, automaticky se vysílají všechny úseky pracovních postupů. Funkci configure_otel_providers() lze použít k nastavení exportérů pro trasování, metriky a protokoly.

Výstraha

Zkontrolujte konfiguraci kanálu telemetrie a ujistěte se, že jsou citlivá data při exportu trasování správně chráněná.

Další kroky

• Seznamte se s izolací stavu v pracovních postupech.
• Naučte se vizualizovat pracovní postupy.