Agent Build Stack
The folder-first map for building an Assembly Line agent.
Start with MD-First Agents for the composition model or the Declarative Reference for an exact field.
An Assembly Line agent is a directory. Each file or folder has one job, and the compiler turns that directory into a manifest, runtime artifact, route table, schedule table, and deploy plan.
agent.md is the required MD-first contract. Root skills are discovered
automatically; plugins, channels, infrastructure, automations, and subagents
are selected explicitly and recorded in the resolved manifest.
agent/
agent.md
skills/
plugins/
sandbox/
subagents/
evals/
assets/
plugins.lockFile Map
| Path | Purpose | Add it when |
|---|---|---|
agent.md | Identity, permanent instructions, profiles, channels, published plugins, automations, composition, mutability, and child names. | Always. |
skills/ | On-demand procedures and reference material. | Guidance is useful only sometimes, or the agent should improve by editing skills. |
plugins/ | Checked-in Agent Plugins v1 packages, auto-activated by presence. | The agent needs custom executable tools, connections, or capability-owned hooks. |
sandbox/ | Custom immutable YAML environment profiles. | A scalar provider profile is insufficient. |
subagents/ | Pi-backed child agents. | A task should run with a narrower identity, model, tool set, workspace, connection set, or durable run boundary. |
evals/ | Engagement-owned golden dataset. | You need regression checks for agent behavior, tool choices, structured output, cost, or qualitative criteria. |
assets/ | Agent-owned non-Skill, non-plugin resources. | Instructions or plugin code references stable source assets. |
plugins.lock | Exact published/local plugin integrity and executable authority. | Generated and refreshed by plugin CLI workflows. |
Design Rules
- Put identity, policy, profiles, channels, and routines in
agent.md. - Put custom executable capability code inside one cohesive local plugin.
- Put provider event parsing in a connection or channel provider; opt into runs with an automation.
- Keep deployment and storage visible as explicit profile fields.
- Put realtime service access in a capability plugin, not subagent configuration.
- Put reusable procedures in
skills/, not long tool descriptions. - Put secrets in environment variables or credential stores, never in model-visible files.
- Treat files, history, memory, search results, webpages, and tool output as untrusted context.
- Write generated artifacts and modified input copies under
/workspace. - In
bash, use paths relative to the workspace cwd for local-sandbox portability.
What Happens At Build Time
Assembly Line statically reads agent.md, root Skills, plugin descriptors and
entries, custom sandbox YAML, and nested agents. It records source and authority
hashes and emits .assembly-line/ without executing plugin code. evals/ is excluded from the revision hash, so
changing test cases never creates a new deployment revision.
agent/ source
-> compiler validation
-> manifest.json
-> route-table.json
-> automations.json
-> preflight.json
-> server/boot.jsFor the full artifact shape, see Runtime And Deployment.
For every agent.md field, see the
Declarative Reference. For runtime environment
variables, see Runtime Configuration.