---
title: Tools
description: Use first-party AI SDK tools to add capabilities to agents and applications.
url: "https://ai-sdk.dev/docs/ai-sdk-core/tools"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

The AI SDK provides first-party tools for agents and applications. Each tool
includes its input schema, model-facing description, and
execution logic, ready to use with `generateText`, `streamText`, or `ToolLoopAgent`.
These tools work with any model that supports function calling.

Install tools from their individual `@ai-sdk/tool-*` packages.

For defining your own tools and configuring tool execution, see
[Tools and Tool Calling](/docs/ai-sdk-core/tools-and-tool-calling).

## Bash Tool

`createBashTool` lets agents run Bash commands to search, analyze, and transform files.
Supply an `Experimental_SandboxSession` to choose where commands run. Use
`@ai-sdk/sandbox-just-bash` for an in-memory environment,
`@ai-sdk/sandbox-vercel` for Vercel Sandbox, or your own implementation.
The tool has no direct dependency on either runtime.

### Installation

Install the tool and the sandbox adapter you want to use. The following examples
use just-bash:

```sh
pnpm add ai @ai-sdk/tool-bash @ai-sdk/sandbox-just-bash
```

Requires Node.js 22.13 or newer.

### Usage

```ts
import { createJustBashNetworkSandboxSession } from '@ai-sdk/sandbox-just-bash';
import { createBashTool } from '@ai-sdk/tool-bash';
import { generateText, isStepCount } from 'ai';

const session = await createJustBashNetworkSandboxSession();

try {
  const sandbox = session.restricted();
  await sandbox.writeTextFile({
    path: 'notes.txt',
    content: 'Apples: 10\nPears: 20\n',
  });
  const bash = await createBashTool({ sandbox });

  const result = await generateText({
    model, // Your configured model with function calling support.
    tools: { bash },
    stopWhen: isStepCount(5),
    prompt: 'Read notes.txt and write a summary to summary.txt.',
  });

  console.log(result.text);
  console.log(await sandbox.readTextFile({ path: 'summary.txt' }));
} finally {
  await session.destroy();
}
```

### Vercel Sandbox

Install `@ai-sdk/sandbox-vercel` and `@vercel/sandbox` to use an existing native
Vercel Sandbox. Wrap it with the adapter before passing it to the tool:

```ts
import { createVercelSandboxSessionFromNativeSandbox } from '@ai-sdk/sandbox-vercel';
import { createBashTool } from '@ai-sdk/tool-bash';
import { Sandbox } from '@vercel/sandbox';

const nativeSandbox = await Sandbox.create();

try {
  const sandbox = createVercelSandboxSessionFromNativeSandbox(nativeSandbox);
  await sandbox.writeTextFile({
    path: 'notes.txt',
    content: 'Hello from Vercel Sandbox',
  });
  const bash = await createBashTool({ sandbox });

  // Use bash with generateText, streamText, or ToolLoopAgent here.
} finally {
  await nativeSandbox.stop();
}
```

You can also create a managed session with
`createVercelNetworkSandboxSession()` from `@ai-sdk/sandbox-vercel` and pass
`session.restricted()`. For an existing native just-bash `Sandbox`, use
`createJustBashSandboxSessionFromNativeSandbox()` from `@ai-sdk/sandbox-just-bash`.
Raw runtime instances need their respective adapters; a custom
`Experimental_SandboxSession` can be passed directly.

### Options

`createBashTool()` requires an options object:

| Option             | Type                          | Description                                                                                                                   |
| ------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `sandbox`          | `Experimental_SandboxSession` | Required session for command execution and file operations.                                                                   |
| `workingDirectory` | `string`                      | Optional absolute starting directory for each command, created if needed. When omitted, uses the sandbox's default directory. |
| `maxOutputLength`  | `number`                      | Positive integer limiting characters retained from each output stream before a truncation notice. Defaults to `30000`.        |

The model calls the tool with `{ command: string }` and receives
`{ stdout, stderr, exitCode }`. Nonzero exit codes are returned so the model can
inspect failures and recover. AI SDK cancellation is forwarded to the session.
Output truncation happens after execution and does not limit execution memory or
duration.

### Files and lifecycle

Commands use the sandbox's default working directory unless `workingDirectory`
is provided. Without an override, creating the tool runs no setup commands.
Seed files through `sandbox.writeTextFile({ path, content })` before running the
tool. With an explicit working directory, use absolute paths to write files there.

The sandbox controls which files commands can access. Available programs, network
access, shell state, and persistence depend on the supplied sandbox. Its
description is included in the tool's instructions.

Tools using the same session share files. Creating a tool does not reset existing
files or create a new sandbox. Use separate sessions for independent workflows.
The caller creates, reconnects, and destroys the sandbox.

`createBashTool()` returns the tool directly, ready to use as `tools: { bash }`.
Use the supplied sandbox's `readTextFile({ path })` to read generated text files;
it returns `null` if the file is missing. Relative read paths depend on the
sandbox adapter; just-bash resolves them against its default directory. With an
explicit working directory, use absolute paths to read files from that directory.
The same session provides other file operations.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)