[python] warn when an action declares a return value

[vishnuprakaz]

Linked issue: #834

Purpose of change

Actions communicate by sending events via ctx.send_event(...); any value an
action returns is silently discarded by the framework. Previously this failed
quietly, so writing return result in an action did nothing with no error or
warning a confusing trap.

This implements the existing TODO in
plan/actions/action.py by emitting a warning when an agent plan is built for
any @action-decorated method that declares a non-None return type, pointing
the user to ctx.send_event(...). Warning only no change to execution behavior.

Tests

Added two unit tests in plan/tests/test_agent_plan.py:

• an action declaring a return type (-> str) logs the warning, and
• a normal -> None action logs no warning.

Verified locally with pytest and ruff check.

API

No public API changes.

Documentation

• doc-needed
• doc-not-needed
• doc-included

[wenjin272]

Hi, @vishnuprakaz, thanks for your work. Since Flink Agents 0.3 has been code freeze, I will review this PR after we cut release-0.3 branch.

[weiqingy]

Thanks for taking this on — clean implementation of the TODO, and nice touch handling the stringized "None" annotation so the warning still fires correctly in modules that opt into from __future__ import annotations. One scope question inline.

[weiqingy]

The warning fires for @action-decorated methods here, but actions registered imperatively via add_action(name, events, func) flow through the agent.actions loop below (around line 311) and skip this check — so a plain Python callable with -> str passed to add_action hits the same silent-discard trap with no warning. Issue #834 scopes this to decorated methods, so this may be deliberate — is covering the add_action path worth a follow-up, or intentionally out of scope?

[vishnuprakaz]

Thanks for review @weiqingy! Yes I scoped this to decorated @ action methods to match issue #834, so leaving out add_action was intentional. I'd prefer to keep this PR focused and cover the add_action path in a follow up I'll open a separate issue for it. Let me know if you'd rather I fold it into this PR instead.

[weiqingy]

Thanks for review @weiqingy! Yes I scoped this to decorated @ action methods to match issue #834, so leaving out add_action was intentional. I'd prefer to keep this PR focused and cover the add_action path in a follow up I'll open a separate issue for it. Let me know if you'd rather I fold it into this PR instead.

Sounds good.
I also traced the target=-style decorated actions (the target is not None branch) to be sure it isn't a second silent-discard spot: there the decorated method is just a stub and the real executed function is the descriptor's target, so skipping the stub's annotation is correct. That leaves add_action as the only genuinely uncovered path, which your follow-up covers. Current change LGTM — I'll leave the final call to the maintainers.