Quick start: create your first tool plugin

This guide walks you through the complete local workflow of building your first system tool plugin using @fastgpt-plugin/cli and @fastgpt-plugin/sdk-factory.

Prerequisites

Ensure your local development environment has:

• Node.js: Node.js 22 (>= 22.23.2).
• pnpm: pnpm 10.
• FastGPT: v4.15.0 or later running instance.
• FastGPT Plugin: v1.0.0 or later plugin service.
• Git: For version control and code commits.

Step 1: Create the Plugin Skeleton

Initialize a single-tool plugin using the official CLI:

pnpx @fastgpt-plugin/cli create hello-tool --type tool

The command generates the hello-tool project in your current directory with standard files:

hello-tool/
├── index.ts          # Core plugin logic entrypoint, exports defineTool by default
├── index.spec.ts     # Unit test file
├── package.json      # Build and test scripts
├── tsconfig.json     # TypeScript configuration
├── vitest.config.ts  # Unit testing configuration
├── logo.svg          # Plugin icon
├── README.md         # Default plugin documentation
├── README.zh-CN.md   # Simplified Chinese documentation
└── README.en.md      # English documentation

Navigate into the directory and install dependencies:

cd hello-tool
pnpm install

Step 2: Implement Tool Logic and Schemas

Open index.ts to define the tool metadata, input schema, output schema, and execution handler:

import {
  createToolHandler,
  defineTool,
  type InputSchemaMetaType,
  type OutputSchemaMetaType
} from '@fastgpt-plugin/sdk-factory';
import z from 'zod';

const handler = createToolHandler({
  inputSchema: z.object({
    name: z
      .string()
      .min(1)
      .default('FastGPT')
      .meta({
        title: {
          en: 'User Name',
          'zh-CN': '用户名称'
        },
        description: {
          en: 'Name of the user to greet',
          'zh-CN': '输入需要问候的用户名称'
        },
        isToolParam: true
      } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    greeting: z.string().meta({
      title: 'Greeting'
    } satisfies OutputSchemaMetaType)
  }),
  handler: async (input) => {
    return {
      greeting: `Hello, ${input.name}!`
    };
  }
});

export default defineTool({
  manifest: {
    pluginId: 'hello-tool',
    version: '1.0.0',
    name: {
      en: 'Hello Tool',
      'zh-CN': '问候工具'
    },
    description: {
      en: 'Greet the user with a friendly message',
      'zh-CN': '输出友好的问候信息'
    },
    versionDescription: {
      en: 'Initial release',
      'zh-CN': '初始版本'
    },
    tags: ['tools']
  },
  handler
});

Key concepts:

• manifest.pluginId: Globally unique plugin identifier, recommended in lowercase hyphenated format.
• manifest.name and manifest.description: Bilingual text for English and Simplified Chinese, displayed in the FastGPT Studio according to user language preferences.
• inputSchema and outputSchema: Zod schemas that declare input and output types, enriched with .meta() attributes for UI rendering.
• handler: Business logic implementation whose returned values strictly conform to outputSchema.

Step 3: Validate inputs

Run these commands from the plugin directory to check the default value and the empty-string constraint:

pnpx @fastgpt-plugin/cli debug . --run --input '{}'
pnpx @fastgpt-plugin/cli debug . --run --input '{"name":""}'

The first call should return a result containing "greeting": "Hello, FastGPT!". The second should report an input validation error because name requires at least one character. These cases cover the schema's default and invalid-input behavior.

Step 4: Run Local Debugging

Use the CLI debug command to simulate inputs and inspect runtime outputs directly:

pnpx @fastgpt-plugin/cli debug . --run --input '{"name": "FastGPT User"}'

Check that the debug result contains this output:

{
  "greeting": "Hello, FastGPT User!"
}

Step 5: Build and Pack

After verification passes, execute the standard build and pack steps:

pnpm run build
pnpx @fastgpt-plugin/cli check --entry . --output ./dist
pnpm run pack

The commands produce hello-tool.pkg in the plugin root directory by default (or in the directory passed to --output). See the package and SDK reference for artifact details.

Step 6: Install and Verify in FastGPT

After generating the .pkg package, complete end-to-end acceptance in FastGPT:

1. Install plugin:
   • Open-source Community Edition: Sign in with the root system administrator account, go to Admin → System Tools in the bottom-left sidebar, click New Tool → Install from Local in the upper-right corner, upload hello-tool.pkg, and click Confirm import.
   • Commercial Edition: System administrators can import it under Admin → System Resources → System Tools → New Tool → Install from Local. When Allow teams to upload plugins is enabled under Admin → System Config → Feature Flags, a team administrator or owner can also import it under Studio → System Tools → New Tool → Install from Local.
2. Configure application: Open any Workflow or Chat Agent canvas, and add the newly installed "Hello Tool" (hello-tool) from the tool list.
3. Verify execution result: Send a test message in the debug preview to trigger the tool and inspect the node output in Run Details. A successful response contains:

{
  "greeting": "Hello, FastGPT!"
}

This completes the full delivery lifecycle from scaffolding, schema validation, and packaging to live application invocation.

Next Steps

• Learn advanced tool specifications and toolkit patterns: System Tool Development Guide
• Connect with a live FastGPT instance for remote debugging and distribution: Debugging, Packing, and Publishing
• Install the generated .pkg package into your team workspace: Install and Manage Team Plugins