wenjin272 opened a new issue, #1056: URL: https://github.com/apache/flink-agents/issues/1056
### Search before asking - [x] I searched in the [issues](https://github.com/apache/flink-agents/issues) and found nothing similar. ### Description Parent issue: #1055 `ChatMessage` is a public contract shared by the Java and Python APIs, model integrations, runtime actions, Event Log serialization, state, and the pemja bridge. As these areas have evolved, the class has accumulated responsibilities that are not clearly separated: - `content` is limited to text, while provider messages may contain richer, ordered content. This is also being discussed in #1031. - `tool_calls` is represented as untyped maps whose required keys and value shapes are enforced by convention in provider and runtime code. - `extra_args` is used for several unrelated purposes, including provider-native message data, tool-call correlation, token usage, refusal/reasoning details, structured output, and routing metadata. - Some values associated with a model invocation or response are carried as message attributes because there is no separate response-level representation. - Java and Python do not always use the same field names or interpret `extra_args` in the same way. Cross-language conversions therefore depend on implicit conventions. - Serialization and copying behavior is spread across Jackson, Python models, Event Log records, and explicit pemja conversion code. This makes it difficult to distinguish stable message semantics from provider-specific or runtime metadata, validate messages consistently, and evolve the API without adding more implicit conventions. Related provider-level parity problems are tracked in #936. Before establishing the post-0.4 compatibility baseline, the responsibilities and public contract of `ChatMessage` should be reviewed across Java, Python, provider adapters, runtime call paths, and cross-language serialization. This issue intentionally records the current problems only. The target data model, field names, compatibility impact, and implementation scope should be agreed separately before implementation. ### Are you willing to submit a PR? - [ ] I'm willing to submit a PR! -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
