[Tech Debt] Clarify Workflow Agent documentation around event emission and event metadata #793

Search before asking

• I searched in the issues and found nothing similar.

Description

There are two documentation/API-contract follow-ups around the Workflow Agent page.

1. The Send Event snippet shows one action sending both a ChatRequestEvent and an OutputEvent.

   This is valid API usage, but it can be misleading as a workflow example. In the runtime, an OutputEvent is emitted downstream immediately, while the ChatRequestEvent continues through the chat-model path. If a ChatResponseEvent handler also emits an output, one input may produce both an immediate output and a later model-based output.

   Source / evidence:

   • The snippet is in docs/content/docs/development/workflow_agent.md, in the Send Event section. It shows ctx.send_event(ChatRequestEvent(...)) followed by ctx.send_event(OutputEvent(...)) in the same action. The Java tab shows the same pattern with ctx.sendEvent(...).
   • Runtime behavior is in runtime/src/main/java/org/apache/flink/agents/runtime/operator/ActionExecutionOperator.java: OutputEvent is collected downstream immediately, while non-output events are routed to triggered actions.

   Suggested fix: split the snippet into separate examples for "trigger another action" and "emit downstream output", or explicitly state that sending an OutputEvent in the same action is only for immediate downstream output and is not the normal chat request/response workflow pattern.

2. The typed event reconstruction contract should be explicit about base Event metadata such as id and sourceTimestamp.

   fromEvent / from_event helpers reconstruct typed events from a base Event. If metadata such as id or sourceTimestamp is dropped in any typed reconstruction path, event logs, listeners, correlation, deduplication, and downstream timestamp propagation become harder to reason about.

   Source / evidence:

   • The custom event subclass guidance is in docs/content/docs/development/workflow_agent.md, in the Custom Event Subclasses section. The examples require users to implement from_event / fromEvent, but do not state whether base metadata should be copied.
   • Built-in Java event reconstruction paths such as InputEvent.fromEvent(...) and ChatRequestEvent.fromEvent(...) preserve the base event id, and Java paths also preserve sourceTimestamp where applicable. This should either become part of the documented contract or be explicitly described as implementation-specific behavior.
   • Python built-in event reconstruction paths preserve the base id, for example InputEvent.from_event(...), but the workflow page does not tell users writing custom events what metadata they are responsible for preserving.

   Suggested fix: audit typed event reconstruction implementations and either preserve base metadata consistently or document the intended contract and limitations.

Are you willing to submit a PR?

• I'm willing to submit a PR!