The AgenticFlow Playbook

The complete playbook for getting the best out of AgenticFlow — how to pick the right primitive (workflow, agent, or workforce), build each layer step-by-step, and ship it to real users. Every step in

This is the long-form guide to building on AgenticFlow well — not just making something run, but making the choices that keep it cheap, reliable, and shippable. It's written for two readers at once:

• You, working in the visual builder at app.agenticflow.ai

• Your AI copilot (Ishi, Claude Code, Cursor, Codex…), driving the AgenticFlow CLI on your behalf

Every section ends with a 📋 copy-paste prompt. Paste it into your AI copilot and it will do the step for you. That's the AgenticFlow ecosystem working as designed: you brief your AI, your AI talks to our CLI, the CLI configures AgenticFlow, and AgenticFlow serves your customers.

If you only have 20 minutes, do the CLI Walkthrough first. This playbook is the full journey.

---

Part 1 — Think in three primitives

Everything you'll ever build on AgenticFlow is one of three things, or a composition of them:

Primitive	What it is	Reach for it when…	Cost profile
Workflow	A deterministic pipeline of nodes (LLM, scraping, API calls, image/video, data)	The task is a repeatable SOP: same inputs, same steps, every time	Lowest — a handful of credits, ~30s
Agent	A conversational AI with tools (web search, MCP apps, code execution, knowledge bases, workflows)	A human is in the conversation and the AI must decide which tool to use	Medium — pay for judgment per turn
Workforce	A team: a graph of agents, decision gates, and tools with shared state	The deliverable needs planning, routing, and quality control with no human in the loop	Highest — multiple agents per mission

The golden rule: build at the lowest rung that solves the problem. The most common (and most expensive) mistake is building an agent where a workflow would do, or a workforce where an agent would do.

The three primitives compose upward:

• A workflow plugs into an agent as a tool — the agent decides when to run your SOP.

• A workflow plugs into a workforce as a node — the team gets a cheap deterministic baseline.

• Agents plug into workforces as team members with distinct roles.

Build the deterministic part once. Let every higher layer reuse it.

📋 Copy-paste prompt — decide what to build:

I want to automate this on AgenticFlow: [DESCRIBE YOUR TASK IN 2-3 SENTENCES].

Apply the composition ladder: is this a workflow (repeatable SOP, no judgment),
an agent (conversation + tool decisions), or a workforce (autonomous mission with
quality control)? Recommend the LOWEST rung that genuinely solves it, tell me why,
and name the closest AgenticFlow blueprint to start from. Run `af bootstrap --json`
first if you have CLI access.

---

Part 2 — Set up once (5 minutes)

In the browser: sign up at app.agenticflow.ai — workspace and project auto-create. Grab an API key from Settings → API Keys if your AI copilot will drive the CLI.

For your AI copilot:

npm install -g @pixelml/agenticflow-cli
af login                 # paste your API key
af bootstrap --json      # THE command — run it first, every session

af bootstrap --json returns your entire workspace in one call: auth status, existing agents and workforces, the full blueprint catalog with deploy commands, available models, and a command cheat-sheet. An AI that starts with bootstrap never guesses.

Also point your copilot at the built-in playbooks — guides written specifically for AI operators:

af playbook first-touch          # orientation
af playbook mas-graph-building   # before hand-authoring any workforce graph

📋 Copy-paste prompt — onboard your AI copilot:

You have the AgenticFlow CLI available (`af`). Start by running `af bootstrap --json`
and `af playbook first-touch`. Summarize for me: what's already in my workspace,
which blueprints look relevant to [MY BUSINESS/USE CASE], and what you'd build first.
Don't create anything yet.

---

Part 3 — The Workflow layer: your productized SOP

A workflow is the thing you can sell fifty of per week at fixed marginal cost. Start here.

3.1 Deploy from a blueprint, then make it yours

Hundreds of blueprints ship with the platform. Deploy the closest one, inspect it, and customize — it's minutes, not hours:

af blueprints list --json                                  # browse (or filter in the UI templates gallery)
af blueprints get --id website-audit-lead-report --json    # inspect BEFORE deploying
af workflow init --blueprint website-audit-lead-report --json

Customizing is where the value is. Real example: the website-audit-lead-report blueprint scrapes a prospect's site, writes an audit, and emails it. For a lead-generation funnel you may want the report returned instead of auto-emailed (side effects should be opt-in) — so you remove the email nodes and reshape the inputs. Same skeleton, your funnel.

3.2 The conventions that save you an afternoon

• Update uses the create shape. af workflow get returns nodes wrapped in {"nodes": {"nodes": [...]}}; af workflow update --body expects the flat create shape plus output_mapping, project_id, and public_runnable. Run af workflow validate --body @file.json before every update — the local validator catches shape issues instantly.

• Templating reaches into everything. {{input_var}} works inside api_call URLs (https://api.example.com/quote/{{ticker}}), node prompts, and headers. response_type is "json" or "string" — use "string" for CSV, RSS, or XML sources.

• Test data sources from inside a run, not from your laptop. Public APIs treat platform infrastructure differently than your home IP — some want a browser User-Agent header (a normal node config field), a few won't serve datacenter ranges at all. One test run tells you immediately.

• Debug at the node level. af workflow run --wait --json returns the final output at .output.content and every node's inputs/outputs under .state.nodes_state[]. Final outputs summarize; node states explain.

3.3 Ship it

A finished workflow can run four ways: manually, on a schedule (cron), from a webhook (your website's form → workflow), or inside an agent or workforce (Parts 4 and 5). If a workforce will call it, set public_runnable: true now — you'll need it in Part 5.

📋 Copy-paste prompt — build your first workflow:

Build me an AgenticFlow workflow for this SOP: [DESCRIBE — e.g. "given a prospect's
website URL, produce a client-ready audit of their lead-capture gaps"].

Steps: (1) run `af blueprints list --json` and pick the closest blueprint;
(2) deploy it with `af workflow init`; (3) customize it to my SOP — remove any
side-effect nodes (email/posting) so it RETURNS the result instead; (4) run it once
with realistic test inputs using --wait, then read .state.nodes_state[] and confirm
every node's real output looks right — not just the final text; (5) give me the
workflow ID, the run output, and what it would cost per run in credits.

---

Part 4 — The Agent layer: the front door

Your team (or your clients) shouldn't need to know workflow IDs. They should ask a chat window in plain language — and the right SOP should fire.

4.1 Scaffold with tools included

af agent init --blueprint research-assistant --json
# → an agent with web_search, web_retrieval, api_call, string_to_json attached

4.2 Attach your workflow as a tool

This is the composition move that makes the agent more than a chatbot:

af agent update --agent-id <id> --patch --body '{
  "name": "Client Intelligence Assistant",
  "system_prompt": "...when the user wants a website audit, call the audit workflow tool...",
  "tools": [{
    "run_behavior": "auto_run",
    "workflow_id": "<your workflow id>",
    "description": "Generate a client-ready website audit. Inputs: website_url, audit_focus. Use whenever the user asks to audit or review a website.",
    "timeout": 300
  }]
}' --json

Two details carry all the weight:

• --patch is load-bearing. It fetch-merges-puts, so MCP clients, plugins, and the rest of your config survive a partial update.

• The tool description is the advertisement to the agent's brain. Write it like a function docstring: when to use it, what the inputs mean. A good description is the difference between the agent calling your SOP and the agent winging it.

4.3 Structured output — the contract

When an agent's answer must be machine-readable (routing decisions, form-filling, anything a workforce gate will read), enable JSON mode with this exact contract:

"response_format": {
  "enable": true,
  "prompt": "Return the plan as JSON.",
  "schema": {
    "name": "mission_plan",
    "strict": true,
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "properties": { "route": { "type": "string", "enum": ["workflow", "research"] } },
      "required": ["route"]
    }
  }
}

Both halves matter: the {name, strict, schema} wrapper, and "additionalProperties": false on every object level — that's how strict mode works, and AgenticFlow passes your schema through faithfully.

4.4 The model-split rule

Pin structured-output agents to a structured-output-native model (agenticflow/gpt-4o-mini class): native strict-schema parsing at 10–20× lower cost per decision. Spend frontier models on prose and judgment — research, writing, critique. Splitting model spend this way is the single biggest lever on your credit bill.

4.5 Ship it

An agent is deployable the moment it works: public chat URL, web widget embed on your site, or publish to Discord / Slack / Telegram / WhatsApp (100 credits per platform). For an agency, that's a client-facing deliverable with zero deployment work.

📋 Copy-paste prompt — build your front-door agent:

Create an AgenticFlow agent that acts as the front door for my team.

(1) Scaffold from the research-assistant blueprint (`af agent init`).
(2) Rename it to "[NAME]" and write a system prompt for this job: [DESCRIBE — e.g.
"help my team research prospects and prepare for client calls"].
(3) Attach my workflow <WORKFLOW_ID> as a tool with a docstring-quality description
of when to use it. Use `af agent update --patch` so nothing else gets clobbered.
(4) Test it: send a message that SHOULD trigger the workflow tool and confirm from
the response that the tool actually ran. Then send one that shouldn't, and confirm
it didn't.
(5) Give me the agent ID and the public chat link.

---

Part 5 — The Workforce layer: the team that runs without you

A workforce is for missions: "here's a goal; come back with a verified deliverable." Not a chat, not a fixed pipeline — planning, routing, judgment, and quality control with nobody watching.

5.1 The autonomous desk — one command

The highest-leverage workforce pattern ships as a blueprint (CLI ≥ 1.10.7):

af workforce init --blueprint autonomous-desk --json

One command creates four agents and wires the full graph:

trigger → Planner (structured JSON: route + research questions)
        → decision gate
            ├─ workflow route → runs your deployed WORKFLOW (cheap deterministic baseline)
            └─ research route → Researcher (live web tools)
        → shared state merges either branch into one draft
        → Critic (structured verdict: approved / score / itemized feedback)
        → QA gate
            ├─ approved → Editor → output
            └─ rejected → Researcher revises against the critic's feedback → Editor → output

To give the desk your Part-3 workflow as a deterministic execution route:

af workflow update --workflow-id <wf_id> --body '{... "public_runnable": true ...}' --json
af workforce init --blueprint autonomous-desk \
  --tool-workflow-id <wf_id> \
  --tool-workflow-purpose "one-line description the planner uses to route missions" \
  --tool-workflow-input '{"your_field": "{{nodes.agent_planner.output.structured_output.workflow_input_primary}}"}' \
  --json

5.2 Why the critic gate is the whole point

In a live production run of this exact desk, the mission was: "Evaluate whether Apple still deserves a spot on our conservative long-term watchlist." The planner routed it through the attached stock-brief workflow, which returned a clean live-data draft in thirty seconds. Then the critic rejected it — 6/10 — because the mission asked for peer-valuation comparisons and quantified margin impact that a generic SOP doesn't cover. The QA gate sent it to the revision pass, the researcher deepened it with live web evidence against the critic's itemized feedback, and the editor shipped a final brief that plainly flagged what remained unverifiable.

Total human involvement after the trigger: zero. That's what you're buying at this layer: not parallelism — quality control that runs without you. The workflow produced the cheap baseline; agent judgment was spent only on the delta the mission demanded.

5.3 Hand-authoring custom graphs

The desk covers plan→verify→revise missions. For custom topologies, have your copilot read af playbook mas-graph-building first — it's the field-verified rulebook. The rules that matter most:

You want	Write
Trigger field	{{trigger.message}}
Agent's reply	{{nodes.<name>.output.last_message}}
Agent's JSON field	{{nodes.<name>.output.structured_output.<field>}}
Shared state variable	{{variables.<name>}}
Workflow result	{{nodes.<name>.output.output.workflow_output.content}}

• References must be exact — including the .output hop. A mistyped reference renders as an empty string, not an error (prompts often legitimately contain literal {{...}} text). So smoke-run every new graph once and check node_start.node_input in the event stream before trusting a mission.

• Condition-node edges use connection_type: "condition" with {branch_index: 0}; -1 is the default/else branch — always wire one.

• Branch merging: each branch gets a state_modifier writing the same variables.<x>; downstream nodes read {{variables.<x>}} without caring which branch ran.

• Workflow invocation from a graph is a plugin node wrapping call_other_workflow — workflow_input is a JSON string, and the target workflow must be public_runnable.

• Deploys diff nodes by name — to change a node's type, rename it.

5.4 Ship it

af workforce publish --workforce-id <id> --json

That mints a public URL and a run endpoint anyone can trigger without platform auth:

curl -X POST https://api.agenticflow.ai/v1/workforce/public/<key>/run \
  -H 'Content-Type: application/json' \
  -d '{"trigger_data":{"message":"<mission>"},"stream":true}'

The run streams live JSON events — you can watch the planner hand off, the workflow execute, the critic pass judgment, node by node. af workforce rotate-key invalidates a leaked URL.

📋 Copy-paste prompt — deploy your autonomous desk:

Deploy an AgenticFlow autonomous desk for my missions.

(1) Run `af workforce init --blueprint autonomous-desk --dry-run --json` and show me
the plan. (2) Deploy it, attaching my workflow <WORKFLOW_ID> as the deterministic
route: set the workflow public_runnable first, and map its inputs from the planner's
structured output with --tool-workflow-input. (3) Publish it and give me the public
URL. (4) Run this test mission through the public endpoint and narrate the event
stream to me node by node — which route the planner chose, what the critic scored,
whether the revision pass fired:

Mission: [PASTE A REAL MISSION — e.g. "Evaluate whether <COMPANY> still deserves a
spot on our conservative long-term watchlist. I care about valuation stretch, margin
pressure, and pending legal exposure."]

(5) Show me the final deliverable and tell me what it cost in credits.

---

Part 6 — Operating well: the habits that compound

Verify at the node level, always. Workflows: .state.nodes_state[]. Workforces: the event stream (node_start shows each node's substituted inputs — the fastest way to catch a templating mistake; node_end shows per-node status and output). Final outputs summarize; node-level state explains.

Put a critic downstream of anything risky. A node can produce a thin or empty result while the run itself completes. A QA-gate agent turns those into revision passes instead of shipped garbage. This is cheaper than it sounds — the critic is a small structured-output model.

Split your model spend. Small structured-output models for routing and verdicts; frontier models for research, writing, and critique. Revisit this whenever your credit bill surprises you.

Blueprints are starting points, not products. Deploy the closest one, then patch (af agent update --patch, af workflow update, af workforce deploy). Everything in this playbook — the audit workflow, the front-door agent, the desk — started life as a blueprint.

Everything user-facing ends in a publish. Chat URL, widget, messaging platforms, workforce public endpoint, webhooks, schedules. The artifact you build is already deployed the moment it works — use that.

Let your AI copilot do the driving. The CLI is built for it: af bootstrap --json as the single source of truth, --json on every command, local validators, schemas on demand (af schema agent, af workforce node-types), and built-in playbooks. Your job is the brief; the copilot's job is the plumbing.

---

Part 7 — Troubleshooting quick reference

Symptom	Cause	Fix
workflow update rejected with missing-field errors	Update expects the flat create shape	Send nodes as a flat array + include output_mapping, project_id, public_runnable; pre-check with af workflow validate --body @file
Workflow "succeeds" but the output is full of N/A	An upstream fetch returned an error page	Read .state.nodes_state[], check the fetch node's status_code and body; add a User-Agent header or switch source
Agent create rejected: "Schema is missing required fields {'schema','name'}"	Bare JSON schema in response_format	Wrap it: {"name": "...", "strict": true, "schema": {...}}
Structured-output agent fails at runtime inside a workforce	Strict mode requires additionalProperties: false	Add it to every object level of the schema; pin the agent to a structured-output-native model
Workforce run "succeeds" but agents complain about empty inputs	A template reference is off (usually the missing .output hop)	Check node_start.node_input in the event stream; fix refs to {{nodes.<name>.output.<field>}}
Condition gate always takes the default branch	Gate is reading a field that isn't there	Confirm the upstream agent has response_format enabled and the gate reads ...output.structured_output.<field>
Workflow node in a workforce fails with "Workflow is not public runnable"	The invoked workflow isn't public-runnable	af workflow update --workflow-id <id> with "public_runnable": true
Node type won't change on redeploy	Deploys diff nodes by name; updates can't change type	Rename the node (forces delete + create)
Authenticated workforce run returns a user-info 400	Known API-key auth issue	Publish the workforce and use the public run endpoint, or run from the web UI

---

The one-shot mega prompt

If you want the whole stack in one brief, paste this into your AI copilot:

You're my AgenticFlow operator. Build my three-layer automation stack end to end.

My business: [2-3 SENTENCES — who you serve, what you sell]
My repeatable SOP: [THE THING YOU DO OVER AND OVER — this becomes the workflow]
My team's front door: [WHO ASKS FOR THINGS AND HOW — this becomes the agent]
My missions: [THE BIG RECURRING ASKS — these go to the autonomous desk]

Process — follow the composition ladder, lowest rung first:
1. `af bootstrap --json`, then `af playbook first-touch`.
2. WORKFLOW: closest blueprint → deploy → customize to my SOP → remove side-effect
   nodes so it returns results → test-run and verify node-by-node via
   .state.nodes_state[].
3. AGENT: research-assistant blueprint → my front-door system prompt → attach the
   workflow as a tool with a docstring-quality description → test that the tool
   fires when it should and doesn't when it shouldn't.
4. WORKFORCE: `af workforce init --blueprint autonomous-desk` with my workflow
   attached as the deterministic route (--tool-workflow-id; set public_runnable
   first). Publish it. Run one realistic mission through the public endpoint and
   narrate the event stream.
5. Report: every resource ID and public URL, what each layer costs per run, and
   the one thing you'd improve next.

Rules: preview with --dry-run before creating; use --patch for agent updates;
small structured-output models for routing decisions, frontier models for prose;
verify every layer by RUNNING it, not by reading its config back.

---

Where to go next

• CLI Walkthrough — Build a Demo Stack — the 20-minute hands-on version

• Workforce Hub — multi-agent concepts and the visual builder

• Workflow Nodes Reference — every node type

• Plans & Credits — what things cost

• af playbook mas-graph-building — the graph-authoring rulebook, inside the CLI