# System Tool Development Guide

> Learn how to build FastGPT system tool plugins from scratch, define input/output schemas and secrets, implement handlers, and package releases.

Source: https://doc.fastgpt.io/plugin/system-tool-development
Last Updated: 2026-11-12

## Introduction

This document targets system tool development after FastGPT v4.15.0. System tools use SDK definitions and are delivered to the FastGPT Plugin service as `.pkg` files for installation, updates, and runtime management. Model presets use a [static configuration contribution workflow](https://doc.fastgpt.io/plugin/model-presets).

The currently stable system tool plugin types are:

* Single tool: one plugin exposes one tool and is declared with `defineTool()`.
* Toolkit: one plugin exposes multiple related child tools and is declared with `defineToolSet()`.

System tool plugins run in the runtime provided by the FastGPT Plugin service. The FastGPT main service invokes tools through the plugin service, and plugin code uses `@fastgpt-plugin/sdk-factory` to describe input, output, secret configuration, and execution logic.

## Differences From The Legacy Mechanism

1. FastGPT and FastGPT Plugin remain separate services within a microservice architecture.
2. The plugin package protocol upgrades from the old built-in system tool directory to a unified `.pkg` format, making installation, version management, hot updates, and future plugin type expansion easier.
3. The plugin runtime is managed by the server. The current default runtime is `local-pool`, where each plugin version has its own process pool, queue, and runtime configuration.
4. Plugin metadata, input/output schemas, secret schemas, and icon assets are included in build artifacts for use by FastGPT pages, workflows, and Agents.
5. Tool development uses `@fastgpt-plugin/cli` and `@fastgpt-plugin/sdk-factory` to define schemas and build packages.

## Information To Collect Before Development

Clarify these items before coding:

| Information                      | Description                                                                                 |
| -------------------------------- | ------------------------------------------------------------------------------------------- |
| Plugin type                      | `tool` or `tool-suite`.                                                                     |
| Plugin ID                        | `pluginId`, globally stable and unique. Keep it unchanged after publishing.                 |
| Child tool ID                    | Required for Toolkits. `children[].id` stays unchanged after publishing.                    |
| Chinese and English names        | `name.en` and `name.zh-CN`.                                                                 |
| Chinese and English descriptions | `description.en` and `description.zh-CN`.                                                   |
| Inputs                           | Type, constraints, default value, UI title, and description for each field.                 |
| Outputs                          | Type, meaning, and downstream usage for each field.                                         |
| Secrets                          | API Key, Base URL, username/password, and similar values, described through `secretSchema`. |
| External API                     | Request method, auth method, timeout, rate limit, error response, and test account.         |
| File capability                  | Use `ctx.invoke.uploadFile()` when file upload is needed.                                   |
| Streaming output                 | Use `ctx.streamResponse()` when streaming text answers to the user.                         |
| Test cases                       | Include at least success, invalid parameters, auth failure, and upstream failure.           |

Missing information that affects plugin ID, auth method, billing, or listing security should be confirmed first. Other missing information can use reasonable defaults, with assumptions recorded in the submission notes.

## Developing With An Agent

When using Claude Code, Codex, or another agent tool, copy this prompt:

```plaintext
Develop a plugin using the following official FastGPT plugin development Skill:

https://raw.githubusercontent.com/labring/fastgpt-official-plugins/refs/heads/main/.agents/skills/develop-fastgpt-plugin/SKILL.md

Requirements:

1. Read and understand the complete Skill first, then follow its development workflow.
2. Before coding, collect the plugin name and type, Chinese and English names and descriptions, inputs and outputs, secrets, external APIs, expected behavior, error handling, and test cases.
3. If key requirements are missing, ask no more than three essential questions. When reasonable defaults are available, state the assumptions and continue.
4. Use `@fastgpt-plugin/cli` to create the plugin skeleton. Follow the repository's existing structure, naming, testing, and build conventions.
5. After implementation, run the required validation, including tests, build, plugin checks, and packaging. Explain anything that could not be validated.
6. In the final response, list changed files, validation results, remaining assumptions, and external API behavior that requires human confirmation.
```

When developing or maintaining SDK/CLI in the `fastgpt-plugin` repository, also refer to local skills:

* `sdk/factory/skills/fastgpt-plugin-development/SKILL.md`
* `sdk/factory/skills/fastgpt-system-tool-development/SKILL.md`
* `sdk/factory/skills/fastgpt-sdk-factory/SKILL.md`

## 1. Prepare Environment

Recommended environment:

* Node.js 22 (`>= 22.23.2`).
* `pnpm` 10; the `fastgpt-plugin` repository uses pnpm workspace.
* Git.
* GitHub CLI `gh`, used for forking, creating repositories, and submitting PRs.

When developing community plugins, first fork and clone the community repository:

```bash
gh repo fork labring/fastgpt-community-plugins --clone
cd fastgpt-community-plugins
pnpm install
```

When debugging the CLI or SDK in the `fastgpt-plugin` repository, install dependencies and build the CLI/SDK first:

```bash
pnpm install
pnpm build:sdk-factory
pnpm build:cli
```

## 2. Create Plugin Skeleton

Single-tool plugin:

```bash
pnpx @fastgpt-plugin/cli create my-tool --type tool --cwd packages/tools
```

Toolkit plugin:

```bash
pnpx @fastgpt-plugin/cli create my-tool-suite --type tool-suite --cwd packages/tools
```

You can also enter the target directory and create interactively:

```bash
pnpx @fastgpt-plugin/cli create
```

The CLI creates the plugin directory and common files:

| File               | Purpose                                                                                                         |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| `index.ts`         | Plugin entry, default-exporting `defineTool()` or `defineToolSet()`.                                            |
| `index.spec.ts`    | Unit test file.                                                                                                 |
| `package.json`     | Plugin dependencies and `build`, `build:dev`, `check`, `dev`, `debug`, `debug:run`, `pack`, and `test` scripts. |
| `tsconfig.json`    | TypeScript config.                                                                                              |
| `vitest.config.ts` | Test config.                                                                                                    |
| `README.md`        | Default plugin documentation.                                                                                   |
| `README.zh-CN.md`  | Simplified Chinese plugin documentation.                                                                        |
| `README.en.md`     | English plugin documentation.                                                                                   |
| `logo.svg`         | Main plugin icon.                                                                                               |

## 3. Implement Single Tool

The system tool entry must default-export an SDK factory instance:

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

const secretSchema = z.object({
  apiKey: z
    .string()
    .min(1)
    .meta({
      title: 'API Key',
      isSecret: true
    } satisfies SecretSchemaMetaType)
});

const handler = createToolHandler({
  inputSchema: z.object({
    query: z
      .string()
      .min(1)
      .meta({
        title: 'Query',
        description: 'Search keyword'
      } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    result: z.string().meta({
      title: 'Result'
    } satisfies OutputSchemaMetaType)
  }),
  secretSchema,
  handler: async (input, ctx) => {
    return {
      result: input.query
    };
  }
});

export default defineTool({
  manifest: {
    pluginId: 'example-search',
    version: '1.0.0',
    name: {
      en: 'Example Search',
      'zh-CN': '示例搜索'
    },
    description: {
      en: 'Search example data',
      'zh-CN': '搜索示例数据'
    },
    versionDescription: {
      en: 'Initial version',
      'zh-CN': '初始版本'
    },
    tags: ['tools']
  },
  handler
});
```

Core rules:

* Keep `pluginId`, child tool `id`, input field names, and output field names stable after publishing.
* Use `{ en, 'zh-CN' }` for `manifest.name`, `manifest.description`, and `versionDescription`.
* Describe inputs, outputs, and secrets with Zod schemas.
* Add `InputSchemaMetaType` to input fields and `OutputSchemaMetaType` to output fields.
* Add `SecretSchemaMetaType` to secret fields and set `isSecret: true` for sensitive fields.
* Handler return values must match `outputSchema`.
* Convert external API errors into actionable messages and avoid exposing secrets, tokens, or complete sensitive responses.
* Use `ctx.invoke.uploadFile()` when host file upload is needed, and prefer preserving the returned `err`.
* Use `ctx.streamResponse({ type: 'answer' | 'fastAnswer', content })` when streaming text answers to users.

## 4. Implement a Toolkit

Use `defineToolSet()` for Toolkits. Put shared information in the top-level `manifest` and `secretSchema`, and declare each child tool's independent `id`, name, description, and handler in `children`.

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

const secretSchema = z.object({
  apiKey: z.string().meta({
    title: 'API Key',
    isSecret: true
  } satisfies SecretSchemaMetaType)
});

const searchHandler = createToolHandler({
  inputSchema: z.object({
    query: z.string().meta({
      title: 'Query'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    items: z.array(z.string()).meta({
      title: 'Items'
    } satisfies OutputSchemaMetaType)
  }),
  secretSchema,
  handler: async (input) => ({ items: [input.query] })
});

const summaryHandler = createToolHandler({
  inputSchema: z.object({
    content: z.string().meta({
      title: 'Content'
    } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    summary: z.string().meta({
      title: 'Summary'
    } satisfies OutputSchemaMetaType)
  }),
  secretSchema,
  handler: async (input) => ({ summary: input.content.slice(0, 100) })
});

export default defineToolSet({
  manifest: {
    pluginId: 'text-tools',
    version: '1.0.0',
    name: {
      en: 'Text Tools',
      'zh-CN': '文本工具集'
    },
    description: {
      en: 'Search and summarize text',
      'zh-CN': '搜索和总结文本'
    }
  },
  children: [
    {
      id: 'search',
      name: { en: 'Search', 'zh-CN': '搜索' },
      description: { en: 'Search text', 'zh-CN': '搜索文本' },
      handler: searchHandler
    },
    {
      id: 'summary',
      name: { en: 'Summary', 'zh-CN': '总结' },
      description: { en: 'Summarize text', 'zh-CN': '总结文本' },
      handler: summaryHandler
    }
  ],
  secretSchema
});
```

## 5. Icon Conventions

During build, the CLI scans icons in the plugin root and writes them into the built `manifest.json`.

| Scenario           | File name                                                                   |
| ------------------ | --------------------------------------------------------------------------- |
| Main plugin icon   | `logo.svg`, `logo.png`, `logo.jpg`, `logo.jpeg`, `logo.webp`, or `logo.gif` |
| Toolkit child icon | `<childId>.logo.svg`, `<childId>.logo.png`, and similar names               |

Notes:

* Put icon files in the plugin root.
* The `<childId>` of a child icon must exactly match `children[].id`.
* Keep only one extension for the same icon to avoid ambiguous scan results.
* Child tools without their own icons reuse the main plugin icon by default.
* After build, check the `icon` field in `dist/manifest.json`.

## 6. Key Development Recipes

### 6.1 Authenticated External API Requests

When calling external third-party services requiring an API key, declare the secret field in `secretSchema` and extract it via `ctx.secrets` in the handler. Handle network and HTTP errors with actionable messages while keeping credentials omitted from logs and error text:

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

const secretSchema = z.object({
  apiKey: z
    .string()
    .min(1)
    .meta({
      title: 'API Key',
      isSecret: true
    } satisfies SecretSchemaMetaType)
});

const UPSTREAM_SEARCH_URL = 'https://api.example.com/v1/search';

const handler = createToolHandler({
  inputSchema: z.object({
    query: z
      .string()
      .min(1)
      .meta({
        title: 'Query',
        description: 'Search keyword sent to the trusted upstream service'
      } satisfies InputSchemaMetaType)
  }),
  outputSchema: z.object({
    status: z.string().meta({
      title: 'Status'
    } satisfies OutputSchemaMetaType),
    data: z.any().meta({
      title: 'Response Data'
    } satisfies OutputSchemaMetaType)
  }),
  secretSchema,
  handler: async (input, ctx) => {
    try {
      const requestUrl = new URL(UPSTREAM_SEARCH_URL);
      requestUrl.searchParams.set('q', input.query);
      const res = await fetch(requestUrl.toString(), {
        headers: {
          Authorization: `Bearer ${ctx.secrets.apiKey}`,
          'Content-Type': 'application/json'
        }
      });
      if (!res.ok) {
        throw new Error(`Upstream service returned status ${res.status}`);
      }
      const data = await res.json();
      return { status: 'success', data };
    } catch (err: any) {
      throw new Error(`External API request failed: ${err.message || 'unknown error'}`);
    }
  }
});
```

Keep the authenticated upstream endpoint fixed in a trusted server constant or controlled configuration so `ctx.secrets` credentials are sent only to verified hosts.

### 6.2 Host File Uploads And Artifact Return

When a tool produces generated files (such as reports, exported images, or media) and returns them to FastGPT callers, invoke the host upload capability `ctx.invoke.uploadFile()`. The host stores the artifact and returns an accessible URL:

```ts
handler: async (input, ctx) => {
  const content = Buffer.from(
    `Report for ${input.query}\nGenerated at ${new Date().toISOString()}`
  );
  const [result, err] = await ctx.invoke.uploadFile({
    file: content,
    fileName: 'report.txt',
    contentType: 'text/plain'
  });

  if (err) {
    throw new Error(`Failed to upload generated file: ${err}`);
  }

  return {
    fileUrl: result.accessURL,
    filename: 'report.txt'
  };
};
```

### 6.3 Streaming Text Answer Output

To stream text answer chunks directly to the conversation client during execution, call `ctx.streamResponse()` with `{ type: 'answer' | 'fastAnswer', content: string }`:

```ts
handler: async (input, ctx) => {
  await ctx.streamResponse({
    type: 'answer',
    content: 'Fetching remote resources...\n'
  });

  // Execute processing logic
  await ctx.streamResponse({
    type: 'answer',
    content: 'Processing complete.\n'
  });

  return { result: 'Operation completed successfully' };
};
```

### 6.4 Side Effects And Repeated Invocation Handling

FastGPT Workflows and Agents may call a tool multiple times during loop executions or retries. For operations with side effects (such as database writes, external charges, or messaging):

* **Business idempotency**: Include a unique identifier (such as `requestId` or `orderId`) in the input schema, and enforce idempotency on the external service.
* **State awareness**: Return existing outcomes for already completed external actions.
* **Explicit timeouts**: Set bounded timeouts on requests, detect cancellation signals, and stop pending downstream work promptly.

## 7. Debugging, Packaging, And Publishing Workflow

After implementing your tool, follow the unified delivery path in [debugging, packing, and publishing](https://doc.fastgpt.io/plugin/debugging-and-publishing):

1. **Local debugging**: Use `pnpx @fastgpt-plugin/cli debug . --run` to verify schemas, defaults, and boundary inputs. See [local debugging](https://doc.fastgpt.io/plugin/debugging-and-publishing#local-debugging).
2. **Remote debugging**: Connect to your FastGPT test environment using `pnpx @fastgpt-plugin/cli dev`. See [remote debugging](https://doc.fastgpt.io/plugin/debugging-and-publishing#remote-debugging).
3. **Build and pack**: Run `pnpm run build`, `cli check`, and `pnpm run pack` to generate `.pkg` artifacts. See [build, check, and pack](https://doc.fastgpt.io/plugin/debugging-and-publishing#build-check-pack).
4. **Pre-submission verification**: Check items against the [verification checklist](https://doc.fastgpt.io/plugin/debugging-and-publishing#verification-checklist).
5. **Publishing channels**: Choose community distribution, official distribution, or private commercial delivery. See [publishing workflow](https://doc.fastgpt.io/plugin/debugging-and-publishing#publishing-workflow).

## Design and Versioning Guidelines

### How should I choose between `tool` and `tool-suite`?

Use `tool` for a single capability. Use `tool-suite` for multiple capabilities that share authentication, the same upstream API, and strong business relevance, such as search, detail, and task creation in one plugin.

### How should plugin versions be managed?

Use semantic versioning for `manifest.version`. Upgrade patch for compatible fixes, minor for compatible new features, and major when changing input/output fields, child tool IDs, or user configuration. Evaluate existing workflow compatibility before major changes.

### Can I put API keys in code or environment variables?

Plugins should declare secrets through `secretSchema` and read them through `ctx.secrets`. Real secrets should not appear in code repositories, test snapshots, error logs, or README files.

### Is a test environment still needed after local debug passes?

Yes. Local debug quickly validates plugin logic and schemas. Test environment validation confirms real installation, runtime, host reverse invocation, network, and permission behavior.

## References

* [FastGPT Plugin Repository](https://github.com/labring/fastgpt-plugin)
* [System Plugin Development Guide](https://github.com/labring/fastgpt-plugin/blob/main/docs/dev/how-to-devlop-plugin.en.md)
* [SDK Factory Guide](https://github.com/labring/fastgpt-plugin/blob/main/sdk/factory/README.en.md)
* [CLI Guide](https://github.com/labring/fastgpt-plugin/blob/main/apps/cli/README.en.md)
