Agenticflow Workforce

One-command deploy (v1.6+)

Always preview with --dry-run first:

af workforce init --blueprint  --name "" --dry-run --json
af workforce init --blueprint  --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 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  --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:

``bash af schema workforce --field schema --json ``

1. Create metadata only:

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

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

``bash af workforce deploy --workforce-id --body @graph.json --json ``

1. Validate:

``bash af workforce validate --workforce-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  --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  --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  --version-id  --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 --run-id flag added for parity
• af workforce runs stop --workforce-id --run-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  --dry-run --json
af marketplace try --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  --dry-run --json
# Or duplicate from an existing workforce:
af templates duplicate workforce --workforce-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  --json       # Check pattern before attach
af agent update --agent-id  --patch --body '{"mcp_clients":[{"mcp_client_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  --json
# For each auto-created agent id captured from init:
af agent delete --agent-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 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: antongulin
• Source: antongulin/agenticflow-ai-skills
• License: MIT

Install and usage instructions live in the source repository linked above.