AgentPMT Workflow Creator -- Agent Instructions

Required First Step

Call get_instructions before creating or updating workflows. Then use fetch_tools to get real tool product_id and product_name values before adding tool nodes.

Core Actions

• get_instructions -- Retrieve this workflow authoring guide.
• fetch_tools -- Search available tools for workflow tool nodes.
• search_public -- Check existing public workflows before building from scratch.
• validate -- Dry-run validate nodes and edges without persisting. Use this before create_new, update_existing, and publish when changing graph structure.
• create_new -- Create a private or public workflow draft.
• fetch_existing -- Fetch your workflows or one workflow by skill_id.
• update_existing -- Update metadata, nodes, or edges for an existing draft.
• publish -- Create a versioned executable snapshot.
• remix -- Fork a public workflow into a private editable copy.
• delete -- Delete a workflow you own.
• add_showcase_example / remove_showcase_example -- Manage workflow demos.
• fetch_industry_tags -- List valid industry tags.

Workflow Graph Contract

Persisted workflow nodes are not React Flow nodes. Do not put node configuration inside data. Put each node's configuration at the node root under the key matching its node type.

Tool Node

Use tool ids and names from fetch_tools.

{
  "id": "calculate",
  "type": "tool",
  "label": "Calculate Result",
  "tool": {
    "product_id": "689df4ac8ee2d1dd79e9035b",
    "product_name": "Complex Mathematics Engine",
    "parameters": "{\"action\":\"calculate\",\"expression\":\"2+2\"}",
    "instructions": "Run the calculation and return the numeric result."
  }
}

Rules: tool.product_id must be an accessible active product ObjectId. tool.product_name must be non-empty for agent writes and publish. tool.parameters, when present, must be a JSON string.

Prompt Node

Freeform prompt:

{
  "id": "summarize",
  "type": "prompt",
  "label": "Summarize Result",
  "prompt": {
    "mode": "freeform",
    "text": "Summarize the calculation result for the user."
  }
}

Structured prompt:

{
  "id": "classify",
  "type": "prompt",
  "label": "Classify Expense",
  "prompt": {
    "mode": "structured",
    "goal": "Classify each expense into a reporting category.",
    "inputs": "Receipt vendor, date, amount, and line item text.",
    "outputs": "A category label and short rationale.",
    "constraints": "Use only approved accounting categories."
  }
}

Rules: freeform prompts require non-empty prompt.text for agent writes and publish. Structured prompts require non-empty goal and at least one of inputs or outputs.

for_each Node

Use for_each for iteration instead of graph cycles. Child nodes must set parentId to the for_each node id and must be reached by a loop edge from that parent.

{
  "id": "each-item",
  "type": "for_each",
  "label": "For Each Item",
  "for_each": {
    "item_alias": "item",
    "instructions": "Run the child steps once for each item in the collection."
  }
}

Child prompt example:

{
  "id": "process-item",
  "type": "prompt",
  "label": "Process Item",
  "parentId": "each-item",
  "prompt": {
    "mode": "freeform",
    "text": "Process the current item."
  }
}

Required for_each edges:

[
  { "id": "loop-edge", "from": "each-item", "to": "process-item", "sourceHandle": "loop" },
  { "id": "next-edge", "from": "each-item", "to": "after-loop", "sourceHandle": "next" }
]

Rules: for_each outgoing handles are only loop and next. A parented child is invalid unless there is a loop edge from its for_each parent to that child.

Branch Node

Use branch nodes for conditional paths. Outgoing handles must be path_1, path_2, or path_<index>.

{
  "id": "choose-path",
  "type": "branch",
  "label": "Choose Path",
  "branch": {
    "description": "Select the next path based on the analysis result.",
    "option_count": 2,
    "options": {
      "path_1": { "name": "Approved", "description": "Proceed automatically." },
      "path_2": { "name": "Review", "description": "Ask a human to review." }
    }
  }
}

Merge Node

Use merge nodes to join branch paths.

{
  "id": "merge-paths",
  "type": "merge",
  "label": "Merge Paths",
  "merge": {}
}

notify_human Node

Use only when human approval, credentials, budget, or judgment is genuinely required.

{
  "id": "ask-human",
  "type": "notify_human",
  "label": "Request Approval",
  "notify_human": {
    "request_type": "other",
    "request": "Please review and approve the generated report before delivery."
  }
}

Allowed request_type values: add_funds, enable_tool, enable_workflow, credential_setup, other.

Edge Contract

Edges connect node ids with from and to. Optional handles are sourceHandle and targetHandle.

{ "id": "edge-1", "from": "calculate", "to": "summarize" }

Rules:

• All edge endpoints must reference existing node ids.
• Graphs must be acyclic; use for_each for iteration.
• Duplicate edges with the same from, to, and sourceHandle are invalid.
• Only branch and for_each nodes may have multiple outgoing edges.
• Edge condition is only allowed on branch edges.

Position Fields

Canvas-created workflows may include node position fields when fetched. Agent-authored payloads should omit position unless passing through fetched nodes unchanged. In agent_write validation, position is accepted for compatibility and removed from the canonical stored graph. Browser draft validation and publish snapshots may retain positions for rendering.

Validation Modes

Use validate before persisting graph changes.

{
  "action": "validate",
  "validation_mode": "agent_write",
  "nodes": [ ... ],
  "edges": [ ... ]
}

Modes:

• agent_write -- Use before create_new or update_existing. Accepts existing fetched positions and canonicalizes them away.
• draft_structure -- Browser/editor draft validation.
• publish_executable -- Publish-time validation. Requires at least one tool node and complete executable payloads.

Recommended Build Flow

1. get_instructions.
2. fetch_tools for each external capability needed.
3. search_public to avoid rebuilding existing workflows.
4. Draft root-level nodes and edges using the contract above.
5. Call validate with validation_mode: "agent_write".
6. Call create_new or update_existing only after validation passes.
7. Call fetch_existing to confirm stored graph shape.
8. Call publish only when the graph should become an executable versioned snapshot.

Common Mistakes to Avoid

• Do not send { "type": "tool", "data": { ... } }.
• Do not send { "type": "prompt", "data": { "prompt": "..." } }.
• Do not put product_id or product_name directly on a node; put them under tool.
• Do not create cycles for loops; use for_each with loop and next edges.
• Do not invent product ids. Use fetch_tools.
• Do not publish malformed drafts to test validation. Use validate first.