FastGPTFastGPT

Initialization Script

Learn how to configure and execute initialization scripts in skill packages to prepare the skill running environment.

The skill initialization script is an optional pre-execution script provided by the skill developer. After the system successfully deploys and extracts your skill in an app, it automatically runs this script in an isolated virtual machine before executing the actual AI tasks.

Through the initialization script, you can automatically install third-party dependencies or perform necessary configurations before the skill code runs.


1. Skill Script Configuration and Execution Timing

To add an initialization script to your skill, simply place a Shell script named entrypoint.sh in the root directory of your skill package.

Skill Initialization Script Example

This example uses a root entrypoint.sh that prints Ready. The terminal shows manual execution in the editing workspace. Runtime initialization is verified separately after associating the published Skill with an Agent.

Execution Timing

  1. Deployment and Extraction: When a user runs an app referencing the skill, the system first deploys and extracts the skill package to the virtual machine at ./projects/<versionId>/.
  2. Script Execution: The system runs the entrypoint.sh script located in the root of the skill directory.

2. Smart Deduplication Mechanism

To prevent running environment initialization scripts repeatedly in subsequent conversations (for example, reinstalling dependencies on every turn would add substantial latency), FastGPT tracks successful initialization and skips repeated runs.

The execution state is stored in the ~/.fastgpt/runtime/state.json file inside the virtual machine.

  • Version ID Deduplication: Since the code and script content of a specific skill version (versionId) are immutable once published, the system tracks the successfully executed versionId inside the virtual machine.
  • Skipped Execution: When the same virtual machine instance is reused in subsequent turns, if the corresponding versionId has already executed successfully, the system will skip running the script, enabling hot starts.
  • New Version Trigger: Whenever a new skill version is published, the system will automatically deploy and run its initialization script upon the next conversation, regardless of whether it is an existing (old) or a new chat window.

3. Execution Constraints and Fault Tolerance

To ensure the smooth execution of the AI workflow, the skill initialization script must adhere to the same execution constraints and fault tolerance rules as the app startup script:

  • Execution Constraints and Non-blocking Fault Tolerance: The timeout protection (default 30 seconds), non-blocking workflow (failures do not block main execution), and 8 KiB execution-output limit (service logs separately truncate to 4,000 characters) are identical to those of the app startup script. For detailed parameters, please refer to App Startup Script Execution Constraints.
  • Debug Mode Limitation: In the skill edit mode, the virtual machine will not automatically execute the entrypoint.sh script. To verify the script's behavior, the skill developer can manually execute the commands in the Terminal panel at the bottom right of the editor.

Troubleshoot initialization

Current runtime state records successfully executed version IDs in skillEntrypoints. Inspect the deployed projects/<versionId>/entrypoint.sh, working directory, dependency-download network, and execution logs. Correct dependency or permission failures and verify the next initialization result. Use the state file for diagnosis; removing state manually can repeat initialization. This path describes the current implementation; check your release for older deployments.

Edit on GitHub

Last updated

On this page

Put your business knowledge to work with AI

Import company documents and build accurate, reliable, traceable AI answers.