Agenticflow Workforce

One-command deploy (v1.6+)

Always preview with --dry-run first:

af workforce init --blueprint <slug> --name "<name>" --dry-run --json
af workforce init --blueprint <slug> --name "<name>" --json

init creates the workforce + one real agent per required slot + the wired graph — in a single atomic call. On failure, every resource is rolled back automatically; inspect details.rolled_back_agents and details.rolled_back_workforce in the error.

Use --include-optional-slots to fill every slot, not just required ones. Use --model <id> to override the default model for all auto-created agents.

Default model change: Since CLI v1.8.1, blueprint agents default to agenticflow/gpt-4o-mini (not gemini-2.0-flash). GPT-4o-mini follows system prompts and reliably calls tools; Gemini 2.0 Flash sometimes refuses web_search on "latest X" prompts citing cutoff.

Workflow blueprints (deterministic pipelines)

Workforce is NOT the only multi-agent primitive. For simpler, deterministic pipelines (no agent hand-off), use workflow blueprints instead (rung 0-2):

# Rung 0: Single-node hello
af workflow init --blueprint llm-hello --json

# Rung 1: Chained LLM nodes
af workflow init --blueprint llm-chain --json

# Rung 2: Web retrieval + summarize
af workflow init --blueprint summarize-url --json
af workflow init --blueprint api-summary --json
af workflow init --blueprint email-to-structured --json        # v1.10.5
af workflow init --blueprint rss-digest-email --json           # v1.10.5
af workflow init --blueprint competitor-url-snapshot --json    # v1.10.5
af workflow init --blueprint job-app-package --json           # v1.10.5
af workflow init --blueprint n8n-converter --json             # v1.10.5

Workflows require an LLM-provider connection (straico, openai, anthropic). af workflow init auto-discovers it.

Workflow runs support --wait (v1.10.2):

af workflow run --workflow-id <id> --body '{"field":"value"}' --wait --timeout 180 --poll-interval 3 --json
# Polls until terminal. Exits code 2 if failed/cancelled/error.
# Also auto-unwraps {"input":{...}} to flat body when top-level has only that key.

Custom workforce (no blueprint fits)

If the user's ask is a precise custom pipeline that no blueprint matches (e.g. a 2-step researcher → writer flow that doesn't fit the 3–5-agent blueprints), skip blueprints:

1. Inspect the expected graph shape:

   af schema workforce --field schema --json
   

2. Create metadata only:

   af workforce create --body '{"name":"Raul Content Pipeline","description":"..."}' --json
   

3. Create each agent separately via af agent create (see agenticflow-agent skill).
4. Build a graph JSON with trigger → researcher (agent node, agent_id from step 3) → writer (agent node) → output.
5. Deploy the graph atomically:

   af workforce deploy --workforce-id <id> --body @graph.json --json
   

6. Validate:

   af workforce validate --workforce-id <id> --json
   

Edge connection_type is one of next_step, condition, ai_condition. Agent nodes require a real agent_id in input.

Run + publish

af workforce run --workforce-id <id> --trigger-data '{"message":"..."}'
# Streams SSE events — each line is one JSON event. The CLI auto-wraps your
# payload in {trigger_data: ...} — don't wrap it yourself.

af workforce publish --workforce-id <id> --json
# Mints a public_key + public_url.
# Returns `_links.workforce_canvas` (Web UI) and `_links.public_run_curl` (ready-to-paste curl).
# Backend used to return 404 paths; CLI now overrides with correct ones.

af workforce versions publish --workforce-id <id> --version-id <v> --json
# Snapshot + publish a specific version (draft/published/restore workflow).

Workforce run fixes (v1.10.2)

• af workforce publish now returns correct _links.public_run_curl — copy-paste directly
• af workforce runs get --workforce-id <id> --run-id <id> flag added for parity
• af workforce runs stop --workforce-id <id> --run-id <id> flag added for parity

When workforce run fails with API-key auth

The backend sometimes rejects API-key auth on workforce run with Failed to retrieve user info. This is a known server-side limitation. The CLI prints a 3-step workaround:

1. Publish the workforce (af workforce publish)
2. Run via the public SSE endpoint (uses public_key)
3. Check status with af workforce runs list

Live marketplace (beyond built-in blueprints)

When built-in blueprints don't cover the use case, browse the live catalog:

af marketplace list --type mas_template --json              # MAS / workforce templates
af marketplace list --type agent_template --json             # Single-agent templates
af marketplace list --type workflow_template --json        # Workflow templates

Clone a marketplace item into your workspace:

af marketplace try --id <item_id> --dry-run --json
af marketplace try --id <item_id> --json

Cross-workspace caveat: MAS template clones may reference source-workspace agent_ids. Check the warnings field in the response and duplicate source agents separately, or the workforce will 400 on runs.

Workforce template duplication

af templates duplicate workforce --template-id <marketplace_mas_id> --dry-run --json
# Or duplicate from an existing workforce:
af templates duplicate workforce --workforce-id <id> --dry-run --json

Workspace migration (company export/import)

Export workspace agents

af company export --file agents.yaml --json
# Produces a portable YAML with agent definitions.

Import into another workspace

af company import --file agents.yaml --dry-run --json   # Preview changes
af company import --file agents.yaml --json              # Execute

Match key: agent name. Existing agents → update (PUT all fields). Missing agents → create.

Diff before importing

af company diff --file agents.yaml --json
# Read-only comparison. Returns per-agent status: new | modified | in_sync | remote_only.

Merge with conflict strategy

af company merge --file agents.yaml --strategy local --dry-run --json
af company merge --file agents.yaml --strategy local --json

Strategies:

• local — overwrite remote with local (update modified, create new, skip no_change)
• remote — keep live state (skip all modified)
• skip — do nothing (report only)

Never deletes: Remote-only agents are reported but NEVER deleted by any strategy.

Attach MCP tools per agent (not per workforce)

MCP clients attach to individual agents, not to the workforce graph. After init, use:

af mcp-clients list --name-contains "google sheets" --fields id,name --json
af mcp-clients inspect --id <mcp_id> --json       # Check pattern before attach
af agent update --agent-id <agent_id> --patch --body '{"mcp_clients":[{"mcp_client_id":"<id>","run_behavior":"auto_run","tools":{}}]}' --json

See the agenticflow-mcp skill for the Pipedream vs Composio write-safety distinction.

Cleanup

Workforces + agents are billed while they exist. Delete test deploys:

af workforce delete --workforce-id <id> --json
# For each auto-created agent id captured from init:
af agent delete --agent-id <id> --json

Both return {"schema":"agenticflow.delete.v1","deleted":true,"id":"...","resource":"..."} on success.

On errors

All API errors return {schema: "agenticflow.error.v1", code, message, hint, details}. Read hint first — it points at the recovery command (e.g. af <resource> list on a 404). For 422s, inspect details.payload.detail for field-level errors.

workforce run occasionally returns a backend Failed to retrieve user info for user_id: api_key:... 400 — this is a known server-side issue with API-key auth, not a CLI bug.