> For the complete documentation index, see [llms.txt](https://docs.agenticflow.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agenticflow.ai/get-started/the-agenticflow-playbook.md). # The AgenticFlow Playbook 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](https://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](/welcome-to-agenticflow/cli-walkthrough.md) 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](https://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:** ```bash 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: ```bash 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: ```bash 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 ```bash 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: ```bash af agent update --agent-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": "", "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: ```json "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 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): ```bash 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: ```bash af workflow update --workflow-id --body '{... "public_runnable": true ...}' --json af workforce init --blueprint autonomous-desk \ --tool-workflow-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..output.last_message}}` | | Agent's JSON field | `{{nodes..output.structured_output.}}` | | Shared state variable | `{{variables.}}` | | Workflow result | `{{nodes..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.`; downstream nodes read `{{variables.}}` 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 ```bash af workforce publish --workforce-id --json ``` That mints a public URL and a run endpoint anyone can trigger without platform auth: ```bash curl -X POST https://api.agenticflow.ai/v1/workforce/public//run \ -H 'Content-Type: application/json' \ -d '{"trigger_data":{"message":""},"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 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 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..output.}}` | | 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.` | | Workflow node in a workforce fails with "Workflow is not public runnable" | The invoked workflow isn't public-runnable | `af workflow update --workflow-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](/welcome-to-agenticflow/cli-walkthrough.md) β€” the 20-minute hands-on version * [Workforce Hub](/workforce/05-workforce.md) β€” multi-agent concepts and the visual builder * [Workflow Nodes Reference](/reference/nodes.md) β€” every node type * [Plans & Credits](/get-started/plans-and-credits.md) β€” what things cost * `af playbook mas-graph-building` β€” the graph-authoring rulebook, inside the CLI