Open in ClaudeOpen in ChatGPTOpen in Cursor
On this page

Automation

run-process-flow

Can be held for approval

Run a process flow against the knowledge base. It returns an execution_id for get-execution. Needs the fabric:agent.run grant.

curl -sS -X POST https://fabric.wexa.ai/mcp/$FABRIC_PROJECT_ID \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "Mcp-Session-Id: $MCP_SESSION_ID" \
  -H "content-type: application/json" -H "accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run-process-flow","arguments":{"process_flow_id":"6ab1945e7566f41b5c28e308","goal":"Reply OK."}}}'
{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000185\",\"result\":{\"execution_id\":\"d8b83fa9-afa7-4619-886f-55fafe5c9bc6\",\"agentflow_id\":\"6ab1945e7566f41b5c28e308\",\"agentflow_name\":\"docs-fixture-flow\",\"goal\":\"Reply OK.\",\"status\":\"running\"}}"
    }
  ],
  "isError": false
}

Parameters

ParameterTypeRequiredNotes
goalstringRequiredNatural-language goal for this run.
agentflow_idstringOptionalAlias for process_flow_id. One of the two is required.
filesarrayOptionalFile ids for execution context. Do not pass for now: it makes the execution unreadable (see More details).
flow_namestringOptionalOnly for compiler (factory) process flows: appended to the goal as the name for the output manifest. It does not select which process flow runs.
input_variablesobjectOptionalInput variables. Ignored on a process flow made from code; put the values in goal.
kb_tagsarrayOptionalExtends (does not replace) a knowledge-base agent's tag filter for this run only. Must be an array. See More details.
process_flow_idstringOptionalProcess flow id to run. Required unless agentflow_id is given. A process flow in this project; not found is reported as 502 here.
session_idstringOptionalConversation id that groups several calls as one conversation.
start_from_agent_idstringOptionalAgent id to start from, instead of the process flow's first agent. An agent inside that flow; not found is reported as 502 here.
Errors
  • UpstreamError (502): the id names a single agent, not a process flow; the error says to use run-agent.
Show full response

A real response, captured from a live call to run-process-flow:

agentflow came back populated and is shown as … here, because the real value runs to thousands of characters. Read it from your own call rather than from this page.

{
  "lifecycle_id": "qlc_000185",
  "result": {
    "agent_type": "Task",
    "agent_version": null,
    "agentflow": "\u2026",
    "agentflow_id": "6ab1945e7566f41b5c28e308",
    "agentflow_name": "docs-fixture-flow",
    "agents_output": [],
    "anomaly_detected": null,
    "application_user_id": "6a79a770b6c128ccc24bfca7",
    "conclusion": null,
    "created_at": 1790023297.303432,
    "duration_ms": null,
    "end_time": null,
    "executed_by": {
      "_id": "6a79a770b6c128ccc24bfca7",
      "application_user_id": "6a79a770b6c128ccc24bfca7",
      "is_external_application": true,
      "metadata": null,
      "name": "6a79a770b6c128ccc24bfca7",
      "type": "api"
    },
    "execution_context": {},
    "execution_id": "d8b83fa9-afa7-4619-886f-55fafe5c9bc6",
    "files": [],
    "goal": "Reply OK.",
    "goal_template": null,
    "input_variables": {},
    "interop_ask": null,
    "interop_resume": null,
    "is_external_application": true,
    "kb_tags": [],
    "parent_execution_id": null,
    "previews": {},
    "projectID": "6aa9beb7ec8121a43b6c791b",
    "runtime_inputs": {},
    "schedule": null,
    "session_id": null,
    "simulation": false,
    "start_from_agent_id": null,
    "status": "running",
    "task_id": "6ab196817566f41b5c28e31d",
    "total_price": null,
    "total_tokens": null,
    "trigger_source": "api"
  }
}
More details

Running starts a real, side-effecting run, as running an agent does. The call returns an execution_id and finishes: the run is asynchronous, so you poll the execution with get-execution. A run can be scoped to a slice of the knowledge base by tag, so every agent that reads it sees the same evidence.

For KB-to-process-flow, first run a compiler-style process flow (one designed to classify ingested knowledge base evidence into a process hierarchy). Its terminal agent's output (see get-execution's last_agent_output) is a process_flow_manifest JSON for create-process-flow's manifest argument.

kb_tags is additive alongside create-process-flow's kb_tags, manifest.knowledge_base.tags and the agent's stored context. It applies only to an agent that already has has_knowledge_base set; it does not switch an agent into knowledge-base mode. A files run is accepted, and every get-execution on it then fails with a ValidationError (422).

Every agent in a process flow makes its own governed calls. A policy decision that refuses one agent's call refuses that call, not the process flow's right to exist. The execution's trace shows what happened, and the audit record shows what was refused.

Known limitations

These are faults in the platform today, each with what to do instead.

files makes the execution unreadable. A run started with files is accepted, and every get-execution on it then fails with a ValidationError (422), so you cannot read its status or conclusion. Do not pass files for now. Add the content to the knowledge base and pass its tags in kb_tags instead.

input_variables is ignored on a process flow made from code. Input variables fill only the process flow's goal template (goal_structure), and a process flow made with create-process-flow has none. A {{name}} in the goal is sent as literal text. A {{name}} in an agent's prompt is worse: the run stops in awaiting_input, only the console can supply the value, and no tool ends the run. Write the values into the goal instead.

Marked consequential: it is audited in full, and a policy rule may hold it for a person to approve. See Policy and approvals.

Every tool call works the same way: How every tool call works.