diff --git a/docs/content/docs/development/workflow_agent.md b/docs/content/docs/development/workflow_agent.md
index 11ef50502..798fef583 100644
--- a/docs/content/docs/development/workflow_agent.md
+++ b/docs/content/docs/development/workflow_agent.md
@@ -490,6 +490,58 @@ To use async execution on JDK 21+, user should append jvm option `--add-exports=
 {{< /tab >}}
 {{< /tabs >}}
 
+### Cross-language Actions
+
+An action declared in one language can dispatch its body to the other language by setting a `target` on the decorator/annotation. The decorated function or annotated method then acts as a stub — it should raise so direct calls outside the framework fail loud.
+
+{{< tabs "Cross-language Actions" >}}
+
+{{< tab "Python" >}}
+```python
+from flink_agents.api.function import JavaFunction
+
+class MyAgent(Agent):
+    @action(
+        InputEvent.EVENT_TYPE,
+        target=JavaFunction(
+            qualname="com.example.MyHandlers",
+            method_name="handleInput",
+            parameter_types=[
+                "org.apache.flink.agents.api.Event",
+                "org.apache.flink.agents.api.context.RunnerContext",
+            ],
+        ),
+    )
+    @staticmethod
+    def handle_input(event: Event, ctx: RunnerContext) -> None:
+        raise NotImplementedError("cross-language stub")
+```
+{{< /tab >}}
+
+{{< tab "Java" >}}
+```java
+public class MyAgent extends Agent {
+    @Action(
+            listenEventTypes = {InputEvent.EVENT_TYPE},
+            target = @PythonFunction(
+                    module = "my_pkg.handlers",
+                    qualname = "handle_input"))
+    public static void handleInput(Event event, RunnerContext ctx) {
+        throw new UnsupportedOperationException("cross-language stub");
+    }
+}
+```
+{{< /tab >}}
+
+{{< /tabs >}}
+
+{{< hint warning >}}
+**Limitations:**
+
+- Cross-language actions are currently supported only when [running in Flink]({{< ref "docs/operations/deployment#run-in-flink" >}}), not in local development mode
+- Complex object serialization between languages may have limitations
+{{< /hint >}}
+
 ## Event
 
 Events are JSON-serializable messages passed between actions. Every event has a `type` string used for routing and an `attributes` map that carries the payload. A single event may trigger multiple actions if they are all listening to its type.
diff --git a/docs/content/docs/development/yaml.md b/docs/content/docs/development/yaml.md
index 9bea5c467..30760d803 100644
--- a/docs/content/docs/development/yaml.md
+++ b/docs/content/docs/development/yaml.md
@@ -525,7 +525,7 @@ Loaded with `agents_env.load_yaml(...)` on the Python side, this produces an age
 - `math_chat_model` is a Python Ollama setup that calls a Java function tool through the cross-language tool bridge.
 - `creative_chat_model` is a Java Ollama setup driven from the Python loader via the Java chat-model wrapper.
 
-Not every resource type is cross-language. Currently `chat_model_connections`, `chat_model_setups`, `embedding_model_connections`, `embedding_model_setups`, and `vector_stores` support `type:` on the opposite language; others (e.g. `mcp_servers`) do not.
+Not every resource type is cross-language. Currently `actions`, `tools`, `chat_model_connections`, `chat_model_setups`, `embedding_model_connections`, `embedding_model_setups`, and `vector_stores` support `type:` on the opposite language; others (e.g. `mcp_servers`) do not.
 
 ## YAML API Specification