Feature: Agentic Tasks

Last updated: 2026-06-01

Status (2026-05-25 — RIG hard-cut #696): legacy direct-execution paths have been removed: API /tools/execute, Agent API direct tool execution, Python /v1/tasks*, the legacy Python task runtime, and stale /v1/tasks* AgentClient methods. The agentic-task pre-approval surface still exists at the API level (/agentic/tasks/*), but execution now flows through the Hermes-backed runtime control plane (runs, events, approvals/input, tool/model/sandbox/artifact gateways) with Per-Org × Specialist sandboxed runtimes (#662, #947, #981, #1024). Calls to the removed /v1/tasks/* paths return HTTP 410 with code LEGACY_TASK_AUTHORITY_REMOVED. See docs/architecture/RIG_HARD_CUT_RUNTIME_PORT_PLAN.md and docs/architecture/ISOLATION_SANDBOXING_BINARIES.md.

An agentic task is a multi-step, structured work request where a Specialist proposes a sequence of actions before executing them. Each step must be approved by an Expert (or routed through the RIG approval-event surface) before the runtime 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

Auth scoping (#1567 / #1570): /agentic/tasks* is org-scoped and role-aware. Requests with no resolvable org context return 401. Read access is granted to Experts assigned to the org (via expert_access), to AMs assigned to the org, and to SuperAdmins; everyone else gets 403. The approve/reject step endpoints additionally require the Expert role and a binding on the task's org × Specialist via ExpertAccessService.

Agent Dispatch Mode

Two modes:

• Domain mode (default) — fast path: GPT-4o function calling with pre-defined tools (shopify_query, amazon_query, …) inside the Specialist's sandbox.
• Agentic mode — Hermes-backed runtime for open-ended multi-step tasks. Mode is selected by a combination of conversation-level intent signals and an env override (AGENT_DEFAULT_MODE=agentic). The historical "trigger by keyword" framing (build, deploy, script, …) is superseded by the Hermes-backed runtime control plane (#696 / #947 / #981 / #1024): mode selection is now mediated by the runtime dispatcher, not by a Python keyword regex.

In both modes the agent loads the business-scenario role template selected by the dispatching Specialist's prompt_template_key (ecommerce_ops / finance_ops / ir_reporting / kyc_ops), resolved through the per-Specialist → conversation-role → ecommerce_ops fallback chain. This is the same selector that prevents cross-org template bleed on the conversation path — see ADR-034 — Specialist Prompt-Template Scoping and docs/features/expert-queue.md § Specialist Prompt Template Key.

For full dispatch architecture, see ARCHITECTURE.md and docs/architecture/RIG_HARD_CUT_RUNTIME_PORT_PLAN.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 at /agentic/tasks/*
• Expert approval UI (/agentic): Implemented
• Primary chat path: Implemented — /v1/chat shells out to the real hermes chat CLI via agent/hermes_client.py (PR #194)
• Tool execution: superseded by the RIG runtime control plane (#696). The agentic-task pre-approval surface still exists at the API level (/agentic/tasks/*), but execution now flows through the RIG run authority (runs, events, approvals/input, tool/model/sandbox/artifact gateways), with Per-Org × Specialist sandboxed runtimes (#662). Per-step approval semantics are mediated by RIG approval events, not the removed Python /v1/tasks* runtime. The Python agent/routers/tasks.py now returns HTTP 410 LEGACY_TASK_AUTHORITY_REMOVED for any caller still hitting /v1/tasks*.
• Hermes toolset wiring (#1502 / #1598): the per-run toolset list passed to Hermes is now derived from AgentRun.toolsManifest via the tool gateway client. The HERMES_TOOLSETS env var the runtime sees is populated per-run from that manifest rather than from static deployment config — see docs/api/hermes-agent-runtime-integration-readme.md for the flow.
• Client-facing approval UI (for client-initiated high-stakes actions): Not built (USER_STORIES.md C-W8). Demoted from P0 → P2 on 2026-05-23 — MVP collects approval manually via the conversation channel; dedicated UI is post-launch.