Skip to main content

Assembly Line Developer Documentation

Assembly Line is a vendor-neutral, filesystem-first framework for durable AI agents. An agent should be understandable as a folder; Assembly Line validates that folder, compiles it into a manifest and runtime artifact, and runs it through the adapters declared by the agent.

Everything in Assembly Line is built to snap together. An agent is assembled from small, self-contained pieces — a tool is one file, a channel is one file, a connection is one declaration — and each piece plugs into the same well-defined contracts, so you compose an agent the way you compose with building blocks. The same contracts power the plugin system: official @assemblyline-agents/* packages ship channels, connections, sandboxes, and skills that drop into any agent with one import, and anything you build against those contracts is itself a reusable plugin you can share across agents, teams, or the ecosystem.

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, scheduler, and observability adapters
plugins            add optional channels, connections, sandboxes, state, blob, deploy, skills, and companions

The simple path is deliberately small: instructions.md and agent.ts are the only required files. The advanced path stays explicit: add one file in the relevant folder when you need a tool, skill, channel, schedule, trigger handler, connection, sandbox, subagent, or instrumentation hook.

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 - model, identity, reasoning, and capability policy.
  • 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/ - Pi-backed child agents with scoped models, tools, workspaces, 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 - module ownership, security-sensitive flows, and line-count exceptions.
  • 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.