Skip to main content

Execution Operations Playbook

Once AxonFlow is running real multi-agent workflows, execution data stops being just a debugging aid. It becomes part of day-two operations. Platform teams need to know which workflow is stuck, which step failed, whether a policy blocked the run, whether a reviewer is holding it up, and how to prove what happened afterward.

This playbook explains how teams usually operate that execution surface in practice.

The Three Main Execution Surfaces​

AxonFlow gives platform teams three complementary ways to work with executions:

  • the Execution Viewer for visual inspection
  • axonctl executions for terminal-based list, get, replay, and export workflows
  • execution APIs for application dashboards, platform tooling, and automation

The core API families are:

  • replay and export APIs under /api/v1/executions
  • unified status and streaming APIs under /api/v1/unified/executions

The right operating model is usually to use the UI for triage, the CLI for incident handling, and the APIs for automation.

What Platform Teams Need To Watch​

The most useful execution signals are:

  • workflow status and duration
  • blocked or approval-pending steps
  • provider failures and retry loops
  • connector latency and connector error spikes
  • token and cost growth by workflow or provider
  • policy decisions and block reasons (redaction details are available through audit logs and execution exports, not directly in execution status)

That is why execution operations usually sit next to Grafana Dashboard, Token Usage, and WCP Tracing and Audit.

The Standard Incident Loop​

When a workflow misbehaves, most strong teams follow the same sequence.

1. Find The Run​

Start with one of:

  • GET /api/v1/executions
  • GET /api/v1/unified/executions
  • axonctl executions list
  • the execution viewer UI

Use filters such as status, workflow ID, time range, or execution type to narrow the search quickly.

2. Inspect The Timeline​

Then inspect:

  • GET /api/v1/executions/{id}
  • GET /api/v1/executions/{id}/steps
  • GET /api/v1/executions/{id}/timeline

This is where you answer:

  • which step failed or stalled?
  • did a policy block it?
  • did a step gate return require_approval, putting the step into approval status?
  • did a provider fail?
  • did a connector return bad or redacted data?

3. Decide Which Failure Class You Are In​

In practice, most incidents fall into one of five buckets:

  • policy block: the control plane is behaving correctly, but the request violated a rule
  • approval pending: the run is waiting on a reviewer, not on infrastructure
  • provider failure: upstream LLM or routing behavior is degraded
  • connector failure: the orchestration is healthy, but the integration target is not
  • workflow logic bug: the agent or orchestrator state machine is wrong

That classification matters because the right next action is different in each case.

4. Take The Correct Action​

Typical actions are:

  • approve or reject the blocked step if the workflow is waiting for review
  • cancel a long-running or unsafe execution through POST /api/v1/unified/executions/{id}/cancel
  • replay or export the run for deeper debugging
  • re-run the workflow from the application side once the upstream issue is fixed

The execution control plane is strongest when teams use it to shorten mean time to understanding, not only mean time to restart.

Replay And Export​

Replay and export are what make the execution surface operationally useful rather than just visually interesting.

Use replay when you need to understand:

  • how a run reached a bad state
  • which step changed the trajectory
  • whether the issue is deterministic

Use export when you need:

  • audit evidence
  • a debugging artifact to share with another engineer
  • a review package for compliance, governance, or product stakeholders

The most common tools are:

  • axonctl executions replay <id>
  • axonctl executions export <id>
  • GET /api/v1/executions/{id}/export

API Filters and Portal Views​

Replay list endpoints support filters such as:

  • limit
  • offset
  • status
  • workflow_id
  • start_time
  • end_time

Unified execution list endpoints support:

  • limit
  • offset
  • execution_type
  • status

The enterprise portal uses unified execution views to show both map_plan and wcp_workflow runs in one place. Common status filters include pending, running, completed, failed, and aborted.

Approval-Aware Execution Handling​

Approval-driven workflows need a slightly different operating loop. A pending execution is not always broken. It may be doing exactly what the governance design intended.

Platform teams should distinguish between:

  • a workflow waiting normally in an approval state
  • a queue that is backing up because reviewer operations are weak
  • a workflow that should never have required approval in the first place

That is why execution operations and Approvals And Exception Handling Patterns belong together.

Code Governance Metrics​

If your deployment uses governed code generation, there is a dedicated metrics surface:

GET /api/v1/code-governance/metrics

That returns tenant-scoped aggregates such as:

  • total PRs
  • open, merged, and closed PR counts
  • total generated files
  • total secrets detected
  • total unsafe patterns
  • first and last PR timestamps

This is useful when internal platform teams need to quantify how AI-generated code is behaving in production engineering workflows.

What Good Teams Automate​

Once the execution surface becomes important, teams usually automate:

  • live dashboards based on /api/v1/unified/executions/{id}/stream
  • alerts for abnormal failure or pending-approval spikes
  • exports for regulated review workflows
  • links from app incidents directly into execution detail pages

That is the point where AxonFlow starts to behave like a control plane platform rather than a single-service runtime.

A Practical Maturity Curve​

  • early stage: engineers use the execution viewer and axonctl directly
  • shared-team stage: dashboards and alerts are built around the unified execution APIs
  • enterprise stage: execution operations are combined with approvals, audit exports, portal workflows, and broader governance processes

Each stage builds on the same execution primitives. The difference is how much review, triage, and automation workflow grows around them.

Enterprise Execution Viewer​

The enterprise portal execution view gives platform teams a single place to inspect MAP plans and WCP workflow runs after they have started.

The enterprise execution view is where platform teams inspect real workflow runs after they have been planned or started. It is the portal surface for answering questions like:

  • Which MAP plans are failing?
  • Which WCP workflows are waiting for approval?
  • Which step introduced cost, latency, or policy friction?

The page is backed by the unified execution APIs:

  • GET /api/v1/unified/executions
  • GET /api/v1/unified/executions/{executionId}

These session-authenticated routes give portal users one place to inspect both multi-agent planning and workflow-control execution histories.

What The Page Shows​

The current execution model includes:

  • execution ID
  • execution type
  • name and source
  • status
  • current step index
  • total steps
  • progress percentage
  • start and completion timestamps
  • estimated and actual cost
  • per-step detail when a run is expanded

The portal currently exposes execution types:

  • map_plan
  • wcp_workflow

And it supports common status filters such as:

  • pending
  • running
  • completed
  • failed
  • aborted

That makes the page useful for both active incident response and slower-moving operational review.

Why This Page Matters​

Senior engineers usually do not want a generic “runs” page. They want a place where execution state is tied back to the control plane.

That means an execution page is only useful if it helps answer:

  • what stage the workflow reached
  • whether a step failed, blocked, or was skipped
  • whether human approval was required
  • whether cost escalated on a particular branch or tool call

The enterprise portal is built to surface exactly that kind of execution record.

  1. filter by status or execution type to narrow the search space
  2. open one execution and inspect the step timeline
  3. correlate blocked or approval states with Approvals Queue
  4. correlate suspicious policy behavior with Policy Management
  5. move to Usage & Analytics if the issue is cost or latency across a wider time period

MAP And WCP In The Same View​

This page is especially valuable because enterprise teams often operate more than one orchestration style at once. A team may use MAP for dynamic planning and WCP for deterministic workflow execution, yet still want one operational view of enterprise runs.

That is why the portal uses a unified execution surface instead of making platform teams jump between unrelated tools.

What This Page Is Not​

This page is not the authoring interface for public workflows or a replacement for the community Orchestration Overview. It is the enterprise operations layer above those systems.

Think of it as the place where platform teams confirm that the system is behaving as intended after a workflow definition, routing policy, or approval rule has already been deployed.

Last updated on