> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Read and Write Optimized Agents

> Configure the Lumos On-Premise Agent to prefer read or write connector operations.

## **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):
  ```powershell theme={null}
  setx /M LUMOS_ON_PREMISE_AGENT_OPERATION_MODE "READ_PREFERRED"
  ```
* Docker:
  ```bash theme={null}
  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`):
  ```toml theme={null}
  [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.

<br />