Projects, Processes & Tasks — The Agent Work Model

How AgileX agents do real work inside Huly under human supervision: the three primitives, what agents can and can't touch via the API, and the patterns that keep a human in the loop.

1. Why this matters for agents

An autonomous agent with raw write access to a workspace is a liability — it can act fast, confidently, and wrongly. The value of running AgileX agents inside Huly is that Huly already provides the structures a moderated workflow needs: a unit of work that can carry state, a status lifecycle that can act as an approval gate, a comment thread that doubles as a human-agent conversation, and a notification system that pulls a human in at the right moment.

Instead of inventing an approval system, AgileX agents express their work as Huly objects. Every action an agent takes leaves an auditable trail, every decision can be parked behind a status gate, and every human override is a first-class event. The agent doesn't have a private state machine — the Huly board is the state machine, and it's one a human can see and touch at any moment.

2. The three primitives

3. How they nest

Tasks and Processes meet at the Card. In Recruiting, a Talent is a card; a screening Process runs against that talent card; and the individual steps surface as Tasks a recruiter or agent acts on. The Process keeps the sequence honest; the Tasks carry the work; the Project bounds the whole thing.

4. Capability matrix (verified against the live MCP server)

This is the actual surface exposed by @firfi/huly-mcp@0.30.1 connected to huly.app workspace agilex — not the docs, the running server.

Adjacent surfaces an agent can also use as moderation signals: list_notifications / mark_notification_read, list_mentions, add_reaction, list_object_collaborators, fulltext_search, plus full Document, Drive, Contacts, and Channel (chat) toolsets.

5. The Process truth: define vs. run

Why this is a feature, not a limitation. If agents could rewrite the workflow definition, they could remove the very gates that make the flow safe. By making the Process layer human-authored and immutable-to-agents, AgileX guarantees that:

• The sequence of states (and which require human approval) is set by a person and can't be silently bypassed.
• Agents operate within the rail: they can start_process on a card, watch the execution progress, and cancel_execution if something is wrong — but they can't invent a new rail.
• Changing the workflow is a deliberate, human, UI-level act with an audit trail.

So how do you create a Process?

1. Author in the UI — Recruiting/Settings → Processes (the ⚡ module). Define the master tag it attaches to (e.g. Talent), its states, transitions, and automated actions. This is the supported, recommended path.
2. Raw transactor (advanced, not via this MCP) — Process definitions are ordinary documents in the @hcengineering/process plugin. A privileged service with transactor access can create them programmatically with TxOperations, but that path is intentionally outside the agent's toolset and reserved for platform setup/migration scripts.

For everything that looks like a lightweight process but needs to be agent-creatable, use Tasks + Statuses + Todos instead (§7). That's the agent-writable equivalent of a workflow.

6. The four moderation channels

"Human-assisted and moderated" is not a vibe — in AgileX it maps to four concrete Huly mechanisms an agent uses deliberately:

The key design move: an agent never performs an irreversible or outward-facing action directly (sending an offer, rejecting a candidate, emailing externally). It stages the action as a task in a gate status and waits for human approval. Approval = a human moving the status forward, which the agent detects by polling list_issues / list_notifications.

7. Human-assisted flow patterns

Pattern A — Status as approval gate

The agent polls for the human's decision rather than blocking a thread. Statuses ending in Needs Review / Approved / Rejected are the contract.

Pattern B — Confidence-routed autonomy

The agent self-grades. High confidence → it advances within the rail automatically. Low confidence → it routes to a gate with an @mention. This keeps humans focused only on the ambiguous cases.

Pattern C — Process execution as the spine, tasks as the work

A human-authored Talent Screening Process defines the rail. The agent start_process-es it on a talent card, then for each state creates the concrete Task it needs to do, and reports progress back via comments. The Process guarantees order; the Tasks carry the doing.

Pattern D — Todos as the agent's scratchpad

Within a single task, the agent breaks its plan into create_todo items and complete_todos them as it goes. Humans watching the task see a live checklist of what the agent is doing — transparency without interruption.

8. Worked example — Recruiting (the agilex workspace)

The generic primitives in §2 have exact counterparts in Huly's Recruiting module. This is the mapping AgileX agents actually operate on:

Live data in the workspace: talents like James Grant, Kagiso Maile (Senior ML), Chloé Dubois, Rudzani Nemukula (Staff MLOps), Farhan Ismail (Principal AI). Here's the moderated loop for one of them against a Senior ML Engineer vacancy:

1. Human (once): creates the Senior ML Engineer Vacancy and defines the Application status pipeline (e.g. New → Screening → Review → Shortlisted → Interview → Offer), marking Shortlisted+ as requiring a Review verdict.
2. Agent: finds the Talent (list_cards / Talent master tag), creates the Application linking Kagiso Maile → Senior ML Engineer at status Screening.
3. Agent: reads the CV via download_attachment / fulltext_search, scores fit against the vacancy's Skills, writes its assessment into the application and advances status → Review.
4. ⛔ Gate — Review: agent add_comment("@craig fit 0.78 for Senior ML — strengths/risks below"). The recruiter records a Review verdict + notes and moves the application → Shortlisted (approve) or Rejected / back to Screening (redirect).
5. Agent: on detecting Shortlisted, stages the interview-scheduling step (create_event / invite) — again parked behind the next gate before anything external is sent.

At no point does the agent reject a candidate or send an external email on its own authority. The Application status is the state machine and the Review verdict is the human signature — every outward action is a human-approved transition.

9. Setting up the rails (illustrative API calls)

What a human/operator does once to give agents a place to work. Calls shown as MCP tool invocations; parameter names are indicative — confirm exact schema with tools/list.

Create the project (the sandbox)

create_project {
  name: "Recruiting",
  identifier: "REC",
  projectType: "Classic project"
}

Define a Task Type + its gate status

create_task_type {
  projectType: "Classic project",
  name: "Screening",
  fromTemplate: "Task"            # copies workflow config
}
create_issue_status {
  project: "REC",
  name: "Needs Review",          # the approval gate
  category: "Active"
}

Agent creates and advances a task

create_issue {
  project: "REC", title: "Screen — Kagiso Maile",
  type: "Screening", status: "In Progress",
  assignee: "agent:screener"
}
# …work happens…
update_issue { issue: "REC-42", status: "Needs Review" }
add_comment { object: "REC-42",
  message: "@craig fit 0.78 — recommend shortlist. Rationale: …" }

Run a (human-authored) process on a card

list_processes { masterTag: "Talent" }          # discover the rail
start_process {
  process: "Talent Screening",
  card: "talent:kagiso-maile"
}
list_process_executions { card: "talent:kagiso-maile" }   # watch state

10. Design principles for AgileX agents in Huly

AgileX / agenticX · Agent Work Model · grounded against live @firfi/huly-mcp on workspace agilex · June 2026. See also: Huly Integration Guide, Huly MCP Spec, Platform Architecture.