Complete Guide to Building a Multi-Agent Workflow System on Nagent

Who this is for

You're a builder — engineer, RevOps lead, AI/ML practitioner, or solutions architect — who wants to ship a multi-agent system on Nagent. You already know what an LLM is, you've wired up a tool call or two, and you want production-grade orchestration with memory, governance, feedback, and observability without rebuilding those primitives from scratch.

If you want the broader architectural narrative first, read the Technology Overview — it explains the substrate (Smriti · Karmic · Governance · Audit), the runtime, and the application layer this guide builds on. This page is the how-to.

What you'll build

By the end of this guide you'll have a working multi-agent system that:

Takes a one-sentence prompt from the operator and decomposes it into a multi-agent workflow
Routes work across specialist agents that hand off, debate, and escalate as needed
Operates with human-in-the-loop oversight via the autonomy ladder
- per-action overrides
Inherits persistent memory (Smriti), outcome feedback (Karmic), and immutable audit (AuditLog) — without any per-agent wiring
Surfaces in the Control Plane + Topology in real time so operators can pause, demote, or replay any agent

The same shape applies whether your workflow is "outbound demand", "claims triage", "research dossier", "compliance review", or "content production pipeline".

The 8-step build path

   1. Pick the workflow         →  one operator prompt, one outcome
   2. Synthesise with Helix     →  agent graph + tool + model picks
   3. Inspect the AgentSpec     →  validator + auto-fixer landed it
   4. Wire data + tools         →  Ingredient Layer: RAG, MCP, native
   5. Configure governance      →  autonomy ladder + per-action gates
   6. Sandbox + evaluate        →  gold-set + Karmic baseline before promote
   7. Deploy + observe          →  Topology + Decisions Ledger live
   8. Iterate with Karmic       →  the loop closes without you

Each step takes minutes, not weeks. The slowest step is usually step 1 (picking the right workflow) and step 5 (defining the governance bounds your stakeholders are comfortable with).

Step 1 — Pick the workflow

The most common mistake is picking a workflow that is either too narrow (a single LLM call dressed up as an "agent") or too broad (an entire business function that no single workflow can capture).

Good candidate workflows have all three properties:

Repetitive enough to be worth automating — the operator spends ≥5 hours/week on this work today
Structured enough to be governable — there is a known shape of inputs and outputs, even if some steps are creative
Outcome-linked — there's a downstream signal (reply, meeting, deal closed, ticket resolved, claim approved) that closes the loop

Examples that work well as a first multi-agent workflow:

Outbound prospecting + qualification + personalised send + reply classification + follow-up cadence
Inbound lead nurture across email + chat + meeting + deal-room
Account research dossier (signals → research → AccountBrief → prep card)
Content production (brief → variant generation → brand-lock QA → scheduled publish)
Tier-1 customer support (intent classification → KB retrieval → draft response → escalate-on-uncertainty)
Compliance review prep (evidence collection → policy-check drafting → reviewer queue)

Example we'll use throughout this guide: outbound prospecting + personalised send + follow-up.

Step 2 — Synthesise with Helix

Helix is the chat-first builder. Open the Agent Studio (inside the Nagent control plane) and type a single-sentence brief:

"Build a multi-agent workflow that picks D2C fintech prospects from my saved ICP, drafts a personalised first-touch email per prospect grounded in their company's recent news, sends only after brand-voice QA passes, and runs a 5-day follow-up cadence."

Helix parses the brief and proposes an agent graph:

   [NORA]                ┌→ [Email-Composer]
   prospect picker  ────→│
   ICP-aware             ├→ [Brand-Lock]
                         │  voice + tone QA
                         │
                         └→ [Sender]
                            Resend dispatch +
                            reply listener
                                 │
                                 ▼
                            [Reply-Classifier]
                            intent → cadence
                            decision
                                 │
                                 ▼
                            [Follow-Up-Cadencer]
                            5-day rhythm

For each step Helix also picks:

The model from the model registry — narrative Sonnet 4.6 for the composer, fast Haiku 4.5 for the reply classifier, GPT-4o vision if any attached assets need OCR
The tools from the action registry — ContactOut for prospect pull, Exa for company news, Resend for email send, Brand-Lock for validation
The triggers — manual + cron daily firing
The skill modules — "ICP-aware prospect picker", "Brand-voice validator", "Forward-only cadence"
The governance defaults — autonomy level, per-action overrides, budget caps

You review the proposed graph in one screen and accept (or edit inline).

Step 3 — Inspect the AgentSpec

Every agent in your new workflow conforms to the same AgentSpec contract:

{
  identity:    { key, name, description },
  behaviour:   { systemPrompt, model, temperature },
  capabilities: { tools, skills, events },
  governance:  { autonomyLevel, riskLevel, actionOverrides, guardrails },
  triggers:    [{ kind: 'event' | 'cron' | 'manual', config }],
  budget:      { dailyDollarCap, perRunTokenCap },
}

Helix's output is run through the validator (which checks every field against the live registries — action keys, event names, autonomy enums, skill catalogue) and a deterministic auto-fixer that repairs the small number of known-bad values the LLM occasionally produces (cron field count, unknown event names, out-of-range autonomy). What lands in the database is always runnable.

You can drop into BuildCraft (the pro-code path) at any point and edit any spec by hand. Helix and BuildCraft share the same contract, so you can switch back and forth.

Step 4 — Wire data + tools

This is the Ingredient Layer of the platform — what your agents draw from to reason and act.

Models

The Model Registry exposes Sonnet, Haiku, GPT-4o, Sonnet vision, Whisper, and the video-avatar providers. Each is registered with metadata (context window, per-1M token pricing, best use-case). Multi-model routing means a single workflow can use different models per step — cost-sensitive workflows route easy steps to Haiku ($0.25/M input) and reserve Sonnet ($3/M input) for hard steps, with 60–80% measured cost reductions. The live registry is at /resources/models.

Tools / MCP / integrations

The Action Registry catalogues every tool an agent can call. The Composio bridge auto-registers 800+ third-party tools (Salesforce, HubSpot, Pipedrive, Gmail, Outlook, Slack, Discord, Teams, Snowflake, BigQuery, Airtable, Mailchimp, ActiveCampaign, …). Native integrations cover deeper-control surfaces (Anthropic, OpenAI, Cal.id, ContactOut, Exa, Resend, Cloudinary). Custom tools authored in BuildCraft auto-register on deploy. The browsable catalogue is at /resources/tools-and-integrations.

Hard rule: agents physically cannot call tools that aren't in the registry — there is no free-form HTTP escape hatch. This is what makes governance enforceable at runtime, not just at audit time.

Data + Knowledge (Enterprise RAG)

Three ingestion paths feed the agent-readable knowledge layer:

Document ingestion — PDFs, slides, contracts, transcripts
Structured connectors — databases, data warehouses, CRMs
Live API mirrors — selected systems mirrored on schedule/event

Retrieval is hybrid (vector + BM25 + structured filters + re-ranker) with knowledge-graph relations for multi-hop reasoning. Every retrieval is logged to the Decisions Ledger with sources cited. Per-document RBAC is enforced at retrieval time.

Skills

Skills are reusable markdown prompt modules — "ICP-aware prospect picker", "Brand-voice validator", etc. Attach many-to-many to any agent. Author from prose, PDF, or hand. Eval suites attach to skills so a new skill version can be shipped + tested + rolled back like code.

Step 5 — Configure governance

This is the step that determines whether your workflow can be trusted to operate autonomously.

Autonomy ladder

Each agent has a level from L0 (always ask) to L4 (full autonomy, audit-trail review only). Start low. Promote agents up the ladder as they earn trust through Karmic feedback.

For the outbound example: NORA (picks prospects) starts at L2 — operator reviews the batch before drafts begin. Email-Composer + Brand-Lock + Sender can start at L3 once the first 100 sends look clean. Reply-Classifier + Follow-Up-Cadencer start at L4 from day one — the autonomy ladder is per-agent, not per-workflow.

Per-action overrides

Even an L4 agent can be flagged on specific actions: "outbound to any C-level contact requires explicit approval", "any spend above $1k requires approval", "any send to a domain not in the allow-list is blocked". These are governance primitives, not metadata flags.

Budget caps

Per-day dollar cap + per-run token cap, configurable per agent. Auto-pause on exhaustion. Per-debate spend cap (default $20/day) for moderated multi-agent debates. Per-research cap ($0.30 typical) for deep-research jobs.

Kill switch

One-click pause of an agent, agent class, or full fleet, mid-flight. Pending actions queue, in-flight actions complete cleanly. Human override response time is the runtime's next scheduling tick — sub-second for event-driven agents.

Step 6 — Sandbox + evaluate

Before you promote anything to production, run sandbox evals.

Sandbox runs

In Agent Studio (or the Workbench for single-agent edits) you can fire each agent in your workflow against curated inputs in isolation. The workbench surfaces the action chain, the model picks, the tool calls, the token + dollar cost, and the resolution status for each test input. No production state is touched.

Gold-set evals

Curate 10–30 example inputs with the expected outcomes. The runtime scores live runs against the gold-set continuously. Quality drift triggers auto-demote on the autonomy ladder until the agent earns its level back.

Skill-level evals

Eval suites attach to skills as well as agents. Ship a new skill version, run the eval, roll back in one click if it regresses. Full eval history per agent + per skill is persisted in AgentActionLog and visualised in the Workbench's Observability tab.

Step 7 — Deploy + observe

Promote the workflow with a click. Three operator surfaces light up:

Control Plane

The live SSE-driven cockpit — see every action across the fleet in real time, decisions ledger replay for any past run, multi-agent debate observation, kill switch ready at hand. Built on a materialised view so it renders instantly even at fleet scale.

Topology

The living-systems view — your new workflow shows up as one cluster, with NORA at the head and the downstream agents visualised by handoff order. Cognitive gravity highlights which agent is doing the heavy lift. Operators drill from system → cluster → agent.

Observability

Three append-only logs back the substrate. AuditLog captures every write op, 365-day immutable retention. AgentActionLog records every agent run with resolution + error context, 90-day retention. Decisions Ledger captures every AI-suggested action with its outcome, replayable.

Step 8 — Iterate with Karmic

Karmic is the outcome-attribution loop that closes without your involvement. Once your workflow is live:

Drafts that get replies → the prompts that produced them get promoted in the skill library
Agents whose decisions lead to closed deals get higher trust scores → eligible for autonomy promotion
Prompts that produce wins get suggested for re-use in adjacent workflows
Agents that drift (quality drops below threshold against gold-set
- Karmic) auto-demote on the autonomy ladder until they earn the level back

Operators see trust scores per agent in the Control Plane and can override Karmic's decisions if they disagree. The default behaviour is: the loop closes through the agent layer, the operator gets visibility, the autonomy ladder is auto-adjusted.

Things to be careful about

Don't skip Step 5 (governance). Most failed agentic deployments fail not because the agent was wrong, but because the governance was undefined and one mistake created an unrecoverable outcome. Define autonomy bounds + per-action overrides + budget caps before you promote anything past L1.
Use multi-model routing from day one. Even simple workflows benefit from routing classification steps to Haiku. The cost reduction shows up immediately and gives you budget headroom for Sonnet on the hard steps.
Treat skills as code. Version them, eval them, roll them back with the same rigour you apply to TypeScript or Python. The skill IS the prompt logic — drift here is silent but consequential.
Watch the Decisions Ledger weekly for the first month. It catches the patterns Karmic hasn't learned yet — opportunities to add new per-action overrides, tighten a budget cap, or hand-promote a skill that obviously works.

What to read next

Agent Control Plane — operator UX reference (coming soon)
Agent Workbench — per-agent tuning surface (coming soon)
Topology — living-systems visualisation (coming soon)
Smriti — memory fabric architecture (coming soon)
Karmic — outcome feedback loop reference (coming soon)
Running individual agents — when you don't need a multi-agent workflow (coming soon)
Best practices — production-tested patterns (coming soon)

While those are being published, the Technology Overview covers every layer this guide builds on — substrate, agent studio, runtime, application layer, ops layer, content + brand, observability, ingredient layer, education + adoption.

Complete guide to building a multi-agent workflow system on Nagent