Function Tools

Function tools allow you to create custom JavaScript functions that agents can execute in secure, isolated sandboxes. Unlike MCP servers that connect to external services, function tools run your own code directly within the agent framework.

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

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:

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:

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:

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

// 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"]
}

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 for serverless deployment configuration.

Runtime Configuration

Configure execution settings in your application:

import { createExecutionApp } from "@inkeep/agents-run-api";

const app = createExecutionApp({
  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

On this page