Tools

Built-in tools and custom tools that give agents capabilities beyond text generation.

Built-in tools read files, run commands, search codebases, and list directories. Custom tools can call external APIs, query databases, or perform any async operation. All tools execute inside the sandbox—an isolated environment.

Built-in Tools

experimental-agent includes 8 built-in tools. All execute inside the sandbox.

Tool	Description
Read	Read file contents with metadata. Supports line ranges for large files.
Write	Write content to a file. Creates parent directories. Overwrites existing files.
Edit	Replace an exact string in a file. Fails if the string is not unique.
Grep	Search for patterns using ripgrep. Filter by path, file type, glob.
List	Recursively list directory contents. Control depth and include hidden files.
Bash	Execute shell commands. Returns stdout, stderr, exit code. Use `waitUntil: 0` for fire-and-forget.
Skill	Load a skill's full instructions by name from configured `skills` sources.
JavaScript	Run JavaScript in the sandbox. Orchestrate multiple tool calls, transform results, parallelize with `Promise.all`.

All built-in tools run in the sandbox. The agent uses them automatically based on the system prompt and user requests.

Custom Tools

Add custom tools with tool() from the Vercel AI SDK (ai package), not from experimental-agent:

src/agent.ts

import { agent, type ToolContext } from "experimental-agent";
import { tool } from "ai";
import { z } from "zod";

export const myAgent = agent("my-agent", {
  model: "anthropic/claude-opus-4.6",
  tools: {
    Deploy: tool({
      description: "Deploy the project to Vercel",
      parameters: z.object({
        env: z.enum(["preview", "production"]),
      }),
      execute: async ({ env }, { experimental_context }) => {
        const ctx = experimental_context as ToolContext;
        const { authToken } = ctx.context;
        const res = await fetch("https://api.vercel.com/v13/deployments", {
          method: "POST",
          headers: {
            Authorization: `Bearer ${authToken}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ target: env }),
        });
        const data = await res.json();
        return { deploymentId: data.id, url: data.url };
      },
    }),
  },
  contextSchema: z.object({ authToken: z.string() }),
});

Custom tools receive ToolContext via experimental_context:

type ToolContext = {
  session: Session;
  sandbox: Sandbox;
  storage: Storage;
  context: TContext;  // From contextSchema, passed per-request via session.send()
};

Use ctx.sandbox to run commands or read files. Use ctx.storage for session/message lookups. Use ctx.context for auth tokens and other per-request data.

Restricting Tools

Use activeTools to limit which tools are available. Set at agent or session level:

const myAgent = agent("my-agent", {
  model: "anthropic/claude-opus-4.6",
  activeTools: ["Read", "Write", "Edit", "Grep", "List"],
});

const session = myAgent.session(chatId, {
  activeTools: ["Read", "Grep"],
});

Useful for sandboxing (e.g. read-only mode) or reducing token usage for simple tasks.

Next Steps

Build Your First Tool — Create a custom tool with typed input and output
Extending Built-in Tools — Wrap or augment built-in tools
Custom Tools — Advanced patterns and best practices
Sessions — Context and tags for tool execution

Tools

Built-in Tools

Custom Tools

Restricting Tools

Next Steps

On this page