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.
- temporalio/microsoft_agent_framework/__init__.py +67 -0
- temporalio/microsoft_agent_framework/_activities.py +403 -0
- temporalio/microsoft_agent_framework/_chat_client.py +226 -0
- temporalio/microsoft_agent_framework/_mcp.py +339 -0
- temporalio/microsoft_agent_framework/_plugin.py +294 -0
- temporalio/microsoft_agent_framework/_serde.py +578 -0
- temporalio/microsoft_agent_framework/_workflow_runtime.py +221 -0
- temporalio/microsoft_agent_framework/py.typed +1 -0
- temporalio/microsoft_agent_framework/testing.py +193 -0
- temporalio/microsoft_agent_framework/workflow.py +213 -0
- temporalio_microsoft_agent_framework-0.0.1.dist-info/METADATA +539 -0
- temporalio_microsoft_agent_framework-0.0.1.dist-info/RECORD +14 -0
- temporalio_microsoft_agent_framework-0.0.1.dist-info/WHEEL +4 -0
- temporalio_microsoft_agent_framework-0.0.1.dist-info/licenses/LICENSE +21 -0
|
@@ -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)
|