Skip to main content

Standalone Nexus Operations - Python SDK

SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal Python SDK support for Standalone Nexus Operations is at Pre-release.

All APIs are experimental and may be subject to backwards-incompatible changes.

Standalone Nexus Operations let you run Nexus Operation Executions independently, without being orchestrated by a Workflow. Instead of calling a Nexus Operation from within a Workflow Definition using workflow.create_nexus_client(), you execute a Standalone Nexus Operation directly from a Nexus Client created using client.create_nexus_client().

Standalone Nexus Operations use the same Nexus Service contract, Operation handlers, and Worker setup as Workflow-driven Operations — only the execution path differs. See the Nexus feature guide for details on defining a Service contract, developing Operation handlers, and registering a Service in a Worker.

This page focuses on the client-side APIs that are unique to Standalone Nexus Operations:

note

This documentation uses source code from nexus-standalone-operations.

Execute a Standalone Nexus Operation​

To execute a Standalone Nexus Operation, first create a NexusClient using client.create_nexus_client(), bound to a specific Nexus Endpoint and Service. The endpoint must be pre-created on the server. Then call start_operation() or execute_operation() from application code (for example, a starter program), not from inside a Workflow Definition.

execute_operation waits for the Operation to complete and returns the result. Both methods require id. schedule_to_close_timeout is optional and defaults to the maximum allowed by the Temporal server.

nexus_client = client.create_nexus_client(
    service=MyNexusService, endpoint=ENDPOINT_NAME
)

# Await the result of the operation immediately.
echo_result = await nexus_client.execute_operation(
    MyNexusService.echo,
    EchoInput(message="hello"),
    id=f"echo-{uuid.uuid4()}",
    schedule_to_close_timeout=timedelta(seconds=10),
)

See the full starter sample for a complete example that executes both synchronous and asynchronous Operations, gets their results, and lists and counts Operations.

Start a Standalone Nexus Operation and Wait for the Result​

start_operation returns a NexusOperationHandle. Use NexusOperationHandle.result() to wait until the Operation completes and retrieve its result. This works for both synchronous and asynchronous Operations.

# Start an operation and get a NexusOperationHandle
handle = await nexus_client.start_operation(
    MyNexusService.hello,
    HelloInput(name="World"),
    id=f"hello-{uuid.uuid4()}",
    schedule_to_close_timeout=timedelta(seconds=10),
)
# Await the result
try:
    hello_result = await handle.result()
    print(hello_result)
except err:
    print(err)
    raise

If the Operation completed successfully, the result is returned. If the Operation failed, the failure is raised as an error.

List Standalone Nexus Operations​

Use client.list_nexus_operations() to list Standalone Nexus Operation Executions that match a List Filter query. The result contains an iterator that yields operation metadata entries.

Note that list_nexus_operations is called on the base client.Client, not on the NexusClient.

query = f'Endpoint = "{ENDPOINT_NAME}"'
async for op in client.list_nexus_operations(query):
    print(
        f" OperationId: {op.operation_id},",
        f" Operation: {op.operation},",
        f" Status: {op.status.name}",
    )

The query parameter accepts List Filter syntax. For example, "Endpoint = 'my-endpoint' AND Status = 'Running'".

Count Standalone Nexus Operations​

Use client.count_nexus_operations() to count Standalone Nexus Operation Executions that match a List Filter query.

Note that count_nexus_operations is called on the base client.Client, not on the NexusClient.

query = f'Endpoint = "{ENDPOINT_NAME}"'
count = await client.count_nexus_operations(query)
print(f"Total Nexus operations: {count.count}")

Run Standalone Nexus Operations with Temporal Cloud​

The code samples referenced on this page use ClientConfig.load_client_connect_config(), so the same code works against Temporal Cloud — just configure the connection via environment variables or a TOML profile. No code changes are needed.

For full details on connecting to Temporal Cloud, including Namespace creation, Nexus Endpoint setup, certificate generation, and authentication options, see Make Nexus calls across Namespaces in Temporal Cloud and Connect to Temporal Cloud.