Using test mode¶

Test mode lets you inspect and validate workflows before running them in production. When Test mode is enabled, OPAQUE provides detailed execution traces that show how data moves through each node and how tools are invoked at runtime.

This guide explains when to use Test mode, how to run workflows in Test mode, and how to use tracing features to understand execution behavior before promoting a workflow to production.

When to use Test mode¶

Use Test mode when you want to:

• Verify that a workflow executes as expected end-to-end
• Inspect intermediate node inputs and outputs
• Debug agent behavior, tool invocation, or branching logic
• Understand how data flows through complex or agentic workflows

Test mode is especially useful for:

• Agent-based workflows, where behavior depends on prompts and tool selection
• Tool-enabled workflows, where external systems are invoked dynamically
• Retrieval-augmented pipelines, where intermediate context and retrieved data matter

Test mode is designed for development, validation, and confidence-building, not for production traffic.

Enable Test mode¶

Test mode must be enabled while your workflow is in Draft, before requesting approval.

To enable Test mode:

1. Open your workflow in Draft.
2. Toggle Test mode on.
3. Request approval, just as you would for a standard workflow.

Once approved, the workflow is ready to be launched in Test mode.

Launch a workflow in Test mode¶

After approval:

1. Click Launch workflow.
2. The workflow status changes from Ready to launch to Starting to Testing.
3. Switch to the Execution tab.

In Test mode, the Execution tab lets you:

• Enter inputs to trigger the workflow.
• See the workflow structure as connected nodes from Start to End.
• Inspect execution details and trace logs for each run.

If your workflow uses runtime context mapping via the MCP Tool, the Execution tab also includes a Request context section. This lets you provide runtime values—such as user roles or identifiers—that are mapped to API parameters defined in the MCP tool configuration.

These values are injected into MCP API calls at runtime based on the context mapping defined in the workflow. This makes it possible to test how a workflow behaves for different users or execution contexts without changing the workflow definition itself.

For workflows that do not use context mapping, this section is not shown.

Run and inspect a workflow¶

To trigger the workflow:

1. Enter a prompt in the Prompt field.
2. Click Run workflow.
3. Refer to the Workflow overview and the Output and Trace tabs at the bottom of the page to inspect execution details for the run.

Workflow overview and run status¶

The Workflow overview shows your workflow structure as connected nodes from Start to End. Use this view to see which nodes are involved in the run and to select individual nodes for inspection.

For agent-based workflows, the Workflow overview includes additional visual indicators:

• The LLM used by the agent appears as an icon in the top-left corner of the agent node (for example, an OpenAI icon).
• Tools connected to the agent are shown by their icons in a separate box below the agent node.

These indicators reflect how the agent is configured and which tools it can invoke during execution.

While the workflow is running, a run status display appears in the top right of the Workflow overview section. This display provides a live summary about the current run, including:

• The elapsed time
• The currently running node or nodes
• Any recent tool call activity associated with those running nodes

This information helps you understand where the workflow is spending time and which parts of it are active at a given moment.

Inspect individual nodes¶

To inspect what happened at a specific step, click a node in the Workflow overview. This opens the trace dialog for that node.

The trace dialog shows the trace information captured for the selected node during the run. Depending on the node type and what happened during execution, you’ll see:

• Inputs the node received (for example, the prompt for an Agent node), along with trace identifiers
• Elapsed time and status for the node’s execution
• Tool traces (if the node invoked tools), showing each tool call with its elapsed time and status (expand a tool trace to view full details)
• Outputs produced by the node
• The full node trace JSON, which includes the complete trace record for that node (including end time, execution time, and additional trace fields)

Use the trace dialog to validate how a node executed for a given run. This is useful for checking retrieved context, reviewing prompt construction, and inspecting the inputs and results of any tool calls made by the node.

Review run-level results¶

After the run completes, use the Output and Trace tabs at the bottom of the page to review the full results.

The Output tab shows the final result returned by the workflow.

The Trace tab shows the full execution trace for the run, including workflow-level metadata and per-node trace details.

If you want to share a complete record of the run, use the Trace tab. If you want to focus on a specific step, use the Workflow overview and trace dialog.

Interpreting trace logs¶

Trace logs help you understand how data flows through your workflow—what inputs each node receives, what outputs it produces, and how those values change across steps.

Timing information (such as execution duration) is often less important for correctness, but it can be useful when comparing different configurations—for example, evaluating the performance impact of different LLM models or retriever settings.

Trace visibility continues to evolve. While the trace view now includes node-level timing and tool traces, future improvements will provide even more detailed insight into agent execution and tool invocation.

Iterating in Test mode¶

Testing is typically an iterative process:

1. Run the workflow and inspect results.
2. If changes are needed:
   • Click Actions → Stop workflow.
   • Select Actions → Return to draft.
3. Modify the workflow on the canvas.
4. Request approval again.
5. Launch in Test mode and re-run.

For complex workflows—especially agentic or tool-driven ones—this cycle may repeat several times as you refine behavior and validate results.

Exit Test mode and prepare for production¶

When you are satisfied with the workflow:

1. Click Actions → Stop workflow.
2. Select Actions → Return to draft.
3. Toggle Test mode off.
4. Request approval again.
5. Launch the workflow in standard execution mode.

At this point, the workflow behaves like a production service and no longer exposes trace logs by default.

What’s next¶

Test mode provides deep visibility into workflow execution, making it essential for debugging and validation—especially for agentic and tool-driven workflows.

To integrate workflows into applications, automate executions, or request attestation reports, you’ll use the OPAQUE SDK. For details, see Step 4 in Get started.