Deriving an Agent Runtime
agentd is a daemon I’m working on to run autonomous AI agents on self-hosted infrastructure. It will schedule agent sessions, construct isolated execution environments, wire tools via MCP, and manage credentials.
The project is early and experimental. Five Rust crates, all stubs. The architecture is only an intent. I needed a document that captured that intent from three perspectives: developers who need to know where code goes, plugin authors who need the MCP server contract, and AI agents that will contribute code. I filed an issue with a detailed spec and handed it to Claude Opus 4.6.
Opus produced ARCHITECTURE.md in a single pass. The document was solid. But the thing I was most interested in wasn’t the output. It was the method that produced it.
What Agents Actually Need
Every architectural decision in agentd traces to a capability that agents need in order to do useful work. Not “what features should we build” but “what does an agent require to function?” Start there and the architecture derives itself.
Seven needs:
| Need | What agents require | What the runtime provides |
|---|---|---|
| Network | Reach external services | Container network policy |
| Credentials | Authenticate to APIs | Secrets injection, per-agent isolation |
| Identity | Persist state across sessions | Home directory, AGENT_NAME env var |
| Mission | Know what to do | Session context from scheduler |
| Tools | Do things | CLI tools + MCP server plugins |
| Context | Understand the environment | Read-only mounted data |
| Skills | Reusable capabilities | Skill files loaded at session setup |
All seven are derived from what agents require to function and produce coherent output over multiple sessions. Remove any one and you don’t have a degraded agent runtime; you have a broken one.
Sessions from Scheduling Through Teardown
A session is a single execution of an agent, from trigger to teardown. Four phases:
Scheduling: The scheduler determines when to invoke an agent. Triggers include cron-based schedules, external events, and manual invocation. When a trigger fires, the scheduler passes the agent’s identity and trigger context to the runner.
Session Setup: The runner constructs the agent’s execution environment, and the order matters. It starts by building a container from the agent’s base image, then layers identity onto it: the agent’s name and a home directory. Credentials come next, injected as mounted secrets. The runner mounts read-only context data and loads skill files. Finally, it starts each configured MCP server plugin, connects their stdio, and registers their tools. By the time the agent’s process launches, the environment is complete.
Execution: The agent runs. Tool invocations flow through the transport layer to the appropriate plugin and responses return the same way.
Teardown is the inverse. When the session completes or times out, the runner persists the agent’s home directory to the host filesystem, terminates plugin processes, and removes the container. State written during the session survives for the next one.
Traceability
Every architectural decision maps back to a capability need, with evidence in the workspace and a failure consequence if the decision were reversed.
Some mappings are straightforward. Agents need to reach external services, so containers have configurable network access. Agents need credentials, so the runner injects secrets. Others carry more weight than they appear to. Persistent home directories aren’t a convenience feature; they exist because agents need to work across sessions. Without them, every session starts cold, with no memory of previous work. The scheduler doesn’t just trigger sessions. It passes context so the agent has mission: not just “run now” but “run now because this event happened and you need to respond in such-and-such a way.”
No decision exists without a traced need. No need exists without an architectural response. If you can’t trace a decision to a need, it shouldn’t exist. If a need has no architectural response, the architecture has a gap.
What This Revealed About Agents and Architecture
The agent produced ARCHITECTURE.md in a single session. The capability needs, the crate boundary table, the verification matrix. All derived correctly, all grounded in evidence from the codebase. Review feedback refined the edges: a sentence that ended weakly, a constraint stated too narrowly, a claim of exhaustiveness where the design should stay open. The structure held.
Architectural documentation turns out to be exactly the kind of work where agents excel. It’s compilation. The agent didn’t need to invent the architecture. It needed to articulate what was already implied by the constraints.
Agents are exceptional at compilation and synthesis from specs. They can derive a clean architecture document from a well-structured issue, map needs to boundaries, and produce verification matrices. The edges where they need human input aren’t structural. They’re epistemic: knowing when a constraint is too narrow, when a claim should stay open, when the design needs deliberate vagueness instead of false precision.
Give an agent good source material and a clear derivation framework, and the architectural reasoning follows. The framework is the thing.