58 lines
2.8 KiB
Markdown
58 lines
2.8 KiB
Markdown
# Agent Discipline: Config Verification
|
|
|
|
This reference captures hard lessons about agent behavior with configuration.
|
|
|
|
## Rule
|
|
|
|
**Never set a configuration key unless you have verified it exists in the application's documentation, schema, or known-good examples.**
|
|
|
|
If you *assume* a config key exists and write it to a production config file:
|
|
|
|
1. The application silently ignores it (at best) or crashes (at worst)
|
|
2. The user's intent is not met
|
|
3. The agent appears to have fixed the problem when nothing actually changed
|
|
4. The bad key pollutes the config file and wastes debugging time later
|
|
|
|
## Examples of past violations
|
|
|
|
- `fallback_providers` — invented, does not exist in Hermes Agent config schema. The real behavior (manual provider switch) was never configured.
|
|
|
|
## Config file corruption during Python editing
|
|
|
|
Python scripts that read, search/replace, and write YAML config files can **corrupt the file structure** if the replacement logic is wrong (wrong old_string, partial match, or mismatched indentation). This causes Hermes to fail silently or crash on restart.
|
|
|
|
**This session's example:** Replacing `api_key: sk-lbh...bWPA` in the anita profile config (literally the string `sk-lbh...bWPA` with the dots) overwrote the real key value with the literal characters `sk-lbh...bWPA`, causing `HTTP 401: Authentication Error` every time Anita's gateway tried to authenticate against admin-ai.
|
|
|
|
**Rule:** Never use the *displayed/redacted* version of a credential in a search-and-replace operation. The redacted value shown in a `read_file` response (e.g. `sk-lbh...bWPA`) is NOT the real value — the dots are literal characters in the edit buffer but represent truncated content on disk. Always extract the raw value from a hex dump, raw bytes, or the original source file.
|
|
|
|
**Preferred workflow for credential fixing:**
|
|
|
|
```bash
|
|
# Step 1: Get the exact raw key bytes from the source
|
|
python3 -c "
|
|
with open('/root/.hermes/config.yaml', 'rb') as f:
|
|
for line in f:
|
|
if b'api_key:' in line and b'vision' not in line:
|
|
print(line.hex())
|
|
"
|
|
# Step 2: Decode hex to verify the real string
|
|
echo '736b2d6c626868...' | xxd -r -p
|
|
# Step 3: Write the raw string to the target file
|
|
python3 -c "
|
|
with open('/root/.hermes/profiles/anita/config.yaml') as f:
|
|
content = f.read()
|
|
content = content.replace('api_key: VERIFIED_BAD_VALUE', 'api_key: REAL_VALUE')
|
|
with open('/root/.hermes/profiles/anita/config.yaml', 'w') as f:
|
|
f.write(content)
|
|
"
|
|
```
|
|
|
|
**Alternative:** Write the entire file fresh using `write_file` instead of search/replace — less error-prone for small config files.
|
|
|
|
## When a mistake happens
|
|
|
|
- Acknowledge it immediately
|
|
- Remove the bad config key
|
|
- Document what the actual approach should be
|
|
- Do not repeat the same assumption in the same session or on the same application
|