Agent engineering — six lenses¶
reyn read through six engineering perspectives. Each lens is a different way to ask "what does this system get right, and where is it still thin?" The same docs are pointed at from multiple lenses; this index is the map.
The picture¶
┌──────────────────────────────────────────────────┐
│ │
│ User │
│ │ │
│ ▼ │
│ Agent ── selects a Workflow ─────► Workflow │ ← System Design
│ │ │ ← Tool Contract
│ ▼ │
│ OS ◄──── runtime loop ──┤ │ ← Reliability
│ │ ▼ │
│ │ Phase │ ← Retrieval
│ │ (input + instructions)│ (preprocessor)
│ │ │ │
│ │ ▼ │
│ │ Workspace │ ← Security
│ │ │ (permissions)
│ ▼ │
│ ┌────────┐ │
│ │ Events │ ─────► JSONL replay log │
│ └────────┘ │
│ │
└──────────────────────────────────────────────────┘
← Product Think
(CLI, cost, UX)
Every layer has a corresponding engineering lens. The lenses don't partition the system; they overlap on purpose.
The six lenses¶
1. System Design¶
The macro shape: how control flow, state, and responsibility are distributed across layers. In reyn this is the Phase / Workflow / OS split — Phases are stateless and reusable, workflows own structure, the OS owns execution.
2. Tool Contract Design¶
How the LLM acts on the world: the typed envelope that carries side effects (Control IR), the typed envelope that carries decisions (candidate_outputs), and the deterministic enrichment hook (preprocessor).
3. Retrieval Engineering¶
Getting the right context into the agent at the right time. reyn has recall_memory for project- and user-scope facts, integrated as a preprocessor step. This is one of the system's thinner areas — see the page for what's missing.
4. Reliability Engineering¶
Recovery from failure: validation, re-prompt, loop bounds, timeout. reyn validates every LLM output against the next target's schema and re-prompts on rejection; long loops are bounded by limits.phase.max_visits and a soft per-phase wall-clock budget. LLM HTTP calls have a configurable timeout and exponential-backoff retry. Richer retry policies and checkpoint/resume are still on the roadmap.
5. Security¶
Capability gating, sandbox boundaries, trust scoping. The three-layer permission model + AST sandbox for pure Python steps + per-workflow approvals are the core.
6. Product Think¶
The agent as a product: CLI affordances, cost discipline, predictable UX. Model classes (light/standard/strong), per-run cost reporting, and output_language localization are the levers reyn currently exposes.
How to read this section¶
- New to agent engineering generally? Read in order — the lenses build a vocabulary.
- Coming from another framework? Skip to the lens you care most about; cross-links will pull you back to the others as needed.
- Doing self-assessment for your own system? The "where it's still thin" passages on retrieval and reliability are the candid bits.