@temporalio/strands-agents 1.21.0
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 +21 -0
- package/README.md +351 -0
- package/lib/empty-module.d.ts +4 -0
- package/lib/empty-module.js +21 -0
- package/lib/empty-module.js.map +1 -0
- package/lib/failure-converter.d.ts +14 -0
- package/lib/failure-converter.js +60 -0
- package/lib/failure-converter.js.map +1 -0
- package/lib/heartbeat.d.ts +6 -0
- package/lib/heartbeat.js +27 -0
- package/lib/heartbeat.js.map +1 -0
- package/lib/index.d.ts +9 -0
- package/lib/index.js +45 -0
- package/lib/index.js.map +1 -0
- package/lib/json-schema.d.ts +10 -0
- package/lib/json-schema.js +17 -0
- package/lib/json-schema.js.map +1 -0
- package/lib/load-polyfills.d.ts +1 -0
- package/lib/load-polyfills.js +23 -0
- package/lib/load-polyfills.js.map +1 -0
- package/lib/model-activity.d.ts +41 -0
- package/lib/model-activity.js +100 -0
- package/lib/model-activity.js.map +1 -0
- package/lib/plugin.d.ts +79 -0
- package/lib/plugin.js +152 -0
- package/lib/plugin.js.map +1 -0
- package/lib/temporal-activity-tool.d.ts +42 -0
- package/lib/temporal-activity-tool.js +109 -0
- package/lib/temporal-activity-tool.js.map +1 -0
- package/lib/temporal-agent.d.ts +41 -0
- package/lib/temporal-agent.js +80 -0
- package/lib/temporal-agent.js.map +1 -0
- package/lib/temporal-mcp-client.d.ts +107 -0
- package/lib/temporal-mcp-client.js +237 -0
- package/lib/temporal-mcp-client.js.map +1 -0
- package/lib/temporal-mcp-tool.d.ts +24 -0
- package/lib/temporal-mcp-tool.js +109 -0
- package/lib/temporal-mcp-tool.js.map +1 -0
- package/lib/temporal-model.d.ts +41 -0
- package/lib/temporal-model.js +88 -0
- package/lib/temporal-model.js.map +1 -0
- package/lib/workflow.d.ts +39 -0
- package/lib/workflow.js +66 -0
- package/lib/workflow.js.map +1 -0
- package/package.json +72 -0
- package/src/empty-module.ts +20 -0
- package/src/failure-converter.ts +76 -0
- package/src/heartbeat.ts +24 -0
- package/src/index.ts +16 -0
- package/src/json-schema.ts +14 -0
- package/src/load-polyfills.ts +24 -0
- package/src/model-activity.ts +124 -0
- package/src/plugin.ts +215 -0
- package/src/temporal-activity-tool.ts +127 -0
- package/src/temporal-agent.ts +103 -0
- package/src/temporal-mcp-client.ts +274 -0
- package/src/temporal-mcp-tool.ts +89 -0
- package/src/temporal-model.ts +94 -0
- package/src/workflow.ts +60 -0
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
import { McpClient } from '@strands-agents/sdk';
|
|
2
|
+
import type { JSONSchema, JSONValue } from '@strands-agents/sdk';
|
|
3
|
+
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
|
|
4
|
+
import * as workflow from '@temporalio/workflow';
|
|
5
|
+
import type { ActivityOptions } from '@temporalio/workflow';
|
|
6
|
+
import { activityInfo, Context as ActivityContext } from '@temporalio/activity';
|
|
7
|
+
|
|
8
|
+
/** Tool descriptor returned by the per-server `{server}-listTools` activity. */
|
|
9
|
+
export interface McpToolInfo {
|
|
10
|
+
name: string;
|
|
11
|
+
description: string;
|
|
12
|
+
inputSchema?: JSONSchema;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/** Activity input for the per-server `{server}-callTool` activity. */
|
|
16
|
+
export interface CallToolInput {
|
|
17
|
+
toolName: string;
|
|
18
|
+
args: JSONValue;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
const STUB_TRANSPORT: Transport = {
|
|
22
|
+
async start() {
|
|
23
|
+
// No-op; TemporalMCPClient never connects from inside a workflow.
|
|
24
|
+
},
|
|
25
|
+
async send() {
|
|
26
|
+
// No-op.
|
|
27
|
+
},
|
|
28
|
+
async close() {
|
|
29
|
+
// No-op.
|
|
30
|
+
},
|
|
31
|
+
};
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Options for {@link TemporalMCPClient}.
|
|
35
|
+
*
|
|
36
|
+
* The {@link ActivityOptions} apply to every per-tool activity invocation
|
|
37
|
+
* the agent makes for this MCP server.
|
|
38
|
+
*
|
|
39
|
+
* `cacheTools` controls how often the agent re-lists this server's tools.
|
|
40
|
+
* Strands lists an MCP client's tools once when the agent initializes and then
|
|
41
|
+
* reuses that list for every turn, so the list is otherwise frozen for the
|
|
42
|
+
* whole workflow.
|
|
43
|
+
*
|
|
44
|
+
* - `false` (default) — re-list the tools on each agent turn, so the agent
|
|
45
|
+
* picks up an MCP server that's restarted or redeployed mid-workflow. Costs
|
|
46
|
+
* one extra `{server}-listTools` activity per tool round.
|
|
47
|
+
* - `true` — list once at the beginning of the workflow and reuse for all
|
|
48
|
+
* turns. Cheaper, but the tool list is fixed for the workflow's lifetime.
|
|
49
|
+
*/
|
|
50
|
+
export interface TemporalMCPClientOptions {
|
|
51
|
+
server: string;
|
|
52
|
+
activityOptions?: ActivityOptions;
|
|
53
|
+
cacheTools?: boolean;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Minimal view of Strands' `ToolRegistry` used by {@link
|
|
58
|
+
* TemporalMCPClient.refreshTools}. Typed structurally because `ToolRegistry`
|
|
59
|
+
* isn't re-exported from `@strands-agents/sdk`'s public index.
|
|
60
|
+
*/
|
|
61
|
+
export interface ToolRegistryView {
|
|
62
|
+
list(): { name: string }[];
|
|
63
|
+
remove(name: string): void;
|
|
64
|
+
addOrReplace(tools: never[]): void;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Workflow-side handle to an MCP server registered on the worker.
|
|
69
|
+
*
|
|
70
|
+
* The transport factory and tool discovery live worker-side via
|
|
71
|
+
* `StrandsPlugin({ mcpClients: { server: () => new McpClient(...) } })`.
|
|
72
|
+
* This handle only carries the server name (which selects the registered
|
|
73
|
+
* factory) and the per-call activity options.
|
|
74
|
+
*
|
|
75
|
+
* Extends {@link McpClient} so it can be passed directly in an
|
|
76
|
+
* {@link AgentConfig.tools | Agent.tools} array (Strands' `flattenTools`
|
|
77
|
+
* dispatches on `instanceof McpClient`). `connect()` and `disconnect()`
|
|
78
|
+
* are no-ops; `listTools()` returns lightweight {@link TemporalMCPTool}
|
|
79
|
+
* wrappers whose `stream()` dispatches to the per-server `{server}-callTool`
|
|
80
|
+
* activity registered by {@link StrandsPlugin}.
|
|
81
|
+
*/
|
|
82
|
+
export class TemporalMCPClient extends McpClient {
|
|
83
|
+
private readonly server: string;
|
|
84
|
+
private readonly activityOptions: ActivityOptions;
|
|
85
|
+
/** Whether the agent lists this server's tools once or re-lists each turn. */
|
|
86
|
+
readonly cacheTools: boolean;
|
|
87
|
+
|
|
88
|
+
constructor(options: TemporalMCPClientOptions) {
|
|
89
|
+
super({ transport: STUB_TRANSPORT });
|
|
90
|
+
this.server = options.server;
|
|
91
|
+
this.activityOptions = options.activityOptions ?? {};
|
|
92
|
+
this.cacheTools = options.cacheTools ?? false;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
override async connect(): Promise<void> {
|
|
96
|
+
// No-op; all I/O happens inside the per-server callTool activity.
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
override async disconnect(): Promise<void> {
|
|
100
|
+
// No-op.
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
// The base `McpClient.listTools` returns `Promise<McpTool[]>`, but `McpTool`
|
|
104
|
+
// isn't re-exported from `@strands-agents/sdk`'s public index. The cast to
|
|
105
|
+
// `never[]` keeps the override compatible; the agent only uses
|
|
106
|
+
// `name`/`toolSpec`/`stream` on each tool, all of which
|
|
107
|
+
// {@link TemporalMCPTool} provides.
|
|
108
|
+
override async listTools(): Promise<never[]> {
|
|
109
|
+
// Imported lazily to avoid a circular module cycle with TemporalMCPTool.
|
|
110
|
+
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
111
|
+
const { TemporalMCPTool } = require('./temporal-mcp-tool') as typeof import('./temporal-mcp-tool');
|
|
112
|
+
const activities = workflow.proxyActivities<{
|
|
113
|
+
[key: string]: (args: { server: string }) => Promise<McpToolInfo[]>;
|
|
114
|
+
}>({
|
|
115
|
+
startToCloseTimeout: '10 minutes',
|
|
116
|
+
...this.activityOptions,
|
|
117
|
+
});
|
|
118
|
+
const infos = await activities[listToolsActivityName(this.server)]!({ server: this.server });
|
|
119
|
+
return infos.map((info) => new TemporalMCPTool(this.server, info, this.activityOptions)) as never[];
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Re-list this server's tools and reconcile them into the agent's tool
|
|
124
|
+
* registry, dropping tools that no longer exist and adding new ones.
|
|
125
|
+
* {@link TemporalAgent} calls this on each agent turn when `cacheTools` is
|
|
126
|
+
* `false` so a mid-workflow MCP-server restart is reflected in the next call.
|
|
127
|
+
*/
|
|
128
|
+
async refreshTools(registry: ToolRegistryView): Promise<void> {
|
|
129
|
+
// Imported lazily to avoid a circular module cycle with TemporalMCPTool.
|
|
130
|
+
// eslint-disable-next-line @typescript-eslint/no-require-imports
|
|
131
|
+
const { TemporalMCPTool } = require('./temporal-mcp-tool') as typeof import('./temporal-mcp-tool');
|
|
132
|
+
const fresh = await this.listTools();
|
|
133
|
+
const freshNames = new Set((fresh as unknown as { name: string }[]).map((t) => t.name));
|
|
134
|
+
for (const tool of registry.list()) {
|
|
135
|
+
if (tool instanceof TemporalMCPTool && tool.server === this.server && !freshNames.has(tool.name)) {
|
|
136
|
+
registry.remove(tool.name);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
registry.addOrReplace(fresh);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
export function listToolsActivityName(server: string): string {
|
|
144
|
+
return `${server}-listTools`;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
export function callToolActivityName(server: string): string {
|
|
148
|
+
return `${server}-callTool`;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Builds the per-server `{server}-listTools` activity. Enumerates the server's
|
|
153
|
+
* tools live over the shared worker-process connection on every call, so the
|
|
154
|
+
* agent sees the server's current tools even if it is redeployed mid-workflow.
|
|
155
|
+
* Runs whenever a workflow calls {@link TemporalMCPClient.listTools}.
|
|
156
|
+
*/
|
|
157
|
+
export function buildListToolsActivity(
|
|
158
|
+
server: string,
|
|
159
|
+
factory: () => McpClient,
|
|
160
|
+
idleMs: number = MCP_CONNECTION_IDLE_MS
|
|
161
|
+
): (input: { server: string }) => Promise<McpToolInfo[]> {
|
|
162
|
+
const name = listToolsActivityName(server);
|
|
163
|
+
const fn = async (_input: { server: string }): Promise<McpToolInfo[]> => {
|
|
164
|
+
const client = await getConnection(server, factory, idleMs);
|
|
165
|
+
try {
|
|
166
|
+
const tools = await client.listTools();
|
|
167
|
+
return tools.map((t) => ({
|
|
168
|
+
name: t.name,
|
|
169
|
+
description: t.description,
|
|
170
|
+
inputSchema: t.toolSpec.inputSchema,
|
|
171
|
+
}));
|
|
172
|
+
} catch (err) {
|
|
173
|
+
// The session may be broken (e.g. the server was redeployed); drop it so
|
|
174
|
+
// the next call reconnects to the current deployment.
|
|
175
|
+
await _evictConnection(server);
|
|
176
|
+
throw err;
|
|
177
|
+
}
|
|
178
|
+
};
|
|
179
|
+
Object.defineProperty(fn, 'name', { value: name });
|
|
180
|
+
return fn;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* Default for how long an idle MCP connection is kept open before it's
|
|
185
|
+
* disconnected. The timer resets on every {@link callToolActivityName |
|
|
186
|
+
* callTool} that reuses the connection. Override per worker via
|
|
187
|
+
* `StrandsPlugin({ mcpConnectionIdleMs })`.
|
|
188
|
+
*/
|
|
189
|
+
export const MCP_CONNECTION_IDLE_MS = 5 * 60 * 1000;
|
|
190
|
+
|
|
191
|
+
// Worker-process caches, keyed by server name. Activities run in the worker's
|
|
192
|
+
// Node process, so this module state is shared across every activity invocation on the worker.
|
|
193
|
+
const CONNECTIONS: Map<string, Promise<McpClient>> = new Map();
|
|
194
|
+
const IDLE_TIMERS: Map<string, NodeJS.Timeout> = new Map();
|
|
195
|
+
|
|
196
|
+
function resetIdleTimer(server: string, idleMs: number): void {
|
|
197
|
+
const existing = IDLE_TIMERS.get(server);
|
|
198
|
+
if (existing !== undefined) clearTimeout(existing);
|
|
199
|
+
const timer = setTimeout(() => void _evictConnection(server), idleMs);
|
|
200
|
+
// Don't let an idle MCP connection keep the worker process alive.
|
|
201
|
+
timer.unref?.();
|
|
202
|
+
IDLE_TIMERS.set(server, timer);
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
export async function _evictConnection(server: string): Promise<void> {
|
|
206
|
+
const timer = IDLE_TIMERS.get(server);
|
|
207
|
+
if (timer !== undefined) {
|
|
208
|
+
clearTimeout(timer);
|
|
209
|
+
IDLE_TIMERS.delete(server);
|
|
210
|
+
}
|
|
211
|
+
const entry = CONNECTIONS.get(server);
|
|
212
|
+
if (entry === undefined) return;
|
|
213
|
+
CONNECTIONS.delete(server);
|
|
214
|
+
try {
|
|
215
|
+
const client = await entry;
|
|
216
|
+
await client.disconnect();
|
|
217
|
+
} catch {
|
|
218
|
+
// Best-effort; the session may already be broken.
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
function getConnection(server: string, factory: () => McpClient, idleMs: number): Promise<McpClient> {
|
|
223
|
+
let entry = CONNECTIONS.get(server);
|
|
224
|
+
if (entry === undefined) {
|
|
225
|
+
entry = (async () => {
|
|
226
|
+
const client = factory();
|
|
227
|
+
await client.connect();
|
|
228
|
+
return client;
|
|
229
|
+
})();
|
|
230
|
+
CONNECTIONS.set(server, entry);
|
|
231
|
+
// If the connect handshake fails, drop the rejected promise so the next
|
|
232
|
+
// call retries instead of caching the failure forever.
|
|
233
|
+
entry.catch(() => {
|
|
234
|
+
if (CONNECTIONS.get(server) === entry) CONNECTIONS.delete(server);
|
|
235
|
+
});
|
|
236
|
+
}
|
|
237
|
+
resetIdleTimer(server, idleMs);
|
|
238
|
+
return entry;
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/**
|
|
242
|
+
* Builds the per-server `{server}-callTool` activity. Reuses a worker-process
|
|
243
|
+
* MCP session opened lazily through the user-supplied factory — successive
|
|
244
|
+
* calls share one connection rather than reconnecting per call. Idle
|
|
245
|
+
* connections are disconnected after `idleMs` (defaults to
|
|
246
|
+
* {@link MCP_CONNECTION_IDLE_MS}).
|
|
247
|
+
*/
|
|
248
|
+
export function buildCallToolActivity(
|
|
249
|
+
server: string,
|
|
250
|
+
factory: () => McpClient,
|
|
251
|
+
idleMs: number = MCP_CONNECTION_IDLE_MS
|
|
252
|
+
): (input: CallToolInput) => Promise<JSONValue> {
|
|
253
|
+
const name = callToolActivityName(server);
|
|
254
|
+
const fn = async (input: CallToolInput): Promise<JSONValue> => {
|
|
255
|
+
ActivityContext.current().log.debug(`Calling MCP tool ${input.toolName} on server ${server}`, {
|
|
256
|
+
activityId: activityInfo().activityId,
|
|
257
|
+
});
|
|
258
|
+
const client = await getConnection(server, factory, idleMs);
|
|
259
|
+
// Dispatch by name without re-listing tools on the connection: the agent
|
|
260
|
+
// already has the schema from `listTools`, and `McpClient.callTool` only
|
|
261
|
+
// reads `tool.name` to build the request. A minimal `{ name }` matches the
|
|
262
|
+
// by-name dispatch the Python SDK does via `session.call_tool`.
|
|
263
|
+
const tool = { name: input.toolName } as unknown as Parameters<McpClient['callTool']>[0];
|
|
264
|
+
try {
|
|
265
|
+
return await client.callTool(tool, input.args);
|
|
266
|
+
} catch (err) {
|
|
267
|
+
// The session may be broken; drop it so the next call reconnects.
|
|
268
|
+
await _evictConnection(server);
|
|
269
|
+
throw err;
|
|
270
|
+
}
|
|
271
|
+
};
|
|
272
|
+
Object.defineProperty(fn, 'name', { value: name });
|
|
273
|
+
return fn;
|
|
274
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import { JsonBlock, TextBlock, Tool, ToolResultBlock } from '@strands-agents/sdk';
|
|
2
|
+
import type { JSONValue, ToolContext, ToolSpec, ToolStreamGenerator } from '@strands-agents/sdk';
|
|
3
|
+
import * as workflow from '@temporalio/workflow';
|
|
4
|
+
import type { ActivityOptions } from '@temporalio/workflow';
|
|
5
|
+
import type { CallToolInput, McpToolInfo } from './temporal-mcp-client';
|
|
6
|
+
import { callToolActivityName } from './temporal-mcp-client';
|
|
7
|
+
import { toJsonSchema } from './json-schema';
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Workflow-side stub for a single MCP tool. Each invocation dispatches the
|
|
11
|
+
* per-server `{server}-callTool` activity built by {@link StrandsPlugin}, then
|
|
12
|
+
* maps the raw MCP result (`{ content: [...], isError }`) into Strands
|
|
13
|
+
* content blocks.
|
|
14
|
+
*
|
|
15
|
+
* Text items map to {@link TextBlock}; everything else falls back to
|
|
16
|
+
* {@link JsonBlock}. Richer mappings (images, embedded resources) would
|
|
17
|
+
* require `McpTool`, which is bundled in `@strands-agents/sdk` but not
|
|
18
|
+
* re-exported from its public index.
|
|
19
|
+
*/
|
|
20
|
+
export class TemporalMCPTool extends Tool {
|
|
21
|
+
readonly name: string;
|
|
22
|
+
readonly description: string;
|
|
23
|
+
readonly toolSpec: ToolSpec;
|
|
24
|
+
readonly server: string;
|
|
25
|
+
private readonly activityOptions: ActivityOptions;
|
|
26
|
+
|
|
27
|
+
constructor(server: string, info: McpToolInfo, activityOptions: ActivityOptions) {
|
|
28
|
+
super();
|
|
29
|
+
this.server = server;
|
|
30
|
+
this.name = info.name;
|
|
31
|
+
this.description = info.description || `Tool which performs ${info.name}`;
|
|
32
|
+
this.toolSpec = {
|
|
33
|
+
name: info.name,
|
|
34
|
+
description: this.description,
|
|
35
|
+
inputSchema: toJsonSchema(info.inputSchema),
|
|
36
|
+
};
|
|
37
|
+
this.activityOptions = activityOptions;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
// eslint-disable-next-line require-yield
|
|
41
|
+
async *stream(toolContext: ToolContext): ToolStreamGenerator {
|
|
42
|
+
const { toolUseId, input } = toolContext.toolUse;
|
|
43
|
+
const activities = workflow.proxyActivities<{
|
|
44
|
+
[key: string]: (input: CallToolInput) => Promise<JSONValue>;
|
|
45
|
+
}>({
|
|
46
|
+
summary: this.name,
|
|
47
|
+
startToCloseTimeout: '10 minutes',
|
|
48
|
+
...this.activityOptions,
|
|
49
|
+
});
|
|
50
|
+
try {
|
|
51
|
+
const raw = await activities[callToolActivityName(this.server)]!({
|
|
52
|
+
toolName: this.name,
|
|
53
|
+
args: input,
|
|
54
|
+
});
|
|
55
|
+
const result = raw as { content?: unknown[]; isError?: boolean } | null;
|
|
56
|
+
if (result === null || typeof result !== 'object' || !Array.isArray(result.content)) {
|
|
57
|
+
return new ToolResultBlock({
|
|
58
|
+
toolUseId,
|
|
59
|
+
status: 'error',
|
|
60
|
+
content: [new TextBlock('Invalid MCP tool result: missing content array')],
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
const content = result.content.length
|
|
64
|
+
? result.content.map(mapMcpContent)
|
|
65
|
+
: [new TextBlock('Tool execution completed successfully with no output.')];
|
|
66
|
+
return new ToolResultBlock({
|
|
67
|
+
toolUseId,
|
|
68
|
+
status: result.isError ? 'error' : 'success',
|
|
69
|
+
content,
|
|
70
|
+
});
|
|
71
|
+
} catch (err) {
|
|
72
|
+
return new ToolResultBlock({
|
|
73
|
+
toolUseId,
|
|
74
|
+
status: 'error',
|
|
75
|
+
content: [new TextBlock(String(err instanceof Error ? err.message : err))],
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function mapMcpContent(item: unknown): TextBlock | JsonBlock {
|
|
82
|
+
if (typeof item === 'object' && item !== null) {
|
|
83
|
+
const obj = item as { type?: unknown; text?: unknown };
|
|
84
|
+
if (obj.type === 'text' && typeof obj.text === 'string') {
|
|
85
|
+
return new TextBlock(obj.text);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
return new JsonBlock({ json: item as JSONValue });
|
|
89
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { Model } from '@strands-agents/sdk';
|
|
2
|
+
import type { BaseModelConfig, Message, ModelStreamEvent, StreamOptions } from '@strands-agents/sdk';
|
|
3
|
+
import * as workflow from '@temporalio/workflow';
|
|
4
|
+
import type { ActivityOptions } from '@temporalio/workflow';
|
|
5
|
+
import { ApplicationFailure } from '@temporalio/common';
|
|
6
|
+
import type { Duration } from '@temporalio/common/lib/time';
|
|
7
|
+
import type { InvokeModelInput, InvokeModelStreamingInput, ModelActivity } from './model-activity';
|
|
8
|
+
|
|
9
|
+
const STRUCTURED_OUTPUT_DISABLED =
|
|
10
|
+
'TemporalModel.structuredOutput is not supported. Use ' +
|
|
11
|
+
'TemporalAgent({ structuredOutputSchema: ... }) which routes structured ' +
|
|
12
|
+
'output through stream() via the structured-output tool.';
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Options for {@link TemporalModel}.
|
|
16
|
+
*
|
|
17
|
+
* The {@link ActivityOptions} are applied to every activity invocation
|
|
18
|
+
* `stream()` schedules. `streamingTopic` and `streamingBatchInterval`
|
|
19
|
+
* forward {@link ModelStreamEvent}s on a {@link WorkflowStream} as
|
|
20
|
+
* they are produced inside the model activity.
|
|
21
|
+
*/
|
|
22
|
+
export interface TemporalModelOptions {
|
|
23
|
+
modelName?: string;
|
|
24
|
+
activityOptions?: ActivityOptions;
|
|
25
|
+
streamingTopic?: string;
|
|
26
|
+
streamingBatchInterval?: Duration;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* A Strands {@link Model} whose {@link Model.stream} runs as a Temporal
|
|
31
|
+
* activity. Constructing a `TemporalModel` does no I/O, so instances are
|
|
32
|
+
* safe to create at module load time.
|
|
33
|
+
*
|
|
34
|
+
* The `modelName` selects which factory the plugin will invoke worker-side;
|
|
35
|
+
* it must match a key in {@link StrandsPlugin}'s `models` map. A name not
|
|
36
|
+
* present in `models` raises an error inside the model activity at first call.
|
|
37
|
+
*/
|
|
38
|
+
export class TemporalModel extends Model<BaseModelConfig> {
|
|
39
|
+
private readonly modelName?: string;
|
|
40
|
+
private readonly activityOptions: ActivityOptions;
|
|
41
|
+
private readonly streamingTopic?: string;
|
|
42
|
+
private readonly streamingBatchInterval: Duration;
|
|
43
|
+
|
|
44
|
+
constructor(options: TemporalModelOptions = {}) {
|
|
45
|
+
super();
|
|
46
|
+
this.modelName = options.modelName;
|
|
47
|
+
this.activityOptions = options.activityOptions ?? {};
|
|
48
|
+
this.streamingTopic = options.streamingTopic;
|
|
49
|
+
this.streamingBatchInterval = options.streamingBatchInterval ?? '100 milliseconds';
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
override updateConfig(_config: BaseModelConfig): void {
|
|
53
|
+
// No-op; the real model is configured worker-side via the plugin's factories.
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
override getConfig(): BaseModelConfig {
|
|
57
|
+
return {};
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
override async *stream(messages: Message[], options?: StreamOptions): AsyncIterable<ModelStreamEvent> {
|
|
61
|
+
const proxiedActivities = workflow.proxyActivities<{
|
|
62
|
+
invokeModel(input: InvokeModelInput): Promise<ModelStreamEvent[]>;
|
|
63
|
+
invokeModelStreaming(input: InvokeModelStreamingInput): Promise<ModelStreamEvent[]>;
|
|
64
|
+
}>({
|
|
65
|
+
startToCloseTimeout: '10 minutes',
|
|
66
|
+
...this.activityOptions,
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
const events = this.streamingTopic
|
|
70
|
+
? await proxiedActivities.invokeModelStreaming({
|
|
71
|
+
modelName: this.modelName,
|
|
72
|
+
messages,
|
|
73
|
+
options,
|
|
74
|
+
streamingTopic: this.streamingTopic,
|
|
75
|
+
streamingBatchInterval: this.streamingBatchInterval,
|
|
76
|
+
})
|
|
77
|
+
: await proxiedActivities.invokeModel({
|
|
78
|
+
modelName: this.modelName,
|
|
79
|
+
messages,
|
|
80
|
+
options,
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
for (const event of events) {
|
|
84
|
+
yield event;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** Type tag used only to forward the `ModelActivity` type from the activity side. */
|
|
90
|
+
export type _ModelActivityRef = ModelActivity;
|
|
91
|
+
|
|
92
|
+
export function rejectStructuredOutput(): never {
|
|
93
|
+
throw ApplicationFailure.nonRetryable(STRUCTURED_OUTPUT_DISABLED);
|
|
94
|
+
}
|
package/src/workflow.ts
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Helpers for wiring Temporal activities into Strands' tool and hook surfaces.
|
|
3
|
+
*
|
|
4
|
+
* Both {@link activityAsTool} and {@link activityAsHook} produce workflow-side
|
|
5
|
+
* objects that dispatch user activities via {@link workflow.executeActivity},
|
|
6
|
+
* so the I/O actually happens off the workflow.
|
|
7
|
+
*
|
|
8
|
+
* @module
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import type { HookableEvent, HookCallback } from '@strands-agents/sdk';
|
|
12
|
+
import * as workflow from '@temporalio/workflow';
|
|
13
|
+
import type { ActivityOptions } from '@temporalio/workflow';
|
|
14
|
+
import { TemporalActivityTool, type ActivityAsToolOptions } from './temporal-activity-tool';
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Wrap a Temporal activity as a Strands tool.
|
|
18
|
+
*
|
|
19
|
+
* `activityName` must match the `name` registered on the worker (which
|
|
20
|
+
* defaults to the activity function's name). The returned {@link Tool}
|
|
21
|
+
* can be passed directly in {@link AgentConfig.tools}.
|
|
22
|
+
*/
|
|
23
|
+
export function activityAsTool(activityName: string, options: ActivityAsToolOptions = {}): TemporalActivityTool {
|
|
24
|
+
return new TemporalActivityTool(activityName, options);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Options for {@link activityAsHook}.
|
|
29
|
+
*
|
|
30
|
+
* `activityInput` extracts a serializable value from the event to pass as
|
|
31
|
+
* the activity's input. This is needed because events hold references to
|
|
32
|
+
* the `Agent` and `Tool` instances, which are not serializable.
|
|
33
|
+
*/
|
|
34
|
+
export interface ActivityAsHookOptions<E extends HookableEvent, I> {
|
|
35
|
+
activityInput: (event: E) => I;
|
|
36
|
+
activityOptions?: ActivityOptions;
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Wrap a Temporal activity as a Strands hook callback.
|
|
41
|
+
*
|
|
42
|
+
* The returned callback dispatches `activityName` as a Temporal activity
|
|
43
|
+
* each time the associated event fires. Register the callback with
|
|
44
|
+
* {@link Agent.addHook} or a {@link Plugin}'s hook registration.
|
|
45
|
+
*/
|
|
46
|
+
export function activityAsHook<E extends HookableEvent, I>(
|
|
47
|
+
activityName: string,
|
|
48
|
+
options: ActivityAsHookOptions<E, I>
|
|
49
|
+
): HookCallback<E> {
|
|
50
|
+
const activityOptions: ActivityOptions = {
|
|
51
|
+
startToCloseTimeout: '10 minutes',
|
|
52
|
+
...(options.activityOptions ?? {}),
|
|
53
|
+
};
|
|
54
|
+
return async function activityHookCallback(event: E): Promise<void> {
|
|
55
|
+
const activities = workflow.proxyActivities<{
|
|
56
|
+
[key: string]: (input: I) => Promise<unknown>;
|
|
57
|
+
}>(activityOptions);
|
|
58
|
+
await activities[activityName]!(options.activityInput(event));
|
|
59
|
+
};
|
|
60
|
+
}
|