Translate the design to TypeScript

The mechanism

The Python and TypeScript SDKs share the core agent-loop idea, but naming, type systems, event shapes and some capabilities differ. A language bridge should preserve the application contract, not transliterate every identifier. In Python, a decorator exposes a function as a tool; TypeScript uses tool() with a runtime schema and callback.

This chapter targets the recorded TypeScript SDK 1.19.0 baseline and the official Node.js 22+ prerequisite. Keep its dependency lock separate from the Python environment. The Evals project is documented as Python-only at this edition; do not infer evaluation-SDK parity from the existence of a TypeScript agent SDK.

A worked TypeScript tool

Optional package setup; no model call in the code below. In a new project, initialize ESM and install the pinned SDK plus the schema and development dependencies. Review the resulting lock file.

npm init -y
npm pkg set type=module
npm install @strands-agents/sdk@1.19.0 zod
npm install --save-dev typescript @types/node tsx

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

const lookupIncident = tool({
  name: 'lookup_incident',
  description: 'Read one synthetic incident. Never changes incident state.',
  inputSchema: z.object({
    incidentId: z.string().regex(/^INC-\d+$/),
  }),
  callback: ({ incidentId }) => ({
    incidentId,
    found: incidentId === 'INC-104',
    status: incidentId === 'INC-104' ? 'delayed' : 'unknown',
  }),
})

// Supply an explicitly configured, approved model before invoking.
export const tools = [lookupIncident]

The import of Agent shows the package boundary, while the tool export can be consumed by an application factory. A complete agent would use new Agent({ model, tools }) and await agent.invoke(...). Keep credentials and tenant identity in server-side application context; do not bundle them into browser code merely because the language is JavaScript.

The fixture’s camelCase fields are a deliberate TypeScript contract choice. If the tool must interoperate with the Python version, decide whether to standardize JSON names or write an explicit adapter. Silent field renaming can break evaluators and downstream consumers.

Practice: build a parity matrix

Offline. Compare input validation, missing-record behavior, output fields, error categories, cancellation and streaming between the two implementations. Mark each as identical, intentionally different or unverified. Reuse the same synthetic incident fixtures so you can distinguish semantic differences from different test data.

Expected observation: business parity is achievable without API-name parity. A TypeScript method may return a promise where the Python example is synchronous; a streaming event may be a typed object rather than a dictionary. The acceptance condition is the same user-visible contract under the same constraints.

Add one case with malformed input and one with an unknown incident. Then decide how both services represent an unavailable backend. Do not let one language return a successful “unknown” result while the other reports a retryable outage unless that difference is intentional.

Troubleshooting and trade-offs

Module-format errors usually belong to Node/TypeScript configuration, not model access. Check ESM settings and runtime requirements before debugging credentials. Missing provider packages belong to the selected adapter’s installation instructions. Follow the official provider import path for the pinned version rather than guessing from Python.

A shared specification and fixtures are often more valuable than forcing two implementations into identical internal structure. If only one runtime is needed, avoid maintaining two production paths just to demonstrate parity. This chapter is a bridge for readers whose surrounding systems already use TypeScript.

Interview practice

Completion check

Create a parity matrix with unknowns marked. Explain one API difference and one business invariant. Do not claim TypeScript execution was tested until you have actually compiled and run the chosen path.

Sources and version notes

Checked 6 October 2026. Python examples target strands-agents==1.58.0 unless labelled otherwise. Live documentation can change; compare your installed version before adapting an example.

• TypeScript quickstart
• Language-specific streaming
• TypeScript 1.19.0 release