From 3768df804acdab8ac1d96efbfb2c7f08831a0ced Mon Sep 17 00:00:00 2001 From: Mackenzie Zastrow Date: Fri, 20 Mar 2026 14:43:20 -0400 Subject: [PATCH 1/4] docs: add TypeScript vended tools documentation Add comprehensive documentation for TypeScript SDK vended tools: - bash: Shell command execution with persistent sessions - fileEditor: File viewing, creation, and editing - httpRequest: HTTP requests to external APIs - notebook: Persistent text notebooks Includes: - Security warnings and responsibility model documentation - Code examples with TypeScript snippets - Links to SDK READMEs for detailed API reference - References to Interrupts/Hooks for consent workflows - Navigation update to include page under Tools section --- src/config/navigation.yml | 1 + .../concepts/tools/vended-tools-imports.ts | 34 ++++ .../concepts/tools/vended-tools.mdx | 157 ++++++++++++++++++ .../user-guide/concepts/tools/vended-tools.ts | 132 +++++++++++++++ 4 files changed, 324 insertions(+) create mode 100644 src/content/docs/user-guide/concepts/tools/vended-tools-imports.ts create mode 100644 src/content/docs/user-guide/concepts/tools/vended-tools.mdx create mode 100644 src/content/docs/user-guide/concepts/tools/vended-tools.ts diff --git a/src/config/navigation.yml b/src/config/navigation.yml index 1a173821..28210609 100644 --- a/src/config/navigation.yml +++ b/src/config/navigation.yml @@ -66,6 +66,7 @@ sidebar: - docs/user-guide/concepts/tools/mcp-tools - docs/user-guide/concepts/tools/executors - docs/user-guide/concepts/tools/community-tools-package + - docs/user-guide/concepts/tools/vended-tools - label: Plugins items: - docs/user-guide/concepts/plugins diff --git a/src/content/docs/user-guide/concepts/tools/vended-tools-imports.ts b/src/content/docs/user-guide/concepts/tools/vended-tools-imports.ts new file mode 100644 index 00000000..2809bf40 --- /dev/null +++ b/src/content/docs/user-guide/concepts/tools/vended-tools-imports.ts @@ -0,0 +1,34 @@ +// This file contains import snippets used in documentation examples. +// Each snippet is a standalone import block for a specific tool. + +// --8<-- [start:bash_import] +import { Agent } from '@strands-agents/sdk' +import { bash } from '@strands-agents/sdk/vended-tools/bash' +// --8<-- [end:bash_import] + +// --8<-- [start:file_editor_import] +import { Agent } from '@strands-agents/sdk' +import { fileEditor } from '@strands-agents/sdk/vended-tools/file-editor' +// --8<-- [end:file_editor_import] + +// --8<-- [start:http_request_import] +import { Agent } from '@strands-agents/sdk' +import { httpRequest } from '@strands-agents/sdk/vended-tools/http-request' +// --8<-- [end:http_request_import] + +// --8<-- [start:notebook_import] +import { Agent } from '@strands-agents/sdk' +import { notebook } from '@strands-agents/sdk/vended-tools/notebook' +// --8<-- [end:notebook_import] + +// --8<-- [start:notebook_persistence_import] +import { Agent, SessionManager, FileStorage } from '@strands-agents/sdk' +import { notebook } from '@strands-agents/sdk/vended-tools/notebook' +// --8<-- [end:notebook_persistence_import] + +// --8<-- [start:combined_import] +import { Agent } from '@strands-agents/sdk' +import { bash } from '@strands-agents/sdk/vended-tools/bash' +import { fileEditor } from '@strands-agents/sdk/vended-tools/file-editor' +import { notebook } from '@strands-agents/sdk/vended-tools/notebook' +// --8<-- [end:combined_import] diff --git a/src/content/docs/user-guide/concepts/tools/vended-tools.mdx b/src/content/docs/user-guide/concepts/tools/vended-tools.mdx new file mode 100644 index 00000000..fef05125 --- /dev/null +++ b/src/content/docs/user-guide/concepts/tools/vended-tools.mdx @@ -0,0 +1,157 @@ +--- +title: Vended Tools +description: "Pre-built tools included in the TypeScript SDK for common agent tasks like file operations, shell commands, HTTP requests, and persistent notes." +sidebar: + label: "Vended Tools" +languages: [typescript] +--- + +Vended tools are pre-built tools included directly in the Strands SDK for common agent tasks like file operations, shell commands, HTTP requests, and persistent notes. + +They ship as part of the SDK package and are updated alongside it โ€” see [Versioning & Maintenance](#versioning--maintenance) for details on how changes are communicated and what level of backwards compatibility they maintain. + +## Quick Start + +Each tool is imported from its own subpath under `@strands-agents/sdk/vended-tools` โ€” no additional packages required: + +```typescript +--8<-- "user-guide/concepts/tools/vended-tools.ts:basic_import" + +--8<-- "user-guide/concepts/tools/vended-tools.ts:agent_with_vended_tools" +``` + +## Available Tools + +| Tool | Description | Supported in | +|------|-------------|--------------| +| [File Editor](#file-editor) | View, create, and edit files | Node.js | +| [HTTP Request](#http-request) | Make HTTP requests to external APIs | Node.js 20+, browsers | +| [Notebook](#notebook) | Manage persistent text notebooks | Node.js, browsers | +| [Bash](#bash) | Execute shell commands with persistent sessions | Node.js (Unix/Linux/macOS) | + +### File Editor + +Gives your agent the ability to read and modify files on disk โ€” useful for coding agents, config management, or any workflow where the agent needs to inspect output and make targeted edits. + +_Supported in: Node.js only._ + +:::caution[Security Warning] +This tool reads and writes files with the full permissions of the Node.js process. Only use with trusted input and consider running in a sandboxed environment for production. +::: + +**Example:** +```typescript +--8<-- "user-guide/concepts/tools/vended-tools-imports.ts:file_editor_import" + +--8<-- "user-guide/concepts/tools/vended-tools.ts:file_editor_example" +``` + +๐Ÿ“– [Full API Reference](https://github.com/strands-agents/sdk-typescript/blob/main/src/vended-tools/file-editor/README.md) + +--- + +### HTTP Request + +Lets your agent call external APIs and fetch web content. Supports all HTTP methods, custom headers, and request bodies. Default timeout is 30 seconds. + +_Supported in: Node.js 20+, modern browsers._ + +**Example:** +```typescript +--8<-- "user-guide/concepts/tools/vended-tools-imports.ts:http_request_import" + +--8<-- "user-guide/concepts/tools/vended-tools.ts:http_request_example" +``` + +๐Ÿ“– [Full API Reference](https://github.com/strands-agents/sdk-typescript/blob/main/src/vended-tools/http-request/README.md) + +--- + +### Notebook + +A scratchpad the agent can read and write across invocations. The most effective use is giving the agent a notebook at the start of a task and instructing it to plan its work there โ€” it can break the task into steps, check things off as it goes, and always have a clear picture of what's left. Notebook state is part of the agent's state, so it persists automatically with [Session Management](../agents/session-management.mdx). + +_Supported in: Node.js, browsers._ + +**Example - Task Management:** +```typescript +--8<-- "user-guide/concepts/tools/vended-tools-imports.ts:notebook_import" + +--8<-- "user-guide/concepts/tools/vended-tools.ts:notebook_example" +``` + +**Example - State Persistence:** +```typescript +--8<-- "user-guide/concepts/tools/vended-tools-imports.ts:notebook_persistence_import" + +--8<-- "user-guide/concepts/tools/vended-tools.ts:notebook_state_persistence" +``` + +๐Ÿ“– [Full API Reference](https://github.com/strands-agents/sdk-typescript/blob/main/src/vended-tools/notebook/README.md) + +--- + +### Bash + +Lets your agent run shell commands and act on the output. 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. + +_Supported in: Node.js on Unix/Linux/macOS. Not supported on Windows._ + +:::caution[Security Warning] +This tool executes arbitrary bash commands without sandboxing. Commands run with the full permissions of the Node.js process. Only use with trusted input and consider running in sandboxed environments (containers, VMs) for production. +::: + +**Example - File Operations:** +```typescript +--8<-- "user-guide/concepts/tools/vended-tools-imports.ts:bash_import" + +--8<-- "user-guide/concepts/tools/vended-tools.ts:bash_example" +``` + +**Example - Session Persistence:** +```typescript +--8<-- "user-guide/concepts/tools/vended-tools-imports.ts:bash_import" + +--8<-- "user-guide/concepts/tools/vended-tools.ts:bash_session" +``` + +๐Ÿ“– [Full API Reference](https://github.com/strands-agents/sdk-typescript/blob/main/src/vended-tools/bash/README.md) + +--- + +## Using Multiple Tools Together + +Combine vended tools to build powerful agent workflows: + +```typescript +--8<-- "user-guide/concepts/tools/vended-tools-imports.ts:combined_import" + +--8<-- "user-guide/concepts/tools/vended-tools.ts:combined_tools_example" +``` + +## Differences from Community Tools + +Vended tools in TypeScript differ from the Python [Community Tools Package](community-tools-package.mdx) in how they handle tool consent. Python's community tools use the `BYPASS_TOOL_CONSENT` environment variable to control whether tools prompt for user confirmation before executing sensitive operations. TypeScript vended tools do not use environment variables and do not implement a built-in tool consent mechanismโ€”tools execute immediately when called by the agent. + +To implement approval workflows for sensitive operations in TypeScript, use the SDK's [Interrupts](../interrupts.mdx) feature to pause agent execution for human approval, or use [Hooks](../agents/hooks.mdx) to intercept tool calls with `BeforeToolCallEvent` and add custom validation or approval logic. + +| Feature | TypeScript (Vended Tools) | Python (Community Tools Package) | +|---------|---------------------------|----------------------------------| +| Package | Included in SDK | Separate `strands-agents-tools` package | +| Tool Count | 4 core tools | 30+ tools | +| Consent Workflow | Use Interrupts/Hooks | `BYPASS_TOOL_CONSENT` env var | +| Platform | Node.js (some browser support) | Python 3.10+ | + +## Versioning & Maintenance + +Vended tools ship as part of the SDK and are updated alongside it. Report bugs and feature requests in the [TypeScript SDK GitHub repository](https://github.com/strands-agents/sdk-typescript/issues). + +Tool parameters may be added or adjusted between releases to improve effectiveness โ€” these changes are noted in SDK release notes. Pin your SDK version and test after upgrades to avoid unexpected behavior. + +## See also + +- [Custom Tools](custom-tools.mdx) โ€” Build your own tools +- [Community Tools Package](community-tools-package.mdx) โ€” Python tools package with 30+ tools +- [Session Management](../agents/session-management.mdx) โ€” Persist agent state including notebooks +- [Interrupts](../interrupts.mdx) โ€” Implement approval workflows for sensitive operations +- [Hooks](../agents/hooks.mdx) โ€” Intercept and customize tool execution diff --git a/src/content/docs/user-guide/concepts/tools/vended-tools.ts b/src/content/docs/user-guide/concepts/tools/vended-tools.ts new file mode 100644 index 00000000..ece45414 --- /dev/null +++ b/src/content/docs/user-guide/concepts/tools/vended-tools.ts @@ -0,0 +1,132 @@ +// --8<-- [start:basic_import] +import { Agent } from '@strands-agents/sdk' +import { bash } from '@strands-agents/sdk/vended-tools/bash' +import { fileEditor } from '@strands-agents/sdk/vended-tools/file-editor' +import { httpRequest } from '@strands-agents/sdk/vended-tools/http-request' +import { notebook } from '@strands-agents/sdk/vended-tools/notebook' +// --8<-- [end:basic_import] + +// Agent with vended tools example +async function agentWithVendedToolsExample() { + // --8<-- [start:agent_with_vended_tools] + const agent = new Agent({ + tools: [bash, fileEditor, httpRequest, notebook], + }) + // --8<-- [end:agent_with_vended_tools] +} + +// Bash tool example - file operations +async function bashFileOperationsExample() { + // --8<-- [start:bash_example] + 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"') + // --8<-- [end:bash_example] +} + +// Bash tool example - session persistence +async function bashSessionPersistenceExample() { + // --8<-- [start:bash_session] + 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 + // --8<-- [end:bash_session] +} + +// File editor example +async function fileEditorExample() { + // --8<-- [start:file_editor_example] + const agent = new Agent({ + tools: [fileEditor], + }) + + // Create, view, and edit files + await agent.invoke('Create a file /tmp/config.json with {"debug": false}') + await agent.invoke('Replace "debug": false with "debug": true in /tmp/config.json') + await agent.invoke('View lines 1-10 of /tmp/config.json') + // --8<-- [end:file_editor_example] +} + +// HTTP request example +async function httpRequestExample() { + // --8<-- [start:http_request_example] + const agent = new Agent({ + tools: [httpRequest], + }) + + // Make API requests + await agent.invoke('Get data from https://api.example.com/users') + await agent.invoke('Post {"name": "John"} to https://api.example.com/users') + // --8<-- [end:http_request_example] +} + +// Notebook example - task management +async function notebookTaskExample() { + // --8<-- [start:notebook_example] + const agent = new Agent({ + tools: [notebook], + systemPrompt: + 'Before starting any multi-step task, create a notebook with a checklist of steps. ' + + 'Check off each step as you complete it.', + }) + + // The agent uses the notebook to plan and track its work + await agent.invoke('Write a project plan for building a personal budget tracker app') + // --8<-- [end:notebook_example] +} + +// Notebook state persistence example +async function notebookStatePersistenceExample() { + // --8<-- [start:notebook_state_persistence] + const session = new SessionManager({ + sessionId: 'my-session', + storage: { snapshot: new FileStorage('./sessions') }, + }) + + const agent = new Agent({ tools: [notebook], sessionManager: session }) + + // Notebooks are automatically persisted as part of the session + await agent.invoke('Create a notebook called "ideas" with "# Project Ideas"') + await agent.invoke('Add "- Build a web scraper" to the ideas notebook') + + // ... + + // Later, a new agent with the same session restores notebooks automatically + const restoredAgent = new Agent({ tools: [notebook], sessionManager: session }) + await restoredAgent.invoke('Read the ideas notebook') + // --8<-- [end:notebook_state_persistence] +} + +// Combined tools example - development workflow +async function combinedToolsExample() { + // --8<-- [start:combined_tools_example] + const agent = new Agent({ + tools: [bash, fileEditor, notebook], + systemPrompt: [ + 'You are a software development assistant.', + 'When given a feature to implement:', + '1. Use the notebook tool to create a plan with a checklist of steps', + '2. Work through each step, checking them off as you go', + '3. Use the bash tool to run tests and verify your changes', + ].join('\n'), + }) + + // Agent plans the work, implements it, and tracks progress + await agent.invoke( + 'Add input validation to the createUser function in src/users.ts. ' + + 'It should reject empty names and invalid email formats.', + ) + // --8<-- [end:combined_tools_example] +} From 718b2d405269951b9bd47f14032615998b294f7c Mon Sep 17 00:00:00 2001 From: Mackenzie Zastrow Date: Fri, 20 Mar 2026 15:20:31 -0400 Subject: [PATCH 2/4] Fix type errors --- .../docs/user-guide/concepts/tools/vended-tools-imports.ts | 3 +++ src/content/docs/user-guide/concepts/tools/vended-tools.ts | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/src/content/docs/user-guide/concepts/tools/vended-tools-imports.ts b/src/content/docs/user-guide/concepts/tools/vended-tools-imports.ts index 2809bf40..a1b4e06d 100644 --- a/src/content/docs/user-guide/concepts/tools/vended-tools-imports.ts +++ b/src/content/docs/user-guide/concepts/tools/vended-tools-imports.ts @@ -1,5 +1,8 @@ +// @ts-nocheck // This file contains import snippets used in documentation examples. // Each snippet is a standalone import block for a specific tool. +// @ts-nocheck is used because imports are intentionally repeated across snippets +// for documentation clarity โ€” each snippet shows the complete imports needed. // --8<-- [start:bash_import] import { Agent } from '@strands-agents/sdk' diff --git a/src/content/docs/user-guide/concepts/tools/vended-tools.ts b/src/content/docs/user-guide/concepts/tools/vended-tools.ts index ece45414..5d581e4e 100644 --- a/src/content/docs/user-guide/concepts/tools/vended-tools.ts +++ b/src/content/docs/user-guide/concepts/tools/vended-tools.ts @@ -1,5 +1,5 @@ // --8<-- [start:basic_import] -import { Agent } from '@strands-agents/sdk' +import { Agent, SessionManager, FileStorage } from '@strands-agents/sdk' import { bash } from '@strands-agents/sdk/vended-tools/bash' import { fileEditor } from '@strands-agents/sdk/vended-tools/file-editor' import { httpRequest } from '@strands-agents/sdk/vended-tools/http-request' From cb49cfe5869f4fcea987f9cbc16eb9a6c5cad007 Mon Sep 17 00:00:00 2001 From: Mackenzie Zastrow Date: Fri, 20 Mar 2026 15:46:12 -0400 Subject: [PATCH 3/4] Address review feedback --- src/content/docs/user-guide/concepts/tools/vended-tools.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/docs/user-guide/concepts/tools/vended-tools.ts b/src/content/docs/user-guide/concepts/tools/vended-tools.ts index 5d581e4e..2a43a868 100644 --- a/src/content/docs/user-guide/concepts/tools/vended-tools.ts +++ b/src/content/docs/user-guide/concepts/tools/vended-tools.ts @@ -1,10 +1,11 @@ // --8<-- [start:basic_import] -import { Agent, SessionManager, FileStorage } from '@strands-agents/sdk' +import { Agent } from '@strands-agents/sdk' import { bash } from '@strands-agents/sdk/vended-tools/bash' import { fileEditor } from '@strands-agents/sdk/vended-tools/file-editor' import { httpRequest } from '@strands-agents/sdk/vended-tools/http-request' import { notebook } from '@strands-agents/sdk/vended-tools/notebook' // --8<-- [end:basic_import] +import { SessionManager, FileStorage } from '@strands-agents/sdk' // Agent with vended tools example async function agentWithVendedToolsExample() { From ff43a8fbfdd0aa3da05675e7208088a8d3763b52 Mon Sep 17 00:00:00 2001 From: Mackenzie Zastrow Date: Fri, 27 Mar 2026 09:47:19 -0400 Subject: [PATCH 4/4] docs: remove differences section and clarify versioning stability --- .../user-guide/concepts/tools/vended-tools.mdx | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/src/content/docs/user-guide/concepts/tools/vended-tools.mdx b/src/content/docs/user-guide/concepts/tools/vended-tools.mdx index fef05125..293fd4ba 100644 --- a/src/content/docs/user-guide/concepts/tools/vended-tools.mdx +++ b/src/content/docs/user-guide/concepts/tools/vended-tools.mdx @@ -129,24 +129,11 @@ Combine vended tools to build powerful agent workflows: --8<-- "user-guide/concepts/tools/vended-tools.ts:combined_tools_example" ``` -## Differences from Community Tools - -Vended tools in TypeScript differ from the Python [Community Tools Package](community-tools-package.mdx) in how they handle tool consent. Python's community tools use the `BYPASS_TOOL_CONSENT` environment variable to control whether tools prompt for user confirmation before executing sensitive operations. TypeScript vended tools do not use environment variables and do not implement a built-in tool consent mechanismโ€”tools execute immediately when called by the agent. - -To implement approval workflows for sensitive operations in TypeScript, use the SDK's [Interrupts](../interrupts.mdx) feature to pause agent execution for human approval, or use [Hooks](../agents/hooks.mdx) to intercept tool calls with `BeforeToolCallEvent` and add custom validation or approval logic. - -| Feature | TypeScript (Vended Tools) | Python (Community Tools Package) | -|---------|---------------------------|----------------------------------| -| Package | Included in SDK | Separate `strands-agents-tools` package | -| Tool Count | 4 core tools | 30+ tools | -| Consent Workflow | Use Interrupts/Hooks | `BYPASS_TOOL_CONSENT` env var | -| Platform | Node.js (some browser support) | Python 3.10+ | - ## Versioning & Maintenance Vended tools ship as part of the SDK and are updated alongside it. Report bugs and feature requests in the [TypeScript SDK GitHub repository](https://github.com/strands-agents/sdk-typescript/issues). -Tool parameters may be added or adjusted between releases to improve effectiveness โ€” these changes are noted in SDK release notes. Pin your SDK version and test after upgrades to avoid unexpected behavior. +Tool names are stable and will not change. In minor versions, a tool's description, spec, or parameters may be updated to improve effectiveness โ€” these changes are noted in SDK release notes. Pin your SDK version and test after upgrades if your workflows depend on specific tool behavior. ## See also