Choose the SDK, harness and runtime · Strands Agents Handbook

The mechanism

Strands is an ecosystem, not one executable. Current documentation calls the lower-level library the Strands Harness SDK. Python still installs as strands-agents and imports from strands; TypeScript installs as @strands-agents/sdk. The ready-made Strands harness assembles a larger set of defaults on top. Shell and Evals are separate projects with different responsibilities. Similar names do not imply identical permissions or release schedules.

The main path here uses Python because it makes the tool boundary easy to inspect. Official quickstarts require Python 3.10 or later; the TypeScript path requires Node.js 22 or later. Choose a supported patched runtime for your environment. This edition records Python SDK 1.58.0 and TypeScript SDK 1.19.0. A release pin is a reproducibility choice, not a promise that every future documentation page describes that release.

Application requirements

SDK + provider + tools

Pinned environment

Repeatable verification

A worked environment

Optional setup: package downloads use the network; these commands do not invoke a model. Run them in a new disposable project directory, outside a production repository. Windows users can activate the environment using the standard Scripts activation command for their shell.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'strands-agents==1.58.0'
python -c 'from importlib.metadata import version; print(version("strands-agents"))'
python -m pip freeze > requirements.lock.txt

The first pin constrains the main package. The resolved lock records transitive dependencies too. For an actual release pipeline, use your organization’s approved lock and integrity-checking workflow, record the Python version and preserve the artifact that was tested. Do not copy a broad pip freeze from an unrelated environment containing private package URLs or credentials.

No inference is needed to inspect the installation. Importing a library and creating a lock file are different from calling agent(...). Some providers need optional dependencies; install only the provider extra you intend to use. Chapter 3 makes provider and model selection explicit so default changes cannot silently alter the experiment.

Practice: write an environment card

Offline planning. Create a card with runtime version, SDK version, provider adapter, model identifier, region if applicable, dependency lock hash and source-check date. Leave model and region as “not selected” until you have approved access. Add a column for who owns upgrades.

Compare a tutorial using Agent.structured_output() with the current invocation-based structured output guide. Expected observation: a familiar method can remain in older examples after the preferred API changes. Record the mismatch and the replacement; do not silently claim both snippets were tested. Your environment card should make such disagreements visible to a future reader.

Troubleshooting and trade-offs

An import error can come from the wrong interpreter, a shadowing file named strands.py, or a missing provider extra. Check the active interpreter and package metadata before reinstalling globally. A successful import does not prove credentials or model availability. Conversely, a model-access failure does not imply that installation failed.

Experimental modules and evolving protocol integrations deserve separate upgrade tests. Keep experimental features behind an application boundary so a version change can be reviewed without rewriting every handler. The official support policy describes exceptions; avoid translating “semantic versioning” into an unconditional guarantee for every integration.

Interview practice

What would you record to reproduce an agent failure?

Runtime and dependency lock, SDK/provider versions, model identifier and region, sanitized input, tool contract versions, configuration, stop reason and trace identifiers. A package version alone cannot reproduce changing external services.

When would you choose a ready-made harness over the SDK?

When its defaults and included capabilities match the task and can be reviewed. Choose the SDK when you need explicit composition or a narrow authority surface. Evaluate the actual tool set and deployment constraints rather than the product name.

Completion check

Distinguish all four projects in one sentence each. Produce an environment card with unknown values visibly marked. Explain why this book pins versions while still directing readers to current security fixes and migration notes.

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.

YOUR NEXT STEP

Make the understanding yours.

Use the completion check above. Mark this chapter when you can explain the mechanism and its limits.

Self-assessed reading progress. This does not certify that a lab ran or a system is secure.