Added the plugin guide

[flippedcoder]

What does this PR do?

Adds documentation for using plugins with the Python SDK.

Notes to reviewers

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
temporal-documentation	Ready	Preview	Comment	Nov 22, 2025 1:48am

[github-actions]

📖 Docs PR preview links

• Develop
  • Plugins guide

[drewhoskins-temporal]

Thank you! I made a few suggested edits and tagged Tim in for a few.

(Bearing in mind that in some cases I was editing my own content. :-) )

[drewhoskins-temporal]

This ended up feeling a bit long and redundant on my re-read.

Suggested change

	Be cautious when doing retries within your Activity because it lengthens this overall timeout to be longer than the longest possible retry sequence. That means it takes too long to recover from other causes of failure. Such internal retries also prevent users from counting failure metrics and make it harder for users to debug in Temporal UI when something is wrong.
	Be cautious when doing retries within your Activity because it lengthens the needed Activity timeout. Such internal retries also prevent users from counting failure metrics and make it harder for users to debug in Temporal UI when something is wrong.

[Sushisource]

Same deal as my above comments, not sure this whole section even needs to be here at all. We're just repeating advice we give elsewhere in the docs - none of this is specific to plugins

[drewhoskins-temporal]

Yeah, as above, @flippedcoder and I will resolve this in a follow-up PR.

[drewhoskins-temporal]

This is python-specific. Could we maybe do this in a tab? Or otherwise reformat into an SDK-specific section or something?

s/used/usable/

[flippedcoder]

Few questions here:

1. Do we have a code example for how a plugin would be used in the Python sandbox?
2. Do we have sandboxes for the other SDKs?
3. Are we going to recommend using a sandbox for all SDKs?

This will help me figure out how to structure this in the doc.

[drewhoskins-temporal]

Good questions.

• I like the idea of putting a code snippet for sandbox in python. @tconley1428 can you provide?
• Only python has a sandbox.
• Other languages may have their own common/special gotchas. @tconley1428 will know better, esp. in typescript which he is working on.

Maybe for now we should just include a one-off delineator, and then we can refactor once the typescript stuff comes in?

[tconley1428]

The sandbox is enabled by default, all existing samples already have it.
Typescript also has a sandbox which is actually more robust, but it is not optional.

[tconley1428]

• It should be used in the Python sandbox.

Yeah this doesn't make a lot of sense. When you use it in a workflow, which is the whole context here, it is either sandboxed or not based on worker configuration. This isn't something that needs to be specified.

[drewhoskins-temporal]

Tim's code--perhaps we should make this a snippet?

def workflow_runner(runner: Optional[WorkflowRunner]) -> WorkflowRunner:
    if not runner:
        raise ValueError("No WorkflowRunner provided to the OpenAI plugin.")

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

SimplePlugin(..., workflow_runner=workflow_runner)

[drewhoskins-temporal]

Suggested change

	- It should be designed to handle being restarted, resumed, or executed independently of where or how it originally began without losing correctness or state consistency.
	- It should be designed to handle being restarted, resumed, or executed in a different process from where it originally began without losing correctness or state consistency.

[drewhoskins-temporal]

@tconley1428, can you provide details about how to test this by disabling the workflow cache, starting with python? My thought is we can add a "Testing your plugin" section at the bottom and then link to that here.

[flippedcoder]

☝🏽 I like this idea. If we can have a code snippet to show how test by disabling the workflow cache, it'll definitely help out users.

[tconley1428]

client = await Client.connect(
  "localhost:7233",
  plugins=[
    plugin,
  ],
)
async with Worker(
  client,
  task_queue="task-queue",
  max_cached_workflows=0
):
    Test some things.

[drewhoskins-temporal]

@tconley1428 my initial reaction was that this is unrealistic, since plugins are generally designed to be reused. I'd expect people to create a plugin class that declares the Workfows rather than make a global variable for people to use. If you agree, can you help update the code, here and in the other examples?

[tconley1428]

It's not really clear here where the different code lives. If the plugin is defined in some library, it likely will be created via constructor or function, but there's not really any inherent problem with a global. If it is just in the user's code, it's not really clear if this is a global or a local variable in the various main functions, given that there isn't really a scope in the code example at all.

[drewhoskins-temporal]

@tconley1428 I don't follow the objection or how this has anything to do with modules. What I mean is:

class MyLibraryPlugin(SimplePlugin):
  ...

Goal I'm aiming for these sample snippets is to be as much like user's realistic code as possible.

[tconley1428]

Misunderstood what you were asking then. The existing snippet makes sense for a plugin without arguments. You could do as you suggest if you think it will be more extensible, feel free.

[drewhoskins-temporal]

Alright, cool, if this is normal then 👍

[drewhoskins-temporal]

@tconley1428

• This doesn't quite match what we did for OpenAI -- please double check that this is our best up-to-date advice.
• I can't find it, but I remember seeing a snippet where we pull the user's existing codecs into the payload. Should we do something like that here?

[tconley1428]

def _data_converter(converter: Optional[DataConverter]) -> DataConverter:
    if converter is None:
        return DataConverter(payload_converter_class=OpenAIPayloadConverter)
    elif converter.payload_converter_class is DefaultPayloadConverter:
        return dataclasses.replace(
            converter, payload_converter_class=OpenAIPayloadConverter
        )
    elif not isinstance(converter.payload_converter, OpenAIPayloadConverter):
        raise ValueError(
            "The payload converter must be of type OpenAIPayloadConverter."
        )
    return converter

Is our current implementation. We could do so to demonstrate it, but the desires of various payloads may vary.

[tconley1428]

where we pull the user's existing codecs into the payload

That is the code you linked and I pasted.

[Sushisource]

Maybe re-word this to be more generic than adding stuff to workflows, since you can do more than that?

[drewhoskins-temporal]

What do you have in mind?

[flippedcoder]

What do y'all think about this?

A **Plugin** is an abstraction that will let your users add your feature to their Temporal primitives, like Workflows and Activities, in one line. It makes it seamless for platform engineers to add their own custom functionality to many primitives.

[Sushisource]

A Plugin is an abstraction that allows you to customize any aspect of 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.

Would be my take

[drewhoskins-temporal]

Fine with me.

[Sushisource]

This reads awkwardly to me. Each line sort of contradicts the last. Presumably we have advice elsewhere in the docs we can link to about what an activity should be scoped to?

This could be just "Activities should be scoped to a small, ideally idempotent, unit of work" or something

[drewhoskins-temporal]

Presumably we have advice elsewhere in the docs we can link to about what an activity should be scoped to?

We actually don't AFAICT! I'd love to link out to the general activity docs, but I figured, let's get the content in here for starters and then refactor next.

Let me suggest a rewording.

re: idempotent, we have to be careful there since LLMs are not idempotent by some definitions.

[Sushisource]

Definitely seems like we should link to general advice on activities somewhere in this section at least

[drewhoskins-temporal]

Agreed, but we don't actually have almost any of this advice anywhere that I could find. I've opened a task as a follow-up to figure out where to put it.

We can put it here: https://docs.temporal.io/activities and here https://docs.temporal.io/activity-definition in some combination. (But separate from this PR, I hope.)

[flippedcoder]

Yes, we can make that update to the activity definition in a separate PR. For now, let's leave it here and I can come back and change it to a link later.

[Sushisource]

Same deal as my above comments, not sure this whole section even needs to be here at all. We're just repeating advice we give elsewhere in the docs - none of this is specific to plugins

[drewhoskins-temporal]

What do you have in mind?