veryfront__create_runpublic_id for idempotency.
Requires editor access to the owner, and project.runs.write for a project owner.
Follow the run with get_run, list_run_events or get_run_snapshot; streaming stays on REST.
Access
No external-service connection is required. Use a Veryfront credential with access to the requested resources. Call type: Can change resources.Arguments
| Field | Type | Required | Description and constraints |
|---|---|---|---|
kind | string | Yes | Run kind, as in the REST POST /runs body. eval is recognized only to return task:eval migration guidance. Values: "agent", "workflow", "task", "eval". |
owner | object | Yes | The resource that owns the run. Requires editor access to it. |
public_id | string | No | Caller-chosen run id. Repeating a public_id returns the existing run (duplicate: true). |
parent_run_id | string | No | Public id of the parent run, for a child run. |
trigger | object | No | What triggered the run, as in the REST POST /runs body. |
composing_user_id | string | No | Conversation-owned agent runs: the account that composed the run. |
conversation_mode | string | No | Project-owned agent runs: none (default), create_new or existing. |
conversation_id | string | No | Project-owned agent runs with conversation_mode existing: the conversation to run in. |
request | object | Yes | The kind-specific REST request object in the REST spelling: workflow {name?, workflow_id, target, input?, start_mode?, runtime_target_}; task {target, name?, batch_id?, input?, config?, timeout_seconds?, backoff_limit?, runtime_target_}; agent {mode: “agent”, name? and the agent request fields} as documented for POST /runs. name is the run’s title. |
Example request
Send this JSON-RPC request through an initialized MCP client. Replace sample identifiers and values before calling the tool. See MCP client setup.request.json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "veryfront__create_run",
"arguments": {
"kind": "agent",
"owner": {
"kind": "conversation",
"id": "00000000-0000-4000-8000-000000000000"
},
"request": {}
}
}
}
Result
The published output shape is summarized below. Inspect both the MCP response content andisError when handling a call.
| Field | Type | Required | Description and constraints |
|---|---|---|---|
accepted | boolean | Yes | Whether the request was accepted. |
duplicate | boolean | No | Whether the submitted response duplicated an existing response. |
run | object | Yes | Structured run details associated with this tool result. |
conversation_id | string or null | No | Conversation identifier associated with this result. |
message_id | string or null | No |
Full schemas
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"agent",
"workflow",
"task",
"eval"
],
"description": "Run kind, as in the REST POST /runs body. eval is recognized only to return task:eval migration guidance."
},
"owner": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"conversation",
"project"
],
"description": "conversation (agent runs only) or project (every kind)."
},
"id": {
"type": "string",
"format": "uuid",
"description": "Conversation id or project id (a UUID, not a slug)."
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false,
"description": "The resource that owns the run. Requires editor access to it."
},
"public_id": {
"type": "string",
"description": "Caller-chosen run id. Repeating a public_id returns the existing run (duplicate: true)."
},
"parent_run_id": {
"type": "string",
"description": "Public id of the parent run, for a child run."
},
"trigger": {
"type": "object",
"properties": {
"conversation_id": {
"type": "string",
"description": "Conversation identifier that scopes the request."
},
"message_id": {
"type": "string",
"description": "Provide the message id."
},
"tool_call_id": {
"type": "string",
"description": "Tool call identifier that links this request to a prior tool invocation."
}
},
"additionalProperties": false,
"description": "What triggered the run, as in the REST POST /runs body."
},
"composing_user_id": {
"type": "string",
"description": "Conversation-owned agent runs: the account that composed the run."
},
"conversation_mode": {
"type": "string",
"description": "Project-owned agent runs: none (default), create_new or existing."
},
"conversation_id": {
"type": "string",
"description": "Project-owned agent runs with conversation_mode existing: the conversation to run in."
},
"request": {
"type": "object",
"additionalProperties": {
"description": "Additional structured values supplied to the tool."
},
"description": "The kind-specific REST request object in the REST spelling: workflow {name?, workflow_id, target, input?, start_mode?, runtime_target_*}; task {target, name?, batch_id?, input?, config?, timeout_seconds?, backoff_limit?, runtime_target_*}; agent {mode: \"agent\", name? and the agent request fields} as documented for POST /runs. name is the run's title."
}
},
"required": [
"kind",
"owner",
"request"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Arguments for the create_run tool."
}
{
"type": "object",
"properties": {
"accepted": {
"type": "boolean",
"description": "Whether the request was accepted."
},
"duplicate": {
"type": "boolean",
"description": "Whether the submitted response duplicated an existing response."
},
"run": {
"type": "object",
"properties": {
"run_id": {
"type": "string",
"minLength": 1,
"description": "Run identifier associated with this result."
},
"id": {
"type": "string",
"minLength": 1,
"description": "Unique identifier for the returned record."
},
"kind": {
"type": "string",
"enum": [
"agent",
"workflow",
"task",
"eval"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"running",
"waiting",
"completed",
"failed",
"cancelled"
],
"description": "Lifecycle status for the returned record."
},
"owner": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"conversation",
"project"
]
},
"id": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the returned record."
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false,
"description": "Structured owner details associated with this tool result."
},
"project_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"description": "Project identifier associated with this result."
},
{
"type": "null",
"description": "Project identifier associated with this result."
}
],
"description": "Project identifier associated with this result."
},
"conversation_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"description": "Conversation identifier associated with this result."
},
{
"type": "null",
"description": "Conversation identifier associated with this result."
}
],
"description": "Conversation identifier associated with this result."
},
"message_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null",
"description": "The message id returned by the tool."
}
]
},
"usage": {
"anyOf": [
{
"type": "object",
"properties": {
"requests": {
"type": "integer",
"minimum": 0
},
"model_calls": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null",
"description": "The model calls returned by the tool."
}
]
},
"input_tokens": {
"type": "integer",
"minimum": 0
},
"output_tokens": {
"type": "integer",
"minimum": 0
},
"cache_creation_input_tokens": {
"type": "integer",
"minimum": 0
},
"cache_read_input_tokens": {
"type": "integer",
"minimum": 0
},
"reasoning_tokens": {
"type": "integer",
"minimum": 0
},
"total_tokens": {
"type": "integer",
"minimum": 0
},
"cost_credits": {
"anyOf": [
{
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
{
"type": "null",
"description": "The cost credits returned by the tool."
}
]
}
},
"required": [
"requests",
"model_calls",
"input_tokens",
"output_tokens",
"cache_creation_input_tokens",
"cache_read_input_tokens",
"reasoning_tokens",
"total_tokens",
"cost_credits"
],
"additionalProperties": false,
"description": "Structured usage details associated with this tool result."
},
{
"type": "null",
"description": "The usage returned by the tool."
}
]
},
"tool_error_count": {
"type": "integer",
"minimum": 0
},
"children_failed": {
"type": "boolean"
},
"parent_run_id": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null",
"description": "The parent run id returned by the tool."
}
]
},
"root_run_id": {
"type": "string",
"minLength": 1
},
"waiting_reason": {
"anyOf": [
{
"type": "string",
"enum": [
"tool",
"approval",
"event",
"input",
"child_run",
"manual_pause"
]
},
{
"type": "null",
"description": "The waiting reason returned by the tool."
}
]
},
"waiting_on": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "run"
},
"run_id": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Run identifier associated with this result."
},
"correlation": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"tool_call",
"workflow_node"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Unique identifier for the returned record."
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false,
"description": "Structured correlation details associated with this tool result."
}
},
"required": [
"kind",
"run_id",
"correlation"
],
"additionalProperties": false
},
"description": "List of waiting on associated with this tool result."
},
{
"type": "null",
"description": "The waiting on returned by the tool."
}
]
},
"waiting": {
"anyOf": [
{
"type": "object",
"properties": {
"reason": {
"$ref": "#/properties/run/properties/waiting_reason/anyOf/0",
"description": "The reason returned by the tool."
},
"on": {
"type": "array",
"items": {
"$ref": "#/properties/run/properties/waiting_on/anyOf/0/items",
"description": "One on item returned by the tool."
},
"description": "List of on associated with this tool result."
},
"pending_approvals": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"maxItems": 100,
"description": "List of pending approvals associated with this tool result."
},
"resume_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null",
"description": "The resume at returned by the tool."
}
]
}
},
"required": [
"reason",
"on",
"pending_approvals",
"resume_at"
],
"additionalProperties": false,
"description": "Structured waiting details associated with this tool result."
},
{
"type": "null",
"description": "The waiting returned by the tool."
}
]
},
"metadata": {
"anyOf": [
{
"description": "Additional structured metadata returned by the tool."
},
{
"type": "null",
"description": "Additional structured metadata returned by the tool."
}
],
"description": "Additional structured metadata returned by the tool."
},
"cancellation": {
"anyOf": [
{
"type": "object",
"properties": {
"requested_at": {
"type": "string"
},
"stopped_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"requested_at",
"stopped_at"
],
"additionalProperties": false,
"description": "Structured cancellation details associated with this tool result."
},
{
"type": "null",
"description": "The cancellation returned by the tool."
}
]
},
"pause": {
"anyOf": [
{
"type": "object",
"properties": {
"requested_at": {
"type": "string"
}
},
"required": [
"requested_at"
],
"additionalProperties": false,
"description": "Structured pause details associated with this tool result."
},
{
"type": "null",
"description": "The pause returned by the tool."
}
]
},
"control": {
"type": "object",
"properties": {
"pause": {
"type": "object",
"properties": {
"requested_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"requested_at"
],
"additionalProperties": false,
"description": "When a pause was requested; control.waiting confirms when execution is paused."
},
"waiting": {
"anyOf": [
{
"type": "object",
"properties": {
"resume_at": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string",
"enum": [
"manual_pause"
]
}
},
"required": [
"reason"
],
"additionalProperties": false,
"description": "Structured option 1 details associated with this tool result."
},
{
"type": "object",
"properties": {
"resume_at": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string",
"enum": [
"tool_result"
]
},
"tool_call_id": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Tool call identifier associated with this result."
}
},
"required": [
"reason",
"tool_call_id"
],
"additionalProperties": false,
"description": "Structured option 2 details associated with this tool result."
},
{
"type": "object",
"properties": {
"resume_at": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string",
"enum": [
"integration_connected"
]
},
"integration": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"reason",
"integration"
],
"additionalProperties": false,
"description": "Structured option 3 details associated with this tool result."
},
{
"type": "object",
"properties": {
"resume_at": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string",
"enum": [
"approval"
]
},
"wait_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"node_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"minItems": 1,
"description": "List of node ids associated with this tool result."
}
},
"required": [
"reason",
"wait_id",
"node_ids"
],
"additionalProperties": false,
"description": "Structured option 4 details associated with this tool result."
},
{
"type": "object",
"properties": {
"resume_at": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string",
"enum": [
"event"
]
},
"wait_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Human-readable name for the returned record."
}
},
"required": [
"reason",
"wait_id",
"name"
],
"additionalProperties": false,
"description": "Structured option 5 details associated with this tool result."
},
{
"type": "object",
"properties": {
"resume_at": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string",
"enum": [
"input_request"
]
},
"input_request_ids": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
},
"minItems": 1,
"description": "List of input request ids associated with this tool result."
}
},
"required": [
"reason",
"input_request_ids"
],
"additionalProperties": false,
"description": "Structured option 6 details associated with this tool result."
},
{
"type": "object",
"properties": {
"resume_at": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string",
"enum": [
"child_run"
]
},
"dependencies": {
"type": "array",
"items": {
"type": "object",
"properties": {
"run_id": {
"type": "string",
"format": "uuid",
"description": "Run identifier associated with this result."
},
"correlation": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"tool_call"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Unique identifier for the returned record."
}
},
"required": [
"type",
"id"
],
"additionalProperties": false,
"description": "Structured option 1 details associated with this tool result."
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"workflow_node"
]
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"description": "Unique identifier for the returned record."
}
},
"required": [
"type",
"id"
],
"additionalProperties": false,
"description": "Structured option 2 details associated with this tool result."
}
]
}
},
"required": [
"run_id",
"correlation"
],
"additionalProperties": false
},
"minItems": 1,
"description": "List of dependencies associated with this tool result."
}
},
"required": [
"reason",
"dependencies"
],
"additionalProperties": false,
"description": "Structured option 7 details associated with this tool result."
},
{
"type": "object",
"properties": {
"resume_at": {
"type": "string",
"format": "date-time"
},
"reason": {
"type": "string",
"enum": [
"timer"
]
}
},
"required": [
"resume_at",
"reason"
],
"additionalProperties": false,
"description": "Structured option 8 details associated with this tool result."
}
],
"description": "The current durable wait, with only the fields required to satisfy that wait."
}
},
"additionalProperties": false
},
"title": {
"type": [
"string",
"null"
],
"description": "Short human-readable title returned by the tool."
},
"target": {
"type": [
"string",
"null"
]
},
"workflow_id": {
"type": [
"string",
"null"
]
},
"schedule_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null",
"description": "The schedule id returned by the tool."
}
]
},
"batch_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null",
"description": "The batch id returned by the tool."
}
]
},
"runtime_target_kind": {
"anyOf": [
{
"type": "string",
"enum": [
"main_branch",
"environment",
"preview_branch"
],
"description": "Provide the runtime target kind."
},
{
"type": "null",
"description": "The runtime target kind returned by the tool."
}
],
"description": "Provide the runtime target kind."
},
"runtime_target_environment_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null",
"description": "The runtime target environment id returned by the tool."
}
]
},
"runtime_target_branch_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null",
"description": "The runtime target branch id returned by the tool."
}
]
},
"input": {
"anyOf": [
{},
{
"type": "null",
"description": "The input returned by the tool."
}
]
},
"config": {
"anyOf": [
{},
{
"type": "null",
"description": "The config returned by the tool."
}
]
},
"output": {
"anyOf": [
{},
{
"type": "null",
"description": "The output returned by the tool."
}
]
},
"error": {
"anyOf": [
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
}
},
"required": [
"message"
],
"additionalProperties": true,
"description": "Error details returned by the tool."
},
{
"type": "null",
"description": "Error details returned by the tool."
}
],
"description": "Error details returned by the tool."
},
"logs": {
"type": [
"string",
"null"
]
},
"artifacts": {
"type": "array",
"items": {},
"description": "List of artifacts associated with this tool result."
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null",
"description": "The duration ms returned by the tool."
}
]
},
"exit_code": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null",
"description": "The exit code returned by the tool."
}
]
},
"start_mode": {
"type": [
"string",
"null"
]
},
"timeout_seconds": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null",
"description": "The timeout seconds returned by the tool."
}
]
},
"backoff_limit": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null",
"description": "The backoff limit returned by the tool."
}
]
},
"input_schema_sha256": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
{
"type": "null",
"description": "The input schema sha256 returned by the tool."
}
]
},
"output_schema_sha256": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9a-f]{64}$"
},
{
"type": "null",
"description": "The output schema sha256 returned by the tool."
}
]
},
"input_schema_hash": {
"anyOf": [
{
"type": "string",
"pattern": "^sha256:[0-9a-f]{64}$"
},
{
"type": "null",
"description": "The input schema hash returned by the tool."
}
]
},
"output_schema_hash": {
"anyOf": [
{
"$ref": "#/properties/run/properties/input_schema_hash/anyOf/0",
"description": "The output schema hash returned by the tool."
},
{
"type": "null",
"description": "The output schema hash returned by the tool."
}
]
},
"trigger": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"manual",
"schedule",
"webhook",
"api"
]
},
"id": {
"type": [
"string",
"null"
],
"description": "Unique identifier for the returned record."
},
"principal": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"system",
"user",
"api_key",
"service_account"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the returned record."
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false,
"description": "Structured principal details associated with this tool result."
}
},
"required": [
"kind",
"id",
"principal"
],
"additionalProperties": false,
"description": "Structured trigger details associated with this tool result."
},
{
"type": "null",
"description": "The trigger returned by the tool."
}
]
},
"trigger_kind": {
"anyOf": [
{
"type": "string",
"enum": [
"manual",
"schedule",
"webhook",
"api"
]
},
{
"type": "null",
"description": "The trigger kind returned by the tool."
}
]
},
"trigger_id": {
"type": [
"string",
"null"
]
},
"trigger_principal_type": {
"anyOf": [
{
"type": "string",
"enum": [
"system",
"user",
"api_key",
"service_account"
]
},
{
"type": "null",
"description": "The trigger principal type returned by the tool."
}
]
},
"trigger_principal_id": {
"type": [
"string",
"null"
]
},
"created_by": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 255
},
{
"type": "null",
"description": "The created by returned by the tool."
}
]
},
"updated_at": {
"type": "string",
"description": "Last update timestamp in ISO 8601 format."
},
"created_at": {
"type": "string",
"description": "Creation timestamp in ISO 8601 format."
},
"started_at": {
"type": [
"string",
"null"
]
},
"completed_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"run_id",
"id",
"kind",
"status",
"owner",
"project_id",
"conversation_id",
"message_id",
"usage",
"tool_error_count",
"children_failed",
"parent_run_id",
"root_run_id",
"waiting_reason",
"waiting_on",
"waiting",
"cancellation",
"pause",
"title",
"target",
"workflow_id",
"schedule_id",
"batch_id",
"runtime_target_kind",
"runtime_target_environment_id",
"runtime_target_branch_id",
"error",
"logs",
"artifacts",
"duration_ms",
"exit_code",
"start_mode",
"timeout_seconds",
"backoff_limit",
"input_schema_sha256",
"output_schema_sha256",
"input_schema_hash",
"output_schema_hash",
"trigger",
"trigger_kind",
"trigger_id",
"created_by",
"updated_at",
"created_at",
"started_at",
"completed_at"
],
"additionalProperties": false,
"description": "Structured run details associated with this tool result."
},
"conversation_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"description": "Conversation identifier associated with this result."
},
{
"type": "null",
"description": "Conversation identifier associated with this result."
}
],
"description": "Conversation identifier associated with this result."
},
"message_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null",
"description": "The message id returned by the tool."
}
]
}
},
"required": [
"accepted",
"run"
],
"additionalProperties": false,
"description": "Structured result returned by the create_run tool.",
"$schema": "http://json-schema.org/draft-07/schema#"
}