Skip to main content

Microsoft Agent Framework integration

View Markdown

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_KEY in the Worker's environment. The samples use OpenAI's gpt-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 (1.23.0 or newer, below 2), not the agent-framework meta package, so it does not install every provider. The tested range, 1.23.0 through 1.24.0, runs from the floor the plugin was first tested on through the version its lock pins, which CI runs on every change. 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.

Register the plugin on Client.connect(...), as the sample does. The Worker inherits the plugins of the Client it is built from, and only a plugin on the Client sets the Pydantic data converter: a Worker takes its converter from its Client, so a plugin passed to the Worker alone leaves Pydantic models in Workflow inputs and outputs to the default converter. Do not pass it to both; the second copy registers the model Activities twice and the Worker refuses to start with a ValueError. The plugin registers the microsoft_agent_framework.invoke_model and microsoft_agent_framework.invoke_model_streaming Activities and configures the Workflow sandbox for Agent Framework, so the Worker needs no other wiring. Keep the provider imports and the factory in the Worker module, as the sample does: the sandbox loads the Workflow file for every run, and the OpenAI SDK's import tree trips its restrictions, so a provider import in the Workflow file fails the Worker at start.

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 0.4, 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 fails the attempt with a retryable ApplicationError of type MicrosoftAgentFrameworkMCPClientFactoryError, under the same rule as the chat client factories; one that returns something other than an mcp.Client fails the Activity non-retryably with the same type. 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. MCP Activities heartbeat at half the heartbeat_timeout while they run, and temporalio-mcp defaults it to 10 seconds when the provider leaves it unset, so a cancel reaches a request already running on a Worker and a lost Worker is noticed within 10 seconds instead of at the start-to-close timeout; in Temporal Cloud each heartbeat that reaches the Temporal Service is an Action, at most one every 8 seconds of a running request. Pass heartbeat_timeout= on TemporalMCPToolProvider to change it, or None to turn heartbeats off. tool_name_prefix, allowed_tools and approval_mode work as they do on Agent Framework's MCPTool, and tool names are normalized the same way: a character outside A-Za-z0-9_.- becomes - and the separators between the prefix and the name are trimmed, so files/read reaches the model as files-read and prefix gh_ gives gh_files-read. approval_mode is one mode for every tool of the server; the per-tool mapping MCPTool also takes fails the Workflow with MicrosoftAgentFrameworkWorkflowError. 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.

caution

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. It crosses to the model Activity as the strict JSON schema the OpenAI clients send natively for a class (strict: true under the class name, every property required, additionalProperties: false), so the provider holds the model to the schema, and the Workflow parses the reply into response.value:

The Workflow returns the model itself. With the plugin on the Client, it sets the Pydantic data converter unless your Client already has a payload converter of its own, so the typed value crosses the Workflow boundary; a plugin on the Worker alone does not change the converter. 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. response.value parses with the run's response_format from an Agent run or from client.get_response(...) on the TemporalChatClient itself.

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 MicrosoftAgentFrameworkStreamError. 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. Unless you set store yourself, TemporalChatClient sends store=False to the provider, so the provider keeps no conversation of its own (the OpenAI Responses API stores one and returns its identifier when store is left unset), and 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. Your own Workflow state does not cross either: a prompt or an end_chat that arrives while a turn is running sits in the Workflow's fields, so carry those in the input too.

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_policy on TemporalChatClient; Activity tools and MCP providers take their own. Provider errors are classified by HTTP status: 408, 409, 429 and 5xx stay retryable and honor retry-after-ms and retry-after headers through the next retry delay (parsed as numbers, fractions included, or as an HTTP date; a hint above 60 seconds is capped at 60 seconds), other 4xx are non-retryable, and errors without a status, such as connection failures, stay retryable. The failure reaches the Workflow as an ActivityError whose cause is an ApplicationError with type set to the provider SDK's exception class name, such as RateLimitError or AuthenticationError. Match on type, 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 ApplicationError of type MicrosoftAgentFrameworkUnknownChatClient, so during a rolling deployment add a new name to every Worker before Workflows use it. A factory that raises (an OpenAIChatClient without OPENAI_API_KEY on the Worker, for example, or a secret store that is down for a moment) fails the attempt with a retryable ApplicationError of type MicrosoftAgentFrameworkChatClientFactoryError, logged at ERROR on the Worker, so the call's retry_policy or schedule_to_close_timeout bounds the wait and another Worker can pick the attempt up; a factory that returns None fails the Activity non-retryably with the same type. Calling a TemporalChatClient outside a Workflow raises RuntimeError.
  • What crosses the Activity boundary. Messages and chat options cross in their to_dict() form, tools as their JSON schema specs, and the ChatResponse comes back the same way; provider SDK objects never enter Event History. A run's client_kwargs, such as extra_headers, reach the provider client when they are JSON-compatible. They are recorded in Event History, so an extra_headers entry named authorization, x-api-key or api-key (in any case) fails the Workflow with MicrosoftAgentFrameworkWorkflowError; such a header belongs on the provider client in the factory, for example AsyncOpenAI(default_headers=...). Hosted tools passed as mappings, such as a provider's web search, run on the provider's side. A hosted MCP tool must not carry headers or authorization in Workflow code, because the tool mapping is recorded in Event History; the run fails with MicrosoftAgentFrameworkWorkflowError. Register the headers on the Worker with MicrosoftAgentFrameworkPlugin(hosted_mcp_headers={...}), keyed by the server label or URL, and the Activity adds them before the provider call; for an OpenAI connector (a mapping with connector_id), an authorization entry lands in the tool's authorization field as the bare token, because the Responses API takes a connector's OAuth token there, so a leading Bearer is dropped from that one entry, and the other entries stay headers and are passed as written. A tool object the plugin cannot send to the model fails the Workflow with MicrosoftAgentFrameworkWorkflowError.
  • Sandbox and clocks. The plugin passes agent_framework, pydantic_core, annotated_types, msgspec, typing_inspection, opentelemetry, dotenv, mcp and mcp_types through 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 tested range (1.23.0 through 1.24.0), 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, and MicrosoftAgentFrameworkWorkflowError are 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 and FileSessionStore read and write files on a thread, which a Workflow does not have, so the run fails with MicrosoftAgentFrameworkWorkflowError naming the call. Use the default in-memory history and carry session.to_dict() across Continue-As-New, or pass store=True to let the provider keep the conversation.
  • MCP tool classes do not work in tools=. MCPStdioTool, MCPStreamableHTTPTool and MCPWebsocketTool hold a live connection; use TemporalMCPToolProvider in context_providers. The provider exposes tools only: server prompts are not loaded, a result's _meta is not carried to the model, and there is no tool_result_content choice.
  • Global OpenTelemetry providers must be replay-safe. Agent Framework emits agent spans and tool metrics from Workflow code; use create_tracer_provider() and ReplaySafeMeterProvider, 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.