[api] Rename action 'on:' to 'listen_to:' in YAML

wenjin272 · claude · wenjin272 · commit 2c24b98e6c4f · 2026-05-17T00:29:56.000+08:00
Per PR #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>
diff --git a/docs/yaml-schema.json b/docs/yaml-schema.json
@@ -29,18 +29,18 @@
           "default": null,
           "title": "Function"
         },
-        "name": {
-          "title": "Name",
-          "type": "string"
-        },
-        "on": {
+        "listen_to": {
           "items": {
             "type": "string"
           },
           "minItems": 1,
-          "title": "On",
+          "title": "Listen To",
           "type": "array"
         },
+        "name": {
+          "title": "Name",
+          "type": "string"
+        },
         "type": {
           "anyOf": [
             {
@@ -60,7 +60,7 @@
       },
       "required": [
         "name",
-        "on"
+        "listen_to"
       ],
       "title": "ActionSpec",
       "type": "object"
diff --git a/python/flink_agents/api/yaml/loader.py b/python/flink_agents/api/yaml/loader.py
@@ -19,7 +19,6 @@
 environment.
 """
 
-import re
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, List, Tuple
 
@@ -51,27 +50,6 @@
     YamlAgentsDocument,
 )
 
-
-class _FlinkAgentsYamlLoader(yaml.SafeLoader):
-    """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
-    action's event listeners in this API, so we strip those legacy
-    keywords from the bool resolver.
-    """
-
-
-_FlinkAgentsYamlLoader.yaml_implicit_resolvers = {
-    key: [(tag, regexp) for tag, regexp in resolvers if tag != "tag:yaml.org,2002:bool"]
-    for key, resolvers in yaml.SafeLoader.yaml_implicit_resolvers.items()
-}
-_FlinkAgentsYamlLoader.add_implicit_resolver(
-    "tag:yaml.org,2002:bool",
-    re.compile(r"^(?:true|True|TRUE|false|False|FALSE)$"),
-    list("tTfF"),
-)
-
 # Default Java parameter types for an action. Action methods in
 # flink-agents always have signature (Event, RunnerContext).
 _JAVA_ACTION_PARAMETER_TYPES: list[str] = [
@@ -145,7 +123,7 @@ def resolve_function(
 
 def _load_document(path: Path | str) -> YamlAgentsDocument:
     text = Path(path).read_text()
-    raw = yaml.load(text, Loader=_FlinkAgentsYamlLoader)
+    raw = yaml.load(text, Loader=yaml.SafeLoader)
     if raw is None:
         msg = f"YAML file {path} is empty"
         raise ValueError(msg)
@@ -192,7 +170,7 @@ def _resolve_action_function(action: ActionSpec) -> Function:
 
 def _add_action_to_agent(agent: Agent, action: ActionSpec) -> None:
     func = _resolve_action_function(action)
-    events = [resolve_event_type(e) for e in action.on]
+    events = [resolve_event_type(e) for e in action.listen_to]
     config = action.config or {}
     agent.add_action(action.name, events, func, **config)
 
diff --git a/python/flink_agents/api/yaml/specs.py b/python/flink_agents/api/yaml/specs.py
@@ -150,7 +150,7 @@ class ActionSpec(BaseModel):
 
     name: str
     function: str | None = None
-    on: List[str] = Field(..., min_length=1)
+    listen_to: List[str] = Field(..., min_length=1)
     config: Dict[str, Any] | None = None
     type: Language | None = None
 
diff --git a/python/flink_agents/api/yaml/tests/fixtures/multi_agent.yaml b/python/flink_agents/api/yaml/tests/fixtures/multi_agent.yaml
@@ -3,9 +3,9 @@ agents:
     actions:
       - name: increment
         function: flink_agents.api.yaml.tests.fixtures.loader_targets:increment
-        on: [input]
+        listen_to: [input]
   - name: a2
     actions:
       - name: decrement
         function: flink_agents.api.yaml.tests.fixtures.loader_targets:decrement
-        on: [input]
+        listen_to: [input]
diff --git a/python/flink_agents/api/yaml/tests/fixtures/multi_file_a.yaml b/python/flink_agents/api/yaml/tests/fixtures/multi_file_a.yaml
@@ -3,8 +3,7 @@ agents:
     actions:
       - name: increment
         function: flink_agents.api.yaml.tests.fixtures.loader_targets:increment
-        on: [input]
-
+        listen_to: [input]
 chat_model_connections:
   - name: conn_from_a
     clazz: ollama
diff --git a/python/flink_agents/api/yaml/tests/fixtures/multi_file_b.yaml b/python/flink_agents/api/yaml/tests/fixtures/multi_file_b.yaml
@@ -3,8 +3,7 @@ agents:
     actions:
       - name: decrement
         function: flink_agents.api.yaml.tests.fixtures.loader_targets:decrement
-        on: [input]
-
+        listen_to: [input]
 chat_model_connections:
   - name: conn_from_b
     clazz: ollama
diff --git a/python/flink_agents/api/yaml/tests/fixtures/single_agent.yaml b/python/flink_agents/api/yaml/tests/fixtures/single_agent.yaml
@@ -3,4 +3,4 @@ agents:
     actions:
       - name: increment
         function: flink_agents.api.yaml.tests.fixtures.loader_targets:increment
-        on: [input]
+        listen_to: [input]
diff --git a/python/flink_agents/api/yaml/tests/fixtures/with_descriptors.yaml b/python/flink_agents/api/yaml/tests/fixtures/with_descriptors.yaml
@@ -3,10 +3,10 @@ agents:
     actions:
       - name: increment
         function: flink_agents.api.yaml.tests.fixtures.loader_targets:increment
-        on: [input]
+        listen_to: [input]
       - name: decrement
         function: flink_agents.api.yaml.tests.fixtures.loader_targets:decrement
-        on: [chat_response]
+        listen_to: [chat_response]
     chat_model_connections:
       - name: ollama_conn
         clazz: ollama
diff --git a/python/flink_agents/api/yaml/tests/fixtures/with_shared.yaml b/python/flink_agents/api/yaml/tests/fixtures/with_shared.yaml
@@ -4,7 +4,7 @@ agents:
       - shared_inc
       - name: own_dec
         function: flink_agents.api.yaml.tests.fixtures.loader_targets:decrement
-        on: [chat_response]
+        listen_to: [chat_response]
   - name: a2
     actions:
       - shared_inc
@@ -17,4 +17,4 @@ chat_model_connections:
 actions:
   - name: shared_inc
     function: flink_agents.api.yaml.tests.fixtures.loader_targets:increment
-    on: [input]
+    listen_to: [input]
diff --git a/python/flink_agents/api/yaml/tests/test_loader.py b/python/flink_agents/api/yaml/tests/test_loader.py
@@ -99,35 +99,19 @@ def test_resolve_function_missing_target_raises_importerror() -> None:
         func.as_callable()
 
 
-def test_build_agents_treats_unquoted_on_as_string_not_bool(tmp_path: Path) -> None:
-    yaml_text = (
-        "agents:\n"
-        "  - name: a\n"
-        "    actions:\n"
-        "      - name: increment\n"
-        f"        function: {_TARGETS_MODULE}:increment\n"
-        "        on: [input]\n"
-    )
-    p = tmp_path / "on_keyword.yaml"
-    p.write_text(yaml_text)
-    agents, _, _ = build_agents(p)
-    assert "a" in agents
-    assert "increment" in agents["a"].actions
-
-
 def test_build_agents_rejects_duplicate_agent_within_file(tmp_path: Path) -> None:
     yaml_text = (
         "agents:\n"
         "  - name: dup\n"
         "    actions:\n"
         "      - name: increment\n"
         f"        function: {_TARGETS_MODULE}:increment\n"
-        "        on: [input]\n"
+        "        listen_to: [input]\n"
         "  - name: dup\n"
         "    actions:\n"
         "      - name: decrement\n"
         f"        function: {_TARGETS_MODULE}:decrement\n"
-        "        on: [input]\n"
+        "        listen_to: [input]\n"
     )
     p = tmp_path / "dup.yaml"
     p.write_text(yaml_text)
@@ -305,9 +289,9 @@ def test_load_yaml_duplicate_shared_action_within_file_errors(tmp_path) -> None:
         "  - name: a\n"
         "actions:\n"
         "  - name: shared\n"
-        "    on: [input]\n"
+        "    listen_to: [input]\n"
         "  - name: shared\n"
-        "    on: [input]\n"
+        "    listen_to: [input]\n"
     )
     env = AgentsExecutionEnvironment.get_execution_environment()
     with pytest.raises(ValueError, match="Duplicate shared action name 'shared'"):
@@ -506,7 +490,7 @@ def test_build_agents_builds_java_action(tmp_path: Path) -> None:
         "      - name: a1\n"
         "        type: java\n"
         "        function: com.example.MyAgent:handle\n"
-        "        on: [input]\n"
+        "        listen_to: [input]\n"
     )
     p = tmp_path / "java_action.yaml"
     p.write_text(yaml_text)
@@ -535,7 +519,7 @@ def test_build_agents_rejects_java_tool_missing_parameter_types(
         "    actions:\n"
         "      - name: noop\n"
         f"        function: {_TARGETS_MODULE}:increment\n"
-        "        on: [input]\n"
+        "        listen_to: [input]\n"
     )
     p = tmp_path / "java_tool_no_params.yaml"
     p.write_text(yaml_text)
@@ -562,7 +546,7 @@ def test_build_agents_builds_java_tool_descriptor(tmp_path: Path) -> None:
         "    actions:\n"
         "      - name: noop\n"
         f"        function: {_TARGETS_MODULE}:increment\n"
-        "        on: [input]\n"
+        "        listen_to: [input]\n"
     )
     p = tmp_path / "java_tool.yaml"
     p.write_text(yaml_text)
diff --git a/python/flink_agents/api/yaml/tests/test_specs.py b/python/flink_agents/api/yaml/tests/test_specs.py
@@ -139,46 +139,50 @@ def test_tool_spec_forbids_extras() -> None:
         ToolSpec.model_validate({"name": "t1", "unknown": 1})
 
 
-def test_action_spec_requires_on() -> None:
+def test_action_spec_requires_listen_to() -> None:
     with pytest.raises(ValidationError):
         ActionSpec.model_validate({"name": "a1"})
 
 
-def test_action_spec_rejects_empty_on() -> None:
-    # An empty ``on: []`` would silently register a dead action that never
-    # fires. The minimum-length constraint forces the mistake to surface at
-    # YAML validation time.
+def test_action_spec_rejects_empty_listen_to() -> None:
+    # An empty ``listen_to: []`` would silently register a dead action that
+    # never fires. The minimum-length constraint forces the mistake to
+    # surface at YAML validation time.
     with pytest.raises(ValidationError):
-        ActionSpec.model_validate({"name": "a1", "on": []})
+        ActionSpec.model_validate({"name": "a1", "listen_to": []})
 
 
 def test_action_spec_defaults() -> None:
-    spec = ActionSpec.model_validate({"name": "a1", "on": ["input"]})
-    assert spec.on == ["input"]
+    spec = ActionSpec.model_validate({"name": "a1", "listen_to": ["input"]})
+    assert spec.listen_to == ["input"]
     assert spec.function is None
     assert spec.config is None
 
 
 def test_action_spec_with_config() -> None:
     spec = ActionSpec.model_validate(
-        {"name": "a1", "on": ["input"], "config": {"k": 1}}
+        {"name": "a1", "listen_to": ["input"], "config": {"k": 1}}
     )
     assert spec.config == {"k": 1}
 
 
 def test_action_spec_accepts_type() -> None:
-    spec = ActionSpec.model_validate({"name": "a1", "on": ["input"], "type": "java"})
+    spec = ActionSpec.model_validate(
+        {"name": "a1", "listen_to": ["input"], "type": "java"}
+    )
     assert spec.type == "java"
 
 
 def test_action_spec_type_defaults_to_none() -> None:
-    spec = ActionSpec.model_validate({"name": "a1", "on": ["input"]})
+    spec = ActionSpec.model_validate({"name": "a1", "listen_to": ["input"]})
     assert spec.type is None
 
 
 def test_action_spec_rejects_unknown_type() -> None:
     with pytest.raises(ValidationError):
-        ActionSpec.model_validate({"name": "a1", "on": ["input"], "type": "rust"})
+        ActionSpec.model_validate(
+            {"name": "a1", "listen_to": ["input"], "type": "rust"}
+        )
 
 
 def test_tool_spec_accepts_type() -> None:
@@ -208,7 +212,13 @@ def test_agent_spec_minimal() -> None:
 
 def test_agent_spec_action_can_be_string_reference() -> None:
     spec = AgentSpec.model_validate(
-        {"name": "a", "actions": ["shared_action1", {"name": "x", "on": ["input"]}]}
+        {
+            "name": "a",
+            "actions": [
+                "shared_action1",
+                {"name": "x", "listen_to": ["input"]},
+            ],
+        }
     )
     assert spec.actions[0] == "shared_action1"
     assert isinstance(spec.actions[1], ActionSpec)
@@ -232,7 +242,7 @@ def test_yaml_document_with_shared_resources_and_actions() -> None:
         {
             "agents": [{"name": "a"}],
             "chat_model_connections": [{"name": "c", "clazz": "x.Y"}],
-            "actions": [{"name": "shared", "on": ["input"]}],
+            "actions": [{"name": "shared", "listen_to": ["input"]}],
         }
     )
     assert doc.chat_model_connections[0].name == "c"
@@ -289,7 +299,7 @@ def test_action_spec_rejects_parameter_types() -> None:
         ActionSpec.model_validate(
             {
                 "name": "a1",
-                "on": ["input"],
+                "listen_to": ["input"],
                 "type": "java",
                 "parameter_types": ["x.Y"],
             }
diff --git a/python/flink_agents/e2e_tests/resources/yaml_cross_language_agent.yaml b/python/flink_agents/e2e_tests/resources/yaml_cross_language_agent.yaml
@@ -42,7 +42,7 @@ agents:
     actions:
       - name: process_input
         function: flink_agents.e2e_tests.e2e_tests_resource_cross_language.yaml_cross_language_actions:process_input
-        on: [input]
+        listen_to: [input]
       - name: process_chat_response
         function: flink_agents.e2e_tests.e2e_tests_resource_cross_language.yaml_cross_language_actions:process_chat_response
-        on: [chat_response]
+        listen_to: [chat_response]
diff --git a/python/flink_agents/e2e_tests/resources/yaml_multi_agent.yaml b/python/flink_agents/e2e_tests/resources/yaml_multi_agent.yaml
@@ -14,7 +14,7 @@ agents:
     actions:
       - name: chat_request
         function: flink_agents.e2e_tests.e2e_tests_integration.yaml_test_actions:chat_request
-        on: [input]
+        listen_to: [input]
       - process_chat_response
 
   - name: commentator_agent
@@ -31,7 +31,7 @@ agents:
     actions:
       - name: commentary_request
         function: flink_agents.e2e_tests.e2e_tests_integration.yaml_test_actions:commentary_request
-        on: [input]
+        listen_to: [input]
       - process_chat_response
 
 # File-level shared resources reused by every agent above.
@@ -43,4 +43,4 @@ chat_model_connections:
 actions:
   - name: process_chat_response
     function: flink_agents.e2e_tests.e2e_tests_integration.yaml_test_actions:process_chat_response
-    on: [chat_response]
+    listen_to: [chat_response]
diff --git a/python/flink_agents/e2e_tests/resources/yaml_test_agent.yaml b/python/flink_agents/e2e_tests/resources/yaml_test_agent.yaml
@@ -26,7 +26,7 @@ agents:
     actions:
       - name: process_input
         function: flink_agents.e2e_tests.e2e_tests_integration.yaml_test_actions:process_input
-        on: [input]
+        listen_to: [input]
       - name: process_chat_response
         function: flink_agents.e2e_tests.e2e_tests_integration.yaml_test_actions:process_chat_response
-        on: [chat_response]
+        listen_to: [chat_response]
