@temporalio/strands-agents 1.23.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
|
@@ -13,17 +13,17 @@ import type { z } from 'zod';
|
|
|
13
13
|
import * as workflow from '@temporalio/workflow';
|
|
14
14
|
import type { ActivityOptions } from '@temporalio/workflow';
|
|
15
15
|
import { ActivityFailure, ApplicationFailure } from '@temporalio/common';
|
|
16
|
-
import { STRANDS_INTERRUPT_TYPE } from './
|
|
16
|
+
import { type InterruptDetails, STRANDS_INTERRUPT_TYPE } from './strands-errors';
|
|
17
17
|
import { toJsonSchema } from './json-schema';
|
|
18
18
|
|
|
19
19
|
/**
|
|
20
20
|
* Options accepted by {@link activityAsTool}.
|
|
21
21
|
*
|
|
22
|
-
* `name` defaults to the activity
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
22
|
+
* `name` defaults to the registered activity name. `description` is omitted
|
|
23
|
+
* when not supplied; supply one to help the model decide when to call the
|
|
24
|
+
* tool. `inputSchema` describes the activity's single argument; pass either a
|
|
25
|
+
* literal JSON Schema object or a Zod schema, which is converted to JSON
|
|
26
|
+
* Schema for you.
|
|
27
27
|
*/
|
|
28
28
|
export interface ActivityAsToolOptions {
|
|
29
29
|
name?: string;
|
|
@@ -37,14 +37,17 @@ export interface ActivityAsToolOptions {
|
|
|
37
37
|
* {@link workflow.executeActivity}.
|
|
38
38
|
*
|
|
39
39
|
* When the activity fails with an {@link ApplicationFailure} whose `type`
|
|
40
|
-
* matches {@link STRANDS_INTERRUPT_TYPE} —
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
40
|
+
* matches {@link STRANDS_INTERRUPT_TYPE} — {@link StrandsPlugin} turns an
|
|
41
|
+
* interrupt the activity throws into one —
|
|
42
|
+
* `stream()` raises each interrupt in its details, in order, so the agent loop
|
|
43
|
+
* handles them the same way as hook- or tool-body interrupts: the agent pauses
|
|
44
|
+
* at the first one without a response. Other failures, including a malformed
|
|
45
|
+
* interrupt, are converted to an error {@link ToolResultBlock}.
|
|
44
46
|
*/
|
|
45
47
|
export class TemporalActivityTool extends Tool {
|
|
46
48
|
readonly name: string;
|
|
47
|
-
|
|
49
|
+
// Strands accepts an omitted description at runtime, though Tool and ToolSpec require it in their types.
|
|
50
|
+
declare readonly description: string;
|
|
48
51
|
readonly toolSpec: ToolSpec;
|
|
49
52
|
private readonly activityName: string;
|
|
50
53
|
private readonly activityOptions: ActivityOptions;
|
|
@@ -61,12 +64,14 @@ export class TemporalActivityTool extends Tool {
|
|
|
61
64
|
super();
|
|
62
65
|
this.activityName = activityName;
|
|
63
66
|
this.name = options.name ?? activityName;
|
|
64
|
-
this.description = options.description ?? '';
|
|
65
67
|
this.toolSpec = {
|
|
66
68
|
name: this.name,
|
|
67
|
-
description: this.description,
|
|
68
69
|
inputSchema: toJsonSchema(options.inputSchema) ?? { type: 'object', properties: {} },
|
|
69
|
-
};
|
|
70
|
+
} as ToolSpec;
|
|
71
|
+
if (options.description !== undefined) {
|
|
72
|
+
this.description = options.description;
|
|
73
|
+
this.toolSpec.description = this.description;
|
|
74
|
+
}
|
|
70
75
|
this.activityOptions = options.activityOptions ?? {};
|
|
71
76
|
}
|
|
72
77
|
|
|
@@ -89,29 +94,19 @@ export class TemporalActivityTool extends Tool {
|
|
|
89
94
|
err.cause instanceof ApplicationFailure &&
|
|
90
95
|
err.cause.type === STRANDS_INTERRUPT_TYPE
|
|
91
96
|
) {
|
|
92
|
-
const details = (err.cause.details ?? []) as
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
// Route through the agent's interrupt() helper: throws InterruptError to
|
|
99
|
-
// halt on first call, returns the user's response on resume.
|
|
100
|
-
const response = toolContext.interrupt<unknown>({
|
|
101
|
-
name: first?.name ?? 'interrupt',
|
|
102
|
-
reason: first?.reason as JSONValue,
|
|
103
|
-
});
|
|
97
|
+
const details = (err.cause.details ?? []) as InterruptDetails[];
|
|
98
|
+
// Route each interrupt through the agent's interrupt() helper, in order: the first one with
|
|
99
|
+
// no response throws InterruptError and halts; on resume the answered ones return theirs.
|
|
100
|
+
const responses = (details.length > 0 ? details : [{ name: 'interrupt' }]).map((d: Partial<InterruptDetails>) =>
|
|
101
|
+
toolContext.interrupt<unknown>({ name: d.name ?? 'interrupt', reason: d.reason as JSONValue })
|
|
102
|
+
);
|
|
104
103
|
return new ToolResultBlock({
|
|
105
104
|
toolUseId,
|
|
106
105
|
status: 'success',
|
|
107
|
-
content: [toResultContent(
|
|
106
|
+
content: [toResultContent(responses.length === 1 ? responses[0] : responses)],
|
|
108
107
|
});
|
|
109
108
|
}
|
|
110
|
-
return
|
|
111
|
-
toolUseId,
|
|
112
|
-
status: 'error',
|
|
113
|
-
content: [new TextBlock(String(err instanceof Error ? err.message : err))],
|
|
114
|
-
});
|
|
109
|
+
return activityErrorResult(toolUseId, err);
|
|
115
110
|
}
|
|
116
111
|
return new ToolResultBlock({
|
|
117
112
|
toolUseId,
|
|
@@ -121,6 +116,22 @@ export class TemporalActivityTool extends Tool {
|
|
|
121
116
|
}
|
|
122
117
|
}
|
|
123
118
|
|
|
119
|
+
/**
|
|
120
|
+
* The error result for a tool call whose activity failed. An `ActivityFailure`'s own message is
|
|
121
|
+
* the generic "Activity task failed", so the result carries its cause instead: what the activity
|
|
122
|
+
* threw, or the timeout or cancellation that ended it. The error is attached for hooks.
|
|
123
|
+
*/
|
|
124
|
+
export function activityErrorResult(toolUseId: string, err: unknown): ToolResultBlock {
|
|
125
|
+
const cause = err instanceof ActivityFailure && err.cause ? err.cause : err;
|
|
126
|
+
const error = cause instanceof Error ? cause : new Error(String(cause));
|
|
127
|
+
return new ToolResultBlock({
|
|
128
|
+
toolUseId,
|
|
129
|
+
status: 'error',
|
|
130
|
+
content: [new TextBlock(error.message)],
|
|
131
|
+
error,
|
|
132
|
+
});
|
|
133
|
+
}
|
|
134
|
+
|
|
124
135
|
function toResultContent(value: unknown): TextBlock | JsonBlock {
|
|
125
136
|
if (typeof value === 'string') return new TextBlock(value);
|
|
126
137
|
return new JsonBlock({ json: value as JSONValue });
|
package/src/temporal-agent.ts
CHANGED
|
@@ -1,19 +1,19 @@
|
|
|
1
1
|
import { Agent, AfterToolsEvent } from '@strands-agents/sdk';
|
|
2
|
-
import type { AgentConfig } from '@strands-agents/sdk';
|
|
2
|
+
import type { AgentConfig, AgentResult, AgentStreamEvent, InvokeArgs, InvokeOptions } from '@strands-agents/sdk';
|
|
3
3
|
import type { ActivityOptions } from '@temporalio/workflow';
|
|
4
4
|
import type { Duration } from '@temporalio/common/lib/time';
|
|
5
5
|
import { TemporalModel } from './temporal-model';
|
|
6
6
|
import { TemporalMCPClient } from './temporal-mcp-client';
|
|
7
|
+
import { workflowErrorFor } from './strands-errors';
|
|
7
8
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
'
|
|
11
|
-
'
|
|
12
|
-
"Temporal's durable execution instead.";
|
|
9
|
+
// Strands' own message, which its Agent throws at construction for a stateful model.
|
|
10
|
+
const STATEFUL_MANAGER_REFUSED =
|
|
11
|
+
'contextManager and conversationManager cannot be used with a stateful model. ' +
|
|
12
|
+
'The model manages conversation state server-side.';
|
|
13
13
|
|
|
14
14
|
const RETRY_STRATEGY_DISABLED =
|
|
15
|
-
'TemporalAgent disables Strands retries; configure retries via
|
|
16
|
-
'
|
|
15
|
+
'TemporalAgent disables Strands retries; configure retries via activityOptions.retry ' +
|
|
16
|
+
'on TemporalAgent, and on the activity options ' +
|
|
17
17
|
'passed to workflow.activityAsTool, workflow.activityAsHook, or TemporalMCPClient. ' +
|
|
18
18
|
'Remove retryStrategy from TemporalAgent(...) or pass retryStrategy: null.';
|
|
19
19
|
|
|
@@ -22,7 +22,7 @@ const RETRY_STRATEGY_DISABLED =
|
|
|
22
22
|
*
|
|
23
23
|
* Accepts everything {@link AgentConfig} accepts except `model` (which is a
|
|
24
24
|
* factory name selecting a worker-side {@link Model}, not an instance) and
|
|
25
|
-
* `retryStrategy` (
|
|
25
|
+
* `retryStrategy` (only `null` is accepted — Temporal handles retries via
|
|
26
26
|
* `activityOptions.retry`).
|
|
27
27
|
*
|
|
28
28
|
* The {@link ActivityOptions} apply to every model invocation this agent
|
|
@@ -31,6 +31,8 @@ const RETRY_STRATEGY_DISABLED =
|
|
|
31
31
|
*/
|
|
32
32
|
export interface TemporalAgentOptions extends Omit<AgentConfig, 'model' | 'retryStrategy'> {
|
|
33
33
|
model?: string;
|
|
34
|
+
/** Disable Strands retries explicitly; Temporal manages retries via `activityOptions.retry`. */
|
|
35
|
+
retryStrategy?: null;
|
|
34
36
|
activityOptions?: ActivityOptions;
|
|
35
37
|
streamingTopic?: string;
|
|
36
38
|
streamingBatchInterval?: Duration;
|
|
@@ -49,11 +51,25 @@ export interface TemporalAgentOptions extends Omit<AgentConfig, 'model' | 'retry
|
|
|
49
51
|
* Strands' `retryStrategy` is disabled; configure retries via
|
|
50
52
|
* `activityOptions.retry` here and on the activity options accepted by
|
|
51
53
|
* {@link activityAsTool}, {@link activityAsHook}, and {@link TemporalMCPClient}.
|
|
54
|
+
*
|
|
55
|
+
* `activityOptions.heartbeatTimeout` defaults to 10 seconds, and the model
|
|
56
|
+
* activities heartbeat at half of it; `heartbeatTimeout: 0` turns them off.
|
|
57
|
+
* Cancelling a model activity aborts the model call only when the activity
|
|
58
|
+
* heartbeats, since the worker learns of the cancellation through its
|
|
59
|
+
* heartbeats, and only when the model passes `cancelSignal` to its client
|
|
60
|
+
* (Strands' `AnthropicModel` does not). A model that ignores it keeps running
|
|
61
|
+
* and its activity can still complete with the model's result. A workflow
|
|
62
|
+
* cancel during a model call cancels the model activity. With `TRY_CANCEL` the
|
|
63
|
+
* run ends as cancelled at once. With `WAIT_CANCELLATION_COMPLETED` it ends as
|
|
64
|
+
* cancelled only if the activity does; if the activity completes, the turn
|
|
65
|
+
* continues with the model's result.
|
|
52
66
|
*/
|
|
53
67
|
export class TemporalAgent extends Agent {
|
|
68
|
+
private readonly managerGiven: boolean;
|
|
69
|
+
|
|
54
70
|
constructor(options: TemporalAgentOptions = {}) {
|
|
55
|
-
const { model, activityOptions, streamingTopic, streamingBatchInterval, ...rest } = options;
|
|
56
|
-
if (
|
|
71
|
+
const { model, retryStrategy, activityOptions, streamingTopic, streamingBatchInterval, ...rest } = options;
|
|
72
|
+
if (retryStrategy !== undefined && retryStrategy !== null) {
|
|
57
73
|
throw new Error(RETRY_STRATEGY_DISABLED);
|
|
58
74
|
}
|
|
59
75
|
const temporalModel = new TemporalModel({
|
|
@@ -67,25 +83,67 @@ export class TemporalAgent extends Agent {
|
|
|
67
83
|
model: temporalModel,
|
|
68
84
|
retryStrategy: null,
|
|
69
85
|
});
|
|
86
|
+
this.managerGiven = Boolean(rest.conversationManager || rest.contextManager);
|
|
70
87
|
|
|
71
88
|
// Strands lists each MCP client's tools once at agent initialization and
|
|
72
89
|
// reuses that list for every turn. For clients with `cacheTools: false`,
|
|
73
90
|
// re-list on each turn so a mid-workflow MCP-server restart is picked up.
|
|
74
91
|
// `AfterToolsEvent` fires after a tool round completes, before the next
|
|
75
92
|
// model call reads the tool registry — so the refresh lands on that call.
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
93
|
+
// One hook per client, as each lists its server. Strands runs them last to
|
|
94
|
+
// first, so the first client's hook runs last: it checks the round's
|
|
95
|
+
// listings together and applies them, so a name can move from one server
|
|
96
|
+
// to another.
|
|
97
|
+
const mcpClients = collectMcpClients(rest.tools);
|
|
98
|
+
for (const hook of TemporalMCPClient.refreshHooks(mcpClients.filter((client) => !client.cacheTools))) {
|
|
99
|
+
this.addHook(AfterToolsEvent, hook);
|
|
80
100
|
}
|
|
101
|
+
// A name that Strands adds a client's tool under is that client's until a
|
|
102
|
+
// re-listing of that client drops it.
|
|
103
|
+
TemporalMCPClient.holdAdded(mcpClients, this.toolRegistry);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* Read the worker model's id, context window and stateful flag before Strands initializes the
|
|
108
|
+
* agent, so its traces, proactive compression and stateful handling use them from the first
|
|
109
|
+
* model call.
|
|
110
|
+
*
|
|
111
|
+
* Not `async`: once the config is read, this returns Strands' own `initialize()` promise, so it
|
|
112
|
+
* adds no microtask before Strands' hooks and model call.
|
|
113
|
+
*/
|
|
114
|
+
override initialize(): Promise<void> {
|
|
115
|
+
const loading = this.model instanceof TemporalModel ? this.model.loadConfig() : undefined;
|
|
116
|
+
return loading ? loading.then(() => this.initializeWithConfig()) : this.initializeWithConfig();
|
|
81
117
|
}
|
|
82
118
|
|
|
83
|
-
|
|
84
|
-
|
|
119
|
+
private initializeWithConfig(): Promise<void> {
|
|
120
|
+
// Strands' Agent refuses these managers for a stateful model at construction, before
|
|
121
|
+
// TemporalAgent can read the worker model's stateful flag, so refuse them here.
|
|
122
|
+
if (this.model.stateful && this.managerGiven) {
|
|
123
|
+
return Promise.reject(new Error(STATEFUL_MANAGER_REFUSED));
|
|
124
|
+
}
|
|
125
|
+
return super.initialize();
|
|
85
126
|
}
|
|
86
127
|
|
|
87
|
-
|
|
88
|
-
|
|
128
|
+
/**
|
|
129
|
+
* Strands' stream, ending in a Temporal failure where Strands would end in an error that only
|
|
130
|
+
* fails the workflow task: a terminal model error becomes a typed, non-retryable failure, and a
|
|
131
|
+
* model activity that failed or was cancelled ends the turn with that activity's failure. So the
|
|
132
|
+
* run, or the update that runs the turn, fails or is cancelled. `invoke()` uses this too.
|
|
133
|
+
*
|
|
134
|
+
* Its awaits add microtasks to each agent event, and those are part of replay: when two turns run
|
|
135
|
+
* at once in one workflow, they can change the order in which the turns schedule activities. So
|
|
136
|
+
* removing this override, or wrapping the stream in another layer, can break replay of such runs.
|
|
137
|
+
*/
|
|
138
|
+
override async *stream(
|
|
139
|
+
args: InvokeArgs,
|
|
140
|
+
options?: InvokeOptions
|
|
141
|
+
): AsyncGenerator<AgentStreamEvent, AgentResult, undefined> {
|
|
142
|
+
try {
|
|
143
|
+
return yield* super.stream(args, options);
|
|
144
|
+
} catch (err) {
|
|
145
|
+
throw workflowErrorFor(err);
|
|
146
|
+
}
|
|
89
147
|
}
|
|
90
148
|
}
|
|
91
149
|
|