Authoring Workers

Workers are task-oriented background agents that automate reporting, planning, and execution inside Finqu admin. You configure workers with custom system instructions, tool whitelists, and execution schedules in Work Hub. Once deployed, workers run autonomously when triggered by cron schedules, store events, playbook steps, or manual operator actions.

Worker Architecture

Finqu organizes workers into three specialized roles. This separation enforces the principle of least privilege, ensuring agents that analyze data cannot accidentally alter production store records.

1. Analyst (analyst)

• Role: Data digestion, anomaly detection, and summary generation.
• Tool scope: Read-only tools (analytics queries, inventory levels, order histories, customer metrics, and external BI MCP tools).
• Output: Structured markdown reports, anomaly alerts, or tabular data summaries.
• Common triggers: Nightly or weekly cron schedules, batch post-sale analysis.

2. Planner (planner)

• Role: Strategic evaluation and decision logic.
• Tool scope: Read-only tools, catalog inspection, guideline lookup, and calculation tools.
• Output: Actionable proposals with concrete parameters (for example, suggested reorder quantities, proposed discount codes, or product categorization rules).
• Common triggers: Scheduled after an Analyst report runs, or triggered manually by a merchant in Work Hub.

3. Executor (executor)

• Role: Concrete mutation and implementation.
• Tool scope: Write-scoped tools (creating purchase orders, updating product tags, publishing campaigns, calling external fulfillment MCP tools).
• Output: Execution logs, success/failure statuses, and created entity IDs.
• Common triggers: Playbook execution steps, event triggers requiring automated resolution, or merchant-approved actions.

Worker Configuration Schema

Each worker is defined by a configuration record specifying its role, custom instructions, allowed tools, and schedule:

{
  "slug": "weekly-inventory-analyst",
  "name": "Weekly Inventory Analyst",
  "type": "analyst",
  "system_prompt_extension": "Focus strictly on variants where stock_level < reorder_point. Group findings by manufacturer and calculate total stockout exposure in the store's base currency. Output the summary in Markdown table format.",
  "tool_names": ["get_profile", "list_channels", "list_storages", "search_products", "get_product_inventory"],
  "schedule": "0 6 * * 1",
  "channel_id": 101,
  "status": "active"
}

Configuration fields

Authoring Examples

Example 1: Inventory Analyst Worker

This worker runs every Monday at 06:00 UTC to evaluate stock thresholds and generate an inventory health summary.

{
  "slug": "low-stock-analyst",
  "name": "Low Stock Analyst",
  "type": "analyst",
  "system_prompt_extension": "Inspect inventory across all active warehouses. Identify items below safety stock thresholds. Include current stock, 30-day sales velocity, and estimated days of inventory remaining.",
  "tool_names": ["list_storages", "search_products", "get_product_inventory", "get_sales_velocity"],
  "schedule": "0 6 * * 1"
}

Example 2: Replenishment Planner Worker

This worker takes the Analyst’s findings and generates suggested purchase order drafts adhering to store reorder guidelines.

{
  "slug": "po-replenishment-planner",
  "name": "Purchase Order Planner",
  "type": "planner",
  "system_prompt_extension": "Review low-stock reports from the analyst. For each item below the reorder point, determine the optimal order quantity using minimum order quantities (MOQ) and standard pack sizes. Format proposals as valid JSON arrays matching the draft purchase order schema.",
  "tool_names": ["search_products", "get_manufacturer_details", "list_storages"]
}

Example 3: Transfer Executor Worker

This worker creates stock transfers between warehouses once approved.

{
  "slug": "stock-transfer-executor",
  "name": "Stock Transfer Executor",
  "type": "executor",
  "system_prompt_extension": "Execute inventory transfers between the primary warehouse and regional fulfillment hubs based on verified transfer plans. Never execute transfers exceeding 500 units without human confirmation.",
  "tool_names": ["create_inventory_transfer", "update_inventory_transfer", "add_order_note"]
}

Runtime Execution Lifecycle

When a worker runs, Finqu executes the task through a managed four-phase lifecycle:

1. Triggering

Execution begins through one of three pathways:

• Cron schedule: The configured cron expression fires automatically.
• Store event: An event rule (e.g. order_created, inventory_depleted) starts the worker with event data as input.
• Playbook step: A step in an active playbook invokes the worker, passing outputs from previous steps.

2. Context injection

Before invoking the model, the runtime injects:

• Base identity: Role-specific system instructions (analyst, planner, or executor).
• Domain extension: Your configured system_prompt_extension.
• Store guidelines: Global rules from Guidelines (e.g. brand voice, return policies, margin floors).
• Execution context: Active channel_id, currency, and input payloads from the triggering event or previous playbook step.

3. Tool execution gating

When the worker requests a tool call, the runtime validates the tool against the tool_names array:

• If the tool is present in tool_names and supported by the worker’s OAuth scopes, the call executes.
• If the tool is omitted from tool_names, the call is rejected with a policy denial error:

  Security Exception: Tool 'delete_product' is not permitted for worker 'weekly-inventory-analyst'.

4. Reporting results to Work Hub

Upon completion, the worker returns:

• Status: completed, failed, or waiting_for_approval.
• Summary: Concise explanation of actions taken or findings uncovered.
• Artifacts: Structured data, generated files, or created entity IDs.

Merchants and developers can review full execution logs, tool inputs, and outputs in Work Hub > AI Activity.

Authoring Best Practices

• Limit tool whitelists: Only grant the exact tools each worker requires. An Analyst should never hold write tools like create_product or delete_variant.
• Enforce structured outputs: When a Planner outputs data meant for an Executor, instruct the Planner to output strictly valid JSON conforming to your desired schema.
• Use channel context: Always specify a channel_id if the worker operates on webstore-specific entities such as menus, themes, or articles.
• Inject business rules via Guidelines: Store reusable business logic (e.g. minimum profit margins, supplier contact lists) in Guidelines rather than hardcoding them into individual worker prompts.

Next steps

• Authoring Playbooks — Chain multiple workers into automated pipelines
• Events — Trigger workers automatically based on store actions or schedules
• Inbound MCP Tools — Connect external APIs and services to your workers
• Guidelines — Define global rules and guardrails for workers