[api][python] Introduce YAML API for declaring agents by wenjin272 · Pull Request #670 · apache/flink-agents

wenjin272 · 2026-05-14T07:04:52Z

Linked issue: #625

Purpose of change

Add data structure to represent a java function in python
Support execute java function tool in python.
Introduce YAML api in python.

Tests

ut & e2e

API

Yes, add yaml api.

Documentation

doc-needed
doc-not-needed
doc-included

xintongsong · 2026-05-15T07:19:40Z

+
+    name: str
+    description: str | None = None
+    namespace: str | None = None


The name namespace is confusing. Maybe something like default_func_path. Anyway, the semantic of this needs well description in documents.

Do we need separate defaults for python and java?

I think this default needs more careful design, otherwise it may introduce more confusion than convenience. I'd suggest to make this a follow-up and exclude from this PR.

xintongsong · 2026-05-15T07:30:50Z

+    name: str
+    function: str | None = None
+    type: Language | None = None
+    parameter_types: List[str] | None = None


This needs a more detailed description. What are the required formats/values of the parameter type strings.

xintongsong · 2026-05-15T07:56:38Z

+    """SafeLoader that recognizes only ``true``/``false`` as booleans.
+
+    PyYAML follows YAML 1.1 by default, where ``on``/``off``/``yes``/``no``
+    also coerce to booleans. ``on:`` is the natural way to declare an


Can we change to another keyword?

xintongsong · 2026-05-15T07:59:41Z

+        if "." in function:
+            qualified = function


What if namespace is foo and the function is foo.bar.Func?

xintongsong · 2026-05-15T08:06:38Z

+    return agents, shared_resources, shared_actions, agent_specs, doc
+
+
+def _assert_has_python_implementation(


Is this necessary? What if I implemented an agent in yaml + java, but need to use it in a pyflink job?

xintongsong · 2026-05-15T08:24:10Z

+
+def test_load_yaml_string_ref_to_missing_shared_action_errors() -> None:
+    env = AgentsExecutionEnvironment.get_execution_environment()
+    bad = _FIXTURES / "bad_missing_shared_action.yaml"


Should not write temporal contents in the source directory.

The agent-level ``namespace`` default + ``<namespace>.<name>`` fallback for ``function`` was deferred to a follow-up per reviewer feedback (PR apache#670 comment by xintongsong): the naming was confusing, the python/java default story was unclear, and edge cases like ``namespace=foo`` + ``function=foo.bar.Func`` needed more design. Every action and tool entry now requires an explicit fully-qualified ``function:``. Loader, fixtures, e2e YAML and the checked-in JSON Schema are updated to match; the resolve_function rules collapse to: function given → split at last ``.``; function missing → error. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Per PR apache#670 review comment by xintongsong: an agent declared in YAML + Java should be runnable from a PyFlink job. The loader was refusing those plans up front, which prejudges what the runtime can host. Drop the gate (and its two helpers + the corresponding test) and let the runtime own whatever support gaps remain — bugs should surface as runtime errors at the actual boundary, not as a parse-time refusal. A separate cross-language ChatMessage role serdes bug currently keeps Java→Python ChatRequestEvent dispatch from round-tripping through Python actions, but that's an upstream serdes issue and not a reason for the YAML loader to filter plans. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Per PR apache#670 review comment by xintongsong: spell out exactly what strings are accepted in a Java tool's ``parameter_types`` list — order, primitive aliases, fully-qualified reference types (boxed primitives included), and the no-generics rule (JVM method descriptors don't carry type parameters). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@action

Per PR apache#670 review comment by xintongsong: the previous keyword collided with YAML 1.1's boolean resolver (which coerces unquoted 'on' / 'off' / 'yes' / 'no'), forcing a custom SafeLoader subclass to patch the bool resolver. The new keyword 'listen_to:' aligns with the Java @action(listenEventTypes = {...}) annotation and lets us drop the loader workaround so the YAML stays portable to any standard YAML 1.1 / 1.2 consumer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The agent-level ``namespace`` default + ``<namespace>.<name>`` fallback for ``function`` was deferred to a follow-up per reviewer feedback (PR apache#670 comment by xintongsong): the naming was confusing, the python/java default story was unclear, and edge cases like ``namespace=foo`` + ``function=foo.bar.Func`` needed more design. Every action and tool entry now requires an explicit fully-qualified ``function:``. Loader, fixtures, e2e YAML and the checked-in JSON Schema are updated to match; the resolve_function rules collapse to: function given → split at last ``.``; function missing → error. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Per PR apache#670 review comment by xintongsong: an agent declared in YAML + Java should be runnable from a PyFlink job. The loader was refusing those plans up front, which prejudges what the runtime can host. Drop the gate (and its two helpers + the corresponding test) and let the runtime own whatever support gaps remain — bugs should surface as runtime errors at the actual boundary, not as a parse-time refusal. A separate cross-language ChatMessage role serdes bug currently keeps Java→Python ChatRequestEvent dispatch from round-tripping through Python actions, but that's an upstream serdes issue and not a reason for the YAML loader to filter plans. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Per PR apache#670 review comment by xintongsong: spell out exactly what strings are accepted in a Java tool's ``parameter_types`` list — order, primitive aliases, fully-qualified reference types (boxed primitives included), and the no-generics rule (JVM method descriptors don't carry type parameters). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

@action

Per PR apache#670 review comment by xintongsong: the previous keyword collided with YAML 1.1's boolean resolver (which coerces unquoted 'on' / 'off' / 'yes' / 'no'), forcing a custom SafeLoader subclass to patch the bool resolver. The new keyword 'listen_to:' aligns with the Java @action(listenEventTypes = {...}) annotation and lets us drop the loader workaround so the YAML stays portable to any standard YAML 1.1 / 1.2 consumer. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

xintongsong

LGTM

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

github-actions Bot added doc-needed Your PR changes impact docs. fixVersion/0.3.0 The feature or bug should be implemented/fixed in the 0.3.0 version. priority/major Default priority of the PR or issue. and removed doc-needed Your PR changes impact docs. labels May 14, 2026

wenjin272 force-pushed the yaml-api branch 2 times, most recently from 4a2cd9f to 665b593 Compare May 14, 2026 09:46

wenjin272 mentioned this pull request May 15, 2026

[Feature] Support using cross-language actions. #622

Open

2 tasks

xintongsong reviewed May 15, 2026

View reviewed changes

wenjin272 force-pushed the yaml-api branch from 665b593 to 2c24b98 Compare May 16, 2026 16:34

wenjin272 force-pushed the yaml-api branch from 2c24b98 to 78e3c19 Compare May 17, 2026 10:23

xintongsong approved these changes May 18, 2026

View reviewed changes

wenjin272 and others added 2 commits May 18, 2026 21:32

[api][plan][runtime] Cross-language Function/FunctionTool

2e1c313

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

[api] Introduce YAML API for declaring agents

1d65629

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

wenjin272 force-pushed the yaml-api branch from 78e3c19 to 1d65629 Compare May 18, 2026 13:33

wenjin272 merged commit 5182f25 into apache:main May 18, 2026
23 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[api][python] Introduce YAML API for declaring agents#670

[api][python] Introduce YAML API for declaring agents#670
wenjin272 merged 2 commits into
apache:mainfrom
wenjin272:yaml-api

wenjin272 commented May 14, 2026 •

edited

Loading

Uh oh!

xintongsong May 15, 2026

Uh oh!

xintongsong May 15, 2026

Uh oh!

xintongsong May 15, 2026

Uh oh!

xintongsong May 15, 2026

Uh oh!

xintongsong May 15, 2026

Uh oh!

xintongsong May 15, 2026

Uh oh!

xintongsong May 15, 2026

Uh oh!

xintongsong May 15, 2026

Uh oh!

xintongsong left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		return agents, shared_resources, shared_actions, agent_specs, doc


		def _assert_has_python_implementation(

Conversation

wenjin272 commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose of change

Tests

API

Documentation

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xintongsong left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

wenjin272 commented May 14, 2026 •

edited

Loading