GreatEugenius commented on code in PR #232:
URL: https://github.com/apache/flink-agents/pull/232#discussion_r2404850044
##########
docs/content/docs/operations/configuration.md:
##########
@@ -22,8 +22,664 @@ specific language governing permissions and limitations
under the License.
-->
-{{< hint warning >}}
-**TODO**: How to configure Flink Agents for local execution and Flink cluster
execution.
+## How to configure Flink Agents
-**TODO**: List of all built-in Configuration options.
-{{< /hint >}}
\ No newline at end of file
+There are three ways to configure Flink Agents:
+
+1. **Explicit Settings in Code**
+2. **YAML Configuration File**
+3. **Configuration During Build Agent Time**
+
+{{< hint info >}}
+The priority of configuration sources, from highest to lowest, is: **Explicit
Settings**, followed by **YAML Configuration File**, and finally
**Configuration During Build Agent Time**. In case of duplicate keys, the value
from the highest-priority source will override those from lower-priority ones.
+{{< /hint >}}
+
+### Explicit Settings in Code
+
+Users can explicitly modify the configuration when defining the
`AgentsExecutionEnvironment`:
+
+{{< tabs>}}
+{{< tab "python" >}}
+
+```python
+# Get Flink Agents execution environment
+agents_env = AgentsExecutionEnvironment.get_execution_environment()
+
+# Get configuration object from the environment
+config = agents_env.get_configuration()
+
+# Set custom configuration using a direct key (string-based key)
+# This is suitable for user-defined or non-standardized settings.
+config.set_str("OpenAIChatModelSetup.model", "gpt-5")
+
+# Set framework-level configuration using a predefined ConfigOption class
+# This ensures type safety and better integration with the framework.
+config.set(FlinkAgentsCoreOptions.KAFKA_BOOTSTRAP_SERVERS,
"kafka-broker.example.com:9092")
+```
+
+{{< /tab >}}
+
+{{< tab "java" >}}
+
+```java
+// Get Flink Agents execution environment
+AgentsExecutionEnvironment agentsEnv =
AgentsExecutionEnvironment.getExecutionEnvironment(env);
+
+// Get configuration object
+Configuration config = agentsEnv.getConfig();
+
+// Set custom configuration using key (direct string key)
+config.setInt("kafkaActionStateTopicNumPartitions", 128); // Kafka topic
partitions count
+
+// Set framework configuration using ConfigOption (predefined option class)
+config.set(AgentConfigOptions.KAFKA_BOOTSTRAP_SERVERS,
"kafka-broker.example.com:9092"); // Kafka cluster address
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
+### YAML Configuration File
+
+Flink Agents allows reading configurations from a YAML file.
+
+#### Format
+
+The YAML file must follow this format, with all agent-specific settings nested
under the `agent:` key:
+
+```yaml
+agent:
+ # Agent-specific configurations
+ OpenAIChatModelSetup.model: "gpt-5"
+ OpenAIChatModelConnection.max_retries: 10
+```
+
+{{< hint info >}}
+- The `agent:` key is required as the root namespace for Flink Agents
configurations.
+- This differs from standard Flink configurations (which use `flink-conf.yaml`
without a root key).
+{{< /hint >}}
+
+
+#### Loading Behavior
+
+**Local Mode**
+
+Use the `AgentsExecutionEnvironment.get_configuration()` API to load a custom
YAML file directly:
+
+```python
+config = agents_env.get_configuration("path/to/your/config.yaml")
+```
+
+**MiniCluster Mode / Cluster Submission**
+
+By default, Flink Agents configurations are included in the standard Flink
configuration file (config.yaml) used for cluster submissions.
+
+- **For MiniCluster**:
+ Manual setup is **required** — always export the environment variable before
running the job:
+
+ ```bash
+ export FLINK_CONF_DIR="path/to/your/config.yaml"
+ ```
+
+ This ensures the configuration directory is explicitly defined.
+
+- **For Cluster Submission**:
+ The configuration is automatically loaded from
`$FLINK_HOME/conf/flink-conf.yaml` (if the `agent:` section exists).
+
+### Configuration During Build Agent Time
+
+For resources like `ChatModel`, `EmbeddingModel`, and `VectorStore`, Flink
Agents allows configuration **during agent definition** via
`ResourceDescriptor`. This enables declarative setup of model parameters
directly in the agent class.
+
+#### Example: Defining a Math-Focused Chat Model
+
+``````python
+class MyAgent(Agent):
+ """Example agent demonstrating the new ChatModel architecture."""
+
+ @chat_model_connection
+ @staticmethod
+ def ollama_connection() -> ResourceDescriptor:
+ """Defines the connection to the Ollama model service."""
+ return ResourceDescriptor(
+ clazz=OllamaChatModelConnection # Connection class
+ )
+
+ @chat_model_setup
+ @staticmethod
+ def math_chat_model() -> ResourceDescriptor:
+ """Configures a math-focused chat model using the Ollama connection."""
+ return ResourceDescriptor(
+ clazz=OllamaChatModelSetup, # Model setup class
+ connection="ollama_connection", # Reference to the connection
method
+ model=OLLAMA_MODEL, #
Specific model name
+ tools=["add"], # Add tools
+ extract_reasoning=True # Enable reasoning extraction
+ )
+``````
+
+
+
+## Built-in configuration options
+
+Here is the list of all built-in configuration options.
+
+### ChatModel
+
+{{< hint info >}}
+ChatModel's built-in configuration options work only with the ChatModel
defined in Python.
Review Comment:
Yes, the ChatModel in Java has not yet been implemented when introducing the
configuration system. Currently, the ChatModel in Java does not support
automatically reading the built-in configuration.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
