ExecutionObserver

CORE · interface · 类型合同

Live consumer of Core facts.

导入

TypeScriptJavaScript

import type { ExecutionObserver } from '@jangts/agent-core';

/** @typedef {import('@jangts/agent-core').ExecutionObserver} ExecutionObserver */

其他公开入口：@jangts/agent-core、@jangts/agent-core/types、@jangts/agent-core/structs。

定义

interface ExecutionObserver

字段结构

字段	类型	必需	说明
`accepts`	`((descriptor: Readonly<ExecutionEventDescriptor>) => boolean) \| undefined`	可省略	Metadata-only by default. Content requires an explicit accepts decision.
`event`	`(event: Readonly<CoreEvent>) => void \| Promise<void>`	必需	Handles one fact; a rejected promise propagates to the emitting call.

成员目录

成员	用途
`event`	Handles one fact; a rejected promise propagates to the emitting call.

成员详情

`event`

Handles one fact; a rejected promise propagates to the emitting call.

ExecutionObserver.event(event: Readonly<CoreEvent>): void | Promise<void>

Handles one fact; a rejected promise propagates to the emitting call.

参数	类型	传递	说明
`event`	`Readonly<CoreEvent>`	必需	—

参数 event的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"loop.event"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`LoopEvent`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 2

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"model.binding"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ modelId: string; invocationId: string; status: "running" \| "success" \| "error" \| "cancelled"; phase: "input" \| "invoke" \| "output"; durationMs?: number; errorCode?: string; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 3

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"model.prepare"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ stageId: string; transportId: string; messages: readonly ModelMessage[]; options: unknown; context?: unknown; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 4

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"model.output"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ stageId: string; callSequence: number; partIndex: number; part: import("./model/messages.js").ModelPart; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 5

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"model.parsed"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ stageId: string; callSequence: number; value?: unknown; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 6

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"model.end"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ stageId: string; state: Readonly<ModelCallTrace>; error?: unknown; receivedParts: number; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 7

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"runtime.rejected"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ stageId?: string; error: unknown; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 8

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"node.progress"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ payload?: unknown; subStep?: import("./debug.js").SubStepProgress; reportError?: "INVALID_NODE_REPORT"; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 9

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"model.start"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ stageId: string; callSequence: number; transportId: string; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 10

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"workflow.event"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ event: WorkflowEvent; payload?: unknown; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 11

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"tool.call"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ toolId: string; invocationId: string; input?: unknown; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 12

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"tool.result"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ toolId: string; invocationId: string; value?: unknown; error?: unknown; errorCode?: string; status: import("./common.js").InvocationStatus; durationMs: number; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

分支 13

字段	类型	必需	说明
`runId`	`string`	必需	只读。Root run id shared by every fact of one logical run.
`spanId`	`string`	必需	只读。Span that produced the fact.
`parentSpanId`	`string \| undefined`	可省略	只读。Enclosing span; absent for a root span.
`invocationId`	`string \| undefined`	可省略	只读。Invocation that produced the fact, when the fact belongs to one.
`parentInvocationId`	`string \| undefined`	可省略	只读。Enclosing invocation, when one invocation triggers another.
`nodeRole`	`"invocation" \| "workflow-node" \| "workflow-boundary" \| "loop-step" \| undefined`	可省略	只读。Role the emitting span plays in the execution graph.
`agentId`	`string \| undefined`	可省略	只读。App-owned agent identity.
`branchId`	`string \| undefined`	可省略	只读。App-owned branch identity.
`agentVersionId`	`string \| undefined`	可省略	只读。App-owned immutable version identity of the agent definition.
`parentBranchId`	`string \| undefined`	可省略	只读。Branch this branch was forked from, when applicable.
`parentAgentVersionId`	`string \| undefined`	可省略	只读。Version of the parent branch at the fork point.
`forkPointId`	`string \| undefined`	可省略	只读。App-owned fork marker shared by the forked branch and its origin.
`workflowInvocationId`	`string \| undefined`	可省略	只读。Workflow invocation the fact belongs to.
`workflowNodeId`	`string \| undefined`	可省略	只读。Workflow node invocation the fact belongs to.
`definitionKind`	`string \| undefined`	可省略	只读。Kind of the workflow/agent definition that dispatched the node.
`definitionId`	`string \| undefined`	可省略	只读。Id of that definition.
`definitionRevision`	`string \| undefined`	可省略	只读。Revision of that definition; distinguishes executions of different definition states.
`nodeId`	`string \| undefined`	可省略	只读。Node id inside the workflow.
`nodeName`	`string \| undefined`	可省略	只读。Human-readable node name.
`nodeKind`	`string \| undefined`	可省略	只读。Node kind as declared by the App.
`nodeDescription`	`string \| undefined`	可省略	只读。Optional node description for diagnostics display.
`stageId`	`string \| undefined`	可省略	只读。Model stage that produced the fact.
`modelId`	`string \| undefined`	可省略	只读。Model binding used, when the fact concerns a model call.
`version`	`2`	必需	Envelope version; consumers must reject anything else.
`eventId`	`string`	必需	Unique id of this fact, stable across observers and log writers.
`type`	`"rule.result"`	必需	Discriminator matching `payload`.
`producerSequence`	`number`	必需	Monotonic counter owned by the producing scope; starts at 1 for each producer.
`occurredAtMs`	`number`	必需	Instant the fact occurred, in epoch milliseconds.
`payload`	`{ tags: readonly string[]; error: unknown; }`	必需	Event-specific facts.
`usedModel`	`boolean \| undefined`	可省略	Whether the reported step used a model; omitted when the producer did not state it.
`subSteps`	`readonly RecordedSubStep[]`	必需	Reported sub-steps attached to this fact, bounded and already validated.
`subStepsDropped`	`number`	必需	Number of reported sub-steps omitted by the recorder's bounds.
`subStepsTruncated`	`boolean`	必需	True when reported sub-steps were truncated, so the attached list is incomplete.

返回： void \| Promise<void>。

等待后的值： void。

使用示例

过程监听与节点报告：App 订阅 Core 执行事实；节点报告自身 usedModel，并用实例式子日志先记意图、再补结果，Loop 负责身份和日志。

监听任务经过的节点与模型事件

入门 · Node.js

TypeScriptJavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';

type State = { name: string; answer?: string };
const workflow = defineWorkflow<State, string>({
  id: 'greeting',
  nodes: [{
    id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
    run: state => ({ answer: '你好，' + state.name }),
    routes: [route.deliver('answer')],
  }],
});
const agent = new AgentCoreEngine({ workflow, execution: {
  observe: { event(event) { console.log(event.type, event.eventId); } },
} });
console.log(await agent.run({ name: 'Ivan' }));

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({
    id: 'greeting',
    nodes: [{
            id: 'greet', description: '根据本次姓名生成问候', startsRound: true,
            run: state => ({ answer: '你好，' + state.name }),
            routes: [route.deliver('answer')],
        }],
});
const agent = new AgentCoreEngine({ workflow, execution: {
        observe: { event(event) { console.log(event.type, event.eventId); } },
    } });
console.log(await agent.run({ name: 'Ivan' }));

节点执行时报告业务阶段

配置 · Node.js

节点只报告它知道的事实；Core 负责节点身份和执行关联。

TypeScriptJavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
type State = { name: string; answer?: string };
const workflow = defineWorkflow<State, string>({ id: 'greeting', nodes: [{
  id: 'greet', description: '生成问候', startsRound: true,
  run(state, context) {
    context.report({ payload: { phase: 'formatting' } });
    return { answer: '你好，' + state.name };
  }, routes: [route.deliver('answer')],
}] });
const agent = new AgentCoreEngine({ workflow, execution: {
  observe: { event(event) { console.log(event.type); } },
} });
console.log(await agent.run({ name: 'Ivan' }));

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
const workflow = defineWorkflow({ id: 'greeting', nodes: [{
            id: 'greet', description: '生成问候', startsRound: true,
            run(state, context) {
                context.report({ payload: { phase: 'formatting' } });
                return { answer: '你好，' + state.name };
            }, routes: [route.deliver('answer')],
        }] });
const agent = new AgentCoreEngine({ workflow, execution: {
        observe: { event(event) { console.log(event.type); } },
    } });
console.log(await agent.run({ name: 'Ivan' }));

AgentCoreEngine

AgentWorkflow

AttemptBudget

route

AgentCachePort

AgentCheckpoint

AgentModelRuntime

ExecutionObserver

NodeAgentCache

NodeCache

WorkflowContext

WorkflowModel

ExecutionObserver

导入

定义

字段结构

成员目录

成员详情

`event`

使用示例

监听任务经过的节点与模型事件

节点执行时报告业务阶段

相关策略源码

相关定义

AgentCoreEngine

AgentWorkflow

AttemptBudget

route

AgentCachePort

AgentCheckpoint

AgentModelRuntime

ExecutionObserver

NodeAgentCache

NodeCache

WorkflowContext

WorkflowModel

ExecutionObserver ​

导入 ​

定义 ​

字段结构 ​

成员目录 ​

成员详情 ​

event ​

使用示例 ​

监听任务经过的节点与模型事件 ​

节点执行时报告业务阶段 ​

相关策略源码 ​

相关定义 ​

ExecutionObserver

导入

定义

字段结构

成员目录

成员详情

`event`

使用示例

监听任务经过的节点与模型事件

节点执行时报告业务阶段

相关策略源码

相关定义