mcp_aql_execute
Control the execution lifecycle of agents, workflows, and pipelines: start runs, approve pending operations, resume paused tasks, abort unwanted executions, and transfer progress across sessions.
Instructions
Execution lifecycle operations for executable elements (agents, workflows, pipelines).
Supported operations: confirm_operation, approve_cli_permission, execute_agent, complete_execution, continue_execution, abort_execution, prepare_handoff, resume_from_handoff
These operations manage runtime execution state. Unlike CRUD operations (which manage definitions), Execute operations handle the execution lifecycle:
execute_agent: Start a new execution (returns goalId and stateVersion for tracking)
complete_execution: Signal successful completion once the goal is done
continue_execution: Resume a previously paused execution with the same goal parameters
abort_execution: Abort a running execution, rejecting further operations
confirm_operation: Confirm a pending operation that requires user approval (Gatekeeper flow)
approve_cli_permission: Approve a pending CLI tool permission request
prepare_handoff: Serialize goal progress into a portable handoff block for session transfer
resume_from_handoff: Resume agent execution from a handoff block with integrity validation
IMPORTANT: Execute operations are potentially destructive (agents can perform any action) and non-idempotent (calling execute_agent twice creates two separate executions).
⚠️ SECURITY: Do not auto-allow this endpoint in your host settings (e.g., Claude Code settings.json). Each execution should require explicit human approval. Auto-allowing bypasses the per-operation confirmation gate. While DangerZone verification and element deny policies still provide protection, the primary human review checkpoint is lost.
Canonical loop:
Call execute_agent once to start the goal and receive { goalId, stateVersion, activeElements, safetyTier, ... }.
After each chunk of work, use mcp_aql_create: { operation: "record_execution_step", ... }.
Read record_execution_step.autonomy.continue and any autonomy.notifications to decide whether to continue, pause for a human, or handle a gatekeeper block.
When the goal is finished, call complete_execution. Use continue_execution only when an already-started goal was paused and you are resuming it with the same goal parameters. It is not the normal next call after execute_agent.
Quick start examples: { operation: "execute_agent", params: { element_name: "code-reviewer", parameters: { objective: "Review code" } } } Next lifecycle step — use mcp_aql_create: { operation: "record_execution_step", params: { element_name: "code-reviewer", stepDescription: "Reviewed auth module", outcome: "success", findings: "Found 2 security issues" } } { operation: "complete_execution", params: { element_name: "code-reviewer", outcome: "success", summary: "Completed review" } } { operation: "abort_execution", params: { element_name: "data-collector", reason: "User requested cancellation" } } { operation: "continue_execution", params: { element_name: "rubric-qa-agent", previousStepResult: "Verified citation set", parameters: { run_dir: "/app/run", deliverable_path: "/app/run/output.docx" } } } { operation: "confirm_operation", params: { operation: "execute_agent" } } { operation: "approve_cli_permission", params: { request_id: "req-123", decision: "allow" } } { operation: "prepare_handoff", params: { element_name: "code-reviewer" } } { operation: "resume_from_handoff", params: { element_name: "code-reviewer", handoff_block: "..." } }
Discover required parameters — use mcp_aql_read: { operation: "introspect", params: { query: "operations", name: "execute_agent" } }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | Operation parameters | |
| operation | Yes | Operation name to execute | |
| operations | No | Array of operations for batch execution | |
| element_type | No | Target element type (optional) |