Workflows
Workflows are reusable, multi-step automations that a Managed Agents session executes on demand or on a schedule. Build them with create_workflow, activate and edit them with update_workflow, trigger them with run_workflow, and inspect run history with get_workflow_runs. The companion Marcora Workflow Builder skill documents authoring patterns (step design, scheduling, deduplication, runner-summary conventions).
Tools
create_workflow
Create a new workflow template. Workflows start as status="draft"; activate them via update_workflow once the user confirms.
Input Schema
{
"type": "object",
"required": [
"name",
"steps"
],
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Human-readable workflow name."
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"description"
],
"properties": {
"name": {
"type": "string"
},
"agent_hint": {
"type": "string"
},
"description": {
"type": "string"
}
},
"additionalProperties": true
},
"minItems": 1,
"description": "Ordered step objects. The runner executes these sequentially."
},
"inputs": {
"type": "object",
"description": "Declared input schema. Keys are input names; values describe type/label/required (free-form).",
"additionalProperties": true
},
"description": {
"type": "string",
"description": "One- or two-sentence description of what this workflow accomplishes."
},
"allowed_tools": {
"type": "array",
"items": {
"type": "string"
},
"description": "Narrow allowlist of MCP tool names the runner may call."
},
"schedule_config": {
"type": "object",
"description": "Optional. Creates an accompanying workflow_trigger with is_enabled=false. Shape: frequency (daily/weekly/hourly), interval_hours, timezone (UTC).",
"additionalProperties": true
}
},
"additionalProperties": false
}Output Schema
{
"type": "object",
"required": [
"id",
"name",
"status",
"link_url"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Workflow UUID. Use as workflow_id in other workflow tools."
},
"name": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"steps": {
"type": "array"
},
"inputs": {
"type": "object"
},
"status": {
"enum": [
"draft"
],
"type": "string"
},
"team_id": {
"type": "string",
"format": "uuid"
},
"link_url": {
"type": "string",
"format": "uri"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"description": {
"type": "string"
},
"allowed_tools": {
"type": "array"
},
"created_by_user_id": {
"type": "string"
}
}
}get_workflow
Fetch a single workflow's full definition plus its triggers and latest run. Use before updating a workflow to avoid clobbering unknown fields.
Input Schema
{
"type": "object",
"required": [
"workflow_id"
],
"properties": {
"workflow_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the workflow template."
}
},
"additionalProperties": false
}Output Schema
{
"type": "object",
"required": [
"workflow"
],
"properties": {
"workflow": {
"type": "object",
"required": [
"id",
"name",
"status",
"link_url"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"steps": {
"type": "array"
},
"inputs": {
"type": "object"
},
"status": {
"enum": [
"draft",
"active",
"archived"
],
"type": "string"
},
"link_url": {
"type": "string",
"format": "uri"
},
"_triggers": {
"type": "array",
"description": "Schedule/trigger configs. Inspect _triggers[0].schedule_config and .is_enabled."
},
"_latest_run": {
"type": [
"object",
"null"
],
"description": "Most recent run (carries its own link_url), or null if never run."
},
"allowed_tools": {
"type": "array"
}
}
}
}
}get_workflow_runs
Inspect workflow run history. Two modes: list mode (paginated runs for a workflow) or single mode (one run with step logs and tool call logs) controlled by run_id presence.
Input Schema
{
"type": "object",
"required": [
"workflow_id"
],
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1
},
"run_id": {
"type": "string",
"format": "uuid",
"description": "UUID of a specific run. Omit to list all runs for the workflow."
},
"status": {
"enum": [
"pending",
"running",
"succeeded",
"failed",
"skipped"
],
"type": "string",
"description": "Filter by run status (list mode only)."
},
"per_page": {
"type": "integer",
"default": 20,
"maximum": 100,
"minimum": 1
},
"workflow_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the workflow template."
}
},
"additionalProperties": false
}Output Schema
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Single-run mode only. Run UUID."
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"link_url": {
"type": "string",
"format": "uri"
},
"workflow_template_id": {
"type": "string",
"format": "uuid"
}
}
},
"description": "List mode only. Array of run summaries."
},
"status": {
"type": "string",
"description": "Single-run mode only. Run status."
},
"link_url": {
"type": "string",
"format": "uri",
"description": "Single-run mode only. Direct URL to view this run."
},
"_step_logs": {
"type": "array",
"description": "Single-run mode only. Step execution logs."
},
"itemsTotal": {
"type": "integer",
"description": "List mode only. Total number of matching runs."
},
"_tool_call_logs": {
"type": "array",
"description": "Single-run mode only. Tool call logs."
},
"workflow_template_id": {
"type": "string",
"format": "uuid",
"description": "Single-run mode only."
}
},
"description": "Shape depends on mode. List mode (run_id omitted): items + itemsTotal. Single-run mode (run_id supplied): id, workflow_template_id, status, _step_logs, _tool_call_logs, link_url."
}list_workflows
List workflows for the authenticated user's active team. Supports optional status filter and name search.
Input Schema
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"default": 1,
"minimum": 1
},
"search": {
"type": "string"
},
"status": {
"enum": [
"draft",
"active",
"archived"
],
"type": "string"
},
"per_page": {
"type": "integer",
"default": 20,
"maximum": 100,
"minimum": 1
}
},
"additionalProperties": false
}Output Schema
{
"type": "object",
"required": [
"items",
"itemsTotal"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Workflow ID. Use as workflow_id in get_workflow, update_workflow, run_workflow, and get_workflow_runs."
},
"name": {
"type": "string"
},
"status": {
"enum": [
"draft",
"active",
"archived"
],
"type": "string"
},
"link_url": {
"type": "string",
"format": "uri",
"description": "Direct URL to view the workflow in Marcora."
}
}
}
},
"curPage": {
"type": "integer"
},
"nextPage": {
"type": [
"integer",
"null"
]
},
"prevPage": {
"type": [
"integer",
"null"
]
},
"itemsTotal": {
"type": "integer"
}
}
}run_workflow
Manually dispatch a workflow run. Creates a workflow_run row and dispatches a Managed Agents session. Returns the run row — check .status to know what happened.
Input Schema
{
"type": "object",
"required": [
"workflow_id"
],
"properties": {
"workflow_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the workflow template to run."
},
"input_values": {
"type": "object",
"description": "Values for the workflow's declared inputs, if any.",
"additionalProperties": true
}
},
"additionalProperties": false
}Output Schema
{
"type": "object",
"required": [
"id",
"workflow_template_id",
"status",
"link_url"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Workflow run UUID. Use as run_id in get_workflow_runs (single mode)."
},
"status": {
"enum": [
"running",
"failed",
"skipped"
],
"type": "string"
},
"link_url": {
"type": "string",
"format": "uri"
},
"error_reason": {
"type": [
"string",
"null"
],
"description": "Failure cause when status is failed, else null."
},
"trigger_type": {
"type": "string",
"description": "How the run was triggered. manual for this tool."
},
"error_summary": {
"type": "string"
},
"runner_session_id": {
"type": "string"
},
"workflow_template_id": {
"type": "string",
"format": "uuid"
}
}
}update_workflow
Partial update of a workflow template. Only keys present in the input mutate — unspecified keys are preserved. Call get_workflow first to see the current state.
Input Schema
{
"type": "object",
"required": [
"workflow_id"
],
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"tags": {
"type": "array"
},
"steps": {
"type": "array"
},
"inputs": {
"type": "object"
},
"status": {
"enum": [
"draft",
"active",
"archived"
],
"type": "string"
},
"description": {
"type": "string"
},
"workflow_id": {
"type": "string",
"format": "uuid",
"description": "UUID of the workflow to update."
},
"allowed_tools": {
"type": "array"
}
},
"additionalProperties": false
}Output Schema
{
"type": "object",
"required": [
"id",
"name",
"status",
"link_url"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"steps": {
"type": "array"
},
"inputs": {
"type": "object"
},
"status": {
"enum": [
"draft",
"active",
"archived"
],
"type": "string"
},
"link_url": {
"type": "string",
"format": "uri"
},
"updated_at": {
"type": "string"
},
"allowed_tools": {
"type": "array"
}
}
}