Bash / shell

Lets your agent run shell commands and act on the output. The two SDKs expose different tools here:

• TypeScript bash spawns a persistent bash process on the host. Shell state (variables, working directory, exported functions) persists across invocations within the same session, so the agent can build up context incrementally. Sessions can be restarted to clear state.
• Python shell (and TypeScript’s makeShell) routes each command through the agent’s Sandbox and is stateless: every call runs in a fresh shell, so variables and the working directory do not carry over. The sandbox decides the interpreter (sh locally and in Docker, the remote login shell over SSH), so use portable POSIX syntax.

Supported in: Node.js on Unix/Linux/macOS (TypeScript), all platforms (Python).

Security Warning

These tools execute arbitrary shell commands. Without a Sandbox, commands run with the full permissions of the process. Only use with trusted input and consider running in a sandboxed environment for production.

Example - File Operations:

TypeScript

import { Agent } from '@strands-agents/sdk'
import { bash } from '@strands-agents/sdk/vended-tools/bash'

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

// List files and create a new file
await agent.invoke('List all files in the current directory')
await agent.invoke('Create a new file called notes.txt with "Hello World"')

Python

from strands import Agent
from strands.vended_tools import shell

agent = Agent(tools=[shell])
agent("List all Python files in the current directory and count them")

Example - Session Persistence (TypeScript):

import { Agent } from '@strands-agents/sdk'
import { bash } from '@strands-agents/sdk/vended-tools/bash'

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

// Variables persist across invocations within the same session
await agent.invoke('Run: export MY_VAR="hello"')
await agent.invoke('Run: echo $MY_VAR') // Will show "hello"

// Restart session to clear state
await agent.invoke('Restart the bash session')
await agent.invoke('Run: echo $MY_VAR') // Variable will be empty

Full API reference: shell, bash (TypeScript only)

Tags

tool-authoring26