Skip to content

Invoking workflows

Once a workflow is launched, you can invoke it programmatically from any application using the OPAQUE Python SDK. Invoking a workflow sends an input request to the running service and returns a structured response for that execution.

This guide assumes your workflow is already running. If you haven't launched one yet, see Get started.

Before you begin

Before invoking a workflow, gather the following information:

  • API key: Click API key in the left-hand navigation to retrieve your API key.
  • Workflow service UUID and domain: Click the icon above your canvas to open the Trigger the SDK drawer.
  • OPAQUE REST URL: The API domain configured during your deployment. It follows the format https://api.{your-subdomain}/v2.5—the same subdomain as your OPAQUE frontend URL, with app replaced by api and /v2.5 appended. If you're unsure, ask your workspace admin.

Invoke the workflow

The following script sets the required environment variables, initializes a connection to your workflow, and submits a request.

# Import the standard libraries used
import os
import uuid

from opaque.workflow import WorkflowService

# Set the environment variables used by the SDK
os.environ["OPAQUE_DATAPLANE_DOMAIN"]="<your_workflow_service_domain>"
os.environ["OPAQUE_REST_URL"]="app.<app_subdomain>"
os.environ["OPAQUE_API_KEY"] = "<your_api_key_here>"

# Define the UUID of the workflow you want to call
WORKFLOW_SERVICE_UUID = "<your_UUID>"

# Create a workflow client using that UUID
workflow_service = WorkflowService(workflow_uuid=uuid.UUID(WORKFLOW_SERVICE_UUID))

# Define the input payload — this must match the expected input schema 
# for the nodes connected to the start node in your workflow.
rag_request = {"prompt": "Is the claim eligible for reimbursement?"}

# Submit the request and capture the response
workflow_response = workflow_service.submit(rag_request)

# Print the result to the terminal
print(workflow_response)

When you submit a request, OPAQUE runs your input through the full workflow—from Start to End—and returns a structured response based on the final connected node(s). In most cases, that means getting a model-generated output or decision.

For example, if the last node before the End node is a language model, your response might look like:

{'output': "Yes, the claim is eligible for reimbursement because..."}

This response is returned as a dictionary and printed to your terminal when using the example script.

You can reuse this same pattern to trigger any approved workflow you've built. Just update the UUID and adjust your input payload to match the schema expected by the Start node and its connected nodes.

Store attestation results

All communication between the SDK and a workflow occurs over aTLS. As a result, the SDK only submits your request to the workflow if the workflow successfully passes attestation.

If you want the SDK to store attestation reports generated during the establishment of an aTLS connection, configure the WorkflowService class as follows:

workflow_service = WorkflowService(
    workflow_uuid=uuid.UUID(WORKFLOW_SERVICE_UUID),

    # Save attestation reports in the given directory (optional)
    report_path="/home/your_user/workflow_reports",

    # Save appraisal logs that explain how the report was verified (optional)
    appraisal_path="/home/your_user/workflow_reports",
    )

Save reports and appraisal logs in a shared location accessible to those responsible for verification, such as developers, auditors, or compliance teams.

Note that reports are generated during the establishment of aTLS connections, not on a per-request basis. aTLS connections are pooled, so you may see multiple invocations that result in no new report, as the underlying connection is recycled.

What's next