[docs] Improve consistency and configuration guidance

docs/content/_index.md

@@ -45,7 +45,7 @@ It provides a step by step introduction on how to install Flink Agents and build
 
 ### How to Operate an Agent
 
-* [Deployment]({{< ref "docs/operations/deployment" >}}), [Configuration]({{< ref "docs/operations/configuration" >}}), and [Monitoring]({{< ref "docs/operations/monitoring" >}}) - Deploy, configure, and monitor agents
+* [Deployment]({{< ref "docs/operations/deployment" >}}), [Consistency]({{< ref "docs/operations/consistency" >}}), [Configuration]({{< ref "docs/operations/configuration" >}}), and [Monitoring]({{< ref "docs/operations/monitoring" >}}) - Deploy, configure, recover, and monitor agents
 
 <--->
 

docs/content/docs/development/calling-llms/chat.md

@@ -259,13 +259,12 @@ the failure.
 <span id="failures-and-recovery"></span>
 
 Model-call failures are reported after configured retries and routing fallbacks
-are exhausted. See [Core Options]({{< ref "docs/operations/configuration#core-options" >}})
+are exhausted. See [Model calls, tools, and retries]({{< ref "docs/operations/configuration#model-calls-tools-and-retries" >}})
 for retry settings and [Model Routing]({{< ref "docs/development/calling-llms/model_routing" >}})
 for fallbacks.
 
 For how calls behave after a failure and recovery, see
-[Recovery Behavior]({{< ref "docs/development/create-agent/actions#recovery-behavior" >}})
-in Actions.
+[Recovery flow]({{< ref "docs/operations/consistency#recovery-flow" >}}).
 
 ## Multimodal Messages {#message-content-blocks}
 

docs/content/docs/development/calling-llms/model_routing.md

@@ -281,7 +281,7 @@ behaviors:
 
 For candidates `[small, medium, big]`, selecting `big` with fallback enabled tries
 `big`, then `small`, then `medium`. Model-call retries run before fallback; see
-[Core Options]({{< ref "docs/operations/configuration#core-options" >}}).
+[Model calls, tools, and retries]({{< ref "docs/operations/configuration#model-calls-tools-and-retries" >}}).
 Failures before the call, such as an unresolved model resource, can proceed
 directly to the next candidate without retries.
 
@@ -354,7 +354,7 @@ metadata when distinguishing their usage.
 With durable execution enabled, completed routing decisions and model calls can
 be reused after recovery. Without it, a request may be routed again and select a
 different model. See
-[Recovery Behavior]({{< ref "docs/development/create-agent/actions#recovery-behavior" >}})
+[Consistency]({{< ref "docs/operations/consistency#recovery-guarantees-and-user-responsibilities" >}})
 for the persistence and replay guarantees.
 
 ## Examples

docs/content/docs/development/calling-llms/tool_use.md

@@ -437,9 +437,9 @@ inside each tool, such as an HTTP client read timeout.
 A batch timeout does not undo external effects or guarantee that an already
 running tool stops. Tools that change external systems should be idempotent,
 because a call may run again after recovery. See
-[Configuration]({{< ref "docs/operations/configuration" >}}) for the full async batch
+[Configuration]({{< ref "docs/operations/configuration#runtime-and-async-execution" >}}) for the full async batch
 and execution-capacity options, and
-[Durable Execution]({{< ref "docs/development/create-agent/actions#durable-execution" >}})
+[Consistency]({{< ref "docs/operations/consistency#recovery-guarantees-and-user-responsibilities" >}})
 for recovery guarantees.
 
 ## Tool response content and metadata

docs/content/docs/development/create-agent/actions.md

@@ -562,8 +562,9 @@ For example, if an Action fails after a profile lookup has completed and its res
 been persisted, recovery can reuse that profile instead of querying the service again.
 Code outside the durable call may still run again when the Action is re-executed.
 
-Durable execution requires an external action state store. Configure it as described in
-[Exactly-Once Action Consistency]({{< ref "docs/operations/deployment#exactly-once-action-consistency" >}}).
+To save and reuse call outcomes during recovery, configure checkpointing and an external
+Action State Store as described in
+[Consistency]({{< ref "docs/operations/consistency#configure-an-action-state-store" >}}).
 
 #### A Durable Call
 
@@ -628,18 +629,10 @@ Java's `getResultClass()` provides the type needed to deserialize a saved result
 
 #### Recovery Behavior
 
-When recovery re-executes an unfinished Action and reaches a durable call:
-
-| State of the matching call | Recovery behavior |
-| --- | --- |
-| A successful result has been persisted | Return the saved result without calling the function again. |
-| A failure has been persisted | Replay the failure without calling the function again. |
-| No completed outcome has been persisted | Execute the function again, or use the reconciler for a previously recorded in-flight call. |
-
-An external operation may finish before its result is persisted. If a failure occurs in
-that interval, calling the operation again can repeat its side effects. For such
-operations, use the external service's idempotency support or a reconciler that can
-recover the existing outcome.
+See [Recovery flow]({{< ref "docs/operations/consistency#recovery-flow" >}}) for how recovery
+handles saved outcomes and in-flight calls, and
+[Limits on external side effects]({{< ref "docs/operations/consistency#limits-on-external-side-effects" >}})
+for operations that may repeat.
 
 #### Reconciling an In-flight Call
 
@@ -799,9 +792,10 @@ worker and batch limits. Concurrency between Actions has additional requirements
   the cross-language Flink versions below.
 - **Python Actions:** use `async def` and the framework's futures and `gather` APIs.
 
-See [Core Options]({{< ref "docs/operations/configuration#core-options" >}}) for worker-pool
-and concurrency limits. These scheduling requirements apply to both ordinary and durable
-async calls. Durable calls additionally require the configured action state store.
+See [Runtime and async execution]({{< ref "docs/operations/configuration#runtime-and-async-execution" >}})
+for worker-pool and concurrency limits. These scheduling requirements apply to both ordinary
+and durable async calls. Saving durable call outcomes for recovery additionally requires
+an Action State Store.
 
 #### Cross-language Async Requirements
 
@@ -886,7 +880,7 @@ missing value.
 
 Reading a missing attribute without a guard or applying an operation to an incompatible
 value can fail while evaluating a condition for an Event. For failure handling options, see
-[`action.trigger-condition.evaluate-failure-strategy`]({{< ref "docs/operations/configuration#core-options" >}})
+[`action.trigger-condition.evaluate-failure-strategy`]({{< ref "docs/operations/configuration#condition-handling" >}})
 in Configuration.
 
 #### Limitations

docs/content/docs/development/memory/memory_events.md

@@ -238,7 +238,7 @@ Because `agent-run.begin-event` is disabled by default, the Trace Log has no bui
 
 ## Semantics & Caveats
 
-- **Trace Log level.** Configure [recording targets]({{< ref "docs/operations/configuration#trace-log-targets" >}}) with `scope: EVENT_ONLY` and `level: VERBOSE` when full memory-event attributes are required, or select individual Event names with an entity scope. Memory-event generation and log selection are independent: the emission switches determine whether Events are produced, while targets determine whether they are written to Trace Log.
+- **Trace Log level.** Configure [recording targets]({{< ref "docs/operations/monitoring#recording-targets" >}}) with `scope: EVENT_ONLY` and `level: VERBOSE` when full memory-event attributes are required, or select individual Event names with an entity scope. Memory-event generation and log selection are independent: the emission switches determine whether Events are produced, while targets determine whether they are written to Trace Log.
 - **Durable execution.** A long-term memory operation wrapped in `durable_execute` is not recorded again when the durable result is replayed from state. The generated events describe operations that actually executed in the current attempt.
 - **Observation failures.** Unsupported short-term or sensory values are omitted. Invalid long-term records are skipped individually after a valid batch is parsed, but a bridge, batch-serialization, or malformed-payload failure drops the current partition key's LTM observation batch. Warnings do not include observed values. These failures do not fail the action or roll back a completed long-term backend operation.
 - **Failed actions.** A failed action does not reach the memory-event emission boundary. The operator task fails and recovery rebuilds the interpreter, so queued actions do not continue in the same interpreter instance after the failure.

docs/content/docs/development/multi-agent/subagents.md

@@ -1253,8 +1253,12 @@ triggers recovery.
 
 Sub-agent calls use
 [durable execution]({{< ref "docs/development/create-agent/actions#durable-execution" >}}).
-Recovery reuses persisted results. Work whose result has not been persisted may
-run again, so external services need to handle retried requests.
+With checkpointing and an
+[Action State Store]({{< ref "docs/operations/consistency#configure-an-action-state-store" >}}),
+recovery reuses persisted results. Work whose result has not been persisted may
+run again, so external services need to handle retried requests. See
+[Consistency]({{< ref "docs/operations/consistency#recovery-guarantees-and-user-responsibilities" >}})
+for replay conditions and limits on repeated effects.
 
 The framework generates stable `session_id` and `call_id` values for recovery.
 If you supply your own IDs, keep them unchanged when the same call is retried.

docs/content/docs/get-started/overview.md

@@ -33,7 +33,7 @@ Like any Agent OS, it manages the core building blocks of an agent - orchestrati
 The key features of Apache Flink Agents include:
 - **Massive Scale and Millisecond Latency**: Processes massive-scale event streams in real time, leveraging Flink's distributed processing engine.
 - **Seamless Data and AI Integration**: Agents interact directly with Flink's DataStream and Table APIs for input and output, enabling a smooth integration of structured data processing and semantic AI capabilities within Flink.
-- **Reliable and Exactly-Once Execution**: Ensures exactly-once consistency for agent actions and their side effects by integrating Flink's checkpointing with an external write-ahead log, and supports durable execution - optionally with reconcilers to reconcile in-flight side effects upon failure recovery - so agents run reliably without human supervision.
+- **Reliable Execution**: Builds on Flink checkpointing and supports an external Action State Store to reuse saved Action completions and durable call outcomes during recovery. See [Consistency]({{< ref "docs/operations/consistency" >}}) for setup, guarantees, and limits on external side effects.
 - **Familiar Agent Abstractions**: Leverages well-known AI agent concepts - skills, short/long-term memory, prompts, tools, and dynamic orchestration - making it easy for developers experienced with agent-based systems to quickly adopt and build on Apache Flink Agents without a steep learning curve.
 - **Multi-Language Support**: Provides Java, Python, and YAML APIs for defining Agents. Actions and supported Resources can be implemented in Java or Python and used across languages. See [Choose APIs and Languages]({{< ref "docs/development/create-agent/choose-apis-and-languages" >}}).
 - **Rich Ecosystem**: Natively integrates mainstream LLMs, vector stores from diverse providers, and tools or prompts hosted on MCP servers into your agents, while enabling customizable extensions.

docs/content/docs/get-started/setup.md

@@ -434,5 +434,6 @@ submits a complete example and shows its output:
 - [Use the Built-in ReAct Agent]({{< ref "docs/get-started/quickstart/react_agent" >}})
 - [Define an Agent with YAML]({{< ref "docs/get-started/quickstart/yaml_agent" >}})
 
-For a remote cluster, and for the consistency guarantees that apply once the job runs
-there, see [Deployment]({{< ref "docs/operations/deployment" >}}).
+For submission to a remote cluster, see
+[Deployment]({{< ref "docs/operations/deployment#submit-to-flink-cluster" >}}).
+For consistency guarantees, see [Consistency]({{< ref "docs/operations/consistency" >}}).