Review Queue

The admin-side queue for approving or rejecting workflows before they go live.

The Review Queue is where lifecycle managers and space admins process staged workflows. Every workflow that a developer submits for review appears here, along with its full graph, history, and any notes from the submitter. Reviewers approve or reject — they cannot edit the graph during review.

---

Who uses the Review Queue

Role	What they can do in the queue
lifecycle_manager	Approve or reject any staged workflow in their space
space_admin	Same as lifecycle_manager, plus manage the approval matrix
admin	Global — can approve or reject any workflow in any space
agent_developer	Read-only — can see their own submissions and their status

---

How a workflow enters the queue

1. A developer finishes editing and clicks Stage for Review in the Agent Builder.
2. The workflow status changes to staged. The graph is locked.
3. The workflow appears in the Review Queue for all lifecycle managers in that space.
4. The developer can no longer edit the workflow until it is approved, rejected, or they click Revise (after rejection).

---

Review Queue interface

Navigate to Admin > Workflows or Dashboard > Review Queue (visibility depends on your role) to see all staged workflows. Each card shows:

Field	Description
Workflow name	Human-readable name
Space	Which space it belongs to
Submitted by	The developer who staged it
Staged at	Timestamp
Notes	Optional notes from the developer
Version	Current version string

Click a workflow to open the full review view. From here you can:

• Browse the full graph (read-only canvas)
• Read the lifecycle history (who did what and when)
• See any active approval stages (if an approval matrix is configured)
• Submit your decision

---

Making a decision

Approve

Moves the workflow directly to Published status. A version snapshot is created automatically at this moment. The workflow is now live and can be invoked via the API.

POST /api/v1/agent-workflows/{id}/approve
{
  "notes": "Looks good — approved for production"
}

Reject

Returns the workflow to Rejected status. The developer is notified and can click Revise to unlock the graph for editing. A rejection requires notes explaining the reason.

POST /api/v1/agent-workflows/{id}/reject
{
  "notes": "The guardrails node is missing for the PII output step. Please add before resubmitting."
}

Notes are mandatory for rejection

The API enforces a non-empty notes field on rejection. This ensures the developer receives actionable feedback rather than a silent failure.

---

Approval Matrix (multi-stage approval)

For workflows that require sign-off from multiple stakeholders before publication, a lifecycle manager can configure an Approval Matrix. When a matrix is active, staging the workflow creates a series of approval stage records — one per configured stage. The workflow cannot be published until all stages are resolved.

Configuring a matrix

PUT /api/v1/agent-workflows/{id}/approval-matrix
{
  "stages": [
    {
      "name": "Legal Review",
      "required_approvers": ["user-id-legal-manager"],
      "required_count": 1,
      "fallback_role": "lifecycle_manager"
    },
    {
      "name": "Exec Sign-off",
      "required_approvers": ["user-id-vp"],
      "required_count": 1,
      "fallback_role": "space_admin",
      "auto_approve_condition": "catalog.catalog_type == 'sandbox'"
    }
  ],
  "auto_approve_condition": null,
  "enabled": true
}

Stage config fields:

Field	Description
name	Display name for this stage
required_approvers	List of user IDs who must approve
required_count	How many of the listed approvers must act (default: all)
fallback_role	Space role to use if named approvers are unavailable
auto_approve_condition	Python expression; if True, this stage is skipped automatically

Global auto_approve_condition: If set on the matrix itself, it is evaluated once when the workflow is staged. If the condition returns True, all stages are skipped and the workflow can be published immediately.

Checking stage progress

GET /api/v1/agent-workflows/{id}/approval-stages

Returns each stage record with its current status, who decided, and any notes.

Deciding on a stage

Each named approver (or anyone with the fallback role) can submit their decision:

POST /api/v1/agent-workflows/{id}/approval-stages/{stage_record_id}/decide
{
  "decision": "approve",
  "notes": "Reviewed the risk assessment logic — approved."
}

When all stages are approved, the workflow is automatically published without requiring a separate /approve call.

Removing the matrix

DELETE /api/v1/agent-workflows/{id}/approval-matrix

Removes the matrix. The workflow reverts to the standard single-step lifecycle (stage → approve/reject).

---

Lifecycle audit log

Every status transition is recorded in an immutable event log:

GET /api/v1/agent-workflows/{id}/lifecycle

Each event includes the actor, their role, the from/to status, a timestamp, and any notes. Use this for compliance, auditing, and debugging lifecycle issues.

Looking for a general "who changed what" trail?

This log only covers stage/approve/reject/revise status transitions. For a full create/update/delete/publish/permission-change trail across the whole workflow (and skills), see Traceability & Audit Log.

Example event:

{
  "id": "evt-abc123",
  "workflow_id": "wf-xyz",
  "from_status": "staged",
  "to_status": "published",
  "actor_id": "user-lm-01",
  "actor_role": "lifecycle_manager",
  "notes": "Approved after legal review.",
  "created_at": 1750842000
}

---

Role reference

Action	Required role
Submit for review (stage)	agent_developer, lifecycle_manager, space_admin
Approve / reject	lifecycle_manager, space_admin, admin
Configure approval matrix	lifecycle_manager, space_admin, admin
Decide on an approval stage	Named approver or fallback role for that stage
View lifecycle history	Any member of the workflow's space

See Workflow Lifecycle for the full status diagram.