Home/Tools/@tpmjs/registry-execute

registryExecuteTool

@tpmjs/registry-execute

Execute a tool from the TPMJS registry by toolId. Use registrySearchTool first to find toolIds.

Official
api-integration
v0.1.5
MIT

Interactive Playground

Test @tpmjs/registry-execute (registryExecuteTool) with AI-powered execution

0/2000 characters

Installation & Usage

Install this tool and use it with the AI SDK

1. Install the package

npm install @tpmjs/registry-execute
pnpm add @tpmjs/registry-execute
yarn add @tpmjs/registry-execute
bun add @tpmjs/registry-execute
deno add npm:@tpmjs/registry-execute

2. Import the tool

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

3. Use with AI SDK

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

const result = await generateText({
  model: openai('gpt-4o'),
  tools: { registryExecuteTool },
  prompt: 'Your prompt here...',
});

console.log(result.text);

AI Agent Integration

How AI agents can use this tool

Use Case

Use after finding a tool with registrySearchTool. Execute the tool by its toolId with the required parameters.

Examples

  • Execute '@exalabs/ai-sdk::webSearch' with query parameter
  • Execute '@firecrawl/ai-sdk::scrapeTool' with url parameter

Signature

(params: Record<string, unknown>, toolId: string, env?: Record<string, unknown>) => Promise<unknown>

Tags

ai-sdk
api-integration
execute
find
first
registry
registrysearchtool
toolid
toolids
tpmjs
vercel-ai

Parameters

Available configuration options

Auto-extracted
toolId
Required
Type: string

Tool identifier from registrySearchTool (format: 'package::name')

params
Required
Type: object

Parameters to pass to the tool

env
Optional
Type: object

Environment variables (API keys) if required by the tool

Schema extracted: 3/1/2026, 4:25:31 AM

README

@tpmjs/registry-execute

Execute tools from the TPMJS registry in any AI SDK agent. Tools run in a secure sandbox - no local installation required.

Installation

npm install @tpmjs/registry-execute
# or
pnpm add @tpmjs/registry-execute

Usage

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

const result = streamText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: {
    registrySearch: registrySearchTool,
    registryExecute: registryExecuteTool,
  },
  system: `You have access to the TPMJS tool registry.
Use registrySearch to find tools, then registryExecute to run them.`,
  prompt: 'Search for web scraping tools and scrape https://example.com',
});

// The agent can now:
// 1. Search for tools: registrySearch({ query: "web scraping" })
// 2. Execute found tools: registryExecute({ toolId: "@firecrawl/ai-sdk::scrapeTool", params: { url: "..." } })

Tool: registryExecuteTool

Execute a tool from the TPMJS registry by its toolId.

Parameters

NameTypeRequiredDescription
toolIdstringYesTool identifier (format: package::name)
paramsobjectYesParameters to pass to the tool
envobjectNoEnvironment variables (API keys) if required

Example

// Execute a web search tool
const result = await registryExecuteTool.execute({
  toolId: '@exalabs/ai-sdk::webSearch',
  params: { query: 'latest AI news' },
  env: { EXA_API_KEY: 'your-api-key' },
});

// Result:
// {
//   toolId: '@exalabs/ai-sdk::webSearch',
//   executionTimeMs: 1234,
//   output: { results: [...] }
// }

Returns

{
  "toolId": "@exalabs/ai-sdk::webSearch",
  "executionTimeMs": 1234,
  "output": { ... }
}

Environment Variables

VariableDefaultDescription
TPMJS_API_URLhttps://tpmjs.comBase URL for the registry API
TPMJS_EXECUTOR_URLhttps://executor.tpmjs.comURL for the sandbox executor

Self-Hosted Registry

To use your own TPMJS registry and executor:

export TPMJS_API_URL=https://registry.mycompany.com
export TPMJS_EXECUTOR_URL=https://executor.mycompany.com

Passing API Keys to Tools

Many tools require API keys to function (e.g., web scraping tools need a Firecrawl key, search tools need an Exa key). The recommended approach is to wrap registryExecuteTool with your pre-configured keys.

Recommended: Create a Wrapper

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!,
};

// 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 });
  },
});

Now use the wrapped tool in your agent:

import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { registrySearchTool } from '@tpmjs/registry-search';
import { registryExecute } from './tools';  // Your wrapped version

const result = streamText({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: {
    registrySearch: registrySearchTool,
    registryExecute,  // Keys are auto-injected
  },
  system: `You have access to the TPMJS tool registry.
Use registrySearch to find tools, then registryExecute to run them.`,
  prompt: 'Scrape https://example.com and summarize the content',
});

How It Works

  1. Search returns required keys: When you search for a tool, the response includes requiredEnvVars:

    {
      "toolId": "@firecrawl/ai-sdk::scrapeTool",
      "requiredEnvVars": ["FIRECRAWL_API_KEY"]
    }
  2. Your wrapper injects keys: The wrapped tool automatically passes your configured keys to the executor.

  3. Keys are injected into sandbox: The executor injects these as environment variables in the isolated Deno runtime where the tool runs.

Tools Without Required Keys

Some tools don't require any API keys (like @tpmjs/createblogpost). They work with or without the wrapper.

Security

  • All tools run in a sandboxed Deno environment on Railway
  • API keys are passed per-request, never stored
  • Keys are isolated to the specific tool execution
  • Only registered tools can be executed (no arbitrary code)

Related

License

MIT

Statistics

Downloads/month

382

GitHub Stars

0

Quality Score

87%

Bundle Size

NPM Keywords

tpmjs
ai-sdk
vercel-ai
registry
execute

Maintainers

thomasdavis(thomasalwyndavis@gmail.com)

Frameworks

vercel-ai
registryExecuteTool | TPMJS | TPMJS