plugins-guide

title

Plugins guide

sidebar_label

Plugins guide

description

Best practices for creating plugins for AI Agents

toc_max_heading_level

hide_table_of_contents

false

keywords

ai agents

best practices

Plugins

A Plugin is an abstraction that allows you to customize any aspect of your Temporal Worker setup, including registering Workflow and Activity definitions, modifying worker and client options, and more. Using plugins, you can build reusable open-source libraries or build add-ons for engineers at your company.

This guide will teach you how to create plugins and give platform engineers general guidance on using and managing Temporal's primitives.

Here are some common use cases for plugins:

AI Agent SDKs
Observability, tracing, or logging middleware
Adding reliable built-in functionality such as LLM calls, messaging systems, and payments infrastructure
Encryption or compliance middleware

How to build a Plugin

The recommended way to start building plugins is with a SimplePlugin. This abstraction will tackle the vast majority of plugins people want to write.

Example Plugins

If you prefer to learn by getting hands-on with code, check out some existing plugins.

Temporal's Python SDK ships with an OpenAI Agents SDK plugin
Temporal client and Worker plugin for Pydantic AI
Temporal's TypeScript SDK ships with an OpenTelemetry Plugin

What you can provide to users in a plugin

There are a number of features you can give your users with a plugin. Here's a short list of some of the things you can do.

Built-in Activities
Workflow-friendly libraries
Built-in Workflows
Built-in Nexus Operations
Custom Data Converters
Interceptors
Context Propagators

Built-in Activity

You can provide built-in Activities in a Plugin for users to call from their Workflows. Check out the Activities page for more details on how they work.

Refer to the best practices for creating Activities when you are making Activity plugins.

Timeouts and retry policies

Temporal's Activity retry mechanism gives applications the benefits of Durable Execution. See the Activity retry policy explanation for more details.

{/* SNIPSTART python-plugin-activity */} [features/snippets/plugins/plugins.py](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.py) ```py @activity.defn async def some_activity() -> None: return None

plugin = SimplePlugin("organization.PluginName", activities=[some_activity])

    {/* SNIPEND */}
  </SdkTabs.Python>
  <SdkTabs.Go>
    {/* SNIPSTART go-plugin-activity */}
[features/snippets/plugins/plugins.go](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.go)
```go
func SomeActivity(ctx context.Context) error {
	// Activity implementation
	return nil
}

func createActivityPlugin() (*temporal.SimplePlugin, error) {
	return temporal.NewSimplePlugin(temporal.SimplePluginOptions{
		Name: "organization.PluginName",
		RunContextBefore: func(ctx context.Context, options temporal.SimplePluginRunContextBeforeOptions) error {
			options.Registry.RegisterActivityWithOptions(
				SomeActivity,
				activity.RegisterOptions{Name: "SomeActivity"},
			)
			return nil
		},
	})
}

{/* SNIPEND */}

</SdkTabs.Go> <SdkTabs.Java> {/* SNIPSTART java-plugin-activity */} features/snippets/plugins/plugins.java

@ActivityInterface
public interface SomeActivity {
  @ActivityMethod
  void someActivity();
}

public class SomeActivityImpl implements SomeActivity {
  @Override
  public void someActivity() {
    // Activity implementation
  }
}

SimplePlugin activityPlugin =
    SimplePlugin.newBuilder("organization.PluginName")
        .registerActivitiesImplementations(new SomeActivityImpl())
        .build();

{/* SNIPEND */}

</SdkTabs.Java> <SdkTabs.TypeScript> {/* SNIPSTART typescript-plugins-activity */} features/snippets/plugins/plugins.ts

const activity = async () => 'activity';
const plugin = new SimplePlugin({
  name: 'organization.PluginName',
  activities: {
    pluginActivity: activity,
  },
});

{/* SNIPEND */}

</SdkTabs.TypeScript> <SdkTabs.DotNet> {/* SNIPSTART dotnet-plugins-activity */} features/snippets/plugins/plugins.cs

[Activity]
static void SomeActivity() => throw new NotImplementedException();

SimplePlugin activityPlugin = new SimplePlugin(
    "organization.PluginName",
    new SimplePluginOptions() { }.AddActivity(SomeActivity));

{/* SNIPEND */}

</SdkTabs.DotNet> <SdkTabs.Ruby> {/* SNIPSTART ruby-plugin-activity */} features/snippets/plugins/plugins.rb

def some_activity
  # Activity implementation
end

plugin = Temporalio::SimplePlugin.new(
  name: 'organization.PluginName',
  activities: [method(:some_activity)]
)

{/* SNIPEND */}

</SdkTabs.Ruby>

Workflow-friendly libraries

You can provide a library for use within a Workflow if you'd like to abstract away some Temporal-specific details for your users. Your library will call elements you include in your Plugin such as Activities, Child Workflows, Signals, Updates, Queries, Nexus Operations, Interceptors, Data Converters, and any other code as long as it follows these requirements:

Any code that runs in the Workflow context must be deterministic, meaning it produces the same commands and results when replayed. For example, don't call system time APIs, generate random values, or perform direct network and file I/O from Workflow-context code; move that work to Activities or Nexus Operations.
See observability to avoid duplicating observation side effects when Workflows replay.
Put other side effects inside of Activities or Local Activities. This helps your Workflow handle being restarted, resumed, or executed in a different process from where it originally began without losing correctness or state consistency.
See testing your Plugin to write tests that check for issues with side effects.
It should run quickly since it may be replayed many times during a long Workflow execution. More expensive code should go in Activities or Nexus Operations.

A Plugin should allow a user to decompose their Workflows into Activities, as well as Child Workflows and Nexus Calls when needed. This gives users granular control through retries and timeouts, debuggability through the Temporal UI, operability with resets, pauses, and cancels, memoization for efficiency and resumability, and scalability using task queues and Workers.

Users use Workflows for:

Orchestration and decision-making
Interactivity via message-passing
Tracing and observability

Making changes to your library

Your users may want to keep their Workflows running across deployments of their Worker code. If their deployment includes a new version of your Plugin, changes to your Plugin could break Workflow code that started before the new version was deployed. This can be due to non-deterministic behavior from code changes in your Plugin.

See testing to see how to test for this. And, if you make substantive changes, you need to use patching.

Example of a Workflow library that uses a Plugin in Python

Built-in Workflows

You can provide a built-in Workflow in a SimplePlugin. It’s callable as a Child Workflow or standalone. When you want to provide a piece of functionality that's more complex than an Activity, you can:

Use a Workflow Library that runs directly in the end user’s Workflow
Add a Child Workflow

Consider adding a Child Workflow when one or more of these conditions applies:

That child should outlive the parent.
The Workflow Event History would otherwise not scale in parent Workflows.
When you want a separate Workflow ID for the child so that it can be operated independently of the parent's state (canceled, terminated, paused).

Any Workflow can be run as a standalone Workflow or as a Child Workflow, so registering a Child Workflow in a SimplePlugin is the same as registering any Workflow.

{/* SNIPSTART python-plugin-workflow */} [features/snippets/plugins/plugins.py](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.py) ```py @workflow.defn class HelloWorkflow: @workflow.run async def run(self, name: str) -> str: return f"Hello, {name}!"

plugin = SimplePlugin("organization.PluginName", workflows=[HelloWorkflow])

    {/* SNIPEND */}
  </SdkTabs.Python>
  <SdkTabs.Go>
    {/* SNIPSTART go-plugin-workflow */}
[features/snippets/plugins/plugins.go](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.go)
```go
func HelloWorkflow(ctx workflow.Context, name string) (string, error) {
	return "Hello, " + name + "!", nil
}

func createWorkflowPlugin() (*temporal.SimplePlugin, error) {
	return temporal.NewSimplePlugin(temporal.SimplePluginOptions{
		Name: "organization.PluginName",
		RunContextBefore: func(ctx context.Context, options temporal.SimplePluginRunContextBeforeOptions) error {
			options.Registry.RegisterWorkflowWithOptions(
				HelloWorkflow,
				workflow.RegisterOptions{Name: "HelloWorkflow"},
			)
			return nil
		},
	})
}

{/* SNIPEND */}

</SdkTabs.Go> <SdkTabs.Java> {/* SNIPSTART java-plugin-workflow */} features/snippets/plugins/plugins.java

@WorkflowInterface
public interface HelloWorkflow {
  @WorkflowMethod
  String run(String name);
}

public static class HelloWorkflowImpl implements HelloWorkflow {
  @Override
  public String run(String name) {
    return "Hello, " + name + "!";
  }
}

SimplePlugin workflowPlugin =
    SimplePlugin.newBuilder("organization.PluginName")
        .registerWorkflowImplementationTypes(HelloWorkflowImpl.class)
        .build();

{/* SNIPEND */}

</SdkTabs.Java> <SdkTabs.DotNet> {/* SNIPSTART dotnet-plugins-workflow */} features/snippets/plugins/plugins.cs

[Workflow]
class SimpleWorkflow
{
    [WorkflowRun]
    public Task<string> RunAsync(string name) => Task.FromResult($"Hello, {name}!");
}

SimplePlugin workflowPlugin = new SimplePlugin(
    "organization.PluginName",
    new SimplePluginOptions() { }.AddWorkflow<SimpleWorkflow>());

{/* SNIPEND */}

</SdkTabs.DotNet> <SdkTabs.Ruby> {/* SNIPSTART ruby-plugin-workflow */} features/snippets/plugins/plugins.rb

class HelloWorkflow < Temporalio::Workflow::Definition
  def execute(name)
    "Hello, #{name}!"
  end
end

plugin = Temporalio::SimplePlugin.new(
  name: 'organization.PluginName',
  workflows: [HelloWorkflow]
)

{/* SNIPEND */}

</SdkTabs.Ruby>

Built-in Nexus Operations

Nexus calls are used from Workflows similar to Activities and you can learn more about Temporal Nexus. Like Activities, Nexus operation inputs and return values must be serializable.

{/* SNIPSTART python-plugin-nexus */} [features/snippets/plugins/plugins.py](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.py) ```py @nexusrpc.service class WeatherService: get_weather_nexus_operation: nexusrpc.Operation[WeatherInput, Weather]

@nexusrpc.handler.service_handler(service=WeatherService) class WeatherServiceHandler: @nexusrpc.handler.sync_operation async def get_weather_nexus_operation( self, ctx: nexusrpc.handler.StartOperationContext, input: WeatherInput ) -> Weather: return Weather( city=input.city, temperature_range="14-20C", conditions="Sunny with wind.", )

plugin = SimplePlugin( "organization.PluginName", nexus_service_handlers=[WeatherServiceHandler()] )

    {/* SNIPEND */}

  </SdkTabs.Python>
  <SdkTabs.Go>
    {/* SNIPSTART go-plugin-nexus */}
[features/snippets/plugins/plugins.go](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.go)
```go
type WeatherInput struct {
	City string `json:"city"`
}

type Weather struct {
	City             string `json:"city"`
	TemperatureRange string `json:"temperatureRange"`
	Conditions       string `json:"conditions"`
}

var WeatherService = nexus.NewService("weather-service")

var GetWeatherOperation = nexus.NewSyncOperation(
	"get-weather",
	func(ctx context.Context, input WeatherInput, options nexus.StartOperationOptions) (Weather, error) {
		return Weather{
			City:             input.City,
			TemperatureRange: "14-20C",
			Conditions:       "Sunny with wind.",
		}, nil
	},
)

func createNexusPlugin() (*temporal.SimplePlugin, error) {
	return temporal.NewSimplePlugin(temporal.SimplePluginOptions{
		Name: "organization.PluginName",
		RunContextBefore: func(ctx context.Context, options temporal.SimplePluginRunContextBeforeOptions) error {
			options.Registry.RegisterNexusService(WeatherService)
			return nil
		},
	})
}

{/* SNIPEND */}

</SdkTabs.Go> <SdkTabs.Java> {/* SNIPSTART java-plugin-nexus */} features/snippets/plugins/plugins.java

// Example Nexus service implementation
public class WeatherService {
  public Weather getWeather(WeatherInput input) {
    return new Weather(input.getCity(), "14-20C", "Sunny with wind.");
  }
}

public static class Weather {
  private final String city;
  private final String temperatureRange;
  private final String conditions;

  public Weather(String city, String temperatureRange, String conditions) {
    this.city = city;
    this.temperatureRange = temperatureRange;
    this.conditions = conditions;
  }

  // Getters...
}

public static class WeatherInput {
  private final String city;

  public WeatherInput(String city) {
    this.city = city;
  }

  public String getCity() {
    return city;
  }
}

SimplePlugin nexusPlugin =
    SimplePlugin.newBuilder("organization.PluginName")
        .registerNexusServiceImplementation(new WeatherService())
        .build();

{/* SNIPEND */}

</SdkTabs.Java> <SdkTabs.TypeScript> {/* SNIPSTART typescript-plugins-nexus */} features/snippets/plugins/plugins.ts

const testServiceHandler = nexus.serviceHandler(
  nexus.service('testService', {
    testSyncOp: nexus.operation<string, string>(),
  }),
  {
    async testSyncOp(_, input) {
      return input;
    },
  },
);
const plugin = new SimplePlugin({
  name: 'organization.PluginName',
  nexusServices: [testServiceHandler],
});

{/* SNIPEND */}

</SdkTabs.TypeScript> <SdkTabs.DotNet> {/* SNIPSTART dotnet-plugins-nexus */} features/snippets/plugins/plugins.cs

[NexusService]
public interface IStringService
{
    [NexusOperation]
    string DoSomething(string name);
}

[NexusServiceHandler(typeof(IStringService))]
public class HandlerFactoryStringService
{
    private readonly Func<IOperationHandler<string, string>> handlerFactory;

    public HandlerFactoryStringService(Func<IOperationHandler<string, string>> handlerFactory) =>
        this.handlerFactory = handlerFactory;

    [NexusOperationHandler]
    public IOperationHandler<string, string> DoSomething() => handlerFactory();
}

SimplePlugin nexusPlugin = new SimplePlugin(
    "organization.PluginName",
    new SimplePluginOptions() { }.AddNexusService(new HandlerFactoryStringService(() =>
        OperationHandler.Sync<string, string>((ctx, name) => $"Hello, {name}")))
);

{/* SNIPEND */}

</SdkTabs.DotNet>

Custom Data Converters

A custom Data Converter can alter data formats or provide compression or encryption.

Note that you can use an existing Data Converter such as, in Python, PydanticPayloadConverter in your Plugin.

{/* SNIPSTART python-plugin-converter */} [features/snippets/plugins/plugins.py](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.py) ```py def set_converter(converter: DataConverter | None) -> DataConverter: if converter is None or converter == DataConverter.default: return pydantic_data_converter # Should consider interactions with other plugins, # as this will override the data converter. # This may mean failing, warning, or something else return converter

plugin = SimplePlugin("organization.PluginName", data_converter=set_converter)

    {/* SNIPEND */}

  </SdkTabs.Python>
  <SdkTabs.Go>
    {/* SNIPSTART go-plugin-converter */}
[features/snippets/plugins/plugins.go](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.go)
```go
func createConverterPlugin() (*temporal.SimplePlugin, error) {
	customConverter := converter.GetDefaultDataConverter() // Or your custom converter

	return temporal.NewSimplePlugin(temporal.SimplePluginOptions{
		Name:          "organization.PluginName",
		DataConverter: customConverter,
	})
}

{/* SNIPEND */}

</SdkTabs.Go> <SdkTabs.Java> {/* SNIPSTART java-plugin-converter */} features/snippets/plugins/plugins.java

SimplePlugin converterPlugin =
    SimplePlugin.newBuilder("organization.PluginName")
        .customizeDataConverter(
            existingConverter -> {
              // Customize the data converter
              // This example keeps the existing converter unchanged
              // In practice, you might wrap it with additional functionality
              return existingConverter;
            })
        .build();

{/* SNIPEND */}

</SdkTabs.Java> <SdkTabs.TypeScript> {/* SNIPSTART typescript-plugins-converter */} features/snippets/plugins/plugins.ts

const codec: PayloadCodec = {
  encode(_payloads: Payload[]): Promise<Payload[]> {
    throw new Error();
  },
  decode(_payloads: Payload[]): Promise<Payload[]> {
    throw new Error();
  },
};
const plugin = new SimplePlugin({
  name: 'organization.PluginName',
  dataConverter: (converter: DataConverter | undefined) => ({
    ...converter,
    payloadCodecs: [...(converter?.payloadCodecs ?? []), codec],
  }),
});

{/* SNIPEND */}

</SdkTabs.TypeScript> <SdkTabs.DotNet> {/* SNIPSTART dotnet-plugins-converter */} features/snippets/plugins/plugins.cs

private class Codec : IPayloadCodec
{
    public Task<IReadOnlyCollection<Payload>> EncodeAsync(IReadOnlyCollection<Payload> payloads) => throw new NotImplementedException();
    public Task<IReadOnlyCollection<Payload>> DecodeAsync(IReadOnlyCollection<Payload> payloads) => throw new NotImplementedException();
}

SimplePlugin converterPlugin = new SimplePlugin(
    "organization.PluginName",
    new SimplePluginOptions()
    {
        DataConverterOption = new SimplePluginOptions.SimplePluginOption<DataConverter>(
            (converter) => converter with { PayloadCodec = new Codec() }
        ),
    });

{/* SNIPEND */}

</SdkTabs.DotNet> <SdkTabs.Ruby> {/* SNIPSTART ruby-plugin-converter */} features/snippets/plugins/plugins.rb

custom_converter = Temporalio::Converters::DataConverter.new(
  payload_converter: Temporalio::Converters::PayloadConverter.default
)

plugin = Temporalio::SimplePlugin.new(
  name: 'organization.PluginName',
  data_converter: custom_converter
)

{/* SNIPEND */}

</SdkTabs.Ruby>

Interceptors

Interceptors are middleware that can run before and after various calls such as Activities, Workflows, and Signals. You can learn more about interceptors for the details of implementing them. They're used to:

Create side effects such as logging and tracing.
Modify arguments, such as adding headers for authorization or tracing propagation.

{/* SNIPSTART python-plugin-interceptors */} [features/snippets/plugins/plugins.py](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.py) ```py class SomeWorkerInterceptor(temporalio.worker.Interceptor): pass # Your implementation

class SomeClientInterceptor(temporalio.client.Interceptor): pass # Your implementation

plugin = SimplePlugin( "organization.PluginName", interceptors=[SomeWorkerInterceptor(), SomeClientInterceptor()], )

    {/* SNIPEND */}
  </SdkTabs.Python>
  <SdkTabs.Go>
    {/* SNIPSTART go-plugin-interceptors */}
[features/snippets/plugins/plugins.go](https://github.com/temporalio/features/blob/main/features/snippets/plugins/plugins.go)
```go
type SomeWorkerInterceptor struct {
	interceptor.WorkerInterceptorBase
}

type SomeClientInterceptor struct {
	interceptor.ClientInterceptorBase
}

func createInterceptorPlugin() (*temporal.SimplePlugin, error) {
	return temporal.NewSimplePlugin(temporal.SimplePluginOptions{
		Name:               "organization.PluginName",
		WorkerInterceptors: []interceptor.WorkerInterceptor{&SomeWorkerInterceptor{}},
		ClientInterceptors: []interceptor.ClientInterceptor{&SomeClientInterceptor{}},
	})
}

{/* SNIPEND */}

</SdkTabs.Go> <SdkTabs.Java> {/* SNIPSTART java-plugin-interceptors */} features/snippets/plugins/plugins.java

public class SomeWorkerInterceptor extends WorkerInterceptorBase {
  // Your worker interceptor implementation
}

public class SomeClientInterceptor extends WorkflowClientInterceptorBase {
  // Your client interceptor implementation
}

SimplePlugin interceptorPlugin =
    SimplePlugin.newBuilder("organization.PluginName")
        .addWorkerInterceptors(new SomeWorkerInterceptor())
        .addClientInterceptors(new SomeClientInterceptor())
        .build();

{/* SNIPEND */}

</SdkTabs.Java> <SdkTabs.TypeScript> {/* SNIPSTART typescript-plugins-interceptors */} features/snippets/plugins/plugins.ts

class MyWorkflowClientInterceptor implements WorkflowClientInterceptor {}

class MyActivityInboundInterceptor implements ActivityInboundCallsInterceptor {}

class MyActivityOutboundInterceptor implements ActivityOutboundCallsInterceptor {}

const workflowInterceptorsPath = '';

const plugin = new SimplePlugin({
  name: 'organization.PluginName',
  clientInterceptors: {
    workflow: [new MyWorkflowClientInterceptor()],
  },
  workerInterceptors: {
    client: {
      workflow: [new MyWorkflowClientInterceptor()],
    },
    workflowModules: [workflowInterceptorsPath],
    activity: [
      (_: Context) => ({
        inbound: new MyActivityInboundInterceptor(),
        outbound: new MyActivityOutboundInterceptor(),
      }),
    ],
  },
});

{/* SNIPEND */}

</SdkTabs.TypeScript> <SdkTabs.DotNet> {/* SNIPSTART dotnet-plugins-interceptors */} features/snippets/plugins/plugins.cs

private class SomeClientInterceptor : IClientInterceptor
{
    public ClientOutboundInterceptor InterceptClient(
        ClientOutboundInterceptor nextInterceptor) =>
        throw new NotImplementedException();
}

private class SomeWorkerInterceptor : IWorkerInterceptor
{
    public WorkflowInboundInterceptor InterceptWorkflow(
        WorkflowInboundInterceptor nextInterceptor) =>
        throw new NotImplementedException();

    public ActivityInboundInterceptor InterceptActivity(
        ActivityInboundInterceptor nextInterceptor) =>
        throw new NotImplementedException();
}

SimplePlugin interceptorPlugin = new SimplePlugin(
    "organization.PluginName",
    new SimplePluginOptions()
    {
        ClientInterceptors = new List<IClientInterceptor>() { new SomeClientInterceptor() },
        WorkerInterceptors = new List<IWorkerInterceptor>() { new SomeWorkerInterceptor() },
    });

{/* SNIPEND */}

</SdkTabs.DotNet> <SdkTabs.Ruby> {/* SNIPSTART ruby-plugin-interceptors */} features/snippets/plugins/plugins.rb

class SomeWorkerInterceptor
  include Temporalio::Worker::Interceptor::Workflow

  def intercept_workflow(next_interceptor)
    # Your interceptor implementation
    next_interceptor
  end
end

class SomeClientInterceptor
  include Temporalio::Client::Interceptor

  def intercept_client(next_interceptor)
    # Your interceptor implementation
    next_interceptor
  end
end

plugin = Temporalio::SimplePlugin.new(
  name: 'organization.PluginName',
  client_interceptors: [SomeClientInterceptor.new],
  worker_interceptors: [SomeWorkerInterceptor.new]
)

{/* SNIPEND */}

</SdkTabs.Ruby>

Context Propagators {#context-propagators}

Context propagators pass custom key-value data (such as tracing IDs, tenant IDs, or auth tokens) across Workflow, Activity, and Child Workflow boundaries via Temporal headers. See Context Propagation for details on how they work.

Propagators registered via a Plugin are appended to any propagators already set by the user or by previous plugins.

func createContextPropagatorPlugin() (*temporal.SimplePlugin, error) {
    return temporal.NewSimplePlugin(temporal.SimplePluginOptions{
        Name:               "organization.PluginName",
        ContextPropagators: []workflow.ContextPropagator{NewMyPropagator()},
    })
}

</SdkTabs.Go>

Special considerations for different languages

Each of the SDKs has nuances you should be aware of so you can account for it in your code.

Python

You can choose to run your Workflows in a sandbox in Python. This lets you run Workflow code in a sandbox environment to help prevent non-determinism errors in your application. To work for users who use sandboxing, your Plugin should specify the Workflow runner that it uses.

{/* SNIPSTART python-plugin-sandbox */} features/snippets/plugins/plugins.py

def workflow_runner(runner: WorkflowRunner | None) -> WorkflowRunner:
    if not runner:
        raise ValueError("No WorkflowRunner provided to the plugin.")

    # If in sandbox, add additional passthrough
    if isinstance(runner, SandboxedWorkflowRunner):
        return dataclasses.replace(
            runner,
            restrictions=runner.restrictions.with_passthrough_modules("module"),
        )
    return runner


plugin = SimplePlugin("organization.PluginName", workflow_runner=workflow_runner)

{/* SNIPEND */}

TypeScript

TypeScript bundles cannot provide built-in Workflows because the TypeScript SDK bundles all Workflow code from a single module. Plugin users must import and re-export any Plugin-provided Workflows from their own Workflow module so the bundle includes them.

Users of a plugin which provides Workflow interceptors should always provide the plugin to the bundler if bundling. If you aren't aware of the exact function of the plugin, you can always provide it, as it won't have any adverse effects.

{/* SNIPSTART typescript-plugins-bundler */} features/snippets/plugins/plugins.ts

const bundle = await bundleWorkflowCode({
  workflowsPath: require.resolve('./workflows'),
  plugins: [plugin],
});

const worker = await Worker.create({
  connection,
  taskQueue: 'my-task-queue',
  workflowBundle: bundle,
  plugins: [plugin],
});

{/* SNIPEND */}

Testing your Plugin {#testing-your-plugin}

To test your Plugin, you'll write a normal Temporal Workflow tests, having included the plugin in your Client.

Two special concerns are versioning tests, for when you're making changes to your plugin, and testing unwanted side effects.

Versioning tests

When you make changes to your plugin after it has already shipped to users, we recommend that you set up replay testing on each important change to make sure that you’re not causing non-determinism errors for your users.

Side effects tests

Your Plugin should cater to Workflows resuming in different processes than the ones they started on and then replaying from the beginning, which can happen, for example, after an intermittent failure.

You can ensure you're not depending on local side effects by turning Workflow caching off, which will mean that the Workflow replays from the top each time it progresses:

{/* SNIPSTART python-worker-max-cached-workflows */} [features/snippets/worker/worker.py](https://github.com/temporalio/features/blob/main/features/snippets/worker/worker.py) ```py worker = Worker(client, task_queue="task-queue", max_cached_workflows=0) ``` {/* SNIPEND */} {/* SNIPSTART go-worker-max-cached-workflows */} [features/snippets/worker/worker.go](https://github.com/temporalio/features/blob/main/features/snippets/worker/worker.go) ```go worker.SetStickyWorkflowCacheSize(0) w := worker.New(c, "task-queue", worker.Options{}) ``` {/* SNIPEND */} {/* SNIPSTART java-worker-max-cached-workflows */} [features/snippets/worker/worker.java](https://github.com/temporalio/features/blob/main/features/snippets/worker/worker.java) ```java WorkerFactory factory = WorkerFactory.newInstance( client, WorkerFactoryOptions.newBuilder().setWorkflowCacheSize(0).build()); Worker worker = factory.newWorker("task-queue"); ``` {/* SNIPEND */} {/* SNIPSTART typescript-worker-max-cached-workflows */} [features/snippets/worker/worker.ts](https://github.com/temporalio/features/blob/main/features/snippets/worker/worker.ts) ```ts const worker = await Worker.create({ connection, taskQueue: 'task-queue', maxCachedWorkflows: 0, }); ``` {/* SNIPEND */} {/* SNIPSTART dotnet-worker-max-cached-workflows */} [features/snippets/worker/worker.cs](https://github.com/temporalio/features/blob/main/features/snippets/worker/worker.cs) ```cs using var worker = new TemporalWorker( client, new TemporalWorkerOptions("task-queue") { MaxCachedWorkflows = 0 }); ``` {/* SNIPEND */} {/* SNIPSTART ruby-worker-max-cached-workflows */} [features/snippets/worker/worker.rb](https://github.com/temporalio/features/blob/main/features/snippets/worker/worker.rb) ```rb worker = Temporalio::Worker.new( client: client, task_queue: 'task-queue', max_cached_workflows: 0 ) ``` {/* SNIPEND */}

Inside this replay regime, you should test for duplicate side effects or other types of failures. When testing for duplicate side effects, it may not be sufficient to simply have a counter that increments once per effect, as activities may be retried. Instead, consider these patterns:

count ActivityTaskScheduled events of the expected activity type in workflow history (one per intended call, independent of retries),
or accumulate activity IDs in a concurrency-safe set and assert on its size (different scheduled activities get different IDs; retries of the same scheduled activity share one).

It's harder to test against side effects to global variables, so this practice is best avoided entirely.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Plugins

How to build a Plugin

Example Plugins

What you can provide to users in a plugin

Built-in Activity

Timeouts and retry policies

Workflow-friendly libraries

Making changes to your library

Example of a Workflow library that uses a Plugin in Python

Built-in Workflows

Built-in Nexus Operations

Custom Data Converters

Interceptors

Context Propagators {#context-propagators}

Special considerations for different languages

Python

TypeScript

Testing your Plugin {#testing-your-plugin}

Versioning tests

Side effects tests

FilesExpand file tree

plugins-guide.mdx

Latest commit

History

plugins-guide.mdx

File metadata and controls

Plugins

How to build a Plugin

Example Plugins

What you can provide to users in a plugin

Built-in Activity

Timeouts and retry policies

Workflow-friendly libraries

Making changes to your library

Example of a Workflow library that uses a Plugin in Python

Built-in Workflows

Built-in Nexus Operations

Custom Data Converters

Interceptors

Context Propagators {#context-propagators}

Special considerations for different languages

Python

TypeScript

Testing your Plugin {#testing-your-plugin}

Versioning tests

Side effects tests