This is an automated email from the ASF dual-hosted git repository.
sxnan pushed a commit to branch release-0.1
in repository https://gitbox.apache.org/repos/asf/flink-agents.git
The following commit(s) were added to refs/heads/release-0.1 by this push:
new 726a70c [doc] Add Consistency Guarantee section in deployment
documentation. (#269)
726a70c is described below
commit 726a70c067b7844d54455f10f27658aa075f5b84
Author: Xuannan <[email protected]>
AuthorDate: Fri Oct 10 16:42:29 2025 +0800
[doc] Add Consistency Guarantee section in deployment documentation. (#269)
---
docs/content/docs/operations/configuration.md | 6 +++---
docs/content/docs/operations/deployment.md | 26 ++++++++++++++++++++++++++
2 files changed, 29 insertions(+), 3 deletions(-)
diff --git a/docs/content/docs/operations/configuration.md
b/docs/content/docs/operations/configuration.md
index 16e454d..688ed7e 100644
--- a/docs/content/docs/operations/configuration.md
+++ b/docs/content/docs/operations/configuration.md
@@ -299,11 +299,11 @@ VectorStore built-in configuration options work only with
the VectorStore define
| ChromaVectorStore.collection | "flink_agents_chroma_collection"
| String | Name of the ChromaDB collection to use.
|
| ChromaVectorStore.create_collection_if_not_exists | true
| Boolean | Whether to create the collection if it doesn't exist.
|
-### State Store
+### Action State Store
-#### Kafka-based State Store
+#### Kafka-based Action State Store
-Here is the configuration options for Kafka-based State Store.
+Here are the configuration options for Kafka-based Action State Store.
| Key | Default | Type |
Description |
|-------------------------------------|--------------------------|---------|-----------------------------------------------------------------------------|
diff --git a/docs/content/docs/operations/deployment.md
b/docs/content/docs/operations/deployment.md
index f4a0748..76036b6 100644
--- a/docs/content/docs/operations/deployment.md
+++ b/docs/content/docs/operations/deployment.md
@@ -153,3 +153,29 @@ Currently, to resolve the classloader issue, user should
place the Flink Agents
Now you should see a Flink job submitted to the Flink Cluster in Flink web UI
(typically accessible at http://<jobmanagerHost>:8081).
+
+
+## Consistency Guarantees
+
+Flink Agents leverage Flink’s checkpointing to provide **exactly-once output
consistency**. Exactly-once output consistency does not mean each event is
processed only once; it means that every event will affect the state and output
result exactly once. This is sufficient for typical data-processing use cases
where the processing of data does not cause any external side effects.
+
+However, actions in Flink Agents can trigger external side effects (for
example, sending an email or invoking an external API). These side effects
should not be executed more than once. To address this, Flink Agents support
**exactly-once action consistency** by leveraging an external action state
store.
+
+### Exactly-Once Output Consistency
+
+When a job runs on a Flink cluster, Flink periodically takes checkpoints. See
[Flink
Checkpointing](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/ops/state/checkpoints/)
for details.
+After recovery from a checkpoint, Flink Agents reprocess events that arrived
after that checkpoint. As a result, any actions triggered by those events may
be executed again.
+
+### Exactly-Once Action Consistency
+
+To ensure exactly-once action consistency, you must configure an external
action state store. Flink Agents record action state in this store on a
per-action basis. After recovering from a checkpoint, Flink Agents consult the
external store and will not re-execute actions that were already completed.
This guarantees each action is executed exactly once after recovering from a
checkpoint.
+
+{{< hint info >}}
+**Note**: Currently, Kafka is supported as the external action state store.
+{{< /hint >}}
+
+See [Action State Store Configuration]({{< ref
"docs/operations/configuration#action-state-store" >}}) for configuration
options.
+
+{{< hint info >}}
+**Note**: Exactly-once action consistency is guaranteed only if, after
recovering from the same checkpoint, inputs for each key arrive in the same
order as before recovery. If this ordering requirement is not met, the system
falls back to exactly-once output consistency.
+{{< /hint >}}
