Module Deep Dive

Agents, Workflows & Multi-Agent Teams

The three modules that do the actual work in Derbee Studio — what each one is, how it executes, and when to reach for which.

Overview

Read this first — it explains why there are three modules instead of one.

Every other module in Derbee Studio is something an agent uses: a knowledge base it reads, a template it follows, a guardrail it obeys, a model it calls. These three modules are different — they are the things that actually run. They form a stack, and each layer exists because the layer below it stops being enough at a certain level of complexity.

An Agent is one reasoning unit. Give it a model, a knowledge source, some prompt templates and a guardrail, and it can take a question, work out what is being asked, gather what it needs, and answer. For a very large class of problems — support Q&A, document lookup, a bot that calls two or three tools — a single agent is the entire solution, and adding anything more would only be overhead.

A Workflow is the plan an agent runs inside one turn. Agents reason well but improvise the order of their work. When the order matters — extract these fields, then look them up, then score the result, then shape it to this exact schema — you stop describing the outcome and start describing the steps. A workflow is that list of steps, with real dependencies, parallel branches, retries and error policies.

A Multi-Agent Team is a graph of agents plus control-flow blocks. One agent with one long instruction degrades as you pile on responsibilities: the prompt grows, the persona blurs, and the model starts dropping requirements. A team splits the job across specialists — each with its own model, instruction and tools — and adds the machinery to route between them: conditions, loops, variables, code, and human approval gates.

The relationship in one line: a workflow runs inside an agent's turn, and an agent runs as a node inside a team. A team node can even point at an agent you already built and tested, so nothing is ever rewritten to be promoted up a layer.

How they fit together

What lives inside an agent, and how an agent becomes one node in a team graph.

An agent bundles its own resources; a team wires whole agents together and adds control flow between them

Choosing between them

Start at the top of this table and stop at the first row that matches what you need.

Use	When	Signals you have outgrown it
Agent alone	One subject area, one persona, an answer that can be reasoned out in a single pass	The order of operations keeps coming out wrong, or the output schema drifts
Agent + Workflow	The work is a repeatable pipeline — parse, look up, score, reshape, write	The instruction needs several conflicting personas, or a step needs a human to approve it
Team	Distinct roles, branching, iteration over a collection, or an approval gate	Nothing above — this is the top of the stack

Modules

Agents

An Agent is a configured, addressable AI entity. It owns a model, a set of prompt templates, one knowledge source, optional tool bindings, a guardrail and a set of policies. Once saved it can be called from Chat, from an API key, from a channel, from a schedule, or as a node inside a team — and it behaves identically through every one of those doors.

What makes an agent more than a prompt is that the platform owns the plumbing. You never write retrieval code, tool-calling loops, token accounting or safety checks. You declare what the agent knows and how it should behave; the runtime handles classification, retrieval, tool execution, guardrail enforcement, streaming and logging on every single turn.

Anatomy of an agent

modelId

The chat model that does the reasoning. Swappable at any time without touching anything else, so the same agent can be cost-tuned or upgraded in place.

templateIds

Prompt blueprints the agent can adopt. At run time a classifier picks the best match by semantic similarity, so one agent can hold several distinct behaviours without a branching prompt. (See the dedicated Templates Manual ↗).

knowledgeSourceType

Where context comes from — rag (vector search), mcp (tool server), api_registry (REST endpoints), channel (WhatsApp / Outlook actions), or none for pure reasoning.

workflowIds

Standalone workflows the agent may run. When a workflow declares a templateId, it only fires for turns the classifier routed to that template — one agent, several pipelines, no manual switching.

guardrailId

Safety policy applied at both boundaries: on the incoming message before the model sees it, and on the generated answer before the user sees it.

groundingPolicy

strict — closed-loop grounding, answers come only from attached sources and web tools are blocked. open — augmented research, the agent may reach the open web. This is resolved once per run and every downstream node reads the same value.

rateLimit

Daily invocation ceiling for this agent. 0 or unset means unlimited. Separate from the tenant-wide per-minute and per-day limits.

logging.levels

Multi-select trace levels — trace, debug, info, warn, error, fatal. Each run writes its own lifecycle log file, purged on the analytics retention clock.

The runtime pipeline

Every turn runs as a state machine, not a single prompt. Each stage below is a real node with its own inputs, outputs and routing rules — which is why an agent run is traceable step by step rather than a black box.

classifier

Reads the message, resolves the grounding policy, matches the closest template, and decides what the turn will need: retrieval, tools, web, API, or nothing. Can short-circuit straight to the output stage for a cached or errored turn.

guardrail_input

Runs the input half of the guardrail — injection detection, blocked topics, PII, language, length. A violation ends the turn here with the policy's fallback message. PII is masked at this chokepoint, before any model call.

research_node

Gathers context: vector search over the knowledge base, MCP tool discovery, registered API calls, web loading when the policy allows it, and text extracted from attachments.

action_planner

Taken instead of research when a workflow is attached. Resolves the plan — the authored step list, or in dynamic mode a plan the model writes from your free-text instructions.

action_executor

Runs the plan one step at a time, looping back into itself until every step is done, then hands the consolidated result forward. Respects each step's dependencies, parallel flag, retries and error policy.

execute_task

The generation stage. Applies the matched template's persona, task, constraints and output format over whatever context arrived, and produces either an answer or a tool call. Bound tools are first scored for keyword relevance against the query — tools already called this conversation are boosted, channel tools always pass, and if nothing scores the full set is sent — so a large tool catalogue does not flood every prompt. Workflow output always passes through here, so the template shapes the final response rather than raw step JSON being returned.

tools

Executes requested MCP tool calls and returns to generation with the results. The loop is capped per run so a misbehaving tool can never spin forever.

channel_node

A dedicated path for channel actions — sending a WhatsApp message or template, sending mail, creating a calendar event — separated from ordinary tools so outbound side effects are isolated and auditable.

state_compactor

Clears the turn's heavy retrieval context — RAG, web, attachment, MCP and API results — before the output guardrail runs, so it is not carried into the next turn.

guardrail_output

Runs the output half — topic adherence, PII redaction, toxicity, format validation, disclaimers, length. Masked PII is restored here, so the model never saw the real value and the user never sees a placeholder.

Also handled for you

Per-tenant concurrency limiting with FIFO queueing
Session-scoped MCP connections, closed at turn end
Single-flighted connects shared across parallel steps
Pre-flight token estimation before each model call
A faster utility model for classification and planning
Checkpointed graph state with TTL cleanup
Streamed output with mid-stream stop
Per-run cost, token and latency capture

Workflows

A Workflow is an ordered plan of discrete actions that runs inside a single agent turn. Where an agent decides what to say, a workflow decides what happens before it says it — and in what order, with what dependencies, and what to do when a step fails.

Workflows are standalone records, not fields on an agent. That means one pipeline can be reused by several agents, versioned independently, and bound to a specific template so it only runs for the kind of request it was built for. A workflow also carries its own model and resource bindings, so it can run on its own without an agent wrapped around it.

Three authoring modes

Linear

A form. Steps run top to bottom, each one seeing everything before it. The right choice when the pipeline is genuinely a straight line — most pipelines are.

DAG

A drag-and-drop canvas. Steps declare which other steps they depend on, so independent branches run at the same time and only converge where you say they do. Node positions, edges and viewport are persisted, so the diagram stays the source of truth.

Dynamic

Free text. You write instructions; a planner model turns them into steps at run time. Pair it with a saved Planner Step list to keep the shape of the plan fixed while the details adapt to the input.

The step contract

Every step, in every mode, is the same shape. These fields are what make a workflow a pipeline rather than a list.

stepId

A stable name. Later steps reference results by this id, so reordering the list never breaks a reference.

type

Which action to run. Resolved through a registry, so the set of action types is extensible rather than fixed in the schema.

config

The per-type settings. Each action type publishes its own schema — the editor renders the right fields and validates them before you can save.

dependsOn

Step ids that must finish first. This is what turns the list into a graph and lets the executor work out what can run at the same time.

runMode

linear runs in order; parallel runs alongside its siblings once dependencies are satisfied.

onError

stop aborts the run, skip continues without this step's output, retry attempts again up to maxRetries.

condition

An expression over earlier results, e.g. search_roles.resultCount > 0. The step is skipped when it evaluates false.

How data moves between steps

Each completed step publishes its output under its stepId. Any later step reads earlier outputs by naming them in inputs or fieldsFrom — there is no implicit global state to reason about, which is what keeps a large pipeline debuggable.

Two special values let a step inherit from the matched template instead of repeating it: from_template_task supplies a scoring rubric, and from_template_outputFormat supplies an output schema. Change the template and every step that references it follows.

Why workflow output still passes through the template: after the last step completes, the consolidated result is handed back to the generation stage rather than returned directly. Without that hop the agent's persona, task and output format would never be applied and callers would receive raw step JSON.

Ten built-in action types

extract_keys — pull fields by dot path
embed_fields — vectorise field values
rag_search — vector search a KB or collection
llm_generate — generate from template or instruction
image_generate — text-to-image, local Ollama
score — grade against a rubric
transform_json — reshape to a schema
conditional — branch on an expression
mcp — plan and run MCP tools
api_registry — call a REST endpoint

Full configuration for each type is in the reference tables at the end of this page.

Multi-Agent Teams

A Team is a graph you draw on a canvas. Some nodes are agents; the rest are control-flow and data blocks that decide which agent runs next and what it receives. The whole graph executes as a state machine, so the wiring owns control flow and a shared run context owns the data — the two never get tangled.

An agent node either references an agent you already built, or carries its own inline model, instruction and tool bindings. Either way it executes through the same agent runtime described above, which means a team never re-implements what an agent already does: guardrails, retrieval, tool loops and tracing all behave identically inside a team node.

Orchestration strategies

Supervisor

One agent routes. After each worker finishes, the supervisor sees the result and picks the next worker — or declares the job done. Best when the path depends on what earlier agents find.

Sequential

A fixed chain. Each node hands off to the next along the edges you drew. Best when the order is known up front and never varies.

Group

Round-robin. Every agent wired to the supervisor takes a turn, in order, until all of them have contributed. Best for breadth — several independent takes on the same input.

How a supervisor decides

The supervisor chooses from the agents wired to it, using only their name and description — so those two fields do real work. Before it chooses, the roster passes through a deterministic capability filter: an agent whose name, role or instruction marks it as a category specialist — a web scraper, an email composer — is dropped from the roster when the query carries none of that category's signals. An agent matching no category is always kept, so the filter only ever removes clearly irrelevant specialists. Three decision styles are then available per node:

react

Asks the model after every step: given what has happened, who should run next? Most adaptive, most model calls.

function-calling

The roster is exposed as callable tools and the model picks by calling one. Structured and less prone to free-text drift.

plan-execute

Plans the whole sequence once, up front, with a focused sub-task per agent — then executes it without consulting the supervisor again. Cheapest and most predictable.

Block types

Seventeen block kinds, in four families. Agent blocks think; data blocks move and reshape values; control blocks decide and repeat; structural blocks bound the graph.

supervisor worker

Agent blocks. Instruction comes from one of three modes — custom free text, template a saved template, or planner a saved planner-step list. Each can bind its own knowledge base, MCP server and API endpoints.

llm

A plain prompt with no agent scaffolding — no retrieval, no tools. Useful for a quick rewrite or summarisation between agents.

extract

Pull values out of a variable. JSON mode takes dot paths. Text mode offers four operations: regex with flags, between two markers, lines by range, and split on a delimiter.

transform

Reshape data three ways: llm describes the target shape in words, mapping applies a deterministic JSON field map, passthrough merges inputs untouched.

aggregator

Merge several named variables into one object under a new name. The usual way to gather parallel branches before a final write-up.

variable

Set a named value with one of three operations — overwrite, append, increment. Increment plus a condition is how you build a counter-bounded retry.

template

Render a text template against current variables. No model call — deterministic string building for prompts, messages or report bodies.

code

Run JavaScript or Python, inline or from a relative file. Inline JavaScript is parsed at save time so syntax errors surface in the editor. File paths are forced relative and may not traverse upward.

tool

Call one tool directly, without an agent deciding to: web_search, mcp, rag or api. Everything but web search needs an explicit target.

condition

A rule list joined by and or or, with true and false output handles. Fifteen operators: equality and ordering comparisons, contains, starts_with, ends_with, regex, and unary emptiness and truthiness checks.

loop

A container whose child blocks repeat. each iterates a collection and binds the current item to a name; count repeats a fixed number of times; while repeats until a condition stops being true. Iterations are capped at 1000, and a while-loop without a condition is rejected at save time.

hitl

A human approval gate. Fires before or after the step it guards, shows a prompt, and waits. Optional timeout with auto-approve fallback so an unattended run is not blocked forever.

start end

Graph boundaries. The end block's output template is what the caller receives — which matters whenever the last real block produced data rather than prose.

empty note

A placeholder for work in progress, and a canvas annotation. Notes carry no execution semantics and are skipped entirely.

Graph validation

The canvas checks the whole graph before you can run it, and reports errors and warnings against the specific node. The checks that catch the most real mistakes:

Cycles — use a loop block instead
Supervisors may only dispatch to agent nodes
Workers not wired to the supervisor can never be picked
Workers with no role or instruction to choose on
Nodes with no model and no team fallback
Unreachable nodes in a sequential chain
Cycles inside a loop body
Invalid regex, dot paths or JSON field maps
Missing end node after a data-producing block
Max steps below 1, or loop iterations above the cap

The missing-end-node warning is worth understanding. When a data block — transform, extract, code, aggregator, variable — is the last thing in a chain, its result lives in run variables and never becomes the agent's answer, so the caller silently receives the last agent output instead. Wiring an end block after it, with an output template, is what makes the processed data the response.

Team-level settings

sharedContext — one scratchpad or isolated memory
maxSteps — hard ceiling on supervisor hops
stopCondition — when the supervisor should finish
modelId — fallback model for unset nodes
guardrailId — perimeter input and output gate
rateLimit — daily invocation ceiling
Per-tenant team concurrency limiter
logLevels — trace verbosity, empty means off
isActive — deactivate without deleting

How They Work — Flow Examples

Five diagrams tracing real execution paths. Each box is a stage the runtime actually has; arrows show where control goes next, and dashed arrows are loops back.

Entry / exit Retrieval / data Model / decision Guardrail / side effect Result

Example 1 — The agent request lifecycle Agents

One turn, end to end. The branch after the input guardrail is the key decision: a workflow-backed turn takes the action engine, a research-backed turn gathers context first, and a simple turn goes straight to generation.

Classify → screen → research or run the plan → generate → tools or channel → compact → screen → respond

Example 2 — The three workflow authoring modes Workflows

The same pipeline expressed three ways. Linear is a list, DAG is a dependency graph, and dynamic hands the shape of the plan to a planner model at run time.

Pick linear for a straight line, DAG when independent work can overlap, dynamic when the input decides the plan

Example 3 — A DAG workflow, step by step Workflows

A document-scoring pipeline. Two independent lookups run at the same time, both feed one reshaping step, and every step reads earlier output by step id rather than from hidden global state.

Each step publishes under its id; later steps name the ids they read, so the dependency graph is explicit

Example 4 — A supervisor team in motion Teams

The supervisor dispatches one agent at a time, reads what comes back, and decides again — bounded by max steps. When its stop condition is met it exits to the finish path instead of dispatching.

Dispatch → run one agent → return → decide again, until the stop condition or the step ceiling ends the loop

Example 5 — Control flow inside a team Teams

A sequential team using the non-agent blocks: a condition splits the path, a loop repeats work over a collection, and a human approval gate holds the run before the end block renders the output.

Branch on a rule → repeat over a collection → gate on a human → render the end block's output

Reference Tables

Every workflow action type and every team block, with the settings that matter most.

Workflow action types

Type	What it does	Key settings
extract_keys	Pull specific values out of input JSON using dot-notation paths	sourceField, keys
embed_fields	Generate vector embeddings for extracted field values	fieldsFrom, keys
rag_search	Vector search a knowledge base, or a custom collection with its own index	knowledgeBaseId or collectionName, query, topK, filter
llm_generate	Generate content from a saved template or a custom instruction, over earlier step output	instructionMode, templateId / instruction, inputs, outputSchema
image_generate	Produce an image from a text prompt, optionally built by an upstream step. Runs against a locally pulled Ollama image model — macOS only	prompt, inputs, model, size
score	Grade data against a rubric and return a score	rubric (or from_template_task), inputs, scoreFormat
transform_json	Restructure data by model, by deterministic field map, or by merging inputs	mode, inputs, outputSchema, format
conditional	Evaluate an expression over earlier results and route accordingly	expression
mcp	Let a tool planner select and run the relevant MCP tools, then return their combined output	mcpRegistryId, query, instruction, inputs
api_registry	Call a saved endpoint or an inline URL, with query and body overrides from earlier steps	apiRegistryId or url, method, headers, params, body

Team block types

Block	Purpose	Key settings
Agent blocks
supervisor	Routes work to the agents wired to it and decides when the run is done	strategy, instructionMode, tools
worker	A specialist agent — inline, or a reference to a saved agent	sourceAgentId, role, modelId, tools
Data blocks
llm	A plain prompt with no retrieval or tools	prompt
extract	Pull values by JSON path, or by regex, delimiter, line range or split	source, extractMode, paths / pattern
transform	Reshape data by model, field map, or passthrough merge	transformMode, inputs, fieldMap / outputSchema
aggregator	Merge named variables into one object	inputs, output
variable	Set, append to, or increment a named value	varName, op, value
template	Render text against current variables, no model call	template
code	Run JavaScript or Python, inline or from a relative file	language, sourceMode, body / filePath
tool	Invoke one tool directly without an agent deciding to	toolKind, target
Control blocks
condition	Branch on a rule list with true and false handles	rules, logic
loop	Repeat child blocks over a collection, a count, or while a condition holds	loopMode, over, itemVar, maxIterations
hitl	Pause for human approval before or after a step	hitlTiming, hitlPrompt, hitlTimeout, hitlAutoApprove
Structural blocks
start	Graph entry point	—
end	Graph exit — its output template is what the caller receives	output template
empty	Placeholder for work in progress	—
note	Canvas annotation, never executed	—