Microsoft Agent Framework integration
Temporal's integration with Microsoft Agent Framework is an
SDK Plugin that runs an Agent Framework Agent inside a Temporal Workflow. You write the
agent the way Agent Framework documents it and swap the chat client for TemporalChatClient. Each model round trip then
runs as a Temporal Activity with its own timeout and retries, and Temporal records its result in the Workflow's Event
History.
The agent's own function-invocation loop, tools, middleware, context providers and approvals run in the Workflow. After a crash or a Worker restart, Temporal replays the Workflow from Event History and the agent resumes after the last completed Activity instead of starting over.
Code snippets in this guide are taken from the Agent Framework plugin samples. Refer to the samples for the complete code.
Get started
Install the plugin, then run one agent inside a Workflow.
Prerequisites
- This guide assumes you are familiar with Microsoft Agent Framework. If you are not, start with the Agent Framework documentation.
- If you are new to Temporal, read Understanding Temporal or take the Temporal 101 course.
- Set up your local development environment by following Set up your local development environment. Leave the Temporal development server running if you want to test your code locally.
- Use Python 3.11 or later. The plugin declares
requires-python = ">=3.11", as Temporal Python SDK 1.36 does; current Agent Framework releases require it too. - Export
OPENAI_API_KEYin the Worker's environment. The samples use OpenAI'sgpt-4o-mini; the Workflow never sees the key.
Install the plugin
Install the temporalio-microsoft-agent-framework package together with the Agent Framework provider package you use.
The samples use OpenAI:
uv add temporalio-microsoft-agent-framework agent-framework-openai
or with pip:
pip install temporalio-microsoft-agent-framework agent-framework-openai
The package depends on agent-framework-core, not the agent-framework meta package, so it does not install every
provider. MCP support is an extra; Connect to MCP servers installs it. Refer to the
package requirements
for the supported Python, Temporal SDK and Agent Framework versions.
Import MicrosoftAgentFrameworkPlugin, TemporalChatClient and TemporalMCPToolProvider from
temporalio.microsoft_agent_framework, and activity_as_tool from temporalio.microsoft_agent_framework.workflow.
Run an agent with Durable Execution
The following example runs one Agent inside a Workflow. The Workflow carries the model name "gpt-4o-mini" and
nothing else; the Worker maps that name to a real chat client.
1. Define the Workflow
Build the Agent over a TemporalChatClient instead of a provider client. Each round trip to the model runs as the
microsoft_agent_framework.invoke_model Activity with the Activity options you pass to the client. The sample sets a
60-second start_to_close_timeout. The defaults are a 5-minute start_to_close_timeout and a 10-second
heartbeat_timeout; the Activity heartbeats on its own every 5 seconds, so the Temporal Service marks the Activity
timed out within 10 seconds of a Worker dying mid-call and schedules the retry.
2. Start a Worker
MicrosoftAgentFrameworkPlugin(chat_clients=...) maps each model name to a factory that builds the provider's chat
client. The factory runs on the Worker on first use and its client is cached for the Worker's lifetime, so
OPENAI_API_KEY and the connection stay on the Worker. Temporal retries the model Activity, so turn the OpenAI SDK's
own retries off with AsyncOpenAI(max_retries=0); OpenAIChatClient has no max_retries setting of its own. A client
that still retries gets one warning in the Worker log the first time it runs.
Add the plugin to Client.connect(...) or to the Worker, not both. A Worker inherits the plugins of the Client it is
built from, and a second copy registers the model Activities twice, which the Worker rejects with a ValueError. The
plugin registers the microsoft_agent_framework.invoke_model and microsoft_agent_framework.invoke_model_streaming
Activities, sets the Pydantic data converter, and configures the Workflow sandbox for Agent Framework, so the Worker
needs no other wiring.
3. Run the Workflow
Start the Workflow from a separate script:
The Workflow's Event History shows one microsoft_agent_framework.invoke_model Activity. Its summary is the model name,
so the Web UI shows which model each call used.
To run the sample from a samples-python checkout: uv sync --group microsoft-agent-framework, then
uv run microsoft_agent_framework_plugin/hello_world/run_worker.py and, in a second terminal,
uv run microsoft_agent_framework_plugin/hello_world/run_workflow.py.
Build the agent
Choose where each tool runs, connect MCP servers, and add middleware.
Run tools as Activities
Decide per tool where it runs. A tool that is pure logic stays in the Workflow as an ordinary @tool. A tool that does
I/O or reads a clock belongs in an Activity: decorate the function with @activity.defn, register it on the Worker, and
pass it to the agent through activity_as_tool. The plugin cannot tell the two apart, so the choice is yours.
The sample has one of each. letter_counter counts characters and runs in the Workflow:
fetch_weather stands in for an HTTP call and runs as an Activity:
activity_as_tool takes the same Activity options as workflow.execute_activity, and like it needs a
start_to_close_timeout or a schedule_to_close_timeout; without either it raises ValueError when the tool is built,
not when the model calls it. The sample gives the tool a 30-second start_to_close_timeout. Agent Framework reads the
tool's parameter schema from the Activity's signature and its description from the docstring, so Annotated parameters
work as they do on @tool. A failed Activity, including one that ran out of retries, raises its failure cause from the
tool, and Agent Framework turns that into an error result for the model.
Register the Activity on the Worker next to the Workflow:
A synchronous def tool runs on the Workflow's event loop. Agent Framework hands it to asyncio.to_thread, which the
Workflow event loop does not implement, so the plugin's Worker runtime rebinds that name in the framework's tool module
to a stand-in that calls the function directly inside a Workflow and still uses a thread anywhere else. The tool object
itself is not changed, so one shared with an Activity or a plain agent in the same process keeps its normal behavior
there. A sync tool that blocks for long blocks the Workflow Task, so keep sync tools quick or make them Activities.
Agent Framework's loop settings apply unchanged: tool calls of one response run concurrently by default
(allow_concurrent_invocation=True), a run makes at most max_iterations (40) model calls before one last call with
tool_choice="none", and after three consecutive rounds of failing tools the loop stops calling tools and asks for a
final answer. Set them on TemporalChatClient(function_invocation_configuration={...}).
Connect to MCP servers
MCP support runs on temporalio-mcp and MCP Python SDK 2. Install the mcp
extra, which adds temporalio-mcp, mcp 2.2 or later and mcp-types; a project that still pins MCP SDK 1 cannot
install it:
uv add "temporalio-microsoft-agent-framework[mcp]"
MicrosoftAgentFrameworkPlugin(mcp_clients=...) maps a server name to a factory that returns an mcp.Client, the same
shape as chat_clients. A factory that raises, or returns something other than an mcp.Client, fails the Activity once,
with a non-retryable ApplicationError of type MicrosoftAgentFrameworkMCPClientFactoryError. For each server the
plugin registers the temporalio.mcp.<server>.list-tools and temporalio.mcp.<server>.call-tool Activities, plus
temporalio-mcp's prompt and resource operations (list-prompts, get-prompt, list-resources,
list-resource-templates, read-resource). The connection lives on the Worker: the plugin connects on the first MCP
Activity and closes the connection after 5 minutes of idleness (mcp_connection_idle_timeout; None keeps it until
shutdown, timedelta(0) closes it after every Activity).
In the Workflow, TemporalMCPToolProvider("echo") is an Agent Framework context provider. Before each agent.run it
lists the server's tools through the list-tools Activity and adds one tool per entry, with the server's input schema;
cache_tools=True lists once per provider instance instead. Each call the model makes runs the call-tool Activity.
Pass it in context_providers, not tools. Agent Framework's MCPStdioTool, MCPStreamableHTTPTool and
MCPWebsocketTool hold a live connection, which cannot exist in a Workflow, so they cannot be used in tools=; the
provider replaces them.
Register the server factory on the Worker. The sample starts a one-tool echo server over stdio; swap in any MCP server by changing the factory. The sample is its own uv project because it needs MCP Python SDK 2, so its imports are flat:
The Activity options on the provider apply to its list and call Activities. The sample sets a 30-second
start_to_close_timeout; without one, temporalio-mcp's one-minute default applies. The default Retry Policy retries
without limit, so a run waits while its server is down; bound it with retry_policy or schedule_to_close_timeout.
An exhausted call-tool then becomes an error result for the model, and an exhausted list-tools raises from
agent.run. The provider sets no heartbeat_timeout: temporalio-mcp 0.3 does not heartbeat its Activities, and its
next release gives them a 10-second default. tool_name_prefix, allowed_tools and approval_mode work as they do on
Agent Framework's MCPTool. A server tool whose name the agent already has fails the Workflow with
MicrosoftAgentFrameworkWorkflowError before the model call; give that provider a tool_name_prefix or an
allowed_tools list. Tools passed to agent.run(tools=...) are merged after context providers run, so a collision with
one of those raises Agent Framework's own ValueError instead; put such tools on the Agent. Do not register the same
server name through MCPPlugin on the same Worker: the Activity names clash. A server name that no Worker registered has
no Activity to run, so the attempt fails with a retryable NotFoundError and the run waits until a Worker with that name
polls the Task Queue.
Add middleware
Pass middleware to the Agent or to TemporalChatClient as you do natively. Agent middleware runs in the Agent;
chat and function middleware run in TemporalChatClient's layers. All of it runs in the Workflow, next to the agent's
loop. In the sample, delete_file is a plain @tool and ALLOWED_PREFIX is /tmp/. BlockOutsideTmp is function
middleware that refuses delete_file calls outside that prefix by setting context.result without calling
call_next(), so the tool never runs and the model reads the refusal. AppendReminder is chat middleware that appends
REMINDER to the instructions of every model call before the request leaves for the Activity.
A Workflow Definition must be deterministic, and middleware is part
of it. Do not read the clock, do I/O or draw random numbers in middleware. Middleware that needs I/O calls
await workflow.execute_activity(...). Context providers run in the Workflow too and may await Activities in
before_run and after_run.
Agents compose inside the Workflow too. Agent.as_tool() turns a sub-agent into a tool of a coordinator; every agent
runs in the Workflow and every agent's model calls are Activities, so the whole tree is durable with no per-agent
wiring. A
sub-agent called through as_tool() runs streaming, so its calls are microsoft_agent_framework.invoke_model_streaming
Activities. The
multi-agent sample
gives each agent its own TemporalChatClient with a summary, so the Activities read coordinator, researcher and
writer in the Web UI.
Add human approval to tool calls
Approvals are Agent Framework's own. A tool with approval_mode="always_require" does not run; agent.run returns with
the request in response.user_input_requests, and you answer with request.to_function_approval_response(approved) on
the same session. In a Workflow the wait is durable. The sample publishes the pending requests through a
Query, waits in workflow.wait_condition until a decide
Update has answered each of them with a Decision that carries
the request's identifier and the verdict, and runs the agent again with the decisions. Only an approved call runs the
tool; a rejected call sends the model Agent Framework's rejection result. Agent Framework decides what happens to a
request you do not answer: a response whose id matches no pending request is ignored with a log line and the request
stays pending, and a run that brings a new message without answering drops the pending call from the transcript. Check
response.user_input_requests before the next run if a dropped request matters.
Agent Framework keys the approval by the request's id and binds the response to the request recorded in the
session, so both runs use the same session. When a provider omits the function call's identifier, the provider's client
assigns one on the Worker before the response enters Event History, so the id in a pending request survives a Worker
restart and a replay. The Update's validator checks only that request_id is present; the handler does the state check.
The SDK runs the validator when the Update arrives, before the Workflow's main coroutine has seen an Activity result
delivered in the same Workflow Task, so a validator that checked for a pending request would reject a decision that
arrives together with the model's reply. The handler instead waits until the reply has been read, then fails the Update
with an ApplicationError for a request that is already decided or not pending, so a double submit or a wrong
identifier cannot answer a later request.
Return structured output
Pass a Pydantic class as response_format in the run options. Its JSON schema crosses to the model Activity and the
Workflow parses the reply into response.value:
The Workflow returns the model itself. The plugin sets the
Pydantic data converter unless your Client already
has a payload converter of its own, so the typed value crosses the Workflow boundary. Add
MicrosoftAgentFrameworkPlugin() to the starter's Client as well, as the sample does, so the starter decodes the result
with the same converter; the starter is a separate process, so this is not a second copy on the Worker.
Stream agent output
agent.run(prompt, stream=True) works as it does natively: the microsoft_agent_framework.invoke_model_streaming
Activity consumes the provider's stream and the Workflow receives the updates once the Activity completes. To forward
updates to a consumer outside the Workflow while the call runs, host a
Workflow Stream on the Workflow and pass streaming_topic to
TemporalChatClient. With a topic set, every model call of that client runs as the streaming Activity, with or without
stream=True, and publishes each ChatResponseUpdate, in its to_dict() form, to the topic; a run without
stream=True gets its response assembled from the same updates. A batch goes out every 100 milliseconds
(streaming_batch_interval) or at 256 updates, whichever comes first. Each batch is one Signal to the Workflow, so it
adds an Event to Event History and counts toward the 10,000 Signals a Workflow Execution can receive. A client without a
topic runs agent.run(prompt) as the plain model Activity and publishes nothing.
Any client can subscribe to the topic by Workflow ID and decode each item with ChatResponseUpdate.from_dict:
The durable result is the same as without streaming. The Activity result is one payload, which has to stay under the
2 MiB payload limit, so the Activity does not record one entry per token. It records one entry per run of
text, one entry per streamed tool call with its argument deltas merged (a provider's final full-arguments update stays
its own entry), and one entry per usage or finish update; the topic still receives every update. If the updates cannot
all be published, the Activity fails with an ApplicationError of type microsoft_agent_framework.StreamError. It is
non-retryable when a retry would fail the same way, such as a batch over the 2 MiB payload limit or one past the run's
10,000-Signal limit; other publish failures are retried. A retry calls the model again and publishes from its first
update again, so a subscriber sees the earlier attempt's updates followed by the whole retry; a consumer that must not
repeat output keys on response_id (a new provider response carries a new one) or on each call's call_id.
Keep long conversations under the history limit
Temporal owns the conversation by default. TemporalChatClient does not store conversations on the provider's side, so
when you pass a session, Agent Framework keeps the transcript in its in-memory history and resends it on every call.
Event History is the durable record and replay rebuilds the session.
Every turn adds Events, and a streamed turn adds one per published batch, so a chat that streams has to Continue-As-New
sooner. When workflow.info().is_continue_as_new_suggested() turns True, serialize the session with
session.to_dict() and hand it to a fresh run with Continue-As-New; the new
run restores it with AgentSession.from_dict. The dict carries the transcript, pending approval state and the
provider's conversation identifier (session.service_session_id). The Agent object, provider connections and spans
do not cross; build the agent again in the new run.
Compaction strategies (TruncationStrategy, SummarizationStrategy(client=TemporalChatClient(...))) run in the
Workflow and bound what each call resends; the summary call is an Activity. They do not shrink Event History.
In the sample each user turn is an Update, so the caller gets the reply from the same call; a lock runs one turn at a
time so the session's history stays in order, an end_chat Signal ends the chat, and a transcript Query reads the
messages from the in-memory history provider's entry in session.state. The run method waits until the chat ends or
Temporal suggests Continue-As-New, lets in-flight Updates finish with workflow.all_handlers_finished, and continues
as new with the serialized session:
To let the provider keep the conversation instead, pass store=True in the agent's default_options or a run's
options. The returned conversation identifier lands in session.service_session_id, the next call carries it, and
only the new turn crosses the Activity boundary.
Compose with an observability plugin
OpenTelemetryPlugin composes with MicrosoftAgentFrameworkPlugin on the same Client, and the Worker inherits both in
registration order. The sample passes add_temporal_spans=True, which adds the StartWorkflow, RunWorkflow,
StartActivity and RunActivity spans; the default OpenTelemetryPlugin() does not emit them.
Agent Framework starts its invoke_agent span from Workflow code through the global tracer provider, so that provider
must be replay-safe: set create_tracer_provider() from temporalio.contrib.opentelemetry as the global provider
before connecting the Client. With a plain OpenTelemetry SDK TracerProvider every replay re-emits the agent spans, and
the plugin warns at Worker and Replayer start. Agent Framework records tool metrics the same way, so wrap a metrics
provider in ReplaySafeMeterProvider. The provider client's own chat span runs inside the Activity with real timings.
The sample's install_tracer_provider, which the Worker calls before Client.connect, is these lines plus a service
name on the resource and the endpoint read from OTEL_EXPORTER_OTLP_ENDPOINT:
import opentelemetry.trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from temporalio.contrib.opentelemetry import create_tracer_provider
provider = create_tracer_provider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter("http://localhost:4317")))
opentelemetry.trace.set_tracer_provider(provider)
One trace then runs from the starter's root span through StartWorkflow:TracedWorkflow, RunWorkflow:TracedWorkflow,
invoke_agent assistant, StartActivity:microsoft_agent_framework.invoke_model and
RunActivity:microsoft_agent_framework.invoke_model to the OpenAI client's chat gpt-4o-mini span. See
Set up tracing for the plugin's options.
Runtime behavior and limitations
- Temporal owns retries. Model calls retry under the
retry_policyonTemporalChatClient; Activity tools and MCP providers take their own. Provider errors are classified by HTTP status: 408, 409, 429 and 5xx stay retryable and honorretry-after-msandretry-afterheaders, as seconds or an HTTP date, through the next retry delay, other 4xx are non-retryable, and errors without a status, such as connection failures, stay retryable. The failure reaches the Workflow as anActivityErrorwhose cause is anApplicationErrorwithtypeset to the provider SDK's exception class name, such asRateLimitErrororAuthenticationError. Match ontype, not on the message. - Credentials and clients stay on the Worker. The Workflow carries a model name. A name the Worker that runs the
Activity does not know fails it with a non-retryable
ApplicationErrorof typeMicrosoftAgentFrameworkUnknownChatClient, so during a rolling deployment add a new name to every Worker before Workflows use it. A factory that raises (anOpenAIChatClientwithoutOPENAI_API_KEYon the Worker, for example) or returnsNonefails the Activity the same way, with typeMicrosoftAgentFrameworkChatClientFactoryError; fix the Worker and start the Workflow again. Calling aTemporalChatClientoutside a Workflow raisesRuntimeError. - What crosses the Activity boundary. Messages and chat options cross in their
to_dict()form, tools as their JSON schema specs, and theChatResponsecomes back the same way; provider SDK objects never enter Event History. A run'sclient_kwargs, such asextra_headers, reach the provider client when they are JSON-compatible. Hosted tools passed as mappings, such as a provider's web search, run on the provider's side. A hosted MCP tool must not carryheadersorauthorizationin Workflow code, because the tool mapping is recorded in Event History; the run fails withMicrosoftAgentFrameworkWorkflowError. Register the headers on the Worker withMicrosoftAgentFrameworkPlugin(hosted_mcp_headers={...}), keyed by the server label or URL, and the Activity adds them before the provider call. A tool object the plugin cannot send to the model fails the Workflow withMicrosoftAgentFrameworkWorkflowError. - Sandbox and clocks. The plugin passes
agent_framework,pydantic_core,annotated_types,msgspec,typing_inspection,opentelemetry,dotenv,mcpandmcp_typesthrough the Workflow sandbox, and installs Workflow-aware stand-ins for the clock and identifier reads in Agent Framework's agent code (default agent and session identifiers, the loop's time budget, span durations) so they replay deterministically. Workers and Replayers both get them. A Worker fails at start, naming the seam and the installed version, if an Agent Framework release moves one of them. - Framework exceptions fail the Workflow. Agent Framework's own exceptions raised in Workflow code, such as
MiddlewareFailure, andMicrosoftAgentFrameworkWorkflowErrorare registered as Workflow failure types, because retrying the Workflow Task cannot change a deterministic failure. - File-backed persistence does not work in a Workflow.
FileHistoryProvider,FileSessionStoreandSessionStoreread and write files on a thread, which the Workflow event loop does not provide, so the first run fails. Use the default in-memory history and carrysession.to_dict()across Continue-As-New, or passstore=Trueto let the provider keep the conversation. - MCP tool classes do not work in
tools=.MCPStdioTool,MCPStreamableHTTPToolandMCPWebsocketToolhold a live connection; useTemporalMCPToolProviderincontext_providers. - Global OpenTelemetry providers must be replay-safe. Agent Framework emits agent spans and tool metrics from
Workflow code; use
create_tracer_provider()andReplaySafeMeterProvider, or every replay re-emits them. - Synchronous tools block the Workflow Task while they run. Keep them quick or make them Activities.
- Out of scope. The Agent Framework Workflows pillar (
WorkflowBuilder, executors, checkpoints,agent-framework-orchestrations), the harness, skills, evaluations, DevUI, declarative agents, hosting, memory and vector providers, and the experimental agent hooks are out of scope. Compose agents with Temporal Workflow code instead:Agent.as_tool(), Signals, Timers and Child Workflows. OpenAI background responses (continuation_token) and embedding clients are not routed through Activities.
Samples
The
Agent Framework plugin samples
cover the ten scenarios on this page: hello world, tools, MCP, human in the loop, middleware, multi-agent, structured
output, streaming, Continue-As-New and OpenTelemetry. The repository's tests run each one against the plugin's scripted
chat client, with no API key. The MCP sample is its own uv project because it needs MCP Python SDK 2. The plugin's
source and README are in the
temporalio/ai-integrations repository.