Plugin development overview
Choose a FastGPT extension path and understand tool plugins, model presets, SDKs, and delivery formats
This document applies to FastGPT Plugin v1.0.0 and later.
Plugin development is part of the FastGPT developer documentation. Choose a guide based on the capability you want to deliver:
| Goal | Start here | Delivery format |
|---|---|---|
| Build your first tool plugin | Quick start | Verify locally and generate a .pkg tool package |
| Implement a tool or Toolkit | Tool development guide | SDK definitions, debugging, building, and packaging |
| Add model or provider presets | Model preset guide | Update static configuration in the plugin repository and submit the changes |
| Develop Agent Skills | Skill development tutorial | Author code in sandbox and bind to Agent |
To install existing plugins, see team installation and management. System administrators (users signed in with the root account, with the Admin entry at the bottom-left of the sidebar) can use system tool management and plugin runtime configuration.
Recommended development baseline: FastGPT v4.15.0+, FastGPT Plugin v1.0.0+, Node.js 22 (>= 22.23.2), pnpm 10.
Background
FastGPT Plugin maintains the plugin service, SDKs, and CLI in a dedicated repository so plugins can evolve with their own versions. Tool authors create projects with the CLI, implement capabilities with the SDK, and deliver built packages to FastGPT.
Design Goals
- Independent iteration: maintain plugin source, versions, and publishing channels separately.
- Clear development paths: use the CLI and SDK from project creation through debugging and packaging.
- Runtime isolation: let the plugin service manage execution environments, process pools, and request scheduling.
- Resource-specific development: give each resource its own declarations, validation, and delivery workflow.
Core Concepts
| Term | Meaning |
|---|---|
| Plugin | A resource that extends FastGPT; its development steps depend on the resource type. |
| Tool | An API or computation exposed for Workflows and Agents to call. |
| Toolkit | Multiple child tools in one plugin with shared metadata and secret configuration. |
| Plugin package | The .pkg delivery file used to install and version tool plugins. |
| Model preset | Static provider, capability, and default-parameter configuration supplied by the plugin service. |
| Marketplace | A discovery and publishing channel for official and community plugins. |
| Runtime | The backend that runs plugin code and manages resources; the default is local-pool. |
| Pod | A plugin worker process in local-pool. |
Repository Structure
Plugin authors primarily use these entry points:
| Path | Responsibility |
|---|---|
apps/cli/ | Create, debug, build, check, and pack commands |
sdk/factory/ | Author SDK for tools, Toolkits, schemas, and handlers |
sdk/client/ | Client SDK used by the FastGPT main service to call the plugin service |
apps/server/ | Plugin server startup and HTTP interfaces |
packages/infrastructure/src/static-data/models/ | Model and provider presets |
For internal layers and dependencies, see the FastGPT Plugin architecture.
Repository Responsibilities
| Repository | Maintained content |
|---|---|
labring/fastgpt-plugin | Plugin service, CLI, SDKs, runtime, and model presets |
fastgpt-official-plugins | Officially maintained or reviewed tool plugins |
fastgpt-community-plugins | Community-contributed tool plugins |
fastgpt-business-plugins | Private, customer-specific, and commercial plugins |
Marketplace And Usage Boundaries
After verification, tool authors follow the publishing workflow for community, official, or private distribution. A team can also install a delivered .pkg directly. For discovery, permission review, and installation, see install from Marketplace.
Plugin Installation And Management
| Scope | Responsible role | Guide |
|---|---|---|
| Team installation, updates, and removal | Team administrator or owner | Install and manage team plugins |
| System-wide installation and configuration | System administrator (root account) | System tool management |
| Runtime capacity, environment variables, and troubleshooting | Deployment operator | Plugin runtime configuration |
Localized Plugin Metadata
When you provide { en, 'zh-CN' } locale objects in manifest and schemas along with localized README files (README.zh-CN.md, README.en.md), the FastGPT UI displays the active locale and falls back to Simplified Chinese and then English.
Packaging and Runtime
Tool plugins are delivered as .pkg packages and executed in the plugin service's local-pool process pool. See package and SDK reference for build artifacts and SDK entry points, and plugin runtime configuration for worker pool capacity and environment variables.
Development And Distribution
Start tool development with your first tool, then continue to debugging, packing, and publishing. Model presets are contributed as static repository configuration; follow the model preset guide to validate those changes.
References
Last updated