GEgetaxonflow
Multi-Agent Planning

Execute a stored plan

Executes a plan previously generated and stored via POST /api/v1/plan. The plan to execute is identified by context.plan_id in the request body. The execution mode is taken from the stored plan (not this request): auto, parallel, sequential, balanced, or the Enterprise-only HITL modes confirm / step.

Where a multi-agent step is decided - in confirm and step mode, and in the other modes only when the orchestrator runs with AXONFLOW_HITL_ENABLED=true outside Community (otherwise no step is decided per step) - it is decided over its content as text: its prompt, statement and parameters as written, then what its processor sends (the rendered prompt of an llm-call; the statement and built parameters of a connector-call) or, for any other step type, the input it is passed. In confirm and step mode a step's hold asks no policy; each step is decided when it runs (POST /api/v1/plan/{id}/resume), for the credential that resumed the plan, in the plan's organization, and anything but an allow fails the step.

Requires authentication: requests must be routed through the AxonFlow Agent (user.id must be set). The X-Tenant-ID / X-Org-ID headers set by the Agent auth chain override any identity fields in the body.

A plan can be executed once: re-executing returns 409, a cancelled plan returns 409, and an expired plan returns 410.

post/api/v1/plan/execute

Request

Request body

querystring required

Natural language task description

domain'travel' | 'healthcare' | 'finance' | 'generic'

Task domain for specialized handling

execution_mode'auto' | 'parallel' | 'sequential' | 'balanced' | 'confirm' | 'step'

How to execute sub-tasks.

  • auto: Automatically determines parallel/sequential (recommended)
  • parallel: Force parallel execution of all independent steps
  • sequential: Force sequential step-by-step execution
  • balanced: I/O-bound connector steps parallel, LLM steps sequential
  • confirm: Every step requires explicit approval before execution (Enterprise only)
  • step: First step auto-executes, subsequent steps require approval (Enterprise only)
clientobject
contextobject

Response

Plan executed successfully. Body is a PlanResponse for normal execution, in which every step was decided by the organization's policy before it ran, on every deployment (#4382; since v11.1.0 AXONFLOW_HITL_ENABLED is ignored). HITL confirm/step dispatch returns an inline object (plan_id, workflow_id, status, current_step, total_steps, step_name, approval_info) instead.

successboolean
plan_idstring
versioninteger

Plan version number (for optimistic locking)

workflow_execution_idstring
resultunknown
errorstring
engine'anchored'

The engine that decided a refused plan: anchored, the ADR-065 decision plane (PRD v11 §1.1). Present on the policy refusal (HTTP 403) only, with the same meaning as on /api/v1/process.

subject_typestring

The type of principal the plan was decided for. The orchestrator admits the client credential the agent's proxy authentication forwards, so it is Client on every edition. Omitted on a refusal made before a subject was admitted, and wherever engine is.

policy_bundlestring

The digest of the policy set that decided the plan. Omitted wherever subject_type is.

verdict'blocked'

blocked on the policy refusal. Omitted wherever engine is.

complexitystring

Plan complexity hint inferred from query characteristics (e.g. simple/medium/complex). Surfaced from the planning engine so callers can apply complexity-aware UI hints.

domainstring

Inferred query domain (e.g. travel, finance, healthcare). Echoes the request's domain field if provided, otherwise populated by the planning engine's domain classifier.

parallelboolean

True when the planning engine produced steps that can execute in parallel. Callers may choose to render parallel-step UIs differently from sequential ones.

statusstring

Plan lifecycle status (e.g. created, in_progress, completed, failed). Mirrors the WorkflowStatusResponse.status field for plans the orchestrator returns synchronously alongside the plan body.

Example response

{
  "version": 1,
  "complexity": "medium",
  "domain": "travel"
}

Changes

No recorded changes to this operation across all 1 revision of this API.