Configuring Read and Write Optimized Agents

What it is?

A configurable setting that allows agents to declare a connector operation type to prefer. The agent-specific mode that declares which types of connector operations the agent intends to run. It is advertised to Lumos on every request and heartbeat, and used by Lumos to queue compatible operations for the agent. The operation options are as follows:

DEFAULT: Can perform both read and write operations.
READ_PREFERRED: Will prioritize handling non-mutating (read-only) operations.
WRITE_PREFERRED: Will prioritize handling mutating (write) operations.
If a mismatched operation is received by the agent (e.g., write while in read mode), the agent logs an error but will still attempt to execute it. Treat this as an intent/guardrail signal.
Note - as the name states, these are the agents preferred operations, however there are certain situations in which the agent will be able to perform operations outside of the designated preference read operations despite being set a write agent, and vice versa:
- If there are zero healthy agents in a cluster which are capable of performing an operation type (ex. zero read capable agents), then agents in the cluster will perform any operation. This is a fail-safe to prevent agent operations from being blocked.

Setup Instructions

How to set it (Environment Variable)

Name: LUMOS_ON_PREMISE_AGENT_OPERATION_MODE
Allowed values: default, read_preferred, write_preferred

Windows (system-wide):

setx /M LUMOS_ON_PREMISE_AGENT_OPERATION_MODE "READ_PREFERRED"

Docker:

docker run --platform linux/amd64 -d \\
  --restart unless-stopped \\
  -e LUMOS_ON_PREMISE_AGENT_API_KEY=$LUMOS_ON_PREMISE_AGENT_API_KEY \\
  -e LUMOS_ON_PREMISE_AGENT_OPERATION_MODE=WRITE_PREFERRED \\
  public.ecr.aws/g3l5j2q0/lumos/on-premise-agent

How to set it (settings.toml):

In [agent-settings] (case-insensitive key; value accepts DEFAULT, READ_PREFERRED, WRITE_PREFERRED):
```
[agent-settings]
agent-operation-mode = "READ_PREFERRED"
```
Invalid values are ignored and the agent keeps/uses DEFAULT.
Precedence and default:
- If both are provided, the value in settings.toml overrides the environment variable at runtime.
- If not set anywhere, the agent will fall back to default and be able to perform any operation.