Feature: Agentic Tasks

Last updated: 2026-05-04

An agentic task is a multi-step, structured work request where an AI Agent proposes a sequence of actions before executing them. Each step must be approved by an Expert before the agent proceeds. This is the primary mechanism for handling consequential or irreversible actions safely.

What Is an Agentic Task

Unlike a standard conversation message (draft + confidence score → Expert queue), an agentic task involves:

1. A plan: a list of discrete steps the agent intends to execute
2. A pre-approval gate: an Expert must approve each step before execution begins
3. Risk classification: each step carries a risk level (low/medium/high/critical)
4. Sequential execution: steps execute in order; any rejection halts execution

Example: "Reconcile all Amazon orders for October and update inventory in Shopify for any discrepancies" would produce a multi-step plan before any changes are made.

Task Structure

{
  "id": "uuid",
  "orgId": "uuid",
  "conversationId": "uuid",
  "description": "Reconcile Amazon orders for October",
  "status": "pending_approval | approved | in_progress | completed | rejected | failed",
  "steps": [
    {
      "stepId": "uuid",
      "order": 1,
      "description": "Fetch all Amazon orders for October 2026",
      "toolName": "amazon_query",
      "parameters": { "action": "listOrders", "dateRange": "2026-10" },
      "riskLevel": "low",
      "status": "pending | approved | rejected | executed | failed",
      "expertFeedback": null
    },
    {
      "stepId": "uuid",
      "order": 2,
      "description": "Update Shopify inventory for 14 mismatched SKUs",
      "toolName": "shopify_query",
      "parameters": { "action": "updateInventory", "skuCount": 14 },
      "riskLevel": "high",
      "status": "pending | approved | rejected | executed | failed",
      "expertFeedback": null
    }
  ]
}

Risk Classification

Each step is assigned a risk level by the agent:

Risk Level	Meaning	Auto-Approve?
low	Read-only or informational	Configurable (default: no)
medium	Minor writes, reversible	No
high	Significant writes, hard to reverse	No
critical	Destructive, financial, compliance-sensitive	No

Current classification: keyword heuristic. LLM-based classification planned for P2.

Pre-Approval Flow

Client message triggers agentic task
         │
         ▼
Agent constructs step plan → AgenticTask created (status: pending_approval)
         │
         ▼
Expert sees task in /agentic view
         │
         ├── Approve step 1 → POST /agentic/tasks/:id/steps/:stepId/approve
         │       │
         │       └── Step executes (tool call) → step status: executed
         │               │
         │               └── Next step presented for approval
         │
         └── Reject step → POST /agentic/tasks/:id/steps/:stepId/reject
                 │ (provide feedback)
                 └── Task halts → Expert notified, client informed

Expert Interface

The Expert Workspace provides a To Review tab (nav: /workspace/tasks) showing tasks pending approval. For each task:

• Full plan is visible (all steps with descriptions, tools, parameters, risk levels)
• Steps are approved/rejected one at a time in sequence
• Expert can add feedback on rejection (sent to agent for plan revision)
• Task status tracks which steps are complete

API Endpoints

Method	Path	Auth	Description
POST	/agentic/tasks	JWT	Create agentic task with step plan
GET	/agentic/tasks	JWT	List tasks by org (filter: status=pending_approval)
GET	/agentic/tasks/:id	JWT	Get task status + full plan
POST	/agentic/tasks/:id/steps/:stepId/approve	Expert	Approve a step
POST	/agentic/tasks/:id/steps/:stepId/reject	Expert	Reject step with feedback

Agent Dispatch Mode

The agent service runs in two modes. Agentic mode is triggered by:

1. Keyword detection in the message: build, deploy, script, scrape, automate, crawl, analyze all, process batch, create website, write code
2. Environment override: AGENT_DEFAULT_MODE=agentic

When no agentic keywords are detected (and no override), the agent runs in domain mode (fast path: function calling with pre-defined tools like shopify_query and amazon_query).

For full dispatch architecture, see ARCHITECTURE.md.

Tool Permissions

Each org must have tool permissions explicitly enabled before the agent can invoke a tool. This prevents agents from using integrations the org has not configured.

• GET /orgs/:orgId/tool-permissions — list enabled tools
• PUT /orgs/:orgId/tool-permissions/:toolName — enable/disable with optional config

Current Status

• Multi-step plan structure: Implemented
• Pre-approval gate (API): Implemented
• Expert approval UI (/agentic): Implemented
• Primary chat path (Hermes runtime): Implemented — /v1/chat shells out to the real hermes chat CLI via agent/hermes_client.py (PR #194)
• Tool execution: Implemented in the agent service for approved task steps — /v1/tasks/* plans with Hermes, checkpoints task state locally, waits for step approval, and executes approved steps through Hermes Agent. Live external credentials remain deployment-dependent.
• Client-facing approval UI (for client-initiated high-stakes actions): Not built (USER_STORIES.md C-W8, P0 gap)