Part 1 of 7 · 2 min read
Overview
In this module you will
- Explain what a secret is and the rules for keeping one safe.
- Read all configuration from environment variables, checked once at start-up.
- Keep API keys out of code, Git history, logs and error messages.
- Write structured (JSON) logs that let you answer "what happened in request X?".
- Use a small scanner to catch a leaked key before it is committed.
Why this matters for agents
Agents hold powerful keys: model providers (billed for every use), search services, databases, email. A leaked model key can be found by automatic bots within minutes and used to run up a large bill.
Agents also make long, branching runs where something goes wrong at step seven of twelve. Without good logs you cannot see why. Both problems are cheap to prevent now and expensive to fix later.
The problem: a key in the wrong place
Imagine this. You build a small agent, and to make it work you paste your model provider's key straight into the code:
client = ModelClient(api_key="sk-live-abc123...") # NEVER do this
It works. You commit the project and push it to GitHub so a friend can see it. Within minutes, automatic programs that scan GitHub for keys find it. By the next morning, someone else has used your key to make thousands of calls, and the provider's bill is yours.
Nothing about the code was wrong. The key was in the wrong place. This module is about the right places, and about the logs that tell you what your program did. First, four words.
Secret
A value that grants access or identity: API keys, tokens, passwords, private keys, database connection strings. Anyone who has it can act as you.
Configuration
Anything that differs between environments (your laptop, a test run, production) without changing the code: web addresses, model names, timeouts, log level, and the secrets themselves.
Environment variable
A named value that the operating system hands to a program when it starts, for example APP_LLM_API_KEY=.... Every language and every hosting platform can read them, which is why they are the common meeting point between your code and its settings.
Structured logging
Writing each log entry as a record with named fields (usually one JSON object per line), instead of a free-text sentence. A computer can then search and count the fields.
Check yourself
- Why is a key in the code a problem even if the repository is private?
- What is the difference between a secret and other configuration?