temporalio-microsoft-agent-framework 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,67 @@
1
+ """Temporal integration for Microsoft Agent Framework.
2
+
3
+ Installed from the ``temporalio-microsoft-agent-framework`` distribution as
4
+ ``temporalio.microsoft_agent_framework``. Build an ``agent_framework.Agent`` inside a
5
+ ``@workflow.defn`` with ``client=TemporalChatClient("model-name")`` and add
6
+ ``MicrosoftAgentFrameworkPlugin(chat_clients=...)`` to the Client or Worker: every model
7
+ round trip runs as a Temporal Activity while the agent's own loop, tools,
8
+ middleware and approvals run in the workflow.
9
+
10
+ The public names load on first access, so importing this package does not
11
+ import the worker-side modules into workflow code.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from typing import TYPE_CHECKING, Any
17
+
18
+ __all__ = [
19
+ "MicrosoftAgentFrameworkPlugin",
20
+ "MicrosoftAgentFrameworkWorkflowError",
21
+ "TemporalChatClient",
22
+ "TemporalMCPToolProvider",
23
+ "workflow",
24
+ ]
25
+
26
+ if TYPE_CHECKING:
27
+ from temporalio.microsoft_agent_framework import workflow
28
+ from temporalio.microsoft_agent_framework._chat_client import TemporalChatClient
29
+ from temporalio.microsoft_agent_framework._mcp import TemporalMCPToolProvider
30
+ from temporalio.microsoft_agent_framework._plugin import (
31
+ MicrosoftAgentFrameworkPlugin,
32
+ )
33
+ from temporalio.microsoft_agent_framework.workflow import (
34
+ MicrosoftAgentFrameworkWorkflowError,
35
+ )
36
+
37
+
38
+ def __dir__() -> list[str]:
39
+ return sorted(set(__all__) | {name for name in globals() if name.startswith("__")})
40
+
41
+
42
+ def __getattr__(name: str) -> Any:
43
+ if name == "MicrosoftAgentFrameworkPlugin":
44
+ from temporalio.microsoft_agent_framework._plugin import (
45
+ MicrosoftAgentFrameworkPlugin,
46
+ )
47
+
48
+ return MicrosoftAgentFrameworkPlugin
49
+ if name == "TemporalChatClient":
50
+ from temporalio.microsoft_agent_framework._chat_client import TemporalChatClient
51
+
52
+ return TemporalChatClient
53
+ if name == "TemporalMCPToolProvider":
54
+ from temporalio.microsoft_agent_framework._mcp import TemporalMCPToolProvider
55
+
56
+ return TemporalMCPToolProvider
57
+ if name == "MicrosoftAgentFrameworkWorkflowError":
58
+ from temporalio.microsoft_agent_framework.workflow import (
59
+ MicrosoftAgentFrameworkWorkflowError,
60
+ )
61
+
62
+ return MicrosoftAgentFrameworkWorkflowError
63
+ if name == "workflow":
64
+ import importlib
65
+
66
+ return importlib.import_module("temporalio.microsoft_agent_framework.workflow")
67
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
@@ -0,0 +1,403 @@
1
+ """The model Activities: one provider round trip per Activity."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ import math
7
+ from collections.abc import Callable, Generator, Mapping
8
+ from contextlib import contextmanager, suppress
9
+ from dataclasses import dataclass, field
10
+ from datetime import datetime, timedelta, timezone
11
+ from email.utils import parsedate_to_datetime
12
+ from functools import wraps
13
+ from typing import Any, TypeVar, cast
14
+
15
+ from agent_framework import SupportsChatGetResponse
16
+
17
+ from temporalio import activity
18
+ from temporalio.contrib.workflow_streams import WorkflowStreamClient
19
+ from temporalio.exceptions import ApplicationError
20
+ from temporalio.microsoft_agent_framework import _serde
21
+ from temporalio.service import RPCError, RPCStatusCode
22
+
23
+ INVOKE_MODEL = "microsoft_agent_framework.invoke_model"
24
+ INVOKE_MODEL_STREAMING = "microsoft_agent_framework.invoke_model_streaming"
25
+ STREAM_ERROR_TYPE = "MicrosoftAgentFrameworkStreamError"
26
+ """``ApplicationError.type`` of a streaming call whose updates did not all reach the topic."""
27
+ UNKNOWN_CHAT_CLIENT_TYPE = "MicrosoftAgentFrameworkUnknownChatClient"
28
+ """``ApplicationError.type`` of a call for a model name the worker does not know."""
29
+ CHAT_CLIENT_FACTORY_ERROR_TYPE = "MicrosoftAgentFrameworkChatClientFactoryError"
30
+ """``ApplicationError.type`` of a call whose chat client factory raised (retryable) or returned ``None`` (not)."""
31
+ MCP_CLIENT_FACTORY_ERROR_TYPE = "MicrosoftAgentFrameworkMCPClientFactoryError"
32
+ """``ApplicationError.type`` of an MCP Activity whose client factory raised (retryable) or returned no ``mcp.Client`` (not)."""
33
+
34
+ ChatClientFactory = Callable[[], SupportsChatGetResponse[Any]]
35
+
36
+
37
+ @dataclass
38
+ class InvokeModelInput:
39
+ """One model round trip: the model name and the serialized request."""
40
+
41
+ model: str
42
+ messages: list[dict[str, Any]]
43
+ options: dict[str, Any] = field(default_factory=dict)
44
+ kwargs: dict[str, Any] = field(default_factory=dict)
45
+ """The run's ``client_kwargs``, such as ``extra_headers``, for the provider client."""
46
+
47
+
48
+ @dataclass
49
+ class InvokeModelStreamingInput(InvokeModelInput):
50
+ """A streamed round trip, optionally published to a workflow stream topic."""
51
+
52
+ streaming_topic: str | None = None
53
+ streaming_batch_interval_seconds: float = 0.1
54
+
55
+
56
+ F = TypeVar("F", bound=Callable[..., Any])
57
+
58
+
59
+ def auto_heartbeater(fn: F) -> F:
60
+ """Heartbeat at half the Activity's heartbeat timeout while ``fn`` runs."""
61
+
62
+ @wraps(fn)
63
+ async def wrapper(*args: Any, **kwargs: Any) -> Any:
64
+ heartbeat_timeout = activity.info().heartbeat_timeout
65
+ heartbeat_task: asyncio.Task[None] | None = None
66
+ if heartbeat_timeout:
67
+ heartbeat_task = asyncio.create_task(
68
+ _heartbeat_every(heartbeat_timeout.total_seconds() / 2)
69
+ )
70
+ try:
71
+ return await fn(*args, **kwargs)
72
+ finally:
73
+ if heartbeat_task is not None:
74
+ heartbeat_task.cancel()
75
+ # Let the cancellation land so no task outlives the Activity.
76
+ await asyncio.wait([heartbeat_task])
77
+
78
+ return cast(F, wrapper)
79
+
80
+
81
+ async def _heartbeat_every(delay: float) -> None:
82
+ while True:
83
+ await asyncio.sleep(delay)
84
+ activity.heartbeat()
85
+
86
+
87
+ def _is_retryable_status(status: int) -> bool:
88
+ return status in (408, 409, 429) or status >= 500
89
+
90
+
91
+ def _status_error(exc: BaseException) -> tuple[BaseException, int] | None:
92
+ """Return the first exception in the cause chain that carries an HTTP status."""
93
+ seen: set[int] = set()
94
+ current: BaseException | None = exc
95
+ while current is not None and id(current) not in seen:
96
+ seen.add(id(current))
97
+ status = getattr(current, "status_code", None)
98
+ if (
99
+ isinstance(status, int)
100
+ and not isinstance(status, bool)
101
+ and 400 <= status < 600
102
+ ):
103
+ return current, status
104
+ current = current.__cause__
105
+ return None
106
+
107
+
108
+ def _headers(exc: BaseException) -> dict[str, str]:
109
+ headers: Any = getattr(exc, "headers", None)
110
+ if headers is None:
111
+ headers = getattr(getattr(exc, "response", None), "headers", None)
112
+ if headers is None:
113
+ return {}
114
+ try:
115
+ return {str(k).lower(): str(v) for k, v in dict(headers).items()}
116
+ except (TypeError, ValueError):
117
+ return {}
118
+
119
+
120
+ MAX_RETRY_AFTER = timedelta(seconds=60)
121
+ """The longest retry delay taken from a ``Retry-After`` hint; a longer hint is capped here."""
122
+
123
+
124
+ def _retry_after(headers: Mapping[str, str]) -> timedelta | None:
125
+ """Read the retry hint: ``retry-after-ms``, else ``retry-after`` as seconds or an HTTP-date.
126
+
127
+ Both forms parse as floats; a value that does not parse falls through to
128
+ the next form. A past date or a non-positive value is no hint, so the
129
+ retry policy's own backoff applies, and the delay is capped at
130
+ ``MAX_RETRY_AFTER`` so a server's hint cannot hold a retry for hours.
131
+ """
132
+ seconds = _seconds(headers.get("retry-after-ms"))
133
+ if seconds is not None:
134
+ seconds /= 1000
135
+ else:
136
+ value = headers.get("retry-after")
137
+ seconds = _seconds(value)
138
+ if seconds is None and value is not None:
139
+ seconds = _seconds_until(value)
140
+ if seconds is None or seconds <= 0:
141
+ return None
142
+ return min(timedelta(seconds=seconds), MAX_RETRY_AFTER)
143
+
144
+
145
+ def _seconds(value: str | None) -> float | None:
146
+ if value is None:
147
+ return None
148
+ try:
149
+ parsed = float(value)
150
+ except ValueError:
151
+ return None
152
+ return parsed if math.isfinite(parsed) else None
153
+
154
+
155
+ def _seconds_until(value: str) -> float | None:
156
+ """Return the seconds until an HTTP-date, or ``None`` when ``value`` is not one."""
157
+ try:
158
+ when = parsedate_to_datetime(value)
159
+ except (TypeError, ValueError):
160
+ return None
161
+ if when.tzinfo is None:
162
+ when = when.replace(tzinfo=timezone.utc)
163
+ return (when - datetime.now(timezone.utc)).total_seconds()
164
+
165
+
166
+ def classify_provider_error(exc: Exception) -> ApplicationError | None:
167
+ """Map a provider error with an HTTP status onto Temporal's retry contract.
168
+
169
+ Agent Framework wraps provider SDK errors in ``ChatClientException`` with
170
+ the SDK error as ``__cause__``, so the chain is walked for a
171
+ ``status_code``. 408, 409, 429 and 5xx stay retryable, with
172
+ ``next_retry_delay`` from ``retry-after-ms`` or ``retry-after`` (seconds,
173
+ including fractions, or an HTTP-date; capped at ``MAX_RETRY_AFTER``) and
174
+ ``x-should-retry`` honored; other 4xx are non-retryable. Returns ``None``
175
+ for an error without a status, which stays retryable as it is.
176
+ """
177
+ found = _status_error(exc)
178
+ if found is None:
179
+ return None
180
+ cause, status = found
181
+ headers = _headers(cause)
182
+ retryable = _is_retryable_status(status)
183
+ should_retry = headers.get("x-should-retry")
184
+ if should_retry == "false":
185
+ retryable = False
186
+ elif should_retry == "true":
187
+ retryable = True
188
+ return ApplicationError(
189
+ str(exc),
190
+ type=type(cause).__name__,
191
+ non_retryable=not retryable,
192
+ next_retry_delay=_retry_after(headers),
193
+ )
194
+
195
+
196
+ @contextmanager
197
+ def _classify_provider_errors(model: str) -> Generator[None, None, None]:
198
+ try:
199
+ yield
200
+ except Exception as err:
201
+ translated = classify_provider_error(err)
202
+ if translated is None:
203
+ raise
204
+ log = (
205
+ activity.logger.error
206
+ if translated.non_retryable
207
+ else activity.logger.warning
208
+ )
209
+ log(
210
+ "Model %r failed with %s (HTTP status error, %s)",
211
+ model,
212
+ translated.type,
213
+ "not retried" if translated.non_retryable else "retried",
214
+ )
215
+ raise translated from err
216
+
217
+
218
+ def _stream_publish_error(err: Exception, model: str, topic: str) -> ApplicationError:
219
+ """Fail a streaming call whose updates did not all reach the topic.
220
+
221
+ A retry calls the model again, so the error is non-retryable when the
222
+ retry would fail the same way: the server refused the batch as invalid
223
+ (over the payload size limit, or past the run's Signal limit) or as over
224
+ its gRPC message limit. Other failures, such as a server outage, stay
225
+ retryable.
226
+ """
227
+ # The gRPC message size limit arrives as RESOURCE_EXHAUSTED with no status
228
+ # of its own, so the message text tells it apart from rate limiting; the
229
+ # Google ADK plugin matches the same text.
230
+ non_retryable = isinstance(err, RPCError) and (
231
+ err.status == RPCStatusCode.INVALID_ARGUMENT
232
+ or (
233
+ err.status == RPCStatusCode.RESOURCE_EXHAUSTED
234
+ and "larger than max" in err.message
235
+ )
236
+ )
237
+ return ApplicationError(
238
+ f"model {model!r}: publish streamed updates to topic {topic!r}: {err}",
239
+ type=STREAM_ERROR_TYPE,
240
+ non_retryable=non_retryable,
241
+ )
242
+
243
+
244
+ def _max_retries(client: Any) -> int:
245
+ """Return the provider SDK's own retry count when the client exposes one.
246
+
247
+ Agent Framework's OpenAI clients keep the SDK client on ``client``; the
248
+ attribute is read by duck typing so no provider package is imported here.
249
+ """
250
+ for candidate in (client, getattr(client, "client", None)):
251
+ retries = getattr(candidate, "max_retries", None)
252
+ if isinstance(retries, int) and not isinstance(retries, bool):
253
+ return retries
254
+ return 0
255
+
256
+
257
+ class ChatClientActivities:
258
+ """Holds the worker-side chat client factories and exposes the model Activities.
259
+
260
+ Factories are called on first use and cached for the worker's lifetime, so
261
+ credentials and connections never enter workflow history.
262
+ """
263
+
264
+ def __init__(
265
+ self,
266
+ factories: Mapping[str, ChatClientFactory],
267
+ *,
268
+ hosted_mcp_headers: Mapping[str, _serde.HostedMCPHeaders] | None = None,
269
+ ) -> None:
270
+ """Store the factories keyed by the model names workflows use.
271
+
272
+ ``hosted_mcp_headers`` holds the headers of hosted MCP tools, keyed by
273
+ the server's label or URL, which the Activities add to the tool before
274
+ the provider call so they never leave the worker.
275
+ """
276
+ self._factories = dict(factories)
277
+ self._clients: dict[str, SupportsChatGetResponse[Any]] = {}
278
+ self._hosted_mcp_headers = dict(hosted_mcp_headers or {})
279
+
280
+ def _client(self, model: str) -> SupportsChatGetResponse[Any]:
281
+ client = self._clients.get(model)
282
+ if client is not None:
283
+ return client
284
+ factory = self._factories.get(model)
285
+ if factory is None:
286
+ known = sorted(self._factories) or "no names"
287
+ raise ApplicationError(
288
+ f"No chat client named {model!r} is registered on this worker; "
289
+ f"MicrosoftAgentFrameworkPlugin(chat_clients=...) knows {known}.",
290
+ type=UNKNOWN_CHAT_CLIENT_TYPE,
291
+ non_retryable=True,
292
+ )
293
+ try:
294
+ # Typed as Any: a factory can return None, which is checked below.
295
+ built: Any = factory()
296
+ except Exception as err:
297
+ # A factory can fail for a while (a secret store or a token
298
+ # endpoint that is down, one worker of many without its
299
+ # environment), so the attempt fails retryably: the call's retry
300
+ # policy or schedule-to-close timeout bounds the wait, another
301
+ # worker can pick the attempt up, and the worker log says why.
302
+ activity.logger.error(
303
+ "Chat client factory for %r raised %s: %s",
304
+ model,
305
+ type(err).__name__,
306
+ err,
307
+ )
308
+ raise ApplicationError(
309
+ f"The chat client factory for {model!r} raised "
310
+ f"{type(err).__name__}: {err}",
311
+ type=CHAT_CLIENT_FACTORY_ERROR_TYPE,
312
+ non_retryable=False,
313
+ ) from err
314
+ if built is None:
315
+ # Wrong on every attempt: fail the run now.
316
+ raise ApplicationError(
317
+ f"The chat client factory for {model!r} returned None instead of a "
318
+ "chat client.",
319
+ type=CHAT_CLIENT_FACTORY_ERROR_TYPE,
320
+ non_retryable=True,
321
+ )
322
+ client = built
323
+ self._clients[model] = client
324
+ retries = _max_retries(client)
325
+ if retries > 0:
326
+ activity.logger.warning(
327
+ "Chat client %r retries %d times inside the provider SDK; disable "
328
+ "those retries (for example AsyncOpenAI(max_retries=0)) so Temporal "
329
+ "owns retries.",
330
+ model,
331
+ retries,
332
+ )
333
+ return client
334
+
335
+ @activity.defn(name=INVOKE_MODEL)
336
+ @auto_heartbeater
337
+ async def invoke_model(self, input: InvokeModelInput) -> dict[str, Any]:
338
+ """Run one model round trip and return the serialized ``ChatResponse``."""
339
+ client = self._client(input.model)
340
+ messages = _serde.load_messages(input.messages)
341
+ options = _serde.load_options(input.options, self._hosted_mcp_headers)
342
+ with _classify_provider_errors(input.model):
343
+ response = await client.get_response(
344
+ messages, options=options, client_kwargs=input.kwargs
345
+ )
346
+ return _serde.dump_response(response)
347
+
348
+ @activity.defn(name=INVOKE_MODEL_STREAMING)
349
+ @auto_heartbeater
350
+ async def invoke_model_streaming(
351
+ self, input: InvokeModelStreamingInput
352
+ ) -> list[dict[str, Any]]:
353
+ """Run one streamed round trip and return the recorded updates.
354
+
355
+ The record holds one entry per function call, usage or finish update
356
+ and one entry per run of text (see ``_serde.StreamRecorder``). With
357
+ ``streaming_topic`` set, every provider update is also published to
358
+ that topic on the workflow's ``WorkflowStream`` as it arrives, batched
359
+ at ``streaming_batch_interval_seconds``.
360
+ """
361
+ client = self._client(input.model)
362
+ messages = _serde.load_messages(input.messages)
363
+ options = _serde.load_options(input.options, self._hosted_mcp_headers)
364
+ recorder = _serde.StreamRecorder()
365
+
366
+ async def consume(publish: Callable[[dict[str, Any]], None] | None) -> None:
367
+ with _classify_provider_errors(input.model):
368
+ async for update in client.get_response(
369
+ messages, stream=True, options=options, client_kwargs=input.kwargs
370
+ ):
371
+ serialized = recorder.add(update)
372
+ if serialized is not None and publish is not None:
373
+ publish(serialized)
374
+
375
+ if input.streaming_topic is None:
376
+ await consume(None)
377
+ return recorder.updates
378
+
379
+ # A batch goes out on the interval or at 256 updates, whichever comes
380
+ # first, so a burst of token deltas stays under the payload limit.
381
+ stream = WorkflowStreamClient.from_within_activity(
382
+ batch_interval=timedelta(seconds=input.streaming_batch_interval_seconds),
383
+ max_batch_size=256,
384
+ )
385
+ topic = stream.topic(input.streaming_topic)
386
+ # The stream's exit sends the last batch and raises the error of a
387
+ # batch the background flush failed to send; either way subscribers
388
+ # missed updates, so the call fails instead of returning as if they
389
+ # had. A model error, or the Activity's cancellation, stays the error.
390
+ await stream.__aenter__()
391
+ try:
392
+ await consume(topic.publish)
393
+ except BaseException:
394
+ with suppress(Exception):
395
+ await stream.__aexit__(None, None, None)
396
+ raise
397
+ try:
398
+ await stream.__aexit__(None, None, None)
399
+ except Exception as err:
400
+ raise _stream_publish_error(
401
+ err, input.model, input.streaming_topic
402
+ ) from err
403
+ return recorder.updates
@@ -0,0 +1,226 @@
1
+ """The workflow-side chat client: every model round trip is an Activity."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import AsyncIterator, Awaitable, Mapping, Sequence
6
+ from datetime import timedelta
7
+ from typing import Any, ClassVar
8
+
9
+ from agent_framework import (
10
+ BaseChatClient,
11
+ ChatAndFunctionMiddlewareTypes,
12
+ ChatMiddlewareLayer,
13
+ ChatResponse,
14
+ ChatResponseUpdate,
15
+ CompactionStrategy,
16
+ FunctionInvocationConfiguration,
17
+ FunctionInvocationLayer,
18
+ Message,
19
+ ResponseStream,
20
+ TokenizerProtocol,
21
+ )
22
+
23
+ from temporalio import workflow
24
+ from temporalio.common import Priority, RetryPolicy
25
+ from temporalio.microsoft_agent_framework import _serde
26
+ from temporalio.microsoft_agent_framework._activities import (
27
+ INVOKE_MODEL,
28
+ INVOKE_MODEL_STREAMING,
29
+ InvokeModelInput,
30
+ InvokeModelStreamingInput,
31
+ )
32
+ from temporalio.microsoft_agent_framework.workflow import (
33
+ MicrosoftAgentFrameworkWorkflowError,
34
+ )
35
+ from temporalio.workflow import (
36
+ ActivityCancellationType,
37
+ ActivityConfig,
38
+ VersioningIntent,
39
+ )
40
+
41
+
42
+ class TemporalChatClient(FunctionInvocationLayer, ChatMiddlewareLayer, BaseChatClient): # type: ignore[type-arg]
43
+ """An Agent Framework chat client that runs each model call as a Temporal Activity.
44
+
45
+ Pass it where you would pass a provider client:
46
+ ``Agent(client=TemporalChatClient("gpt-4o"), ...)`` or
47
+ ``TemporalChatClient("gpt-4o").as_agent(...)``. ``model`` names a factory
48
+ registered with ``MicrosoftAgentFrameworkPlugin(chat_clients=...)`` on the worker;
49
+ the workflow carries only that name. The function-invocation loop, chat and
50
+ function middleware, approvals and compaction run in the workflow as they
51
+ do natively; each provider round trip runs as the
52
+ ``microsoft_agent_framework.invoke_model`` Activity (``microsoft_agent_framework.invoke_model_streaming``
53
+ for ``stream=True``) with the activity options given here. ``summary``
54
+ defaults to the model name; the default timeouts are a 5 minute
55
+ start-to-close and a 10 second heartbeat, and the Activity heartbeats on
56
+ its own at half the heartbeat timeout. A run's ``client_kwargs`` (such as
57
+ ``extra_headers``) cross to the Activity and reach the provider client;
58
+ they are recorded in Event History, so credentials stay in the factory,
59
+ and an ``extra_headers`` entry named ``authorization``, ``x-api-key`` or
60
+ ``api-key`` (in any case) fails the run with
61
+ ``MicrosoftAgentFrameworkWorkflowError``. Unless the caller sets ``store``, the options reach the provider with
62
+ ``store=False``, so the provider keeps no conversation of its own and the
63
+ session's in-memory history is the one transcript; ``store=True`` in the
64
+ agent's or the run's options keeps the service-side conversation path.
65
+
66
+ With ``streaming_topic`` set, every call of this client runs as the
67
+ streaming Activity, with or without ``stream=True``, and publishes each
68
+ update (as its dict form) to that topic on the workflow's
69
+ ``WorkflowStream``, batched at ``streaming_batch_interval`` or 256 updates. ``middleware``,
70
+ ``function_invocation_configuration``, ``compaction_strategy`` and
71
+ ``tokenizer`` are the framework's own client options. A synchronous
72
+ ``def`` tool runs inline on the workflow task (the plugin's worker
73
+ runtime stands in for the thread hand-off the framework would use).
74
+
75
+ The client only works inside a workflow; calling it elsewhere raises
76
+ ``RuntimeError``. Construction itself does no I/O.
77
+ """
78
+
79
+ OTEL_PROVIDER_NAME: ClassVar[str] = "temporal"
80
+ STORES_BY_DEFAULT: ClassVar[bool] = False
81
+
82
+ def __init__(
83
+ self,
84
+ model: str,
85
+ *,
86
+ task_queue: str | None = None,
87
+ schedule_to_close_timeout: timedelta | None = None,
88
+ schedule_to_start_timeout: timedelta | None = None,
89
+ start_to_close_timeout: timedelta | None = timedelta(minutes=5),
90
+ heartbeat_timeout: timedelta | None = timedelta(seconds=10),
91
+ retry_policy: RetryPolicy | None = None,
92
+ cancellation_type: ActivityCancellationType = ActivityCancellationType.TRY_CANCEL,
93
+ versioning_intent: VersioningIntent | None = None,
94
+ summary: str | None = None,
95
+ priority: Priority = Priority.default,
96
+ streaming_topic: str | None = None,
97
+ streaming_batch_interval: timedelta = timedelta(milliseconds=100),
98
+ middleware: Sequence[ChatAndFunctionMiddlewareTypes] | None = None,
99
+ function_invocation_configuration: FunctionInvocationConfiguration
100
+ | None = None,
101
+ compaction_strategy: CompactionStrategy | None = None,
102
+ tokenizer: TokenizerProtocol | None = None,
103
+ ) -> None:
104
+ """Configure the model name, activity options and streaming settings.
105
+
106
+ Raises:
107
+ MicrosoftAgentFrameworkWorkflowError: If ``model`` is not a non-empty string.
108
+ """
109
+ if not isinstance(model, str) or not model:
110
+ raise MicrosoftAgentFrameworkWorkflowError(
111
+ f"TemporalChatClient needs the name of a chat client registered with "
112
+ f"MicrosoftAgentFrameworkPlugin(chat_clients=...), got {model!r}. Credentials and "
113
+ "provider clients live in the worker's factories, not in workflow code."
114
+ )
115
+ super().__init__(
116
+ middleware=middleware,
117
+ function_invocation_configuration=function_invocation_configuration,
118
+ compaction_strategy=compaction_strategy,
119
+ tokenizer=tokenizer,
120
+ )
121
+ self._model = model
122
+ self._streaming_topic = streaming_topic
123
+ self._streaming_batch_interval = streaming_batch_interval
124
+ self._activity_options = ActivityConfig(
125
+ task_queue=task_queue,
126
+ schedule_to_close_timeout=schedule_to_close_timeout,
127
+ schedule_to_start_timeout=schedule_to_start_timeout,
128
+ start_to_close_timeout=start_to_close_timeout,
129
+ heartbeat_timeout=heartbeat_timeout,
130
+ retry_policy=retry_policy,
131
+ cancellation_type=cancellation_type,
132
+ versioning_intent=versioning_intent,
133
+ summary=summary if summary is not None else model,
134
+ priority=priority,
135
+ )
136
+
137
+ @property
138
+ def model(self) -> str:
139
+ """The name of the worker-side chat client this client dispatches to."""
140
+ return self._model
141
+
142
+ def _inner_get_response(
143
+ self,
144
+ *,
145
+ messages: Sequence[Message],
146
+ stream: bool,
147
+ options: Mapping[str, Any],
148
+ **kwargs: Any,
149
+ ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]:
150
+ if not workflow.in_workflow():
151
+ raise RuntimeError(
152
+ "TemporalChatClient only runs inside a Temporal workflow; outside one, "
153
+ "use the provider's chat client directly."
154
+ )
155
+ # What arrives here is the run's client_kwargs, which the provider
156
+ # client reads (the OpenAI client takes extra_headers from them).
157
+ dumped_kwargs = _serde.dump_kwargs(kwargs)
158
+ dumped_messages = _serde.dump_messages(messages)
159
+ dumped_options = _serde.dump_options(options)
160
+ if dumped_options.get("store") is None:
161
+ # The Agent decides who keeps the transcript from an explicit store
162
+ # only; left unset, a provider that stores by default (the OpenAI
163
+ # Responses API) would return a conversation id, and the next call
164
+ # would carry that id and the session's full history both.
165
+ dumped_options["store"] = False
166
+ if stream or self._streaming_topic is not None:
167
+ streaming_input = InvokeModelStreamingInput(
168
+ model=self._model,
169
+ messages=dumped_messages,
170
+ options=dumped_options,
171
+ kwargs=dumped_kwargs,
172
+ streaming_topic=self._streaming_topic,
173
+ streaming_batch_interval_seconds=self._streaming_batch_interval.total_seconds(),
174
+ )
175
+ if stream:
176
+ return ResponseStream(
177
+ self._stream_updates(streaming_input),
178
+ finalizer=lambda updates: ChatResponse.from_updates(
179
+ updates, output_format_type=options.get("response_format")
180
+ ),
181
+ )
182
+ # A topic publishes on every call of this client, so a call without
183
+ # stream=True runs the streaming Activity too and is finalized here.
184
+ return self._get_response_from_stream(
185
+ streaming_input, options.get("response_format")
186
+ )
187
+ return self._get_response(
188
+ InvokeModelInput(
189
+ model=self._model,
190
+ messages=dumped_messages,
191
+ options=dumped_options,
192
+ kwargs=dumped_kwargs,
193
+ ),
194
+ options.get("response_format"),
195
+ )
196
+
197
+ async def _get_response(
198
+ self, input: InvokeModelInput, response_format: Any
199
+ ) -> ChatResponse:
200
+ raw = await workflow.execute_activity(
201
+ INVOKE_MODEL,
202
+ input,
203
+ result_type=dict[str, Any],
204
+ **self._activity_options,
205
+ )
206
+ # The format does not cross the boundary as a class, so the rebuilt
207
+ # response gets it here and parses ``value`` like the streamed path.
208
+ return _serde.load_response(raw, response_format)
209
+
210
+ async def _get_response_from_stream(
211
+ self, input: InvokeModelStreamingInput, response_format: Any
212
+ ) -> ChatResponse:
213
+ updates = [update async for update in self._stream_updates(input)]
214
+ return ChatResponse.from_updates(updates, output_format_type=response_format)
215
+
216
+ async def _stream_updates(
217
+ self, input: InvokeModelStreamingInput
218
+ ) -> AsyncIterator[ChatResponseUpdate]:
219
+ raw = await workflow.execute_activity(
220
+ INVOKE_MODEL_STREAMING,
221
+ input,
222
+ result_type=list[dict[str, Any]],
223
+ **self._activity_options,
224
+ )
225
+ for item in raw:
226
+ yield _serde.load_update(item)