Core concepts

Workflows & crews

Four objects make up the LoopLlama data model. Understanding how they relate is the fastest way to design effective agent pipelines.

The model at a glance#

A workflow is a reusable configuration that owns a crew.
A crew is an ordered list of agents.
A run is one execution of a workflow against a single input.
A run is made of steps — one per agent in the crew.

Workflows#

A workflow is the unit you create once and run many times. It stores a name, an optional description, a default model, and the crew that processes each run. Workflows have a status of active or paused; triggering a run against a paused workflow returns 409 Conflict.

Crews & agents#

A crew is an array of 1–10 agents. Each agent is a single role with its own system prompt, and optionally its own model that overrides the workflow default. An agent has these fields:

rolestringrequired

A short label for the agent, 1–60 characters (e.g. planner, writer, reviewer). Used to label the step and to frame prior output for the next agent.

systemPromptstringrequired

The system prompt that defines the agent's behavior, 1–8000 characters.

modelstringoptional

Optional per-agent model override, e.g. claude-opus-4-7. Falls back to the workflow's model when omitted.

The default crew

If you create a workflow without specifying a crew, LoopLlama provisions a two-agent default: a planner that breaks the request into ordered steps, followed by a writer that produces the final output.

Defining a custom crew

Pass a crew array when creating a workflow. Agents run top-to-bottom; design the prompts so each role builds on the last.

json

{
  "name": "Spec reviewer",
  "model": "claude-sonnet-4-6",
  "crew": [
    {
      "role": "researcher",
      "systemPrompt": "Extract the key claims and open questions from the input. Be exhaustive and concise."
    },
    {
      "role": "writer",
      "systemPrompt": "Using the research, draft a clear one-page summary with a 'Risks' section."
    },
    {
      "role": "reviewer",
      "model": "claude-opus-4-7",
      "systemPrompt": "Critique the draft for accuracy and gaps, then output a corrected final version."
    }
  ]
}

Runs & steps#

Triggering a run executes the crew sequentially. The first agent receives the run's input; every subsequent agent receives the original input plus a transcript of the prior agents' output. The final agent's output becomes the run's output.

A run moves through these statuses:

queuedstatusoptional

Accepted and waiting to start. New runs are returned in this state.

runningstatusoptional

At least one step has started executing.

completedstatusoptional

Every agent finished; output holds the final result.

failedstatusoptional

A step errored. error describes which step and why; completed steps are still recorded.

Each step persists its own input, output, model, token counts, and timestamps — so you can inspect exactly what every agent saw and produced. See the Runs reference for the full object shape.

Execution is asynchronous

Runs return immediately as queued. Poll GET /v1/runs/{id} until the status is completed or failed, or use an SDK helper that polls for you.

Usage & metering#

Every completed or failed run records a usage event capturing the number of steps and the input/output tokens consumed. These roll up into your monthly workflow steps — the unit LoopLlama bills on. One step is one agent reasoning turn. See Rate limits & usage for plan limits and overage pricing.