Nexus Python SDK - exception types
Three Nexus-specific exception classes in Python: nexusrpc.OperationError (raised to indicate operation failure per application logic, should not be retried), nexusrpc.HandlerError (raised with specific HandlerErrorType, marked retryable or non-retryable per Nexus spec), and temporalio.exceptions.NexusOperationError (raised in Workflow when operation fails, use __cause__ attribute to access cause chain). Non-retryable handler error types: BAD_REQUEST, UNAUTHENTICATED, UNAUTHORIZED, NOT_FOUND, NOT_IMPLEMENTED. Retryable types: RESOURCE_EXHAUSTED, INTERNAL, UNAVAILABLE, UPSTREAM_TIMEOUT.
Nexus Python SDK - create caller and handler namespaces
Create separate Namespaces for caller and handler using temporal operator namespace create --namespace <name>. Example: temporal operator namespace create --namespace my-target-namespace and temporal operator namespace create --namespace my-caller-namespace
Nexus Python SDK - create endpoint
Create a Nexus Endpoint to route requests from caller to handler using: temporal operator nexus endpoint create --name <name> --target-namespace <namespace> --target-task-queue <queue>
Nexus Python SDK - start development server
Start the Temporal development server with Nexus enabled using temporal server start-dev. This automatically starts the server with the Web UI and creates the default Namespace. It uses an in-memory database and should not be used for real use cases. Web UI accessible at http://localhost:8233, server available on localhost:7233.
Nexus Python SDK - Temporal Cloud namespaces
Create caller and handler Namespaces in Temporal Cloud using temporal cloud namespace create --name <namespace> --region <region> --ca-certificate-file path/to/ca.pem --retention-days <days> or tcld namespace create with similar parameters. Requires mTLS client certificates for Worker authentication.
Nexus Python SDK - Temporal Cloud endpoint creation
Create Nexus Endpoint in Temporal Cloud using: temporal cloud nexus endpoint create --name <name> --target-task-queue <queue> --target-namespace <namespace.account> --allow-namespace <caller-namespace.account> --description-file <file>. The --allow-namespace parameter builds an Endpoint allowlist of caller Namespaces. Requires Developer account role or higher and NamespaceAdmin permission on target namespace.
Nexus Python SDK - certificate generation for Temporal Cloud
Generate mTLS client certificates for Temporal Cloud using tcld: tcld gen ca --org <YOUR_ORG_NAME> --validity-period 1y --ca-cert ca.pem --ca-key ca.key. Install latest tcld version on macOS with: brew install temporalio/brew/tcld
Standalone Nexus Operations require Python SDK 1.30.0 or above
Standalone Nexus Operations require Python SDK version 1.30.0 or above. All APIs are experimental and may be subject to backwards-incompatible changes.
execute_operation() Python example
nexus_client = client.create_nexus_client(
service=MyNexusService, endpoint=ENDPOINT_NAME
)
echo_result = await nexus_client.execute_operation(
MyNexusService.echo,
EchoInput(message="hello"),
id=f"echo-{uuid.uuid4()}",
schedule_to_close_timeout=timedelta(seconds=10),
)
start_operation() and get result Python example
handle = await nexus_client.start_operation(
MyNexusService.hello,
HelloInput(name="World"),
id=f"hello-{uuid.uuid4()}",
schedule_to_close_timeout=timedelta(seconds=10),
)
try:
hello_result = await handle.result()
print(hello_result)
except err:
print(err)
raise
list_nexus_operations() Python example
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}",
)
count_nexus_operations() Python example
query = f'Endpoint = "{ENDPOINT_NAME}"'
count = await client.count_nexus_operations(query)
print(f"Total Nexus operations: {count.count}")
Pre-release dev server enables Standalone Nexus Operations by default
The Pre-release dev server enables Standalone Nexus Operations by default — no dynamic config is required. Start it with the caller and handler Namespaces pre-created.
Temporal CLI get Nexus Operation result
./temporal nexus operation result --namespace my-caller-namespace --operation-id my-echo-op
Temporal CLI list Nexus Operations
./temporal nexus operation list --namespace my-caller-namespace --query 'Endpoint = "my-nexus-endpoint"'
Temporal CLI count Nexus Operations
./temporal nexus operation count --namespace my-caller-namespace --query 'Endpoint = "my-nexus-endpoint"'
Standalone Nexus Operations work with Temporal Cloud
The same code for Standalone Nexus Operations works against Temporal Cloud — just configure the connection via environment variables or a TOML profile using ClientConfig.load_client_connect_config(). No code changes are needed.
Define Nexus Service contract with @nexusrpc.service decorator
Create a Nexus Service by defining a dataclass for input and a service class decorated with @nexusrpc.service. The service class declares typed operations using nexusrpc.Operation[InputType, OutputType]. For example, a service can have an operation say_hello: nexusrpc.Operation[MyInput, str] where MyInput is a dataclass containing the operation input and str is the output type. This establishes the contract between implementation and callers and provides type safety when invoking Nexus Operations.
Python SDK Nexus prerequisites
Before building a Nexus Service in Python, complete the Python SDK Quickstart. You should have activities.py, workflows.py, worker.py, and starter.py from that guide.
Nexus imports in Python SDK
Use nexusrpc and nexusrpc.handler for defining services and handlers. Use temporalio.nexus for decorators and context types like nexus.workflow_run_operation and nexus.WorkflowRunOperationContext. Use workflow.create_nexus_client() from the temporalio.workflow module to create Nexus clients in Workflows.
Rust SDK Nexus documentation location
Temporal Nexus documentation for the Rust SDK is located at the Rust SDK Nexus section, with a feature guide available at /develop/rust/nexus/feature-guide.
Call Nexus Operation from Rust Workflow
Use ctx.start_nexus_operation() to start a Nexus operation from a Workflow. This method accepts NexusOperationOptions and returns a started operation that can be awaited for results.
NexusOperationOptions parameters
NexusOperationOptions builder accepts the following parameters: endpoint (string, the Nexus endpoint name), service (string, the service name), operation (string, the operation name), input (optional payload), start_to_close_timeout (Duration, how long the operation can run), and schedule_to_close_timeout (Duration, how long the caller waits for the operation to complete).
Rust Nexus Operation example with error handling
Here is a complete example of calling a Nexus operation from a Rust workflow:
```rust
use std::time::Duration;
use temporalio_common::protos::coresdk::AsJsonPayloadExt;
use temporalio_macros::{workflow, workflow_methods};
use temporalio_sdk::{
ApplicationFailure, NexusOperationOptions, WorkflowContext, WorkflowContextView,
WorkflowResult,
};
#[workflow]
pub struct GreetingWorkflow {
pub name: String,
}
#[workflow_methods]
impl GreetingWorkflow {
#[init]
fn new(_ctx: &WorkflowContextView, name: String) -> Self {
Self { name }
}
#[run]
pub async fn run(ctx: &mut WorkflowContext<Self>) -> WorkflowResult<String> {
let name = ctx.state(|s| s.name.clone());
let nexus_started = ctx
.start_nexus_operation(
NexusOperationOptions::builder()
.endpoint("my-endpoint")
.service("my-service")
.operation("my-operation")
.input(name.as_json_payload().map_err(ApplicationFailure::new)?)
.start_to_close_timeout(Duration::from_secs(10))
.build(),
)
.await;
let nexus_started = match nexus_started {
Ok(started) => started,
Err(failure) => return Ok(format!("Nexus start failed: {failure:?}")),
};
let nexus_result = nexus_started.result().await;
println!("Nexus result: {:?}", nexus_result);
Ok(format!("nexus result: {:?}", nexus_result))
}
}
```
This example shows starting a Nexus operation with payload serialization, handling start failures, and awaiting the result.
Nexus Operation result retrieval
After starting a Nexus operation with start_nexus_operation(), call result() on the returned started operation and await it to get the operation result.
Define Nexus Service contract in TypeScript
Use nexus.service() to declare a named service and nexus.operation<I, O>() to define a typed operation with input and output types. This establishes the contract between implementation and callers, providing type safety when invoking Nexus Operations.
Create caller Namespace and Nexus Endpoint
Create a caller Namespace using 'temporal operator namespace create --namespace <namespace-name>'. Create a Nexus Endpoint using 'temporal operator nexus endpoint create --name <endpoint-name> --target-namespace <namespace> --target-task-queue <task-queue>'. The endpoint name in the CLI command must match the NEXUS_ENDPOINT variable used in the caller Workflow.
Nexus TypeScript quickstart example: complete service definition
import * as nexus from 'nexus-rpc';
export interface MyInput {
name: string;
}
export const sayHelloService = nexus.service('say-hello', {
sayHello: nexus.operation<MyInput, string>(),
});
Nexus Workflow Event history tracking
When invoking a Nexus Operation from a Workflow, the Web UI displays NexusOperationScheduled, NexusOperationStarted, and NexusOperationCompleted events in the Workflow's Event history.
Temporal Nexus TypeScript SDK documentation structure
The Temporal Nexus documentation for TypeScript SDK includes three main sections: Quickstart, Feature guide, and Standalone Operations.
Standalone Nexus Operations require TypeScript SDK v1.20.2+
Standalone Nexus Operations require TypeScript SDK version 1.20.2 or above. All APIs are experimental and may be subject to backwards-incompatible changes.
Execute Standalone Nexus Operation without Workflow
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 @temporalio/workflow's createNexusServiceClient(), you execute a Standalone Nexus Operation directly from a Nexus service client created on the Temporal Client using client.nexus.createServiceClient().
Pre-release Temporal CLI required for Standalone Nexus Operations
Standalone Nexus Operations require a special Pre-release build of the Temporal CLI, not the standard brew install build. The temporal nexus operation commands require this Pre-release version.
Start dev server with Standalone Nexus Operations support
The Pre-release dev server enables Standalone Nexus Operations by default with no dynamic config required. Start it with: ./temporal server start-dev --namespace my-caller-namespace --namespace my-handler-namespace
Create Nexus Endpoint for handler Namespace
Create a Nexus Endpoint that routes to the handler Namespace and the Worker's Task Queue using: ./temporal operator nexus endpoint create --name my-nexus-endpoint --target-namespace my-handler-namespace --target-task-queue nexus-handler-queue
Standalone Nexus Operations use same contract as Workflow-driven Operations
Standalone Nexus Operations use the same Nexus Service contract, Operation handlers, and Worker setup as Workflow-driven Operations. Only the execution path differs.
Same code works for Temporal Cloud with loadClientConnectConfig()
Code using loadClientConnectConfig() from @temporalio/envconfig works against Temporal Cloud without changes. Configure the connection via environment variables or a TOML profile.