Quickstart Guide

Get your AI agent access to thousands of tools in under 5 minutes.

Prerequisites

What you need before starting

  • Node.js 18 or later
  • npm, pnpm, or yarn
  • An AI provider API key (OpenAI, Anthropic, or any AI SDK provider)

Step 1: Install the SDK

Add TPMJS packages to your project

Install the TPMJS SDK packages alongside the Vercel AI SDK:

npm

npm install @tpmjs/registry-search @tpmjs/registry-execute ai zod

pnpm

pnpm add @tpmjs/registry-search @tpmjs/registry-execute ai zod

yarn

yarn add @tpmjs/registry-search @tpmjs/registry-execute ai zod

Also install your preferred AI provider SDK:

# Anthropic (Claude)
npm install @ai-sdk/anthropic

# OpenAI (GPT-4, etc.)
npm install @ai-sdk/openai

# Google (Gemini)
npm install @ai-sdk/google

Step 2: Add Tools to Your Agent

Give your agent access to the TPMJS registry

Import the TPMJS tools and add them to your AI agent:

import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { registrySearchTool } from '@tpmjs/registry-search';
import { registryExecuteTool } from '@tpmjs/registry-execute';

// Create a streaming text generation with tools
const result = await streamText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: {
    registrySearch: registrySearchTool,
    registryExecute: registryExecuteTool,
  },
  system: `You are a helpful assistant with access to thousands of tools
via the TPMJS registry. Use registrySearch to find tools for any task,
then registryExecute to run them.`,
  prompt: 'Search for weather tools and get the current weather in Tokyo',
});

// Handle the streaming response
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

Step 3: Understanding the Tools

How registrySearch and registryExecute work

registrySearchTool

Searches the TPMJS registry to find tools for any task. Returns metadata including the toolId needed for execution.

// The agent will call this tool to search for tools
{
  "query": "web scraping",
  "category": "web-scraping",  // optional
  "limit": 5                    // optional
}

registryExecuteTool

Executes any tool from the registry by its toolId. Tools run in a secure sandbox—no local installation required.

// The agent will call this tool to execute a tool
{
  "toolId": "@firecrawl/ai-sdk::scrapeTool",
  "params": { "url": "https://example.com" },
  "env": { "FIRECRAWL_API_KEY": "..." }  // optional
}

Step 4: Configure API Keys

Pre-configure API keys for tools that need them

Many tools require API keys (e.g., Firecrawl, Exa, Tavily). Create a wrapper to auto-inject your keys:

Create tools.ts

import { tool } from 'ai';
import { registryExecuteTool } from '@tpmjs/registry-execute';

// Pre-configure your API keys
const API_KEYS: Record<string, string> = {
  FIRECRAWL_API_KEY: process.env.FIRECRAWL_API_KEY!,
  EXA_API_KEY: process.env.EXA_API_KEY!,
  TAVILY_API_KEY: process.env.TAVILY_API_KEY!,
};

// Create a wrapped version that auto-injects keys
export const registryExecute = tool({
  description: registryExecuteTool.description,
  parameters: registryExecuteTool.parameters,
  execute: async ({ toolId, params }) => {
    return registryExecuteTool.execute({ toolId, params, env: API_KEYS });
  },
});

Use the wrapped tool

import { registrySearchTool } from '@tpmjs/registry-search';
import { registryExecute } from './tools';

const result = await streamText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: {
    registrySearch: registrySearchTool,
    registryExecute,  // Uses your pre-configured keys
  },
  prompt: 'Scrape https://example.com',
});

Step 5: Complete Example

A full working example you can copy

agent.ts

import { streamText, generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { registrySearchTool } from '@tpmjs/registry-search';
import { registryExecuteTool } from '@tpmjs/registry-execute';

// Configure environment variables
const API_KEYS: Record<string, string> = {
  FIRECRAWL_API_KEY: process.env.FIRECRAWL_API_KEY || '',
  EXA_API_KEY: process.env.EXA_API_KEY || '',
};

// Create the wrapped execute tool
const registryExecute = {
  ...registryExecuteTool,
  execute: async (args: Parameters<typeof registryExecuteTool.execute>[0]) => {
    return registryExecuteTool.execute({
      ...args,
      env: { ...API_KEYS, ...args.env },
    });
  },
};

// Main agent function
async function runAgent(prompt: string) {
  const result = await generateText({
    model: anthropic('claude-sonnet-4-20250514'),
    tools: {
      registrySearch: registrySearchTool,
      registryExecute,
    },
    maxSteps: 5,  // Allow multiple tool calls
    system: `You are a helpful assistant with access to thousands of tools.

Available tool workflow:
1. Use registrySearch to find tools for your task
2. Use registryExecute to run the tools you find
3. Synthesize the results into a helpful response

Always search for tools first before attempting to execute them.`,
    prompt,
  });

  return result.text;
}

// Example usage
const response = await runAgent(
  'Search for web scraping tools, then scrape https://example.com and summarize it'
);
console.log(response);

Next Steps

Continue learning about TPMJS

Common Issues

Solutions to frequently encountered problems

Tool execution fails with "missing API key"

Check that you're passing the required environment variables in the env parameter of registryExecute.

registryExecute.execute({
  toolId: '@firecrawl/ai-sdk::scrapeTool',
  params: { url: 'https://example.com' },
  env: { FIRECRAWL_API_KEY: process.env.FIRECRAWL_API_KEY }  // Required!
})

Tool not found in search results

Try broader search terms or check the tool category. You can also browse the full registry at tpmjs.com.

Agent not using the tools

Make sure your system prompt clearly instructs the agent to use registrySearch first, then registryExecute. Also ensure maxSteps is set high enough (default is 1).

const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: { registrySearch, registryExecute },
  maxSteps: 5,  // Allow multiple tool calls
  system: 'Use registrySearch to find tools, then registryExecute to run them.',
  prompt: 'Your prompt here',
});