contrib: add @temporalio/strands-agents plugin

[brianstrauch]

Summary

Adds @temporalio/strands-agents, a Temporal plugin that runs Strands Agents inside Temporal Workflows. Model invocations, MCP tool calls, and activityAsTool/activityAsHook calls all dispatch through Temporal Activities for durable execution and Temporal-managed retries.

API

// Workflow side
import { TemporalAgent, TemporalMCPClient, workflow as strandsWorkflow } from '@temporalio/strands-agents';

const agent = new TemporalAgent({
  model: 'bedrock',
  tools: [
    strandsWorkflow.activityAsTool('getWeather', { description: '…', inputSchema: { … } }),
    new TemporalMCPClient({ server: 'filesystem' }),
  ],
});
const result = await agent.invoke(prompt);

// Worker side
new StrandsPlugin({
  models: { bedrock: () => new BedrockModel({ … }) },
  mcpClients: { filesystem: () => new McpClient({ … }) },
});

Mirrors temporalio[strands-agents] from sdk-python (TemporalAgent, TemporalMCPClient, activity_as_tool, activity_as_hook, auto_heartbeater).

Workflow-bundle plumbing

@strands-agents/sdk@1.3.0's index transitively pulls fs, node:*, and MCP transport modules into any workflow that imports Agent/McpClient. StrandsPlugin.configureBundler handles this by:

• Ignoring fs (statically imported from vended-plugins/skills and vended-tools/file-editor, both unreachable from workflow code).
• Replacing node:fs/promises/os/path/process/stream and @modelcontextprotocol/sdk/client/{stdio,sse}.js with an empty stub via NormalModuleReplacementPlugin (dynamic imports inside mcp-config.js's server-only code paths).
• Disabling async chunks / code-splitting so webpack's JSONP chunk loader (which uses self/document) never ships in the bundle.

load-polyfills.ts installs Headers, web-streams-polyfill, @ungap/structured-clone, and a deterministic crypto.randomUUID backed by workflow.uuid4() — @ungap/structured-clone calls crypto.randomUUID() internally and Temporal's sink path uses structuredClone for log payloads, so without the polyfill the first logger.warn from inside an agent crashes the workflow.

TemporalMCPClient.listTools() returns lightweight TemporalMCPTool wrappers (lazy-required to break the cycle) because McpTool isn't re-exported from @strands-agents/sdk's public index. If strands-agents/sdk-typescript#1108 merges, temporal-mcp-tool.ts can be deleted entirely and TemporalMCPClient.listTools() can return real McpTool instances bound to itself — picking up the built-in content mapping for images, embedded resources, and URL-elicitation errors that our wrapper currently elides.

Tests

9 ava integration tests in contrib/strands/src/__tests__/test-strands.ts:

• Model dispatch via invokeModel activity
• activityAsTool end-to-end
• TemporalMCPClient listTools + callTool through per-server activities
• In-workflow tool() (Strands FunctionTool) running inside the sandbox
• activityAsHook on AfterToolCallEvent
• structuredOutputSchema via the strands_structured_output tool
• Activity-tool interrupt round-trip through the failure converter + workflow-signal resume
• streamingTopic events consumed via WorkflowStreamClient.subscribe
• Captured-history replay (validates the deterministic crypto.randomUUID polyfill stays replay-safe)

Test plan

• pnpm build clean
• pnpm test in contrib/strands — 9/9 passing
• Reviewer-side smoke: install in a downstream project and run a real agent against Bedrock

🤖 Generated with Claude Code

[JasonSteving99]

I still think this isn't necessarily validating what we need it to. With this not actually validating that the activity literally gets called, we wouldn't notice if some bug were introduced where the model returns a tool call, but this plugin somehow fails to invoke the activity. Right now this test is moreso testing the StubModel impl than the plugin itself.

Can you wrap the underlying activity (getWeather) def in something that logs the args that it was called with so we can assert that here? Should be fairly straightforward to even make an edit directly in ./activities/strands to collect that.

same comment on other similar tests

[JasonSteving99]

Let's also make sure we track the args to assert it's expected.

[JasonSteving99]

this is a good idea! How about we wire this idle timeout through as a plugin config option?

[JasonSteving99]

I'm not sure how i feel about the preemptive client.listTools() call here. If all the sdk asked for was a connection, maybe it's not going to ever call client.listTools() and this cache warming is wasted effort. Could you just extract some generic ttl caching utility and have two separate caches one for tools, and one for clients?

But on another note, is it even right to cache tools at all? MCP servers may redeploy or something and start publishing different tools, no?

[JasonSteving99]

I actually don't think you need this tool call activity to be listing the tools before calling the tool. As best as I can tell, the underlying callTool impl in strands makes MCP tool calls using literally just the tool name and the args which you already have here in the CallToolInput.

Is there another specific reason why this running on Temporal requires doing a tool lookup before calling each time? I could just be missing something (also sorry for not catching this on first review pass)