Quickstart

This walkthrough takes you from an empty terminal to a running, traced multi-agent workflow. You need zero external keys to start — the scaffolded workflow runs on a built-in mock model — and a free developer key unlocks hosted traces. There is no credit card required at any point.

1. Sign up and create a free developer key#

1. Go to https://getassemble.dev/sign-up and create an account.
2. Go to the API keys page and create a developer key. Developer keys look like asm_dev_... and are shown once, so copy it right away.

Hosted traces are included with your workspace. You bring your own model keys later, when you switch off the mock model.

2. Install the CLI and log in#

npm install -g @assemble-dev/cli
asm login --key asm_dev_your_key_here

asm login validates the key against the platform and saves it to ~/.assemble/config.json. Confirm the active workspace at any time:

asm whoami

You can also provide the key without saving it by exporting ASSEMBLE_API_KEY in your shell.

3. Scaffold a project#

asm init my-team
cd my-team
pnpm install

asm init writes a starter project, including src/workflow.ts, an .env.example, and a package.json. The sample workflow runs on mockModel, so it needs no API keys.

4. Run the workflow#

asm run src/workflow.ts --input '{"topic":"launch day"}'

The starter workflow's input schema requires a topic string, so pass it with --input. asm run executes the workflow, streams a colorized trace to your terminal, writes a JSONL trace under .assemble/runs/, and — because you are logged in — uploads the run to your workspace. The final summary prints the run id, status, and a hosted trace URL:

Workflow completed.

Run ID: run_...
Status: completed
Latency: 12ms
Trace: https://getassemble.dev/app/runs/run_...

Open the Trace: URL to see the run-detail timeline, live streaming, and every agent step, tool call, policy decision, and routing decision.

If you are not logged in, asm run still works fully offline and points you at the local JSONL file plus a hint to get a free developer key.

Load input from a file instead of the command line:

asm run src/workflow.ts --input-file input.json

5. Iterate with asm dev#

While editing, asm dev watches the file and re-runs on every save:

asm dev src/workflow.ts

6. Evaluate a suite#

An eval suite pins expected behavior so regressions surface immediately:

asm eval src/workflow.eval.ts

asm eval runs each case, prints a metric table, saves results under .assemble/evals/, and uploads the eval run to your workspace so you can review it in the dashboard. See Evals for how to write a suite.

Bring your own OpenAI, Anthropic, or Gemini key#

When you are ready to use a real model, swap mockModel for a provider adapter and pass your own key. Assemble reads the key from the provider's usual environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY) or from the apiKey option — and calls the provider directly. Your model keys are never sent to Assemble.

import { openai, anthropic, gemini } from "@assemble-dev/providers";

const drafter = openai({ model: "gpt-4o-mini" });
const reviewer = anthropic({ model: "claude-3-5-sonnet-latest" });
const summarizer = gemini({ model: "gemini-1.5-flash" });

Copy .env.example to .env and add whichever provider key you use:

cp .env.example .env

OPENAI_API_KEY=sk-...

See Model providers for every adapter option.

Where to go next#

That is the whole loop: define a team, asm run it, read the hosted trace, and asm eval it. Continue with Agents to learn every primitive, or jump into the runnable example projects.