SDK Reference

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

npm install ai zod

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

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

const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: { registrySearch: registrySearchTool },
  prompt: 'Find tools for web scraping',
});

interface SearchResult {
  query: string;
  matchCount: number;
  tools: Array<{
    toolId: string;           // Format: package::name
    name: string;             // Tool export name
    package: string;          // npm package name
    description: string;      // Tool description
    category: string;         // Tool category
    requiredEnvVars: string[]; // Required API keys
    healthStatus: 'HEALTHY' | 'UNHEALTHY' | 'UNKNOWN';
    qualityScore: number;     // 0.00 - 1.00
  }>;
}

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

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

const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: { registryExecute: registryExecuteTool },
  prompt: 'Execute the hello world tool',
});

interface ExecuteResult {
  toolId: string;           // The executed tool ID
  executionTimeMs: number;  // Execution time in milliseconds
  output: unknown;          // Tool output (varies by tool)
}

// Direct usage with env parameter
const result = await registryExecuteTool.execute({
  toolId: '@firecrawl/ai-sdk::scrapeTool',
  params: { url: 'https://example.com' },
  env: { FIRECRAWL_API_KEY: process.env.FIRECRAWL_API_KEY },
});

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

// Your pre-configured 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!,
  OPENAI_API_KEY: process.env.OPENAI_API_KEY!,
};

// Wrapped tool with pre-configured keys
export const registryExecute = tool({
  description: registryExecuteTool.description,
  parameters: registryExecuteTool.parameters,
  execute: async ({ toolId, params }) => {
    return registryExecuteTool.execute({
      toolId,
      params,
      env: API_KEYS,
    });
  },
});

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

// Search for tools directly
const searchResult = await registrySearchTool.execute({
  query: 'web scraping',
  limit: 5,
});

console.log('Found tools:', searchResult.tools);

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

// Execute a tool directly
const result = await registryExecuteTool.execute({
  toolId: '@tpmjs/hello::helloWorldTool',
  params: { name: 'World' },
});

console.log('Result:', result.output);

# .env
TPMJS_API_URL=https://registry.mycompany.com
TPMJS_EXECUTOR_URL=https://executor.mycompany.com

import type {
  SearchToolParams,
  SearchToolResult,
  ToolInfo,
} from '@tpmjs/registry-search';

// SearchToolParams
interface SearchToolParams {
  query: string;
  category?: string;
  limit?: number;
}

// SearchToolResult
interface SearchToolResult {
  query: string;
  matchCount: number;
  tools: ToolInfo[];
}

// ToolInfo
interface ToolInfo {
  toolId: string;
  name: string;
  package: string;
  description: string;
  category: string;
  requiredEnvVars: string[];
  healthStatus: 'HEALTHY' | 'UNHEALTHY' | 'UNKNOWN';
  qualityScore: number;
}

import type {
  ExecuteToolParams,
  ExecuteToolResult,
} from '@tpmjs/registry-execute';

// ExecuteToolParams
interface ExecuteToolParams {
  toolId: string;
  params: Record<string, unknown>;
  env?: Record<string, string>;
}

// ExecuteToolResult
interface ExecuteToolResult {
  toolId: string;
  executionTimeMs: number;
  output: unknown;
}

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

try {
  const result = await registryExecuteTool.execute({
    toolId: '@firecrawl/ai-sdk::scrapeTool',
    params: { url: 'https://example.com' },
    env: { FIRECRAWL_API_KEY: process.env.FIRECRAWL_API_KEY },
  });
  console.log('Success:', result);
} catch (error) {
  if (error instanceof Error) {
    console.error('Tool execution failed:', error.message);

    // Common error types:
    // - "Tool not found: ..." - Invalid toolId
    // - "Missing required env var: ..." - API key not provided
    // - "Execution timeout" - Tool took too long
    // - "Sandbox error: ..." - Tool runtime error
  }
}

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

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

// Wrapped execute tool with pre-configured keys
const registryExecute = tool({
  description: registryExecuteTool.description,
  parameters: registryExecuteTool.parameters,
  execute: async ({ toolId, params }) => {
    return registryExecuteTool.execute({ toolId, params, env: API_KEYS });
  },
});

// System prompt that guides the agent
const systemPrompt = `You are a helpful assistant with access to thousands of tools.

To complete tasks, follow this workflow:
1. Use registrySearch to find relevant tools
2. Review the search results and pick the best tool
3. Use registryExecute to run the tool with appropriate parameters
4. Synthesize the results into a helpful response

Always explain what you're doing and why.`;

// Main function
async function runAgent(userPrompt: string) {
  const result = await streamText({
    model: anthropic('claude-sonnet-4-20250514'),
    tools: {
      registrySearch: registrySearchTool,
      registryExecute,
    },
    maxSteps: 10,
    system: systemPrompt,
    prompt: userPrompt,
  });

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

  console.log('\n---');
  console.log('Tool calls:', (await result.toolCalls).length);
}

// Usage
await runAgent('Find a web scraping tool and scrape https://example.com');