# Function Tools (/typescript-sdk/tools/function-tools)

Create custom JavaScript functions that your agents can execute in secure sandboxes



Function tools allow you to create custom JavaScript functions that agents can execute in secure, isolated sandboxes. Unlike [MCP servers](/typescript-sdk/tools/mcp-tools) that connect to external services, function tools run your own code directly within the agent framework.

<Tip>
  For sensitive function tools (write/delete actions), require explicit user approval before execution. See
  [Tool approvals](/typescript-sdk/tools/tool-approvals).
</Tip>

<SkillRule id="function-tools-overview" skills="typescript-sdk" title="Function Tools Overview" description="Use cases and how to create function tools">
  ## Overview

  Function tools are perfect for:

  * **Custom business logic** - Implement domain-specific calculations or workflows
  * **Data processing** - Transform, validate, or analyze data using JavaScript
  * **API integrations** - Make HTTP calls to services that don't have MCP servers
  * **Utility functions** - Create reusable helper functions for your agents

  ## Creating Function Tools

  ### Basic Function Tool

  ```typescript
  import { agent, functionTool } from "@inkeep/agents-sdk";

  const calculateBMI = functionTool({
    name: "calculate-bmi",
    description: "Calculate BMI and health category",
    inputSchema: {
      type: "object",
      properties: {
        weight: { type: "number", description: "Weight in kilograms" },
        height: { type: "number", description: "Height in meters" },
      },
      required: ["weight", "height"],
    },
    execute: async ({ weight, height }) => {
      const bmi = weight / (height * height);
      let category = "Normal";
      if (bmi < 18.5) category = "Underweight";
      else if (bmi >= 30) category = "Obese";

      return { bmi: Math.round(bmi * 10) / 10, category };
    },
  });

  const healthAgent = subAgent({
    id: "health-agent",
    name: "Health Assistant",
    prompt: "I help with health calculations using available tools.",
    canUse: () => [calculateBMI],
  });
  ```

  ### Function Tool with Dependencies

  Dependencies are automatically detected from your code and use the versions installed in your project:

  ```typescript
  const fetchJoke = functionTool({
    name: "fetch-joke",
    description: "Fetch a random programming joke",
    inputSchema: {
      type: "object",
      properties: {},
      required: [],
    },
    // Dependencies detected automatically from require() calls
    execute: async () => {
      const axios = require("axios"); // Uses version from your project
      const response = await axios.get(
        "https://official-joke-api.appspot.com/jokes/programming/random"
      );
      return {
        setup: response.data[0].setup,
        punchline: response.data[0].punchline,
      };
    },
  });
  ```

  ### Pinning Dependency Versions

  If you need to pin to specific versions, specify them explicitly:

  ```typescript
  const fetchJoke = functionTool({
    name: "fetch-joke",
    description: "Fetch a random programming joke",
    dependencies: {
      axios: "1.6.0", // Pin to exact version
    },
    execute: async () => {
      const axios = require("axios");
      // Uses axios 1.6.0 regardless of your project version
      return {
        joke: "Why do programmers prefer dark mode? Because light attracts bugs!",
      };
    },
  });
  ```

  ### Built-in Node.js Modules

  Function tools have access to Node.js built-in modules:

  ```typescript
  const generatePassword = functionTool({
    name: "generate-password",
    description: "Generate a secure random password",
    inputSchema: {
      type: "object",
      properties: {
        length: { type: "number", default: 12, description: "Password length" },
      },
    },
    execute: async ({ length = 12 }) => {
      const crypto = require("crypto");
      const charset =
        "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*";

      let password = "";
      for (let i = 0; i < length; i++) {
        password += charset[crypto.randomInt(0, charset.length)];
      }

      return { password, length };
    },
  });
  ```

  ## Input Schema Validation

  Function tools use JSON Schema to validate input parameters. This ensures your functions receive properly typed and validated data.

  ### Supported JSON Schema Types

  ```typescript
  // Example schema showing common types
  {
    type: "object",
    properties: {
      name: { type: "string", description: "User name" },
      age: { type: "number", minimum: 0, description: "User age" },
      active: { type: "boolean", description: "Is active" },
      tags: { type: "array", items: { type: "string" } },
      status: { type: "string", enum: ["pending", "approved"] }
    },
    required: ["name"]
  }
  ```
</SkillRule>

<SkillRule id="function-tools-execution" skills="typescript-sdk" title="Function Tools Execution Environment" description="Sandbox providers, runtime configuration, and security guarantees">
  ## Execution Environment

  Function tools run in secure, isolated sandboxes that provide a safe execution environment for your code.

  ### Sandbox Providers

  The framework supports multiple sandbox providers:

  * **Native** (default) - Uses Node.js child processes, works in most environments including cloud VMs, Docker, Kubernetes, and traditional hosting
  * **Vercel** - Uses Vercel Sandbox MicroVMs for serverless environments where child process spawning is restricted (Vercel, AWS Lambda, etc.)

  The sandbox provider is configured at the application level when deploying. See [Deploy to Vercel](/deployment/vercel#step-2-configure-sandbox-in-your-application) for serverless deployment configuration.

  ### Runtime Configuration

  Configure execution settings in your application:

  ```typescript
  import { createAgentsApp } from "@inkeep/agents-api";

  const app = createAgentsApp({
    sandboxConfig: {
      provider: "native", // or 'vercel' for serverless
      runtime: "node22", // Node.js 22 or 'typescript'
      timeout: 30000, // 30 second timeout
      vcpus: 2, // Max 2 concurrent executions
    },
  });
  ```

  ### Security & Isolation

  Function tools execute with strong security guarantees:

  * **Isolated execution** - Each function runs in its own sandbox
  * **No file system access** - Cannot read or write outside the sandbox
  * **Network restrictions** - Only through explicitly declared dependencies
  * **Resource limits** - CPU, memory, and execution time constraints enforced
  * **No state persistence** - Functions are stateless between executions

  ### Best Practices

  * **Keep functions focused** - Each function should do one thing well
  * **Minimize dependencies** - Only include packages you actually need
  * **Handle errors gracefully** - Always catch and return meaningful errors
  * **Test independently** - Functions should be testable in isolation
  * **Document thoroughly** - Clear descriptions help agents use tools effectively
</SkillRule>