Assembly Line

Assembly Line is a vendor-neutral, filesystem-first framework for durable AI agents. An agent is an ordinary folder. The compiler validates that folder and builds a deterministic manifest and runtime artifact. The runtime then executes the agent through the adapters selected in gateway.ts.

Each file has one role. A tool is one file, a channel is one file, and a connection is one declaration. Official @assemblyline-agents/* packages use the same public contracts, so agents can add channels, connections, sandboxes, skills, and infrastructure providers without changing the framework core.

Mental Model

agent/ folder      what the agent is
compiler           validates the folder and emits a manifest plus .assembly-line artifact
runtime            executes runs durably and records events, tools, deliveries, and recovery state
gateway.ts         chooses deploy, runtime, state, blob, sandbox, and scheduler adapters
plugins            add optional channels, connections, sandboxes, state, blob, deploy, skills, and companions

A minimal agent needs only instructions.md and agent.ts. Add a file in the matching folder when the agent needs a tool, skill, channel, automation, connection, sandbox, subagent, or instrumentation setup.

Start Here

1. Getting Started - clone the repo, build it, run the example agent, create a new agent, and inspect the compiled artifact.
2. Agent Build Stack - navigate the agent folder by the file or directory you are editing.
3. Building Agents - the linear tutorial through the whole authoring path.
4. Runtime And Deployment - understand the compiler output, durable runtime lifecycle, HTTP endpoints, preflight checks, and deploy targets.
5. Troubleshooting - diagnose install, CLI, model-key, auth, preflight, ingress, and durability-worker failures.

Agent Build Stack

Start at the Agent Build Stack overview, then jump to the file you are editing:

• instructions.md - always-on trusted instructions.
• agent.ts - static identity/policy and synchronous runtime capability hooks.
• context.ts - default or custom context bundle policy.
• gateway.ts - deploy, runtime, state, blob, sandbox, and scheduler adapters.
• tools/ - typed actions the model can call.
• skills/ - on-demand procedures and self-improvement surface.
• channels/ - external entrypoints and provider reply delivery.
• automations/ - schedule- and event-triggered durable work with trusted lifecycle hooks.
• connections/ - external capability and credential contracts.
• sandbox/ - isolated filesystem and shell backend.
• subagents/ - hook-composed child agents with scoped models, tools, workspaces, state, and connections.
• evals/ - golden cases, custom evaluators, repeatable experiments, and baseline gates.
• instrumentation.ts - telemetry sinks and capture policy.

Guides

• Building Agents - the agent folder shape, tools, skills, channels, automations, lifecycle handlers, connections, sandboxes, subagents, and instrumentation in one continuous tutorial.
• Customizing Agents - context policy, gateway adapters, capability metadata, approvals, self-improvement, dynamic automations and connections, and observability.
• Runtime And Deployment - CLI commands, build artifacts, runtime lifecycle, HTTP endpoints, preflight, deploy targets, and production checks.
• Troubleshooting - common failures with the exact error text and the fix.
• Remote Computer Use - pair a Mac with a hosted agent through Computer Host and an end-to-end encrypted relay.

Plugins And Providers

• Plugins - install optional Assembly Line integrations and understand how plugin contributions map to providers, adapters, connections, skills, and companions.
• Adapters - consume substrate adapters: the role matrix, gateway config, and per-adapter env reference.
• Photon iMessage Channel - Photon/Spectrum channel setup, delivery modes, typing lifecycle, rich tools, and file handling.
• Authoring Plugins - implement new channels, connections, sandboxes, blob stores, deploy targets, and state stores as plugin provider contributions.

Reference

• Framework Guide - current framework contracts, manifest shape, runtime guarantees, package boundaries, and adapter boundaries.
• Configuration Reference - every define* config shape, per-file compiler contract, and ASSEMBLY_LINE_* environment variable.
• Architecture - system shape, trust boundaries, and package ownership.
• Contributing - work on the Assembly Line framework itself and keep developer docs current.
• Migrating from OpenEve - what the rename changes for existing projects, what still works, and the alias removal policy.