Built-in Tools

Use activeTools to restrict which tools are available per-agent or per-session. Use needsApproval to require human approval before specific tools execute.

import { agent } from "experimental-agent";

agent("my-agent", { activeTools: ["Read", "Grep", "List"] });

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

Read

Read files with optional pagination. For files over 200 lines, automatically shows first 100 lines unless a specific line range is provided.

Input

Output

Notes: Auto-paginates files over 200 lines (shows first 100). Use startLine and endLine for exact ranges on large files.

Grep

Search files with ripgrep. Find code patterns, function definitions, imports, etc.

Input

Output

Notes: Output truncated at ~50k chars. Use more specific pattern or path for large result sets.

List

Recursively list directory contents. Control depth for overview vs. detail.

Input

Output

Write

Write content to a file. Creates parent directories. Overwrites existing files.

Input

Output

Edit

Edit a file by exact string replacement. Fails if old_string is not found or appears multiple times.

Input

Output

Notes: Include enough surrounding context to make old_string unique. For multiple replacements, call the tool multiple times.

Bash

Execute bash commands. Returns stdout and stderr. Use waitUntil to control how long to wait.

Input

Output

Notes: waitUntil=0 returns immediately; process continues in sandbox. Large outputs truncated (~50k stdout, ~10k stderr); full content in outputDir.

Skill

Load a skill's full instructions by name. Call before following a skill. Only available when skills is configured.

Input

Output

Notes: Tool is omitted when skills is not set. Throws if skill not found.

JavaScript

Execute JavaScript code dynamically. Code runs as async function body with ctx in scope. Must return to produce output. Can call other tools as sub-tools via ctx.tools.

Input

Output

Returns whatever the code returns. undefined or missing return yields null.

Notes: Code runs in sandbox via Node.js. ctx has tools (call other tools), session, sandbox, storage, context. Execution timeout: 5 minutes. Can invoke Read, Write, Edit, Grep, List, Bash, and custom tools as sub-tools.

activeTools

Restrict which tools are available at agent or session level:

agent("my-agent", {
  activeTools: ["Read", "Grep", "List"],
});

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

Session-level activeTools overrides agent-level. Include both built-in and custom tool names.

builtinToolNames

Use for type-safe tool references:

import { builtinToolNames } from "experimental-agent";

builtinToolNames.Read;   // "Read"
builtinToolNames.Bash;   // "Bash"
builtinToolNames.Write;  // "Write"

See also

• agent() — Setting activeTools on the agent
• Session API — Overriding activeTools per session
• Custom Tools — Building tools with ToolContext
• Extending Built-in Tools — Wrapping or replacing built-ins
• Skills — Skill discovery and usage