Strands Agents TypeScript SDK

The repository contains several specialized examples demonstrating different orchestration patterns and integrations:

• first-agent: Demonstrates basic agent usage, including tool calling, the invoke method, and streaming response patterns.
• graph: Shows multi-agent orchestration using graph structures (linear flows, fan-out patterns, and streaming).
• swarm: Demonstrates swarm-based orchestration where agents drive handoffs between one another.
• mcp: Shows integration with the Model Context Protocol (MCP) to connect with external tool servers.
• agents-as-tools: Implements the pattern where an orchestrator agent delegates tasks to specialized agent-based tools.
• browser-agent: A browser-based agent capable of DOM manipulation (supports OpenAI, Anthropic, and Bedrock).
• telemetry: Demonstrates OpenTelemetry tracing integrated with Jaeger.

The system uses a WebAssembly (WASM) component architecture where the TypeScript SDK acts as the guest and Python acts as the host.

1. The Guest (TS SDK): The TypeScript SDK is compiled into a WASM component (strands-agent.wasm). It handles the agent runtime, including the event loop, model provider HTTP calls (Bedrock, Anthropic, OpenAI, Gemini), tools, hooks, and streaming.
2. The Host (Python): Python loads the WASM component via wasmtime-py and drives it.

The WIT Contract (wit/agent.wit) defines the boundary:

• Exports (TS $\rightarrow$ Python): The api interface allows Python to call into WASM for agent construction, streaming, and conversation management.
• Imports (Python $\rightarrow$ TS): The WASM guest calls back into Python via tool-provider to execute Python-defined tools, and via host-log to route logs to Python's logging framework.

A dependency MUST be a peer dependency if it crosses an API boundary—specifically, if users are expected to construct or pass instances of that dependency into the SDK.

For example, because users construct zod schemas and pass them into the tool function, zod is treated as a peer dependency.

import { z } from 'zod'
import { Agent, tool } from '@strands-agents/sdk'

const calculator = tool({
  name: 'calculator',
  inputSchema: z.object({ value: z.number() }),
  callback: (input) => input.value * 2,
})

const agent = new Agent({ model, tools: [calculator] })

The Bash tool maintains a persistent session for each agent instance. This means that environment variables, functions, and working directory changes (using cd) persist across multiple tool calls within the same session. Each agent instance receives its own isolated bash session, which is automatically cleaned up when the agent is garbage collected.

// Variables persist across commands in the same session
res = await agent.invoke('run export "MY_VAR=hello"')
res = await agent.invoke('run "echo $MY_VAR"')
// res.lastMessage will show "hello"

When writing tests for the Strands SDK, select your model provider based on the level of granularity required:

• MockMessageModel: Use this for agent loop tests and high-level flows. It is content-focused and designed to eliminate boilerplate by working with content blocks.
• TestModelProvider: Use this for low-level event streaming tests where you need precise control over individual events in the stream.

Follow these rules to determine the scope of your testing:

• Implementations: You MUST write tests for implementations (functions, classes, methods).
• Interfaces: You SHOULD NOT write tests for interfaces, as the TypeScript compiler already enforces type correctness.
• Complex Types: You SHOULD write Vitest type tests (*.test-d.ts) for complex types to ensure backwards compatibility.

The Graph pattern is used for deterministic execution. You define a set of agents as nodes and specify the execution order using edges. This allows for parallel execution and controlled workflows where downstream nodes run once dependencies are met.

import { Agent, BedrockModel, Graph } from '@strands-agents/sdk'

const model = new BedrockModel({ maxTokens: 1024 })

const researcher = new Agent({
  model,
  id: 'researcher',
  systemPrompt: 'Research the topic and provide key facts.',
})

const writer = new Agent({
  model,
  id: 'writer',
  systemPrompt: 'Rewrite the research into a polished paragraph.',
})

const graph = new Graph({
  nodes: [researcher, writer],
  edges: [['researcher', 'writer']],
})

const result = await graph.invoke('What is the largest ocean?')