@temporalio/strands-agents 1.24.0 → 2.0.0-rc.1
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.
- package/LICENSE +6 -6
- package/README.md +112 -15
- package/lib/empty-module.d.ts +1 -1
- package/lib/empty-module.js +6 -1
- package/lib/empty-module.js.map +1 -1
- package/lib/index.d.ts +2 -2
- package/lib/index.js +21 -11
- package/lib/index.js.map +1 -1
- package/lib/load-polyfills.js +15 -0
- package/lib/load-polyfills.js.map +1 -1
- package/lib/model-activity.d.ts +57 -2
- package/lib/model-activity.js +100 -6
- package/lib/model-activity.js.map +1 -1
- package/lib/plugin.d.ts +33 -12
- package/lib/plugin.js +127 -26
- package/lib/plugin.js.map +1 -1
- package/lib/strands-errors.d.ts +39 -0
- package/lib/strands-errors.js +130 -0
- package/lib/strands-errors.js.map +1 -0
- package/lib/temporal-activity-tool.d.ts +18 -10
- package/lib/temporal-activity-tool.js +50 -29
- package/lib/temporal-activity-tool.js.map +1 -1
- package/lib/temporal-agent.d.ts +38 -4
- package/lib/temporal-agent.js +68 -16
- package/lib/temporal-agent.js.map +1 -1
- package/lib/temporal-mcp-client.d.ts +113 -17
- package/lib/temporal-mcp-client.js +376 -102
- package/lib/temporal-mcp-client.js.map +1 -1
- package/lib/temporal-mcp-tool.d.ts +3 -1
- package/lib/temporal-mcp-tool.js +26 -16
- package/lib/temporal-mcp-tool.js.map +1 -1
- package/lib/temporal-model.d.ts +32 -0
- package/lib/temporal-model.js +108 -24
- package/lib/temporal-model.js.map +1 -1
- package/lib/workflow.js +17 -7
- package/lib/workflow.js.map +1 -1
- package/package.json +46 -22
- package/src/empty-module.ts +5 -0
- package/src/index.ts +3 -1
- package/src/load-polyfills.ts +20 -1
- package/src/model-activity.ts +153 -8
- package/src/plugin.ts +159 -31
- package/src/strands-errors.ts +147 -0
- package/src/temporal-activity-tool.ts +43 -32
- package/src/temporal-agent.ts +77 -19
- package/src/temporal-mcp-client.ts +407 -91
- package/src/temporal-mcp-tool.ts +9 -9
- package/src/temporal-model.ts +111 -18
- package/lib/failure-converter.d.ts +0 -14
- package/lib/failure-converter.js +0 -61
- package/lib/failure-converter.js.map +0 -1
- package/src/failure-converter.ts +0 -77
package/LICENSE
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
|
|
1
|
+
MIT License
|
|
2
2
|
|
|
3
|
-
Copyright (c)
|
|
3
|
+
Copyright (c) 2026 temporal.io
|
|
4
4
|
|
|
5
5
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
6
|
of this software and associated documentation files (the "Software"), to deal
|
|
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
|
9
9
|
copies of the Software, and to permit persons to whom the Software is
|
|
10
10
|
furnished to do so, subject to the following conditions:
|
|
11
11
|
|
|
12
|
-
The above copyright notice and this permission notice shall be included in
|
|
13
|
-
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
14
|
|
|
15
15
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
16
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
17
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
18
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
19
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
21
|
-
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Strands Agents
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Release stage: Generally Available.
|
|
4
4
|
|
|
5
5
|
This Temporal [Plugin](https://docs.temporal.io/develop/plugins-guide) allows you to run [Strands Agents](https://strandsagents.com/) inside Temporal Workflows, routing model invocations, tool calls, and MCP tool calls through Temporal Activities for durable execution, Temporal-managed retries, and timeouts.
|
|
6
6
|
|
|
@@ -91,6 +91,16 @@ new StrandsPlugin({
|
|
|
91
91
|
|
|
92
92
|
Each `TemporalAgent` carries its own activity options (timeouts, retry policy, task queue, streaming topic) and dispatches to the shared model activity, which resolves the model name against the registered factories at runtime. A name not present in `models` throws inside the activity.
|
|
93
93
|
|
|
94
|
+
Before its first model call, each `TemporalAgent` reads the model's `modelId` and `contextWindowLimit` from its `getConfig()` through the `strandsGetModelConfig` activity, with the agent's activity options but no heartbeat timeout: the read runs synchronously, so it can't heartbeat. Strands' traces and [proactive compression](https://strandsagents.com/docs/user-guide/sdk/agents/conversation-management/#proactive-context-compression) then use the real model's values, as they do outside Temporal. If you scaled `compressionThreshold` by the model's window divided by 200,000 to make up for the missing limit, remove that scaling.
|
|
95
|
+
|
|
96
|
+
A worker model that keeps the conversation server-side, such as `OpenAIModel` with `stateful: true`, gets the agent's `modelState`, such as the last response id, on each model call through `TemporalAgent`, and the agent clears its messages after each turn, as natively. As in Strands, such an agent cannot use a `conversationManager` or `contextManager`; because `TemporalAgent` learns that the model is stateful when it reads the config, it throws at the agent's first invocation instead of at construction. Catch that error, or the workflow task fails and is retried until you remove the manager and redeploy the worker. With no manager given, such an agent keeps Strands' default sliding window manager, which Strands picks before the agent reads the config, where natively it would use `NullConversationManager`. Through the plugin that manager has nothing to trim: the agent clears its messages after each turn, before the manager runs, and a context window overflow reaches the agent as a model error. A custom model that reports `stateful` but does not use `modelState` ran statelessly through earlier versions, with the agent keeping its messages; it now gets only each turn's new message, and an agent that gives it a manager now throws. Report `stateful` as false for such a model to keep the earlier behavior.
|
|
97
|
+
|
|
98
|
+
`OpenAIModel` calls through `TemporalAgent`, stateful or not, work with current `@strands-agents/sdk` releases because the model activities give the model their own cancellation signal (see [Cancellation](#cancellation)). Earlier versions of this plugin passed the agent's signal, which reached the model activity as a plain object, so from `@strands-agents/sdk` 1.15.0 the OpenAI client failed with `signal.addEventListener is not a function` before it sent a request. During a rollout, such calls on a worker without this change fail and are retried until an upgraded worker takes them.
|
|
99
|
+
|
|
100
|
+
Stateful model calls run as their own activities, `strandsInvokeStatefulModel` and `strandsInvokeStatefulModelStreaming`, chosen from the stateful flag that `strandsGetModelConfig` returns, so a run that uses a stateful model needs the workflow and the config activity from the same version. An earlier workflow that reads this version's config schedules `invokeModel`, and this version then fails to replay the run with a nondeterminism error. This version's workflow that reads an earlier config, which has no flag, keeps the stateless path for the rest of the run, and an upgraded worker fails each of its model calls with a non-retryable `StatefulModelOnStatelessPath` error. Changing a worker model between stateful and stateless, such as adding `stateful: true` to a deployed `OpenAIModel`, also applies only to new runs: an open run keeps the mode its config read recorded, and its model calls fail with `StatefulModelOnStatelessPath`, or with `StatelessModelOnStatefulPath` when the model became stateless. None of these runs recovers. The agent's `invoke()` throws an `ActivityFailure` whose cause has that type, so unless the workflow catches it, the run fails; reset a run you want to continue. Roll out with Worker Versioning, keeping each run's workflow and activity workers on one version, including any task queue set in `activityOptions`. Without it, stop the runs that use a stateful model, replace every worker on those task queues, and then start new runs.
|
|
101
|
+
|
|
102
|
+
The plugin's activities are named `invokeModel`, `invokeModelStreaming`, `strandsGetModelConfig`, `strandsInvokeStatefulModel`, `strandsInvokeStatefulModelStreaming`, and `{name}-listTools` and `{name}-callTool` for each MCP client. A different activity with one of these names (your own activity, another integration's activity, or one from another `StrandsPlugin` that is not the same) fails with `Duplicate registration of Activity '<name>'`. If it is registered before `StrandsPlugin` (in the worker's `activities` or by an earlier plugin), creating the worker fails. If a plugin applied after `StrandsPlugin` replaces one, `worker.run()` fails before the worker polls. `Worker.create` applies the worker's `plugins` in order, then the `NativeConnection`'s. Rename your activity, run the other integration on its own worker and task queue, or put every model and MCP client in one `StrandsPlugin`. The same instance on the `NativeConnection` and the worker still works. Two instances count as the same only when they share the `models` object (or both omit it) and, for each MCP server name they share, the same factory function and idle timeout, as when both are built from one options object. Two equal object literals are refused.
|
|
103
|
+
|
|
94
104
|
## Retries
|
|
95
105
|
|
|
96
106
|
`TemporalAgent` disables Strands' built-in `ModelRetryStrategy` so retries are handled exclusively by Temporal. Configure retries via `activityOptions.retry` on `TemporalAgent`, and on the activity options accepted by `workflow.activityAsTool`, `workflow.activityAsHook`, and `TemporalMCPClient`:
|
|
@@ -104,11 +114,43 @@ new TemporalAgent({
|
|
|
104
114
|
});
|
|
105
115
|
```
|
|
106
116
|
|
|
107
|
-
|
|
117
|
+
Omit `retryStrategy` or pass `retryStrategy: null` to `new TemporalAgent(...)`. Any non-null strategy throws; put the retry config on the activity options instead.
|
|
118
|
+
|
|
119
|
+
The plugin turns Strands' terminal errors (`ContextWindowOverflowError`, `MaxTokensError` and `StructuredOutputError`) into non-retryable `ApplicationFailure`s whose `type` is the error's name:
|
|
120
|
+
|
|
121
|
+
- A `ContextWindowOverflowError` from the model activity is not retried. It reaches the agent as Strands' own error, so its conversation manager trims the conversation and calls the model again, as it does outside Temporal. Each round is a new model activity with the whole conversation as its input, recorded in history, and the worker logs it at DEBUG without counting it in its activity failure metric. [Proactive compression](https://strandsagents.com/docs/user-guide/sdk/agents/conversation-management/#proactive-context-compression) trims before the call instead.
|
|
122
|
+
- An activity of yours that throws one of the three fails without retries.
|
|
123
|
+
- The agent throws `MaxTokensError` and `StructuredOutputError` in workflow code. When one of the three ends a `TemporalAgent` turn, `invoke()` and `stream()` throw a non-retryable `ApplicationFailure` of that type, with the original error as its `cause`, so the run, or the update, fails with it instead of the workflow task failing on every attempt.
|
|
124
|
+
|
|
125
|
+
A model activity that fails for good, times out or is cancelled ends the turn with that activity's `ActivityFailure`, so the run fails or is cancelled. Strands wraps it in a `ModelError`, which on its own would only fail the workflow task. Other errors Strands raises in workflow code, such as a `ModelError` for a model response it cannot parse, still fail the workflow task on every attempt.
|
|
126
|
+
|
|
127
|
+
Workflow code that catches these errors around `invoke()` by class sees the `ApplicationFailure` or `ActivityFailure` instead: match on the failure's `type`, or read the original error from its `cause`. Your own activity interceptors, and those of plugins listed before `StrandsPlugin`, run outside the plugin's and see the `ApplicationFailure`; those of plugins listed after it run inside and see the original error.
|
|
128
|
+
|
|
129
|
+
If your worker lists one of these errors in `workflowFailureErrorTypes`, the run used to fail with a retryable failure, so a workflow retry policy started another run. The plugin's failure is non-retryable, so that run is no longer retried.
|
|
130
|
+
|
|
131
|
+
## Cancellation
|
|
132
|
+
|
|
133
|
+
Workflow code can pass a `cancelSignal` to `agent.invoke()` and compose signals with `AbortSignal.any()`. `AbortSignal.timeout()` throws a `DeterminismViolationError` in workflows because its native timer is not recorded in Temporal history. To abort a signal after a delay, use Temporal's `sleep()` and an `AbortController`.
|
|
134
|
+
|
|
135
|
+
The model gets the model activity's cancellation signal as `cancelSignal`. Once the worker learns that the activity was cancelled, the signal is aborted. Only a model that passes `cancelSignal` to its client stops the call; the model activity then ends as cancelled. In `@strands-agents/sdk` 1.19.0, `OpenAIModel` and `BedrockModel` do this, but `AnthropicModel`, `GoogleModel` and `VercelModel` ignore `cancelSignal`. With a model that ignores it, the provider call keeps running after cancellation, and the activity can still complete with the model's result. The worker learns of the cancellation through the activity's heartbeats. The model activities heartbeat at half of `activityOptions.heartbeatTimeout`, which defaults to 10 seconds. With `heartbeatTimeout: 0`, they don't heartbeat, and the model call runs to completion after its activity is cancelled. `agent.cancel()` in workflow code does not cancel the model activity.
|
|
136
|
+
|
|
137
|
+
Through `TemporalAgent`, cancelling the workflow during a model call cancels the model activity. With the default `TRY_CANCEL` cancellation type, the workflow does not wait for the activity: the run is cancelled at once (see [Retries](#retries)), and the model call is aborted once the worker learns of the cancellation. With `WAIT_CANCELLATION_COMPLETED`, the workflow waits for the model activity to end. If it ends as cancelled, so does the run. If it completes instead, as it can with a model that ignores `cancelSignal` or with `heartbeatTimeout: 0`, the agent gets the model's result and the turn carries on, so the run can complete normally rather than as cancelled:
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
import { ActivityCancellationType } from '@temporalio/workflow';
|
|
141
|
+
|
|
142
|
+
new TemporalAgent({
|
|
143
|
+
activityOptions: {
|
|
144
|
+
startToCloseTimeout: '60 seconds',
|
|
145
|
+
heartbeatTimeout: '10 seconds',
|
|
146
|
+
cancellationType: ActivityCancellationType.WAIT_CANCELLATION_COMPLETED,
|
|
147
|
+
},
|
|
148
|
+
});
|
|
149
|
+
```
|
|
108
150
|
|
|
109
151
|
## Snapshots
|
|
110
152
|
|
|
111
|
-
`TemporalAgent
|
|
153
|
+
`TemporalAgent` inherits Strands' `takeSnapshot()` and `loadSnapshot()`. These capture and restore in-memory agent state without external I/O; Temporal's event history still provides durability. Strands uses them to reset a subagent before each tool call made with `agent.asTool()` or automatic wrapping via `tools: [subagent]`. Each call starts from the state captured when the tool was created. To retain the subagent's context across calls, use `agent.asTool({ preserveContext: true })`.
|
|
112
154
|
|
|
113
155
|
## Structured Output
|
|
114
156
|
|
|
@@ -131,7 +173,7 @@ export async function myWorkflow(prompt: string) {
|
|
|
131
173
|
|
|
132
174
|
## Streaming
|
|
133
175
|
|
|
134
|
-
To forward model chunks to external consumers, pass `streamingTopic: '...'` to `TemporalAgent` and host a workflow stream on the workflow via [`@temporalio/workflow-streams`](../workflow-streams). Each model stream event is published on the named topic from inside the model activity; subscribers read via `WorkflowStreamClient`. Chunks are batched on `streamingBatchInterval` (default `'100 milliseconds'`).
|
|
176
|
+
To forward model chunks to external consumers, pass `streamingTopic: '...'` to `TemporalAgent` and host a workflow stream on the workflow via [`@temporalio/workflow-streams`](../workflow-streams). Each model stream event is published on the named topic from inside the model activity; subscribers read via `WorkflowStreamClient`. Chunks are batched on `streamingBatchInterval` (default `'100 milliseconds'`). If a model call fails after it published events, for example on a context overflow the agent then trims, those events stay on the topic and the next call publishes a whole message after them; each message starts with its own `modelMessageStartEvent`.
|
|
135
177
|
|
|
136
178
|
```ts
|
|
137
179
|
import { WorkflowStream } from '@temporalio/workflow-streams/workflow';
|
|
@@ -156,7 +198,9 @@ for await (const item of stream.subscribe(['events'])) {
|
|
|
156
198
|
|
|
157
199
|
## Tools
|
|
158
200
|
|
|
159
|
-
Wrap an activity registered on the worker with `workflow.activityAsTool(name, options)
|
|
201
|
+
Wrap an activity registered on the worker with `workflow.activityAsTool(name, options)`.
|
|
202
|
+
|
|
203
|
+
`description` is optional and is omitted from the tool specification when not supplied. Supply a description to help the model decide when to call the tool. An explicitly empty description is rejected by Strands.
|
|
160
204
|
|
|
161
205
|
```ts
|
|
162
206
|
// activities/index.ts
|
|
@@ -220,34 +264,34 @@ agent.addHook(AfterToolCallEvent, auditCallback);
|
|
|
220
264
|
|
|
221
265
|
Strands supports interrupts via `toolContext.interrupt(...)` and `event.interrupt(...)`. Both work with the plugin: `agent.invoke()` returns `AgentResult` with `stopReason: 'interrupt'` and `interrupts: [...]`. Pair this with a signal handler that supplies responses, then resume by calling `agent.invoke(responses)`.
|
|
222
266
|
|
|
223
|
-
Interrupts also survive the activity boundary when raised from an `activityAsTool`-wrapped activity.
|
|
267
|
+
Interrupts also survive the activity boundary when raised from an `activityAsTool`-wrapped activity. An activity interceptor the plugin adds to the worker packages the interrupt as a typed, non-retryable `ApplicationFailure`, and `TemporalActivityTool` re-raises it through the agent's interrupt machinery on the workflow side, so `AgentResult.interrupts` is populated just like the in-workflow case. From an activity, throw an error with an `interrupts` array, the shape of Strands' `InterruptError`: each entry needs a `toJSON()` that returns an object with a unique string `name` and, optionally, a `reason`, all JSON-encodable, whatever payload converter the worker uses. With several entries, the agent pauses at each one in turn. A malformed interrupt fails the activity without retries, as type `StrandsMalformedInterrupt`, and reaches the model as an error tool result. Interrupts are benign failures: the worker logs them at DEBUG and does not count them in its activity failure metric.
|
|
224
268
|
|
|
225
|
-
|
|
269
|
+
The interceptor runs only on workers that register `StrandsPlugin`, so register it on every worker that runs an `activityAsTool` activity, including activity-only workers on other task queues.
|
|
226
270
|
|
|
227
|
-
|
|
228
|
-
const client = new Client({ /* ... */, plugins: [new StrandsPlugin({ models })] });
|
|
229
|
-
```
|
|
271
|
+
The plugin keeps the failure converter your client and worker set with `dataConverter.failureConverterPath`, for example to [encode failure messages](https://docs.temporal.io/failure-converter). For activity-tool interrupts to work, your converter must decode a failure of type `StrandsInterrupt` to an `ApplicationFailure` with that type and its details, as the SDK's default converter does. Context overflow recovery reads the failure's type from the failure itself, so it works with any converter built on the SDK's default one.
|
|
230
272
|
|
|
231
273
|
## Continue-as-new
|
|
232
274
|
|
|
233
|
-
A chat-style workflow accumulates history with every turn and will eventually hit Temporal's per-workflow history limit. `workflowInfo().continueAsNewSuggested` flips true once the server decides history has grown large enough; check it after each turn and hand off to a fresh run, carrying `agent.messages` as input:
|
|
275
|
+
A chat-style workflow accumulates history with every turn and will eventually hit Temporal's per-workflow history limit. `workflowInfo().continueAsNewSuggested` flips true once the server decides history has grown large enough; check it after each turn and hand off to a fresh run, carrying `agent.messages` and `agent.modelState` as input. A stateful model clears the messages after each turn and keeps its context in the model state, such as the last response id; a run that carries only the messages starts the model's conversation over:
|
|
234
276
|
|
|
235
277
|
```ts
|
|
236
278
|
import { defineSignal, setHandler, condition, continueAsNew, workflowInfo } from '@temporalio/workflow';
|
|
237
279
|
import { TemporalAgent } from '@temporalio/strands-agents';
|
|
238
|
-
import type { Message } from '@strands-agents/sdk';
|
|
280
|
+
import type { JSONValue, Message } from '@strands-agents/sdk';
|
|
239
281
|
|
|
240
282
|
export const userSays = defineSignal<[string]>('userSays');
|
|
241
283
|
export const endChat = defineSignal('endChat');
|
|
242
284
|
|
|
243
285
|
export interface ChatInput {
|
|
244
286
|
messages?: Message[];
|
|
287
|
+
modelState?: Record<string, JSONValue>;
|
|
245
288
|
}
|
|
246
289
|
|
|
247
290
|
export async function chatWorkflow(input: ChatInput = {}): Promise<void> {
|
|
248
291
|
const agent = new TemporalAgent({
|
|
249
292
|
activityOptions: { startToCloseTimeout: '60 seconds' },
|
|
250
293
|
messages: input.messages,
|
|
294
|
+
modelState: input.modelState,
|
|
251
295
|
});
|
|
252
296
|
|
|
253
297
|
const pending: string[] = [];
|
|
@@ -260,7 +304,7 @@ export async function chatWorkflow(input: ChatInput = {}): Promise<void> {
|
|
|
260
304
|
if (done) return;
|
|
261
305
|
await agent.invoke(pending.shift()!);
|
|
262
306
|
if (workflowInfo().continueAsNewSuggested) {
|
|
263
|
-
await continueAsNew<typeof chatWorkflow>({ messages: agent.messages });
|
|
307
|
+
await continueAsNew<typeof chatWorkflow>({ messages: agent.messages, modelState: agent.modelState.getAll() });
|
|
264
308
|
}
|
|
265
309
|
}
|
|
266
310
|
}
|
|
@@ -302,6 +346,19 @@ new Worker({
|
|
|
302
346
|
|
|
303
347
|
Each factory returns a fully configured `McpClient`. The connection is opened lazily on first use rather than at worker startup.
|
|
304
348
|
|
|
349
|
+
A factory result must have callable `connect()`, `disconnect()`, `listTools()` and `callTool()` methods. An invalid result now fails the Activity without retries with type `MCPClientFactoryTypeError`. Fix these factories before upgrading; the next attempt of an in-flight Activity also runs this check.
|
|
350
|
+
|
|
351
|
+
`TemporalMCPClient` takes `prefix` and `toolFilters`, which work as on Strands' `McpClient`: the agent sees `{prefix}_{name}`, and string and `RegExp` filters match the server's tool name. A callback filter receives the workflow-side `TemporalMCPTool` and runs in the workflow, so it must be deterministic. Tool calls send the server's own name. Set `prefix` here, not on the factory's `McpClient`: a factory `McpClient` with a `prefix` fails the `{name}-listTools` activity, which is retried until the worker is fixed. The factory's `toolFilters` still apply on the worker, before these. Each listing records the tools that the factory's `McpClient` returns in the workflow history, before these filters apply; for a server with many tools, filter on the factory or set `cacheTools: true`.
|
|
352
|
+
|
|
353
|
+
```ts
|
|
354
|
+
const github = new TemporalMCPClient({
|
|
355
|
+
server: 'github',
|
|
356
|
+
prefix: 'gh',
|
|
357
|
+
toolFilters: { allowed: ['search_issues', /get_/] },
|
|
358
|
+
activityOptions: { startToCloseTimeout: '30 seconds' },
|
|
359
|
+
});
|
|
360
|
+
```
|
|
361
|
+
|
|
305
362
|
By default, `TemporalMCPClient` re-lists the server's tools (via `{name}-listTools`) on every agent turn, so an MCP server that is restarted or redeployed mid-workflow — with tools added, removed, or renamed — is picked up. To list the tools just once at the beginning of the workflow and reuse that schema for the workflow's lifetime (one fewer activity per turn), set `cacheTools: true`:
|
|
306
363
|
|
|
307
364
|
```ts
|
|
@@ -312,7 +369,9 @@ const echo = new TemporalMCPClient({
|
|
|
312
369
|
});
|
|
313
370
|
```
|
|
314
371
|
|
|
315
|
-
|
|
372
|
+
Tool names must be unique on one agent, as in Strands: two tools may not have the same name, or names that differ only by `-` or `_`. Strands refuses such a name when the agent first lists its MCP servers. After each tool round, the agent re-lists its `cacheTools: false` servers, checks their new listings against each other and against its other tools, and then applies them together, so a name can move from one server to another. When a re-listed server starts listing a name that another tool of the agent has, such as a tool of another server or a tool in `tools`, or lists a name twice or one that Strands rejects, the listing throws Strands' `ToolValidationError` and leaves the agent's tools as they were. Like other errors thrown in workflow code, it fails the workflow task on every attempt, until the run is reset or terminated. To fix it, set a `prefix` (or a different one) on one server's `TemporalMCPClient`, or drop the tool with its `toolFilters`. Both are workflow code, and they rename or drop that server's tools in every replay: an open run fails to replay if its model called such a tool, if its workflow code acted on one among the agent's tools, or if it met the error and went on. So deploy such a change with Worker Versioning, and reset a run that met the error to before the first listing that returned a tool the change renames or drops. Or, without changing workflow code, stop the server from listing the name, or drop the tool with the `toolFilters` of the `McpClient` that the server's factory returns. The round's listings are in the run's history, and the agent checks them only after the last one, so then reset the run to before that tool round's first `{name}-listTools` activity, or, if you changed a `cacheTools: true` server, to before its only listing. For a `cacheTools: false` server, a name is the server's from the listing that added its tool under it until a re-listing of that server drops the name: a tool you put under it is replaced at the next listing, and removed by the listing that drops the name. A `cacheTools: true` server is not listed again, so a tool you put under one of its names stays for the run.
|
|
373
|
+
|
|
374
|
+
To amortize connection setup, the `{name}-listTools` and `{name}-callTool` activities share one MCP connection per server and reuse it across calls. Each `StrandsPlugin` instance has its own connections: workers that use the same instance (for example through the `NativeConnection`) share them, and another `StrandsPlugin` opens its own through its own factory, even for the same server name. The connection is disconnected after it sits idle for `mcpConnectionIdleTimeout` (default 5 minutes), and when the last worker using the plugin stops; a call still running keeps it open until it finishes. The idle timer resets on every reuse. `mcpConnectionIdleTimeout` accepts a millisecond number or a duration string (e.g. `'30 seconds'`), like `startToCloseTimeout`:
|
|
316
375
|
|
|
317
376
|
```ts
|
|
318
377
|
new StrandsPlugin({
|
|
@@ -323,7 +382,7 @@ new StrandsPlugin({
|
|
|
323
382
|
|
|
324
383
|
## Observability
|
|
325
384
|
|
|
326
|
-
`StrandsPlugin` composes cleanly with [`OpenTelemetryPlugin`](../interceptors-opentelemetry). Register
|
|
385
|
+
`StrandsPlugin` composes cleanly with [`OpenTelemetryPlugin`](../interceptors-opentelemetry). Register `OpenTelemetryPlugin` on the client and the worker, and `StrandsPlugin` on the worker. List `OpenTelemetryPlugin` first, so that an activity span ending in an interrupt sees the benign failure and is not marked as an error. You'll get OTel spans around the model, tool, and MCP activities the plugin schedules, plus any spans Strands itself emits inside `invoke`:
|
|
327
386
|
|
|
328
387
|
```ts
|
|
329
388
|
import { OpenTelemetryPlugin } from '@temporalio/interceptors-opentelemetry';
|
|
@@ -349,3 +408,41 @@ const worker = await Worker.create({
|
|
|
349
408
|
```
|
|
350
409
|
|
|
351
410
|
See the [OpenTelemetry interceptor README](../interceptors-opentelemetry) for exporter setup.
|
|
411
|
+
|
|
412
|
+
## Pre-built workflow bundles
|
|
413
|
+
|
|
414
|
+
If you build workflow code with `bundleWorkflowCode` instead of giving the worker `workflowsPath`, pass the plugin to the bundler as well as to the worker. Its bundler hook stubs modules that workflow code cannot load.
|
|
415
|
+
|
|
416
|
+
```ts
|
|
417
|
+
import { bundleWorkflowCode } from '@temporalio/worker';
|
|
418
|
+
import { StrandsPlugin } from '@temporalio/strands-agents';
|
|
419
|
+
|
|
420
|
+
const bundle = await bundleWorkflowCode({
|
|
421
|
+
workflowsPath: require.resolve('./workflows'),
|
|
422
|
+
plugins: [new StrandsPlugin()],
|
|
423
|
+
});
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
The bundle holds the plugin's workflow code, such as `TemporalAgent`, so rebuild it when you upgrade the plugin: a bundle built with an earlier version keeps that version's behavior in workflow code, and nothing warns about it.
|
|
427
|
+
|
|
428
|
+
## Upgrading from 1.24 and earlier
|
|
429
|
+
|
|
430
|
+
This version changes what workflow code does in the cases below, with no version gate. A run that started on an earlier version can fail to replay on this one with a nondeterminism error:
|
|
431
|
+
|
|
432
|
+
- **Model config read.** Before its first model call, each agent now reads the model's config through the `strandsGetModelConfig` activity, so a run whose agent ran before the upgrade fails to replay.
|
|
433
|
+
- **Your failure converter.** Earlier versions replaced the failure converter your client and worker set with the plugin's, so workflow code now decodes the failures of earlier runs with yours. If yours decodes a failure into another error than the SDK's default converter and that changes which commands the workflow issues, the run fails to replay. If it only changes a value the workflow keeps or returns, the run replays without error and continues with the new value, so replay tests do not catch it.
|
|
434
|
+
- **Errors from a turn.** Workflow code that catches errors from `invoke()` by class now gets an `ApplicationFailure` or `ActivityFailure` instead of the Strands error. If it acts on the difference, the run fails to replay.
|
|
435
|
+
- **Context overflow.** A run whose workflow code caught a context overflow from the agent now trims and calls the model again on replay instead, and fails to replay.
|
|
436
|
+
- **Snapshots and agents as tools.** `takeSnapshot()` and `loadSnapshot()` now use Strands' implementations instead of throwing, enabling default `agent.asTool()` calls and automatic wrapping via `tools: [subagent]`. The workflow sandbox also exposes `AbortSignal` from its existing `AbortController`, so nested calls, including those using `preserveContext: true`, can compose their cancellation signals instead of returning an `AbortSignal is not defined` tool error. A run whose workflow code caught the previous snapshot error, or whose model received the cancellation-signal error, can take a different path and fail to replay. This is a breaking change for those runs: keep them on their previous worker version until they finish, or reset to a point before the affected call on upgraded workers.
|
|
437
|
+
- **Activity tools without descriptions.** An unspecified description is now omitted instead of defaulting to an empty string, so agent construction succeeds. A run whose workflow caught the earlier tool-registration `ToolValidationError` can take a different path on replay and fail to replay.
|
|
438
|
+
- **Duplicate MCP tool names.** When a re-listed server starts listing a name that another tool of the agent has, the listing now throws Strands' `ToolValidationError`, where earlier versions let the new tool replace the other one. A run in which that happened fails to replay after that tool round's last listing. A re-listed server that lists one name twice is now refused too, where earlier versions kept the later copy. For a name that differs from another tool's only by `-` or `_`, or that Strands rejects, earlier versions threw Strands' own error from that server's hook, after applying part of its listing and before listing the servers whose hooks came after it. Now every re-listed server lists first, and the refusal applies nothing; a `-`/`_` name that moves from one server to another is now accepted. So a run whose workflow code caught such an error and went on can fail to replay. The new tools of the re-listed servers are now applied together, once all of them have listed, and not at all if a listing fails; earlier versions applied each server's tools as soon as it listed. So workflow code that reads the agent's tools in between, or after catching a failed listing, can take another path. And a tool that workflow code put under the name of a server's tool is now removed by the listing in which that server drops the name, where earlier versions kept it. A run whose model or workflow code used that tool after that listing can fail to replay, though no names clashed.
|
|
439
|
+
|
|
440
|
+
Let those runs finish before you upgrade, or keep them on the earlier version with Worker Versioning. The same applies to rolling back: a run that started on this version can fail to replay on an earlier one, so let it finish before you roll back.
|
|
441
|
+
|
|
442
|
+
Other changes when you upgrade:
|
|
443
|
+
|
|
444
|
+
- A run whose workflow task keeps failing on a Strands terminal error, or on a model call that failed or was cancelled, fails or is cancelled once this version runs, and one stuck on a context overflow trims and continues, as long as it started on a build that already reads the model config. A run started on 1.24 and stuck this way fails to replay at the config read instead: reset or terminate it.
|
|
445
|
+
- Rebuild [pre-built workflow bundles](#pre-built-workflow-bundles) with this version.
|
|
446
|
+
- `StrandsFailureConverter` is removed. Remove imports of it, and any `failureConverterPath` that points at `@temporalio/strands-agents/lib/failure-converter`.
|
|
447
|
+
- The plugin no longer needs to be on the client, where it now does nothing, so you can remove it there.
|
|
448
|
+
- A `prefix` on the `McpClient` that an `mcpClients` factory returns now fails the `{name}-listTools` activity, which is retried until it's removed. Set `prefix` on `TemporalMCPClient` instead. Earlier versions listed the prefixed names, but every call of those tools failed. A run that listed through such a factory has the prefixed names in its history, so it can fail to replay once the prefix moves to `TemporalMCPClient`.
|
package/lib/empty-module.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
declare class WorkflowSandboxStub {
|
|
2
2
|
}
|
|
3
|
-
export { WorkflowSandboxStub as StreamableHTTPClientTransport, WorkflowSandboxStub as StdioClientTransport, WorkflowSandboxStub as SSEClientTransport, };
|
|
3
|
+
export { WorkflowSandboxStub as StreamableHTTPClientTransport, WorkflowSandboxStub as StdioClientTransport, WorkflowSandboxStub as SSEClientTransport, WorkflowSandboxStub as EventSource, WorkflowSandboxStub as EventSourceParserStream, };
|
|
4
4
|
export default WorkflowSandboxStub;
|
package/lib/empty-module.js
CHANGED
|
@@ -10,12 +10,17 @@
|
|
|
10
10
|
// at build time. Export every name MCP/Strands' static imports reach as a
|
|
11
11
|
// no-op class. Workflow code never instantiates these — the real transports
|
|
12
12
|
// run worker-side from the user's `mcpClients` factories.
|
|
13
|
+
// MCP v2 bundles its HTTP transport into the client entrypoint and statically
|
|
14
|
+
// imports EventSourceParserStream from the rewritten eventsource-parser/stream
|
|
15
|
+
// module, so that name must also remain available to the bundler.
|
|
13
16
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
14
|
-
exports.SSEClientTransport = exports.StdioClientTransport = exports.StreamableHTTPClientTransport = void 0;
|
|
17
|
+
exports.EventSourceParserStream = exports.EventSource = exports.SSEClientTransport = exports.StdioClientTransport = exports.StreamableHTTPClientTransport = void 0;
|
|
15
18
|
class WorkflowSandboxStub {
|
|
16
19
|
}
|
|
17
20
|
exports.StreamableHTTPClientTransport = WorkflowSandboxStub;
|
|
18
21
|
exports.StdioClientTransport = WorkflowSandboxStub;
|
|
19
22
|
exports.SSEClientTransport = WorkflowSandboxStub;
|
|
23
|
+
exports.EventSource = WorkflowSandboxStub;
|
|
24
|
+
exports.EventSourceParserStream = WorkflowSandboxStub;
|
|
20
25
|
exports.default = WorkflowSandboxStub;
|
|
21
26
|
//# sourceMappingURL=empty-module.js.map
|
package/lib/empty-module.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"empty-module.js","sourceRoot":"","sources":["../src/empty-module.ts"],"names":[],"mappings":";AAAA,sEAAsE;AACtE,0DAA0D;AAC1D,0EAA0E;AAC1E,yCAAyC;AACzC,EAAE;AACF,uDAAuD;AACvD,wGAAwG;AACxG,2EAA2E;AAC3E,0EAA0E;AAC1E,4EAA4E;AAC5E,0DAA0D;;;
|
|
1
|
+
{"version":3,"file":"empty-module.js","sourceRoot":"","sources":["../src/empty-module.ts"],"names":[],"mappings":";AAAA,sEAAsE;AACtE,0DAA0D;AAC1D,0EAA0E;AAC1E,yCAAyC;AACzC,EAAE;AACF,uDAAuD;AACvD,wGAAwG;AACxG,2EAA2E;AAC3E,0EAA0E;AAC1E,4EAA4E;AAC5E,0DAA0D;AAC1D,8EAA8E;AAC9E,+EAA+E;AAC/E,kEAAkE;;;AAElE,MAAM,mBAAmB;CAAG;AAGH,4DAA6B;AAC7B,mDAAoB;AACpB,iDAAkB;AAClB,0CAAW;AACX,sDAAuB;AAEhD,kBAAe,mBAAmB,CAAC"}
|
package/lib/index.d.ts
CHANGED
|
@@ -2,8 +2,8 @@ import './load-polyfills';
|
|
|
2
2
|
export { StrandsPlugin, type StrandsPluginOptions } from './plugin';
|
|
3
3
|
export { TemporalAgent, type TemporalAgentOptions } from './temporal-agent';
|
|
4
4
|
export { TemporalModel, type TemporalModelOptions } from './temporal-model';
|
|
5
|
-
export { TemporalMCPClient, type TemporalMCPClientOptions, type McpToolInfo, type CallToolInput, } from './temporal-mcp-client';
|
|
5
|
+
export { TemporalMCPClient, type TemporalMCPClientOptions, type McpToolFilters, type McpToolMatcher, type McpToolInfo, type CallToolInput, } from './temporal-mcp-client';
|
|
6
6
|
export { TemporalMCPTool } from './temporal-mcp-tool';
|
|
7
7
|
export { TemporalActivityTool, type ActivityAsToolOptions } from './temporal-activity-tool';
|
|
8
|
-
export { STRANDS_INTERRUPT_TYPE,
|
|
8
|
+
export { STRANDS_INTERRUPT_TYPE, STRANDS_MALFORMED_INTERRUPT_TYPE } from './strands-errors';
|
|
9
9
|
export * as workflow from './workflow';
|
package/lib/index.js
CHANGED
|
@@ -15,15 +15,25 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
|
|
|
15
15
|
}) : function(o, v) {
|
|
16
16
|
o["default"] = v;
|
|
17
17
|
});
|
|
18
|
-
var __importStar = (this && this.__importStar) || function (
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
};
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
25
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
26
|
-
exports.workflow = exports.
|
|
36
|
+
exports.workflow = exports.STRANDS_MALFORMED_INTERRUPT_TYPE = exports.STRANDS_INTERRUPT_TYPE = exports.TemporalActivityTool = exports.TemporalMCPTool = exports.TemporalMCPClient = exports.TemporalModel = exports.TemporalAgent = exports.StrandsPlugin = void 0;
|
|
27
37
|
// eslint-disable-next-line import/no-unassigned-import
|
|
28
38
|
require("./load-polyfills");
|
|
29
39
|
var plugin_1 = require("./plugin");
|
|
@@ -38,8 +48,8 @@ var temporal_mcp_tool_1 = require("./temporal-mcp-tool");
|
|
|
38
48
|
Object.defineProperty(exports, "TemporalMCPTool", { enumerable: true, get: function () { return temporal_mcp_tool_1.TemporalMCPTool; } });
|
|
39
49
|
var temporal_activity_tool_1 = require("./temporal-activity-tool");
|
|
40
50
|
Object.defineProperty(exports, "TemporalActivityTool", { enumerable: true, get: function () { return temporal_activity_tool_1.TemporalActivityTool; } });
|
|
41
|
-
var
|
|
42
|
-
Object.defineProperty(exports, "STRANDS_INTERRUPT_TYPE", { enumerable: true, get: function () { return
|
|
43
|
-
Object.defineProperty(exports, "
|
|
51
|
+
var strands_errors_1 = require("./strands-errors");
|
|
52
|
+
Object.defineProperty(exports, "STRANDS_INTERRUPT_TYPE", { enumerable: true, get: function () { return strands_errors_1.STRANDS_INTERRUPT_TYPE; } });
|
|
53
|
+
Object.defineProperty(exports, "STRANDS_MALFORMED_INTERRUPT_TYPE", { enumerable: true, get: function () { return strands_errors_1.STRANDS_MALFORMED_INTERRUPT_TYPE; } });
|
|
44
54
|
exports.workflow = __importStar(require("./workflow"));
|
|
45
55
|
//# sourceMappingURL=index.js.map
|
package/lib/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,uDAAuD;AACvD,4BAA0B;AAE1B,mCAAoE;AAA3D,uGAAA,aAAa,OAAA;AACtB,mDAA4E;AAAnE,+GAAA,aAAa,OAAA;AACtB,mDAA4E;AAAnE,+GAAA,aAAa,OAAA;AACtB,6DAO+B;AAN7B,wHAAA,iBAAiB,OAAA;AAOnB,yDAAsD;AAA7C,oHAAA,eAAe,OAAA;AACxB,mEAA4F;AAAnF,8HAAA,oBAAoB,OAAA;AAC7B,mDAA4F;AAAnF,wHAAA,sBAAsB,OAAA;AAAE,kIAAA,gCAAgC,OAAA;AACjE,uDAAuC"}
|
package/lib/load-polyfills.js
CHANGED
|
@@ -3,6 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
3
3
|
const headers_polyfill_1 = require("headers-polyfill");
|
|
4
4
|
const workflow_1 = require("@temporalio/workflow");
|
|
5
5
|
if ((0, workflow_1.inWorkflowContext)()) {
|
|
6
|
+
// Strands composes the parent's cancellation signal with the subagent's via AbortSignal.any().
|
|
7
|
+
// Keep native signal composition, but refuse timeout's timer outside Temporal history.
|
|
8
|
+
// Subclass instead of changing the constructor shared with the worker and other workflows.
|
|
9
|
+
if (typeof globalThis.AbortSignal === 'undefined') {
|
|
10
|
+
const NativeAbortSignal = new AbortController().signal.constructor;
|
|
11
|
+
globalThis.AbortSignal = class extends NativeAbortSignal {
|
|
12
|
+
static timeout(_milliseconds) {
|
|
13
|
+
throw new workflow_1.DeterminismViolationError('AbortSignal.timeout() is not supported in workflows. Use Temporal sleep() and AbortController instead.');
|
|
14
|
+
}
|
|
15
|
+
// AbortController and the inherited helpers still return native signals.
|
|
16
|
+
static [Symbol.hasInstance](value) {
|
|
17
|
+
return value instanceof NativeAbortSignal;
|
|
18
|
+
}
|
|
19
|
+
};
|
|
20
|
+
}
|
|
6
21
|
if (typeof globalThis.Headers === 'undefined') {
|
|
7
22
|
globalThis.Headers = headers_polyfill_1.Headers;
|
|
8
23
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"load-polyfills.js","sourceRoot":"","sources":["../src/load-polyfills.ts"],"names":[],"mappings":";;AAAA,uDAA2C;AAC3C,
|
|
1
|
+
{"version":3,"file":"load-polyfills.js","sourceRoot":"","sources":["../src/load-polyfills.ts"],"names":[],"mappings":";;AAAA,uDAA2C;AAC3C,mDAA2F;AAE3F,IAAI,IAAA,4BAAiB,GAAE,EAAE,CAAC;IACxB,+FAA+F;IAC/F,uFAAuF;IACvF,2FAA2F;IAC3F,IAAI,OAAO,UAAU,CAAC,WAAW,KAAK,WAAW,EAAE,CAAC;QAClD,MAAM,iBAAiB,GAAG,IAAI,eAAe,EAAE,CAAC,MAAM,CAAC,WAAiC,CAAC;QACzF,UAAU,CAAC,WAAW,GAAG,KAAM,SAAQ,iBAAiB;YACtD,MAAM,CAAU,OAAO,CAAC,aAAqB;gBAC3C,MAAM,IAAI,oCAAyB,CACjC,wGAAwG,CACzG,CAAC;YACJ,CAAC;YAED,yEAAyE;YACzE,MAAM,CAAU,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,KAAc;gBACjD,OAAO,KAAK,YAAY,iBAAiB,CAAC;YAC5C,CAAC;SACF,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,UAAU,CAAC,OAAO,KAAK,WAAW,EAAE,CAAC;QAC9C,UAAU,CAAC,OAAO,GAAG,0BAAO,CAAC;IAC/B,CAAC;IAED,6FAA6F;IAC7F,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAEzC,IAAI,CAAC,CAAC,iBAAiB,IAAI,UAAU,CAAC,EAAE,CAAC;QACvC,iEAAiE;QACjE,MAAM,eAAe,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;QAC3D,UAAU,CAAC,eAAe,GAAG,eAAe,CAAC,OAAO,CAAC;IACvD,CAAC;IAED,4EAA4E;IAC5E,gEAAgE;IAChE,+DAA+D;IAC/D,IAAI,OAAO,UAAU,CAAC,MAAM,EAAE,UAAU,KAAK,UAAU,EAAE,CAAC;QACxD,UAAU,CAAC,MAAM,GAAG,EAAE,GAAG,CAAC,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,gBAAK,EAAW,CAAC;IACnF,CAAC;AACH,CAAC"}
|
package/lib/model-activity.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { Message } from '@strands-agents/sdk';
|
|
2
|
-
import type { Model, ModelStreamEvent, StreamOptions } from '@strands-agents/sdk';
|
|
2
|
+
import type { JSONValue, Model, ModelStreamEvent, StreamOptions } from '@strands-agents/sdk';
|
|
3
3
|
import type { Duration } from '@temporalio/common/lib/time';
|
|
4
4
|
/**
|
|
5
5
|
* Input for the `invokeModel` activity. Mirrors `Model.stream(messages, options)`
|
|
@@ -18,6 +18,39 @@ export interface InvokeModelStreamingInput extends InvokeModelInput {
|
|
|
18
18
|
streamingTopic: string;
|
|
19
19
|
streamingBatchInterval: Duration;
|
|
20
20
|
}
|
|
21
|
+
/**
|
|
22
|
+
* Input for the stateful model activities: a copy of the agent's model state, such as the last
|
|
23
|
+
* response id, which the model reads and updates.
|
|
24
|
+
*/
|
|
25
|
+
export interface InvokeStatefulModelInput extends InvokeModelInput {
|
|
26
|
+
modelState: Record<string, JSONValue>;
|
|
27
|
+
}
|
|
28
|
+
/** Input for the streaming stateful model activity. */
|
|
29
|
+
export interface InvokeStatefulModelStreamingInput extends InvokeModelStreamingInput {
|
|
30
|
+
modelState: Record<string, JSONValue>;
|
|
31
|
+
}
|
|
32
|
+
/** A stateful model's events and its updated model state. */
|
|
33
|
+
export interface InvokeStatefulModelResult {
|
|
34
|
+
events: ModelStreamEvent[];
|
|
35
|
+
modelState: Record<string, JSONValue>;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Input for the model config activity: the factory name, as in {@link InvokeModelInput}.
|
|
39
|
+
*/
|
|
40
|
+
export interface GetModelConfigInput {
|
|
41
|
+
modelName?: string;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* The parts of the worker model that Strands reads in workflow code: the model id for traces, the
|
|
45
|
+
* context window for proactive compression, and whether the model keeps the conversation
|
|
46
|
+
* server-side. Nothing else is returned, so provider settings such as credentials never reach the
|
|
47
|
+
* workflow history.
|
|
48
|
+
*/
|
|
49
|
+
export interface ModelConfigInfo {
|
|
50
|
+
modelId?: string;
|
|
51
|
+
contextWindowLimit?: number;
|
|
52
|
+
stateful?: boolean;
|
|
53
|
+
}
|
|
21
54
|
/**
|
|
22
55
|
* Holds the model factory map and exposes the model activities.
|
|
23
56
|
*
|
|
@@ -26,7 +59,7 @@ export interface InvokeModelStreamingInput extends InvokeModelInput {
|
|
|
26
59
|
* default-Bedrock fallback; user-supplied factories force `model: 'name'`
|
|
27
60
|
* on every {@link TemporalAgent}.
|
|
28
61
|
*
|
|
29
|
-
*
|
|
62
|
+
* The model activities heartbeat at half the configured `heartbeatTimeout` via
|
|
30
63
|
* {@link autoHeartbeat} so long model calls don't stall the worker's view
|
|
31
64
|
* of activity liveness.
|
|
32
65
|
*/
|
|
@@ -36,6 +69,28 @@ export declare class ModelActivity {
|
|
|
36
69
|
private readonly models;
|
|
37
70
|
constructor(factories: Record<string, () => Model>, defaultName?: string | undefined);
|
|
38
71
|
private getModel;
|
|
72
|
+
getModelConfig(input: GetModelConfigInput): Promise<ModelConfigInfo>;
|
|
39
73
|
invokeModel(input: InvokeModelInput): Promise<ModelStreamEvent[]>;
|
|
40
74
|
invokeModelStreaming(input: InvokeModelStreamingInput): Promise<ModelStreamEvent[]>;
|
|
75
|
+
/**
|
|
76
|
+
* The model for a stateless call. A stateful model cannot run here without the agent's model
|
|
77
|
+
* state, and retrying does not bring it: the workflow chose this activity because its config
|
|
78
|
+
* read had no stateful flag, from a worker without stateful support or from a model that became
|
|
79
|
+
* stateful later, or because `TemporalModel` runs without `TemporalAgent` and never read the
|
|
80
|
+
* config.
|
|
81
|
+
*/
|
|
82
|
+
private getStatelessModel;
|
|
83
|
+
/**
|
|
84
|
+
* The model for a stateful call. A model that is no longer stateful ignores the model state, and
|
|
85
|
+
* the agent, which read a stateful config, clears its messages after each turn, so the model
|
|
86
|
+
* would see only each turn's new message: the worker model became stateless after the run read
|
|
87
|
+
* its config.
|
|
88
|
+
*/
|
|
89
|
+
private getStatefulModel;
|
|
90
|
+
private runModel;
|
|
91
|
+
private runModelStreaming;
|
|
92
|
+
/** Run a stateful model with the agent's model state; return its events and the updated state. */
|
|
93
|
+
invokeStatefulModel(input: InvokeStatefulModelInput): Promise<InvokeStatefulModelResult>;
|
|
94
|
+
/** As {@link invokeStatefulModel}, publishing each event as {@link invokeModelStreaming} does. */
|
|
95
|
+
invokeStatefulModelStreaming(input: InvokeStatefulModelStreamingInput): Promise<InvokeStatefulModelResult>;
|
|
41
96
|
}
|