Let Agent be run in a Temporal workflow by moving model requests, tool calls, and MCP to Temporal activities

[DouweM]

• Closes Native temporal support #1975
• Builds on Add AbstractAgent, WrapperAgent, Agent.event_stream_handler, Toolset.id, Agent.override(tools=...) in preparation for Temporal #2458

To do:

• Tests
• Docs

[github-actions]

Docs Preview

commit:	e9195e8
Preview URL:	https://a443527e-pydantic-ai-previews.pydantic.workers.dev

[mattbrandman]

I'm so excited for this to be natively supported

[nir-litt]

Thank you for taking the time to look into native temporal support - this is a topic I’m really interested in seeing progress on.

One key feature I’d love to see is support for HITL (Human-in-the-Loop) during tool calls when using temporal and agents. My suggestion on how to achieve that (and not being to specific for HITL) is to pause the workflow before a tool call waiting on a condition for a signal. This will allow, among other things, to wait for human input.

Currently, tool calls are handled like this:

async def call_tool(
    self, name: str, tool_args: dict[str, Any], ctx: RunContext[AgentDepsT], tool: ToolsetTool[AgentDepsT]
) -> Any:
    serialized_run_context = self.serialize_run_context(ctx)
    return await workflow.execute_activity(
        activity=self.call_tool_activity,
        arg=FunctionCallToolParams(name=name, tool_args=tool_args, serialized_run_context=serialized_run_context),
        **self.temporal_settings.__dict__,
    )

To add the wait support, we can do something like:
(This example is a bit abstract - we will have to understand (at least):

• how to pass the self.allow_tool_call from the workflow to this class or effect it with some callback instead of just setting it
• pass all the data of the tool call for the handler to be able to decide which action to take)

async def call_tool(
    self, name: str, tool_args: dict[str, Any], ctx: RunContext[AgentDepsT], tool: ToolsetTool[AgentDepsT]
) -> Any:
    # --- ADDED: tool call pause using signal and wait_condition ---
    await workflow.wait_condition(lambda: self.allow_tool_call)
    # --- END ADDED CODE ---
    serialized_run_context = self.serialize_run_context(ctx)
    activity_result =  await workflow.execute_activity(
        activity=self.call_tool_activity,
        arg=FunctionCallToolParams(name=name, tool_args=tool_args, serialized_run_context=serialized_run_context),
        **self.temporal_settings.__dict__,
    )
    # --- ADDED: tool call reset state ---
    self.allow_tool_call = False
    return activity_result
    # --- END ADDED CODE ---

This will allow users to define their workflow something like:

@workflow.signal
def approve_tool_call(self):
    ... # some code to determine the tool is OK to run
    self.allow_tool_call = True

This way, the workflow will pause at the tool call and only continue once the signal is approved.

of course this would be optional and the default ,that can be overwritten by the user, will be to approve the request

Appreciate the ongoing work!

[hyperlint-ai]

PR Change Summary

Introduced the Temporal Agent feature by enhancing toolset definitions and adding optional IDs for better identification in error messages.

• Added optional ID parameters to FunctionToolset for better identification in error messages.
• Updated LangChainToolset and ACIToolset to include IDs for Slack and Open Weather Map respectively.
• Enhanced documentation to clarify the use of IDs in durable execution environments.

Modified Files

• docs/tools.md
• docs/toolsets.md

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[dmontagu]

Suggested change

Pydantic AI allows you to build durable agents that never lose their progress and handle long-running, asynchronous, and human-in-the-loop workflows with production-grade reliability. Durable agents have full support for [streaming](agents.md#streaming-all-events) and [MCP](mcp/client.md), with the added benefit of fault tolerance.

Pydantic AI allows you to build durable agents that can preserve their progress across transient API failures and application errors or restarts, and handle long-running, asynchronous, and human-in-the-loop workflows with production-grade reliability. Durable agents have full support for [streaming](agents.md#streaming-all-events) and [MCP](mcp/client.md), with the added benefit of fault tolerance.

Imo this feels like it better-represents the benefits, though a bit wordy..

[dmontagu]

Suggested change

	The key to making this work is to separate the applications repeatable (deterministic) and non-repeatable (non-deterministic) parts:
	The key to making this work is to separate the application's repeatable (deterministic) and non-repeatable (non-deterministic) parts:

[dmontagu]

I don't think you explicitly mention anywhere that workflows cannot incorporate I/O (at least, nowhere up to this point?). This might be implicit in saying "deterministic" but I feel like when most people read "deterministic" they think non-random, rather than not-including-I/O. I think it's worth making the point explicitly quite early:

Suggested change

	Workflow code can run for extended periods and, if interrupted, resume exactly where it left off.
	Workflow code can run for extended periods and, if interrupted, resume exactly where it left off. Critically, workflow code _cannot_ include any kind of I/O, over network, terminal, etc.

or similar

[dmontagu]

it restarts from the beginning.

This feels a bit ambiguous if you don't understand what an activity is. What is "the beginning"? (I don't think we've really explained that activities are triggered via function calls, and that "restarting" essentially amounts to calling that function from the top.)

I think it's maybe worth explaining something like — "if you are familiar with distributed execution frameworks like celery, you can think of calling activity code like executing a celery task, except where you wait for the response and continue executing once it is received". (You can add caveats about how this isn't a perfect analogy or whatever, but I think it would help people unfamiliar with temporal understand what was going on.)

[dmontagu]

Suggested change

In the case of Pydantic AI agents, this means that [model requests](models/index.md), [tool calls](tools.md) that may require I/O, and [MCP server communication](mcp/client.md) all need to be offloaded to Temporal activities, while the logic that coordinates them (i.e. the agent run) lives in the workflow. Code that handles a scheduled job or web request can then execute the workflow, which will in turn execute the activities as needed.

In the case of Pydantic AI agents, integration with Temporal means that [model requests](models/index.md), [tool calls](tools.md) that may require I/O, and [MCP server communication](mcp/client.md) all need to be offloaded to Temporal activities due to their I/O requirements, while the logic that coordinates them (i.e. the agent run) can live in the workflow. Code that should _trigger_ the agent run, such as scheduled jobs or web requests, can execute the workflow, which will in turn execute these activities as needed.

[dmontagu]

Suggested change

	The Temporal Server is responsible to tracking program execution and making sure associated state is preserved reliably (i.e., stored to a database, possibly replicated across cloud regions).
	The Temporal Server is responsible for tracking program execution and making sure the associated state is preserved reliably (i.e., stored to an internal database, and possibly replicated across cloud regions).

[dmontagu]

Suggested change

	See the [Temporal documentation](https://docs.temporal.io/evaluate/understanding-temporal#temporal-application-the-building-blocks) for more information.
	See the [Temporal documentation](https://docs.temporal.io/evaluate/understanding-temporal#temporal-application-the-building-blocks) for more information.

[dmontagu]

Suggested change

	Any agent can be wrapped in a [`TemporalAgent`][pydantic_ai.durable_exec.temporal.TemporalAgent] to get a durable agent that can be used inside a deterministic Temporal workflow, by automatically offloading all work that requires IO (namely model requests, tool calls, and MCP server communication) to non-deterministic activities.
	Any agent can be wrapped in a [`TemporalAgent`][pydantic_ai.durable_exec.temporal.TemporalAgent] to get a durable agent that can be used inside a deterministic Temporal workflow, by automatically offloading all work that requires I/O (namely model requests, tool calls, and MCP server communication) to non-deterministic activities.

Let's try to be consistent on "IO" vs. "I/O". I don't care which we use, but I think I've seen both already.

[dmontagu]

Suggested change

At the time of wrapping, the agent's [model](models/index.md) and [toolsets](toolsets.md) (including function tools registered on the agent and MCP servers) are frozen, activities are dynamically created for each, and the original model and toolsets are wrapped to call on the worker to execute the corresponding activity instead of directly performing the action inside the workflow. The original agent can still be used as normal outside of the Temporal workflow, but any changes to its model or toolsets after wrapping will not be reflected in the durable agent.

At the time of wrapping, the agent's [model](models/index.md) and [toolsets](toolsets.md) (including function tools registered on the agent and MCP servers) are frozen, activities are dynamically created for each, and the original model and toolsets are wrapped to call on the worker to execute the corresponding activities instead of directly performing the actions inside the workflow. The original agent can still be used as normal outside of the Temporal workflow, but any changes to its model or toolsets after wrapping will not be reflected in the durable agent.

[dmontagu]

Suggested change

	This is a simple but complete example of wrapping an agent for durable execution, creating a Temporal workflow with durable execution logic, connecting to a Temporal server, and running the workflow from non-durable code.
	### Simple example
	Here is a simple but complete example of wrapping an agent for durable execution, creating a Temporal workflow with durable execution logic, connecting to a Temporal server, and running the workflow from non-durable code.

Feels like it's worth a bit heavior of a markdown transition here.

[dmontagu]

Suggested change

	All it requires is a Temporal server to be [running locally](https://github.com/temporalio/temporal#download-and-start-temporal-server-locally):
	All it requires is the Temporal dev server to be [running locally](https://github.com/temporalio/temporal#download-and-start-temporal-server-locally) on the default port:

[dmontagu]

Is this really a worker process? If it's not a distinct process, but just something else running on the same async event loop, I'd probably drop the word process here.

Separately, I would add here that in a production deployment, you would typically run the worker in a different code path than you'd use to execute a workflow. Basically just more clearly making the point that this structure is designed for making the example convenient to run and not what "real world" temporal code would look like.

[dmontagu]

I see you made this point below:

the agent, workflow, and worker are typically defined separately from the code that calls for a workflow to be executed.

but I still feel it's also worth making this point here, where the code is.

[DouweM]

Separately, I would add here that in a production deployment, you would typically run the worker in a different code path than you'd use to execute a workflow. Basically just more clearly making the point that this structure is designed for making the example convenient to run and not what "real world" temporal code would look like.

I mentioned that below, but feel free to rephrase:

In a real world application, the agent, workflow, and worker are typically defined separately from the code that calls for a workflow to be executed.

[dmontagu]

Suggested change

	_(This example is complete, it can be run "as is" — you'll need to add `asyncio.run(main())` to run `main`)_
	_(This example is complete, it can be run "as is" — you just need to add `asyncio.run(main())` to run `main`)_

if we are already using the existing phrasing elsewhere its' fine.

[dmontagu]

Suggested change

	For more information on how to use Temporal in Python applications, see their [Python SDK guide](https://docs.temporal.io/develop/python).
	Note that temporal workflows can be used for more than just handling failures, including .... For more information on how to use Temporal in Python applications, see their [Python SDK guide](https://docs.temporal.io/develop/python).

(the "..." here might talk about how you can use signals to achieve human-in-the-loop, how you can "sleep" for days without a problem, etc., I just think it's worth pointing out that temporal is more than just error handling, and helps motivate why someone might want to read more. Sorry I didn't flesh it out for you, maybe AI can help lol.)

[dmontagu]

Suggested change

	Other than that, any agent and toolset will just work!
	Other than that, using any agent and toolset with `TemporalAgent` should "just work"!

[dmontagu]

I think we should convert this and the next 3 sections into subsections of a parent section called something like "Requirements on durable agent usage" or similar, and drop the point about "Other than that, any agent ... will just work!", given it's actually three caveats here. But for the most part I think these sections can stay the same.

[DouweM]

Outstanding docs feedback will be addressed by @dmontagu in a follow-up PR tonight or tomorrow.