xintongsong commented on code in PR #232:
URL: https://github.com/apache/flink-agents/pull/232#discussion_r2385776065
##########
docs/content/docs/operations/configuration.md:
##########
@@ -22,8 +22,635 @@ 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**
Review Comment:
```suggestion
1. **Explicit Settings in Code**
```
##########
docs/content/docs/operations/configuration.md:
##########
@@ -22,8 +22,635 @@ 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**
+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
+
+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 reads configuration from a YAML file structured under the
**`agent:`** root key. This file is typically used when submitting jobs to a
Flink cluster or running locally with a custom configuration.
+
+#### Configuration Structure
Review Comment:
```suggestion
#### Format
```
##########
docs/content/docs/operations/configuration.md:
##########
@@ -22,8 +22,635 @@ 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**
+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
+
+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 reads configuration from a YAML file structured under the
**`agent:`** root key. This file is typically used when submitting jobs to a
Flink cluster or running locally with a custom configuration.
+
+#### Configuration Structure
+
+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**
+
+Flink Agents automatically loads configurations from
`$FLINK_CONF_DIR/conf.yaml`, ensuring the file includes the `agent:` section.
+
+- **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
+
+How to configure during the build agent time: please refer to the
documentation under "How to Build an Agents," specifically the document titled
["Workflow Agent"]({{< ref "docs/development/workflow_agent" >}}).
Review Comment:
I still don't know what this is. Don't find anything relevant in the linked
page.
##########
docs/content/docs/operations/configuration.md:
##########
@@ -22,8 +22,635 @@ 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**
+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
+
+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 reads configuration from a YAML file structured under the
**`agent:`** root key. This file is typically used when submitting jobs to a
Flink cluster or running locally with a custom configuration.
+
+#### Configuration Structure
+
+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**
+
+Flink Agents automatically loads configurations from
`$FLINK_CONF_DIR/conf.yaml`, ensuring the file includes the `agent:` section.
Review Comment:
This is confusing. User may wonder whether they should make the
configurations for flink-agents a separate yaml file or part of the flink
config.yaml file. We should explain that both ways are fined, and also when
should we use which way.
##########
docs/content/docs/operations/configuration.md:
##########
@@ -22,8 +22,635 @@ 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**
+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
+
+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 reads configuration from a YAML file structured under the
**`agent:`** root key. This file is typically used when submitting jobs to a
Flink cluster or running locally with a custom configuration.
Review Comment:
We should say "Flink Agents **allows / supports** reading configurations
from a YAML file." Because this is not the default behavior. It's just an
option we provided to users.
And the "structured under the **`agent:`** root key" here is confusing. We
don't need to mention it as it will be explained in subsequent sections.
##########
docs/content/docs/operations/configuration.md:
##########
@@ -22,8 +22,635 @@ 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**
+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
+
+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 reads configuration from a YAML file structured under the
**`agent:`** root key. This file is typically used when submitting jobs to a
Flink cluster or running locally with a custom configuration.
+
+#### Configuration Structure
+
+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**
+
+Flink Agents automatically loads configurations from
`$FLINK_CONF_DIR/conf.yaml`, ensuring the file includes the `agent:` section.
Review Comment:
I think we might want to say that including the flink-agents configurations
in the flink config.yaml is the default, and using a separate file is a special
case only for local python execution without a flink cluster.
--
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]
