# Create a bot

Source: https://langbot.app/docs/en/api-reference/bots/create-a-bot

## POST /api/v1/platform/bots



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots": {
      "post": {
        "tags": [
          "Bots"
        ],
        "summary": "Create a bot",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BotCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BotCreate": {
        "type": "object",
        "required": [
          "name",
          "adapter",
          "config"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Delete a bot

Source: https://langbot.app/docs/en/api-reference/bots/delete-a-bot

## DELETE /api/v1/platform/bots/{bot_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}": {
      "delete": {
        "tags": [
          "Bots"
        ],
        "summary": "Delete a bot",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get a bot

Source: https://langbot.app/docs/en/api-reference/bots/get-a-bot

## GET /api/v1/platform/bots/{bot_uuid}

Get bot details, including runtime information such as the webhook URL.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}": {
      "get": {
        "tags": [
          "Bots"
        ],
        "summary": "Get a bot",
        "description": "Get bot details, including runtime information such as the webhook URL.",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bot": {
                          "$ref": "#/components/schemas/Bot"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Bot": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string",
            "example": "telegram"
          },
          "config": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get bot event logs

Source: https://langbot.app/docs/en/api-reference/bots/get-bot-event-logs

## POST /api/v1/platform/bots/{bot_uuid}/logs

Get event log entries for the specified bot.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}/logs": {
      "post": {
        "tags": [
          "Bots"
        ],
        "summary": "Get bot event logs",
        "description": "Get event log entries for the specified bot.",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from_index": {
                    "type": "integer",
                    "description": "Starting index (-1 starts from the most recent entry)",
                    "default": -1
                  },
                  "max_count": {
                    "type": "integer",
                    "description": "Maximum number of entries to return",
                    "default": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "logs": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "total_count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List all bots

Source: https://langbot.app/docs/en/api-reference/bots/list-all-bots

## GET /api/v1/platform/bots



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots": {
      "get": {
        "tags": [
          "Bots"
        ],
        "summary": "List all bots",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bots": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Bot"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Bot": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string",
            "example": "telegram"
          },
          "config": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Send a message through a bot

Source: https://langbot.app/docs/en/api-reference/bots/send-a-message-through-a-bot

## POST /api/v1/platform/bots/{bot_uuid}/send_message

Send a message to a target through the specified bot. This endpoint supports API Key authentication only.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}/send_message": {
      "post": {
        "tags": [
          "Bots"
        ],
        "summary": "Send a message through a bot",
        "description": "Send a message to a target through the specified bot. This endpoint supports API Key authentication only.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "target_type",
                  "target_id",
                  "message_chain"
                ],
                "properties": {
                  "target_type": {
                    "type": "string",
                    "enum": [
                      "person",
                      "group"
                    ],
                    "description": "Target type"
                  },
                  "target_id": {
                    "type": "string",
                    "description": "Target ID (user ID or group ID)"
                  },
                  "message_chain": {
                    "type": "array",
                    "description": "Message chain",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "Plain",
                            "Image",
                            "At",
                            "Voice"
                          ],
                          "description": "Message element type"
                        },
                        "text": {
                          "type": "string",
                          "description": "Text content (Plain type)"
                        },
                        "url": {
                          "type": "string",
                          "description": "Image URL (Image type)"
                        },
                        "target": {
                          "type": "string",
                          "description": "Mention target ID (At type)"
                        }
                      }
                    },
                    "example": [
                      {
                        "type": "Plain",
                        "text": "Hello, World!"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "sent": {
                          "type": "boolean",
                          "example": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```

---

# Update a bot

Source: https://langbot.app/docs/en/api-reference/bots/update-a-bot

## PUT /api/v1/platform/bots/{bot_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}": {
      "put": {
        "tags": [
          "Bots"
        ],
        "summary": "Update a bot",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BotUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BotUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Create an embedding model

Source: https://langbot.app/docs/en/api-reference/embedding-models/create-an-embedding-model

## POST /api/v1/provider/models/embedding

Create a new embedding model. The model must be associated with an existing provider.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding": {
      "post": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "Create an embedding model",
        "description": "Create a new embedding model. The model must be associated with an existing provider.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingModelCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModelCreate": {
        "type": "object",
        "required": [
          "name",
          "provider_uuid"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "text-embedding-3-small"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Delete an embedding model

Source: https://langbot.app/docs/en/api-reference/embedding-models/delete-an-embedding-model

## DELETE /api/v1/provider/models/embedding/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}": {
      "delete": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "Delete an embedding model",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get an embedding model

Source: https://langbot.app/docs/en/api-reference/embedding-models/get-an-embedding-model

## GET /api/v1/provider/models/embedding/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}": {
      "get": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "Get an embedding model",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "model": {
                          "$ref": "#/components/schemas/EmbeddingModel"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModel": {
        "type": "object",
        "description": "Embedding model. Associated with a provider through provider_uuid.",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Model name (model ID)",
            "example": "text-embedding-3-small"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "Associated provider UUID"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List all embedding models

Source: https://langbot.app/docs/en/api-reference/embedding-models/list-all-embedding-models

## GET /api/v1/provider/models/embedding

List all embedding models. Use provider_uuid to filter models by provider.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding": {
      "get": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "List all embedding models",
        "description": "List all embedding models. Use provider_uuid to filter models by provider.",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by provider UUID"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "models": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/EmbeddingModel"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModel": {
        "type": "object",
        "description": "Embedding model. Associated with a provider through provider_uuid.",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Model name (model ID)",
            "example": "text-embedding-3-small"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "Associated provider UUID"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Test an embedding model

Source: https://langbot.app/docs/en/api-reference/embedding-models/test-an-embedding-model

## POST /api/v1/provider/models/embedding/{model_uuid}/test

Send a test request to the specified embedding model to verify that it is available.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}/test": {
      "post": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "Test an embedding model",
        "description": "Send a test request to the specified embedding model to verify that it is available.",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "Text to use for the test",
                    "example": "Hello"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Update an embedding model

Source: https://langbot.app/docs/en/api-reference/embedding-models/update-an-embedding-model

## PUT /api/v1/provider/models/embedding/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}": {
      "put": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "Update an embedding model",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingModelUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModelUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Upload a document

Source: https://langbot.app/docs/en/api-reference/files/upload-a-document

## POST /api/v1/files/documents

Upload a document file up to 10 MB. After the upload, use the file_id to associate the document with a knowledge base.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/files/documents": {
      "post": {
        "tags": [
          "Files"
        ],
        "summary": "Upload a document",
        "description": "Upload a document file up to 10 MB. After the upload, use the file_id to associate the document with a knowledge base.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Document file"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "file_id": {
                          "type": "string",
                          "description": "File ID that can be used to associate the document with a knowledge base"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Upload an image

Source: https://langbot.app/docs/en/api-reference/files/upload-an-image

## POST /api/v1/files/images

Upload an image file. Supported formats are jpg, jpeg, png, gif, and webp. The maximum file size is 10 MB.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/files/images": {
      "post": {
        "tags": [
          "Files"
        ],
        "summary": "Upload an image",
        "description": "Upload an image file. Supported formats are jpg, jpeg, png, gif, and webp. The maximum file size is 10 MB.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Image file"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Uploaded successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "file_key": {
                          "type": "string",
                          "description": "File identifier that can be used to reference the image"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Add a file to a knowledge base

Source: https://langbot.app/docs/en/api-reference/knowledge-bases/add-a-file-to-a-knowledge-base

## POST /api/v1/knowledge/bases/{kb_uuid}/files

Associate an uploaded file with a knowledge base and begin parsing it. First upload the file through /api/v1/files/documents to obtain a file_id.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/files": {
      "post": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "Add a file to a knowledge base",
        "description": "Associate an uploaded file with a knowledge base and begin parsing it. First upload the file through /api/v1/files/documents to obtain a file_id.",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "file_id"
                ],
                "properties": {
                  "file_id": {
                    "type": "string",
                    "description": "Uploaded file ID"
                  },
                  "parser_plugin_id": {
                    "type": "string",
                    "description": "Parser plugin ID to use (optional)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Create a knowledge base

Source: https://langbot.app/docs/en/api-reference/knowledge-bases/create-a-knowledge-base

## POST /api/v1/knowledge/bases



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases": {
      "post": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "Create a knowledge base",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "engine_plugin_id": {
                    "type": "string",
                    "description": "Knowledge engine plugin ID (author/name format)"
                  },
                  "creation_settings": {
                    "type": "object",
                    "description": "Engine creation parameters"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Delete a knowledge base

Source: https://langbot.app/docs/en/api-reference/knowledge-bases/delete-a-knowledge-base

## DELETE /api/v1/knowledge/bases/{kb_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}": {
      "delete": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "Delete a knowledge base",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get a knowledge base

Source: https://langbot.app/docs/en/api-reference/knowledge-bases/get-a-knowledge-base

## GET /api/v1/knowledge/bases/{kb_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}": {
      "get": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "Get a knowledge base",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "base": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List all knowledge bases

Source: https://langbot.app/docs/en/api-reference/knowledge-bases/list-all-knowledge-bases

## GET /api/v1/knowledge/bases



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases": {
      "get": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "List all knowledge bases",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bases": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List knowledge base files

Source: https://langbot.app/docs/en/api-reference/knowledge-bases/list-knowledge-base-files

## GET /api/v1/knowledge/bases/{kb_uuid}/files



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/files": {
      "get": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "List knowledge base files",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "files": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Remove a file from a knowledge base

Source: https://langbot.app/docs/en/api-reference/knowledge-bases/remove-a-file-from-a-knowledge-base

## DELETE /api/v1/knowledge/bases/{kb_uuid}/files/{file_id}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": {
      "delete": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "Remove a file from a knowledge base",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Retrieve from a knowledge base

Source: https://langbot.app/docs/en/api-reference/knowledge-bases/retrieve-from-a-knowledge-base

## POST /api/v1/knowledge/bases/{kb_uuid}/retrieve

Perform semantic retrieval against a knowledge base and return relevant document chunks.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/retrieve": {
      "post": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "Retrieve from a knowledge base",
        "description": "Perform semantic retrieval against a knowledge base and return relevant document chunks.",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Retrieval query text"
                  },
                  "retrieval_settings": {
                    "type": "object",
                    "description": "Retrieval parameters (such as top_k)",
                    "properties": {
                      "top_k": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Update a knowledge base

Source: https://langbot.app/docs/en/api-reference/knowledge-bases/update-a-knowledge-base

## PUT /api/v1/knowledge/bases/{kb_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}": {
      "put": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "Update a knowledge base",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get the knowledge engine creation schema

Source: https://langbot.app/docs/en/api-reference/knowledge-engines/get-the-knowledge-engine-creation-schema

## GET /api/v1/knowledge/engines/{plugin_id}/creation-schema

Get the JSON Schema for the specified knowledge engine's creation parameters.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/engines/{plugin_id}/creation-schema": {
      "get": {
        "tags": [
          "Knowledge Engines"
        ],
        "summary": "Get the knowledge engine creation schema",
        "description": "Get the JSON Schema for the specified knowledge engine's creation parameters.",
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Plugin ID (author/name format)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get the knowledge engine retrieval schema

Source: https://langbot.app/docs/en/api-reference/knowledge-engines/get-the-knowledge-engine-retrieval-schema

## GET /api/v1/knowledge/engines/{plugin_id}/retrieval-schema

Get the JSON Schema for the specified knowledge engine's retrieval parameters.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/engines/{plugin_id}/retrieval-schema": {
      "get": {
        "tags": [
          "Knowledge Engines"
        ],
        "summary": "Get the knowledge engine retrieval schema",
        "description": "Get the JSON Schema for the specified knowledge engine's retrieval parameters.",
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Plugin ID (author/name format)"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List available knowledge engines

Source: https://langbot.app/docs/en/api-reference/knowledge-engines/list-available-knowledge-engines

## GET /api/v1/knowledge/engines

List all plugin-provided knowledge engines, including their capabilities and configuration schemas.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/engines": {
      "get": {
        "tags": [
          "Knowledge Engines"
        ],
        "summary": "List available knowledge engines",
        "description": "List all plugin-provided knowledge engines, including their capabilities and configuration schemas.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "engines": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Create an LLM model

Source: https://langbot.app/docs/en/api-reference/llm-models/create-an-llm-model

## POST /api/v1/provider/models/llm

Create a new large language model. The model must be associated with an existing provider.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm": {
      "post": {
        "tags": [
          "LLM Models"
        ],
        "summary": "Create an LLM model",
        "description": "Create a new large language model. The model must be associated with an existing provider.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LLMModelCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModelCreate": {
        "type": "object",
        "required": [
          "name",
          "provider_uuid"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Model name (model ID)",
            "example": "gpt-4o"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "Associated provider UUID"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "chat",
              "vision"
            ]
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Delete an LLM model

Source: https://langbot.app/docs/en/api-reference/llm-models/delete-an-llm-model

## DELETE /api/v1/provider/models/llm/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}": {
      "delete": {
        "tags": [
          "LLM Models"
        ],
        "summary": "Delete an LLM model",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get an LLM model

Source: https://langbot.app/docs/en/api-reference/llm-models/get-an-llm-model

## GET /api/v1/provider/models/llm/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}": {
      "get": {
        "tags": [
          "LLM Models"
        ],
        "summary": "Get an LLM model",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "model": {
                          "$ref": "#/components/schemas/LLMModel"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModel": {
        "type": "object",
        "description": "Large language model. Associated with a provider through provider_uuid and inherits the provider's API endpoint and keys.",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Model name (the model ID sent as the API model parameter)",
            "example": "gpt-4o"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "Associated provider UUID"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Model capability tags",
            "example": [
              "chat",
              "vision",
              "tool-use"
            ]
          },
          "extra_args": {
            "type": "object",
            "description": "Additional parameters (such as temperature and max_tokens)"
          },
          "prefered_ranking": {
            "type": "integer",
            "description": "Priority ranking (higher values take precedence)",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List all LLM models

Source: https://langbot.app/docs/en/api-reference/llm-models/list-all-llm-models

## GET /api/v1/provider/models/llm

List all large language models. Use provider_uuid to filter models by provider.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm": {
      "get": {
        "tags": [
          "LLM Models"
        ],
        "summary": "List all LLM models",
        "description": "List all large language models. Use provider_uuid to filter models by provider.",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter by provider UUID"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "models": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/LLMModel"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModel": {
        "type": "object",
        "description": "Large language model. Associated with a provider through provider_uuid and inherits the provider's API endpoint and keys.",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Model name (the model ID sent as the API model parameter)",
            "example": "gpt-4o"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "Associated provider UUID"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Model capability tags",
            "example": [
              "chat",
              "vision",
              "tool-use"
            ]
          },
          "extra_args": {
            "type": "object",
            "description": "Additional parameters (such as temperature and max_tokens)"
          },
          "prefered_ranking": {
            "type": "integer",
            "description": "Priority ranking (higher values take precedence)",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Test an LLM model

Source: https://langbot.app/docs/en/api-reference/llm-models/test-an-llm-model

## POST /api/v1/provider/models/llm/{model_uuid}/test

Send a test request to the specified LLM model to verify that it is available.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}/test": {
      "post": {
        "tags": [
          "LLM Models"
        ],
        "summary": "Test an LLM model",
        "description": "Send a test request to the specified LLM model to verify that it is available.",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "Prompt text to use for the test",
                    "example": "Hello"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Update an LLM model

Source: https://langbot.app/docs/en/api-reference/llm-models/update-an-llm-model

## PUT /api/v1/provider/models/llm/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}": {
      "put": {
        "tags": [
          "LLM Models"
        ],
        "summary": "Update an LLM model",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LLMModelUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModelUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Create a model provider

Source: https://langbot.app/docs/en/api-reference/model-providers/create-a-model-provider

## POST /api/v1/provider/providers

Create a new model provider.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers": {
      "post": {
        "tags": [
          "Model Providers"
        ],
        "summary": "Create a model provider",
        "description": "Create a new model provider.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelProviderCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProviderCreate": {
        "type": "object",
        "required": [
          "name",
          "requester",
          "base_url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "OpenAI"
          },
          "requester": {
            "type": "string",
            "description": "Requester type. Use GET /api/v1/provider/requesters to list available requesters.",
            "example": "openai-chat-completions"
          },
          "base_url": {
            "type": "string",
            "example": "https://api.openai.com/v1"
          },
          "api_keys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "sk-xxx"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Delete a model provider

Source: https://langbot.app/docs/en/api-reference/model-providers/delete-a-model-provider

## DELETE /api/v1/provider/providers/{provider_uuid}

Delete a model provider. A provider cannot be deleted while it is still referenced by a model.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers/{provider_uuid}": {
      "delete": {
        "tags": [
          "Model Providers"
        ],
        "summary": "Delete a model provider",
        "description": "Delete a model provider. A provider cannot be deleted while it is still referenced by a model.",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "description": "The provider is still referenced by one or more models and cannot be deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get a model provider

Source: https://langbot.app/docs/en/api-reference/model-providers/get-a-model-provider

## GET /api/v1/provider/providers/{provider_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers/{provider_uuid}": {
      "get": {
        "tags": [
          "Model Providers"
        ],
        "summary": "Get a model provider",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "provider": {
                          "$ref": "#/components/schemas/ModelProvider"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProvider": {
        "type": "object",
        "description": "Model provider. Defines the API endpoint and keys; models are associated through provider_uuid.",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "OpenAI"
          },
          "requester": {
            "type": "string",
            "description": "Requester type",
            "example": "openai-chat-completions"
          },
          "base_url": {
            "type": "string",
            "description": "API base URL",
            "example": "https://api.openai.com/v1"
          },
          "api_keys": {
            "type": "array",
            "description": "List of API keys",
            "items": {
              "type": "string"
            }
          },
          "llm_count": {
            "type": "integer",
            "description": "Number of associated LLM models"
          },
          "embedding_count": {
            "type": "integer",
            "description": "Number of associated embedding models"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List all model providers

Source: https://langbot.app/docs/en/api-reference/model-providers/list-all-model-providers

## GET /api/v1/provider/providers

List all model providers, including the number of LLM and embedding models associated with each provider.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers": {
      "get": {
        "tags": [
          "Model Providers"
        ],
        "summary": "List all model providers",
        "description": "List all model providers, including the number of LLM and embedding models associated with each provider.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "providers": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ModelProvider"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProvider": {
        "type": "object",
        "description": "Model provider. Defines the API endpoint and keys; models are associated through provider_uuid.",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "OpenAI"
          },
          "requester": {
            "type": "string",
            "description": "Requester type",
            "example": "openai-chat-completions"
          },
          "base_url": {
            "type": "string",
            "description": "API base URL",
            "example": "https://api.openai.com/v1"
          },
          "api_keys": {
            "type": "array",
            "description": "List of API keys",
            "items": {
              "type": "string"
            }
          },
          "llm_count": {
            "type": "integer",
            "description": "Number of associated LLM models"
          },
          "embedding_count": {
            "type": "integer",
            "description": "Number of associated embedding models"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Update a model provider

Source: https://langbot.app/docs/en/api-reference/model-providers/update-a-model-provider

## PUT /api/v1/provider/providers/{provider_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers/{provider_uuid}": {
      "put": {
        "tags": [
          "Model Providers"
        ],
        "summary": "Update a model provider",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelProviderUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProviderUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "requester": {
            "type": "string"
          },
          "base_url": {
            "type": "string"
          },
          "api_keys": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List available parsers

Source: https://langbot.app/docs/en/api-reference/parsers/list-available-parsers

## GET /api/v1/knowledge/parsers

List all plugin-provided file parsers. Use mime_type to filter the results.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/parsers": {
      "get": {
        "tags": [
          "Parsers"
        ],
        "summary": "List available parsers",
        "description": "List all plugin-provided file parsers. Use mime_type to filter the results.",
        "parameters": [
          {
            "name": "mime_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter parsers by MIME type"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "parsers": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Copy a pipeline

Source: https://langbot.app/docs/en/api-reference/pipelines/copy-a-pipeline

## POST /api/v1/pipelines/{pipeline_uuid}/copy

Copy an existing pipeline to create a new one.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}/copy": {
      "post": {
        "tags": [
          "Pipelines"
        ],
        "summary": "Copy a pipeline",
        "description": "Copy an existing pipeline to create a new one.",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Copied successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Create a pipeline

Source: https://langbot.app/docs/en/api-reference/pipelines/create-a-pipeline

## POST /api/v1/pipelines



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines": {
      "post": {
        "tags": [
          "Pipelines"
        ],
        "summary": "Create a pipeline",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PipelineCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PipelineCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Delete a pipeline

Source: https://langbot.app/docs/en/api-reference/pipelines/delete-a-pipeline

## DELETE /api/v1/pipelines/{pipeline_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}": {
      "delete": {
        "tags": [
          "Pipelines"
        ],
        "summary": "Delete a pipeline",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get a pipeline

Source: https://langbot.app/docs/en/api-reference/pipelines/get-a-pipeline

## GET /api/v1/pipelines/{pipeline_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}": {
      "get": {
        "tags": [
          "Pipelines"
        ],
        "summary": "Get a pipeline",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "pipeline": {
                          "$ref": "#/components/schemas/Pipeline"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pipeline": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get pipeline extension configuration

Source: https://langbot.app/docs/en/api-reference/pipelines/get-pipeline-extension-configuration

## GET /api/v1/pipelines/{pipeline_uuid}/extensions

Get the plugins and MCP server configuration associated with a pipeline.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}/extensions": {
      "get": {
        "tags": [
          "Pipelines"
        ],
        "summary": "Get pipeline extension configuration",
        "description": "Get the plugins and MCP server configuration associated with a pipeline.",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "enable_all_plugins": {
                          "type": "boolean"
                        },
                        "enable_all_mcp_servers": {
                          "type": "boolean"
                        },
                        "bound_plugins": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "available_plugins": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "bound_mcp_servers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "available_mcp_servers": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get pipeline metadata

Source: https://langbot.app/docs/en/api-reference/pipelines/get-pipeline-metadata

## GET /api/v1/pipelines/_/metadata

Get metadata describing the pipeline configuration, including configurable fields and their types.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/_/metadata": {
      "get": {
        "tags": [
          "Pipelines"
        ],
        "summary": "Get pipeline metadata",
        "description": "Get metadata describing the pipeline configuration, including configurable fields and their types.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "configs": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List all pipelines

Source: https://langbot.app/docs/en/api-reference/pipelines/list-all-pipelines

## GET /api/v1/pipelines



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines": {
      "get": {
        "tags": [
          "Pipelines"
        ],
        "summary": "List all pipelines",
        "parameters": [
          {
            "name": "sort_by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "created_at"
            }
          },
          {
            "name": "sort_order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ],
              "default": "DESC"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "pipelines": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Pipeline"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pipeline": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Update a pipeline

Source: https://langbot.app/docs/en/api-reference/pipelines/update-a-pipeline

## PUT /api/v1/pipelines/{pipeline_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}": {
      "put": {
        "tags": [
          "Pipelines"
        ],
        "summary": "Update a pipeline",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PipelineUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PipelineUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "is_default": {
            "type": "boolean"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Update pipeline extension configuration

Source: https://langbot.app/docs/en/api-reference/pipelines/update-pipeline-extension-configuration

## PUT /api/v1/pipelines/{pipeline_uuid}/extensions

Update the plugins and MCP servers associated with a pipeline.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}/extensions": {
      "put": {
        "tags": [
          "Pipelines"
        ],
        "summary": "Update pipeline extension configuration",
        "description": "Update the plugins and MCP servers associated with a pipeline.",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enable_all_plugins": {
                    "type": "boolean",
                    "default": true
                  },
                  "enable_all_mcp_servers": {
                    "type": "boolean",
                    "default": true
                  },
                  "bound_plugins": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "bound_mcp_servers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Delete a plugin

Source: https://langbot.app/docs/en/api-reference/plugins/delete-a-plugin

## DELETE /api/v1/plugins/{author}/{plugin_name}

Delete a plugin asynchronously and return the task ID.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}": {
      "delete": {
        "tags": [
          "Plugins"
        ],
        "summary": "Delete a plugin",
        "description": "Delete a plugin asynchronously and return the task ID.",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "delete_data",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Whether to delete the plugin data as well"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get plugin configuration

Source: https://langbot.app/docs/en/api-reference/plugins/get-plugin-configuration

## GET /api/v1/plugins/{author}/{plugin_name}/config

Get the plugin's current configuration values and configuration schema.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}/config": {
      "get": {
        "tags": [
          "Plugins"
        ],
        "summary": "Get plugin configuration",
        "description": "Get the plugin's current configuration values and configuration schema.",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get plugin details

Source: https://langbot.app/docs/en/api-reference/plugins/get-plugin-details

## GET /api/v1/plugins/{author}/{plugin_name}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}": {
      "get": {
        "tags": [
          "Plugins"
        ],
        "summary": "Get plugin details",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "plugin": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Install a plugin from GitHub

Source: https://langbot.app/docs/en/api-reference/plugins/install-a-plugin-from-github

## POST /api/v1/plugins/install/github

Install a plugin from a GitHub repository asynchronously and return the task ID.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/install/github": {
      "post": {
        "tags": [
          "Plugins"
        ],
        "summary": "Install a plugin from GitHub",
        "description": "Install a plugin from a GitHub repository asynchronously and return the task ID.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "GitHub repository URL",
                    "example": "https://github.com/rocksclawbot/langbot-community-plugins/tree/main/disaster-alert"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Install a plugin from Marketplace

Source: https://langbot.app/docs/en/api-reference/plugins/install-a-plugin-from-marketplace

## POST /api/v1/plugins/install/marketplace

Install a plugin from LangBot Marketplace asynchronously and return the task ID.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/install/marketplace": {
      "post": {
        "tags": [
          "Plugins"
        ],
        "summary": "Install a plugin from Marketplace",
        "description": "Install a plugin from LangBot Marketplace asynchronously and return the task ID.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plugin_id"
                ],
                "properties": {
                  "plugin_id": {
                    "type": "string",
                    "description": "Marketplace plugin ID (author/name format)",
                    "example": "kellz-dev/disaster-alert"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List installed plugins

Source: https://langbot.app/docs/en/api-reference/plugins/list-installed-plugins

## GET /api/v1/plugins



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins": {
      "get": {
        "tags": [
          "Plugins"
        ],
        "summary": "List installed plugins",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "plugins": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Update plugin configuration

Source: https://langbot.app/docs/en/api-reference/plugins/update-plugin-configuration

## PUT /api/v1/plugins/{author}/{plugin_name}/config



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}/config": {
      "put": {
        "tags": [
          "Plugins"
        ],
        "summary": "Update plugin configuration",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Plugin configuration key-value pairs"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "Operation completed successfully",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Upgrade a plugin

Source: https://langbot.app/docs/en/api-reference/plugins/upgrade-a-plugin

## POST /api/v1/plugins/{author}/{plugin_name}/upgrade

Upgrade a plugin to the latest version asynchronously and return the task ID.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}/upgrade": {
      "post": {
        "tags": [
          "Plugins"
        ],
        "summary": "Upgrade a plugin",
        "description": "Upgrade a plugin to the latest version asynchronously and return the task ID.",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# Get system information

Source: https://langbot.app/docs/en/api-reference/system/get-system-information

## GET /api/v1/system/info

Get basic information about the LangBot instance, including its version and release type. This endpoint does not require authentication.

No authentication required.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/system/info": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Get system information",
        "description": "Get basic information about the LangBot instance, including its version and release type. This endpoint does not require authentication.",
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string",
                          "example": "v4.9.5"
                        },
                        "debug": {
                          "type": "boolean"
                        },
                        "edition": {
                          "type": "string",
                          "example": "community"
                        },
                        "enable_marketplace": {
                          "type": "boolean"
                        },
                        "cloud_service_url": {
                          "type": "string"
                        },
                        "allow_modify_login_info": {
                          "type": "boolean"
                        },
                        "disable_models_service": {
                          "type": "boolean"
                        },
                        "limitation": {
                          "type": "object"
                        },
                        "wizard_status": {
                          "type": "string",
                          "enum": [
                            "none",
                            "skipped",
                            "completed"
                          ]
                        },
                        "wizard_progress": {
                          "type": "object",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {}
}
```

---

# Get tool detail

Source: https://langbot.app/docs/en/api-reference/tools/get-tool-detail

## GET /api/v1/tools/{tool_name}

Get detailed information about a specific tool.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/tools/{tool_name}": {
      "get": {
        "tags": [
          "Tools"
        ],
        "summary": "Get tool detail",
        "description": "Get detailed information about a specific tool.",
        "operationId": "getToolDetail",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tool_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Tool name"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "msg": {
                      "type": "string",
                      "example": "ok"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "tool": {
                          "$ref": "#/components/schemas/ToolSummary"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tool not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ToolSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Tool name"
          },
          "label": {
            "type": "object",
            "description": "Display label (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "object",
            "description": "Tool description (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "icon": {
            "type": "string",
            "description": "Tool icon"
          },
          "spec": {
            "type": "object",
            "description": "Tool specification",
            "properties": {
              "llm_prompt": {
                "type": "string"
              },
              "parameters": {
                "type": "object",
                "description": "JSON Schema for tool parameters"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# List all available tools

Source: https://langbot.app/docs/en/api-reference/tools/list-all-available-tools

## GET /api/v1/tools

List all available tools in the current LangBot instance, including plugin tools and MCP tools.

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete en OpenAPI specification](https://langbot.app/docs/openapi/service-api-en.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/tools": {
      "get": {
        "tags": [
          "Tools"
        ],
        "summary": "List all available tools",
        "description": "List all available tools in the current LangBot instance, including plugin tools and MCP tools.",
        "operationId": "listTools",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "msg": {
                      "type": "string",
                      "example": "ok"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "tools": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ToolSummary"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ToolSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Tool name"
          },
          "label": {
            "type": "object",
            "description": "Display label (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "object",
            "description": "Tool description (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "icon": {
            "type": "string",
            "description": "Tool icon"
          },
          "spec": {
            "type": "object",
            "description": "Tool specification",
            "properties": {
              "llm_prompt": {
                "type": "string"
              },
              "parameters": {
                "type": "object",
                "description": "JSON Schema for tool parameters"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# LangBot Articles

Source: https://langbot.app/docs/en/articles

Product updates, engineering deep dives, tutorials, integrations, and announcements from the LangBot Blog.

Product updates, engineering deep dives, tutorials, integrations, and announcements from the LangBot Blog.

## Product Updates

- [The new LangBot Cloud is here — and multi-user Workspaces are now in open source](https://langbot.app/docs/en/articles/langbot-cloud-multi-user-workspaces.md) — 2026-08-25

## Engineering

- [LangBot v4.10.0: Agentic Sandbox & Skills — Letting Your Agent Work Like a Developer](https://langbot.app/docs/en/articles/langbot-v4100-sandbox-skills.md) — 2026-06-04
- [LangBot v4.9.0: Full RAG Plugin Architecture — Knowledge Without Borders](https://langbot.app/docs/en/articles/langbot-v490-rag-plugin-architecture.md) — 2026-03-10
- [Deep Dive into the LangBot Plugin System: Process Isolation, Event-Driven Hooks, and Component Architecture](https://langbot.app/docs/en/articles/langbot-plugin-system-deep-dive.md) — 2026-02-23

## Tutorials & Integrations

- [LangTARS: Open-Source AI Agent for Remote PC Control — Works with Dify, n8n & 10+ Messaging Platforms](https://langbot.app/docs/en/articles/langtars-remote-pc-control-dify-n8n.md) — 2026-03-23
- [How to Connect DeepSeek R1 to WeChat, Discord & Telegram in 5 Minutes (FREE)](https://langbot.app/docs/en/articles/connect-deepseek-to-wechat.md) — 2026-02-21
- [Deploy Your Own AI Bot to Discord, Telegram & WeChat in 5 Minutes](https://langbot.app/docs/en/articles/deploy-ai-bot-in-5-minutes.md) — 2026-02-17
- [Finally Got My Dify Agent Working in Discord, Telegram and Slack](https://langbot.app/docs/en/articles/dify-agent-discord-telegram-slack.md) — 2025-12-11
- [How I Built a Multi-Platform AI Bot with Langflow's Drag-and-Drop Workflows](https://langbot.app/docs/en/articles/langflow-drag-and-drop-ai-bot.md) — 2025-12-05
- [How I Built a Multi-Platform AI Chatbot with n8n and LangBot](https://langbot.app/docs/en/articles/n8n-multi-platform-ai-chatbot.md) — 2025-12-03
- [LangBot 4.6.0 External Knowledge Base Tutorial: Integrating Dify with LangBot for RAG-powered Conversations](https://langbot.app/docs/en/articles/dify-langbot-rag-knowledge-base.md) — 2025-12-02

## Announcements

- [Introducing the LangBot Blog](https://langbot.app/docs/en/articles/welcome.md) — 2026-02-17

---

# How to Connect DeepSeek R1 to WeChat, Discord & Telegram in 5 Minutes (FREE)

Source: https://langbot.app/docs/en/articles/connect-deepseek-to-wechat

A step-by-step guide to connecting DeepSeek R1/V3 API to WeChat (Personal/Enterprise), Discord, Telegram, and more using LangBot. No coding required.

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/connect-deepseek-to-wechat).

Published 2026-02-21 · Author: LangBot Team

![DeepSeek x WeChat Integration](https://langbot.app/docs/images/articles/source/images/covers/deepseek-wechat.png)

DeepSeek has taken the AI world by storm. Its R1 reasoning model rivals OpenAI's o1 but is open-source and significantly cheaper.

However, the official DeepSeek app currently only supports "AI Search" in WeChat, and direct integration into group chats or private workflows is limited.

**What if you could have a fully functional DeepSeek R1 bot in your WeChat groups, Discord servers, and Telegram chats right now?**

With **LangBot**, you can. And it takes less than 5 minutes.

## Why LangBot?

LangBot is an open-source, production-grade IM bot platform. Unlike simple scripts or single-platform bots, LangBot gives you:

- **Unified Platform:** Connect once, deploy to WeChat, Discord, Telegram, Slack, Lark, and more.
- **Model Agnostic:** Use DeepSeek R1, V3, Claude 3.5, GPT-4, or local Ollama models.
- **No Coding:** robust WebUI for configuration.
- **Enterprise Features:** Knowledge base (RAG), Plugin system, and multi-user management.

## Prerequisites

1. **A Server or PC:** Docker installed (VPS, local computer, or Synology/NAS).
2. **DeepSeek API Key:**
   - **Official:** [platform.deepseek.com](https://platform.deepseek.com)
   - **SiliconFlow (Recommended for speed):** [cloud.siliconflow.cn](https://cloud.siliconflow.cn) (Faster R1 inference).

## Step 1: Deploy LangBot

If you haven't deployed LangBot yet, run this one command:

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose up -d
```

Access your dashboard at `http://localhost:5300` (or your server IP).

## Step 2: Configure DeepSeek Model

1. Go to **Models** -> **Provider List**.
2. Find **DeepSeek** (or **SiliconFlow** / **OpenAI Compatible**).
3. Enter your API Key.
4. Click **Save**.

Now create a **Model Instance**:

- **Name:** `DeepSeek-R1-Bot`
- **Model:** `deepseek-reasoner` (for R1) or `deepseek-chat` (for V3).

## Step 3: Create a Chat Pipeline

LangBot uses "Pipelines" to manage bot logic.

1. Go to **Pipelines** -> **New Pipeline**.
2. Choose **Chat Pipeline**.
3. Select your `DeepSeek-R1-Bot` model.
4. (Optional) Add a System Prompt:
   > "You are a helpful assistant powered by DeepSeek R1. You think deeply before answering."

## Step 4: Connect to WeChat (or any platform)

### For WeChat (Personal / Wechaty)

*Note: Personal WeChat access relies on third-party libraries and carries some risk. For business use, we recommend Enterprise WeChat (WeCom).*

1. Go to **Bots** -> **New Bot**.
2. Select **WeChat**.
3. Choose the **GeweChat** or **Wechaty** adapter (depending on your preference).
4. Click **Save**.
5. Scan the QR code that appears in the logs or UI.

### For Discord / Telegram

1. Select **Discord** or **Telegram**.
2. Paste your **Bot Token** (from Discord Developer Portal or BotFather).
3. Click **Save**.

## Step 5: Test It Out!

Open your chat app and send a message. You should see DeepSeek R1 "thinking" (if supported) and replying with high-quality reasoning.

## Advanced: Using Search & Tools

DeepSeek is great, but DeepSeek with **Internet Access** is better.

In LangBot:

1. Go to **Plugins**.
2. Install **Tavily Search** or **Google Search**.
3. Add the plugin to your DeepSeek Pipeline.

Now your bot can search the web for real-time info *before* reasoning with DeepSeek R1!

***

**Ready to build?**
[Star us on GitHub](https://github.com/langbot-app/LangBot) or [Read the Docs](https://langbot.app/docs/en/insight/guide.md).

---

# Deploy Your Own AI Bot to Discord, Telegram & WeChat in 5 Minutes

Source: https://langbot.app/docs/en/articles/deploy-ai-bot-in-5-minutes

A step-by-step guide to deploying LangBot — the open-source platform that connects 20+ LLMs to 13+ messaging platforms with a single Docker command.

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/deploy-ai-bot-in-5-minutes).

Published 2026-02-17 · Author: LangBot Team

![LangBot Dashboard](https://langbot.app/docs/images/articles/source/images/covers/deploy-ai-bot.png)

What if you could have GPT-5, Claude, DeepSeek, and Gemini all answering questions in your Discord server, Telegram group, and WeChat — at the same time?

No API wrangling. No weeks of development. Just one Docker command.

That's **LangBot** — and it just crossed **15,000 stars** on GitHub.

## The Problem Everyone Faces

You want an AI assistant in your team's chat. Maybe for customer support on Telegram. Maybe for a coding helper in Discord. Maybe for a knowledge base bot in your company's WeChat or Lark group.

But then reality hits:

- Each platform has its own bot API, webhook format, and auth flow
- You need to handle message queuing, session management, and error recovery
- Switching LLM providers means rewriting your integration layer
- Adding RAG or tool calling is yet another project

LangBot solves all of this with a single, unified platform.

## What Makes LangBot Different

### 13+ Messaging Platforms, One Codebase

Deploy a single LangBot instance and connect it to:

**Global:** Discord, Telegram, Slack, LINE, WhatsApp
**Asia:** WeChat (Official Account), WeCom, QQ, Lark, DingTalk, Feishu, KOOK

Each platform gets its own adapter — you just fill in your bot token in the WebUI and you're live.

![LangBot Bot Management Page](https://langbot.app/docs/images/articles/source/images/article-mcp/13-bot-page.png)

### 20+ LLM Models, Zero Lock-in

Through **LangBot Space**, you get instant access to 20 cloud models out of the box — no API keys to manage:

- **Claude** (Opus 4.6, Sonnet 4.5, Haiku 4.5)
- **GPT** (GPT-5.2, GPT-5-mini, GPT-4.1-mini)
- **Gemini** (3 Pro, 2.5 Pro, 2.5 Flash)
- **DeepSeek** (R1, V3)
- **Grok** (4, 4.1)
- **Qwen** (3 Max)

Or add your own providers — OpenAI-compatible endpoints, Ollama for local models, any provider you want.

![Model Selection](https://langbot.app/docs/images/articles/source/images/article-mcp/08-model-select.png)

### Built-in Agent with Tool Calling

LangBot's Local Agent isn't just a chat wrapper — it's a full agent runtime:

- **Multi-round conversations** with configurable memory
- **Function calling / tool use** for LLM-driven actions
- **MCP (Model Context Protocol)** support for connecting to 100+ pre-built tools
- **Knowledge base (RAG)** with built-in vector search

![Pipeline AI Configuration](https://langbot.app/docs/images/articles/source/images/article-mcp/06-pipeline-ai.png)

### Plugin Marketplace

37+ community plugins and growing — install with one click:

- **WebSearch** — Let your bot search the web
- **AI Image Generator** — Generate images from text
- **LinkAnaly** — Auto-preview links in chat
- **ScheNotify** — Schedule reminders with natural language
- **Google Search**, **Tavily Search**, **RAGFlow Retriever**, and more

![LangBot Space Plugin Market](https://langbot.app/docs/images/articles/source/images/article-mcp/14-space-market.png)

## Deploy in 5 Minutes — For Real

### Step 1: Run Docker Compose

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose up -d
```

That's it. LangBot is now running at `http://localhost:5300`.

### Step 2: Initialize with LangBot Space

Open the WebUI and click **"Initialize with Space"**. This connects your instance to LangBot Space, giving you:

- 20 cloud models ready to use (with free credits)
- One-click plugin installation
- Managed API keys

![Initialize with Space](https://langbot.app/docs/images/articles/source/images/article-mcp/01-init-page.png)

### Step 3: Configure Your Pipeline

Go to **Pipelines** and edit the default `ChatPipeline`:

1. Select your model (e.g., `deepseek-v3`, `gpt-5-mini`, `claude-sonnet-4-5`)
2. Customize the system prompt
3. Optionally attach a knowledge base or enable tools

![Pipelines Page](https://langbot.app/docs/images/articles/source/images/article-mcp/05-pipelines.png)

### Step 4: Connect a Platform

Go to **Bots** → click **+** → choose your platform (Discord, Telegram, etc.) → enter your bot token.

Done. Your bot is live.

### Step 5: Test It

Use the built-in **Debug Chat** to test your pipeline before going live:

![Debug Chat](https://langbot.app/docs/images/articles/source/images/article-mcp/07-debug-chat.png)

## Real Conversations, Real Value

Here's what it looks like when LangBot is running in a QQ group — users asking technical questions and getting instant, accurate answers:

![Group Chat Demo](https://langbot.app/docs/images/articles/source/images/article-mcp/10-group-chat.png)

And in private chat:

![Private Chat Demo](https://langbot.app/docs/images/articles/source/images/article-mcp/11-private-chat.png)

## Architecture That Scales

LangBot is built for production:

- **Pipeline architecture** — each bot binds to a pipeline; pipelines handle AI logic, triggers, safety controls, and output formatting
- **Cross-process plugin isolation** — a bad plugin can't crash your bot
- **Multiple runner backends** — use LangBot's Local Agent, or connect to Dify, n8n, Langflow, Coze for complex workflows
- **Database flexibility** — SQLite for dev, PostgreSQL for production
- **Vector DB options** — Chroma, Qdrant, Milvus, pgvector, SeekDB

## Why 15,000+ Developers Choose LangBot

| Feature       | LangBot             | Building from Scratch |
| ------------- | ------------------- | --------------------- |
| Platforms     | 13+ ready           | Weeks per platform    |
| LLM Providers | 20+ models          | Manual integration    |
| Agent Runtime | Built-in            | Build your own        |
| RAG           | Native + external   | Separate project      |
| Plugin System | Marketplace         | DIY                   |
| Deployment    | `docker compose up` | Days of setup         |
| WebUI         | Included            | Build your own        |

## Get Started

- **GitHub:** [github.com/langbot-app/LangBot](https://github.com/langbot-app/LangBot) — give us a star!
- **Documentation:** [langbot.app/docs](https://langbot.app/docs/en/insight/guide.md)
- **Plugin Market:** [space.langbot.app](https://space.langbot.app)

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose up -d
```

Your AI bot empire starts with one command.

---

# Finally Got My Dify Agent Working in Discord, Telegram and Slack

Source: https://langbot.app/docs/en/articles/dify-agent-discord-telegram-slack

Finally Got My Dify Agent Working in Discord, Telegram and Slack

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/dify-agent-discord-telegram-slack).

Published 2025-12-11 · Author: LangBot Team

![Finally Got My Dify Agent Working in Discord, Telegram and Slack](https://langbot.app/docs/images/articles/source/images/covers/dify-agent.png)

Want your Dify Agent to break free from the browser and chat directly in WeChat, QQ, or Telegram? Combine LangBot with Dify and you can set it up in under 10 minutes.

## Why This Combo?

[**LangBot**](https://github.com/langbot-app/LangBot) is the most powerful open-source multi-platform chatbot framework available. It supports major Chinese IMs (QQ, WeChat, Feishu, DingTalk) and international platforms (Telegram, Discord, Slack, LINE). Its core strength is connecting AI backends to messaging apps.

**Dify** is one of the hottest AI app development platforms, offering visual Agent orchestration, 50+ built-in tools, and RAG knowledge bases. Together, they let you build a multi-platform AI assistant fast.

## Deploy LangBot

Three commands with uvx:

```bash
mkdir langbot-instance
cd langbot-instance
uvx langbot@latest
```

Visit `http://127.0.0.1:5300` and register an admin account:

![LangBot Dashboard](https://langbot.app/docs/images/articles/external/c6d52212ba91-02-langbot-dashboard.png)

## Create a Dify Agent

Log in to [cloud.dify.ai](https://cloud.dify.ai) and create a new app. Choose **Agent** type - unlike basic chat apps, Agents can reason autonomously and call tools for complex tasks.

![Select Agent Type](https://langbot.app/docs/images/articles/external/3e5b1d8ec6ec-07-dify-create-app-types.png)

### Configure the Agent

In the orchestration interface, set up:

**System Instructions** - Define the Agent's role:

```
You are an intelligent assistant that helps users complete various tasks. You have the following capabilities:
1. Answer various user questions
2. Query weather information
3. Retrieve webpage content

Please always maintain a friendly and professional attitude. If you need to use tools to get information, proactively call the relevant tools.
```

**Add Tools** - Pick from Dify's 50+ built-in tools, like Weather and Web Scraper:

![Add Tools](https://langbot.app/docs/images/articles/external/9066d99b172c-11-dify-tools-panel.png)

**Select Model** - Supports GPT, Claude, Gemini, DeepSeek, and other major LLMs.

Final configuration:

![Configuration Complete](https://langbot.app/docs/images/articles/external/be278ca435e8-12-dify-agent-configured.png)

### Get the API Key

Click "Publish", then go to "Access API" to create a key:

![Create API Key](https://langbot.app/docs/images/articles/external/471b316018e5-13-dify-api-key-created.png)

Save the API key and server address `https://api.dify.ai/v1`.

## Connect Dify to LangBot

Back in LangBot, go to Pipelines > ChatPipeline > AI Capability:

![AI Capability Config](https://langbot.app/docs/images/articles/external/8f4b3820ed5b-14-langbot-pipeline-ai-capability.png)

Select **Dify Service API** as the Runner:

![Select Dify Runner](https://langbot.app/docs/images/articles/external/efa6fcae9c58-15-langbot-runner-dropdown.png)

Enter the configuration:

- **Base URL**: `https://api.dify.ai/v1`
- **API Key**: The key you just created
- **App Type**: Chat (including Chatflow)

![Enter Configuration](https://langbot.app/docs/images/articles/external/74f71a8bf1dc-17-langbot-dify-api-key-entered.png)

Save and click "Debug Conversation" to test:

![Test Conversation](https://langbot.app/docs/images/articles/external/9999c12907eb-20-langbot-chat-test.png)

If the Agent responds correctly and calls tools, the integration is working.

## Why This Architecture Rocks

- **Decoupled Design**: Agent capabilities live in Dify, LangBot handles message routing - each does what it's best at
- **One Config, Multi-Platform**: Same Agent serves QQ, WeChat, Telegram, and more simultaneously
- **Easy to Extend**: Add RAG knowledge bases, Workflow orchestration, or more tools in Dify later

## Next Steps

- Configure messaging platforms in LangBot (QQ bot, WeChat personal account, etc.)
- Add more tools in Dify (database queries, API calls)
- Try Dify Chatflow for complex conversation flows

If you're using n8n, FastGPT, Coze, or Langflow, LangBot supports those too.

***

**Resources**

- [LangBot Docs](https://langbot.app/docs/en/insight/guide.md) | [GitHub](https://github.com/langbot-app/LangBot)
- [Dify Docs](https://docs.dify.ai) | [Cloud Platform](https://cloud.dify.ai)

---

# LangBot 4.6.0 External Knowledge Base Tutorial: Integrating Dify with LangBot for RAG-powered Conversations

Source: https://langbot.app/docs/en/articles/dify-langbot-rag-knowledge-base

LangBot 4.6.0 External Knowledge Base Tutorial: Integrating Dify with LangBot for RAG-powered Conversations

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/dify-langbot-rag-knowledge-base).

Published 2025-12-02 · Author: LangBot Team

![LangBot 4.6.0 External Knowledge Base Tutorial: Integrating Dify with LangBot for RAG-powered Conversations](https://langbot.app/docs/images/articles/source/images/covers/dify-rag.png)

LangBot 4.6.0 introduces external knowledge base functionality, allowing users to integrate external knowledge retrieval services such as Dify and RAGFlow into conversation pipelines. This tutorial demonstrates how to combine Dify knowledge base with LangBot to enable intelligent conversations based on domain-specific knowledge.

## Feature Overview

The external knowledge base feature enables LangBot to:

- Connect to various external knowledge retrieval services (Dify, RAGFlow, etc.)
- Provide professional answers based on domain-specific knowledge
- Flexibly extend knowledge retrieval capabilities through the plugin system
- Configure conveniently through WebUI without manual configuration file editing

## Prerequisites

Before starting, you need:

1. Deploy LangBot 4.6.0 or higher
2. Have a Dify account (register at <https://cloud.dify.ai>)
3. Configure a conversation model (this tutorial uses claude-opus-4-1-20250805)

## Step 1: Deploy LangBot

### 1.1 View LangBot Repository

First, visit the [LangBot GitHub repository](https://github.com/langbot-app/LangBot) to understand the project. LangBot is a production-grade instant messaging bot development platform supporting multiple messaging platforms and LLM services.

### 1.2 Learn About External Knowledge Base Feature

Visit the [official LangBot documentation](https://langbot.app/docs/en/insight/guide.md) to view the external knowledge base usage instructions. The documentation provides detailed explanations on how to build built-in knowledge bases and connect to external knowledge bases.

### 1.3 Start LangBot

Use the `uvx langbot` command to quickly start LangBot, then visit <http://127.0.0.1:5300> for initialization. Fill in your email and password to complete registration, then log in.

### 1.4 Dashboard After Login

After successfully logging in, you will see the LangBot WebUI dashboard.

## Step 2: Configure Conversation Model

Before using the knowledge base, you need to configure a conversation model.

### 2.1 Navigate to Model Configuration Page

Click "Models" in the left navigation bar to enter the model configuration page.

### 2.2 Add New Model

Click the "+" button to open the model configuration dialog.

### 2.3 Fill in Model Information

Fill in the following information:

- **Model Name**: claude-opus-4-1-20250805
- **Model Provider**: New API
- **Request URL**: Your API endpoint
- **API Key**: Your API Key
- **Abilities**: Check Vision Ability and Function Call

Click "Submit" to save the configuration.

## Step 3: Create Knowledge Base in Dify

### 3.1 Log in to Dify Platform

Visit <https://cloud.dify.ai> and log in to your account.

### 3.2 Navigate to Knowledge Page

Click "Knowledge" in the top navigation bar to enter the knowledge base management page.

### 3.3 Create New Knowledge Base

Click "Create Knowledge" to start creating a knowledge base.

### 3.4 Select Data Source

You can choose from the following methods to import data:

- **Import from file**: Upload document files
- **Sync from Notion**: Sync from Notion
- **Sync from website**: Crawl website content

This tutorial selects "Import from file" and uploads prepared LangBot documentation.

### 3.5 Upload Document

After uploading the document, the system will display file information. Click "Next" to proceed.

### 3.6 Configure Document Processing Parameters

On the document processing page, you can configure chunk settings, index method, and retrieval settings:

- **Chunk Settings**: General mode, maximum chunk length 1024 characters
- **Index Method**: High Quality (uses embedding model)
- **Retrieval Setting**: Vector Search

Click "Save & Process" to start processing the document.

### 3.7 Knowledge Base Processing

The system starts processing the document and generating vector embeddings.

### 3.8 Embedding Completed

After processing is complete, the knowledge base is ready to use.

## Step 4: Get Dify API Information

### 4.1 Open Service API Panel

Click the "Service API" button in the bottom right. Record the following information:

- **Service API Endpoint**: <https://api.dify.ai/v1>
- **Dataset ID**: Get from the URL

### 4.2 Get API Key

Click the "API Key" button to view the API key. Record your API Key for use in subsequent configuration.

## Step 5: Configure External Knowledge Base in LangBot

### 5.1 Navigate to Knowledge Page

In the LangBot WebUI, click "Knowledge" in the left navigation bar.

### 5.2 Switch to External Knowledge Base Tab

Click the "External" tab.

### 5.3 Add External Knowledge Base

Click the "+" button to open the add external knowledge base dialog. In this dialog, you need to:

1. **Knowledge Base Name**: Give the knowledge base a name
2. **Knowledge Base Description**: Add a description (optional)
3. **Retriever**: Select a knowledge retriever plugin

**Note**: Using an external knowledge base requires installing the corresponding knowledge retriever plugin first. You can search for and install the Dify knowledge retriever plugin in the [plugin marketplace](https://space.langbot.app/market?category=KnowledgeRetriever).

After installing the plugin, select the corresponding plugin from the Retriever dropdown, then fill in the configuration information obtained from Dify (API Endpoint, API Key, Dataset ID).

## Step 6: Configure Pipeline

After configuring the external knowledge base, you need to enable it in the pipeline:

1. Navigate to the "Pipelines" page
2. Edit or create a new pipeline
3. On the "AI Capabilities" page, select "Built-in Agent" as the runner
4. In the knowledge base selection, check the external knowledge base you just configured
5. Save the pipeline configuration

## Step 7: Test the Effect

Test in the pipeline's "Conversation Testing" page, or bind the pipeline to a bot for actual conversation testing. When users ask questions, LangBot will automatically retrieve relevant content from the Dify knowledge base and generate answers combined with the retrieved knowledge.

## Frequently Asked Questions

### 1. How to Install Knowledge Retriever Plugins?

Visit the [LangBot plugin marketplace](https://space.langbot.app/market), search for "Knowledge Retriever" or "Dify", find the corresponding plugin and click install.

### 2. Which External Knowledge Retrieval Services Are Supported?

LangBot currently supports multiple external knowledge retrieval services through the plugin system, including:

- Dify
- RAGFlow
- Other custom knowledge retrieval services

Specific supported services can be viewed in the plugin marketplace.

### 3. What's the Difference Between External and Built-in Knowledge Bases?

- **Built-in Knowledge Base**: Data is stored locally in LangBot, with LangBot handling vectorization and retrieval
- **External Knowledge Base**: Data is stored in external services (like Dify), with retrieval performed through API calls

The advantage of external knowledge bases is the ability to leverage the capabilities of professional LLMOps platforms, such as Dify's advanced document processing and multiple retrieval strategies.

### 4. Can Multiple Knowledge Bases Be Used Simultaneously?

Yes. In the pipeline configuration, you can check multiple knowledge bases (built-in or external) simultaneously, and LangBot will comprehensively utilize the content from these knowledge bases to generate answers.

## Summary

Through this tutorial, you learned how to:

1. Create a knowledge base and upload documents on the Dify platform
2. Obtain Dify API key and related configuration information
3. Configure a conversation model in LangBot
4. Add an external knowledge base in LangBot
5. Configure pipelines to use external knowledge bases

The external knowledge base feature provides LangBot with more powerful and flexible knowledge management capabilities. Combined with professional LLMOps platforms like Dify, you can build more intelligent and professional conversational bots.

## Related Resources

- [LangBot Official Website](https://langbot.app)
- [LangBot Documentation](https://langbot.app/docs/en/insight/guide.md)
- [LangBot GitHub](https://github.com/langbot-app/LangBot)
- [Dify Official Website](https://dify.ai)
- [LangBot Plugin Marketplace](https://space.langbot.app/market)

---

# The new LangBot Cloud is here — and multi-user Workspaces are now in open source

Source: https://langbot.app/docs/en/articles/langbot-cloud-multi-user-workspaces

LangBot is an open-source AI bot platform connecting LLMs with messaging apps. The new Cloud and open-source editions now support multi-user Workspaces, invitations, and role-based access.

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/langbot-cloud-multi-user-workspaces).

Published 2026-08-25 · Author: LangBot Team

![LangBot multi-user Workspace dashboard](https://langbot.app/docs/images/articles/source/images/cloud-multi-user/oss-dashboard.png)

The new [LangBot Cloud](https://cloud.langbot.app) is live. This release tackles a practical question: when a team uses LangBot together, who can access which resources?

The same multi-user foundation is now available in the open-source edition. Cloud and self-hosted LangBot still have different operating models, but they share the same basic approach to members, invitations, and permissions.

## What is LangBot?

LangBot is an open-source platform for building and operating AI bots across messaging apps. A single dashboard manages bots, message pipelines, knowledge bases, models, and extensions, then connects them to Discord, Telegram, Slack, LINE, QQ, WeChat, WeCom, Lark, DingTalk, and KOOK. LangBot also supports Satori and Matrix; Matrix bridges can extend a deployment to networks such as WhatsApp, Signal, Messenger, Mattermost, Google Chat, IRC, XMPP, and Zulip.

The model layer is provider-neutral. LangBot connects to OpenAI, Anthropic Claude, DeepSeek, Google Gemini, xAI Grok, Moonshot Kimi, and Zhipu GLM, while Ollama and LM Studio cover local models. Gateway options include SiliconFlow, Aliyun Bailian, Volcengine Ark, ModelScope, and GiteeAI. Existing agent workflows can also be connected through Dify and MCP.

A team can therefore run AI assistants on several messaging platforms from one place and choose a hosted model, a local model, or an existing agent workflow for each use case.

![The new LangBot Cloud sign-in page](https://langbot.app/docs/images/articles/source/images/cloud-multi-user/cloud-login.png)

## Cloud: start in your own Workspace

LangBot Cloud now uses LangBot Account for sign-in. New users start with a personal Workspace and can accept invitations to join team Workspaces. If an account belongs to several Workspaces, the current one can be switched from the interface.

Bots, pipelines, models, knowledge bases, and extensions belong to the active Workspace. Switching Workspaces does not mix one team's configuration or data with another's.

Cloud continues to provide the hosting, updates, and runtime environment. It is the simpler option for teams that want to configure a bot without maintaining a server first.

## Invite people instead of sharing an admin account

An Owner, or another role with member-management permission, can send a one-time invitation. The recipient accepts it with their own account and enters the Workspace with the assigned role.

![LangBot Cloud invitation page with the Workspace name anonymized](https://langbot.app/docs/images/articles/source/images/cloud-multi-user/cloud-invitation.png)

That is a better long-term setup than sharing one administrator password: each person has an identity, and access can match the work they actually do.

Five fixed roles are available today:

- **Owner** — owns the Workspace and its highest-level membership controls.
- **Admin** — manages members and most Workspace settings.
- **Developer** — configures bots, pipelines, models, and extensions.
- **Operator** — handles day-to-day operations.
- **Viewer** — read-only access.

## Open source: one instance, one Workspace, multiple users

The self-hosted edition is not turning into a multi-Workspace SaaS. One LangBot instance still has one Workspace, but that Workspace can now include several users.

The account created during initialization becomes the Owner. It can invite other people later. When SMTP is configured, LangBot can deliver the invitation by email; otherwise it shows a one-time link that can be shared through a trusted channel.

Members still use the familiar LangBot dashboard. The difference is that resource access is checked against both the Workspace and the member's role, rather than treating every signed-in user as a full administrator.

## Which edition should you use?

|                         | LangBot Cloud                    | Open-source self-hosted                       |
| ----------------------- | -------------------------------- | --------------------------------------------- |
| Deployment              | Hosted and maintained by LangBot | You operate the server and data               |
| Workspaces              | Own or join multiple             | One per instance                              |
| Members and invitations | Included                         | Included                                      |
| Fixed role-based access | Included                         | Included                                      |
| Best for                | Getting a team running quickly   | Private deployment and infrastructure control |

To start with the hosted edition, visit [cloud.langbot.app](https://cloud.langbot.app). To keep the runtime and data on your own infrastructure, deploy LangBot from [GitHub](https://github.com/langbot-app/LangBot).

---

# Deep Dive into the LangBot Plugin System: Process Isolation, Event-Driven Hooks, and Component Architecture

Source: https://langbot.app/docs/en/articles/langbot-plugin-system-deep-dive

A source-level deep dive into LangBot 4.0's plugin architecture — process-isolated communication, event-driven hooks, a component-based extension model, and comparisons with Dify and MCP.

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/langbot-plugin-system-deep-dive).

Published 2026-02-23 · Author: LangBot Team

![LangBot Plugin System](https://langbot.app/docs/images/articles/source/images/covers/plugin-system.png)

Most chatbot frameworks call their "plugin system" a glorified dynamic import of Python modules. LangBot 4.0 takes a harder but more principled approach — **every plugin runs in its own process**, communicating with the host through a structured JSON-RPC-style protocol.

This article dissects the system from source code, end to end.

## Overall Architecture: A Three-Layer Process Model

LangBot's plugin system consists of three cooperating process layers:

![LangBot Plugin System Architecture](https://langbot.app/docs/images/articles/source/images/plugin-system/architecture.png)

**Each layer has a distinct responsibility:**

1. **LangBot Main Process**: Runs business logic (message pipelines, platform adapters, model invocations), connects to Runtime via `PluginRuntimeConnector`.
2. **Plugin Runtime**: The orchestration layer — discovers, launches, and manages all plugin subprocesses, routes requests from the main process to the appropriate plugin.
3. **Plugin Subprocesses**: Each plugin runs in its own Python process, communicating with Runtime via stdio pipes.

### Why Three Layers Instead of Two?

The intuitive design would have the main process manage plugin processes directly. LangBot adds the Runtime layer for **deployment flexibility**:

- **Local development**: Main process spawns Runtime as a child via stdio (zero config)
- **Docker production**: Runtime runs as a separate container, connected via WebSocket
- **Windows compatibility**: Since Windows asyncio has incomplete stdio subprocess support, it automatically falls back to WebSocket

The same codebase — no config changes — adapts from development to production.

## Communication Protocol: JSON-RPC-Style Request/Response

All cross-process communication runs on a unified protocol layer. The core data structures are minimal:

```python
# Request
class ActionRequest(pydantic.BaseModel):
    seq_id: int    # Sequence number for matching request/response
    action: str    # Action name
    data: dict     # Payload

# Response
class ActionResponse(pydantic.BaseModel):
    seq_id: int
    code: int           # 0 = success
    message: str
    data: dict
    chunk_status: str   # "continue" | "end" (streaming support)
```

The `Handler` class is the system's core abstraction, acting as both RPC client and server:

```python
class Handler:
    async def call_action(self, action, data, timeout=15.0) -> dict:
        """Actively call an action provided by the peer, wait for response"""
        self.seq_id_index += 1
        request = ActionRequest.make_request(self.seq_id_index, action.value, data)
        future = asyncio.Future()
        self.resp_waiters[self.seq_id_index] = future
        await self.conn.send(json.dumps(request.model_dump()))
        response = await asyncio.wait_for(future, timeout)
        return response.data

    @action(SomeAction.DO_SOMETHING)
    async def handle_something(data: dict) -> ActionResponse:
        """Register an action for the peer to call"""
        return ActionResponse.success({"result": "ok"})
```

**Key design points:**

- `seq_id`-based request/response matching enables full-duplex concurrent calls
- Streaming responses via `chunk_status` for long-running operations like command execution
- Large messages auto-chunk (stdio: 16KB / WebSocket: 64KB per chunk)
- File transfer uses a separate base64 chunking mechanism

### Action Enums: Clear API Contracts

The system defines all cross-process calls through four enum groups:

```python
# Plugin → Runtime (plugin-initiated requests)
class PluginToRuntimeAction:
    REGISTER_PLUGIN = "register_plugin"
    SEND_MESSAGE = "send_message"        # Send message to a platform
    INVOKE_LLM = "invoke_llm"           # Call an LLM
    SET_PLUGIN_STORAGE = "set_plugin_storage"  # Persistent storage
    # ...

# Runtime → Plugin (runtime-dispatched commands)
class RuntimeToPluginAction:
    INITIALIZE_PLUGIN = "initialize_plugin"
    EMIT_EVENT = "emit_event"
    CALL_TOOL = "call_tool"
    EXECUTE_COMMAND = "execute_command"
    SHUTDOWN = "shutdown"
    # ...

# LangBot Main → Runtime
class LangBotToRuntimeAction:
    INSTALL_PLUGIN = "install_plugin"
    EMIT_EVENT = "emit_event"
    LIST_TOOLS = "list_tools"
    # ...

# Runtime → LangBot Main
class RuntimeToLangBotAction:
    GET_PLUGIN_SETTINGS = "get_plugin_settings"
    SET_BINARY_STORAGE = "set_binary_storage"
    # ...
```

This makes API boundaries crystal clear — what a plugin can and cannot do is defined entirely by these enums.

## Plugin Lifecycle

A plugin goes through these stages from installation to execution:

### 1. Discovery

On startup, Runtime scans the `data/plugins/` directory:

```python
async def launch_all_plugins(self):
    for plugin_path in glob.glob("data/plugins/*"):
        if not os.path.isdir(plugin_path):
            continue
        task = self.launch_plugin(plugin_path)
        self.plugin_run_tasks.append(task)
```

Directory names follow the `{author}__{name}` convention, each containing a `manifest.yaml` and plugin code.

### 2. Launch

Runtime spawns an independent subprocess for each plugin:

```python
async def launch_plugin(self, plugin_path: str):
    python_path = sys.executable
    args = ["-m", "langbot_plugin.cli.__init__", "run", "-s", "--prod"]

    ctrl = StdioClientController(
        command=python_path,
        args=args,
        working_dir=plugin_path,  # Each plugin runs in its own directory
    )
    await ctrl.run(new_plugin_connection_callback)
```

**Key detail**: The subprocess working directory is set to the plugin's own directory — natural filesystem isolation.

### 3. Registration

After starting, the plugin process actively registers itself with Runtime:

```python
# Runtime-side registration handler
async def register_plugin(self, handler, container_data, debug_plugin=False):
    plugin_container = PluginContainer.from_dict(container_data)
    # Fetch plugin settings from the main process
    plugin_settings = await self.context.control_handler.call_action(
        RuntimeToLangBotAction.GET_PLUGIN_SETTINGS, {...}
    )
    # Initialize the plugin (send config)
    await handler.initialize_plugin(plugin_settings)
    # Store the plugin container
    self.plugins.append(plugin_container)
```

### 4. Running

Once in `INITIALIZED` state, the plugin can receive events, tool calls, and command executions.

### 5. Shutdown

```python
async def shutdown_plugin(self, plugin_container):
    # 1. Notify the plugin to shut down gracefully
    await plugin_container._runtime_plugin_handler.shutdown_plugin()
    # 2. Close the communication connection
    await plugin_container._runtime_plugin_handler.conn.close()
    # 3. Kill the subprocess
    if handler.stdio_process is not None:
        handler.stdio_process.kill()
        await asyncio.wait_for(handler.stdio_process.wait(), timeout=2)
```

## Component System: Four Extension Types

A LangBot plugin isn't a single hook function — it's a **component container**. A single plugin can provide multiple component types simultaneously:

### EventListener

The most fundamental extension — listen for events in the message pipeline:

```python
from langbot_plugin.api.definition.components.common.event_listener import EventListener
from langbot_plugin.api.entities.events import PersonNormalMessageReceived
from langbot_plugin.api.entities.context import EventContext

class MyListener(EventListener):
    @EventListener.handler(PersonNormalMessageReceived)
    async def on_person_message(self, ctx: EventContext):
        event = ctx.event
        # Modify the user message before it reaches the LLM
        event.user_message_alter = "Answer in poetry: " + event.text_message

        # Or block further processing
        # ctx.prevent_default()
        # ctx.prevent_postorder()
```

Supported events cover the full message lifecycle:

| Event                         | Trigger                            |
| ----------------------------- | ---------------------------------- |
| `PersonMessageReceived`       | Any private message received       |
| `GroupMessageReceived`        | Any group message received         |
| `PersonNormalMessageReceived` | Private message deemed processable |
| `GroupNormalMessageReceived`  | Group message deemed processable   |
| `NormalMessageResponded`      | LLM response completed             |
| `PromptPreProcessing`         | Prompt preprocessing stage         |

Event propagation supports two interruption modes:

- `prevent_default()`: Skip default behavior (e.g., skip the LLM call)
- `prevent_postorder()`: Stop subsequent plugins from running

### Tool

Tools for LLM Function Calling:

```python
from langbot_plugin.api.definition.components.tool.tool import Tool

class WeatherTool(Tool):
    async def call(self, params: dict, session, query_id: int) -> str:
        city = params.get("city", "Beijing")
        # Call weather API...
        return f"{city}: Sunny, 25°C"
```

Tool metadata (name, description, parameter schema) is defined in a companion YAML manifest file. LangBot automatically converts this into the Function definition that LLMs understand.

### Command

User-triggered commands via `!command`, with subcommand support:

```python
from langbot_plugin.api.definition.components.command.command import Command

class MyCommand(Command):
    def __init__(self):
        super().__init__()

        @self.subcommand("hello", help="Say hello")
        async def hello(self, ctx):
            yield CommandReturn(text="Hello from plugin!")

        @self.subcommand("status", help="Show status")
        async def status(self, ctx):
            yield CommandReturn(text="All systems operational.")
```

Command results are returned via `AsyncGenerator`, providing natural streaming output.

### KnowledgeRetriever

A multi-instance component for connecting external knowledge bases:

```python
from langbot_plugin.api.definition.components.knowledge_retriever.retriever import KnowledgeRetriever

class MyRetriever(KnowledgeRetriever):
    async def retrieve(self, context) -> list:
        results = await self.search_external_db(context.query)
        return [RetrievalResultEntry(content=r) for r in results]
```

KnowledgeRetriever is a **polymorphic component** — a single retriever class can spawn multiple instances, each with independent configuration. This allows users to connect multiple different external knowledge bases.

## SDK API: What Plugins Can Do

Plugins gain rich capabilities through the `LangBotAPIProxy` inherited by `BasePlugin`:

```python
class LangBotAPIProxy:
    # Message operations
    async def send_message(self, bot_uuid, target_type, target_id, message_chain)

    # Model invocation
    async def get_llm_models(self) -> list[str]
    async def invoke_llm(self, model_uuid, messages, funcs=[], extra_args={})

    # Persistent storage (plugin-level isolation)
    async def set_plugin_storage(self, key, value: bytes)
    async def get_plugin_storage(self, key) -> bytes

    # Workspace storage (cross-plugin shared)
    async def set_workspace_storage(self, key, value: bytes)
    async def get_workspace_storage(self, key) -> bytes

    # System info
    async def get_langbot_version(self) -> str
    async def get_bots(self) -> list[str]
    async def list_plugins_manifest(self) -> list
```

**The storage API design is worth noting**: Two levels of KV storage — `plugin_storage` (plugin-private) and `workspace_storage` (globally shared), storing data as bytes (base64-serialized in transit). Simple but flexible enough.

## Event Dispatch Mechanism

The complete path from main process to plugin:

![Event Dispatch Flow](https://langbot.app/docs/images/articles/source/images/plugin-system/event-dispatch.png)

Key source code:

```python
async def emit_event(self, event_context, include_plugins=None):
    for plugin in self.plugins:
        if plugin.status != RuntimeContainerStatus.INITIALIZED:
            continue
        if not plugin.enabled:
            continue

        # Pipeline-level plugin filtering
        if include_plugins is not None:
            plugin_id = f"{plugin.manifest.metadata.author}/{plugin.manifest.metadata.name}"
            if plugin_id not in include_plugins:
                continue

        resp = await plugin._runtime_plugin_handler.emit_event(
            event_context.model_dump()
        )

        event_context = EventContext.model_validate(resp["event_context"])

        # Plugin requested propagation stop
        if event_context.is_prevented_postorder():
            break

    return emitted_plugins, event_context
```

The `include_plugins` parameter enables **pipeline-level plugin binding** — different message processing pipelines can use different subsets of plugins.

## Installation & Distribution

Plugins support three installation sources:

1. **Local upload**: `.lbpkg` files (actually zip archives containing manifest.yaml and code)
2. **Marketplace**: Install from LangBot Space online
3. **GitHub Release**: Download from a GitHub repository's Release assets

The installation flow:

```python
async def install_plugin(self, source, install_info):
    yield {"current_action": "downloading plugin package"}
    # 1. Fetch and extract the plugin package (unzip)
    plugin_path, author, name, version = await self.install_plugin_from_file(plugin_file)

    yield {"current_action": "installing dependencies"}
    # 2. Install dependencies (pip install -r requirements.txt)
    pkgmgr_helper.install_requirements(requirements_file)

    yield {"current_action": "initializing plugin settings"}
    # 3. Initialize configuration
    await self.context.control_handler.call_action(
        RuntimeToLangBotAction.INITIALIZE_PLUGIN_SETTINGS, {...}
    )

    yield {"current_action": "launching plugin"}
    # 4. Launch the plugin process
    task = self.launch_plugin(plugin_path)
```

The entire process reports progress via `AsyncGenerator`, enabling real-time installation status in the frontend.

## Developer Experience

The SDK provides a complete developer toolchain:

```bash
# Initialize a new plugin
lbp init

# Add a component
lbp component add

# Run locally for debugging
lbp run

# Package for publication
lbp publish
```

**Debug mode** has a particularly clever design: the developer's plugin connects to the running Runtime via WebSocket (instead of stdio), meaning you can hot-reload plugin code without restarting LangBot. Debug plugins are specially marked in the UI and protected from accidental deletion.

## Comparisons with Other Systems

### vs Dify Plugins

Dify's plugin system (`dify-plugin-daemon`) shares the process isolation philosophy with LangBot, but the focus differs:

- **Dify**: Plugins extend workflow node types (Tool, Model, Extension) — designed for AI application orchestration
- **LangBot**: Plugins extend the message processing pipeline (Event, Tool, Command, KnowledgeRetriever) — designed for instant messaging scenarios

LangBot's `EventListener` component provides a capability Dify lacks — injecting logic at any stage of message processing.

### vs MCP (Model Context Protocol)

MCP is a standardized protocol for AI tool invocation. LangBot's Tool component and MCP services overlap functionally, but serve different purposes:

- **MCP**: A universal "AI calls external capabilities" protocol, usable by any LLM application
- **LangBot Tool**: Deeply integrated with message processing context, with access to session info, user identity, etc.

In practice, LangBot natively supports MCP — users can configure MCP servers directly in LangBot without writing plugins. LangBot's Tool component is for scenarios requiring access to LangBot's internal context.

## Design Decisions Explained

**Why process isolation instead of threads/coroutines?**

- Plugin code quality is unpredictable; a segfault shouldn't crash the entire service
- Dependency isolation: different plugins may depend on different versions of the same library
- Resource control: you can set per-plugin process resource limits

**Why JSON instead of Protobuf/MessagePack?**

- Debug-friendly: developers can directly read communication logs
- Natively supported in Python, no extra dependencies
- The performance bottleneck isn't serialization (plugin call frequency is far below database queries)

**Why stdio over WebSocket by default?**

- stdio requires no network stack — lower latency
- Simpler process lifecycle management (child processes auto-cleanup when parent exits)
- WebSocket is only used where stdio isn't supported (Docker, Windows)

## Conclusion

LangBot's plugin system is a **production-grade, process-isolated, event-driven component framework for extensibility**.

Its core design principles:

1. **Safety first**: Process isolation ensures plugins can't destabilize the main service
2. **Deployment flexibility**: Dual stdio/WebSocket modes adapt to all environments
3. **Developer-friendly**: Complete SDK, CLI, and debug support
4. **Component-based**: Four component types cover the major extension needs

If you're interested in developing LangBot plugins, start with the [plugin development docs](https://langbot.app/docs/en/plugin/dev/tutor.md), or browse existing plugins on the [marketplace](https://space.langbot.app/market) for inspiration.

---

# LangBot v4.10.0: Agentic Sandbox & Skills — Letting Your Agent Work Like a Developer

Source: https://langbot.app/docs/en/articles/langbot-v4100-sandbox-skills

LangBot v4.10.0 brings a real sandbox (Box Runtime) and an on-demand Skills system to the built-in Agent. It can now run commands and edit files in an isolated environment, and pull in specialized know-how exactly when a task needs it.

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/langbot-v4100-sandbox-skills).

Published 2026-06-04 · Author: LangBot Team

![LangBot v4.10.0 Agentic Sandbox & Skills](https://langbot.app/docs/images/articles/source/images/covers/sandbox-skills.png)

LangBot v4.10.0 is our biggest Agent update yet. It ships two features that point in the same direction — **letting the built-in Agent work like a real developer**:

1. **Sandbox**: the Agent now runs in a genuinely isolated environment where it can execute commands and work with files.
2. **Skills**: the Agent can load specialized know-how on demand, instead of cramming everything into its context.

Both capabilities were led by community contributor [@huanghuoguoguo](https://github.com/huanghuoguoguo). Let's dig in.

> **New to LangBot?** [LangBot](https://github.com/langbot-app/LangBot) is an open-source LLM bot platform (15k+ GitHub stars) that lets you deploy AI chatbots across **Discord, Telegram, WeChat (个人微信 / 企业微信), Slack, Lark (Feishu), DingTalk, QQ** and more — all from a single instance. It connects 20+ large language models (OpenAI GPT, Anthropic Claude, Google Gemini, DeepSeek, and others) to 13+ messaging platforms, with built-in Agent, RAG knowledge bases, MCP support, and a plugin ecosystem. You can self-host it with one Docker command or run it managed on [LangBot Cloud](https://space.langbot.app/cloud).

## 📦 Sandbox: a real workspace for your Agent

Until now, LangBot's built-in Agent could only call predefined tools. It couldn't "open a terminal and run a command," nor "write an intermediate result to a file and read it back later" — which is exactly what human developers do all day.

v4.10.0 introduces the new **Box Runtime**. It gives the Agent an isolated sandbox environment with six native tools built in:

| Tool    | Purpose                      |
| ------- | ---------------------------- |
| `exec`  | Run shell commands           |
| `read`  | Read file contents           |
| `write` | Write files                  |
| `edit`  | Make targeted edits to files |
| `glob`  | Find files by pattern        |
| `grep`  | Search inside file contents  |

With this toolkit, the Agent can work like a developer: run a script, save the output to a file, read it back to analyze, and post-process the result. All of it happens inside an isolated environment that never touches the host.

![LangBot sandbox in action](https://langbot.app/docs/images/articles/source/images/sandbox-skills/sandbox.png)

### Pluggable backends

The sandbox's execution backend is **pluggable**, and LangBot selects one automatically based on your deployment:

- **Docker**: spins up a dedicated `langbot_box` container that talks to the main process over WebSocket. Great for containerized deployments.
- **nsjail**: lightweight isolation based on Linux namespaces, no extra container needed. Great for bare-metal or single-container setups.
- **E2B**: cloud sandbox that runs execution in a remote isolated environment.

You don't have to pick manually — `box.enabled` is the master switch. Once on, LangBot probes for the most suitable backend and degrades gracefully if probing fails.

![Sandbox native tools](https://langbot.app/docs/images/articles/source/images/sandbox-skills/sandbox-tools.png)

### It also hosts MCP Servers

Beyond native tools, the Box Runtime takes on another important job: **hosting stdio-mode MCP Servers**.

Previously, stdio-mode MCP Servers had to be spawned as subprocesses directly inside the main process — neither safe nor easy to manage. Now they all run inside the sandbox, sharing the same isolation boundary as the Agent's execution environment. `http` / `sse` mode MCP is unaffected and works as before.

## 🎯 Skills: know-how, loaded on demand

The second big update is **Skills**.

As the Agent's capabilities grow, an old problem surfaces: **the context window is finite**. If you stuff every possible instruction, procedure, and reference doc into the system prompt, the context fills up fast — and most of it is irrelevant to the task at hand.

The design idea behind Skills is simple: **keep the table of contents in view, and open the book only when you need it.**

A Skill is an **on-demand instruction pack** containing:

- **A prompt**: tells the Agent what the skill does and when to use it
- **A procedure**: the steps to accomplish a class of tasks
- **Scripts**: ready-to-run helper scripts
- **Reference files**: API docs, templates, examples, and so on

By default the Agent only sees a **list of available skills** (name + summary), which costs almost nothing in context. When it decides a task needs a particular skill, it pulls the full content just in time via the `activate` action.

![LangBot Skills system](https://langbot.app/docs/images/articles/source/images/sandbox-skills/skills.png)

The benefits are clear:

1. **Lean context**: irrelevant skill content never takes up the window.
2. **Extensible capabilities**: want to teach the Agent a new trick? Write a skill pack — no core code changes.
3. **Instant effect**: skills load dynamically during execution, no restart required.

If you've used Claude's Skills or a similar mechanism, this pattern will feel familiar — it decouples "what the Agent knows" from "what the Agent needs right now."

## 🧩 Shipped early across 4.9.x

These were planned for v4.10.0 but shipped early in the 4.9.x line:

- **Plugin Extension Pages**: plugins can render custom UI via iframe + a Page SDK ([@TyperBody](https://github.com/TyperBody), #2107)
- **Monitoring**: feedback linked to message IDs, plus feedback export ([@6mvp6](https://github.com/6mvp6), #2120)
- **Security hardening**: path-traversal fixes and removal of an authenticated RCE endpoint ([@sebastiondev](https://github.com/sebastiondev), #2087 / #2178)

## 🚀 Getting started

The sandbox needs an execution backend, depending on how you deploy:

- **Docker**: run `docker compose --profile all up`, which also launches the `langbot_box` container.
- **Manual / `uvx`**: runs as a stdio subprocess automatically, nothing to do.
- **LangBot Cloud**: ready out of the box — the sandbox is already set up for you, nothing to install.

To turn the sandbox off, set `box.enabled: false` — built-in tools, Skill create/edit, and stdio-mode MCP are all disabled; `http` / `sse` mode MCP is unaffected. See the [Sandbox docs](https://langbot.app/docs/en/usage/sandbox/readme.md) for details.

This release also upgrades the plugin SDK to **`langbot-plugin 0.4.1`**.

## Closing thoughts

Sandbox and Skills are, at their core, answering the same question: **how do we let an Agent handle genuinely complex, open-ended tasks?**

The sandbox solves the "**hands**" problem — giving the Agent the ability to execute and room to experiment. Skills solve the "**brain**" problem — letting the Agent reach for the right knowledge at the right moment, without drowning in irrelevant information.

The fastest way to try it is to spin up a managed instance on [LangBot Cloud](https://space.langbot.app/cloud), where the sandbox is ready to go. You can also read the [full release notes](https://github.com/langbot-app/LangBot/releases/tag/v4.10.0) for every change.

Thank you to everyone building with LangBot. We'll keep making the cloud Agent experience more stable and more capable.

---

# LangBot v4.9.0: Full RAG Plugin Architecture — Knowledge Without Borders

Source: https://langbot.app/docs/en/articles/langbot-v490-rag-plugin-architecture

LangBot v4.9.0 refactors the entire knowledge base system from a built-in implementation to a plugin-driven architecture, introducing KnowledgeEngine and Parser component types for boundless extensibility.

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/langbot-v490-rag-plugin-architecture).

Published 2026-03-10 · Author: LangBot Team

![LangBot v4.9.0 RAG Plugin Architecture](https://langbot.app/docs/images/articles/source/images/covers/rag-plugin.png)

LangBot v4.9.0, codenamed **"Knowledge Without Borders,"** does exactly what the name says: **the entire knowledge base capability has been refactored from a built-in implementation to a plugin-driven architecture.**

This isn't a minor tweak — it redefines what "knowledge" means in LangBot.

## The Problem with the Old Approach

Before v4.9.0, LangBot's knowledge base was split into two separate systems:

- **Built-in Knowledge Base**: Used Chroma as the vector database, with embedding models managed by LangBot directly. Document parsing, chunking, and indexing were all hardcoded.
- **External Knowledge Base**: Bridged services like Dify, RAGFlow, and FastGPT through the `KnowledgeRetriever` plugin component — retrieval only, no document ingestion.

These two systems lived behind separate UI tabs, with completely different data models and management flows.

**Why this was painful:**

1. **Poor extensibility**: Want a different vector database? A custom chunking strategy? Sorry, that's hardcoded.
2. **High maintenance cost**: Every RAG improvement required changes to LangBot's core code and a new release.
3. **Fragmented UX**: Two completely different knowledge base management flows meant a steep learning curve.

v4.9.0 solves this decisively: **extract RAG capabilities from LangBot's core and hand them to plugins.**

## What Changed

### 1. Unified Knowledge Base Model

The `internal` / `external` distinction is gone. All knowledge bases are managed through a single interface, differentiated only by their `rag_engine_plugin_id`. One list, one creation flow — just pick your engine.

### 2. KnowledgeEngine Component

This is the headline addition. `KnowledgeEngine` replaces the old `KnowledgeRetriever` and takes ownership of the full knowledge base lifecycle:

- **Document Ingestion**: The complete pipeline from file parsing to vector indexing
- **Knowledge Retrieval**: Returning relevant chunks at query time
- **Document Deletion**: Cleaning up documents and their associated vector data
- **Lifecycle Hooks**: Callbacks when knowledge bases are created or deleted

A KnowledgeEngine plugin has full control over indexing and retrieval strategies — not just retrieval.

![Knowledge Engine plugins in the Marketplace](https://langbot.app/docs/images/articles/external/b9a33a8551a7-8dd37939-4f10-4046-bd84-cce798005cd4.png)

### 3. Parser Component

Document parsing has been extracted into its own plugin component type. A Parser converts binary files (PDF, Word, Markdown, etc.) into structured text, which is then handed to the RAG engine for chunking and indexing.

**The data flow:**

![Data flow: Parser → KnowledgeEngine](https://langbot.app/docs/images/articles/source/images/rag-plugin/data-flow.png)

If a RAG engine declares `DOC_PARSING` capability, it can handle parsing internally and skip the external Parser.

### 4. Host RAG API

LangBot's core no longer executes RAG operations directly, but it still provides essential infrastructure through `RAGRuntimeService`, accessible to plugins via RPC:

- **Embedding invocation**: `invoke_embedding()` — plugins don't need to manage model connections
- **Vector database operations**: `vector_upsert()` / `vector_search()` / `vector_delete()`
- **File access**: `get_knowledge_file_stream()` — read raw files from storage

This means plugins can focus on RAG strategy (chunking algorithms, retrieval logic, re-ranking) while the host handles the "heavy" operations like vector storage and embedding models.

### 5. KnowledgeRetriever Deprecated

The old `KnowledgeRetriever` component has been removed. If you had external knowledge base plugins, they'll need to migrate to `KnowledgeEngine`. The good news: the new API is cleaner and migration is straightforward.

## Building a RAG Engine Plugin

### Scaffold the Component

```bash
lbp comp KnowledgeEngine
```

This generates the directory structure:

![Plugin directory structure](https://langbot.app/docs/images/articles/source/images/rag-plugin/dir-structure.png)

### Define Configuration Schemas

The YAML manifest defines two configuration schemas:

- **`creation_schema`**: Parameters filled when creating a knowledge base (e.g., chunk size, embedding model)
- **`retrieval_schema`**: Parameters adjustable at retrieval time (e.g., score threshold, top-K)

```yaml
spec:
  creation_schema:
    - name: chunk_size
      label:
        en_US: Chunk Size
      type: integer
      default: 500
    - name: chunk_overlap
      label:
        en_US: Chunk Overlap
      type: integer
      default: 50
  retrieval_schema:
    - name: score_threshold
      label:
        en_US: Score Threshold
      type: float
      default: 0.5
```

LangBot **dynamically renders** creation and retrieval forms based on these schemas — different engines show different configuration fields.

### Declare Capabilities

```python
class SimpleRag(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return [
            KnowledgeEngineCapability.DOC_INGESTION,   # Supports document upload
            # KnowledgeEngineCapability.DOC_PARSING,   # Optional: built-in parsing
        ]
```

| Capability      | Description                                                                             |
| --------------- | --------------------------------------------------------------------------------------- |
| `DOC_INGESTION` | Supports document upload and processing. UI shows "Documents" tab                       |
| `DOC_PARSING`   | Supports built-in document parsing. Without this, an external Parser plugin is required |

### Implement Core Methods

The three essential methods:

**Document Ingestion:**

```python
async def ingest(self, context: IngestionContext) -> IngestionResult:
    # 1. Get file content (or use Parser's pre-parsed result)
    if context.parsed_content:
        text = context.parsed_content.text
    else:
        file_bytes = await self.plugin.get_knowledge_file_stream(
            context.file_object.storage_path
        )
        text = file_bytes.decode('utf-8')

    # 2. Chunk the text
    chunks = self._split_text(text, chunk_size=500)

    # 3. Call host embedding model
    vectors = await self.plugin.invoke_embedding(
        embedding_model_uuid, chunks
    )

    # 4. Write to host vector database
    await self.plugin.vector_upsert(
        collection_id, vectors, ids, metadata
    )

    return IngestionResult(
        document_id=context.file_object.metadata.document_id,
        status=DocumentStatus.COMPLETED,
        chunks_created=len(chunks),
    )
```

**Knowledge Retrieval:**

```python
async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
    # 1. Generate query vector
    query_vectors = await self.plugin.invoke_embedding(
        embedding_model_uuid, [context.query]
    )

    # 2. Vector search
    results = await self.plugin.vector_search(
        collection_id, query_vectors[0], top_k=5
    )

    # 3. Convert and return
    return RetrievalResponse(results=entries, total_found=len(entries))
```

**Document Deletion:**

```python
async def delete_document(self, kb_id: str, document_id: str) -> bool:
    deleted = await self.plugin.vector_delete(
        collection_id=kb_id, file_ids=[document_id]
    )
    return deleted > 0
```

### Bridging External Services

If your goal is to bridge Dify, RAGFlow, FastGPT, or other external services rather than building a custom RAG pipeline, the implementation is even simpler — **don't declare `DOC_INGESTION` capability** and only implement `retrieve`:

```python
class DifyRAGEngine(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return []  # No document upload — managed externally

    async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
        # Call Dify/RAGFlow/FastGPT retrieval API
        ...
```

The knowledge base won't show a "Documents" tab — all content management happens in the external service.

## Building a Parser Plugin

Parser development is even more concise:

```bash
lbp comp Parser
```

Declare supported MIME types in the manifest:

```yaml
spec:
  supported_mime_types:
    - application/pdf
    - application/vnd.openxmlformats-officedocument.wordprocessingml.document
```

Implement the `parse` method:

```python
class PdfParser(Parser):

    async def parse(self, context: ParseContext) -> ParseResult:
        # context.file_content: raw file bytes
        # context.mime_type: detected MIME type
        # context.filename: original filename

        text = extract_text_from_pdf(context.file_content)

        return ParseResult(
            text=text,
            sections=[
                TextSection(content=page_text, heading=f"Page {i}", page=i)
                for i, page_text in enumerate(pages)
            ],
        )
```

Parsers also support **cross-plugin invocation** — a RAG engine plugin can call another plugin's Parser:

```python
result = await self.plugin.invoke_parser(
    plugin_author="author_name",
    plugin_name="plugin_name",
    storage_path=context.file_object.storage_path,
    mime_type=context.file_object.metadata.mime_type,
    filename=context.file_object.metadata.filename,
)
```

## Upgrade Notes

- Knowledge bases created in previous versions are **automatically migrated**. After updating, visit the Knowledge Base page to verify.
- The `KnowledgeRetriever` component is deprecated. Existing plugins need to migrate to `KnowledgeEngine`.
- Browse the [Plugin Marketplace](https://space.langbot.app/market?category=KnowledgeEngine) for available RAG engine plugins.

## The Bigger Picture

v4.9.0's knowledge base refactoring is the latest step in LangBot's plugin-first evolution. From event handlers and tools in v4.0, to knowledge retrievers, to now full RAG engines and parsers — LangBot's core capabilities are progressively moving from "built-in" to "pluggable."

The endgame: **LangBot's core provides pipeline orchestration and infrastructure; all business capabilities are plugin-driven.**

Custom chunking strategy? Write a KnowledgeEngine plugin. PDF parsing? Write a Parser plugin. Bridge your company's internal knowledge service? Also a plugin.

Knowledge, without borders.

***

**Links:**

- [v4.9.0 Release Notes](https://github.com/langbot-app/LangBot/releases/tag/v4.9.0)
- [KnowledgeEngine Development Guide](https://langbot.app/docs/en/plugin/dev/components/knowledge-engine.md)
- [Parser Development Guide](https://langbot.app/docs/en/plugin/dev/components/parser.md)
- [Plugin Marketplace](https://space.langbot.app/market)
- [LangBot Cloud](https://space.langbot.app/cloud)

---

# How I Built a Multi-Platform AI Bot with Langflow's Drag-and-Drop Workflows

Source: https://langbot.app/docs/en/articles/langflow-drag-and-drop-ai-bot

How I Built a Multi-Platform AI Bot with Langflow's Drag-and-Drop Workflows

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/langflow-drag-and-drop-ai-bot).

Published 2025-12-05 · Author: LangBot Team

![How I Built a Multi-Platform AI Bot with Langflow's Drag-and-Drop Workflows](https://langbot.app/docs/images/articles/source/images/covers/langflow.png)

Drive chatbots across QQ, WeChat, Telegram, Discord, and more using visual workflows - no coding required.

***

[LangBot](https://github.com/langbot-app/LangBot) is an open-source instant messaging bot platform that connects AI workflow engines like Langflow, n8n, Dify, FastGPT, and Coze to platforms including WeChat, QQ, Feishu, DingTalk, Telegram, Discord, Slack, and LINE. This tutorial demonstrates how to use Langflow's visual workflows as LangBot's conversation engine.

## Why This Approach Works

- **True Multi-Platform**: One workflow powering 8+ messaging platforms simultaneously
- **Visual Orchestration**: Drag-and-drop conversation design with conditional branches, multi-turn dialogs, and external API calls
- **Flexible AI Models**: Support for OpenAI, Claude, Gemini, DeepSeek, and local models
- **Fully Open Source**: Both LangBot and Langflow are open-source projects for free deployment and customization

## Prerequisites

- Python 3.10+
- Docker (recommended for quick deployment)
- OpenAI API Key or API keys for other LLM services

## Step 1: Deploy LangBot

Launch with uvx in one command:

```bash
uvx langbot
```

First run auto-initializes and opens your browser to <http://127.0.0.1:5300>.

![LangBot Initial Page](https://langbot.app/docs/images/articles/external/0c8aa2c940ab-01-langbot-initial-page.png)

After registration, log in to access the dashboard:

![LangBot Dashboard](https://langbot.app/docs/images/articles/external/b93d97b5b830-04-langbot-dashboard.png)

## Step 2: Deploy Langflow

Deploy quickly with Docker:

```bash
docker run -d --name langflow -p 7860:7860 langflowai/langflow:latest
```

Visit <http://localhost:7860> to access Langflow:

![Langflow Welcome Page](https://langbot.app/docs/images/articles/external/7e7ebfc3ba58-01-langflow-welcome.png)

## Step 3: Create a Langflow Workflow

In Langflow, select the "Basic Prompting" template to get started quickly:

![Langflow Template Selection](https://langbot.app/docs/images/articles/external/b304cebf8ce9-02-langflow-template-selection.png)

This template includes four basic components:

- **Chat Input**: Receives user messages
- **Prompt**: Sets system instructions
- **Language Model**: Calls LLM to generate responses
- **Chat Output**: Returns results

![Langflow Workflow Editor](https://langbot.app/docs/images/articles/external/6e24402fd4a8-03-langflow-workflow-editor.png)

### Configure Language Model

Click the Language Model component and configure:

1. **Model Provider**: Select OpenAI (or other compatible providers like SiliconFlow, New API)
2. **Model Name**: Select gpt-4o-mini or deepseek-chat
3. **OpenAI API Key**: Enter your API Key

![Langflow OpenAI API Key Configured](https://langbot.app/docs/images/articles/external/bcd91ef5e4b3-14-langflow-openai-api-key-configured.png)

> Tip: You can use OpenAI-compatible API services like SiliconFlow or New API by simply modifying the Base URL.

Save the workflow after configuration.

## Step 4: Get Langflow API Information

### Generate API Key

In Langflow's upper right: Settings → API Keys, navigate to the API Keys page:

![Langflow API Keys Page](https://langbot.app/docs/images/articles/external/21fc47358066-05-langflow-api-keys-page.png)

Click Create New Key:

![Langflow Create API Key Dialog](https://langbot.app/docs/images/articles/external/8f04c7b00759-06-langflow-create-api-key-dialog.png)

Generate and save the API Key:

![Langflow API Key Generated](https://langbot.app/docs/images/articles/external/e5a019491ef8-07-langflow-api-key-generated.png)

Format: `sk-xxxxxxxxxxxxxxxxxxxxxxxx`

### Get Flow ID

Extract from the flow editor's URL:

```
http://localhost:7860/flow/{flow-id}
```

Record this `flow-id`.

## Step 5: Configure Langflow in LangBot

Return to LangBot dashboard and go to **Pipelines** page.

Click ChatPipeline to edit, in the AI tab:

![LangBot Pipeline AI Tab](https://langbot.app/docs/images/articles/external/3c7d6bc96738-08-langbot-pipeline-ai-tab.png)

Configure **Runner**, select **Langflow API**:

![LangBot Runner Dropdown](https://langbot.app/docs/images/articles/external/ef9bbef78165-09-langbot-runner-dropdown.png)

Fill in the Langflow configuration:

![LangBot Langflow Config Form](https://langbot.app/docs/images/articles/external/82d5e2ffb9a0-10-langbot-langflow-config-form.png)

Configuration items:

- **Base URL**: `http://localhost:7860` (local) or `http://langflow:7860` (Docker network)
- **API Key**: The API Key generated in Langflow
- **Flow ID**: The Flow ID recorded earlier

![LangBot Langflow Config Filled](https://langbot.app/docs/images/articles/external/2fb54ce0f7a2-11-langbot-langflow-config-filled.png)

> Docker Tip: If both services run in containers, ensure they're on the same network and use the container name for Base URL.

Click **Save** to save the configuration.

## Step 6: Test the Conversation

Click **Debug Chat** on the Pipelines page to open the debug chat interface:

![LangBot Debug Chat Interface](https://langbot.app/docs/images/articles/external/b36d6dea3702-12-langbot-debug-chat-interface.png)

Enter a test message like "Hello" and view the AI response:

![LangBot Chat Test Success](https://langbot.app/docs/images/articles/external/3d7fa393f210-13-langbot-chat-with-response.png)

## How It Works

1. User sends a message on a messaging platform
2. LangBot receives and passes it to the Pipeline
3. Pipeline calls Langflow API
4. Langflow executes the workflow: receives input → adds prompt → calls LLM → returns result
5. LangBot sends the response back to the user

## Common Issues

**Cannot connect to Langflow?**

Check Base URL. For Docker deployment, ensure containers are on the same network:

```bash
docker network create langbot_network
docker network connect langbot_network langflow
docker network connect langbot_network langbot
```

Use container name: `http://langflow:7860`

**API call fails?**

- Confirm API Key and Flow ID are correct
- Verify the Language Model in Langflow has a valid LLM API Key configured

## Advanced Use Cases

Langflow's power lies in visually orchestrating complex AI workflows:

- **Multi-Turn Memory**: Add Memory components for contextual understanding
- **Conditional Branches**: Execute different logic based on user input
- **External API Integration**: Connect databases, search engines, third-party services
- **Multi-Agent Collaboration**: Multiple LLM models working together
- **RAG Applications**: Integrate vector databases for knowledge base Q\&A

All achievable through drag-and-drop without writing code.

## Summary

With LangBot + Langflow, you can rapidly build powerful multi-platform AI chatbots. Langflow provides visual workflow orchestration, LangBot handles messaging platform integration - together they create a complete loop from workflow design to multi-platform deployment.

This approach is ideal for:

- Scenarios requiring the same AI capabilities across multiple platforms
- Teams wanting rapid iteration and testing of different conversation flows
- Developers wanting to build complex AI applications without deep coding

## Related Resources

- [LangBot Official Site](https://langbot.app) | [Documentation](https://langbot.app/docs/en/insight/guide.md) | [GitHub](https://github.com/langbot-app/LangBot)
- [Langflow Official Site](https://www.langflow.org) | [Documentation](https://docs.langflow.org) | [GitHub](https://github.com/langflow-ai/langflow)

***

*This article is based on the latest version of LangBot. LangBot supports integration with Dify, n8n, FastGPT, Coze, and other AI platforms - choose the workflow engine that best fits your needs.*

---

# LangTARS: Open-Source AI Agent for Remote PC Control — Works with Dify, n8n & 10+ Messaging Platforms

Source: https://langbot.app/docs/en/articles/langtars-remote-pc-control-dify-n8n

LangTARS is a LangBot native plugin that lets you remotely control Mac/Windows/Linux from Telegram, Discord & WeChat — with Dify and n8n workflow support.

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/langtars-remote-pc-control-dify-n8n).

Published 2026-03-23 · Author: LangBot Team

![LangTARS Logo](https://langbot.app/docs/images/articles/external/3fe5bdc18716-icon.svg)

**LangBot Native Plugin | OpenClaw-like Experience | Ready to Use with One-Click Deployment**

***

## ✨ What is LangTARS?

**LangTARS** is a powerful **OpenClaw alternative** and native plugin for LangBot, inspired by the loyal and reliable robot TARS from the movie *Interstellar*.

As a versatile **AI agent** for **remote computer control**, LangTARS allows you to remotely command your **Mac, Windows, or Linux** machine directly through your favorite messaging apps like **Telegram, Discord, DingTalk, and WeChat**! If you've been looking for an **OpenClaw-like** computer use agent that integrates seamlessly into your existing **chatbot framework**, LangTARS is the perfect solution.

> 💡 **Deploy LangBot, and you can experience LangTARS instantly!** No extra standalone agent installation needed—just get it with one click from the plugin marketplace.

![LangTARS Demo](https://langbot.app/docs/images/articles/external/70b26e660a60-tars.gif)

***

## 🤖 The LangBot Ecosystem

LangTARS is just ONE plugin in the massive LangBot ecosystem. **LangBot** is a leading **open source chatbot** framework designed for connecting LLMs to messaging platforms.

- **Multi-platform bot integration**: Native support for Telegram, Discord, WeChat, DingTalk, Lark, LINE, Slack, and more.
- **Multi-model LLM chatbot**: Works flawlessly with OpenAI, Claude, Gemini, DeepSeek, and local models.
- **Rich Plugin Marketplace**: Access over 30+ plugins for endless functionality.
- **Advanced Features**: Pipeline-based message processing, RAG support, and multi-agent workflows.
- **Self-hosted AI**: Total control over your data and deployments.
- **AI Workflow Integrations**: Connect LangBot to platforms like **Dify**, **n8n**, **Langflow**, and **Coze**. LangBot can act as the messaging frontend for your complex AI workflows, meaning LangTARS + Dify/n8n = powerful automation!

Get started with LangBot:

- **Easiest**: [LangBot Cloud](https://cloud.langbot.app)
- Self-host: `uvx langbot@latest`
- Documentation: [langbot.app/docs](https://langbot.app/docs/en/insight/guide.md)
- GitHub: [github.com/langbot-app/LangBot](https://github.com/langbot-app/LangBot) (15k+ stars)

***

## 🎯 What Can It Do?

As a comprehensive **automation tool**, just send a message, and the AI will handle your **task automation** and **browser automation**:

| You Say                                                                                      | AI Does                                                            |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `!tars open Reddit in Chrome, post a thread with the title "Hello from LangTARS" and say hi` | 🌐 Automatically controls Chrome to open Reddit and publish a post |
| `!tars organize my desktop files`                                                            | 📁 Automatically categorizes and moves files                       |
| `!tars open the browser and search for today's AI news`                                      | 🌐 Opens a browser, searches the web, and summarizes the news      |
| `!tars create a meeting note for our marketing sync`                                         | 📝 Automatically creates a markdown note file                      |
| `!tars check system memory and CPU`                                                          | 💻 Uses MCP tools to get computer status                           |

![Usage Example](https://langbot.app/docs/images/articles/external/6613b3025b8b-usage-example.png)
![Plan Mode](https://langbot.app/docs/images/articles/external/ff42857251ab-planner-mode.png)

***

## 🔗 Supercharge with Dify & n8n

LangTARS becomes even more powerful when combined with **AI workflow platforms**:

- **Dify Integration**: Connect LangBot to [Dify](https://dify.ai) as a messaging frontend. Build complex AI workflows in Dify's visual editor, then trigger them from Telegram/Discord via LangTARS.
- **n8n Integration**: Use [n8n](https://n8n.io) workflows with LangBot for advanced automation chains. Combine LangTARS's computer control with n8n's 400+ integrations for unlimited possibilities.
- **Also supports**: Langflow, Coze, and any OpenAI-compatible API.

> 💡 **Example**: "Hey TARS, run my Dify workflow to analyze today's sales data and save the report to my desktop" — LangTARS handles the entire chain.

***

## 🚀 Why Choose LangTARS?

### 1️⃣ LangBot Native Plugin, Out of the Box

Instead of deploying a complex standalone agent, you can easily **deploy AI bot** capabilities right where you already chat.

```bash
# Deploy LangBot with one command
uvx langbot@latest

# Install LangTARS from the plugin market, configure your LLM, and start using!
```

**No complex configuration, no extra deployment. LangBot users can experience OpenClaw-style computer control directly!**

![Installation Flow](https://langbot.app/docs/images/articles/external/2a3a0d5f4ae9-install-flow.png)

***

### 2️⃣ Intelligent Task Planning, Autonomous Execution

Powered by an AI planning engine based on the **ReAct agent** loop:

```
Your Command → Understand Needs → Make a Plan → Execute Step-by-Step → Feedback Results
```

The AI assistant thinks like a human and automatically breaks down complex tasks using integrated **MCP tools**!

***

### 3️⃣ Multi-Browser Support for Web Automation

| Browser               | macOS | Windows | Linux |
| --------------------- | ----- | ------- | ----- |
| Playwright (Headless) | ✅     | ✅       | ✅     |
| Safari                | ✅     | -       | -     |
| Chrome                | ✅     | ✅       | ✅     |
| Edge                  | -     | ✅       | -     |
| Firefox               | -     | -       | ✅     |

***

### 4️⃣ Security-First Design

- 🚫 **Dangerous Command Interception** — Automatically blocks commands like `rm -rf /`
- 📂 **Workspace Isolation** — Restricts file operations to safe directories
- 📋 **Command Whitelist** — Configurable allowed commands
- 👤 **User Access Control** — Restricts usage to specific authorized users

![Security Features](https://langbot.app/docs/images/articles/external/a618d3d41416-security.png)

***

## 📱 Quick Start

### Step 1: Deploy LangBot

> 🚀 **Fastest way to start:** Use [LangBot Cloud](https://cloud.langbot.app) — deploy your LangBot instance in one click, no server needed! Install LangTARS from the plugin marketplace and start controlling your computer immediately.

*Alternative for power users (Self-hosted):*

```bash
uvx langbot@latest
```

### Step 2: Configure Chat Platform

Follow the documentation to configure your **Telegram bot**, **WeChat bot**, or **Discord bot**.

### Step 3: Install LangTARS

Search for **LangTARS** in the **plugin marketplace** and install it.

### Step 4: Start Chatting

```
!tars Hello, tell me what you can do
```

> 📱 **Recommendation**: Use it on Telegram or Discord for the best interactive experience!

***

## 🎮 Common Commands

| Command                    | Function               |
| -------------------------- | ---------------------- |
| `!tars <Task Description>` | Execute a task         |
| `!tars stop`               | Stop the current task  |
| `!tars what`               | Check execution status |
| `!tars reset`              | Reset the conversation |
| `!tars help`               | Show help              |

***

## 🌟 Project Information

| Item          | Information                                                                |
| ------------- | -------------------------------------------------------------------------- |
| **GitHub**    | [github.com/langbot-app/LangTARS](https://github.com/langbot-app/LangTARS) |
| **Language**  | Python 100%                                                                |
| **License**   | CC BY-NC-ND 4.0                                                            |
| **Platforms** | macOS / Windows / Linux                                                    |

***

## 🔗 Related Links

- 📖 **LangBot Documentation**: [langbot.app/docs](https://langbot.app/docs/en/insight/guide.md)
- 💬 **Issue Feedback**: [GitHub Issues](https://github.com/langbot-app/LangTARS/issues)
- ⭐ **Support with a Star**: [GitHub](https://github.com/langbot-app/LangTARS)

***

## 🎉 Deploy LangBot and Experience LangTARS!

**Let AI be your loyal digital assistant, just like TARS.**

> 🚀 **Fastest way to start:** Use [LangBot Cloud](https://cloud.langbot.app) — deploy your LangBot instance in one click, no server needed! Install LangTARS from the plugin marketplace and start controlling your computer immediately.

*Alternative for power users (Self-hosted):*

```bash
uvx langbot@latest
```

---

# How I Built a Multi-Platform AI Chatbot with n8n and LangBot

Source: https://langbot.app/docs/en/articles/n8n-multi-platform-ai-chatbot

How I Built a Multi-Platform AI Chatbot with n8n and LangBot

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/n8n-multi-platform-ai-chatbot).

Published 2025-12-03 · Author: LangBot Team

![How I Built a Multi-Platform AI Chatbot with n8n and LangBot](https://langbot.app/docs/images/articles/source/images/covers/n8n.png)

Connecting n8n's visual workflow automation with LangBot's multi-platform bot framework creates a powerful, code-free way to deploy AI chatbots across QQ, WeChat, Discord, Telegram, Slack, and more. This tutorial shows you how to integrate these tools in minutes.

## What You'll Need

- Python 3.8+ installed
- Node.js 18+ installed
- npm or npx available
- 15 minutes of your time

## Deploy LangBot in 3 Commands

LangBot is a production-ready bot framework that connects to multiple messaging platforms and AI services including Dify, FastGPT, Coze, OpenAI, Claude, and Gemini. Deploy it instantly:

```bash
cd your-workspace
mkdir -p langbot-instance && cd langbot-instance
uvx langbot@latest
```

On first launch, LangBot initializes automatically. Open `http://127.0.0.1:5300` in your browser.

![LangBot initialization screen](https://langbot.app/docs/images/articles/external/70ee40a6d232-01-langbot-initialization.png)

Register your admin account when prompted. You'll land on the dashboard where you can manage bots, models, pipelines, and integrations.

![LangBot dashboard](https://langbot.app/docs/images/articles/external/4f1f5c28fbfc-03-langbot-dashboard.png)

## Set Up n8n Workflow Automation

n8n is an open-source automation platform with 400+ integrations and powerful AI capabilities. Launch it locally:

```bash
cd your-workspace
mkdir -p n8n-data
export N8N_USER_FOLDER=$(pwd)/n8n-data
npx n8n
```

Visit `http://127.0.0.1:5678` and create your owner account.

![n8n initial setup](https://langbot.app/docs/images/articles/external/12d0e04600c5-05-n8n-setup.png)

## Build Your AI Workflow

Create a new workflow in n8n. You'll need two essential nodes:

![n8n workflow editor](https://langbot.app/docs/images/articles/external/e36d04ca4a5b-07-n8n-workflow-editor.png)

### Add the Webhook Trigger

Click "+" on the canvas and add a **Webhook** node. Configure it:

- **HTTP Method**: POST
- **Response Mode**: Streaming (enables real-time chat responses)
- **Authentication**: None (adjust for production)

![Webhook node configuration](https://langbot.app/docs/images/articles/external/03443176ae5c-08-n8n-webhook-node.png)

### Add the AI Agent

Press Tab, navigate to the "AI" category, and select **AI Agent**.

**Configure the Chat Model**: Click "Chat Model" and choose "OpenAI Chat Model". Add your credentials:

- **API Key**: Your OpenAI API key (or compatible service key)
- **Base URL**: For OpenAI alternatives like Claude, Gemini, or local models, update to your provider's endpoint

**Critical Step - Fix the Prompt Source**: By default, the AI Agent expects a Chat Trigger node, which won't work with webhooks. Here's how to fix it:

1. Find "Source for Prompt (User Message)" in the AI Agent settings
2. Change from "Connected Chat Trigger Node" to "Define below"
3. Switch to "Expression" mode
4. Enter: `{{ $json.body }}`

This expression pulls the user's message from the webhook request body.

![Configured webhook with AI Agent](https://langbot.app/docs/images/articles/external/621f3d526678-09-n8n-webhook-configured.png)

### Activate and Get Your Webhook URL

Save the workflow and toggle the activation switch (top-right). Switch to the "Production URL" tab and copy the webhook URL:

```
http://localhost:5678/webhook/{your-webhook-id}
```

## Connect LangBot to n8n

Back in the LangBot dashboard, navigate to **Pipelines** and click the default "ChatPipeline".

![LangBot pipelines page](https://langbot.app/docs/images/articles/external/ef2b2f83bd16-04-langbot-pipelines.png)

Switch to the **AI** tab and select "n8n Workflow API" from the Runner dropdown. Configure:

- **Webhook URL**: Paste your n8n production webhook URL
- **Authentication Type**: None (match your n8n webhook settings)
- **Timeout**: 120 seconds
- **Output Key**: response

Click **Save**.

## Test It Out

In the Pipeline editor, click "Debug Chat" on the left sidebar. Send a test message like "What is LangBot?"

If everything works, you'll see LangBot send the message to n8n, where the AI Agent processes it and streams back a response.

## Troubleshooting

**Error: "Expected to find the prompt in an input field called 'chatInput'"**

This means the AI Agent is still configured for a Chat Trigger node. Fix it:

1. Open the AI Agent configuration
2. Set "Source for Prompt (User Message)" to "Define below"
3. Switch to Expression mode
4. Enter: `{{ $json.body }}`

**Test Your Webhook Directly**

Verify the webhook works with curl:

```bash
curl -X POST http://localhost:5678/webhook/your-webhook-id \
  -H "Content-Type: application/json" \
  -d '{"body": "Hello, can you introduce yourself?"}'
```

You should receive streaming JSON with the AI's response.

## How the Integration Works

Here's the complete flow:

1. User sends a message via QQ, WeChat, Discord, Telegram, Slack, LINE, or any LangBot-supported platform
2. LangBot's Pipeline receives the message and calls the n8n Workflow API
3. n8n's Webhook node captures the request and passes it to the AI Agent
4. The AI Agent uses OpenAI, Claude, Gemini, or your configured LLM to generate a response
5. n8n streams the response back to LangBot
6. LangBot delivers the response to the user on their original platform

## Why This Combination Works

**LangBot + n8n** unlocks powerful capabilities:

1. **No-Code AI Logic**: Design conversation flows visually in n8n without touching code
2. **Multi-Platform Reach**: Deploy the same AI across QQ, WeChat, Discord, Telegram, Slack, LINE, DingTalk, and Lark simultaneously
3. **Flexible AI Models**: Swap between OpenAI GPT, Anthropic Claude, Google Gemini, Coze, Dify, local models, and more
4. **Rich Integrations**: Connect n8n's 400+ integrations - databases, APIs, Notion, Airtable, Google Sheets, Slack, and beyond
5. **Tool-Calling Agents**: AI Agent can trigger n8n tools like database queries, API calls, or custom functions
6. **Workflow Extensions**: Add preprocessing, content moderation, logging, or custom business logic

**Perfect For**:

- Enterprise customer support bots
- Knowledge base Q\&A systems
- Multi-platform community management
- Task automation assistants
- Unified chat interfaces for teams

## Next Steps

Extend your bot further:

- Integrate Dify or FastGPT for advanced RAG (retrieval-augmented generation)
- Add vector database nodes (Pinecone, Qdrant, Weaviate) for knowledge retrieval
- Connect business APIs for real-time data
- Implement conversation memory and context tracking
- Add content filtering and moderation workflows
- Use Langflow or Coze for additional AI orchestration

This integration gives you the flexibility of code-based AI frameworks like LangChain with the simplicity of visual workflow builders - all while reaching users across every major messaging platform.

Ready to deploy your multi-platform AI assistant? Start with LangBot and n8n today.

---

# Introducing the LangBot Blog

Source: https://langbot.app/docs/en/articles/welcome

Welcome to the official LangBot blog. Stay up to date with product updates, new features, and milestones.

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/welcome).

Published 2026-02-17 · Author: LangBot Team

![LangBot Blog](https://langbot.app/docs/images/articles/source/images/covers/welcome.png)

We're excited to launch the official LangBot blog! This is where we'll share product updates, new features, milestones, and insights from the LangBot team.

## What is LangBot?

LangBot is an open-source LLM-native instant messaging bot platform. It supports multiple messaging platforms and model providers, with integrations for Dify, Alibaba Cloud Bailian, and other LLMOps platforms. LangBot also provides a WebUI for quick deployment and management.

## What to Expect

On this blog, you'll find:

- **Release Notes** - Detailed breakdowns of each new version
- **Feature Spotlights** - Deep dives into new capabilities
- **Milestones** - Project growth and community achievements
- **Guides & Tips** - Best practices for getting the most out of LangBot

## Stay Connected

- [GitHub](https://github.com/langbot-app/LangBot) - Star us and follow development
- [Documentation](https://langbot.app/docs/en/insight/guide.md) - Full guides and API reference
- [LangBot Home](https://langbot.app) - Main website

Stay tuned for more updates!

---

# Command

Source: https://langbot.app/docs/en/deploy/command

LangBot command-line reference: manage your AI bot instance, configuration, and runtime from the terminal.

LangBot will regard messages starting with `!` as commands. Official provides [`EssentialCommands` plugin](https://space.langbot.app/market?author=langbot-team\&plugin=EssentialCommands), which includes commonly used commands.

You can also develop your own command plugin, please refer to [Command Plugin Development](https://langbot.app/docs/en/plugin/dev/components/command.md).

---

# Docker Deployment

Source: https://langbot.app/docs/en/deploy/langbot/docker

Deploy LangBot with Docker Compose on Windows, Linux, or macOS.

## 1. Prepare your environment

- Install Git.
- **Windows / macOS**: install and start Docker Desktop.
- **Linux**: install Docker and Docker Compose.

## 2. Download the project

Choose a regular directory that you can write to. On Linux, avoid system directories such as `/root` and `/etc`; we recommend a location under `/opt` so sandbox features are not blocked by security rules.

Open a terminal in the directory where you want to store the project (PowerShell works on Windows), then run each line:

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
```

### Mainland China: change the image source before startup (optional)

If Docker Hub downloads are slow, edit `LangBot/docker/docker-compose.yaml` first. Replace every occurrence of `rockchin/langbot:latest` with:

```text
docker.langbot.app/langbot-public/rockchin/langbot:latest
```

Save the file before starting. No other configuration changes are needed.

## 3. Start LangBot

> info:
>
> On a server, use a firewall to restrict dashboard and runtime ports to trusted sources only.

In the same terminal, run:

```bash
docker compose --profile all up -d
```

The first startup downloads the container images. On Windows / macOS, keep Docker Desktop running.

## 4. Open the dashboard

- **Local installation**: open `http://localhost:5300`.
- **Server installation**: open `http://YOUR_SERVER_IP:5300` and make sure the firewall allows your device to access this port.

Follow the on-screen initialization steps, then add a [model](https://langbot.app/docs/en/usage/models/readme.md) and a [bot](https://langbot.app/docs/en/usage/platforms/readme.md).

## Beta releases (optional)

To try a beta instead of the stable setup above, download the [dev/4.11.x Compose file](https://raw.githubusercontent.com/langbot-app/LangBot/dev/4.11.x/docker/docker-compose.yaml) as `compose.yaml` in a separate writable directory. Manually change **every** `rockchin/langbot` image to `rockchin/langbot:beta`: Core (`langbot`), plugin runtime (`langbot_plugin_runtime`), and Box (`langbot_box`, when present). The `beta` tag is updated with every beta release. From that directory, start or update with:

```bash
docker compose --profile all pull
docker compose --profile all up -d
```

---

# Kubernetes Deployment

Source: https://langbot.app/docs/en/deploy/langbot/kubernetes

Deploy LangBot on Kubernetes for scalable, production-grade AI bot hosting across messaging platforms.

> warning:
>
> Before you start, you should be familiar with:
>
> - Basic Kubernetes usage (`kubectl`, Namespace, Deployment, Service, PVC)
> - How to configure inter-container networking and persistent storage

The LangBot repository ships a ready-to-use Kubernetes manifest at [`docker/kubernetes.yaml`](https://github.com/langbot-app/LangBot/blob/master/docker/kubernetes.yaml). This page is the deployment guide for that manifest, focusing on the **Box sandbox runtime** under Kubernetes — the part that differs most from the Docker Compose deployment.

## Components

The manifest creates the following components in the `langbot` namespace:

| Component                | Description                    | Ports            |
| ------------------------ | ------------------------------ | ---------------- |
| `langbot`                | Main app (WebUI + webhooks)    | 5300 / 2280-2290 |
| `langbot-plugin-runtime` | Plugin runtime                 | 5400             |
| `langbot-box`            | Box sandbox runtime (optional) | 5410             |

Persistent storage: three PVCs (`langbot-data`, `langbot-plugins`, `langbot-plugin-runtime-data`). The Box workspace root uses a node `hostPath` (`/app/data/box`) rather than a PVC.

## Quick Start

```bash
# Clone the repository
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker

# Deploy all components
kubectl apply -f kubernetes.yaml

# Check status
kubectl get all -n langbot
```

Access the WebUI via port-forward:

```bash
kubectl port-forward -n langbot svc/langbot 5300:5300
# Visit http://localhost:5300
```

For production, expose via Ingress + TLS (the manifest already includes commented Ingress / LoadBalancer / NodePort examples — uncomment as needed).

### Using SeekDB

The official image already includes the optional SeekDB dependencies, so no
dedicated image or additional build argument is required. Set `vdb.use` to
`seekdb` to enable it, or keep the default `chroma` when it is not needed.

## Box Sandbox Runtime

`langbot-box` provides the code-sandbox capability backing the sandbox tools (`exec` / `read` / `write` / `edit` / `glob` / `grep`), the skill `activate` tool and skill add/edit, and stdio-mode MCP servers. It is **optional**: without it, LangBot still runs and the dashboard / skills list stay visible (read-only), but those features are disabled — in that case set `BOX__ENABLED=false` on `langbot`.

### How it works & the key constraint

The official LangBot image ships **only the Docker CLI** (no dockerd, no nsjail). The Box runtime therefore creates sandbox containers by talking to the node's Docker daemon over the mounted socket (`/var/run/docker.sock`) — it does not run dockerd inside the Pod.

This imposes a **key constraint**: the daemon that actually creates sandbox containers is the **node's Docker daemon**, which resolves bind-mount paths against the **node filesystem**. So the Box workspace root must be the **same absolute path** in all three places:

1. The actual path on the node
2. The mount path inside the `langbot-box` container
3. The mount path inside every sandbox container it spawns

This is exactly why the manifest uses a `hostPath` (fixed at `/app/data/box`) instead of a regular PVC: a PVC path only exists inside the Pod's mount namespace, which the node's dockerd cannot see. `langbot` and `langbot-box` are also pinned to the **same node** via `podAffinity` so they share this hostPath.

> warning:
>
> Because it relies on hostPath + same-node affinity, `langbot` does not support multi-replica horizontal scaling (same limitation as `ReadWriteOnce` PVCs). High availability requires a different architecture.

### Connection & configuration

- `langbot` connects to the Box runtime over WebSocket, using the endpoint from the ConfigMap: `BOX__RUNTIME__ENDPOINT: ws://langbot-box:5410`.

> info:
>
> The in-container default hostname is `langbot_box` (with an underscore), which is **not** a valid Kubernetes DNS name. The endpoint must therefore be set **explicitly** to the valid Service name `langbot-box` — you cannot rely on the in-container default.

- The Box runtime does **not** read its own `box.local.*` / `BOX__*` environment variables; its configuration is read from `BOX__LOCAL__*` by `langbot` and pushed via the INIT RPC. So `BOX__LOCAL__HOST_ROOT` / `DEFAULT_WORKSPACE` / `SKILLS_ROOT` / `ALLOWED_MOUNT_ROOTS` are set on the `langbot` Deployment, where `HOST_ROOT` must match the `box-root` mountPath on both sides (`/app/data/box`).

### Security note

Mounting the node's Docker socket grants the Box runtime (and any code executed in the sandbox) effective root on the node. Only deploy Box on nodes you trust for this workload — ideally a dedicated node pool isolated with taints/tolerations. For a stronger isolation boundary, switch `box.backend` to `e2b` (set `E2B_API_KEY`) and drop the `docker.sock` mount + hostPath. See [Sandbox configuration](https://langbot.app/docs/en/usage/sandbox/config.md).

### Verify Box is ready

```bash
# Box runtime logs (should show the selected backend, e.g. "using backend: docker")
kubectl logs -n langbot -l app=langbot-box -f

# Confirm langbot connected to the Box runtime
kubectl logs -n langbot -l app=langbot | grep -i "box runtime"
```

## When you don't need the sandbox

If you do not need the sandbox, remove the `langbot-box` Deployment / Service from the manifest and set `BOX__ENABLED=false` on the `langbot` Deployment to avoid connection-failure warnings in the logs.

## Further reading

- [Docker Deployment](https://langbot.app/docs/en/deploy/langbot/docker.md)
- [Sandbox docs](https://langbot.app/docs/en/usage/sandbox/readme.md) and [Sandbox configuration](https://langbot.app/docs/en/usage/sandbox/config.md)
- [Skills docs](https://langbot.app/docs/en/usage/skills/readme.md)
- Manifest source file: [`docker/kubernetes.yaml`](https://github.com/langbot-app/LangBot/blob/master/docker/kubernetes.yaml) in the repo

---

# Manual Deployment

Source: https://langbot.app/docs/en/deploy/langbot/manual

Manually deploy LangBot from source. Step-by-step setup for the open-source AI bot platform on Linux, Windows and macOS.

## Installing the Main Program

1. Go to the [Release](https://github.com/langbot-app/LangBot/releases) page to download the latest version of the zip package (recommended) `langbot-xxx-all.zip` (do not download Source Code as it does not include WebUI). Extract it and open a command line (terminal) in the extracted directory.

![Download Release](https://langbot.app/docs/images/zh/deploy/langbot/manual/dl_release.png)

2. Install dependencies

We use [uv](https://docs.astral.sh/uv/) to manage dependencies.

```bash
pip install uv
uv sync
```

The default installation does not include optional SeekDB support. If you need
the SeekDB vector store or built-in embedding model, use:

```bash
uv sync --extra seekdb
```

Embedded-mode platform support depends on the available `pylibseekdb` wheels;
Apple Silicon currently requires macOS 15 or later. All other LangBot features
can use the default `uv sync` installation.

3. Run the main program once to generate configuration files

```bash
uv run main.py
```

You will see the following message:

```
 _                   ___      _   
| |   __ _ _ _  __ _| _ ) ___| |_ 
| |__/ _` | ' \/ _` | _ \/ _ \  _|
|____\__,_|_||_\__, |___/\___/\__|
               |___/              

⭐️Open Source: https://github.com/langbot-app/LangBot
📖Documentation: https://langbot.app/docs

The following files do not exist and have been automatically generated. Please modify the configuration files as needed and restart:
- data/config.yaml
...
```

You can now use Ctrl+C to exit the program and continue to the [Configure Bots](https://langbot.app/docs/en/usage/platforms/readme.md) page.

---

# 1Panel Deployment

Source: https://langbot.app/docs/en/deploy/langbot/one-click/1panel

One-click LangBot deployment with 1Panel. Install the open-source AI chatbot platform without touching the command line.

Deploy LangBot with one click using [1Panel](https://www.bt.cn/new/download.html?r=dk_LangBot).

## Install 1Panel

> Recommended server systems (from 1Panel): Debian 12, Ubuntu 22, etc.

This article assumes that the server has a public IPv4 address by default. If you are using a home machine without a public IP, you can access the relevant pages through the internal network described below.

Visit [1Panel](https://www.bt.cn/new/download.html?r=dk_LangBot) and use the Linux panel installation script provided officially by 1Panel. Select the corresponding script according to your operating system.

![Install 1Panel](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_install_01.png)

Copy the corresponding script, paste it into the server, and execute it.

After waiting for a period of time, the installation of 1Panel will be completed.

Then copy the `External Address` and open it in a browser.

## Install LangBot

Open the `App Store`, select the `AI` category, and click to install LangBot.

![Install LangBot ](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_langbot_01.png)

Check the box for `External Port Access` and click Confirm.

![Install LangBot ](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_langbot_02.png)

Wait for a moment, and the installation will be completed.

Click `Containers` on the left side, then select the `Containers` category, and you will see the LangBot container bar.

![View LangBot Container Information](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_langbot_03.png)

Copy the public IP address of the server, for example, `http://xxx.xxx.xxx.xxx:5300` (where xxx.xxx.xxx.xxx is the IP address of the server where 1Panel is located, and 5300 is the port number).

Open the address, enter the administrator email and password, then click Initialize.

After that, you can configure LangBot in the visual interface.

Next, please continue to read the [Configure Messaging Platforms](https://langbot.app/docs/en/usage/platforms/readme.md) page.

---

# aaPanel Deployment

Source: https://langbot.app/docs/en/deploy/langbot/one-click/bt

One-click LangBot deployment with aaPanel (BT Panel). Install the open-source AI bot platform through a web control panel.

Deploy LangBot with one click using [aaPanel](https://www.bt.cn/new/download.html?r=dk_LangBot).

> warning:
>
> If you already have aaPanel installed, please update to version **9.2.0** or higher

## Installing aaPanel

> Recommended server systems (from aaPanel): Debian 12, Ubuntu 22, etc.
>
> This document assumes you have a server with a public IPv4 address. If you're using a home machine without a public IP, you can access the relevant pages through the internal network mentioned below.

Open [aaPanel](https://www.bt.cn/new/download.html?r=dk_LangBot), use the Linux panel installation script provided by aaPanel official, and select the corresponding script based on your system.

![Install aaPanel](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_install_01.png)

Copy the corresponding script and paste it into your server to execute.

## Installing LangBot

After waiting for a while, aaPanel installation will be complete.

You'll see a message similar to this, copy the external panel address and open it in your browser.

![aaPanel Access Address](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_install_02.png)

When you first open it, you should see a popup for `Recommended Installation Suite`. You can skip this by closing it.

Then click on `docker` in the sidebar. If it's your first time, you'll be prompted to install Docker and Docker Compose services. Click "Install Now" if prompted, or ignore if already installed.

Then go to `Docker -> App Store`, search for `LangBot` (note the case sensitivity), click `Install`, and use the default configuration.

After a short wait, you'll see a container named `langbot_XXXX` showing as `Running`.

![Create LangBot Container](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_langbot_01.png)

Click the red circle in the image above to view the running logs.

![View LangBot Container Logs](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_langbot_02.png)

You can see the external and internal access paths for the WebUI configuration page (visual configuration page). Copy the public address, for example `http://xxx.xxx.xxx.xxx:5300` (where xxx.xxx.xxx.xxx is your aaPanel IP, and 5300 is the port number, which may vary as shown in the image).

After opening it, enter your admin email and password, then click initialize.

You can then proceed with configuration in the visual interface.

If you prefer to directly modify JSON configuration files, you can look at the local mapping directory shown in the image above. Go to the installation directory, where the `data` folder is used to store configuration files, and the `plugins` folder is used for plugin-related files.

Next, please continue reading the [Configure Message Platform](https://langbot.app/docs/en/usage/platforms/readme.md) page.

---

# Deploy with Package Manager

Source: https://langbot.app/docs/en/deploy/langbot/package

Deploy LangBot with a package manager (uv/uvx). Quick install for the open-source LLM chatbot platform.

> info:
>
> Supports Windows, Linux, Mac OS, etc. Recommended for testing environments and personal use scenarios; production-level environments please use [Docker Deployment](https://langbot.app/docs/en/deploy/langbot/docker.md).

LangBot is packaged and released to PyPI. Please install [uv](https://docs.astral.sh/uv/getting-started/installation/), and then run the following command in an empty directory:

```bash
uvx langbot@latest
```

This will set the current directory as the working directory, and you can access `http://localhost:5300` to start using it.

## Beta releases (optional)

To try Beta 3 instead, use the command below. `--prerelease=allow` also permits prereleases of dependencies; `--refresh` refreshes cached package data.

```bash
uvx --prerelease=allow --refresh langbot==4.11.0b3
```

## Optional SeekDB support

The default installation uses Chroma and does not include the SeekDB Python
SDK or native components. Install the `seekdb` extra only when you want to use
SeekDB as the vector store or use its built-in embedding model:

```bash
uvx --from 'langbot[seekdb]@latest' langbot
```

SeekDB embedded mode also requires a compatible `pylibseekdb` wheel. Apple
Silicon currently requires macOS 15 or later; follow
[oceanbase/seekdb#1324](https://github.com/oceanbase/seekdb/issues/1324) for the
macOS 14 ARM64 support plan. Because of the current `pyseekdb` package
metadata, the extra also fails to resolve on macOS 14 ARM64 for server-only
use. These platform limits do not affect LangBot when SeekDB is not installed.

---

# System Environment Settings

Source: https://langbot.app/docs/en/deploy/settings

Complete reference for LangBot config.yaml: API, concurrency, databases, storage, plugins, MCP, monitoring, and Box.

LangBot runtime configuration lives in `data/config.yaml`. The first startup generates it from the default template. The example below is kept aligned with [`src/langbot/templates/config.yaml`](https://github.com/langbot-app/LangBot/blob/master/src/langbot/templates/config.yaml).

> info:
>
> Most self-hosted deployments only need to change public URLs, databases/vector stores, object storage, and Box Runtime. Keep capacity and Cloud safety limits at their defaults unless you understand their operational impact.

## Complete default configuration

```yaml
api:
    port: 5300
    webhook_prefix: 'http://127.0.0.1:5300'
    extra_webhook_prefix: ''
    # Canonical browser origin when WebUI and API use different origins in
    # development (for example http://localhost:3000). Production bundled UI
    # may leave this empty when webhook_prefix already has the browser origin.
    # OAuth redirects trust only these server-side values, never request Host
    # or Origin headers.
    webui_url: ''
    # Global API key for the HTTP service API and the MCP server. When set to a
    # non-empty string, this key is accepted anywhere a web-UI-created API key is
    # accepted (X-API-Key header or "Authorization: Bearer <key>"), WITHOUT any
    # login session and without a database record. Leave empty to disable.
    # Keep this value secret; only enable it on trusted/internal deployments.
    global_api_key: ''
workspace:
    invitations:
        # Public WebUI origin used to build invitation links. Leave empty to
        # use api.webui_url, then api.webhook_prefix. Set via
        # WORKSPACE__INVITATIONS__PUBLIC_WEB_URL in container deployments.
        public_web_url: ''
        email:
            # Optional invitation email delivery. Empty provider keeps
            # invitations link-only. Supported: resend, smtp.
            provider: ''
            from: ''
            timeout_seconds: 10
            resend:
                api_url: 'https://api.resend.com/emails'
                # Secret. Set via WORKSPACE__INVITATIONS__EMAIL__RESEND__API_KEY.
                api_key: ''
            smtp:
                host: ''
                port: 587
                username: ''
                # Secret. Set via WORKSPACE__INVITATIONS__EMAIL__SMTP__PASSWORD.
                password: ''
                starttls: true
                ssl: false
command:
    enable: true
    prefix:
    - '!'
    - ！
    privilege: {}
concurrency:
    pipeline: 20
    session: 1
    # Hard admission limits for queued + running pipeline queries.
    pending_queries: 1000
    pending_queries_per_workspace: 100
webhooks:
    # Bound database materialization and per-message outbound fan-out.
    # Existing rows above this limit remain deletable through the management
    # API, but only this many enabled destinations are dispatched.
    # Supports WEBHOOKS__MAX_PER_WORKSPACE (hard cap: 64).
    max_per_workspace: 16
    # Instance-wide request admission. Delivery fails open when every slot is
    # occupied instead of retaining an unbounded queue of webhook tasks.
    # Supports WEBHOOKS__MAX_INFLIGHT_REQUESTS (hard cap: 128).
    max_inflight_requests: 16
cloud:
    # Operational safety ceilings for the one logical Cloud instance. These
    # are not subscription entitlements. An authoritative directory update
    # that would exceed them is rejected atomically rather than truncated.
    directory:
        # Tune downward from the measured production capacity curve. Core has
        # an absolute safety ceiling of 5,000 active Workspaces.
        max_active_workspaces: 1000
        # Full snapshots contain current Workspaces only. Archived tombstones
        # are delivered through bounded per-Workspace deltas.
        max_snapshot_workspaces: 1000
        # Aggregate memberships accepted in one signed snapshot or delta.
        max_snapshot_memberships: 20000
        # Signed control-plane envelope buffered by the closed adapter before
        # JSON/JWS verification (32 MiB; absolute maximum 64 MiB).
        max_response_bytes: 33554432
proxy:
    http: ''
    https: ''
system:
    instance_id: ''
    edition: community
    recovery_key: ''
    allow_modify_login_info: true
    disabled_adapters: []
    blocking_executor:
        # All asyncio.to_thread work shares this process-wide bounded pool.
        # Both running threads and queued calls are capped to prevent tenant
        # bursts from creating an unbounded queue of retained request objects.
        max_workers: 8
        max_pending: 128
        # One trusted Workspace can occupy at most this many running + queued
        # slots. This must not exceed half of max_workers.
        max_inflight_per_scope: 4
    # Public outbound IP addresses of this LangBot deployment. Some platforms
    # (e.g. WeCom, WeChat Official Account, QQ Official API) require the
    # caller's IPs to be added to their trusted-IP / IP-whitelist settings.
    # When set, the web UI shows these IPs on the bot config form of such
    # adapters. Also settable via the SYSTEM__OUTBOUND_IPS env var
    # (comma-separated). Empty list = hidden in the web UI.
    outbound_ips: []
    limitation:
        max_bots: -1
        max_pipelines: -1
        max_extensions: -1
        max_knowledge_bases: -1
        # When set to a non-empty string, every pipeline is forced to use this
        # Box sandbox-scope template regardless of its own configuration, and
        # the per-pipeline "Sandbox Scope" selector is locked in the web UI.
        # Used by SaaS deployments to confine a tenant to a single shared
        # sandbox (set to '{global}'). Empty string = no restriction.
        force_box_session_id_template: ''
    task_retention:
        # Keep at most this many completed async task records in memory
        completed_limit: 200
        # Bound progress output retained by one task, including running tasks.
        max_log_chars: 200000
        # Protect the shared process from user-triggered operation storms.
        max_active_user_tasks: 256
        max_active_user_tasks_per_workspace: 8
    session_retention:
        # Process-local conversation sessions are a cache, not durable history.
        max_entries: 2000
        max_entries_per_workspace: 200
        idle_ttl_seconds: 86400
        max_conversations_per_session: 20
        max_messages_per_conversation: 100
    websocket_retention:
        # Bound live browser sockets and per-Workspace fan-out in the shared process.
        max_connections: 1024
        max_connections_per_workspace: 32
        # Idle proxy runtimes are evicted when this process-local cache fills.
        max_workspace_proxies: 1024
        max_conversations_per_workspace: 200
        max_messages_per_conversation: 100
        conversation_idle_ttl_seconds: 86400
        send_queue_size: 100
    response_limits:
        # Defense in depth for tenant-configured upstream providers.
        max_generated_chars: 1048576
        max_stream_chunks: 100000
    jwt:
        expire: 604800
        secret: ''
database:
    use: sqlite
    sqlite:
        path: 'data/langbot.db'
    postgresql:
        # Optional SQLAlchemy URL (postgresql[+asyncpg]://...). When set, it
        # overrides the structured fields and preserves TLS/query options.
        url: ''
        host: '127.0.0.1'
        port: 5432
        user: 'postgres'
        password: 'postgres'
        database: 'postgres'
        # One bounded pool is shared by business data and Cloud pgvector.
        pool_size: 10
        max_overflow: 10
        pool_timeout_seconds: 30
        pool_recycle_seconds: 1800
        # Applied only to Cloud runtime connections. The one-shot release
        # migration uses its operator connection without these short limits.
        statement_timeout_ms: 60000
        lock_timeout_ms: 5000
        idle_in_transaction_session_timeout_ms: 60000
    cloud_migration:
        # `langbot migrate --cloud` reads an operator-only PostgreSQL DSN from
        # this environment variable. The operator role must differ from the
        # runtime role above; never put its password in this file or CLI args.
        operator_dsn_env: 'LANGBOT_CLOUD_MIGRATION_DSN'
vdb:
    use: chroma
    # Bound process-local collection/index handles across all Workspaces.
    runtime_cache_limit: 1024
    qdrant:
        url: ''
        host: localhost
        port: 6333
        api_key: ''
    # SeekDB is optional. Source/package deployments need the `seekdb` extra.
    # The official Docker/Kubernetes image already includes it.
    # Embedded-mode platform support depends on the native pylibseekdb wheels.
    seekdb:
        mode: embedded  # 'embedded' or 'server'
        # Embedded mode options:
        path: './data/seekdb'
        database: 'langbot'
        # Server mode options (used when mode='server'):
        host: 'localhost'
        port: 2881
        user: 'root'
        password: ''
        tenant: ''  # Optional, for OceanBase server
    milvus:
        uri: 'http://127.0.0.1:19530'
        token: ''
        db_name: ''
    pgvector:
        # SaaS/shared-schema deployments reuse database.postgresql. OSS can
        # keep this false when deliberately using an external pgvector DB.
        use_business_database: false
        # Release migrations create one partial ANN index per enabled value.
        allowed_dimensions: [384, 512, 768, 1024, 1536]
        host: '127.0.0.1'
        port: 5433
        database: 'langbot'
        user: 'postgres'
        password: 'postgres'
    valkey_search:
        host: 'localhost'
        port: 6379            # integration tests use 6380 -> valkey/valkey-bundle:9.1.0
        db: 0
        password: ''          # optional (toB auth)
        username: ''          # optional (ACL user, toB)
        tls: false            # optional (toB/SaaS)
        index_algorithm: 'HNSW'   # HNSW | FLAT
        distance_metric: 'COSINE' # COSINE | L2 | IP
        request_timeout: 5000     # per-request timeout in ms (glide default 250ms is too low for KNN)
storage:
    use: local
    # Bound every object materialized into Core memory. Built-in Local/S3
    # providers enforce this while reading (hard cap: 64 MiB).
    max_object_read_bytes: 10485760
    cleanup:
        # Enable periodic cleanup of local/S3 uploaded files and old log files
        enabled: true
        # Cleanup check interval in hours
        check_interval_hours: 1
        # Root-level uploaded files older than this will be deleted
        uploaded_file_retention_days: 7
        # LangBot log files older than this many days will be deleted
        log_retention_days: 3
        # Bound per-Workspace file cleanup and diagnostic candidate lists.
        # Supports STORAGE__CLEANUP__MAX_FILES_PER_RUN (hard cap: 10000).
        max_files_per_run: 1000
    s3:
        endpoint_url: ''
        access_key_id: ''
        secret_access_key: ''
        region: 'us-east-1'
        bucket: 'langbot-storage'
        # boto3 is synchronous; bound the number of operations delegated to
        # worker threads so an S3 slowdown cannot saturate the process.
        max_concurrency: 16
plugin:
    enable: true
    runtime_ws_url: 'ws://langbot_plugin_runtime:5400/control/ws'
    enable_marketplace: true
    display_plugin_debug_url: 'ws://localhost:5401/plugin/debug/ws'
    worker:
        # Instance-wide maximum for every plugin installation. Plugin
        # manifests cannot raise or override these limits.
        max_cpus: 1.0
        max_memory_mb: 512
        max_pids: 128
        max_open_files: 256
        max_file_size_mb: 512
        # Instance-wide admission budgets. The effective worker count is the
        # lowest of max_workers, max_total_cpus/max_cpus and
        # max_total_memory_mb/max_memory_mb.
        max_workers: 16
        max_total_cpus: 8.0
        max_total_memory_mb: 8192
        # Includes disabled and historical installation fences retained to
        # reject stale desired-state replay.
        max_installations: 10000
        # Restart storms are globally serialized by default. Repeated
        # unexpected exits within the configured window open a Runtime-wide
        # circuit; one half-open probe must remain stable before other
        # installations may restart.
        max_concurrent_restarts: 1
        restart_failure_threshold: 8
        restart_failure_window_seconds: 30.0
        restart_circuit_open_seconds: 60.0
        # Cloud shared Runtime sets this to true and fails closed unless
        # delegated cgroup v2 controllers are available.
        require_hard_limits: false
    binary_storage:
        # Max bytes for a single plugin binary storage value
        max_value_bytes: 10485760
mcp:
    # Bound instance-wide MCP startup and shutdown bursts. Supports
    # MCP__LIFECYCLE_CONCURRENCY and is clamped to a maximum of 128.
    lifecycle_concurrency: 16
    stdio:
        # Independent gate for local stdio MCP transports. Cloud v2 sets
        # MCP__STDIO__ENABLED=false even when Box Runtime is available.
        enabled: true
monitoring:
    query_limits:
        # Maximum records materialized by one paginated monitoring request.
        # Supports MONITORING__QUERY_LIMITS__PAGE_ROWS (hard cap: 5000).
        page_rows: 1000
        # CSV exports are currently assembled in memory. Keep this lower than
        # the historical 100000-row default (hard cap: 50000).
        export_rows: 10000
        # Maximum related records returned by one session/message detail view
        # (hard cap: 10000). Aggregate statistics remain database-computed.
        detail_rows: 2000
        # Token charts are grouped in SQL and return only the newest buckets
        # (hard cap: 10000). Supports an environment variable override.
        timeseries_buckets: 1000
        # Bound high-offset scans that can otherwise monopolize PostgreSQL CPU
        # (hard cap: 10000000).
        max_offset: 1000000
    auto_cleanup:
        # Enable automatic cleanup of expired monitoring records
        enabled: true
        # Retention period in days, records older than this will be deleted
        retention_days: 30
        # Cleanup check interval in hours
        check_interval_hours: 1
        # Number of expired rows to delete per table batch
        delete_batch_size: 1000
        # Prevent one large Workspace backlog from monopolizing PostgreSQL.
        # Supports MONITORING__AUTO_CLEANUP__MAX_BATCHES_PER_TABLE_PER_RUN.
        max_batches_per_table_per_run: 4
box:
    # Master switch for the Box sandbox runtime. When false, LangBot does NOT
    # attempt to connect to a remote Box runtime nor start a local stdio Box
    # subprocess. Disabling Box also disables every feature that depends on it:
    # the native sandbox tools (exec/read/write/edit/glob/grep), the activate
    # skill tool, skill add/edit, and stdio-mode MCP servers. Skills can still
    # be listed read-only and http/sse MCP servers continue to work.
    enabled: true
    backend: 'local'  # 'local' (Docker/nsjail), 'docker', 'nsjail', or 'e2b'. Can be written via BOX__BACKEND.
    runtime:
        # LANGBOT_BOX_CONTROL_TOKEN is optional for OSS external WebSocket
        # runtimes. To protect an exposed endpoint, set the same strong secret
        # in both LangBot and Box. Keep it out of this config file.
        endpoint: ''  # External Box Runtime base URL, e.g. 'ws://127.0.0.1:5410'. Leave empty for local auto-managed runtime.
    limits:
        max_sessions: 64
        max_managed_processes: 64
        max_completed_processes: 256
        # Core scans a Workspace before and after quota-enforced executions.
        # Fail closed instead of repeatedly walking an inode bomb.
        # Supports BOX__LIMITS__MAX_WORKSPACE_ENTRIES (hard cap: 1000000).
        max_workspace_entries: 100000
        # Retained admission fences prevent replay after entitlement expiry or
        # revocation. Fail closed before that monotonic state can grow without
        # bound; Cloud may override this with BOX__LIMITS__MAX_ADMISSION_RECORDS.
        max_admission_records: 100000
        max_rpc_file_bytes: 20971520
    # Cloud v2 overrides these values through the instance config/environment.
    # OSS keeps admission disabled and preserves the existing multi-session
    # local behavior. These limits are Runtime-owned and cannot be relaxed by
    # a pipeline, Workspace entitlement, or tool call.
    admission:
        required: false
        logical_session_id: 'global'
        required_backend: 'nsjail'
        max_sessions: 1
        max_managed_processes: 0
        max_grant_ttl_sec: 300
        max_timeout_sec: 120
        cpus: 1.0
        memory_mb: 512
        pids_limit: 128
        read_only_rootfs: true
        # OSS admission-disabled mode uses 0 for unlimited compatibility.
        # Cloud bootstrap requires a positive hard quota.
        workspace_quota_mb: 0
        readiness_cache_sec: 15
    local:
        profile: 'default'
        image: ''  # Custom local sandbox image. Leave empty to use the profile default.
        host_root: './data/box'  # Base host directory for local workspace mounts. Docker deployments should override this with an absolute host path.
        default_workspace: ''  # Defaults to '<host_root>/default'. Relative paths are resolved under host_root.
        skills_root: 'skills'  # Box-owned skill package directory. Relative paths are resolved under host_root.
        allowed_mount_roots:  # Defaults to ['<host_root>'] when left empty.
            - './data/box'
            - '/tmp'
        workspace_quota_mb: null  # Optional disk quota override (>= 0). null = profile default.
    # Default nsjail cgroup memory limit for each MCP stdio server process, in MB.
    # Node.js MCP servers (npx/bunx) need more memory than Python ones because V8
    # and WebAssembly modules (e.g. undici llhttp) reserve large virtual address
    # space at startup. Setting this too low causes processes to be killed with
    # return_code=137 (OOM kill); the symptom is "Box managed process exited
    # unexpectedly" in the logs.  Raise on machines with ample RAM; lower only if
    # you run exclusively Python (uvx) MCP servers.
    # Can also be set via BOX__DEFAULT_MEMORY_MB. Default: 1536.
    default_memory_mb: 1536
    docker:
        cpu_limit_enabled: true  # When false, Docker sandbox containers are started without --cpus. Memory and PID limits still apply.
    e2b:
        api_key: ''  # Can also be set via E2B_API_KEY env var.
        api_url: ''  # Custom API URL for self-hosted deployments.
        template: ''  # Default template ID (e.g. 'base', 'python-3.11').
space:
    # Space service URL for OAuth and API
    url: 'https://space.langbot.app'
    # Space API URL for model requests (MaaS)
    models_gateway_api_url: 'https://api.langbot.cloud/v1'
    # OAuth authorization page URL (user will be redirected here)
    oauth_authorize_url: 'https://space.langbot.app/auth/authorize'
    disable_models_service: false
    disable_telemetry: false
```

## Configuration groups

### API, WebUI, and invitations

- `api.port` is the HTTP API and WebUI port. `api.webhook_prefix` is the public base URL used to generate platform callback URLs; production deployments normally set it to the HTTPS reverse-proxy origin.
- Set `api.webui_url` when the browser UI and API use different origins. OAuth redirects trust only this server-side value and `webhook_prefix`, never request `Host` or `Origin` headers.
- `api.global_api_key` authenticates the HTTP Service API and built-in MCP server through `X-API-Key` or `Authorization: Bearer`, without a login session or a database-backed `lbk_` key. Empty means disabled.
- `workspace.invitations.public_web_url` controls invitation links and falls back to `api.webui_url`, then `api.webhook_prefix`. Email delivery is optional; choose `resend` or `smtp`, or leave `provider` empty for link-only invitations.

> warning:
>
> Treat the global API key, JWT secret, database credentials, S3 credentials, email-provider secrets, and E2B key as secrets. Prefer environment variables in production, never commit real values, and expose authenticated endpoints only over HTTPS.

### Admission and capacity limits

- `concurrency` bounds running and queued pipeline work globally and per Workspace.
- `webhooks` bounds enabled destinations per Workspace and instance-wide outbound requests. Full request admission fails open rather than retaining an unbounded task queue.
- `cloud.directory` contains operational safety ceilings for one logical Cloud instance, not subscription entitlements. Oversized authoritative directory updates are rejected atomically instead of being truncated. Most self-hosted deployments should keep these defaults.
- `system.blocking_executor`, `task_retention`, `session_retention`, `websocket_retention`, and `response_limits` bound process-local workers, cached records, sockets, and upstream output.
- Values under `system.limitation` are instance limits; `-1` means unlimited. `force_box_session_id_template` is intended for SaaS sandbox confinement and should remain empty for normal self-hosting.

### Databases and vector stores

- `database.use` selects SQLite or PostgreSQL. A non-empty `database.postgresql.url` overrides the structured connection fields and preserves TLS/query options.
- PostgreSQL pool and timeout settings bound shared runtime resources. `database.cloud_migration.operator_dsn_env` names the environment variable containing the operator-only migration DSN; keep that role separate from the runtime role.
- `vdb.use` selects the vector backend. Configure only the selected backend. `runtime_cache_limit` bounds process-local collection/index handles.
- `vdb.use: seekdb` requires `uv sync --extra seekdb` for a source deployment or `uvx --from 'langbot[seekdb]@latest' langbot` for a package deployment. The official Docker/Kubernetes image already includes the dependency and needs no additional build argument.
- `vdb.pgvector.use_business_database` reuses `database.postgresql`; `allowed_dimensions` controls the partial ANN indexes created by release migrations.
- Valkey Search requires a Valkey server with the Search module, such as `valkey/valkey-bundle:9.1.0`.

### Storage, plugins, MCP, and monitoring

- `storage.max_object_read_bytes` caps objects materialized into Core memory. Cleanup limits bound file scans, and `s3.max_concurrency` bounds synchronous boto3 operations delegated to worker threads.
- `plugin.worker` defines hard per-installation and instance-wide budgets. Plugin manifests cannot raise them. Restart-window settings suppress Runtime restart storms.
- `mcp.lifecycle_concurrency` bounds MCP startup/shutdown bursts. `mcp.stdio.enabled` can disable local stdio transports without disabling HTTP/SSE MCP servers.
- Monitoring query and cleanup limits prevent large pages, exports, offsets, or backlogs from monopolizing memory or PostgreSQL.

### Box sandbox

- `box.enabled` is the master switch. Disabling it also disables native sandbox tools, Skill add/edit, and stdio MCP, while read-only Skill listing and HTTP/SSE MCP remain available.
- `box.backend` selects `local`, `docker`, `nsjail`, or `e2b`; `runtime.endpoint` connects an external WebSocket Runtime.
- `box.limits` bounds sessions, processes, workspace scans, retained admission fences, and RPC file size.
- `box.admission` is the Cloud v2 hard-admission policy. OSS defaults to `required: false`; pipelines, Workspace entitlements, and tool calls cannot relax Runtime-owned limits.
- `box.local` controls workspace roots and mount allowlists. In Docker deployments, use an absolute `host_root` that the Box container can mount.
- `box.default_memory_mb` is the default nsjail cgroup limit for each stdio MCP process. Node.js MCP servers usually need more memory than Python servers; too little commonly produces exit code `137`.

### LangBot Space

`space.url`, `models_gateway_api_url`, and `oauth_authorize_url` control Space OAuth/API and MaaS endpoints. The two `disable_*` flags independently disable model service use and telemetry.

## Environment-variable overrides

Convert a nested key to uppercase and join levels with double underscores:

- `API__PORT` → `api.port`
- `WORKSPACE__INVITATIONS__PUBLIC_WEB_URL` → `workspace.invitations.public_web_url`
- `CONCURRENCY__PENDING_QUERIES_PER_WORKSPACE` → `concurrency.pending_queries_per_workspace`
- `DATABASE__POSTGRESQL__POOL_SIZE` → `database.postgresql.pool_size`
- `STORAGE__CLEANUP__MAX_FILES_PER_RUN` → `storage.cleanup.max_files_per_run`
- `PLUGIN__WORKER__MAX_TOTAL_MEMORY_MB` → `plugin.worker.max_total_memory_mb`
- `MCP__STDIO__ENABLED` → `mcp.stdio.enabled`
- `BOX__DEFAULT_MEMORY_MB` → `box.default_memory_mb`

At startup, LangBot applies these overrides and writes the resulting configuration to `data/config.yaml`.

> info:
>
> In Docker deployments, set unified `BOX__*` variables on the `langbot` service. LangBot sends Box configuration to `langbot_box` through INIT RPC; variables set directly on `langbot_box` are not read.

## Optional telemetry

Telemetry is enabled by default and can be disabled.

Set the following in the existing `space` section of `data/config.yaml`, preserve other settings, and restart LangBot:

```yaml
space:
  disable_telemetry: true
```

This switch disables query statistics, heartbeat and execution telemetry, as well as survey fetching. Use an unquoted YAML boolean. To restore the default, set it to `false` and restart.

If `SPACE__DISABLE_TELEMETRY` is set in your deployment, it overrides the file at startup; update or remove it too. Recreate containers when changing their environment. In Cloud, the instance operator controls this setting for every Workspace in the instance. It does not disable the bot or change privacy settings of messaging platforms, model providers or plugins.

### Per-event execution chains

Execution telemetry also reports sampled per-event chains (one inbound platform event from its source through routing and processing to the platform API calls it caused). Tune the sampling in the same `space` section:

```yaml
space:
  execution_trace: sampled    # off | failures | sampled | all
  execution_trace_sample: 20  # with 'sampled': keep every N-th successful chain
```

`failures` keeps only chains that contain a failed, cancelled or timed-out stage. `off` disables chains while window counters continue. WebUI debug runs are always kept and remain flagged as synthetic. Chains share the 30-day retention of execution records.

See [Data Collection Policy](https://langbot.app/docs/en/insight/data-collection-policy.md).

---

# Update LangBot

Source: https://langbot.app/docs/en/deploy/update

Update LangBot to the latest version. Upgrade your self-hosted AI chatbot platform safely with these steps.

## Using Package Manager

Please execute in the directory you deployed LangBot again:

```bash
uvx langbot@latest
```

This command will download and start the latest version of LangBot.

## Using Docker (or one-click deployment based on Docker)

Please execute in the directory you cloned LangBot:

```bash
git pull
```

Please execute in the `docker/` directory:

```bash
docker compose up --force-recreate --pull always -d
```

This command will pull the latest LangBot image and rebuild the container.

> info:
>
> 4.3.0 version changed the content and location of the `docker-compose.yaml` file, if you updated from a previous version, please [redploy according to the documentation](https://langbot.app/docs/en/deploy/langbot/docker.md).

## Manual Deployment

Download the latest release's `langbot-<version>-all.zip` from the Assets section on the [Releases](https://github.com/langbot-app/LangBot/releases) page, extract it to the original deployment directory, and restart.

---

# AI Assistant Context

Source: https://langbot.app/docs/en/develop/agent-context

A single, copy-paste-the-whole-page context for AI coding assistants: LangBot's directory layout, how components are organized, how they connect at runtime, and how to set up the dev environment.

> This page is written for AI coding assistants (Claude Code / Cursor / Copilot / Codex, etc.).:
>
> Copy the **entire content** of this page and paste it to your AI assistant. It will then understand LangBot's overall architecture, how each component is organized, how they connect at runtime, and how to configure the dev environment — without you having to explain it piece by piece.

This page mirrors the `AGENTS.md` (with `CLAUDE.md` as a symlink) at each repository root, and serves as LangBot's "one-page onboarding" for developers and AI assistants.

## Project Overview

LangBot is an open-source, LLM-native instant-messaging bot development platform. It provides an out-of-the-box IM bot development experience with built-in Agent, RAG, MCP and other LLM application capabilities, supports mainstream global IM platforms, and exposes rich APIs for custom development.

LangBot has a comprehensive web frontend — almost every operation can be performed through it.

- **Backend**: Python (`>=3.11,<4.0`), dependencies managed by `uv`; the web framework is Quart (the async flavour of Flask). Both the HTTP API and the pre-built frontend are served by the backend on `http://127.0.0.1:5300`.
- **Frontend**: `web/` is a **Vite + React Router 7 + shadcn/ui + Tailwind CSS** SPA, managed by `pnpm` (note: this is **not** Next.js — the `dev` script is literally `vite`).
- **Plugin system**: The Plugin SDK, CLI (`lbp`), Plugin Runtime, Box (sandbox) Runtime, and the entity/API definitions shared between LangBot and plugins all live in a separate repository: [`langbot-plugin-sdk`](https://github.com/langbot-app/langbot-plugin-sdk). LangBot depends on it via the version-pinned `langbot-plugin` package in `pyproject.toml`.

## Repository Layout

```
LangBot/
├── main.py                     # Entrypoint shim -> langbot.__main__.main()
├── pyproject.toml              # Python project + deps (uv), pins langbot-plugin==<x.y.z>
├── src/langbot/
│   ├── __main__.py             # Real entrypoint, CLI args (--standalone-runtime / --standalone-box / --debug)
│   ├── pkg/                    # Core backend package
│   │   ├── api/                # HTTP API controllers + services (Quart)
│   │   ├── core/               # App bootstrap, stages, task manager
│   │   ├── platform/           # IM platform adapters, bot managers, session managers
│   │   ├── provider/           # LLM providers, requesters, tool providers
│   │   ├── pipeline/           # Pipelines, stages, query pool
│   │   ├── plugin/             # Bridge to the plugin runtime (connector.py / handler.py)
│   │   ├── box/                # Code-sandbox subsystem (Docker / nsjail / E2B backends)
│   │   ├── skill/              # Skill subsystem
│   │   ├── rag/ , vector/      # RAG + vector store
│   │   ├── command/            # Built-in commands
│   │   ├── persistence/        # ORM models + Alembic migrations (SQLite & PostgreSQL)
│   │   ├── storage/            # Object/file storage abstractions
│   │   ├── config/, entity/, discover/, utils/, telemetry/, survey/
│   ├── libs/                   # Vendored SDKs (qq_official_api, wecom_api, etc.)
│   └── templates/              # Config/component templates (e.g. templates/config.yaml)
├── web/                        # Frontend SPA (Vite + React Router 7 + shadcn + Tailwind)
└── docker/                     # docker-compose deployment files
```

## How Components Are Organized

The core backend package `src/langbot/pkg/` is split into loosely-coupled submodules by responsibility:

| Module                     | Responsibility                                                                                                                |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `core`                     | Application lifecycle: startup stages load config, connect the DB, bring up subsystems in order, and manage background tasks. |
| `platform`                 | Adapters for each IM platform (Discord, Telegram, QQ, WeCom, Lark, etc.); send/receive messages, manage bots and sessions.    |
| `provider`                 | LLM providers and requesters (OpenAI-compatible and native APIs), plus tool providers callable by the Agent.                  |
| `pipeline`                 | The message-processing pipeline: routes one message through trigger, AI processing, output, and safety stages.                |
| `plugin`                   | Bridge between the LangBot main process and the plugin runtime — connect, exchange actions, forward events.                   |
| `box`                      | Code-sandbox subsystem providing isolated code execution for skills/tools; selects Docker / nsjail / E2B by availability.     |
| `skill` / `rag` / `vector` | Skill, retrieval-augmented generation, and vector-store capabilities.                                                         |
| `persistence`              | ORM entity definitions and Alembic migrations; a single set of scripts works on both SQLite and PostgreSQL.                   |

On the plugin side (defined in `langbot-plugin-sdk`, generated by `lbp comp`), components are organized around a single `BasePlugin`. Six component types are currently supported:

- **Command**: user-triggered actions (e.g. `!weather tokyo`).
- **Tool**: functions the LLM calls during Agent execution (e.g. fetch weather, query a database).
- **EventListener**: handlers for events in the message pipeline (e.g. auto-reply, content filtering).
- **KnowledgeEngine**: a custom knowledge-base retrieval/integration implementation used by RAG.
- **Parser**: custom parsing of messages/content.
- **Page**: a custom web page provided by the plugin, embeddable in the LangBot admin panel.

Each plugin runs in its own process, with its lifecycle managed by the plugin runtime (discover → install deps → load → initialize → register components → ready → terminate).

## How Things Connect at Runtime

```
┌──────────────┐   HTTP/API    ┌──────────────┐
│ Browser/Web  │ ────────────► │              │
│ (Vite SPA)   │ :3000/origin  │   LangBot    │
└──────────────┘               │   backend    │
                               │  (Quart)     │
   ┌───────────────────────────┤  :5300       ├─────────────────────────┐
   │ stdio or WebSocket          └──────────────┘   stdio or WebSocket   │
   ▼                                                ▼
┌──────────────┐                            ┌──────────────┐
│ Plugin       │  separate process,         │ Box          │  code sandbox
│ Runtime      │  launches each plugin       │ Runtime      │  Docker/nsjail/E2B
│ :5400 / :5401│                            │ :5410        │
└──────────────┘                            └──────────────┘
```

- **Frontend ↔ Backend**: In dev, the frontend runs standalone on `:3000` and reaches the backend `:5300` via `VITE_API_BASE_URL` in `web/.env`; in production the frontend is pre-built into static files served by the backend on the same origin.
- **Backend ↔ Plugin Runtime**:
  - When LangBot is **started directly** (not in a container), the backend **spawns** the runtime itself and talks over **stdio** (lightweight/personal use). stdio **cannot auto-reconnect** — after a disconnect you must restart LangBot; a common failure is an **orphan runtime process** from a previous backend still holding `5400`/`5401` — kill it and restart.
  - When LangBot runs in a **container**, it connects to a standalone runtime over **WebSocket** (production). Control port defaults to `5400`, debug port to `5401`. Config: `plugin.runtime_ws_url` in `data/config.yaml` (e.g. `ws://langbot_plugin_runtime:5400/control/ws`).
- **Backend ↔ Box Runtime**: The Box subsystem connects to the Box runtime over a control channel (default port `5410`), which executes sandboxed code in Docker / nsjail / E2B. Config (`box:` section of `data/config.yaml`): `box.enabled` (master switch), `box.backend` (`'local'`/`'docker'`/`'nsjail'`/`'e2b'`), `box.runtime.endpoint` (external Box runtime URL, e.g. `ws://127.0.0.1:5410`; empty = local auto-managed). As with the plugin runtime, set that endpoint and start with `--standalone-box` to connect to an external Box runtime.
- The full guide for debugging the runtime, CLI and SDK is in [Debugging Plugin Runtime, CLI, SDK](https://langbot.app/docs/en/develop/plugin-runtime.md); detailed flags and architecture are in the `langbot-plugin-sdk` repo's `AGENTS.md`.

## Development Environment Setup

Full guide: [Development Configuration](https://langbot.app/docs/en/develop/dev-config.md). Summary:

### Backend

```bash
pip install uv
uv sync --dev          # uv creates a .venv/ for you; point your editor's interpreter at it
uv run main.py         # serves API + frontend on http://127.0.0.1:5300
```

On first run the config file is generated at `data/config.yaml`. SQLite is the default (zero setup); PostgreSQL is supported. Migrations run automatically on startup.

### Frontend

Requires Node.js and [pnpm](https://pnpm.io/installation).

```bash
cd web
cp .env.example .env   # Windows: copy .env.example .env
pnpm install
pnpm dev               # http://127.0.0.1:3000 (npm install / npm run dev also work)
```

`pnpm dev` reads `VITE_API_BASE_URL` from `web/.env` so the dev frontend can reach the backend on `:5300`.

### Code Formatting

CI runs lint + format checks. Install the pre-commit hooks so the same checks run locally before each commit:

```bash
uv run pre-commit install
```

### Database Migrations

After changing ORM models, generate a migration:

```bash
# Run from the project root (requires data/config.yaml)
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "describe your change"
```

`autogenerate` detects schema changes (add/drop columns and tables, type changes), but **data migrations** (e.g. mutating JSON field contents) must be hand-written into the generated script. `env.py` sets `render_as_batch=True`, so SQLite's ALTER TABLE limits are handled automatically — no per-database branching needed. Migrations execute automatically on startup.

## Development Standards

- LangBot is a global project: **all code comments and docstrings must be in English**, and every user-facing string must support **i18n** (`en_US` + `zh_Hans` at minimum, plus `ja_JP` where the repo already has it).
- LangBot is adopted in both toC and toB scenarios — always consider compatibility and security.
- **Commit message format**: `<type>(<scope>): <subject>`
  - `type`: one of `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, etc.
  - `scope`: the affected package/module/file/class.
  - `subject`: a concise description of the change.

## Agent-Facing Surfaces (MCP + Skills)

LangBot is built to be **agent-friendly**, with three agent-facing surfaces that
are kept in lockstep with the HTTP API:

1. **MCP server** — `src/langbot/pkg/api/mcp/` exposes a curated subset of the API
   as MCP tools at `/mcp` (API-key authenticated, including `api.global_api_key`
   from config.yaml). `server.py` defines the tools (calling the service layer
   directly); `mount.py` is the ASGI dispatcher.
2. **In-repo skills** — the `skills/` directory is the **single source of truth**
   for all LangBot agent skills (plugin dev, core dev, deployment, e2e, MCP
   operations). Docs and the landing page link here rather than copying content.
3. **API-key auth** — `api.global_api_key` (config.yaml) authenticates the API and
   MCP without a login session; see `docs/API_KEY_AUTH.md`.

> **Maintenance rule (important).** When you add, remove, or change an HTTP API
> endpoint that should be agent-accessible, you MUST update **both** the matching
> MCP tool in `src/langbot/pkg/api/mcp/server.py` **and** the relevant skill under
> `skills/` (especially `skills/skills/langbot-mcp-ops`). API, MCP tools, and
> skills are one system — drift between them is a bug.

## Some Principles

- Keep it simple, stupid.
- Entities should not be multiplied unnecessarily.
- 八荣八耻 (Eight Honors and Eight Shames):

  Shame in guessing interfaces; honor in carefully checking them.
  Shame in vague execution; honor in seeking confirmation.
  Shame in assuming business logic; honor in human confirmation.
  Shame in inventing interfaces; honor in reusing existing ones.
  Shame in skipping verification; honor in proactive testing.
  Shame in breaking architecture; honor in following conventions.
  Shame in pretending to understand; honor in honest ignorance.
  Shame in blind changes; honor in careful refactoring.

---

# Component Architecture

Source: https://langbot.app/docs/en/develop/comp-arch

![Component Architecture Diagram](https://langbot.app/docs/images/zh/develop/comp_arch/develop_comp_arch_1.png)

---

# Development Configuration

Source: https://langbot.app/docs/en/develop/dev-config

LangBot is divided into frontend and backend. The frontend is developed using Vite + React Router + shadcn, and the backend is developed using Quart (an asynchronous version of Flask).

## Backend

The code is located in the `pkg` directory and is started by the `main.py` file in the root directory.

Install dependencies, we use uv to manage dependencies.

```bash
pip install uv
uv sync --dev
```

Start the backend

```bash
uv run main.py
```

At this point, the configuration file will be automatically generated in the `data/config.yaml` file.

## Frontend

The code is located in the `web` directory and requires Node.js and [pnpm](https://pnpm.io/installation).

Copy `.env.example` to `.env` and fill in the values.

- Usage in Linux and other environments

```bash
cp .env.example .env
```

- Usage in Windows environments

```bash
copy .env.example .env
```

Install dependencies and start the frontend

```bash
pnpm install
pnpm dev

# If pnpm is not installed, you can also use npm to solve dependencies and start
npm install
npm run dev
```

Then according to the output information, visit `http://127.0.0.1:3000` to view the standalone frontend page.

> When using \`pnpm dev\` to start locally, the environment variable \`VITE\_API\_BASE\_URL\` will be automatically used by the frontend to ensure that the frontend can access the \`5300\` port of the locally running backend.:
>
> In production environments, the frontend will be precompiled into static files and provided by the backend, and the frontend will automatically access the backend address on the same domain.

## Code Formatting

The repository contains lint and format check workflows, and your code will be automatically checked when you push it. Please configure pre-commit to check your code locally before submitting.

```bash
uv run pre-commit install
```

## API Documentation

We will write API documentation in APIFox before developing each interface. Please refer to [API Documentation(Chinese)](https://ok52vhsenr.apifox.cn/).

## Database Migrations

LangBot uses [Alembic](https://alembic.sqlalchemy.org/) to manage database migrations, supporting both SQLite and PostgreSQL seamlessly without database-specific branching.

### Migration File Location

```
src/langbot/pkg/persistence/alembic/versions/
```

### Creating a New Migration

The recommended way is to use **autogenerate**, which compares ORM models against the database schema and generates a migration script:

```bash
# Run from the project root (requires data/config.yaml)
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "describe your changes"
```

The generated file will appear in `src/langbot/pkg/persistence/alembic/versions/`. Review and edit the generated script to confirm the changes are correct before committing.

> info:
>
> Autogenerate can automatically detect column additions/removals, table changes, type changes, etc. However, for **data migrations** (e.g., modifying JSON field content), you need to manually add code to the generated script.

You can also create migration files manually, following the naming convention `NNNN_description.py`:

```python
"""Describe your migration

Revision ID: 0003_add_bot_description
Revises: 0002_sample
Create Date: 2026-04-08
"""
from alembic import op
import sqlalchemy as sa

revision = '0003_add_bot_description'
down_revision = '0002_sample'  # Points to the previous migration's revision
branch_labels = None
depends_on = None


def upgrade() -> None:
    # Schema change (works on both SQLite and PostgreSQL)
    op.add_column('bots', sa.Column('description', sa.String(512), server_default=''))


def downgrade() -> None:
    op.drop_column('bots', 'description')
```

### Migration Patterns

**Schema Changes (add/drop columns, create tables)**

```python
def upgrade() -> None:
    # Add a column
    op.add_column('table_name', sa.Column('new_col', sa.String(255), server_default=''))
    
    # Create a new table
    op.create_table(
        'new_table',
        sa.Column('id', sa.Integer, primary_key=True, autoincrement=True),
        sa.Column('name', sa.String(255), nullable=False),
    )
```

> info:
>
> `env.py` sets `render_as_batch=True`, which makes Alembic automatically handle SQLite's ALTER TABLE limitations (via temporary table rebuild). No need to branch on database type.

**Data Migrations (read and modify data)**

```python
import json

def upgrade() -> None:
    conn = op.get_bind()
    rows = conn.execute(sa.text("SELECT uuid, config FROM pipelines")).fetchall()
    for row in rows:
        config = json.loads(row[1]) if isinstance(row[1], str) else row[1]
        config.setdefault('ai', {})['new_key'] = 'default_value'
        conn.execute(
            sa.text("UPDATE pipelines SET config = :cfg WHERE uuid = :uuid"),
            {"cfg": json.dumps(config), "uuid": row[0]}
        )
```

### How It Works

Migrations run automatically when LangBot starts — no manual commands needed:

1. On first startup, the baseline version is automatically stamped (marking the existing database)
2. On subsequent startups, all pending migrations are applied (`alembic upgrade head`)

### CI Testing

The repository includes a `test-migrations.yml` workflow that automatically tests migration scripts on both SQLite and PostgreSQL when `persistence/` related files change.

### CLI Tool

```bash
# Autogenerate migration (compare ORM models against DB)
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "description"

# Upgrade database
uv run python -m langbot.pkg.persistence.alembic_runner upgrade

# Show current revision
uv run python -m langbot.pkg.persistence.alembic_runner current

# Stamp revision (without running migrations)
uv run python -m langbot.pkg.persistence.alembic_runner stamp head
```

---

# Debugging Plugin Runtime, CLI, SDK

Source: https://langbot.app/docs/en/develop/plugin-runtime

> info:
>
> Plugin Runtime, CLI, SDK are open sourced at: <https://github.com/langbot-app/langbot-plugin-sdk>

Since LangBot depends on entities defined in langbot-plugin-sdk, we recommend opening VS Code in a new directory, placing both LangBot and langbot-plugin-sdk (git clone <https://github.com/langbot-app/langbot-plugin-sdk>) as subdirectories within it. The directory structure should look like:

```bash
langbot-projects
├── LangBot
├── langbot-plugin-sdk
```

Enter the LangBot directory and install dependencies:

```bash
cd LangBot
uv sync --dev
```

At this point, uv will automatically create a virtual environment (.venv) for you. If your editor asks whether to use this virtual environment, please select `Yes`.

![](https://langbot.app/docs/images/zh/develop/confirm_venv.png)

If the prompt does not appear, please manually set the Python interpreter path to the interpreter in the venv from the bottom-right corner.

Then open the terminal at the bottom of VS Code, which will automatically activate the venv.

Or you can manually activate this virtual environment:

```bash
# Please modify the command according to your .venv path
source .venv/bin/activate
```

## Start Plugin Runtime

```bash
python -m langbot_plugin.cli.__init__ rt
```

Plugin Runtime accepts the following parameters:

- `--debug-only`: Do not start plugins in the `data/plugins` directory, only allow loading plugins through debug connections.
- `--ws-debug-port`: Debug port to listen on, default is `5401`.
- `--ws-control-port`: Control port to listen on (for LangBot main program connection), default is `5400`.
- `-s`: Use `stdio` to accept control connections. **Use only in production environment**.
- `--skip-deps-check`: To ensure that all plugin dependencies are installed, the Runtime will check and install all installed plugin dependencies on every startup. Use this parameter to disable this check.

### Make LangBot Use Your Locally Modified langbot-plugin-sdk

If you have modified things like message entities or plugin data definitions, you need to update them in the LangBot environment to ensure data format compatibility during runtime.

In a **terminal with the LangBot directory's virtual environment (.venv) activated**, switch to the langbot-plugin-sdk directory and run:

```bash
uv pip install .
```

This will install your modified langbot-plugin-sdk into LangBot's environment.

### Make LangBot Connect to This Runtime

Configure `plugin.runtime_ws_url` to `ws://localhost:5400/control/ws` in LangBot's `data/config.yaml`.

```yaml
plugin:
  runtime_ws_url: ws://localhost:5400/control/ws
```

In a terminal with LangBot's virtual environment activated, start the main program directly with Python and add `--standalone-runtime` (for example, `python main.py --standalone-runtime`). Calling the current virtual environment's Python directly does not resync dependencies, so it does not overwrite the local langbot-plugin-sdk you just installed with the remote version.\
Restart LangBot, and it will connect to this runtime using WebSocket.

`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` is optional by default. When it is unset on both LangBot and Runtime, the local OSS control connection is established without a token. To protect an exposed port 5400, configure the same high-entropy value of at least 32 characters on both sides. Once the Runtime configures a token, it rejects LangBot clients without the same value; configuring only the LangBot side does not enable authentication on the Runtime.

### Debug a plugin with `lbp run`

Multi-Workspace versions no longer allow a debug plugin to join the Runtime merely by reaching port `5401`. Every Workspace has a separate expiring debug key:

1. Make sure LangBot and Plugin Runtime are running and connected as described above.
2. On the LangBot WebUI Plugins page, open “Debug Info” and copy the debug URL and debug key. This requires resource-management permission in the current Workspace.
3. Add the values to the plugin project's `.env`:

```bash
DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws
PLUGIN_DEBUG_KEY=<debug key copied from the WebUI>
```

4. Start the plugin from its project directory:

```bash
python -m langbot_plugin.cli.__init__ run
```

Instead of storing the key in `.env`, you may run `python -m langbot_plugin.cli.__init__ run --plugin-debug-key '<debug key>'`. Keys are scoped to one Workspace and expire after two hours. Fetch a new key after it expires, the Runtime restarts, or you switch Workspaces. A client that configures only `DEBUG_RUNTIME_WS_URL` is rejected.

## Start Box Runtime in standalone mode

Box Runtime follows the same control-connection rules as Plugin Runtime: a token is optional for OSS standalone development, and the connection works when `LANGBOT_BOX_CONTROL_TOKEN` is unset on both sides:

```bash
# Terminal 1: langbot-plugin-sdk directory
python -m langbot_plugin.cli.__init__ box
```

Point LangBot's `data/config.yaml` at the local Box Runtime:

```yaml
box:
  enabled: true
  backend: local
  runtime:
    endpoint: ws://127.0.0.1:5410
```

```bash
# Terminal 2: LangBot directory
python main.py --standalone-runtime --standalone-box
```

To protect an exposed port 5410, set the same high-entropy, non-whitespace value of at least 32 characters before starting each process:

```bash
export LANGBOT_BOX_CONTROL_TOKEN='<the exact same high-entropy secret on both sides>'
```

Once Box Runtime configures a token, it rejects LangBot clients without the same value. Configuring only the LangBot side does not enable authentication on Box Runtime; an explicitly configured value shorter than 32 characters is still rejected by both sides. Do not commit the real value to configuration or Git.

## langbot-plugin-sdk Architecture

This codebase contains the following:

- `langbot_plugin.api`: Plugin-related entities and API definitions.
- `langbot_plugin.assets`: Plugin templates.
- `langbot_plugin.cli`: Plugin development CLI tools.
- `langbot_plugin.entities`: Plugin system-related entities not defined in API.
- `langbot_plugin.runtime`: Plugin runtime and underlying communication (stdio and websocket) implementation.

## `lbp` CLI Tool

The CLI tool provides Runtime startup, plugin initialization, plugin component management, Marketplace interaction, and other functions.

For detailed program entry points, please see [`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py).

---

# Community Resources

Source: https://langbot.app/docs/en/insight/community

LangBot community resources: GitHub, Discord, documentation and support for the open-source AI bot platform.

## Simplified Tutorials

> Simplified tutorials: such as video tutorials, simpler text tutorials, suitable for beginners

Collected at: <https://blog.thelazy.top/tags/langbot>

## 🥰 Community

Join our community on Discord: [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord\&labelColor=%20%235462eb\&logoColor=%20%23f5f5f5\&color=%20%235462eb)](https://discord.gg/wdNEHETs87)

---

# Data Collection Policy

Source: https://langbot.app/docs/en/insight/data-collection-policy

Optional telemetry, execution observations and opt-out controls

LangBot sends telemetry to the configured LangBot Space service (by default `https://space.langbot.app`) to understand usage and improve reliability. **Telemetry is enabled by default and can be disabled.** Execution observations use existing telemetry rather than a separate Beta diagnostics producer.

## Existing product telemetry

When enabled, the existing query path can send:

| Data                     | Contents                                                                                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Identity and environment | `instance_id`, `workspace_uuid`, random `query_id`, version, adapter and runner types                                                                                                                  |
| Query statistics         | Model name, duration, timestamp, pipeline plugin names                                                                                                                                                 |
| Feature usage            | Tool counts by source, tool-call rounds, knowledge-base and retrieved-entry counts, knowledge-engine plugin IDs, sandbox execution/error counts, activated skill names and configured MCP server names |
| Errors                   | The legacy `error` field can contain a raw traceback, including exception text                                                                                                                         |
| Managed runtime activity | `runtime_instance_id` on managed SaaS queries refreshes idle-timeout activity; it is not stored in the analytics event record                                                                          |

Feature counters do not intentionally include tool arguments/results, retrieved text or sandbox code/output. **However, legacy exception text and user-defined model, skill or MCP names may contain sensitive information. The execution-record content restrictions do not sanitize this legacy stream.** Do not treat existing telemetry as guaranteed content-free.

A Workspace heartbeat is sent shortly after startup and daily for active Workspaces. It includes deployment platform, database/vector-database kinds, sandbox configuration and availability, enabled adapter types and resource counts, rather than resource contents or connection details.

Optional in-app surveys send the survey ID, submitted answers, instance ID, version and completion/dismissal status. Survey answers are user-provided content, not Beta diagnostics.

## Execution telemetry

Execution observations cover platform events, routing, Pipeline / Agent / plugin event processors and platform APIs. Fields include code-defined operation identifiers, adapter and runner types, processing mode, outcome, counts, first/last observation times, instance and Workspace identifiers, version and a synthetic-execution flag. Core aggregates bounded counters in memory and sends them in background tasks; Space performs coverage analysis.

These execution records exclude messages, prompts, model replies, platform user/group IDs, tool/API arguments or results, credentials and raw exception tracebacks. Instance and Workspace identifiers may be associated with deployments or accounts. These content restrictions apply to execution records, not to the legacy query telemetry described above.

### Per-event execution chains

A sampled subset of these records traces one inbound event end to end: an opaque random trace identity, the observed stages in order (platform event → routing decision → Pipeline / Agent / plugin event processor → platform API calls), each stage's outcome, the routing target identity, the Runner run identity when a Runner executed the event, and why the chain closed. Stage fields are the same code-defined identifiers as above; a routing target is reported as `type:uuid`, never as a user-defined rule name. Core keeps a bounded number of stages per chain and a bounded number of chains in memory, then drops overflow.

Chains are sampled with `space.execution_trace`: `off`, `failures` (chains containing a failed, cancelled or timed-out stage), `sampled` (the default: those chains plus every N-th successful one, N = `space.execution_trace_sample`) or `all`. WebUI debug runs are always kept and remain flagged as synthetic, so they stay out of real-execution statistics.

Connection failures, timeouts and server errors do not block normal operations. Failure details are logged only at DEBUG level. Queues are bounded and records may be lost during failures. Observations support analysis; a successful platform API response does not prove that a user read a message.

## Storage and retention

Data is stored by the configured Space service. Raw execution records are periodically removed in bounded batches using a 30-day retention window; backlogs or service interruptions can delay deletion. This does not change retention for legacy query telemetry, surveys, accounts or service logs. Coverage analysis is restricted to authorized telemetry management users or service clients.

Opting out stops future reporting but does not delete existing server records. For historical data requests, contact <hello@langbot.app> or your Space administrator.

## Disabling telemetry

Set the following in the existing `space` section of `data/config.yaml`, preserve other settings, and restart LangBot:

```yaml
space:
  disable_telemetry: true
```

This switch disables query statistics, heartbeat and execution telemetry, as well as survey fetching. Use an unquoted YAML boolean. To restore the default, set it to `false` and restart.

If `SPACE__DISABLE_TELEMETRY` is set in your deployment, it overrides the file at startup; update or remove it too. Recreate containers when changing their environment. In Cloud, the instance operator controls this setting for every Workspace in the instance. It does not disable the bot or change privacy settings of messaging platforms, model providers or plugins.

See [System Settings](https://langbot.app/docs/en/deploy/settings.md).

---

# Features

Source: https://langbot.app/docs/en/insight/features

LangBot is an open-source, production-grade, LLM-native instant messaging bot development platform. Build AI agents for Discord, Telegram, Slack, QQ, WeChat, WeCom, Lark, DingTalk and more — with built-in Agent, RAG knowledge base, MCP, Skills and a code sandbox, plus deep integration with Dify, Coze, n8n and Langflow.

LangBot is an **open-source, production-grade**, LLM-native instant messaging bot development platform. With a single codebase you can bring AI agents to Discord, Telegram, Slack, QQ, WeChat, WeCom, Lark, DingTalk and more — with built-in **Agent, RAG knowledge base, MCP, Skills and a code sandbox**, deep integration with Agent platforms like Dify, Coze, n8n and Langflow, and everything configured and monitored from a browser-based web panel — no hand-written config files.

> idea:
>
> **Don't want to self-host?** Try [LangBot Cloud](https://space.langbot.app/cloud) — no server required, sign up and start instantly.

## Core Capabilities at a Glance

- **AI Conversation & Agent** — multi-turn dialogue, tool calling (function calling), multimodal (image/audio/file) and streaming output, ready out of the box.
- **RAG Knowledge Base** — a built-in knowledge-base engine (vector retrieval + Rerank re-scoring) so your bot answers from your private knowledge, extensible via plugins to seamlessly connect external knowledge-base services like RAGFlow, Dify and FastGPT.
- **All-Platform Coverage** — one codebase reaches Discord, Telegram, Slack, LINE, KOOK, Matrix, QQ, WeChat, WeCom, Lark, DingTalk and more.
- **Deep Agent Platform Integration** — native connectors for Dify, Coze, n8n, Langflow, Deerflow, Aliyun Bailian, Ant TBox and other orchestration & workflow platforms.
- **Skills & Code Sandbox** — on-demand instruction packs paired with a securely isolated code-execution sandbox, so the agent actually *gets things done*.
- **MCP Protocol** — acts as a client into the Model Context Protocol tool ecosystem, supporting both Stdio and HTTP transports.
- **Web Management Panel** — configure, manage and monitor bots visually in the browser, no manual config editing.
- **Production-grade Plugin System** — hundreds of community plugins on a cross-process, event-driven architecture that's safe and hot-pluggable.
- **Multi-pipeline Architecture** — run multiple pipelines per instance so different bots serve different scenarios, with access control, rate limiting, sensitive-word filtering and comprehensive monitoring.

## Instant Messaging Platform Support

LangBot covers mainstream global IM platforms through a unified adapter layer — develop once, reach everywhere.

| Platform                | Status | Remarks                                                                                                                                              |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Personal QQ             | ✅      | Supported via third-party apps implementing the OneBot v11 protocol; private and group chats                                                         |
| QQ Official Bot         | ✅      | Channels, private chats, and group chats                                                                                                             |
| WeChat                  | ✅      | Personal WeChat                                                                                                                                      |
| WeChat Official Account | ✅      |                                                                                                                                                      |
| WeCom                   | ✅      | Internal application messages                                                                                                                        |
| WeCom Intelligent Bot   | ✅      | Supports streaming output                                                                                                                            |
| WeCom Customer Service  | ✅      |                                                                                                                                                      |
| Lark                    | ✅      | Supports streaming output                                                                                                                            |
| DingTalk                | ✅      | Supports streaming output                                                                                                                            |
| Discord                 | ✅      |                                                                                                                                                      |
| Telegram                | ✅      | Supports streaming output                                                                                                                            |
| Slack                   | ✅      |                                                                                                                                                      |
| LINE                    | ✅      |                                                                                                                                                      |
| KOOK                    | ✅      |                                                                                                                                                      |
| Satori                  | ✅      | [Satori](https://satori.chat/zh-CN/introduction.html) is a universal chat protocol that theoretically supports QQ, Zulip, Miyoushe and 15+ platforms |
| Matrix                  | ✅      | Reaches Signal, WhatsApp, Messenger, iMessage, Mattermost, Google Chat, IRC, XMPP, Zulip and more via bridges                                        |
| Email                   | ✅      | Use email as a conversation channel                                                                                                                  |
| Web Page Bot            | ✅      | Embeddable chat widget for web pages                                                                                                                 |
| WhatsApp                | 🚧     | In development (also usable via Matrix bridge)                                                                                                       |

🚧: In development

For fine-grained, per-platform feature support (sending/receiving images, audio, files, rich text, streaming responses, etc.), see the [platform features document](https://langbot.app/docs/en/insight/platform-features.md).

## Model and Agent Platform Support

LangBot uses **LiteLLM as a unified model request backend**, so beyond the built-in providers below you can also connect any OpenAI / Anthropic API-format or LiteLLM-supported model.

### LLM, Aggregation & GPU Platforms

| Provider/Service                                                                    | Status | Remarks                              |
| ----------------------------------------------------------------------------------- | ------ | ------------------------------------ |
| [OpenAI](https://platform.openai.com/)                                              | ✅      | Works with any OpenAI-format model   |
| [Anthropic](https://www.anthropic.com/)                                             | ✅      |                                      |
| [DeepSeek](https://www.deepseek.com/)                                               | ✅      |                                      |
| [Google Gemini](https://aistudio.google.com/prompts/new_chat)                       | ✅      |                                      |
| [xAI](https://x.ai/)                                                                | ✅      |                                      |
| [Moonshot](https://www.moonshot.cn/)                                                | ✅      |                                      |
| [Zhipu AI](https://open.bigmodel.cn/)                                               | ✅      |                                      |
| [Mistral](https://mistral.ai/)                                                      | ✅      |                                      |
| [Groq](https://groq.com/)                                                           | ✅      |                                      |
| [OpenRouter](https://openrouter.ai/)                                                | ✅      | Global LLM gateway                   |
| [Ollama](https://ollama.com/)                                                       | ✅      | Local LLM running platform           |
| [LMStudio](https://lmstudio.ai/)                                                    | ✅      | Local LLM running platform           |
| [SiliconFlow](https://siliconflow.cn/)                                              | ✅      | LLM gateway (MaaS)                   |
| [Aliyun Bailian](https://bailian.console.aliyun.com/)                               | ✅      | LLM gateway (MaaS) / Agent platform  |
| [Volc Engine Ark](https://console.volcengine.com/ark)                               | ✅      | LLM gateway (MaaS) / Agent platform  |
| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro)          | ✅      | LLM gateway (MaaS)                   |
| [GiteeAI](https://ai.gitee.com/)                                                    | ✅      | LLM interface gateway (MaaS)         |
| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758)                      | ✅      | Global LLM aggregation (recommended) |
| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot)                       | ✅      | LLM and GPU resource platform        |
| [PPIO](https://ppio.com/user/register?invited_by=QJKFYD\&utm_source=github_langbot) | ✅      | LLM and GPU resource platform        |
| [302.AI](https://share.302ai.cn/SuTG99)                                             | ✅      | LLM gateway (MaaS)                   |
| [Jiekou AI](https://jiekou.ai/)                                                     | ✅      | LLM gateway (MaaS)                   |
| [TokenPony](https://www.tokenpony.cn/453z1)                                         | ✅      | LLM gateway (MaaS)                   |
| [Qiniu](https://www.qiniu.com/ai/agent)                                             | ✅      | LLM gateway (MaaS)                   |

### Agent Platforms

Plug your existing workflows or agents straight into IM platforms — no need to rewrite your business logic.

| Platform                                 | Status | Remarks                       |
| ---------------------------------------- | ------ | ----------------------------- |
| [Dify](https://dify.ai)                  | ✅      | Agent platform                |
| [Coze](https://coze.cn)                  | ✅      | Agent orchestration platform  |
| [n8n](https://n8n.io/)                   | ✅      | Workflow automation platform  |
| [Langflow](https://langflow.org/)        | ✅      | Visual orchestration platform |
| [Deerflow](https://deerflow.tech)        | ✅      | Deep research framework       |
| [Weknora](https://weknora.weixin.qq.com) | ✅      | WeChat knowledge-base Q\&A    |
| [Ant TBox](https://tbox.cn/)             | ✅      | Agent platform                |

### Rerank Models

| Provider                           | Status | Remarks       |
| ---------------------------------- | ------ | ------------- |
| [Cohere](https://cohere.com/)      | ✅      | Rerank models |
| [Jina](https://jina.ai/)           | ✅      | Rerank models |
| [Voyage AI](https://voyageai.com/) | ✅      | Rerank models |

## LLM Application Paradigm Implementation

LangBot turns mainstream LLM application paradigms into out-of-the-box capabilities, covering the full path from "can chat" to "can get work done."

| Paradigm             | Status | Notes                                                                                                                                                    |
| -------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent                | ✅      | Built-in agent with tool calling, multi-turn reasoning, multimodal and streaming output                                                                  |
| RAG (Knowledge Base) | ✅      | Built-in knowledge-base engine (default Chroma vector store + Rerank re-scoring), pluggable into external knowledge bases like RAGFlow, Dify and FastGPT |
| MCP                  | ✅      | Acts as an MCP client into the tool ecosystem; supports Stdio and HTTP                                                                                   |
| Skills               | ✅      | On-demand instruction packs, pulled into context only when matched — zero extra overhead                                                                 |
| Code Sandbox         | ✅      | Securely isolated code-execution environment with Docker / nsjail / E2B backends                                                                         |

- **Skills**: package a professional workflow, template or script into an on-demand instruction pack — the agent pulls it into context only when the user's request matches, keeping the System Prompt clean. See the [Skills doc](https://langbot.app/docs/en/usage/skills/readme.md).
- **Code Sandbox**: gives the agent securely isolated code-execution capability, automatically picking the best of the Docker / nsjail / E2B backends — the runtime foundation for Skills and native tools. See the [Sandbox doc](https://langbot.app/docs/en/usage/sandbox/readme.md).

## System Extensibility

LangBot offers a complete extension surface for secondary development and enterprise integration.

- **HTTP Service API**: access LangBot's entities through HTTP interfaces with API-key authentication, for easy integration with existing systems.
- **Outgoing Webhook**: push LangBot's internal events to external systems in real time, enabling event-driven automation.
- **Production-grade Plugin System**: built on cross-process communication and async technology, supporting various component extensions — safe, stable and hot-pluggable; hundreds of community plugins install in one click from the [extension marketplace](https://space.langbot.app).
- **Web Management Panel**: do all your bot, model, pipeline, knowledge-base and plugin configuration and monitoring visually.

## Deployment Options

LangBot supports everything from a one-line command to a Kubernetes cluster:

- **LangBot Cloud (recommended)**: [a hosted, deploy-free, out-of-the-box version](https://space.langbot.app/cloud).
- **One-line start**: `uvx langbot`, then open `http://localhost:5300`.
- **Docker Compose**, **aaPanel**, **Kubernetes**, **one-click cloud deploy on Zeabur / Railway**, and more.

See the [deployment docs](https://langbot.app/docs/en/deploy/langbot/kubernetes.md) and [quick start](https://langbot.app/docs/en/insight/guide.md).

## Case Screenshots

![LangBot bot configuration page: bind a web page bot to a pipeline in the web dashboard](https://langbot.app/docs/images/zh/insight/features/bot-page.png)

![LangBot model configuration: connect any OpenAI / Anthropic API-compatible LLM such as OpenAI or Anthropic](https://langbot.app/docs/images/zh/insight/features/create-model.png)

![LangBot pipeline AI configuration: choose the built-in Agent runner and primary model](https://langbot.app/docs/images/zh/insight/features/edit-pipeline.png)

![LangBot extension marketplace: one-click install for hundreds of community plugins and MCP tools](https://langbot.app/docs/images/zh/insight/features/plugin-market.png)

![LangBot built-in Agent calling the code sandbox: executing Python in real time for exact computation](https://langbot.app/docs/images/zh/insight/features/agent-sandbox.png)

![LangBot Skill-driven Agent: producing structured output following a predefined skill](https://langbot.app/docs/images/zh/insight/features/agent-skill.png)

---

# Welcome to LangBot Documentation

Source: https://langbot.app/docs/en/insight/guide

LangBot is an open-source LLM bot platform connecting Discord, Telegram, WeChat, Slack and more to GPT, Claude, Gemini, DeepSeek and Dify. Start here.

LangBot is an **open-source, production-grade**, LLM-native instant messaging bot platform. It connects large language models — OpenAI, Anthropic, Gemini, DeepSeek and more — and Agent platforms like Dify, Coze and n8n to mainstream messaging platforms including Discord, Telegram, Slack, QQ, WeChat, WeCom, Lark and DingTalk. With built-in Agent, RAG knowledge base, MCP, Skills and a code sandbox, plus an out-of-the-box web management panel, you can get your AI bot online in minutes — no hand-written config files required.

![LangBot web management dashboard: real-time monitoring of message volume, model calls, success rate, active sessions and traffic trends](https://langbot.app/docs/images/zh/insight/dashboard-overview.png)

## What You Can Build

- **AI customer service / enterprise assistant**: deploy a knowledge-base-backed AI agent to Slack, Discord, Lark, WeCom or DingTalk to answer customer and employee questions automatically.
- **Community operations**: provide AI-powered Q\&A, content moderation and interaction in Discord, Telegram and QQ groups.
- **Workflow integration**: plug your existing Dify / n8n / Coze workflows straight into chat platforms — no need to rewrite business logic.
- **Multi-platform reach**: one bot covers every platform, managed centrally from a unified panel.

## Start Here

Follow this path to get familiar with LangBot, then explore the guides relevant to your needs.

1. **Explore features and platforms**: read the [feature overview](https://langbot.app/docs/en/insight/features.md) and [platform support](https://langbot.app/docs/en/insight/platform-features.md) to see whether LangBot fits your use case.
2. **Choose how to deploy**: use [LangBot Cloud](https://space.langbot.app/cloud) without managing your own server, or self-host with [Docker](https://langbot.app/docs/en/deploy/langbot/docker.md) or a [package manager](https://langbot.app/docs/en/deploy/langbot/package.md).
3. **Connect bots and models**: see [bot configuration](https://langbot.app/docs/en/usage/platforms/readme.md), [model configuration](https://langbot.app/docs/en/usage/models/readme.md), and [pipelines](https://langbot.app/docs/en/usage/pipelines/readme.md) to learn how messaging platforms connect to AI capabilities.
4. **Add more capabilities**: extend your bot with [knowledge bases](https://langbot.app/docs/en/usage/knowledge/readme.md), [plugins](https://langbot.app/docs/en/plugin/plugin-intro.md), [MCP](https://langbot.app/docs/en/usage/mcp/readme.md), and [Skills](https://langbot.app/docs/en/usage/skills/readme.md).
5. **Explore examples or contribute**: find ideas in [practical articles](https://langbot.app/docs/en/articles.md), or read about [plugin development](https://langbot.app/docs/en/plugin/dev/tutor.md) and [core development setup](https://langbot.app/docs/en/develop/dev-config.md).

If you run into problems, check [troubleshooting](https://langbot.app/docs/en/insight/troubleshooting.md) or ask the [community](https://langbot.app/docs/en/insight/community.md).

> Let an AI agent help you deploy and use LangBot:
>
> Copy the prompt below into your AI assistant. It starts with the official documentation and adapts its help to your environment and goals.
>
> ```text
> Help me deploy and use LangBot. Read the official documentation first, then propose an approach suited to my environment.
>
> Start with the English documentation index at https://langbot.app/docs/en/llms.txt and read these key pages:
> - Features: https://langbot.app/docs/en/insight/features.md
> - Platform support: https://langbot.app/docs/en/insight/platform-features.md
> - Bot configuration: https://langbot.app/docs/en/usage/platforms/readme.md
> - Model configuration: https://langbot.app/docs/en/usage/models/readme.md
> - Pipelines: https://langbot.app/docs/en/usage/pipelines/readme.md
>
> First, find out which messaging platform and model I want to use and whether I already have a LangBot instance. If deployment is needed, ask about my operating system, server or local environment, and preference for cloud or self-hosting. Then use the index to read the relevant deployment and platform connection guides. Do not guess commands or configuration fields.
>
> Help me deploy LangBot and configure the bot connection, model, and pipeline based on the documentation. If you have execution tools, work within the environment I authorize and verify the results; otherwise, give me instructions suited to my setup. Prefer reusing an existing instance. Ask before overwriting configuration, deleting data, or taking paid actions, and do not ask me to paste secrets into chat.
>
> Finally, help me send a real test message and confirm that the bot replies. Once the basics work, guide me to knowledge bases, plugins, MCP, or Skills as needed. If you cannot read the docs or an operation fails, say so clearly. Do not report unverified steps as completed.
> ```

---

# Platform Feature Support

Source: https://langbot.app/docs/en/insight/platform-features

Compare LangBot feature support across messaging platforms: Discord, Telegram, WeChat, Slack, QQ, Lark, DingTalk and more.

The following is a list of features we have implemented and tested for each platform. If you encounter unexpected behavior, please feel free to report it to [GitHub Issues](https://github.com/langbot-app/LangBot/issues) or directly submit a Pull Request to help fix it.

## OneBot v11

### Receive

| Feature                             | Status | Remarks                 |
| ----------------------------------- | ------ | ----------------------- |
| Receive private messages            | ✅      |                         |
| Receive group mention messages      | ✅      |                         |
| Receive group regular messages      | ✅      |                         |
| Receive image messages              | ✅      |                         |
| Receive voice messages              | ✅      |                         |
| Receive file messages               | ✅      |                         |
| Receive rich text messages          | ✅      | Text and image combined |
| Get private message event user name | ✅      |                         |
| Get group message event group name  | ✅      |                         |
| Get group message event sender name | ✅      |                         |

### Send

| Feature                       | Status | Remarks                 |
| ----------------------------- | ------ | ----------------------- |
| Reply to private messages     | ✅      |                         |
| Reply to group messages       | ✅      |                         |
| Reply with image messages     | ✅      |                         |
| Reply with voice messages     | ✅      |                         |
| Reply with file messages      | ✅      |                         |
| Reply with rich text messages | ✅      | Text and image combined |
| Send proactive messages       | ✅      |                         |
| Send streaming response       | ❌      |                         |

## QQ Official Bot

## WeCom (Internal Application)

### Receive

| Feature                             | Status | Remarks                                                      |
| ----------------------------------- | ------ | ------------------------------------------------------------ |
| Receive private messages            | ✅      |                                                              |
| Receive group mention messages      | ❌      | WeCom internal application does not support adding to groups |
| Receive group regular messages      | ❌      |                                                              |
| Receive image messages              | ✅      |                                                              |
| Receive voice messages              | ✅      |                                                              |
| Receive file messages               | ✅      |                                                              |
| Receive rich text messages          | ❌      |                                                              |
| Get private message event user name | ✅      |                                                              |
| Get group message event group name  | ❌      |                                                              |
| Get group message event sender name | ❌      |                                                              |

### Send

| Feature                       | Status | Remarks |
| ----------------------------- | ------ | ------- |
| Reply to private messages     | ✅      |         |
| Reply to group messages       | ❌      |         |
| Reply with image messages     | ✅      |         |
| Reply with voice messages     | ✅      |         |
| Reply with file messages      | ✅      |         |
| Reply with rich text messages | ❌      |         |
| Send proactive messages       | ✅      |         |
| Send streaming response       | ❌      |         |

## Satori

### Receive

| Feature                             | Status | Remarks                 |
| ----------------------------------- | ------ | ----------------------- |
| Receive private messages            | ✅      |                         |
| Receive group mention messages      | ✅      |                         |
| Receive group regular messages      | ✅      |                         |
| Receive image messages              | ✅      |                         |
| Receive voice messages              | ✅      |                         |
| Receive file messages               | ✅      |                         |
| Receive rich text messages          | ✅      | Text and image combined |
| Get private message event user name | ✅      |                         |
| Get group message event group name  | ✅      |                         |
| Get group message event sender name | ✅      |                         |

### Send

| Feature                       | Status | Remarks                 |
| ----------------------------- | ------ | ----------------------- |
| Reply to private messages     | ✅      |                         |
| Reply to group messages       | ✅      |                         |
| Reply with image messages     | ✅      |                         |
| Reply with voice messages     | ✅      |                         |
| Reply with file messages      | ✅      |                         |
| Reply with rich text messages | ✅      | Text and image combined |
| Send proactive messages       | ✅      |                         |
| Send streaming response       | ❌      |                         |

## WeCom (Customer Service)

## WeCom Intelligent Bot

## WeChat Official Account

## Lark

### Receive

| Feature                             | Status | Remarks                                                    |
| ----------------------------------- | ------ | ---------------------------------------------------------- |
| Receive private messages            | ✅      |                                                            |
| Receive group mention messages      | ✅      |                                                            |
| Receive group regular messages      | ❌      | Lark only supports receiving messages that mention the bot |
| Receive image messages              | ✅      |                                                            |
| Receive voice messages              | ❌      | Lark does not have voice messages                          |
| Receive file messages               | ✅      |                                                            |
| Receive rich text messages          | ✅      | Text and image combined                                    |
| Get private message event user name | ❌      | Lark does not support getting user name                    |
| Get group message event group name  | ❌      | Lark does not support getting group name                   |
| Get group message event sender name | ❌      | Lark does not support getting sender name                  |

### Send

| Feature                       | Status | Remarks |
| ----------------------------- | ------ | ------- |
| Reply to private messages     | ✅      |         |
| Reply to group messages       | ✅      |         |
| Reply with image messages     | ✅      |         |
| Reply with voice messages     | ❌      |         |
| Reply with file messages      | ❌      |         |
| Reply with rich text messages | ❌      |         |
| Send proactive messages       | ✅      |         |
| Send streaming response       | ✅      |         |

## DingTalk

### Receive

| Feature                             | Status | Remarks                                                        |
| ----------------------------------- | ------ | -------------------------------------------------------------- |
| Receive private messages            | ✅      |                                                                |
| Receive group mention messages      | ✅      |                                                                |
| Receive group regular messages      | ❌      | DingTalk only supports receiving messages that mention the bot |
| Receive image messages              | ✅      |                                                                |
| Receive voice messages              | ✅      |                                                                |
| Receive file messages               | ✅      |                                                                |
| Receive rich text messages          | ✅      | Text and image combined                                        |
| Get private message event user name | ✅      |                                                                |
| Get group message event group name  | ✅      |                                                                |
| Get group message event sender name | ✅      |                                                                |

### Send

| Feature                       | Status | Remarks                 |
| ----------------------------- | ------ | ----------------------- |
| Reply to private messages     | ✅      |                         |
| Reply to group messages       | ✅      |                         |
| Reply with image messages     | ✅      |                         |
| Reply with voice messages     | ❌      |                         |
| Reply with file messages      | ❌      |                         |
| Reply with rich text messages | ✅      | Text and image combined |
| Send proactive messages       | ✅      |                         |
| Send streaming response       | ✅      |                         |

## KOOK

P.S. Sending voice and file messages has errors not fixed yet

### Receive

| Feature                             | Status | Remarks                 |
| ----------------------------------- | ------ | ----------------------- |
| Receive private messages            | ✅      |                         |
| Receive group mention messages      | ✅      |                         |
| Receive group regular messages      | ✅      |                         |
| Receive image messages              | ✅      |                         |
| Receive voice messages              | ✅      |                         |
| Receive file messages               | ✅      |                         |
| Receive rich text messages          | ✅      | Text and image combined |
| Get private message event user name | ✅      |                         |
| Get group message event group name  | ✅      |                         |
| Get group message event sender name | ✅      |                         |

### Send

| Feature                       | Status | Remarks                                            |
| ----------------------------- | ------ | -------------------------------------------------- |
| Reply to private messages     | ✅      |                                                    |
| Reply to group messages       | ✅      |                                                    |
| Reply with image messages     | ✅      |                                                    |
| Reply with voice messages     | ❌      | KOOK does not support replying with voice messages |
| Reply with file messages      | ❌      |                                                    |
| Reply with rich text messages | ✅      | Text and image combined                            |
| Send proactive messages       | ✅      |                                                    |
| Send streaming response       | ❌      |                                                    |

## Discord

### Receive

| Feature                             | Status | Remarks                 |
| ----------------------------------- | ------ | ----------------------- |
| Receive private messages            | ✅      |                         |
| Receive group mention messages      | ✅      |                         |
| Receive group regular messages      | ✅      |                         |
| Receive image messages              | ✅      |                         |
| Receive voice messages              | ❌      |                         |
| Receive file messages               | ✅      |                         |
| Receive rich text messages          | ✅      | Text and image combined |
| Get private message event user name | ✅      |                         |
| Get group message event group name  | ✅      |                         |
| Get group message event sender name | ✅      |                         |

### Send

| Feature                       | Status | Remarks                 |
| ----------------------------- | ------ | ----------------------- |
| Reply to private messages     | ✅      |                         |
| Reply to group messages       | ✅      |                         |
| Reply with image messages     | ✅      | Sent as file attachment |
| Reply with voice messages     | ✅      | Sent as file attachment |
| Reply with file messages      | ✅      |                         |
| Reply with rich text messages | ✅      | Text and file combined  |
| Send proactive messages       | ✅      |                         |
| Send streaming response       | ❌      |                         |

## Telegram

P.S. Not tested

### Receive

| Feature                             | Status | Remarks |
| ----------------------------------- | ------ | ------- |
| Receive private messages            | ✅      |         |
| Receive group mention messages      | ✅      |         |
| Receive group regular messages      | ✅      |         |
| Receive image messages              | ✅      |         |
| Receive voice messages              | ❌      |         |
| Receive file messages               | ✅      |         |
| Receive rich text messages          | ✅      |         |
| Get private message event user name | ✅      |         |
| Get group message event group name  | ✅      |         |
| Get group message event sender name | ✅      |         |

### Send

| Feature                       | Status | Remarks |
| ----------------------------- | ------ | ------- |
| Reply to private messages     | ✅      |         |
| Reply to group messages       | ✅      |         |
| Reply with image messages     | ✅      |         |
| Reply with voice messages     | ✅      |         |
| Reply with file messages      | ✅      |         |
| Reply with rich text messages | ✅      |         |
| Send proactive messages       | ✅      |         |
| Send streaming response       | ❌      |         |

## Slack

## LINE

---

# Troubleshooting

Source: https://langbot.app/docs/en/insight/troubleshooting

Common LangBot local deployment and runtime issues, with symptoms, causes, and fixes. Currently covers Docker deployment issues.

This page collects practical troubleshooting paths for common issues. It currently covers Docker deployment problems. More sections for models, bot adapters, MCP, and Skills can be added later.

The commands below assume you are running them from `LangBot/docker`.

## Docker Deployment

### Preflight Checks

If you need the sandbox, stdio MCP hosting, or Skill add/edit features, start LangBot with the `all` profile:

```bash
docker compose --profile all up -d
```

Check service status:

```bash
docker compose --profile all ps
```

You should see:

- `langbot`: WebUI and backend service, exposing `5300` and `2280-2285` by default.
- `langbot_plugin_runtime`: plugin runtime, exposing `5401` by default.
- `langbot_box`: Box Runtime control plane, used to create sandbox containers.

If you only run `docker compose up`, `langbot_box` is not started. stdio MCP, Skill add/edit, and some sandbox-dependent features will be unavailable.

### Port Conflicts

#### Symptoms

- `docker compose up` fails with a port binding error.
- The WebUI cannot be opened at `http://127.0.0.1:5300`.
- Logs contain `port is already allocated` or `bind: address already in use`.

#### Fix

Find the process using the port. Linux/macOS:

```bash
lsof -i :5300
lsof -i :5401
```

Windows PowerShell:

```powershell
Get-NetTCPConnection -LocalPort 5300,5401 | Select-Object LocalPort,OwningProcess
Get-Process -Id <PID>
```

If it is an old LangBot, plugin runtime, or test process, stop it and start LangBot again:

```bash
docker compose --profile all up -d
```

If the process cannot be stopped, change the matching port mapping in `docker-compose.yaml`.

### Box Runtime Is Not Available

#### Symptoms

- The UI or logs show `No sandbox backend (Docker/nsjail/E2B) is ready`.
- stdio MCP servers are unavailable.
- Skills cannot be installed, activated, or edited.

#### Common Causes

- LangBot was not started with `--profile all` or `--profile box`.
- `langbot_box` is not running.
- Docker Desktop or the current user cannot access Docker.
- On Linux, the current user does not have permission to access the Docker socket.

#### Fix

Make sure `langbot_box` is running:

```bash
docker compose --profile all ps
docker logs langbot_box --tail 100
```

Make sure Docker itself works:

```bash
docker info
```

On Linux, add the current user to the `docker` group if needed, then log in again:

```bash
sudo usermod -aG docker $USER
newgrp docker
docker info
```

Then recreate the containers:

```bash
docker compose --profile all up -d --force-recreate
```

### Box Root Mount Fails

#### Symptoms

- Logs contain `host_path is outside allowed_mount_roots`.
- Logs contain `host_path must point to an existing directory on the host`.
- On Docker Desktop, the Box root is resolved to `/run/desktop/...` and is rejected.
- stdio MCP or Skill sandbox containers cannot be created.

#### Cause

`langbot_box` creates sandbox containers through the host Docker socket. Those sandbox containers see host paths, so the Box root path must be identical on the host and inside the container, and it must be under `allowed_mount_roots`.

#### Fix

Set an absolute path that Docker can mount and that Box security checks can accept in `LangBot/docker/.env`:

```dotenv
LANGBOT_BOX_ROOT=/var/lib/langbot/box
```

On Windows Docker Desktop, use a path visible to the Docker VM, for example:

```dotenv
LANGBOT_BOX_ROOT=/host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
```

Make sure the directory exists, then recreate the containers:

```bash
docker compose --profile all up -d --force-recreate
```

If you previously edited `docker/data/config.yaml` manually, check that it points to the same root:

```yaml
box:
  local:
    host_root: /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
    allowed_mount_roots:
      - /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
```

### Many stdio MCP Servers Fail or Stay Connecting

#### Symptoms

- MCP status stays at `connecting` or becomes `error`.
- `docker logs langbot_box` contains `Cannot fork`.
- After installing many stdio MCP servers, previously working MCP servers also fail to start.

#### Cause

stdio MCP servers run inside the Box sandbox. The default Box profile has a relatively small PID limit. Starting many `npx` or `uvx` based MCP servers at the same time can hit that process limit.

#### Fix

Use the larger built-in Box profile in `docker/data/config.yaml`:

```yaml
box:
  local:
    profile: network_extended
```

Then stop LangBot and Box, remove the old shared sandbox, and recreate the containers.

Linux/macOS:

```bash
docker compose --profile all stop langbot langbot_box
docker rm -f $(docker ps -aq --filter "name=langbot-box-mcp-shared")
docker compose --profile all up -d --force-recreate
```

Windows PowerShell:

```powershell
docker compose --profile all stop langbot langbot_box
docker ps -a --filter "name=langbot-box-mcp-shared" --format "{{.Names}}" | ForEach-Object { docker rm -f $_ }
docker compose --profile all up -d --force-recreate
```

After the MCP servers finish cold starting, check the MCP management page. Target servers should show `connected` and a non-zero tool count.

### MCP Is Installed but Has No Tools or Cannot Connect

#### Symptoms

- The MCP server is listed, but its status is `error` or stays at `connecting`.
- Tool count is `0`.
- Remote MCP logs show `401 Unauthorized`, connection timeout, or handshake failure.

#### Common Causes

- The remote MCP requires an API key or OAuth authorization that is not configured.
- The MCP package is cold starting through `npx` or `uvx`, and dependency download takes time.
- The current Docker network cannot reach the MCP service or package registry.
- The stdio MCP sandbox does not have enough resources.

#### Fix

Prefer MCP servers from LangBot Space that do not require credentials, or make sure credentials are configured correctly. For credentialed MCP servers, fill in the required environment variables, headers, or URL parameters during installation.

Check runtime logs:

```bash
docker logs langbot --tail 200
docker logs langbot_box --tail 200
```

If a server cannot connect in the current environment, disable or delete it from the MCP management page so it does not confuse later checks.

### Image Tag or Registry Is Inconsistent

#### Symptoms

- `docker compose ps` still shows an old image.
- Image registry or tag changes do not take effect after restart.
- `langbot`, `langbot_plugin_runtime`, and `langbot_box` use different image tags.

#### Fix

Keep the three LangBot service image tags consistent, then pull and recreate:

```bash
docker pull rockchin/langbot:latest
docker compose --profile all up -d --force-recreate
```

If you intentionally deploy a non-default tag, update all three image entries in `docker-compose.yaml`: `langbot`, `langbot_plugin_runtime`, and `langbot_box`.

### Post-Fix Verification

After applying a fix, run a full check:

```bash
docker compose --profile all ps
docker inspect langbot langbot_plugin_runtime langbot_box --format '{{.Name}} {{.Config.Image}} {{.State.Status}}'
```

Check the WebUI:

```bash
curl -I http://127.0.0.1:5300/
```

Then confirm in the UI:

- Login works.
- Box / sandbox features are available.
- Target MCP servers show `connected`.
- stdio MCP servers show the expected tool count.

---

# Certified plugins and shared runtime

Source: https://langbot.app/docs/en/plugin/certified-plugins

What certification is, why it exists, when you need it, and the shared-runtime-v1 / stateless-v1 contract.

## What certification is

Certification is a grant LangBot makes for **one exact, immutable plugin artifact**: that artifact is approved to run **shared across tenants** in LangBot Cloud.

- Certification is bound to the artifact itself (a specific published version, identified by digest), not to a plugin name or an author. Publishing a new version does not carry the previous version's certification over.
- Certification is not a quality score and not a security audit endorsement.

## Why certification exists

LangBot does not place plugins in shared mode by default. The reason is that sharing is keyed by artifact:

- **Dedicated mode**: the plugin does not participate in sharing and runs on its own.
- **Shared mode**: every installation of the same artifact digest shares one Worker.

Sharing keeps the number of processes and the startup cost from growing linearly with the number of installations. The trade-off is that **one process handles calls from several Workspaces at once** — so a plugin that keeps tenant data on its instances will leak it between tenants.

The platform therefore has to review this exact artifact, confirm it satisfies the stateless contract, and then pin that trust to the artifact with a signature before it may enter shared placement. That is what certification is for.

## When you need certification

**Most plugins do not need certification.** Skipping it does not stop you from publishing to the marketplace, and it does not stop users from installing your plugin — it simply runs in dedicated mode.

| Your situation                                                                                        | Certification needed?                   |
| ----------------------------------------------------------------------------------------------------- | --------------------------------------- |
| You only want to publish the plugin so users can install it                                           | No                                      |
| The plugin needs process-local state across calls (for example a long-lived external session process) | No — and it should stay dedicated       |
| The plugin has background tasks, timers, or long-lived tenant caches                                  | No — dedicated mode is the safer choice |
| You want the Certified Plugin badge                                                                   | Yes                                     |
| You want several installations of one artifact to share a process, reducing cost and startup overhead | Yes                                     |
| The plugin targets Cloud multi-tenant scenarios and you want shared placement                         | Yes                                     |

The test is a single question: **certification only makes sense if your code genuinely keeps no tenant or installation data on its instances.**

## What certification changes

After review passes:

- The artifact is signed and installed in **shared mode**; multiple installations of the same digest share one Worker.
- That Worker holds one `BasePlugin` object and one instance per declared component manifest (EventListener, Tool, Command, KnowledgeEngine, Parser, Page, Runner).
- Each installation adds only a lightweight layer of configuration, authority and lifecycle context; the active one is selected per call.
- You receive the Certified Plugin badge.
- Self-hosted OSS ships without a certification issuer public key, so a certified artifact still runs dedicated on self-hosted instances.

You also take on a standing obligation: **every later version must keep satisfying the stateless contract.** After changing code you submit a new version for review; certification does not renew itself.

## What you must adapt

### Declaration

Declare both fields under `execution` in `manifest.yaml`:

```yaml
apiVersion: v1
kind: Plugin
metadata:
  author: your-name
  name: YourPlugin
  version: 0.1.1
spec:
  config: []
  components: {}
execution:
  python:
    path: main.py
    attr: YourPlugin
  sharedRuntime: shared-runtime-v1
  componentModel: stateless-v1
```

| Field                      | Accepted value      | Notes                                                                    |
| -------------------------- | ------------------- | ------------------------------------------------------------------------ |
| `execution.sharedRuntime`  | `shared-runtime-v1` | This is the only accepted value; anything else fails manifest validation |
| `execution.componentModel` | `stateless-v1`      | This is the only accepted value                                          |

- Both fields **must be declared together**. A package that declares `sharedRuntime` without `componentModel` is rejected during certification validation.
- The fields are recognised from **SDK 0.7.0** onwards. Earlier SDKs ignore them, so do not rely on an old SDK to tell you whether the declaration took effect.

> warning:
>
> A declaration is an application, not approval. It grants no badge and does not change how the plugin runs by itself.

### Stateless constraints

- `BasePlugin.initialize()` and component `initialize()` are **process-scoped** and run once per Worker. At that point there is no "current installation" and no "current Workspace".
- Component instances are called concurrently by different Workspaces, so every method must be re-entrant.
- Read the active installation configuration per call: `self.get_config()` on `BasePlugin`, `self.get_plugin_config()` or `self.plugin.get_config()` in a component, and `ctx.config` in a Runner.
- Never store configuration, credentials, Workspace or installation identity, or request data in instance fields or module-level globals.
- Do not read and cache installation configuration in `initialize()`.
- Reach storage, files, credentials, logs, models and other platform capabilities through the SDK Host APIs. Authority is resolved per call; do not cache it yourself.
- Durable tenant state belongs in Host services. Runners use `ctx.state_get()` / `ctx.state_set()` and friends (this requires `ctx.context.available_apis.state` to be `true`). In-process caches may hold artifact-level public data only; if you must cache tenant data, the key has to include the complete installation identity and must be cleaned up when the installation is removed.
- Do not start tenant-bearing background tasks or threads: the SDK does **not** track ownership of work you create. If you must detach work, keep a registry keyed by the installation binding and stop it in `on_installation_revoked()`. Once a handler returns, that invocation's context and run-associated calls are no longer valid.

### One installation, many usages

A Workspace installs each plugin once, but that single installation is reused by **several product objects**:

| Component kind                                   | What reuses it                                     | What isolates it                                                                                      |
| ------------------------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Runner in an Agent or Pipeline                   | every processor                                    | `ctx.state.*` is already per-processor (scopes carry `binding_identity`, derived from the Agent UUID) |
| KnowledgeEngine / Parser behind a knowledge base | every knowledge base                               | **your plugin must isolate by knowledge-base ID itself**                                              |
| Tool / Command / EventListener / Page            | several processors, conversations or page requests | read per call; never accumulate on the instance                                                       |

The platform storage key is `(instance, Workspace, owner type, plugin, key)` and carries **no processor or knowledge-base dimension**. So whenever your plugin persists or caches anything, it must put the product object's identity into the key:

- **Config**: read per call (`ctx.config`, or the task-local `self.get_plugin_config()`); never cache it on the instance.
- **Persistence**: keys must include the product identity (processor identity / knowledge-base ID / conversation identity).
- **Process-local caches**: keys must include both the full installation binding **and** the product identity, and must be released when the installation is revoked (below).
- **Locks and fences**: key them by `(installation, product object)`. **A failure in one processor or knowledge base must not block the others of the same installation.**
- **Failure grading**: only a dispatched mutation with an unknown outcome should enter a state that needs manual reconciliation; deterministic validation errors and pre-dispatch cancellation must not affect later calls.
- **Logs and telemetry**: a diagnostic failure must not affect the work, and tenant data must not be written into a process-wide singleton.

### When an installation is revoked

Under shared placement one object graph serves every installation of the artifact, so **revoking one installation does not destroy it**. The plugin must release binding-keyed process-local state itself:

```python
class MyPlugin(BasePlugin):
    def __init__(self) -> None:
        super().__init__()
        self._caches: dict[str, Cache] = {}

    async def on_installation_revoked(self, binding) -> None:
        self._caches.pop(binding.installation_uuid, None)
```

- **Fires for** uninstall, disable, Workspace removal and upgrade (the superseded binding is revoked). It runs only under shared placement; dedicated workers are shut down, so their process-local state disappears with the process.
- **There is no active invocation**, so Host APIs (storage, config, binding lookups) are unavailable — you can only release process-local state, and the installation is identified by the argument.
- Exceptions are logged and **never block revocation**.
- It requires an SDK version that provides `BasePlugin.on_installation_revoked`; on older versions the hook is simply never called.

### Allowed / forbidden

| Concern                         | Allowed                                                                                             | Forbidden                                                                              |
| ------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Reading config                  | Read per call (`self.get_plugin_config()`, `ctx.config`)                                            | Reading in `initialize()` and keeping it on `self`                                     |
| Connection pools / HTTP clients | Shared pools without tenant credentials                                                             | Baking an installation's endpoint or API key into the instance                         |
| Caching                         | Artifact-level public data; or keys including the full installation identity and supporting cleanup | A module-level `dict` keyed by Workspace or user that persists                         |
| Cross-invocation state          | Host services (`ctx.state_*` in a Runner)                                                           | Instance fields, module globals                                                        |
| Background work                 | None                                                                                                | Holding an invocation's context or its run-associated calls after the handler returned |
| Logging                         | `ctx.log()` or SDK logging APIs                                                                     | A module-level background thread printing tenant config or credentials                 |

### Common anti-patterns

**1. Reading installation config during initialization**

```python
async def initialize(self):
    self.endpoint = self.plugin.config["endpoint"]  # process-scoped init has no active installation
    self.api_key = self.plugin.config["api_key"]
```

Shared initialization has no installation configuration, so this reads empty or stale values.

**2. Caching tenant data in a module global**

```python
_CACHE = {}  # keyed by Workspace or user; persists across installations and tenants

async def call(self, params, **kwargs):
    if params["user"] not in _CACHE:
        _CACHE[params["user"]] = await fetch(params["user"])
```

**3. Keeping work alive after the handler returns**

```python
async def call(self, params, **kwargs):
    config = self.get_plugin_config()
    asyncio.create_task(self._upload_later(config))  # handler already returned; context and authority are gone
    return ok()
```

**4. Treating instance fields as a config container**

```python
async def initialize(self):
    self.default_endpoint = "https://api.example.com"  # a public constant is fine
    self.last_config = {}  # writing installation config here is not
```

The correct shape:

```python
class LookupTool(Tool):
    async def initialize(self):
        # artifact-level objects only, no tenant information
        self.transport = StatelessHTTPTransport()

    async def call(self, params, **kwargs):
        config = self.get_plugin_config()  # read for the active installation on every call
        return await self.transport.lookup(config["endpoint"], params)
```

### Runners in particular

Runners have the most tension with the stateless contract, because a runner naturally tends to keep sessions and context in the process.

- A `RunnerContext` is **valid only for the current run**. Do not keep it, or anything derived from it, on the instance for reuse across calls.
- Session state a Runner needs across calls belongs in `ctx.state_get()` / `ctx.state_set()` (scopes: `conversation`, `actor`, `subject`, `runner`) or another Host-provided store — not in instance fields.
- After a handler returns, do not keep using `ctx` in background tasks, and do not keep using run-associated calls made through `self.plugin`.
- If your Runner fundamentally depends on process-local state across calls (for example a long-lived external session process), **do not declare `stateless-v1`** and stay on a dedicated Worker.

See [Runner context](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md) for the full context API.

## Self-check and submission

Verify each item before submitting:

- [ ] Both fields are declared in `manifest.yaml` with the exact accepted values.
- [ ] A repository-wide search confirms there are no module-level mutable globals.
- [ ] `initialize()` performs process-scoped setup only and reads no installation config.
- [ ] Every piece of installation config is read at call time.
- [ ] No task or thread keeps running after a handler returns.
- [ ] Cross-call state goes through Host APIs (`ctx.state_*` in a Runner).

### How to submit

Certification uses the same path as publishing, with no extra process: declare the two fields above in `manifest.yaml`, then submit a **new version** with `lbp publish` as usual (a published version cannot have the declaration added later). LangBot Space checks the exact submitted package, runs an advisory code review, and issues the Certified Plugin badge after human approval; certification is bound to the reviewed version and checksum.

If the review finds that the release cannot meet the requirements, publish it as an unsigned normal plugin first and fix the findings in a later immutable version.

If this check shows your plugin is not a good fit for sharing, just publish it as a normal plugin — certification is optional. See [Publish to the marketplace](https://langbot.app/docs/en/plugin/dev/publish/market.md) for the publishing flow.

---

# System Compatibility

Source: https://langbot.app/docs/en/plugin/compatibility

LangBot's plugin system utilizes mechanisms such as `Asyncio` and `Subprocess`, which work well on Unix-like systems (such as Linux, macOS), but have some issues on Windows, preventing plugins from running properly.

Python's asynchronous event loop on Windows defaults to using `ProactorEventLoop`, but this event loop lacks support for Stdio, while LangBot in non-Docker environments relies on Stdio to communicate with Plugin Runtime, and Plugin Runtime also depends on Stdio to communicate with plugins.

If we switch to using `SelectorEventLoop`, it would prevent Plugin Runtime and plugins from starting properly, as `SelectorEventLoop` does not support `Subprocess`.

For detailed information about these issues, please refer to: [Python Official Documentation](https://docs.python.org/3.13/library/asyncio-platforms.html)

## Solution

Unlike the tight coupling between subprocess management and Stdio communication on Unix-like systems, LangBot and the Plugin Runtime automatically switch to a hybrid subprocess + WebSocket communication strategy on Windows. LangBot still launches the Plugin Runtime via a subprocess, but communicates with it over WebSocket; similarly, the Plugin Runtime starts each installed plugin via subprocesses while communicating with them through WebSocket.

This behavior is automatically selected based on the OS, so no manual configuration is required.

---

# Context APIs

Source: https://langbot.app/docs/en/plugin/dev/apis/agent-run

A context contains data for one component invocation. Each component receives a different context, so start with the entry point for your component.

| Component          | Handler entry point                    | Context type                           |
| ------------------ | -------------------------------------- | -------------------------------------- |
| EventListener      | `handler(event_context)`               | `EventContext`                         |
| Command            | `subcommand(context)`                  | `ExecuteContext`                       |
| Tool               | `call(params, session, query_id)`      | No separate context object             |
| Runner             | `run(ctx)` or `handler(ctx)`           | `RunnerContext`                        |
| KnowledgeEngine    | `ingest(context)`, `retrieve(context)` | `IngestionContext`, `RetrievalContext` |
| KnowledgeRetriever | `retrieve(context)`                    | `RetrievalContext`                     |
| Parser             | `parse(context)`                       | `ParseContext`                         |
| Page               | `handle_api(request)`                  | `PageRequest`                          |

This page covers the data and methods available through these contexts. Use `self.plugin` for models, knowledge bases, storage, and other LangBot capabilities; see [LangBot API](https://langbot.app/docs/en/plugin/dev/apis/common.md). For platform operations, see [Platform API](https://langbot.app/docs/en/plugin/dev/apis/platform.md).

`EventContext`, `ExecuteContext`, and `Session` also carry `instance_uuid`, `workspace_uuid`, and `placement_generation`. These fields identify the current instance and workspace for execution; plugins must not treat them as authorization data.

## EventListener

EventListener handles Pipeline events. Its event handler receives an `EventContext`:

```python
event = event_context.event
sender_id = event.sender_id
```

### Context data

| Property               | Type             | Description                                                                   |
| ---------------------- | ---------------- | ----------------------------------------------------------------------------- |
| `event`                | `BaseEventModel` | Current event object; its actual type matches the registered event type       |
| `event_name`           | `str`            | Current event class name                                                      |
| `query_id`             | `int`            | Current Pipeline request ID                                                   |
| `query_uuid`           | `str \| None`    | Stable identifier for the current Pipeline request                            |
| `eid`                  | `int`            | Temporary event number inside Plugin Runtime; do not persist it               |
| `is_prevent_default`   | `bool`           | Whether default handling has been stopped; change it with `prevent_default()` |
| `is_prevent_postorder` | `bool`           | Whether later plugins have been stopped; change it with `prevent_postorder()` |

See [Pipeline Events](https://langbot.app/docs/en/plugin/dev/apis/pipeline-events.md) for event fields and all supported event types.

### Context methods

| Method                                                                             | Return value           | Description                                                                 |
| ---------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------- |
| `await event_context.reply(message_chain, quote_origin=False)`                     | -                      | Reply in the conversation for the current request                           |
| `await event_context.get_bot_uuid()`                                               | `str`                  | Get the source bot UUID                                                     |
| `await event_context.set_query_var(key, value)`                                    | -                      | Set a variable on the current request                                       |
| `await event_context.get_query_var(key)`                                           | `Any`                  | Get one request variable                                                    |
| `await event_context.get_query_vars()`                                             | `dict[str, Any]`       | Get all request variables                                                   |
| `await event_context.create_new_conversation()`                                    | `dict[str, Any]`       | Clear the current Pipeline conversation so a later request starts a new one |
| `await event_context.list_pipeline_knowledge_bases()`                              | `list[dict[str, Any]]` | List knowledge bases bound to the current Pipeline Local Agent              |
| `await event_context.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)` | `list[dict[str, Any]]` | Search a knowledge base bound to the current Pipeline                       |
| `event_context.prevent_default()`                                                  | -                      | Stop the default handling of the current event                              |
| `event_context.prevent_postorder()`                                                | -                      | Stop later plugins from handling the current event                          |

`reply()` accepts a [MessageChain](https://langbot.app/docs/en/plugin/dev/apis/messages.md). Request variables, replies, and Pipeline knowledge-base methods require an associated Pipeline request. The `kb_id` passed to `retrieve_knowledge()` must come from `list_pipeline_knowledge_bases()`.

`prevent_default()` only affects Pipeline events whose default flow can be stopped. See [Pipeline Events](https://langbot.app/docs/en/plugin/dev/apis/pipeline-events.md#prevent-default-behavior).

## Command

A Command subcommand handler receives an `ExecuteContext`:

```python
query = " ".join(context.crt_params)
session = context.session
```

### Context data

| Property            | Type          | Description                                          |
| ------------------- | ------------- | ---------------------------------------------------- |
| `session`           | `Session`     | Session that contains the current message            |
| `command_text`      | `str`         | Complete command text without the command prefix     |
| `full_command_text` | `str`         | Complete command text including the prefix           |
| `command`           | `str`         | Root command name                                    |
| `crt_command`       | `str`         | Subcommand currently being executed                  |
| `params`            | `list[str]`   | All arguments after the root command                 |
| `crt_params`        | `list[str]`   | Arguments not yet consumed by the current subcommand |
| `privilege`         | `int`         | Command privilege level of the current user          |
| `query_id`          | `int`         | Current Pipeline request ID                          |
| `query_uuid`        | `str \| None` | Stable identifier for the current Pipeline request   |

The SDK calls `context.shift()` before entering the current subcommand. Components do not need to call it directly.

### Context methods

| Method                                                                       | Return value           | Description                                                                 |
| ---------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------- |
| `await context.reply(message_chain, quote_origin=False)`                     | -                      | Reply in the conversation for the current request                           |
| `await context.get_bot_uuid()`                                               | `str`                  | Get the source bot UUID                                                     |
| `await context.set_query_var(key, value)`                                    | -                      | Set a variable on the current request                                       |
| `await context.get_query_var(key)`                                           | `Any`                  | Get one request variable                                                    |
| `await context.get_query_vars()`                                             | `dict[str, Any]`       | Get all request variables                                                   |
| `await context.create_new_conversation()`                                    | `dict[str, Any]`       | Clear the current Pipeline conversation so a later request starts a new one |
| `await context.list_pipeline_knowledge_bases()`                              | `list[dict[str, Any]]` | List knowledge bases bound to the current Pipeline Local Agent              |
| `await context.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)` | `list[dict[str, Any]]` | Search a knowledge base bound to the current Pipeline                       |

These request methods behave the same as their EventListener equivalents. See [Command](https://langbot.app/docs/en/plugin/dev/components/command.md) for registration and return values.

## Tool

Tool has no separate context object. Its `call()` parameters carry the invocation data:

```python
conversation_type = session.launcher_type.value
conversation_id = session.launcher_id
sender_id = session.sender_id
```

| Parameter  | Description                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------- |
| `params`   | Arguments generated by the model or caller from the tool JSON Schema                        |
| `session`  | Current session data                                                                        |
| `query_id` | Current Pipeline request ID; pass it unchanged to LangBot APIs that require request context |

Common `Session` properties are:

| Property                     | Description                                   |
| ---------------------------- | --------------------------------------------- |
| `launcher_type`              | Conversation type: `person` or `group`        |
| `launcher_id`                | Private-chat user or group ID                 |
| `sender_id`                  | Current message sender ID                     |
| `bot_uuid`                   | Current bot UUID                              |
| `using_conversation`         | Current Pipeline conversation                 |
| `conversations`              | Pipeline conversations stored in this Session |
| `use_prompt_name`            | Active prompt name                            |
| `create_time`, `update_time` | Session creation and update times             |

`session` is a data object and has no context methods such as `reply()`. A tool return value goes back to its caller; it is not sent to the chat platform automatically. Use `self.plugin` for LangBot and platform capabilities. If an API requires `session` and `query_id`, pass the values received by the current call.

## Runner

Both custom `run(ctx)` implementations and Runner event handlers receive a `RunnerContext`. It remains valid only while the current invocation is running.

```python
text = ctx.input.to_text()
event_type = ctx.event.event_type
```

### Context data

| Property         | Type                          | Description                                                                 |
| ---------------- | ----------------------------- | --------------------------------------------------------------------------- |
| `run_id`         | `str`                         | Current run ID                                                              |
| `trigger`        | `AgentTrigger`                | Trigger type, source, and time                                              |
| `event`          | `AgentEventContext`           | Standard event envelope with the event ID, type, source, time, and raw data |
| `platform_event` | Platform event type           | Platform event parsed into its specific event type                          |
| `conversation`   | `ConversationContext \| None` | Current conversation, thread, bot, and workspace identifiers                |
| `actor`          | `ActorContext \| None`        | Actor that caused the event                                                 |
| `subject`        | `SubjectContext \| None`      | Message, group, or other object affected by the event                       |
| `input`          | `AgentInput`                  | Current text, structured content, and attachments                           |
| `delivery`       | `DeliveryContext`             | Output target and streaming, editing, and reaction capabilities             |
| `resources`      | `AgentResources`              | Models, tools, knowledge bases, skills, and storage authorized for this run |
| `context`        | `ContextAccess`               | Conversation cursors, inline policy, and available context APIs             |
| `state`          | `AgentRunState`               | Scope-specific state snapshot loaded at the start of the run                |
| `runtime`        | `AgentRuntimeContext`         | LangBot version, trace ID, and deadline                                     |
| `config`         | `dict[str, Any]`              | Current Agent or plugin-processor configuration                             |
| `adapter`        | `AdapterContext \| None`      | Additional entry-adapter data                                               |
| `variables`      | `dict[str, Any]`              | Public request variables for Runner templates                               |
| `metadata`       | `dict[str, Any]`              | Other metadata supplied by the Host                                         |

Prefer the stable properties in this table. `event.data` and `adapter.extra` carry additional data that has not been promoted to stable fields.

### Replies and logs

| Method                                               | Return value          | Description                                                                 |
| ---------------------------------------------------- | --------------------- | --------------------------------------------------------------------------- |
| `await ctx.get_bot_uuid()`                           | `str`                 | Get the source bot UUID; raises an error when no bot is associated          |
| `await ctx.reply(message_chain, quote_origin=False)` | `Any`                 | Reply to the current event with a string or `MessageChain`                  |
| `ctx.reply_stream()`                                 | Async context manager | Stream full-text updates to one reply                                       |
| `await ctx.log(text, level="info")`                  | -                     | Write to this run's log; levels are `debug`, `info`, `warning`, and `error` |

Each `reply_stream().update(text)` call supplies the complete current text. If the platform does not support streaming, LangBot sends one complete message when the stream finishes. Debug mode only simulates delivery.

### Available tools

| Method                                            | Return value           | Description                                                                                 |
| ------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------- |
| `await ctx.get_available_tools()`                 | `list[dict[str, Any]]` | Get context actions, platform APIs, plugin tools, and MCP tools callable in this invocation |
| `await ctx.call_tool(tool_name, parameters=None)` | `dict[str, Any]`       | Call a tool from that list                                                                  |

Each item returned by `get_available_tools()` contains `name`, `description`, `parameters`, `type`, and `operations`. The result is already filtered by the current Agent or plugin-processor configuration and the event's capabilities. `ctx.call_tool()` cannot call a tool absent from this list.

### Box and attachments

The Runner owns enablement, acquisition, and reuse policy. Use the [LangBot Box APIs](https://langbot.app/docs/en/plugin/dev/apis/common.md#box-sandbox) for resources and these context methods for the current run.

| Method                                                  | Returns         | Behavior                                                                    |
| ------------------------------------------------------- | --------------- | --------------------------------------------------------------------------- |
| `await ctx.bind_box(box_id)`                            | `BoxBinding`    | Bind a Workspace Box; returns `box_id`, `outbox`. A run cannot switch Boxes |
| `await ctx.import_box_attachments(attachment_ids=None)` | `list[BoxFile]` | Import selected input `ref` values, or all inputs; returns sandbox paths    |
| `await ctx.export_box_files()`                          | `list[BoxFile]` | Export this run's outbox as file handles; sends no message                  |
| `await ctx.reply_files(file_ids)`                       | `Any`           | Reply with exported IDs, subject to event reply authorization               |

`BoxFile` contains `id`, `name`, `type`, `size`, and optional `path`. Original attachment URLs and content remain available. Files are staged only on explicit import. Output handles belong to this run and cannot be sent twice.

Bind before native sandbox tools or file operations. Runs sharing a Box still have separate attachment directories. `ctx.variables` contains public request variables for computing reuse keys.

`ctx.delivery.automatic_reply` is `True` for Pipeline execution: return files using `RunnerResult.message_completed(ctx.run_id, message, file_ids=[...])`. Agents and plugin processors explicitly call `ctx.reply_files()`.

External runners use the same flow through `AgentRunExternalTools`: `langbot_get_box_status`, `langbot_list_boxes`, `langbot_acquire_box`, `langbot_bind_box`, `langbot_import_box_attachments`, and `langbot_export_box_files`. `langbot_reply_files` is available when the run has event reply permission. All calls retain the current run authorization.

### Prompt, history, and events

| Method                                                                                                                                           | Return value           | Availability field |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------ |
| `await ctx.get_prompt()`                                                                                                                         | `list[dict[str, Any]]` | `prompt_get`       |
| `await ctx.history_page(conversation_id=None, before_cursor=None, after_cursor=None, limit=50, direction="backward", include_attachments=False)` | `HistoryPage`          | `history_page`     |
| `await ctx.history_search(query, filters=None, top_k=10)`                                                                                        | `HistorySearchResult`  | `history_search`   |
| `await ctx.event_get(event_id)`                                                                                                                  | `AgentEventRecord`     | `event_get`        |
| `await ctx.event_page(conversation_id=None, event_types=None, before_cursor=None, limit=50)`                                                     | `EventPage`            | `event_page`       |
| `await ctx.steering_pull(mode="all", limit=None)`                                                                                                | `SteeringPullResult`   | `steering_pull`    |

### State

| Method                                                | Return value     | Description                           |
| ----------------------------------------------------- | ---------------- | ------------------------------------- |
| `await ctx.state_get(scope, key)`                     | `dict[str, Any]` | Read a state value                    |
| `await ctx.state_set(scope, key, value)`              | `dict[str, Any]` | Store a JSON-serializable state value |
| `await ctx.state_delete(scope, key)`                  | `dict[str, Any]` | Delete a state value                  |
| `await ctx.state_list(scope, prefix=None, limit=100)` | `dict[str, Any]` | List state keys in a scope            |

`scope` can be `conversation`, `actor`, `subject`, or `runner`. These methods require `ctx.context.available_apis.state` to be `true`.

### Run records

| Method                                                                                                         | Return value    | Availability field  |
| -------------------------------------------------------------------------------------------------------------- | --------------- | ------------------- |
| `await ctx.run_get(run_id=None)`                                                                               | `AgentRun`      | `run_get`           |
| `await ctx.run_list(conversation_id=None, statuses=None, before_cursor=None, limit=50)`                        | `RunPage`       | `run_list`          |
| `await ctx.run_events_page(run_id=None, before_cursor=None, after_cursor=None, limit=50, direction="forward")` | `RunEventPage`  | `run_events_page`   |
| `await ctx.run_cancel(run_id=None, reason=None)`                                                               | `AgentRun`      | `run_cancel`        |
| `await ctx.run_append_result(result)`                                                                          | `AgentRunEvent` | `run_append_result` |
| `await ctx.run_finalize(run_id=None, status=None, reason=None)`                                                | `AgentRun`      | `run_finalize`      |

`run_id=None` refers to the current run. The SDK completes a normal event handler automatically. When a custom `run(ctx)` yields `RunnerResult`, do not register the same result again with `run_append_result()`.

### Availability and authorization

Use `ctx.context.available_apis` to check whether prompt, history, event, state, and run-record methods are available. Authorized models, tools, and knowledge bases are in `ctx.resources.models`, `ctx.resources.tools`, and `ctx.resources.knowledge_bases`.

During Runner execution, model, tool, knowledge-base, storage, and platform calls through `self.plugin` are automatically associated with the current run and validated against `ctx.resources`. Do not pass `run_id`. After the handler returns, do not use this context or its run-bound calls from background tasks.

`ctx.api` is the lower-level run-scoped proxy. Normal component code should prefer the `ctx` methods listed on this page and use `self.plugin` for LangBot APIs.

## Data-only contexts

The following components receive task input rather than an EventListener or Runner execution context. Their fields, return values, and complete examples live in the corresponding component guides.

| Component entry point                                    | Main data                                                        | Component guide                                                                                                  |
| -------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `KnowledgeEngine.ingest(context: IngestionContext)`      | File, target knowledge base, creation settings, and parse result | [KnowledgeEngine](https://langbot.app/docs/en/plugin/dev/components/knowledge-engine.md#document-ingestion)      |
| `KnowledgeEngine.retrieve(context: RetrievalContext)`    | Query, target knowledge base, retrieval settings, and filters    | [KnowledgeEngine](https://langbot.app/docs/en/plugin/dev/components/knowledge-engine.md#knowledge-retrieval)     |
| `KnowledgeRetriever.retrieve(context: RetrievalContext)` | Query and external knowledge-base settings                       | [KnowledgeRetriever](https://langbot.app/docs/en/plugin/dev/components/knowledge-retriever.md#retrieval-context) |
| `Parser.parse(context: ParseContext)`                    | File content, filename, MIME type, and metadata                  | [Parser](https://langbot.app/docs/en/plugin/dev/components/parser.md#parse-method)                               |
| `Page.handle_api(request: PageRequest)`                  | Endpoint, HTTP method, body, and headers                         | [Page](https://langbot.app/docs/en/plugin/dev/components/page.md#pagerequest-fields)                             |

---

# LangBot API

Source: https://langbot.app/docs/en/plugin/dev/apis/common

Use `self.plugin` for models, tools, knowledge bases, and storage. For the current event, replies, and conversation state, see [Context APIs](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md).

## LangBot API

These APIs can be called in any plugin component. Access methods:

- In the plugin root directory `main.py`: Internal methods of the `self` object, these APIs are all provided by the plugin class parent class `BasePlugin`.
- In regular plugin component classes: Internal methods of the `self.plugin` object.

### Get Plugin Configuration

Plugin configuration format can be written in `manifest.yaml`, and users need to fill it out according to the plugin configuration format in LangBot's plugin management. Plugin code can then call this API to get plugin configuration information.

```python
def get_config(self) -> dict[str, typing.Any]:
    """Get the config of the plugin."""

# Usage example
config = self.plugin.get_config()
```

### Get LangBot Version

Get the LangBot version number, returned as a string in format `v<major>.<minor>.<patch>`.

```python
async def get_langbot_version(self) -> str:
    """Get the langbot version"""

# Usage example
langbot_version = await self.plugin.get_langbot_version()
```

### Get Configured Bot List

Returns a list of all bot UUIDs.

```python
async def get_bots(self) -> list[str]:
    """Get all bots"""

# Usage example
bots = await self.plugin.get_bots()
```

### Get Bot Information

Get bot information.

```python
async def get_bot_info(self, bot_uuid: str) -> dict[str, Any]:
    """Get a bot info"""

# Usage example
bot_info = await self.plugin.get_bot_info("de639861-be05-4018-859b-c2e2d3e0d603")

# Return example
{
    "uuid": "de639861-be05-4018-859b-c2e2d3e0d603",
    "name": "aiocqhttp",
    "description": "Migrated from LangBot v3",
    "adapter": "aiocqhttp",
    "enable": true,
    "use_pipeline_name": "ChatPipeline",
    "use_pipeline_uuid": "c30a1dca-e91c-452b-83ec-84d635a30028",
    "created_at": "2025-05-10T13:53:08",
    "updated_at": "2025-08-12T11:27:30",
    "adapter_runtime_values": {  # Present if the bot is currently running
        "bot_account_id": 960164003  # Bot account ID
    }
}
```

### Send Proactive Message

Send proactive messages through bot UUID and target session ID.

For message chain construction methods, please refer to [Message Platform Entities](https://langbot.app/docs/en/plugin/dev/apis/messages.md).

```python
async def send_message(
    self,
    bot_uuid: str,
    target_type: str,
    target_id: str,
    message_chain: platform_message.MessageChain,
) -> None:
    """Send a message to a session"""

# Usage example
await self.plugin.send_message(
    bot_uuid="de639861-be05-4018-859b-c2e2d3e0d603",
    target_type="person",
    target_id="1010553892",
    message_chain=platform_message.MessageChain([platform_message.Plain(text="Hello, world!")]),
)
```

### Get Configured LLM Model List

Returns a list of UUIDs for all configured LLM models.

```python
async def get_llm_models(self) -> list[str]:
    """Get all LLM models"""

# Usage example
llm_models = await self.plugin.get_llm_models()
```

### Invoke LLM Model

Invoke an LLM model, returns an LLM message. Non-streaming.

```python
async def invoke_llm(
    self,
    llm_model_uuid: str,
    messages: list[provider_message.Message],
    funcs: list[resource_tool.LLMTool] = [],
    extra_args: dict[str, Any] = {},
    timeout: float | None = None,
    *,
    reasoning_level: ReasoningLevel | None = None,
) -> provider_message.Message:
    """Invoke an LLM model"""

# Usage example
llm_message = await self.plugin.invoke_llm(
    llm_model_uuid="llm_model_uuid",
    messages=[provider_message.Message(role="user", content="Hello, world!")],
    funcs=[],
    extra_args={},
)
```

### Reasoning level

All model invocation methods above accept the optional keyword-only `reasoning_level` parameter:

```python
response = await self.plugin.invoke_llm(
    llm_model_uuid=model_uuid,
    messages=[provider_message.Message(role="user", content="Analyze this problem")],
    reasoning_level="medium",
)
```

Values are `provider_default`, `disabled`, `enabled`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Available levels depend on the model. LangBot validates support and translates the level into provider parameters; unsupported levels raise an error.

- Omitted or `None`: preserves existing model configuration and `extra_args` behavior.
- `provider_default`: adds no explicit reasoning level.
- Other levels: apply to this call only. Do not also supply provider-specific reasoning parameters through `extra_args`.

Runners read their own configuration and explicitly pass the appropriate level for each call, including fallback models and tool follow-ups. LangBot does not extract reasoning levels from Runner configuration. Existing plugins require no changes; when an explicit option is used with an unsupported Host, the SDK requests an upgrade before invoking the model.

### Model streaming and usage

| Method                                                                                                            | Returns                            |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `invoke_llm_with_usage(llm_model_uuid, messages, funcs=[], extra_args={}, timeout=None, *, reasoning_level=None)` | `LLMInvokeResult`                  |
| `invoke_llm_stream(llm_model_uuid, messages, funcs=[], extra_args={}, *, reasoning_level=None)`                   | Async iterator of `MessageChunk`   |
| `invoke_llm_stream_events(llm_model_uuid, messages, funcs=[], extra_args={}, *, reasoning_level=None)`            | Async iterator of `LLMStreamEvent` |

Parameters match `invoke_llm`. `timeout` is in seconds; non-streaming calls default to 120 seconds. Use `invoke_llm_with_usage` when token usage is needed:

```python
from langbot_plugin.api.entities.builtin.provider.message import Message

result = await self.plugin.invoke_llm_with_usage(
    llm_model_uuid=model_uuid,
    messages=[Message(role="user", content="Hello!")],
)
print(result.message.content)
if result.usage is not None:
    print(result.usage.total_tokens)
```

`usage` may be `None`; `prompt_tokens`, `completion_tokens`, and `total_tokens` may also be absent. Missing values do not mean zero usage. Additional provider fields, such as cache usage, are preserved.

```python
async for event in self.plugin.invoke_llm_stream_events(
    llm_model_uuid=model_uuid,
    messages=[Message(role="user", content="Hello!")],
):
    if event.chunk is not None:
        print(event.chunk.content)
    if event.usage is not None:
        print(event.usage.model_dump())
```

`LLMStreamEvent` has optional `chunk` and `usage`; the final event may contain usage without text. `invoke_llm_stream` yields only message/tool-call chunks. `MessageChunk.content` is the current chunk; `all_content`, when supplied, is accumulated text. Replace with accumulated text and append only deltas; an `is_final` chunk may still carry text. Model streaming does not send platform messages; see [Run Context APIs](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md) for explicit streaming replies.

### List Available Parsers

List Parser plugins currently available on the host, optionally filtered by MIME type.

```python
async def list_parsers(self, mime_type: str | None = None) -> list[dict[str, Any]]:
    """List available Parser plugins"""

# Usage example
parsers = await self.plugin.list_parsers(mime_type="application/pdf")
# Each item includes plugin_id, plugin_author, plugin_name, name, description, supported_mime_types
```

### List All Available Tools

List all available tools in the current LangBot instance (including plugin tools and MCP tools).

```python
async def list_tools(self) -> list[dict[str, Any]]:
    """List all available tools

    Returns:
        A list of tool dicts, each containing:
        - name: Tool name
        - label: Display label (i18n)
        - description: Tool description (i18n)
        - icon: Tool icon
        - spec: Tool specification (includes llm_prompt and parameters)
    """

# Example
tools = await self.plugin.list_tools()
for tool in tools:
    print(f"Tool: {tool['name']}")
```

### Get Tool Detail

Get detailed information about a specific tool.

```python
async def get_tool_detail(self, tool_name: str) -> dict[str, Any]:
    """Get detailed information about a specific tool

    Args:
        tool_name: Tool name (metadata.name, e.g. "get_weather_alerts")

    Returns:
        Tool detail dict containing name, label, description, spec (with parameters and llm_prompt)
    """

# Example
detail = await self.plugin.get_tool_detail("get_weather_alerts")
print(detail['spec']['parameters'])
```

### Call Tool

Call a specific tool.

```python
async def call_tool(
    self,
    tool_name: str,
    parameters: dict[str, Any],
    session: dict[str, Any],
    query_id: int,
) -> dict[str, Any]:
    """Call a specific tool

    Args:
        tool_name: Tool name (metadata.name)
        parameters: Tool parameters
        session: Session info
        query_id: Query ID

    Returns:
        Tool response dict
    """

# Example
result = await self.plugin.call_tool(
    tool_name="get_weather_alerts",
    parameters={"state": "CA"},
    session={},
    query_id=0,
)
print(result)
```

> idea:
>
> Tool names use `metadata.name` (e.g. `echo_tool`, `get_weather_alerts`), without author or plugin name prefix.

### Set Plugin Persistent Data

Persistently store plugin data. Data stored through this interface can only be accessed by this plugin. Values need to be converted to bytes manually.

```python
async def set_plugin_storage(self, key: str, value: bytes) -> None:
    """Set a plugin storage value"""

# Usage example
await self.plugin.set_plugin_storage("key", b"value")
```

### Get Plugin Persistent Data

```python
async def get_plugin_storage(self, key: str) -> bytes:
    """Get a plugin storage value"""

# Usage example
plugin_storage = await self.plugin.get_plugin_storage("key")
```

### Get All Plugin Persistent Data Keys

```python
async def get_plugin_storage_keys(self) -> list[str]:
    """Get all plugin storage keys"""

# Usage example
plugin_storage_keys = await self.plugin.get_plugin_storage_keys()
```

### Delete Plugin Persistent Data

```python
async def delete_plugin_storage(self, key: str) -> None:
    """Delete a plugin storage value"""

# Usage example
await self.plugin.delete_plugin_storage("key")
```

### Get Workspace Persistent Data

Data stored through this interface can be accessed by all plugins. Values need to be converted to bytes manually.

```python
async def set_workspace_storage(self, key: str, value: bytes) -> None:
    """Set a workspace storage value"""

# Usage example
await self.plugin.set_workspace_storage("key", b"value")
```

### Get Workspace Persistent Data

```python
async def get_workspace_storage(self, key: str) -> bytes:
    """Get a workspace storage value"""

# Usage example
workspace_storage = await self.plugin.get_workspace_storage("key")
```

### Get All Workspace Persistent Data Keys

```python
async def get_workspace_storage_keys(self) -> list[str]:
    """Get all workspace storage keys"""

# Usage example
workspace_storage_keys = await self.plugin.get_workspace_storage_keys()
```

### Delete Workspace Persistent Data

```python
async def delete_workspace_storage(self, key: str) -> None:
    """Delete a workspace storage value"""

# Usage example
await self.plugin.delete_workspace_storage("key")
```

### Get Plugin File-typed Config Field Data

```python
async def get_config_file(self, file_key: str) -> bytes:
    """Get a config file value"""

# Usage example
file_bytes = await self.plugin.get_config_file("key")
```

Use this in conjunction with configuration fields of type [`file or array[file`](https://langbot.app/docs/en/plugin/dev/basic-info.md#type-file).

## Knowledge Base API

These APIs are accessible via `self.plugin` in regular components, allowing you to list and retrieve from all knowledge bases in the LangBot instance without pipeline restrictions.

### List All Knowledge Bases

List all available knowledge bases in the LangBot instance.

```python
async def list_knowledge_bases(self) -> list[dict[str, Any]]:
    """List all knowledge bases

    Returns:
        List of knowledge base dicts, each containing:
        - uuid: Knowledge base UUID
        - name: Knowledge base name
        - description: Knowledge base description
    """

# Usage example
knowledge_bases = await self.plugin.list_knowledge_bases()
for kb in knowledge_bases:
    print(f"KB: {kb['name']} ({kb['uuid']})")
```

### Retrieve from Knowledge Base

Retrieve relevant documents from any knowledge base.

```python
async def retrieve_knowledge(
    self,
    kb_id: str,
    query_text: str,
    top_k: int = 5,
    filters: dict[str, Any] | None = None,
) -> list[dict[str, Any]]:
    """Retrieve from a knowledge base

    Args:
        kb_id: Knowledge base UUID (from list_knowledge_bases)
        query_text: Search query text
        top_k: Number of results to return (default: 5)
        filters: Optional metadata filters for retrieval

    Returns:
        List of retrieval result entries
    """

# Usage example
results = await self.plugin.retrieve_knowledge(
    kb_id="kb-uuid-here",
    query_text="How to configure the system?",
    top_k=3,
)
for entry in results:
    print(entry)
```

> idea:
>
> These APIs do not require a `query_id` and can be used in regular components (including Tool components). They can access all knowledge bases without being restricted to the current pipeline's configuration.

## RAG API

These APIs are available for `KnowledgeEngine` components to access the LangBot host's embedding models, vector database, and file storage. Access method:

- In `KnowledgeEngine` component classes: Internal methods of the `self.plugin` object.

### Invoke Embedding Model

Generate text embeddings using the host's configured embedding model.

```python
async def invoke_embedding(
    self,
    embedding_model_uuid: str,
    texts: list[str],
) -> list[list[float]]:
    """Generate embeddings using host's embedding model

    Args:
        embedding_model_uuid: Embedding model UUID
        texts: List of texts to embed

    Returns:
        List of embedding vectors, one per input text
    """

# Usage example
vectors = await self.plugin.invoke_embedding("model_uuid", ["Hello", "World"])
```

### Vector Upsert

Upsert vectors to the host's vector database.

```python
async def vector_upsert(
    self,
    collection_id: str,
    vectors: list[list[float]],
    ids: list[str],
    metadata: list[dict[str, Any]] | None = None,
    documents: list[str] | None = None,
) -> None:
    """Upsert vectors

    Args:
        collection_id: Target collection ID
        vectors: List of vectors
        ids: List of unique IDs for vectors
        metadata: Optional list of metadata dicts
        documents: Optional raw text documents. Required for full-text
            and hybrid search in backends that support them.
    """

# Usage example
await self.plugin.vector_upsert(
    collection_id="kb_uuid",
    vectors=[[0.1, 0.2, ...], [0.3, 0.4, ...]],
    ids=["chunk_0", "chunk_1"],
    metadata=[{"document_id": "doc1"}, {"document_id": "doc1"}],
    documents=["chunk text 0", "chunk text 1"],
)
```

### Vector Search

Search similar vectors in the host's vector database.

```python
async def vector_search(
    self,
    collection_id: str,
    query_vector: list[float],
    top_k: int = 5,
    filters: dict[str, Any] | None = None,
    search_type: str = "vector",
    query_text: str = "",
) -> list[dict[str, Any]]:
    """Vector search

    Args:
        collection_id: Target collection ID
        query_vector: Query vector for similarity search
        top_k: Number of results to return
        filters: Optional metadata filters
        search_type: One of 'vector', 'full_text', 'hybrid'
        query_text: Raw query text, used for full_text and hybrid search

    Returns:
        List of search results (dict with id, score, metadata, etc.)
    """

# Usage example
results = await self.plugin.vector_search(
    collection_id="kb_uuid",
    query_vector=[0.1, 0.2, ...],
    top_k=5,
    search_type="hybrid",
    query_text="search query",
)
# Return format: [{"id": "chunk_0", "score": 0.123, "metadata": {"document_id": "doc1", ...}}, ...]
```

> info:
>
> Each result returned by `vector_search` is a dict containing `id` (vector ID), `score` (distance score), and `metadata` (metadata provided during upsert). If you need text content in retrieval results, store the text in metadata during ingestion.

### Vector Delete

Delete vectors from the host's vector database.

```python
async def vector_delete(
    self,
    collection_id: str,
    file_ids: list[str] | None = None,
    filters: dict[str, Any] | None = None,
) -> int:
    """Vector delete

    Args:
        collection_id: Target collection ID
        file_ids: File IDs whose vectors should be deleted
        filters: Optional metadata filters for deletion

    Returns:
        Number of deleted items
    """

# Usage example
deleted = await self.plugin.vector_delete(
    collection_id="kb_uuid",
    file_ids=["doc_001"],
)
```

> info:
>
> The `filters` parameter supports Chroma-style `where` syntax for metadata filtering. Multiple top-level keys are AND-ed. Supported operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`.
>
> ```python
> # Implicit $eq
> results = await self.plugin.vector_search(
>     collection_id="kb_uuid",
>     query_vector=[0.1, 0.2, ...],
>     filters={"file_id": "abc"},
> )
>
> # Comparison operator
> results = await self.plugin.vector_search(
>     collection_id="kb_uuid",
>     query_vector=[0.1, 0.2, ...],
>     filters={"created_at": {"$gte": 1700000000}},
> )
>
> # In-list operator
> results = await self.plugin.vector_search(
>     collection_id="kb_uuid",
>     query_vector=[0.1, 0.2, ...],
>     filters={"file_type": {"$in": ["pdf", "docx"]}},
> )
>
> # Delete by filter
> deleted = await self.plugin.vector_delete(
>     collection_id="kb_uuid",
>     filters={"file_type": {"$eq": "pdf"}},
> )
> ```
>
> **Note:** Chroma, Qdrant, and SeekDB store full metadata and can filter on any field. Milvus and pgvector only store `text`, `file_id`, and `chunk_uuid` — filters on other fields will be silently ignored.

Get uploaded file content from the host's storage.

```python
async def get_knowledge_file_stream(self, storage_path: str) -> bytes:
    """Get file content

    Args:
        storage_path: File storage path (from FileObject.storage_path)

    Returns:
        File content as bytes
    """

# Usage example
file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)
```

## Additional resource APIs

These methods are also called through `self.plugin`.

### Invoke a rerank model

```python
async def invoke_rerank(
    self, rerank_model_uuid: str, query: str, documents: list[str],
    top_k: int | None = None, extra_args: dict[str, Any] | None = None,
    timeout: float = 60.0,
) -> list[dict[str, Any]]:
    ...

scores = await self.plugin.invoke_rerank(
    rerank_model_uuid=rerank_model_uuid,
    query="How do I configure a bot?",
    documents=["Bot configuration guide", "Plugin publishing guide"],
    top_k=1,
)
```

Results usually contain the original document `index` and `relevance_score`.

### Invoke a parser

```python
async def invoke_parser(
    self, plugin_author: str, plugin_name: str, storage_path: str,
    mime_type: str, filename: str, metadata: dict[str, Any] | None = None,
) -> dict[str, Any]:
    ...

parsers = await self.plugin.list_parsers(mime_type="application/pdf")
if parsers:
    parser = parsers[0]
    parsed = await self.plugin.invoke_parser(
        plugin_author=parser["plugin_author"],
        plugin_name=parser["plugin_name"],
        storage_path=storage_path,
        mime_type="application/pdf",
        filename="guide.pdf",
    )
```

`storage_path` is a Host storage path, such as `context.file_object.storage_path` during knowledge ingestion, not a plugin-local path. The result dictionary contains `text`, `sections`, and `metadata`.

### List vector records

```python
async def vector_list(
    self, collection_id: str, filters: dict[str, Any] | None = None,
    limit: int = 20, offset: int = 0,
) -> dict[str, Any]:
    ...

page = await self.plugin.vector_list(
    collection_id=collection_id,
    filters={"file_id": "doc_001"},
    limit=20,
    offset=0,
)
for item in page["items"]:
    print(item["id"], item.get("metadata"))
```

Returns `items` and `total`. Items contain `id`, `document`, and `metadata`; `total` is a best-effort matching count from the storage backend. Filters use the vector API format above.

### List plugins and commands

```python
manifests = await self.plugin.list_plugins_manifest()
commands = await self.plugin.list_commands()
```

Both methods take no arguments and return the Host-provided plugin manifest list and command list respectively.

### Box sandbox

These methods use `self.plugin` and the current Workspace. Runner calls automatically retain invocation authorization.

| Method                                                   | Returns            | Behavior                                                                                                                       |
| -------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `await self.plugin.get_box_status()`                     | `BoxStatus`        | `enabled`, `available`, capacity `limit`, `used`, `remaining`, optional managed `required_reuse_key`, and unavailable `reason` |
| `await self.plugin.list_boxes()`                         | `list[BoxSession]` | Box `id` and `status` snapshot (`idle`, `running`, `closing`)                                                                  |
| `await self.plugin.acquire_box(reuse_key, options=None)` | `BoxSession`       | Reuse the same key or create within capacity; `options` supports `image`                                                       |

Unknown capacity fields are `None`. Zero remaining capacity still permits reuse; Runtime checks creation capacity atomically. The Runner computes reuse keys. When `required_reuse_key` is supplied, use it. Equal keys in different Workspaces never share a Box.

Use the [Runner context](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md#runner) to bind the Box before importing attachments or executing tools.

---

# Message Platform Entities

Source: https://langbot.app/docs/en/plugin/dev/apis/messages

LangBot supports multiple messaging platforms, and each platform has different `message entity` formats. To abstract away these differences, we have implemented a unified standard. Plugin developers only need to master and use the message entities described on this page in plugins, and LangBot's internal message processing logic can automatically handle message parsing and conversion.

## Message Chain

`Messages` on messaging platforms are different from messages used for AI interaction. Messages on messaging platforms are described in the form of `message chains`. Each independent message displayed on QQ is a message chain, which can contain various `message chain components` such as `text`, `images`, `@mentions`, etc. For example:

![](https://langbot.app/docs/images/zh/plugin/dev/apis/plugin_dev_messages_01.png)

This is a message chain containing one Plain component (Hello World) and one Image component (Usagi).

The definitions of message chains and message chain components are located in `langbot_plugin.api.entities.builtin.platform.message`.

### Constructing Message Chains

Please first import the `langbot_plugin.api.entities.builtin.platform.message` package to use the message components within it.

```python
from langbot_plugin.api.entities.builtin.platform.message import *

# Build a message containing text "Hello LangBot" and an image (from URL)
msg_chain = MessageChain([
    Plain(text="Hello LangBot"),
    Image(url='https://qchatgpt.rockchin.top/langbot-logo.png')
])

# Build a message containing @everyone and text "Hello LangBot"
msg_chain = MessageChain([
    AtAll(),
    Plain(text="Hello LangBot")
])

# Build a message containing @specific member and text "Hello LangBot"
msg_chain = MessageChain([
    At(target=123456),
    Plain(text="Hello LangBot")
])
```

Currently supported message chain components:

- `Source` - Source message chain information. Messages received from messaging platforms will include this component at the front of the message chain to record message information
- `Plain` - Plain text message
- `Quote` - Quote message
- `Image` - Image message
- `AtAll` - @everyone message
- `At` - @specific member message
- `Voice` - Voice message
  - Need to check messaging platform support
- `Forward` - Forward message
  - Not supported on many platforms, not recommended
- `File` - File message

When creating components, named parameters must be used. For specific usage, you can check the definitions in the source code `langbot_plugin.api.entities.builtin.platform.message`.

## Other Entities

In addition to the above entities, there are also entities like `Friend` and `Group`. These entities are defined in `langbot_plugin.api.entities.builtin.platform.entities`.

## Platform APIs

Use [Platform APIs](https://langbot.app/docs/en/plugin/dev/apis/platform.md) to query users, manage groups, and call platform-specific actions. Runner uses the same `self.plugin` entrypoint; use `ctx.reply()` for the current conversation.

---

# Pipeline Events and APIs

Source: https://langbot.app/docs/en/plugin/dev/apis/pipeline-events

LangBot plugins can register and handle pipeline events. For usage instructions, see [Component: Event Listener](https://langbot.app/docs/en/plugin/dev/components/event-listener.md).

## List of Events

Some events have `settable attributes`, which can be modified by plugin code and used in subsequent LangBot processing.

### \*MessageReceived

Triggered when any message is received in group chat or private chat.

```python
class PersonMessageReceived(BaseEventModel):
    """When any private chat message is received"""

    event_name: str = "PersonMessageReceived"

    launcher_type: str
    """Launcher object type (person)"""

    launcher_id: typing.Union[int, str]
    """Sender ID"""

    sender_id: typing.Union[int, str]
    """Sender ID, same as launcher_id in private chat"""

    message_event: platform_events.PersonMessage
    """Original message event object. Contains sender information."""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """Message chain"""


class GroupMessageReceived(BaseEventModel):
    """When any group chat message is received"""

    event_name: str = "GroupMessageReceived"

    launcher_type: str
    """Launcher object type (group)"""

    launcher_id: typing.Union[int, str]
    """Group ID"""

    sender_id: typing.Union[int, str]
    """Sender ID"""

    message_event: platform_events.GroupMessage
    """Original message event object. Contains group and sender information."""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """Message chain"""
```

### \*NormalMessageReceived

Triggered when a group chat or private chat message is received and determined to be a message that needs to be processed by LLM (non-command message).

```python
class PersonNormalMessageReceived(BaseEventModel):
    """Triggered when a private chat normal message that should be processed is determined"""

    event_name: str = "PersonNormalMessageReceived"

    launcher_type: str
    """Launcher object type (person)"""

    launcher_id: typing.Union[int, str]
    """Launcher object ID"""

    sender_id: typing.Union[int, str]
    """Sender ID, same as launcher_id in private chat"""

    text_message: str
    """Message text"""

    message_event: platform_events.PersonMessage
    """Original message event object. Contains sender information."""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """Message chain"""

    # ========== Settable Attributes ==========

    user_message_alter: typing.Optional[provider_message.ContentElement] = None
    """Modified message text, langbot_plugin.api.entities.builtin.provider.message.ContentElement type"""

    reply_message_chain: typing.Optional[platform_message.MessageChain] = None
    """Direct reply message chain, only effective when preventing default behavior"""


class GroupNormalMessageReceived(BaseEventModel):
    """Triggered when a group chat normal message that should be processed is determined"""

    event_name: str = "GroupNormalMessageReceived"

    launcher_type: str
    """Launcher object type (group)"""

    launcher_id: typing.Union[int, str]
    """Group ID"""

    sender_id: typing.Union[int, str]
    """Sender ID"""

    text_message: str
    """Message text"""

    message_event: platform_events.GroupMessage
    """Original message event object. Contains group and sender information."""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """Message chain"""

    # ========== Settable Attributes ==========

    user_message_alter: typing.Optional[provider_message.ContentElement] = None
    """Modified message text, langbot_plugin.api.entities.builtin.provider.message.ContentElement type"""

    reply_message_chain: typing.Optional[platform_message.MessageChain] = None
    """Direct reply message chain, only effective when preventing default behavior"""
```

### \*CommandSent

> warning:
>
> No longer recommended for use, please use [Component: Command](https://langbot.app/docs/en/plugin/dev/components/command.md) instead.

Triggered when a group chat or private chat command is received.

```python
class PersonCommandSent(BaseEventModel):
    """Triggered when a private chat command that should be processed is determined"""

    event_name: str = "PersonCommandSent"

    launcher_type: str

    launcher_id: typing.Union[int, str]

    sender_id: typing.Union[int, str]

    command: str
    """Command text"""

    params: list[str]
    """Command parameters"""

    text_message: str
    """Message text"""

    is_admin: bool
    """Whether it's an administrator"""


class GroupCommandSent(BaseEventModel):
    """Triggered when a group chat command that should be processed is determined"""

    event_name: str = "GroupCommandSent"

    launcher_type: str

    launcher_id: typing.Union[int, str]

    sender_id: typing.Union[int, str]

    command: str
    """Command text"""

    params: list[str]
    """Command parameters"""

    text_message: str
    """Message text"""

    is_admin: bool
    """Whether it's an administrator"""
```

### NormalMessageResponded

Triggered when a message receives an LLM response.

```python
class NormalMessageResponded(BaseEventModel):
    """Triggered when replying to a normal message"""

    event_name: str = "NormalMessageResponded"

    launcher_type: str

    launcher_id: typing.Union[int, str]

    sender_id: typing.Union[int, str]

    session: provider_session.Session
    """Session object"""

    prefix: str
    """Reply message prefix"""

    response_text: str
    """Reply message text"""

    finish_reason: str
    """Response end reason"""

    funcs_called: list[str]
    """List of called functions"""

    # ========== Settable Attributes ==========

    reply_message_chain: typing.Optional[platform_message.MessageChain] = None
    """Reply message component list, only effective when preventing default behavior"""
```

### PromptPreProcessing

Triggered when building the LLM response context (prompt).

```python
class PromptPreProcessing(BaseEventModel):
    """Triggered when preprocessing prompt in session"""

    event_name: str = "PromptPreProcessing"

    session_name: str
    """Session name, format is person_1234567890 or group_1234567890"""

    # ========== Settable Attributes ==========

    default_prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]]
    """Scenario preset (system prompt) for this conversation, can be modified, langbot_plugin.api.entities.builtin.provider.message.Message or langbot_plugin.api.entities.builtin.provider.message.MessageChunk type"""

    prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]]
    """Existing message records for this conversation, can be modified, langbot_plugin.api.entities.builtin.provider.message.Message or langbot_plugin.api.entities.builtin.provider.message.MessageChunk type"""
```

## EventListener context

Event handlers read the current event through `event_context.event`. See [Context APIs](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md#eventlistener) for the complete `EventContext` properties and methods.

### Prevent default behavior

Calling `event_context.prevent_default()` stops the default handling of the current event. Only these events support it:

> info:
>
> Only the following events can prevent default behavior:
>
> - PersonMessageReceived
> - GroupMessageReceived
> - PersonNormalMessageReceived
> - GroupNormalMessageReceived
> - PersonCommandSent
> - GroupCommandSent
> - NormalMessageResponded

Call `event_context.prevent_postorder()` to stop later plugins from handling the current event.

---

# Platform APIs

Source: https://langbot.app/docs/en/plugin/dev/apis/platform

Call platform adapter APIs using a bot UUID. Continue using `self.plugin.send_message()` for message chains; use the API below for groups, users, and other platform features.

## Call a platform API

```python
async def call_platform_api(
    self,
    bot_uuid: str,
    action: str,
    params: dict[str, Any] | None = None,
) -> Any:
    ...
```

Call through `self.plugin` in Command, EventListener, Tool, and other regular components. Results are serialized dictionaries, lists, scalars, or `None`, depending on the action, rather than platform SDK objects.

```python
group = await self.plugin.call_platform_api(
    bot_uuid=bot_uuid,
    action="get_group_info",
    params={"group_id": "123456"},
)
```

`bot_uuid` comes from `await self.plugin.get_bots()` or `await event_context.get_bot_uuid()` in a Pipeline event. Use platform IDs from real events or platform configuration.

### Common actions

| `action`                         | `params`                             |
| -------------------------------- | ------------------------------------ |
| `get_user_info`                  | `user_id`                            |
| `get_friend_list`                | `{}`                                 |
| `get_group_info`                 | `group_id`                           |
| `get_group_list`                 | `{}`                                 |
| `get_group_member_list`          | `group_id`                           |
| `get_group_member_info`          | `group_id`, `user_id`                |
| `get_message` / `delete_message` | `chat_type`, `chat_id`, `message_id` |
| `set_group_name`                 | `group_id`, `name`                   |
| `mute_member`                    | `group_id`, `user_id`, `duration`    |
| `unmute_member` / `kick_member`  | `group_id`, `user_id`                |
| `leave_group`                    | `group_id`                           |
| `approve_friend_request`         | `request_id`, `approve`, `remark`    |
| `approve_group_invite`           | `request_id`, `approve`              |
| `get_file_url`                   | `file_id`                            |

Supported actions vary by platform and may require bot administrator permissions. `duration` is in seconds; the meaning of `0` is platform-specific, not a universal permanent mute. Queries may depend on platform caches. Calls raise an exception if the bot is not running, the action is unsupported, or parameters are invalid.

## Platform-specific APIs

Set the outer `action` to `call_platform_api` and put the platform action and parameters inside `params`. For example, read the bot account using OneBot Omni:

```python
account = await self.plugin.call_platform_api(
    bot_uuid=bot_uuid,
    action="call_platform_api",
    params={"action": "get_login_info", "params": {}},
)
```

Only actions declared by the adapter are allowed; this is not unrestricted pass-through to every platform endpoint. Plugins call the Host through the runtime, rather than accessing `ctx.query.adapter` or `adapter.bot`.

## Runner

During Runner execution, model, tool, knowledge-base, storage, and platform calls through `self.plugin` automatically use the current run and its authorization. Do not pass `run_id`. Concurrent runs remain isolated. Do not continue these run-bound calls after the handler returns.

Use `await ctx.get_bot_uuid()` for the current bot. Platform calls must match the tool grants for this invocation. Event-target grants cannot access another target. Ungranted actions, including platform-specific actions, are rejected. These calls also use Mock delivery in debug mode.

```python
tools = await ctx.get_available_tools()
if any(tool["name"] == "event_get_actor" for tool in tools):
    actor = await ctx.call_tool("event_get_actor")
    await ctx.log(str(actor))
```

---

# Plugin Technical Details

Source: https://langbot.app/docs/en/plugin/dev/apis/tech-details

## Architecture

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_system_arch.png)

In version 4.0, we introduced a high-security, high-flexibility production-grade plugin system and provided developers with rich APIs and easy-to-use supporting tools.

Plugin Runtime is used to manage plugin lifecycles and coordinate interactions between LangBot and plugins. It has two operating modes: `stdio` and `websocket`. When LangBot is started directly by users (not running in a container), it uses `stdio` mode, which is common for personal users or lightweight environments. When LangBot runs in a container, it uses `websocket` mode, designed specifically for production environments.

Plugin Runtime automatically starts each installed plugin and interacts through stdio. In plugin development scenarios, developers can use the `lbp` command-line tool to start plugins and connect to the running Runtime via WebSocket for debugging.

---

# Completing Plugin Configuration Information

Source: https://langbot.app/docs/en/plugin/dev/basic-info

## Modifying the Manifest File

The `manifest.yaml` file in the plugin directory declares the basic information about the plugin, which will be displayed in the LangBot UI or plugin marketplace interfaces.

```yaml
apiVersion: v1  # Do not modify
kind: Plugin  # Do not modify
metadata:
  author: RockChinQ  # Author, must match regex ^[a-zA-Z0-9_-]+$
  name: HelloPlugin  # Plugin name, used to distinguish plugins, must match regex ^[a-zA-Z0-9-]+$
  repository: 'https://github.com/langbot-app/HelloPlugin'  # Plugin repository URL
  version: 0.1.0  # Plugin version
  description:
    en_US: 'Hello LangBot Plugin'  # Plugin description, multilingual
    zh_Hans: 'Hello LangBot Plugin'
  label:
    en_US: HelloPlugin  # Plugin label, displayed in the interface, multilingual
    zh_Hans: HelloPlugin
  icon: assets/icon.svg  # Plugin icon, defaults to assets/icon.svg, can be replaced with various image formats
spec:
  config: []  # Plugin configuration item format
  components: {}  # Plugin component list, no need to modify manually
execution:
  python:
    path: main.py  # Do not modify
    attr: HelloPlugin  # Do not modify
```

To certify your plugin and let several installations share one runtime, also declare `sharedRuntime` and `componentModel` under `execution`; see [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md).

Plugin multilingual support follows the [RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646) standard. Currently supported languages include:

- `en_US` English (required)
- `zh_Hans` Simplified Chinese
- `zh_Hant` Traditional Chinese
- `ja_JP` Japanese
- `vi_VN` Vietnamese
- `th_TH` Thai
- `es_ES` Spanish

## Plugin Configuration Item Format

In the `manifest.yaml` file, fields declared in `spec.config` will be rendered by LangBot as configuration item forms for users to fill out. Plugins can retrieve user-filled configuration items through APIs provided by the SDK (see later sections).

For example:

```yaml
spec:
  config:
    - name: github_token  # Required; configuration item name, used for retrieval in the plugin
      type: string  # Required; configuration item type, supports string, integer, float, boolean, select, prompt-editor, llm-model-selector, bot-selector, tools-selector, etc.
      label:  # Required; configuration item display name, supports multilingual. Language codes follow RFC 4646 standard.
        en_US: Github Token
        zh_Hans: Github Token
      description:  # Configuration item description, supports multilingual. Optional.
        en_US: Image downloading requires a Github token
        zh_Hans: 如果不填的话，图片可能会下载失败
      default: ''  # Configuration item default value, optional.
      required: false  # Whether the configuration item is required, optional.
      show_if:  # Conditional rendering (shows when conditions are met), optional.
        field: mode
        operator: eq
        value: mode1
    - name: mode
      type: select
      ...
```

The supported types and fields for configuration items are as follows:

### Conditional Rendering (`show_if`)

All types of configuration items support conditional rendering using the `show_if` field. You can decide whether the current field is rendered based on the value of another field in the same (or an associated) form.

```yaml
- name: advanced_setting
  type: string
  show_if:
    field: mode          # The name of the dependent field
    operator: eq         # The operator, supports 'eq' (equals), 'neq' (not equals), 'in' (in a list)
    value: advanced      # The value to check against
```

> **Note:** Cross-form cascading relationships (e.g. `creation_schema` values reading from `retrieval_schema` values and vice versa in a Knowledge Engine) are supported in the latest LangBot frontend.

### type: string

String type. Optionally supports `options` for preset values — when provided, a dropdown button appears next to the input allowing users to quickly fill in a preset value. Users can still type freely.

```yaml
- name: api_key
  type: string
  ...
```

With preset options:

```yaml
- name: api_url
  type: string
  options:  # Optional preset values, displayed as a dropdown button next to the input.
    - name: "https://api.openai.com/v1"  # The value to fill in when selected.
      label:  # Display name, supports multilingual.
        en_US: OpenAI Official
        zh_Hans: OpenAI 官方
    - name: "https://api.deepseek.com/v1"
      label:
        en_US: DeepSeek
        zh_Hans: DeepSeek
  ...
```

### type: array\[string]

String array.

```yaml
- name: tags
  type: array[string]
  ...
```

### type: integer

Integer type.

```yaml
- name: progress
  type: integer
  ...
```

### type: float

Float type.

```yaml
- name: temperature
  type: float
  ...
```

### type: boolean

Boolean type.

```yaml
- name: is_enabled
  type: boolean
  ...
```

### type: select

Dropdown menu. Requires configuring `options`, which represents the dropdown menu options. Each option displays its `label` as the primary text, with the `name` (value) shown in smaller text below.

```yaml
- name: mode
  type: select
  allow_custom: true
  options:  # Dropdown options, supports multilingual.
    - name: mode1  # Value, displayed as secondary text in the dropdown.
      label:  # Display name, supports multilingual.
        en_US: Mode 1
        zh_Hans: 模式 1
    - name: mode2
      label:  # Display name, supports multilingual.
        en_US: Mode 2
        zh_Hans: 模式 2
  ...
```

Set `allow_custom: true` to add a Custom option alongside the presets. A text input appears only when Custom is selected. The saved value is the selected `name` or the custom string, never a Custom marker. This also applies to a runner’s `spec.config`.

### type: prompt-editor

Prompt editor. Displays a prompt editor from the pipeline configuration page, with the final result represented in OpenAI's `messages` format.

```yaml
- name: prompt
  type: prompt-editor
  ...
```

### type: text

Large text input. Rendered as a textarea in the frontend for user input, and passed to the plugin as a string.

```yaml
- name: prompt
  type: text
  ...
```

### type: file

File upload. Supports file uploads up to 10MB, passed to the plugin in the format `{"file_key": "xxxxx.xxx", "mimetype": "xxxxx"}`. The plugin can use the `get_config_file` API to retrieve the file content.

```yaml
- name: config_file
  type: file
  accept: 'application/json'  # Optional, specify accepted file MIME types
  ...
```

Retrieving the file in the plugin:

```python
# Get file information from config
file_config = self.get_config()['config_file']
file_key = file_config['file_key']
mimetype = file_config['mimetype']

# Example output: {'file_input': {'file_key': 'plugin_config_d2234fd802054faf80babe0679a97fa9.json', 'mimetype': 'application/json'}}
print(file_config)

# Get file content
file_bytes = await self.get_config_file(file_key)
```

> info:
>
> Common MIME type and file extension reference: [MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)

### type: array\[file]

Multiple file upload. Similar to the file type, but supports uploading multiple files, passed to the plugin in the format `[{"file_key": "xxxxx.xxx", "mimetype": "xxxxx"}]`.

```yaml
- name: resource_files
  type: array[file]
  accept: 'image/*'  # Optional, specify accepted file MIME types
  ...
```

Retrieving files in the plugin:

```python
# Get file list from config
files_config = self.get_config()['resource_files']

for file_config in files_config:
    file_key = file_config['file_key']
    mimetype = file_config['mimetype']

    # Get file content
    file_bytes = await self.get_config_file(file_key)
```

### type: llm-model-selector

LLM model selector. Displays an LLM model selector where you can choose configured LLM models, with the final result represented as the LLM model UUID.

```yaml
- name: model
  type: llm-model-selector
  ...
```

### type: bot-selector

Bot selector. Displays a Bot selector where you can choose configured Bots, with the final result represented as the Bot UUID.

```yaml
- name: bot
  type: bot-selector
  ...
```

Using the Bot UUID in the plugin:

```python
# Get Bot UUID from config
bot_uuid = self.get_config()['bot']
print(bot_uuid)  # Output: '550e8400-e29b-41d4-a716-446655440000'
```

### type: tools-selector

Tool selector. Displays a multi-select tool selector where you can choose registered tools (plugin tools and MCP tools), with the final result represented as an array of tool names.

```yaml
- name: selected_tools
  type: tools-selector
  ...
```

Using the selected tool names in the plugin:

```python
# Get selected tool names from config
selected_tools = self.get_config()['selected_tools']
print(selected_tools)  # Output: ['get_weather_alerts', 'web_search']

# Call selected tools
for tool_name in selected_tools:
    result = await self.plugin.call_tool(
        tool_name=tool_name,
        parameters={"query": "hello"},
        session={},
        query_id=0,
    )
```

## What's Next

This tutorial will guide you through step-by-step completion of plugin functionality.

- Adding Components: Plugin components are the core functional units of plugins. You can [add components](https://langbot.app/docs/en/plugin/dev/components/add.md) based on your needs.

---

# Adding Components

Source: https://langbot.app/docs/en/plugin/dev/components/add

Plugins consist of one or more components that provide different functionalities to LangBot. Currently supported component types include:

- Plugin processor (Runner): handles platform events in plugin code after an instance is created and bound. See the [tutorial](https://langbot.app/docs/en/plugin/dev/components/runner.md).
- Agent runner (Runner): provides execution logic selected in an Agent configuration; it is distinct from a standalone plugin processor.
- Event Listeners (EventListener): Listen to events during pipeline execution and modify context or pipelines.
- Commands (Command): Triggered by user command messages starting with `!` (or other configured prefixes).
- Tools (Tool): Called by LLMs during execution of LangBot's built-in Local Agent.
- Knowledge Engines (KnowledgeEngine): Provide knowledge base indexing and retrieval capabilities for LangBot, managing document ingestion, retrieval, and deletion.
- Parsers (Parser): Parse binary files such as PDF, Word, etc. into structured text before document ingestion, for use by Knowledge Engines.
- Pages (Page): Register custom visual pages in the LangBot WebUI sidebar, providing admin panels, data displays, and interactive interfaces.

## Adding Components

Execute the command in the plugin directory:

```bash
lbp comp <component_type>
```

For example, to add an event listener:

```bash
lbp comp EventListener
```

Follow the prompts to enter the component configuration (if any).

```bash
➜  HelloPlugin > lbp comp EventListener
Generating component EventListener...
Component EventListener generated successfully.
组件 EventListener 生成成功。
➜  HelloPlugin >
```

> :
>
> The CLI will generate a `components` directory in the plugin directory and create corresponding component directories within it.
>
> ```
> .
> ├── assets
> │   └── icon.svg
> ├── components
> │   ├── __init__.py
> │   └── event_listener
> │       ├── __init__.py
> │       ├── default.py
> │       └── default.yaml
> ├── main.py
> ├── manifest.yaml
> ├── README.md
> └── requirements.txt
> ```
>
> At the same time, component discovery configuration will be added to the plugin's `manifest.yaml`:
>
> ```yaml
> ...
> components:
>     EventListener:
>       fromDirs:
>       - path: components/event_listener/
> ...
> ```
>
> To remove components, you can delete the corresponding information manually.

## Component Types

For detailed usage of each component, please refer to:

- [Runner](https://langbot.app/docs/en/plugin/dev/components/runner.md)
- [EventListener](https://langbot.app/docs/en/plugin/dev/components/event-listener.md)
- [Command](https://langbot.app/docs/en/plugin/dev/components/command.md)
- [Tool](https://langbot.app/docs/en/plugin/dev/components/tool.md)
- [KnowledgeEngine](https://langbot.app/docs/en/plugin/dev/components/knowledge-engine.md)
- [Parser](https://langbot.app/docs/en/plugin/dev/components/parser.md)
- [Page](https://langbot.app/docs/en/plugin/dev/components/page.md)

---

# Component: Command

Source: https://langbot.app/docs/en/plugin/dev/components/command

Command components are triggered by user command messages starting with `!` (or other configured prefixes). Here's an example of triggering the `!help` command:

![](https://langbot.app/docs/images/zh/plugin/dev/components/command_use.png)

## Adding Command Components

A single plugin can contain any number of commands. Execute the command `lbp comp Command` in the plugin directory and follow the prompts to enter the command configuration.

```bash
➜  HelloPlugin > lbp comp Command
Generating component Command...
Command name: info
Command description: Show information of the query
Component Command generated successfully.
组件 Command 生成成功。
```

This will generate `info.yaml` and `info.py` files in the `components/commands/` directory. The `.yaml` file defines the basic information for the `!info` command, and the `.py` file is the command handler:

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   ├── commands
│   │   ├── __init__.py
│   │   ├── info.py
│   │   └── info.yaml
...
```

## Manifest File: Command Component

```yaml
apiVersion: v1  # Do not modify
kind: Command  # Do not modify
metadata:
  name: info  # Command name, users will trigger this command with !info
  label:  # Command display name, shown in LangBot UI, supports multilingual
    en_US: Info
    zh_Hans: Info
  description:  # Command description, shown in LangBot UI, supports multilingual. Optional.
    en_US: 'Show information of the query'
    zh_Hans: '发送此次消息的详细信息'
spec:
execution:
  python:
    path: info.py  # Command handler, do not modify
    attr: Info  # Command handler class name, matches the class name in info.py
```

## Plugin Processing

The following code is generated by default (`components/command/<command_name>.py`). You need to register and implement subcommand processing logic in the `initialize` method of the `Info` class.

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from typing import Any, AsyncGenerator

from langbot_plugin.api.definition.components.command.command import Command, Subcommand
from langbot_plugin.api.entities.builtin.command.context import ExecuteContext, CommandReturn


class Info(Command):
    
    async def initialize(self):
        await super().initialize()
        
        "Fill with your code here"
```

Adding subcommands:

```python
...
class Info(Command):
    
    async def initialize(self):
        await super().initialize()
        
        @self.subcommand(
            name="",  # Empty string represents root command
            help="Show information of the query", # Command help information
            usage="info", # Command usage example, displayed in command help
            aliases=["i"], # Command aliases
        )
        async def send(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]:
            print(context)

            reply_text = f"Query ID: {context.query_id}\n"
            reply_text += f"command: {context.command}\n"
            reply_text += f"command_text: {context.command_text}\n"
            reply_text += f"params: {context.params}\n"
            reply_text += f"crt_params: {context.crt_params}\n"
            reply_text += f"privilege: {context.privilege}\n"
            reply_text += f"session: {context.session.launcher_type.value}_{context.session.launcher_id}\n"
            
            yield CommandReturn(
                text=reply_text,
            )

        @self.subcommand(
            name="field",
            help="Show information of the field",
            usage="info field",
            aliases=["f"],
        )
        async def field(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]:
            print(context)

            field_name = context.crt_params[0]
            field_value = getattr(context, field_name)

            yield CommandReturn(
                text=f"{field_name}: {field_value}",
            )
```

In this code, the `send` function is registered as a subcommand through the `@self.subcommand` decorator, prints the command context (ExecuteContext) information, and concatenates it into a reply message.

### Subcommand Registration

`name` is the subcommand name. Leaving it empty means handling the main command. If not empty, it matches the second parameter as the command. For example:

- `!info` matches the subcommand with name=""
- `!info field` matches the subcommand with name="field"
- `!info field value` matches the subcommand with name="field", with `value` as the subcommand parameter
- Specialy, `name="*"` matches all unmatched first-level subcommands, and passes each section after `info` as parameters, for example `!info 123`, `!info abc`. You can get `['123']` or `['abc']` from `context.crt_params`, depending on the user's input.

In subcommand functions, you can read command parameters through the `context` variable.

The effect of the above command is shown in the image:

![](https://langbot.app/docs/images/zh/plugin/dev/components/info_command_demo.png)

### Command Context

```python

class ExecuteContext(pydantic.BaseModel):
    """Single command execution context"""

    query_id: int
    """Request ID"""

    session: provider_session.Session
    """Session object for this message"""

    command_text: str
    """Complete command text"""

    command: str
    """Command name"""

    crt_command: str
    """Current command
    
    In multi-level commands, crt_command is the current command, command is the root command.
    Example: !plugin on Webwlkr
    When processing plugin, command is plugin, crt_command is plugin
    When processing on, command is plugin, crt_command is on
    """

    params: list[str]
    """Command parameters
    
    Parameter list after splitting the entire command by spaces
    """

    crt_params: list[str]
    """Current command parameters

    In multi-level commands, crt_params are current command parameters, params are root command parameters.
    Example: !plugin on Webwlkr
    When processing plugin, params is ['on', 'Webwlkr'], crt_params is ['on', 'Webwlkr']
    When processing on, params is ['on', 'Webwlkr'], crt_params is ['Webwlkr']
    """

    privilege: int
    """Session privilege level"""

    ...
```

### Command Return Values

Command return values (CommandReturn) currently support returning text, images (image\_url, image links), and errors.

```python
yield CommandReturn(
    text=reply_text,
)

yield CommandReturn(
    image_url=image_url,
)
```

Command processing supports returning multiple messages, so please use `yield` statements to return messages.

For specific return values, please refer to the definition of `CommandReturn`: [langbot\_plugin.api.entities.builtin.command.context.CommandReturn](https://github.com/langbot-app/langbot-plugin-sdk/tree/main/src/langbot_plugin/api/entities/builtin/command/context.py)

## One installation, many usages

A single command is triggered **concurrently by several conversations**:

- Read config per call; never read it in `initialize()` and cache it on the instance.
- Never leave command arguments, return values or conversation data on instance fields or module-level variables; `ExecuteContext` is valid only for the current execution.
- Concurrent triggering means instance fields get interleaved writes — do not use them to hold "current conversation" style state. Data that must survive calls belongs in Host storage, keyed with the conversation identity.
- If you keep per-installation process-local caches, release them in `on_installation_revoked(binding)`.

See [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md) for the full specification.

## What's Next

You have learned the basic information about command registration and command execution. Next, you can:

- See the complete [`ExecuteContext` API reference](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md#command).
- Check out [Plugin Common APIs](https://langbot.app/docs/en/plugin/dev/apis/common.md).

---

# Component: Event Listener

Source: https://langbot.app/docs/en/plugin/dev/components/event-listener

> info:
>
> This component extends Pipeline processing steps. To handle Bot events such as incoming messages and new group members, see [Event Processor](https://langbot.app/docs/en/plugin/dev/components/runner.md).

LangBot's pipeline generates events during runtime for plugins to hook into and process. Each plugin can only have one event listener (components/event\_listener/default.yaml), but can register any number of events within it.

## Adding Event Listener Component

Execute the command `lbp comp EventListener` in the plugin directory. Creating an event listener component doesn't require any configuration.

```bash
➜  HelloPlugin > lbp comp EventListener
Generating component EventListener...
Component EventListener generated successfully.
组件 EventListener 生成成功。
```

This will generate `default.yaml` and `default.py` files in the `components/event_listener/` directory. The `.yaml` file defines the basic information for the event listener, and the `.py` file is the event listener handler:

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   └── event_listener
│       ├── __init__.py
│       ├── default.py
│       └── default.yaml
...
```

## Manifest File: Event Listener

Since each plugin can only have one event listener, no modifications are needed in the manifest file.

## Plugin Processing

The following code is generated by default (components/event\_listener/default.py). You need to register and implement event processing logic in the `initialize` method of the `DefaultEventListener` class.

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from langbot_plugin.api.definition.components.common.event_listener import EventListener
from langbot_plugin.api.entities import events, context


class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()

        "Fill with your code here"
```

Adding listeners for specific events:

```python
...
class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()
        
        @self.handler(events.PersonMessageReceived)
        async def handler(event_context: context.EventContext):
            print("Hello LangBot Plugin!")
            print(event_context)
            
            await event_context.reply(
                platform_message.MessageChain([
                    platform_message.Plain(text=f"Hello from Nahida Plugin!"),
                ])
            )
```

This code registers a listener for the `PersonMessageReceived` (receiving any message from private chat) event, prints the event context (EventContext) information when the event is triggered, and calls the event context API to reply with a message.

EventContext stores common context information for this event trigger, while EventContext.event is an object of PersonMessageReceived (or other corresponding event types), storing detailed information about the event.

```python
# Summary of EventContext definition
class EventContext(pydantic.BaseModel):
    """Event context, stores information for this event execution"""
    ...

    event: pydantic.SerializeAsAny[BaseEventModel]
    """Event object, specific type is the type specified when registering the handler, can be found in events.py"""
    
    ...
```

## Event Registration

Event registration is implemented through the `@self.handler` decorator, with the decorator parameter being the event type. All monitorable events are defined in `langbot_plugin.api.entities.builtin.events`.

## One installation, many usages

The same event listener is called **concurrently by several Workspaces and several events**:

- Never accumulate state per event on the instance (counters, last event, conversation maps); concurrent callbacks will overwrite each other.
- A callback takes its data only from the current `EventContext`; never reuse a context or its fields across calls.
- Data that must survive calls belongs in Host storage, keyed with the installation identity and the event-related identity (Workspace, conversation, and so on).
- If you keep per-installation process-local state, release it in `on_installation_revoked(binding)`.

See [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md) for the full specification.

## What's Next

You have learned the basic information about event listeners. Next, you can:

- See [Pipeline Events](https://langbot.app/docs/en/plugin/dev/apis/pipeline-events.md) for event types and fields.
- See the complete [`EventContext` API reference](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md#eventlistener).
- Check out [Plugin Common APIs](https://langbot.app/docs/en/plugin/dev/apis/common.md)

---

# Component: Knowledge Engine

Source: https://langbot.app/docs/en/plugin/dev/components/knowledge-engine

The Knowledge Engine component allows plugins to provide full knowledge base indexing and retrieval capabilities for LangBot. When users create a knowledge base in LangBot, they can choose a Knowledge Engine provided by a plugin to manage document ingestion, retrieval, and deletion. Plugins can also bridge advanced knowledge base services such as Dify, RAGFlow, FastGPT, and more.

## Adding a Knowledge Engine Component

A single plugin can add any number of Knowledge Engines. Execute the command `lbp comp KnowledgeEngine` in the plugin directory and follow the prompts to enter the Knowledge Engine configuration.

```bash
➜  MyRAGPlugin > lbp comp KnowledgeEngine
Generating component KnowledgeEngine...
Knowledge Engine name: simple_rag
Knowledge Engine description: A simple Knowledge Engine with built-in chunking and retrieval
Component KnowledgeEngine generated successfully.
```

This will generate `simple_rag.yaml` and `simple_rag.py` files in the `components/knowledge_engine/` directory. The `.yaml` file defines the Knowledge Engine's basic information and configuration schemas, and the `.py` file is the handler for this engine:

```bash
➜  MyRAGPlugin > tree
...
├── components
│   ├── __init__.py
│   └── knowledge_engine
│       ├── __init__.py
│       ├── simple_rag.py
│       └── simple_rag.yaml
...
```

## Manifest File: Knowledge Engine

```yaml
apiVersion: v1  # Do not modify
kind: KnowledgeEngine  # Do not modify
metadata:
  name: simple_rag  # Knowledge Engine name, used to identify this engine
  label:
    en_US: Simple Knowledge Engine  # Engine display name, shown in LangBot's UI, supports multiple languages
    zh_Hans: 简易 RAG 引擎
    ja_JP: シンプル RAG エンジン
  description:
    en_US: 'A simple Knowledge Engine with built-in chunking and retrieval'
    zh_Hans: '内置分块和检索能力的简易 RAG 引擎'
    ja_JP: 'チャンキングと検索を内蔵したシンプルなRAGエンジン'
spec:
  creation_schema:  # Configuration parameters users fill in when creating a knowledge base
    - name: chunk_size
      label:
        en_US: Chunk Size
        zh_Hans: 分块大小
      type: integer
      required: false
      default: 500
    - name: chunk_overlap
      label:
        en_US: Chunk Overlap
        zh_Hans: 分块重叠
      type: integer
      required: false
      default: 50
  retrieval_schema:  # Configurable parameters during retrieval
    - name: score_threshold
      label:
        en_US: Score Threshold
        zh_Hans: 分数阈值
      type: float
      required: false
      default: 0.5
execution:
  python:
    path: simple_rag.py  # Engine handler, do not modify
    attr: SimpleRag  # Class name of the engine handler, consistent with the class name in simple_rag.py
```

For configuration item format reference, see: [Plugin Manifest Configuration Format](https://langbot.app/docs/en/plugin/dev/basic-info.md)

### creation\_schema and retrieval\_schema

Unlike the old `KnowledgeRetriever` component which used a single `spec.config`, KnowledgeEngine uses two separate schemas:

- **creation\_schema**: Parameters users fill in when creating a knowledge base. These are passed to the plugin via `creation_settings` during ingestion and retrieval.
- **retrieval\_schema**: Parameters users can adjust when querying the knowledge base. These are passed to the plugin via `retrieval_settings`.

## Capability Declaration

KnowledgeEngine can declare its supported capabilities. LangBot uses these capability declarations to determine UI behavior and available operations:

```python
from langbot_plugin.api.definition.components.knowledge_engine.engine import KnowledgeEngine, KnowledgeEngineCapability

class SimpleRag(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return [
            KnowledgeEngineCapability.DOC_INGESTION,    # Supports document upload and processing
        ]
```

Available capability constants:

| Capability      | Description                                                                                                                                                                                                                                                                                                                                                      |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOC_INGESTION` | Supports document upload and processing. When declared, LangBot shows a "Documents" tab in the knowledge base details. If the plugin is used to bridge other knowledge base services or does not require users to upload documents, this capability declaration can be omitted.                                                                                  |
| `DOC_PARSING`   | Supports native document parsing (file-to-text extraction). When declared, users can choose to use the Knowledge Engine's built-in parsing when uploading documents, without needing an external [Parser plugin](https://langbot.app/docs/en/plugin/dev/components/parser.md). If not declared, an external Parser plugin must be installed to upload documents. |

> info:
>
> Other retrieval behaviors (such as reranking, hybrid search, etc.) are controlled by the plugin's `retrieval_schema` and do not need capability flags.

## Plugin Handler

The following code will be generated by default (`components/knowledge_engine/<engine_name>.py`). You need to implement the three core methods: `ingest`, `retrieve`, and `delete_document`. Complete code can be found in the `SimpleKnowledgeEngine` example in [langbot-plugin-demo](https://github.com/langbot-app/langbot-plugin-demo).

```python
from langbot_plugin.api.definition.components.knowledge_engine.engine import KnowledgeEngine, KnowledgeEngineCapability
from langbot_plugin.api.entities.builtin.rag.models import (
    IngestionContext,
    IngestionResult,
)
from langbot_plugin.api.entities.builtin.rag.context import (
    RetrievalContext,
    RetrievalResponse,
    RetrievalResultEntry,
)
from langbot_plugin.api.entities.builtin.rag.enums import DocumentStatus
from langbot_plugin.api.entities.builtin.provider.message import ContentElement


class SimpleRag(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return [KnowledgeEngineCapability.DOC_INGESTION]

    async def on_knowledge_base_create(self, kb_id: str, config: dict) -> None:
        """Callback when a knowledge base is created, can be used to initialize resources"""
        pass

    async def on_knowledge_base_delete(self, kb_id: str) -> None:
        """Callback when a knowledge base is deleted, can be used to clean up resources"""
        pass

    async def ingest(self, context: IngestionContext) -> IngestionResult:
        """Ingest a document into the knowledge base"""

        # 1. Get file content
        file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)

        # 2. Parse document and split into chunks
        text = file_bytes.decode('utf-8')
        chunk_size = context.creation_settings.get('chunk_size', 500)
        chunk_overlap = context.creation_settings.get('chunk_overlap', 50)
        chunks = self._split_text(text, chunk_size, chunk_overlap)

        # 3. Generate embeddings using host embedding model
        embedding_model_uuid = context.creation_settings.get('embedding_model_uuid', '')
        vectors = await self.plugin.invoke_embedding(embedding_model_uuid, chunks)

        # 4. Write to host vector database
        collection_id = context.get_collection_id()
        ids = [f"{context.file_object.metadata.document_id}_{i}" for i in range(len(chunks))]
        metadata = [{"document_id": context.file_object.metadata.document_id, "chunk_index": i, "text": chunks[i]} for i in range(len(chunks))]
        await self.plugin.vector_upsert(collection_id, vectors, ids, metadata)

        return IngestionResult(
            document_id=context.file_object.metadata.document_id,
            status=DocumentStatus.COMPLETED,
            chunks_created=len(chunks),
        )

    async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
        """Retrieve relevant content from the knowledge base"""

        # 1. Generate query vector
        embedding_model_uuid = context.creation_settings.get('embedding_model_uuid', '')
        query_vectors = await self.plugin.invoke_embedding(embedding_model_uuid, [context.query])
        query_vector = query_vectors[0]

        # 2. Vector search
        collection_id = context.get_collection_id()
        results = await self.plugin.vector_search(collection_id, query_vector, top_k=context.retrieval_settings.get('top_k', 5))

        # 3. Convert to retrieval results
        entries = []
        for r in results:
            entry = RetrievalResultEntry(
                id=r.get('id', ''),
                content=[ContentElement.from_text(r.get('metadata', {}).get('text', ''))],
                metadata=r.get('metadata', {}),
                distance=r.get('score', 0.0),
            )
            entries.append(entry)

        return RetrievalResponse(
            results=entries,
            total_found=len(entries),
            metadata={},
        )

    async def delete_document(self, kb_id: str, document_id: str) -> bool:
        """Delete a document and its associated data from the knowledge base"""
        collection_id = kb_id
        deleted = await self.plugin.vector_delete(collection_id, file_ids=[document_id])
        return deleted > 0
```

### Lifecycle Hooks

KnowledgeEngine provides two lifecycle hooks that are called when knowledge bases are created and deleted:

```python
async def on_knowledge_base_create(self, kb_id: str, config: dict) -> None:
    """Callback when a knowledge base using this engine is created

    Args:
        kb_id: Knowledge base UUID
        config: User-provided configuration (fields from creation_schema)
    """

async def on_knowledge_base_delete(self, kb_id: str) -> None:
    """Callback when a knowledge base using this engine is deleted

    Args:
        kb_id: Knowledge base UUID
    """
```

### Document Ingestion

The `ingest` method is called when a user uploads a document to the knowledge base:

```python
async def ingest(self, context: IngestionContext) -> IngestionResult:
```

**IngestionContext** contains the following information:

```python
class IngestionContext(pydantic.BaseModel):
    file_object: FileObject        # File object to ingest
    knowledge_base_id: str         # Target knowledge base ID
    collection_id: str | None      # Vector collection ID (falls back to knowledge_base_id)
    creation_settings: dict        # Configuration from knowledge base creation
    parsed_content: ParseResult | None  # Pre-parsed content from external Parser plugin (if any)
```

**FileObject** contains file metadata:

```python
class FileObject(pydantic.BaseModel):
    metadata: FileMetadata    # Contains filename, file_size, mime_type, document_id, knowledge_base_id, etc.
    storage_path: str         # File path in the storage system
```

**IngestionResult** should return the ingestion result:

```python
class IngestionResult(pydantic.BaseModel):
    document_id: str                  # Document ID
    status: DocumentStatus            # Processing status: COMPLETED / FAILED
    chunks_created: int = 0           # Number of chunks created
    error_message: str | None = None  # Error message on failure
    metadata: dict = {}               # Additional metadata
```

### Knowledge Retrieval

The `retrieve` method is called when the knowledge base is queried:

```python
async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
```

**RetrievalContext** contains the following information:

```python
class RetrievalContext(pydantic.BaseModel):
    query: str                           # Query text
    knowledge_base_id: str | None        # Knowledge base ID
    collection_id: str | None            # Vector collection ID
    retrieval_settings: dict             # Retrieval configuration (fields from retrieval_schema)
    creation_settings: dict              # Knowledge base creation configuration
    filters: dict                        # Metadata filter conditions (Chroma-style where syntax)
```

> info:
>
> The LangBot host automatically injects a default `top_k` value (default 5) into `retrieval_settings` before passing it to the plugin. Plugins can access it via `context.retrieval_settings.get('top_k', 5)`.
>
> The `filters` field contains Chroma-style `where` filter conditions extracted from `retrieval_settings`. When the caller provides `filters` in the retrieval settings (e.g., filtering by time range, file type, or custom metadata fields), the host populates this field so plugins can apply them during retrieval. If no filters are provided, this field is an empty dict.

**RetrievalResponse** should return the retrieval results:

```python
class RetrievalResponse(pydantic.BaseModel):
    results: list[RetrievalResultEntry]  # List of retrieval results
    total_found: int                     # Total number of matches
    metadata: dict                       # Additional metadata
```

**RetrievalResultEntry** represents a single retrieval result:

```python
class RetrievalResultEntry(pydantic.BaseModel):
    id: str                       # Result ID
    content: list[ContentElement] # Content, create using ContentElement.from_text()
    metadata: dict                # Metadata
    distance: float               # Distance score (smaller is more relevant)
    score: float | None = None    # Similarity score (larger is more relevant)
```

### Document Deletion

The `delete_document` method is called when a user deletes a document from the knowledge base:

```python
async def delete_document(self, kb_id: str, document_id: str) -> bool:
    """Delete a document and its associated data

    Args:
        kb_id: Knowledge base ID
        document_id: Document ID

    Returns:
        Whether the deletion was successful
    """
```

## Host RAG APIs

KnowledgeEngine components can call LangBot host-provided RAG APIs via `self.plugin`, including embedding model invocation, vector database operations, and file retrieval.

### Invoke Embedding Model

```python
async def invoke_embedding(
    self,
    embedding_model_uuid: str,
    texts: list[str],
) -> list[list[float]]:
    """Generate embeddings using host's embedding model

    Args:
        embedding_model_uuid: Embedding model UUID
        texts: List of texts to embed

    Returns:
        List of embedding vectors, one per input text
    """

# Usage example
vectors = await self.plugin.invoke_embedding("model_uuid", ["Hello", "World"])
```

### Vector Upsert

```python
async def vector_upsert(
    self,
    collection_id: str,
    vectors: list[list[float]],
    ids: list[str],
    metadata: list[dict] | None = None,
) -> None:
    """Upsert vectors to host's vector database

    Args:
        collection_id: Target collection ID
        vectors: List of vectors
        ids: List of unique IDs for vectors
        metadata: Optional list of metadata dicts
    """

# Usage example
await self.plugin.vector_upsert(
    collection_id="kb_uuid",
    vectors=[[0.1, 0.2, ...], [0.3, 0.4, ...]],
    ids=["chunk_0", "chunk_1"],
    metadata=[{"document_id": "doc1"}, {"document_id": "doc1"}],
)
```

### Vector Search

```python
async def vector_search(
    self,
    collection_id: str,
    query_vector: list[float],
    top_k: int = 5,
    filters: dict | None = None,
) -> list[dict]:
    """Search similar vectors in host's vector database

    Args:
        collection_id: Target collection ID
        query_vector: Query vector for similarity search
        top_k: Number of results to return
        filters: Optional metadata filters

    Returns:
        List of search results (dict with id, score, metadata, etc.)
    """

# Usage example
results = await self.plugin.vector_search(
    collection_id="kb_uuid",
    query_vector=[0.1, 0.2, ...],
    top_k=5,
)
# Return format: [{"id": "chunk_0", "score": 0.123, "metadata": {"document_id": "doc1", ...}}, ...]
```

> info:
>
> Each result returned by `vector_search` is a dict containing `id` (vector ID), `score` (distance score), and `metadata` (metadata provided during upsert). If you need text content in retrieval results, store the text in metadata during ingestion.

### Vector Delete

```python
async def vector_delete(
    self,
    collection_id: str,
    file_ids: list[str] | None = None,
    filters: dict | None = None,
) -> int:
    """Delete vectors from host's vector database

    Args:
        collection_id: Target collection ID
        file_ids: File IDs whose vectors should be deleted
        filters: Optional metadata filters for deletion

    Returns:
        Number of deleted items
    """

# Usage example
deleted = await self.plugin.vector_delete(
    collection_id="kb_uuid",
    file_ids=["doc_001"],
)
```

> info:
>
> The `filters` parameter supports Chroma-style `where` syntax for metadata filtering. Multiple top-level keys are AND-ed. Supported operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`. Example: `{"file_id": {"$eq": "abc"}}`.
>
> **Note:** Chroma, Qdrant, and SeekDB store full metadata and can filter on any field. Milvus and pgvector only store `text`, `file_id`, and `chunk_uuid` — filters on other fields will be silently ignored.

```python
async def get_knowledge_file_stream(self, storage_path: str) -> bytes:
    """Get file content from host storage

    Args:
        storage_path: File storage path (from FileObject.storage_path)

    Returns:
        File content as bytes
    """

# Usage example
file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)
```

## One installation, many usages

A single knowledge engine is used by **several knowledge bases** at once, and the platform storage key `(instance, Workspace, owner type, plugin, key)` carries no knowledge-base dimension:

- Persistence and cache keys must include the **knowledge-base ID**, otherwise vectors and document state of different knowledge bases overwrite each other.
- Locks and reconciliation state must be keyed by `(installation, knowledge base)`; **a failure while ingesting one knowledge base must not block ingestion or retrieval of the others under the same installation**.
- Only a dispatched mutation with an unknown outcome should enter a state that needs manual reconciliation; deterministic validation errors and pre-dispatch cancellation must not affect later calls.
- Telemetry and diagnostic failures must not affect the work: never let a log or report failure interrupt ingestion or retrieval, and never write tenant data into a process-wide singleton.
- If you keep per-installation process-local caches or state, release them in `on_installation_revoked(binding)`.

See [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md) for the full specification.

## Testing the Knowledge Engine

After creation, execute the command `lbp run` in the plugin directory to start debugging. Then in LangBot:

1. Go to the "Knowledge Base" page
2. Click "Create Knowledge Base"
3. Select the Knowledge Engine provided by your plugin and fill in the configuration based on the engine's `creation_schema`
4. After creation, upload documents to test ingestion capabilities (if the engine declares `DOC_INGESTION` capability)
5. Bind the knowledge base to a pipeline and test retrieval capabilities

---

# Component: Knowledge Retriever

Source: https://langbot.app/docs/en/plugin/dev/components/knowledge-retriever

The Knowledge Retriever component allows plugins to provide external knowledge base retrieval capabilities for LangBot. When users create an external knowledge base in LangBot, they can choose a knowledge retriever provided by a plugin to retrieve knowledge.

![](https://langbot.app/docs/images/zh/plugin/dev/components/knowledge_retriever_use.png)

## Adding a Knowledge Retriever Component

A single plugin can add any number of knowledge retrievers. Execute the command `lbp comp KnowledgeRetriever` in the plugin directory and follow the prompts to enter the knowledge retriever configuration.

```bash
➜  FastGPTRetriever > lbp comp KnowledgeRetriever
Generating component KnowledgeRetriever...
KnowledgeRetriever name: fastgpt
KnowledgeRetriever description: Retrieve knowledge from FastGPT knowledge bases
Component KnowledgeRetriever generated successfully.
```

This will generate `fastgpt.yaml` and `fastgpt.py` files in the `components/knowledge_retriever/` directory. The `.yaml` file defines the basic information and configuration parameters of the knowledge retriever, and the `.py` file is the handler for this retriever:

```bash
➜  FastGPTRetriever > tree
...
├── components
│   ├── __init__.py
│   └── knowledge_retriever
│       ├── __init__.py
│       ├── fastgpt.py
│       └── fastgpt.yaml
...
```

## Manifest File: Knowledge Retriever

```yaml
apiVersion: v1  # Do not modify
kind: KnowledgeRetriever  # Do not modify
metadata:
  name: fastgpt  # Knowledge retriever name, used to identify this retriever
  label:
    en_US: FastGPT Knowledge Base  # Retriever display name, shown in LangBot's UI, supports multiple languages
    zh_Hans: FastGPT 知识库
    ja_JP: FastGPT ナレッジベース
  description:
    en_US: 'Retrieve knowledge from FastGPT knowledge bases'  # Retriever description, shown in LangBot's UI, supports multiple languages. Optional
    zh_Hans: '从 FastGPT 知识库中检索知识'
    ja_JP: 'FastGPT ナレッジベースから知識を取得'
  icon: assets/icon.svg  # Retriever icon, displayed on the external knowledge base configuration page
spec:
  config:  # Retriever configuration parameters, users need to fill in these parameters when creating an external knowledge base
    - name: api_base_url  # Parameter name
      type: string  # Parameter type: string, number, boolean, select
      label:
        en_US: API Base URL
        zh_Hans: API 基础地址
        ja_JP: API ベース URL
      description:
        en_US: 'Base URL for FastGPT API'
        zh_Hans: 'FastGPT API 基础地址'
        ja_JP: 'FastGPT API ベース URL'
      default: 'http://localhost:3000'  # Default parameter value
      required: true  # Whether required
    - name: api_key
      type: string
      label:
        en_US: FastGPT API Key
        zh_Hans: FastGPT API Key
        ja_JP: FastGPT API キー
      description:
        en_US: 'API key from your FastGPT instance'
        zh_Hans: '从您的 FastGPT 实例获取的 API Key'
        ja_JP: 'FastGPT インスタンスから取得した API Key'
      default: ''
      required: true
    - name: search_mode  # Example of select type parameter
      type: select
      label:
        en_US: Search Mode
        zh_Hans: 搜索模式
        ja_JP: 検索モード
      description:
        en_US: 'The search method to use'
        zh_Hans: '使用的搜索方法'
        ja_JP: '使用する検索方法'
      default: 'embedding'
      options:  # Select type parameters need to define an option list
      - name: 'embedding'
        label:
          en_US: 'Embedding Search'
          zh_Hans: '向量搜索'
          ja_JP: '埋め込み検索'
      - name: 'fullTextRecall'
        label:
          en_US: 'Full-Text Recall'
          zh_Hans: '全文检索'
          ja_JP: '全文検索'
    - name: using_rerank  # Example of boolean type parameter
      type: boolean
      label:
        en_US: Use Re-ranking
        zh_Hans: 使用重排序
        ja_JP: リランキングを使用
      description:
        en_US: 'Whether to use re-ranking'
        zh_Hans: '是否使用重排序'
        ja_JP: 'リランキングを使用するかどうか'
      default: false
      required: false
execution:
  python:
    path: fastgpt.py  # Retriever handler, do not modify
    attr: FastGPT  # Class name of the retriever handler, consistent with the class name in fastgpt.py
```

For configuration item format reference, see: [Plugin Manifest Configuration Format](https://langbot.app/docs/en/plugin/dev/basic-info.md)

## Plugin Handler

The following code will be generated by default (`components/knowledge_retriever/<retriever_name>.py`). You need to implement the knowledge retrieval logic in the `retrieve` method of the `FastGPT` class. Complete code can be found in [langbot-plugin-demo](https://github.com/langbot-app/langbot-plugin-demo).

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
...

class FastGPT(KnowledgeRetriever):

    async def retrieve(self, context: RetrievalContext) -> list[RetrievalResultEntry]:
        """Retrieve knowledge from FastGPT knowledge base"""

        # 1. Get configuration parameters
        api_base_url = self.config.get('api_base_url', 'http://localhost:3000')
        api_key = self.config.get('api_key')
        dataset_id = self.config.get('dataset_id')
        search_mode = self.config.get('search_mode', 'embedding')
        using_rerank = self.config.get('using_rerank', False)

        # 2. Parameter validation
        if not api_key or not dataset_id:
            logger.error("Missing required configuration: api_key or dataset_id")
            return []

        # 3. Build API request
        url = f"{api_base_url.rstrip('/')}/api/core/dataset/searchTest"
        headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
        payload = {
            "datasetId": dataset_id,
            "text": context.query,  # Get query text from RetrievalContext
            "searchMode": search_mode,
            "usingReRank": using_rerank,
        }

        try:
            # 4. Call external API
            async with httpx.AsyncClient() as client:
                response = await client.post(url, json=payload, headers=headers, timeout=30.0)
                response.raise_for_status()
                result = response.json()

            # 5. Parse response and convert to RetrievalResultEntry
            results = []
            for record in result.get('data', []):
                # Combine main data and auxiliary data as content
                content_text = '\n'.join([
                    record.get('q', ''),
                    record.get('a', '')
                ]).strip()

                # Create retrieval result entry
                entry = RetrievalResultEntry(
                    id=record.get('id', ''),
                    content=[ContentElement.from_text(content_text)],
                    metadata={
                        'dataset_id': record.get('datasetId', ''),
                        'source_name': record.get('sourceName', ''),
                        'score': record.get('score', 0.0),
                    },
                    # Convert similarity score to distance (higher score = smaller distance)
                    distance=1.0 - float(record.get('score', 0.0)),
                )
                results.append(entry)

            logger.info(f"Retrieved {len(results)} chunks from FastGPT dataset {dataset_id}")
            return results

        except httpx.HTTPStatusError as e:
            logger.error(f"HTTP error from FastGPT API: {e.response.status_code} - {e.response.text}")
            return []
        except httpx.RequestError as e:
            logger.error(f"Request error when calling FastGPT API: {str(e)}")
            return []
        except Exception as e:
            traceback.print_exc()
            logger.error(f"Unexpected error during retrieval: {str(e)}")
            return []
```

### Retrieval Context

`RetrievalContext` contains context information for this retrieval:

```python
class RetrievalContext(pydantic.BaseModel):
    """Knowledge retrieval context"""

    query: str
    """Query text, the user's retrieval question"""
```

### Retrieval Results

Retrieval results need to be converted to a list of `RetrievalResultEntry` objects, each representing a retrieved knowledge chunk:

```python
class RetrievalResultEntry(pydantic.BaseModel):
    """Single retrieval result entry"""

    id: str
    """Result ID, uniquely identifies this entry"""

    content: list[ContentElement]
    """Result content, create text content using ContentElement.from_text()"""

    metadata: dict[str, Any]
    """Result metadata, can contain any key-value pairs, such as source, score, etc."""

    distance: float
    """Distance score, indicates relevance to the query (smaller is more relevant)
    Usually calculated as 1.0 - similarity_score"""
```

### Getting Configuration Parameters

Get user-configured parameter values using `self.config.get(parameter_name, default_value)`:

```python
# Get string parameter
api_base_url = self.config.get('api_base_url', 'http://localhost:3000')

# Get number parameters
limit = self.config.get('limit', 5000)
similarity = self.config.get('similarity', 0.0)

# Get boolean parameter
using_rerank = self.config.get('using_rerank', False)

# Get select parameter
search_mode = self.config.get('search_mode', 'embedding')
```

## One installation, many usages

A single knowledge retriever is used by **several knowledge bases**, and the platform storage key `(instance, Workspace, owner type, plugin, key)` carries no knowledge-base dimension:

- Any cache, index or intermediate result used for retrieval must be isolated by **knowledge-base ID**, with the ID in the key; never keep it on the instance.
- Key retrieval locks and reconciliation state by `(installation, knowledge base)`; a retrieval failure in one knowledge base must not make retrieval unavailable for the others under the same installation.
- `RetrievalContext` is valid only for a single retrieval; never store it or its results on instance fields for reuse across calls.
- Knowledge-base data that must survive calls belongs in Host storage, with a key that includes both the installation identity and the knowledge-base ID.
- If you cache connections, indexes or any other process-local state per installation, release them in `on_installation_revoked(binding)`.

See [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md) for the full specification.

## Testing the Retriever

After creation, execute the command `lbp run` in the plugin directory to start debugging. Then in LangBot:

1. Go to the "Knowledge Base" page
2. Add an external knowledge base
3. Select the knowledge retriever provided by your plugin and fill in the configuration

![](https://langbot.app/docs/images/zh/plugin/dev/components/knowledge_retriever_config.png)

After saving, you can select this knowledge base in the LangBot pipeline.

---

# Component: Page

Source: https://langbot.app/docs/en/plugin/dev/components/page

The Page component allows plugins to register custom visual pages in the LangBot WebUI sidebar. Pages run inside an iframe sandbox, communicate with the host via the Page SDK, and can call the plugin's backend API.

## Use Cases

- **Admin panels**: Provide visual configuration and data management interfaces (e.g., FAQ management, analytics dashboards)
- **Data displays**: Show runtime statistics, logs, charts, etc.
- **Interactive tools**: Provide forms, editors, and other interactive interfaces

![](https://langbot.app/docs/images/zh/plugin/dev/components/plugin-page-demo.png)

## Adding a Page Component

Run the following command in the plugin directory:

```bash
lbp comp Page
```

After entering the page name, the CLI will generate page files under `components/pages/`:

```bash
├── components
│   └── pages
│       └── dashboard
│           ├── dashboard.yaml   # Page manifest
│           ├── dashboard.py     # Backend handler
│           ├── index.html       # Page entry point
│           └── i18n             # Translation files (optional)
│               ├── en_US.json
│               └── zh_Hans.json
```

The plugin's `manifest.yaml` will also be updated with the component discovery config:

```yaml
spec:
  components:
    Page:
      fromDirs:
      - path: components/pages/
        maxDepth: 2
```

## Manifest File: Page

```yaml
apiVersion: v1  # Do not modify
kind: Page  # Do not modify
metadata:
  name: dashboard  # Unique page ID within the plugin
  label:
    en_US: Dashboard  # Display name shown in the WebUI sidebar, supports i18n
    zh_Hans: 仪表盘
spec:
  path: index.html  # HTML entry file, relative to this YAML file's directory
execution:
  python:
    path: dashboard.py  # Backend handler file
    attr: DashboardPage  # Handler class name
```

## Backend Handler

The Page component's backend handler extends the `Page` base class and implements `handle_api` to process API requests from the frontend page.

```python
from langbot_plugin.api.definition.components.page import Page, PageRequest, PageResponse


class DashboardPage(Page):

    async def handle_api(self, request: PageRequest) -> PageResponse:
        # request.endpoint: API endpoint path, e.g. '/stats'
        # request.method:   HTTP method (GET, POST, PUT, DELETE)
        # request.body:     Request body (parsed JSON, or None)

        if request.endpoint == '/stats' and request.method == 'GET':
            # Read installation-scoped data from a Host storage API.
            entries = await self.load_entries_for_current_installation()
            return PageResponse.ok({'total': len(entries)})

        return PageResponse.fail(f'Unknown endpoint: {request.endpoint}')
```

### PageRequest Fields

| Field      | Type  | Description                                  |
| ---------- | ----- | -------------------------------------------- |
| `endpoint` | `str` | API endpoint path (e.g. `'/entries'`)        |
| `method`   | `str` | HTTP method (`GET`, `POST`, `PUT`, `DELETE`) |
| `body`     | `Any` | Request body (parsed JSON, or `None`)        |

### PageResponse Construction

| Method                     | Description                                                 |
| -------------------------- | ----------------------------------------------------------- |
| `PageResponse.ok(data)`    | Success response. `data` can be any JSON-serializable value |
| `PageResponse.fail(error)` | Error response. `error` is a human-readable error string    |

## Frontend Page Development

Include the Page SDK in your HTML file to communicate with the plugin backend:

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <style>
    body {
      background: var(--langbot-bg, #ffffff);
      color: var(--langbot-text, #0a0a0a);
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      padding: 24px;
    }
  </style>
</head>
<body>
  <h1 data-i18n="title">Dashboard</h1>
  <p id="stats"></p>

  <script src="/api/v1/plugins/_sdk/page-sdk.js"></script>
  <script>
    langbot.onReady(async function(ctx) {
      // Call the backend API
      var data = await langbot.api('/stats', null, 'GET');
      document.getElementById('stats').textContent = 'Total: ' + data.total;
    });
  </script>
</body>
</html>
```

### Page SDK API

| Method                                  | Description                                                                    |
| --------------------------------------- | ------------------------------------------------------------------------------ |
| `langbot.onReady(callback)`             | Fires when SDK is ready. `callback` receives `ctx` with `theme` and `language` |
| `langbot.api(endpoint, body?, method?)` | Calls the plugin's `handle_api`. Returns a Promise                             |
| `langbot.t(key, fallback?)`             | Gets a translated string                                                       |
| `langbot.onThemeChange(callback)`       | Fires when the theme changes                                                   |
| `langbot.onLanguageChange(callback)`    | Fires when the language changes                                                |
| `langbot.applyI18n()`                   | Manually re-apply `data-i18n` translations                                     |

### Dark Mode

The SDK automatically sets CSS custom properties on the page. Use them directly:

| CSS Variable           | Purpose              |
| ---------------------- | -------------------- |
| `--langbot-bg`         | Page background      |
| `--langbot-bg-card`    | Card background      |
| `--langbot-text`       | Primary text color   |
| `--langbot-text-muted` | Secondary text color |
| `--langbot-border`     | Border color         |
| `--langbot-accent`     | Accent color         |

### Page i18n

Create an `i18n/` directory inside your page directory with JSON translation files:

```
pages/dashboard/
├── index.html
└── i18n/
    ├── en_US.json
    └── zh_Hans.json
```

Translation files are flat JSON key-value pairs:

```json
{
  "title": "Dashboard",
  "totalEntries": "Total Entries"
}
```

Add the `data-i18n` attribute to HTML elements for automatic translation:

```html
<h1 data-i18n="title">Dashboard</h1>
```

## Full Example: FAQ Manager

Here is a complete Page component example that implements CRUD operations for FAQ entries.

**Backend handler** (`components/pages/manager/manager.py`):

```python
from langbot_plugin.api.definition.components.page import Page, PageRequest, PageResponse


class ManagerPage(Page):

    async def handle_api(self, request: PageRequest) -> PageResponse:
        if request.endpoint == '/entries' and request.method == 'GET':
            entries = await self.load_entries_for_current_installation()
            return PageResponse.ok({'entries': entries})

        if request.endpoint == '/entries' and request.method == 'POST':
            question = (request.body or {}).get('question', '').strip()
            answer = (request.body or {}).get('answer', '').strip()
            if not question or not answer:
                return PageResponse.fail('question and answer are required')
            entry = {'question': question, 'answer': answer}
            await self.save_entry_for_current_installation(entry)
            return PageResponse.ok({'entry': entry})

        if request.endpoint == '/entries' and request.method == 'DELETE':
            entry_id = (request.body or {}).get('id', '')
            if await self.delete_entry_for_current_installation(entry_id):
                return PageResponse.ok({'deleted': entry_id})
            return PageResponse.fail('entry not found')

        return PageResponse.fail(f'Unknown: {request.method} {request.endpoint}')
```

**Frontend page** (`components/pages/manager/index.html`) calls the backend via `langbot.api()`:

```javascript
// Load entries
var data = await langbot.api('/entries', null, 'GET');

// Add entry
await langbot.api('/entries', { question: '...', answer: '...' }, 'POST');

// Delete entry
await langbot.api('/entries', { id: '...' }, 'DELETE');
```

Full example code is available at [FAQManager plugin](https://github.com/langbot-app/langbot-plugin-demo/tree/main/FAQManager).

## One installation, many usages

The same Page is called by **many page requests** (different requests and different Workspaces under one installation):

- Never leave the previous request's data on the instance; take the endpoint, method, body and current installation information from the current `PageRequest` / binding every time.
- Page data always lives in installation-scoped Host storage; `self.plugin` is a process-level shared object and must not hold tenant data.
- Requests from different Workspaces share the same Page instance, so instance fields get interleaved; data that must survive requests belongs in Host storage.
- If you keep per-installation process-local caches, release them in `on_installation_revoked(binding)`.

See [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md) for the full specification.

## Notes

- Pages run inside a `sandbox="allow-scripts allow-forms"` iframe and cannot open popups or navigate the parent page
- Certified Pages must keep tenant data in installation-scoped Host storage. `self.plugin` is process-wide and must not hold tenant entries. The storage helper names above are illustrative; use the current SDK Host storage APIs available to your component.
- Use `PageResponse.ok()` and `PageResponse.fail()` to construct responses for consistent formatting
- The Page SDK `<script>` tag must be placed before any code that uses the `langbot` object

---

# Component: Parser

Source: https://langbot.app/docs/en/plugin/dev/components/parser

The Parser component allows plugins to provide document parsing capabilities for LangBot. When a user uploads a document to a knowledge base, LangBot invokes the parser before the Knowledge Engine's `ingest` step, extracting structured text from binary files such as PDF, Word, Markdown, etc.

Relationship between Parser and KnowledgeEngine:

- **Parser** is responsible for converting files to text (file → text)
- **KnowledgeEngine** is responsible for indexing and retrieving text (text → chunks → vectors)

If the Knowledge Engine already has native document parsing capabilities (declared `DOC_PARSING` capability), users can choose to use the Knowledge Engine's built-in parsing or an external Parser plugin.

## Adding a Parser Component

A single plugin can add any number of parsers. Execute the command `lbp comp Parser` in the plugin directory and follow the prompts to enter the parser configuration.

```bash
➜  MyParserPlugin > lbp comp Parser
Generating component Parser...
Parser name: pdf_parser
Parser description: A PDF document parser
Component Parser generated successfully.
```

This will generate `pdf_parser.yaml` and `pdf_parser.py` files in the `components/parser/` directory. The `.yaml` file defines the parser's basic information and supported MIME types, and the `.py` file is the handler for this parser:

```bash
➜  MyParserPlugin > tree
...
├── components
│   ├── __init__.py
│   └── parser
│       ├── __init__.py
│       ├── pdf_parser.py
│       └── pdf_parser.yaml
...
```

## Manifest File: Parser

```yaml
apiVersion: v1  # Do not modify
kind: Parser  # Do not modify
metadata:
  name: pdf_parser  # Parser name, used to identify this parser
  label:
    en_US: PDF Parser  # Parser display name, shown in LangBot's UI, supports multiple languages
    zh_Hans: PDF 解析器
  description:
    en_US: 'A PDF document parser'
    zh_Hans: 'PDF 文档解析器'
spec:
  supported_mime_types:  # Declare supported file MIME types
    - application/pdf
execution:
  python:
    path: pdf_parser.py  # Parser handler, do not modify
    attr: PdfParser  # Class name of the parser handler, consistent with the class name in pdf_parser.py
```

### supported\_mime\_types

`supported_mime_types` declares the file types this parser supports. Common MIME types:

| MIME Type                                                                 | Description            |
| ------------------------------------------------------------------------- | ---------------------- |
| `application/pdf`                                                         | PDF documents          |
| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | Word documents (.docx) |
| `text/markdown`                                                           | Markdown files         |
| `text/plain`                                                              | Plain text files       |
| `text/html`                                                               | HTML files             |

## Plugin Handler

The following code will be generated by default (`components/parser/<parser_name>.py`). You need to implement the `parse` method.

```python
from langbot_plugin.api.definition.components.parser.parser import Parser
from langbot_plugin.api.entities.builtin.rag.models import (
    ParseContext,
    ParseResult,
    TextSection,
)


class PdfParser(Parser):
    """Parser component for extracting text from files."""

    async def parse(self, context: ParseContext) -> ParseResult:
        """Parse a file and extract structured text.

        Args:
            context: Contains file_content (bytes), mime_type, filename, and metadata.

        Returns:
            ParseResult with extracted text and optional structured sections.
        """
        # TODO: Implement parsing logic
        text = context.file_content.decode("utf-8", errors="replace")

        return ParseResult(
            text=text,
            sections=[
                TextSection(
                    content=text,
                    heading=context.filename,
                    level=0,
                ),
            ],
            metadata={
                "filename": context.filename,
                "mime_type": context.mime_type,
            },
        )
```

### Parse Method

The `parse` method is called when a document is uploaded to a knowledge base (before Knowledge Engine ingestion):

```python
async def parse(self, context: ParseContext) -> ParseResult:
```

**ParseContext** contains the following information:

```python
class ParseContext(pydantic.BaseModel):
    file_content: bytes          # Raw file bytes (read by LangBot from storage)
    mime_type: str               # Detected MIME type of the file
    filename: str                # Original filename
    metadata: dict[str, Any]     # Extra metadata from FileObject
```

**ParseResult** should return the parsing result:

```python
class ParseResult(pydantic.BaseModel):
    text: str                            # Full extracted plain text
    sections: list[TextSection] = []     # Structured sections (optional)
    metadata: dict[str, Any] = {}        # Parsing metadata (e.g., page_count, language)
```

**TextSection** represents a section of text extracted from the document:

```python
class TextSection(pydantic.BaseModel):
    content: str                   # Section text content
    heading: str | None = None     # Section heading
    level: int = 0                 # Nesting level
    page: int | None = None        # Source page number (for PDF, etc.)
    metadata: dict[str, Any] = {}  # Additional section metadata
```

## Integration with KnowledgeEngine

When a user uploads a document, LangBot determines the parsing flow as follows:

- If the user selects an external Parser plugin, LangBot first calls the Parser's `parse` method, then passes the result to the Knowledge Engine's `ingest` method via `IngestionContext.parsed_content`.
- If the Knowledge Engine declares `DOC_PARSING` capability and the user does not select an external parser, the Knowledge Engine handles document parsing on its own.

KnowledgeEngine can check `IngestionContext.parsed_content` to determine whether pre-parsed content is available:

```python
async def ingest(self, context: IngestionContext) -> IngestionResult:
    if context.parsed_content:
        # Use pre-parsed content from external Parser
        text = context.parsed_content.text
        sections = context.parsed_content.sections
    else:
        # Parse the document internally
        file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)
        text = file_bytes.decode('utf-8')
    ...
```

## Cross-Plugin Parser Invocation

Before invoking a parser from another plugin, you can use `self.plugin.list_parsers` to discover the parsers currently available on the host:

```python
parsers = await self.plugin.list_parsers(mime_type="application/pdf")
# Each item includes plugin_id, plugin_author, plugin_name, name, description, supported_mime_types
```

If the list is empty, no connected Parser plugin currently supports that MIME type.

After obtaining `plugin_author` and `plugin_name`, you can call `self.plugin.invoke_parser`:

```python
parser = parsers[0]
result = await self.plugin.invoke_parser(
    plugin_author=parser["plugin_author"],
    plugin_name=parser["plugin_name"],
    storage_path=context.file_object.storage_path,
    mime_type=context.file_object.metadata.mime_type,
    filename=context.file_object.metadata.filename,
    metadata={},
)
# result is a dict containing text, sections, metadata
```

## One installation, many usages

A single Parser is used by **several knowledge bases** (different knowledge bases of one installation upload files of different MIME types), and the platform storage key carries no knowledge-base dimension:

- Parse caches and temporary files must be isolated by **knowledge-base ID**, with the ID in the key; never cache them on the instance.
- `ParseContext` and intermediate parse results are valid only for a single parse; never store them on instance fields or module-level variables.
- A parse failure affects only that upload of the current knowledge base; it must not make parsing unavailable for the other knowledge bases.
- If you cache models, parsers or temporary directories per installation, release them in `on_installation_revoked(binding)` and make sure temporary files can be cleaned up.

See [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md) for the full specification.

## Testing the Parser

After creation, execute the command `lbp run` in the plugin directory to start debugging. Then in LangBot:

1. Go to the "Knowledge Base" page
2. Select a knowledge base and enter document management
3. When uploading a file, select your plugin's parser in the parser selector
4. After uploading, verify that the document is correctly ingested

---

# Component: Runner

Source: https://langbot.app/docs/en/plugin/dev/components/runner

Runner implements Agent execution or typed event handlers for a **Plugin processor**. Both styles receive `RunnerContext`. After installation, users select and configure the component in LangBot.

For environment setup, see the [plugin development tutorial](https://langbot.app/docs/en/plugin/dev/tutor.md).

See [Context APIs](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md#runner) for the complete `RunnerContext` fields and methods.

## Adding a Runner Component

A plugin can contain several event processors. Run `lbp comp Runner` in the plugin directory. Enter `welcome` as the name and `Welcome new members` as the description.

```bash
lbp comp Runner
```

The generated `components/runner/welcome.yaml` defines the component, and `welcome.py` contains its implementation.

## Custom execution

To integrate a model or implement an execution loop, declare `spec.usages: [agent]` and yield results from `run(ctx)`:

```python
from langbot_plugin.api.definition.components.runner import Runner, RunnerContext, RunnerResult
from langbot_plugin.api.entities.builtin.provider.message import Message


class Echo(Runner):
    async def run(self, ctx: RunnerContext):
        yield RunnerResult.run_completed(
            ctx.run_id,
            message=Message(role="assistant", content=ctx.input.to_text()),
        )
```

## Manifest File: Runner

Replace `welcome.yaml` with:

```yaml
apiVersion: langbot/v1
kind: Runner
metadata:
  name: welcome
  label:
    en_US: Welcome members
    zh_Hans: 欢迎新成员
    ja_JP: 新しいメンバーを歓迎
  description:
    en_US: Welcome new members and respond to /hello.
    zh_Hans: 欢迎新成员，并响应 /hello 消息。
    ja_JP: 新しいメンバーを歓迎し、/hello に返信します。
spec:
  usages: [event]
  events:
    - group.member_joined
    - message.received
  capabilities:
    tool_calling: true
  permissions:
    tools: [detail, call]
  config:
    - name: greeting
      type: string
      label:
        en_US: Greeting
        zh_Hans: 欢迎语
        ja_JP: 歓迎メッセージ
      required: true
      default: Welcome aboard!
    - name: reply_enabled
      type: boolean
      label:
        en_US: Send replies
        zh_Hans: 发送回复
        ja_JP: 返信する
      default: true
execution:
  python:
    path: ./welcome.py
    attr: Welcome
```

`spec.events` lists supported events, and `spec.config` defines settings users can edit on the processor detail page. This example handles new members and incoming messages, with a greeting and a reply switch. Sending replies requires the `tool_calling` and `permissions.tools` settings shown above.

`spec.usages` is required and has no default. `spec.usages` controls where the component can be selected: `agent` for Agents and Pipelines, `event` for Plugin processors. Both can be declared as `[agent, event]`. Event usage requires `spec.events`. The example uses typed handlers; a custom `run(ctx)` can also call `await super().run(ctx)` to dispatch them.

## Plugin Implementation

Register handlers in the `Welcome` class's `initialize` method. Replace `welcome.py` with:

```python
from langbot_plugin.api.definition.components.runner import (
    Runner,
    RunnerContext,
)
from langbot_plugin.api.entities.builtin.platform.events import (
    MemberJoinedEvent,
    MessageReceivedEvent,
)
from langbot_plugin.api.entities.builtin.platform.message import Plain


class Welcome(Runner):
    async def initialize(self):
        await super().initialize()

        @self.handler(MemberJoinedEvent)
        async def on_join(ctx: RunnerContext):
            name = ctx.platform_event.member.nickname or str(ctx.platform_event.member.id)
            await ctx.log(f"Member joined: {name}")
            if not ctx.config.get("reply_enabled", True):
                await ctx.log("Replies are disabled for this processor")
                return
            greeting = ctx.config.get("greeting", "Welcome aboard!")
            await ctx.reply(f"{name}, {greeting}")
            await ctx.log("Welcome action completed")

        @self.handler(MessageReceivedEvent)
        async def on_message(ctx: RunnerContext):
            text = "".join(
                item.text for item in ctx.platform_event.message_chain if isinstance(item, Plain)
            ).strip()
            if text != "/hello":
                await ctx.log("Message ignored: expected /hello")
                return
            if ctx.config.get("reply_enabled", True):
                await ctx.reply(ctx.config.get("greeting", "Welcome aboard!"))
            else:
                await ctx.log("Replies are disabled for this processor")
```

`on_join` welcomes new members, and `on_message` replies to `/hello`. With **Send replies** turned off, they only write logs.

`ctx.platform_event` contains the event data, and `ctx.config` contains this processor's settings. Use `ctx.reply()` to reply and `ctx.log()` to write logs. Processing finishes when the handlers return.

## Streaming Replies

Use `ctx.reply_stream()` to update one reply. `update(text)` takes the complete text so far:

```python
async with ctx.reply_stream() as reply:
    await reply.update("Working…")
    await reply.update("Done.")
```

The reply finishes when the `async with` block exits normally. If streaming is unsupported, disabled, or the event is not a message, the Host sends one complete message at the end. Exceptions discard buffered partial text. Debug runs simulate delivery.

## Registering Events

Register a handler with `@self.handler(EventClass)` and add the event identifier to `spec.events`. For example, `MemberJoinedEvent` corresponds to `group.member_joined`.

| Event                     | Manifest identifier       | SDK event class              |
| ------------------------- | ------------------------- | ---------------------------- |
| Message received          | `message.received`        | `MessageReceivedEvent`       |
| Message edited            | `message.edited`          | `MessageEditedEvent`         |
| Message deleted           | `message.deleted`         | `MessageDeletedEvent`        |
| Message reaction          | `message.reaction`        | `MessageReactionEvent`       |
| Feedback received         | `feedback.received`       | `FeedbackReceivedEvent`      |
| Member joined             | `group.member_joined`     | `MemberJoinedEvent`          |
| Member left               | `group.member_left`       | `MemberLeftEvent`            |
| Member muted              | `group.member_banned`     | `MemberBannedEvent`          |
| Group information updated | `group.info_updated`      | `GroupInfoUpdatedEvent`      |
| Friend request received   | `friend.request_received` | `FriendRequestReceivedEvent` |
| Friend added              | `friend.added`            | `FriendAddedEvent`           |
| Friend removed            | `friend.removed`          | `FriendRemovedEvent`         |
| Bot invited to group      | `bot.invited_to_group`    | `BotInvitedToGroupEvent`     |
| Bot removed from group    | `bot.removed_from_group`  | `BotRemovedFromGroupEvent`   |
| Bot muted                 | `bot.muted`               | `BotMutedEvent`              |
| Bot unmuted               | `bot.unmuted`             | `BotUnmutedEvent`            |
| Platform-specific event   | `platform.specific`       | `PlatformSpecificEvent`      |

See the SDK's [events.py](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/api/entities/builtin/platform/events.py) for available events and fields. Event support varies by platform.

## Testing the Event Processor

Configure the debug connection following the [plugin development tutorial](https://langbot.app/docs/en/plugin/dev/tutor.md), then run `lbp run` in the plugin directory. In LangBot:

1. Create a **Plugin processor**, select **Welcome members** on its detail page, configure it, and save.
2. Select **Member joined** on the left, enter the member nickname, member ID, and group ID, then click **Run test**.
3. Inspect the reply and logs. You can also select **Message received** and enter `/hello` to test replies.

Platform replies use Mock during debugging and send no real messages. Restart `lbp run` after editing component YAML.

After installing the plugin, add this configuration under **Plugin processor** on the bot detail page and save. You can also select a component, fill in its configuration, and create and bind a new configuration directly there. Declared events are delivered automatically; no per-event routes are needed.

Plugin subscriptions run independently of Agent/Pipeline routes. An event can trigger multiple processors, and one failure does not prevent the others from running. Bots using the same configuration share settings and runtime state; create separate configurations for different settings. Expose optional behavior, such as replies, through component configuration to avoid duplicate responses.

## One installation, many usages

A Workspace installs each plugin once, but that installation is reused by **several processors** (Agents and Pipelines). A Runner must keep their data apart on its own:

- `ctx.state.*` is already per-processor: scopes carry `binding_identity` (derived from the Agent UUID), so different processors of the same installation never overwrite each other.
- The platform storage key is `(instance, Workspace, owner type, plugin, key)` and carries **no processor dimension**; any key you write into Host storage or caches yourself must therefore also include the processor or conversation identity.
- `RunnerContext` (`ctx`) is valid only for a single run. Never keep it or its fields on the instance for reuse across calls; persist session state that must survive calls via `ctx.state_get()` / `ctx.state_set()`.
- Several processors share the same Runner instance, so never accumulate the current run's data on instance fields. If your runner must hold cross-call state in-process (for example a long-lived external session process), do not declare shared runtime — stay dedicated.
- If you keep per-installation process-local caches, release them in `on_installation_revoked(binding)`.

See [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md) for the full specification.

## Next Steps

- See the [`RunnerContext` API reference](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md#runner).
- See [LangBot API](https://langbot.app/docs/en/plugin/dev/apis/common.md) for models, tools, knowledge bases, and storage.
- See [Platform API](https://langbot.app/docs/en/plugin/dev/apis/platform.md) for messaging and other platform operations.
- Explore more examples in [RunnerDemo](https://github.com/langbot-app/langbot-plugin-demo/tree/main/Runner/RunnerDemo).
- To extend Pipeline steps such as preprocessing or completion of a model call, use [Event Listener](https://langbot.app/docs/en/plugin/dev/components/event-listener.md).

---

# Component: Tool

Source: https://langbot.app/docs/en/plugin/dev/components/tool

LangBot's built-in Local Agent calls tools to interact with the outside world during execution. Currently, adding tools is supported through both plugins and MCP.

## Adding Tool Components

A single plugin can contain any number of tools. Execute the command `lbp comp Tool` in the plugin directory and follow the prompts to enter the tool configuration.

```bash
➜  HelloPlugin > lbp comp Tool
Generating component Tool...
Tool name: get_weather_alerts
Tool description: Get weather alerts for a US state.
Component Tool generated successfully.
组件 Tool 生成成功。
```

This will generate `get_weather_alerts.yaml` and `get_weather_alerts.py` files in the `components/tools/` directory. The `.yaml` file defines the basic information for the tool, and the `.py` file is the tool handler:

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   └── tools
│       ├── __init__.py
│       ├── get_weather_alerts.py
│       └── get_weather_alerts.yaml
...
```

## Manifest File: Tool

```yaml
apiVersion: v1  # Do not modify
kind: Tool  # Do not modify
metadata:
  name: get_weather_alerts  # Tool name, for LLM recognition
  label:
    en_US: GetWeatherAlerts  # Tool display name, shown in LangBot UI, supports multilingual
    zh_Hans: GetWeatherAlerts
  description:
    en_US: 'Get weather alerts for a US state.'  # Tool description, shown in LangBot UI, supports multilingual. Optional
    zh_Hans: '获取美国某个州的天气预警'
spec:
  parameters: []  # Tool parameters, values generated by LLM based on conversation context
  llm_prompt: 'Get weather alerts for a US state.'  # Tool prompt, for LLM to determine whether to call this tool
execution:
  python:
    path: get_weather_alerts.py  # Tool handler, do not modify
    attr: GetWeatherAlerts  # Tool handler class name, matches the class name in get_weather_alerts.py
```

## Plugin Processing

The following code is generated by default (`components/tools/<tool_name>.py`). You need to implement the calling and return logic for this tool in the `call` method of the `GetWeatherAlerts` class.

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from typing import Any

from langbot_plugin.api.definition.components.tool.tool import Tool
from langbot_plugin.api.entities.builtin.provider import session as provider_session


class GetWeatherAlerts(Tool):

    async def call(self, params: dict[str, Any], session: provider_session.Session, query_id: int) -> str:
        """Fill your tool code here"""
        return {}
```

In the `call` method, implement this tool:

> info:
>
> The weather retrieval tool example comes from MCP's [Server Writing Example](https://modelcontextprotocol.io/quickstart/server).

```python
from __future__ import annotations

from typing import Any

from langbot_plugin.api.definition.components.tool.tool import Tool
from langbot_plugin.api.entities.builtin.provider import session as provider_session
import httpx

# Constants
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"


async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

class GetWeatherAlerts(Tool):

    async def call(self, params: dict[str, Any], session: provider_session.Session, query_id: int) -> str:
        """Fill your tool code here"""
        state = params.get("state", "CA")

        url = f"{NWS_API_BASE}/alerts/active/area/{state}"
        data = await make_nws_request(url)

        if not data or "features" not in data:
            return "Unable to fetch alerts or no alerts found."

        if not data["features"]:
            return "No active alerts for this state."

        alerts = [format_alert(feature) for feature in data["features"]]
        return "\n---\n".join(alerts)
```

In this tool, we need to get the `state` parameter from `params` and call the NWS API to get weather alerts for that state, so we need to define the `state` parameter in the `parameters` of the manifest file.

The `parameters` format follows [JSON Schema](https://json-schema.org/docs), is supported by [OpenAI Function Calling feature](https://platform.openai.com/docs/guides/function-calling#defining-functions), and its root type is fixed as `type: object`. Please add parameters in `properties` and add required parameter descriptions in `required`.

```yaml
...
spec:
  parameters:
    type: object  # Do not modify
    properties:  # Do not modify, add parameters here
      state:
        type: string
        description: 'Two-letter US state code (e.g. CA, NY)'
    required:  # Add required parameter descriptions here
      - state
...
```

This tool also uses the `httpx` library, so we need to add the `httpx` dependency in `requirements.txt` in the plugin directory.

```txt
# HelloPlugin/requirements.txt
langbot-plugin  # Already exists by default
httpx
```

Now execute the command `lbp run` in the plugin directory to start debugging. Configure a model that supports tool calling in LangBot and select to use that model on the corresponding pipeline to use this tool.

![](https://langbot.app/docs/images/zh/plugin/dev/components/tool_use_in_chat.png)

## One installation, many usages

A single Tool is called by **several processors and conversations** (one event can trigger several plugin processors):

- Read config per call (`self.get_plugin_config()` or `ctx.config`); never read it in `initialize()` and cache it on the instance.
- Never leave call arguments, results or conversation data on instance fields or module-level variables; take the conversation identity from the current call's `session` / `query_id`.
- Concurrent calls share the same instance, so instance fields get interleaved writes. Data that must survive calls belongs in Host storage, keyed with the corresponding processor or conversation identity.
- If you keep per-installation process-local caches, release them in `on_installation_revoked(binding)`.

See [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md) for the full specification.

## What's Next

You have learned the basic usage of tools. Next, you can:

- See how Tool receives [`session` and `query_id`](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md#tool).
- Check out [Plugin Common APIs](https://langbot.app/docs/en/plugin/dev/apis/common.md)

---

# Plugin Directory Structure

Source: https://langbot.app/docs/en/plugin/dev/directory-structure

This document introduces the standard directory structure and file organization specifications for LangBot plugins, helping developers create compliant plugins.

## Basic Directory Structure

A standard LangBot plugin should follow this directory structure:

```
MyPlugin/
├── manifest.yaml          # Plugin manifest file (required)
├── main.py               # Plugin main entry file (required)
├── README.md             # English plugin documentation (required)
├── readme/               # Multilingual README directory (optional)
│   ├── README_zh_Hans.md # Simplified Chinese documentation
│   ├── README_ja_JP.md   # Japanese documentation
│   └── README_zh_Hant.md # Traditional Chinese documentation (optional)
├── assets/               # Resource files directory
│   ├── icon.svg         # Plugin icon (recommended)
│   └── ...              # Other resource files
├── components/           # Components directory
│   ├── event_listener/  # Event listener components
│   ├── commands/        # Command components
│   └── tools/           # Tool components
├── requirements.txt      # Python dependencies (optional)
└── config/              # Configuration directory (optional)
```

## Multilingual README Specification

### File Location Specification

LangBot plugins support multilingual README documentation to provide localized plugin descriptions for users in different languages.

**Important Specifications:**

1. **`Root README.md (Required)`**
   - Must be written in **English**
   - Serves as the plugin's default documentation
   - Used as fallback when requested language version doesn't exist
2. **`readme/ Directory (Optional)`**
   - Used to store **non-English** README documents
   - File naming format: `README_{language_code}.md`

### Supported Language Codes

According to [RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646) standard, LangBot currently supports the following language codes:

| Language            | Language Code   | Filename            | Location                  |
| ------------------- | --------------- | ------------------- | ------------------------- |
| English             | `en` or `en_US` | `README.md`         | **Plugin root directory** |
| Simplified Chinese  | `zh_Hans`       | `README_zh_Hans.md` | `readme/` directory       |
| Traditional Chinese | `zh_Hant`       | `README_zh_Hant.md` | `readme/` directory       |
| Japanese            | `ja_JP`         | `README_ja_JP.md`   | `readme/` directory       |
| Vietnamese          | `vi_VN`         | `README_vi_VN.md`   | `readme/` directory       |
| Thai                | `th_TH`         | `README_th_TH.md`   | `readme/` directory       |
| Spanish             | `es_ES`         | `README_es_ES.md`   | `readme/` directory       |

### Example Directory Structure

```
MyPlugin/
├── README.md                    # ✅ English version (required, in root)
└── readme/                      # ✅ Multilingual directory
    ├── README_zh_Hans.md       # ✅ Simplified Chinese
    ├── README_ja_JP.md         # ✅ Japanese
    └── README_zh_Hant.md       # ✅ Traditional Chinese
```

### Incorrect Examples

❌ **Wrong: Placing English README in readme/ directory**

```
MyPlugin/
├── readme/
│   ├── README_en.md        # ❌ Wrong: English should not be in readme/
│   └── README_zh_Hans.md
```

❌ **Wrong: Root README.md contains non-English content**

```markdown
# MyPlugin

This is a plugin...

这是一个插件...    # ❌ Wrong: Root README.md should only contain English
```

### README Language Fallback Logic

When a user requests a README in a specific language, LangBot will search in the following order:

1. Try to read `readme/README_{language_code}.md`
2. If not found, fall back to root `README.md` (English version)

**Examples:**

- User requests Simplified Chinese (`zh_Hans`)
  - → Look for `readme/README_zh_Hans.md`
  - → If not found, return `README.md` (English version)
- User requests Japanese (`ja_JP`)
  - → Look for `readme/README_ja_JP.md`
  - → If not found, return `README.md` (English version)

## Resource Files Directory

### assets/ Directory

The `assets/` directory is used to store plugin static resource files.

**Recommended Structure:**

```
assets/
├── icon.svg              # Plugin icon (SVG format recommended)
├── example.png           # Example image
├── screenshot1.png       # Screenshot
└── logo.png             # Logo image
```

**Icon Specifications:**

- Recommended to use `icon.svg` as plugin icon
- Supported formats: `.svg`, `.png`, `.jpg`, `.jpeg`, `.gif`
- Recommended size: At least 256x256 pixels
- Reference in `manifest.yaml`: `icon: assets/icon.svg`

### Referencing Resources in README

In README documentation, you can use relative paths to reference images in the assets/ directory:

```markdown
# MyPlugin

![Example](./assets/example.png)

![Screenshot](./assets/screenshot1.png)
```

**Note:** After uploading plugins to LangBot Space, resource files will be automatically processed and hosted, and images will display correctly when users view the README.

## Components Directory

Plugin functionality is implemented through components, which should be organized by type in the `components/` directory:

```
components/
├── event_listener/       # Event listeners
│   ├── on_message.py
│   └── on_message.yaml
├── commands/            # Commands
│   ├── hello.py
│   └── hello.yaml
└── tools/               # Tools
    ├── search.py
    └── search.yaml
```

For detailed component development specifications, please refer to: [Adding Components](https://langbot.app/docs/en/plugin/dev/components/add.md)

## Configuration Files

### manifest.yaml

The plugin manifest file `manifest.yaml` is the core configuration file, containing plugin metadata, configuration items, component lists, and other information.

For detailed instructions, please refer to: [Complete Plugin Configuration Information](https://langbot.app/docs/en/plugin/dev/basic-info.md)

### requirements.txt

If the plugin requires additional Python dependencies, create a `requirements.txt` file in the root directory:

```
requests>=2.28.0
beautifulsoup4>=4.11.0
pillow>=9.0.0
```

**Note:** LangBot will automatically install dependencies listed in `requirements.txt` when installing the plugin.

## Related Documentation

- [Basic Tutorial](https://langbot.app/docs/en/plugin/dev/tutor.md) - Learn how to create your first plugin
- [Complete Plugin Configuration Information](https://langbot.app/docs/en/plugin/dev/basic-info.md) - Configure manifest.yaml
- [Adding Components](https://langbot.app/docs/en/plugin/dev/components/add.md) - Develop plugin components
- [Publish to Marketplace](https://langbot.app/docs/en/plugin/dev/publish/market.md) - Distribute your plugin

---

# Migration Guide

Source: https://langbot.app/docs/en/plugin/dev/migration

This tutorial highlights certain considerations. Please read the current version plugin tutorial first, then use this document as a reference for plugin migration.

## Migrating from 3.x Supported Asynchronous Plugins

> Plugin characteristics::
>
> - Main time period: 2024.2 \~ 2025.8
> - Registration method: Using `@handler` decorators to register event listeners and `@llm_func` decorators to register content functions (tools) in the plugin class in `main.py`; all handler functions are asynchronous functions (async def)

- Plugin and component registration method: Changed from the previous single plugin class decorator registration method to manifest file registration method. See [Manifest File](https://langbot.app/docs/en/plugin/dev/basic-info.md); and separated different types of components independently. For details, see [Adding Components](https://langbot.app/docs/en/plugin/dev/components/add.md).
- Message chain entities: Now refactored. The construction method of each message chain element now requires explicit passing of **named parameters**. See [Message Platform Entities](https://langbot.app/docs/en/plugin/dev/apis/messages.md).
- Event listeners: Provides backward compatibility, but no longer provides `query: Query` object in context. For details, see [Pipeline Events](https://langbot.app/docs/en/plugin/dev/apis/pipeline-events.md).
- Command components: Now refactored. See [Command Components](https://langbot.app/docs/en/plugin/dev/components/command.md).

## Migrating from 2.x and 3.x Supported Synchronous Plugins

> Plugin characteristics::
>
> - Main time period: 2023.1 \~ 2024.2
> - Registration method: Using `@on` decorators to register event listeners and `@func` decorators to register content functions (tools) in the plugin class in `main.py`; all handler functions are synchronous functions (def)

- Synchronous to asynchronous: Plugin runtime has now changed to fully asynchronous (based on asyncio). Please change all plugin code involving IO operations to asynchronous writing.
- For detailed content, please refer to the above 3.x asynchronous plugin migration guide.

---

# Distribute Plugins via GitHub

Source: https://langbot.app/docs/en/plugin/dev/publish/github

You can upload your plugin to GitHub, create a Release for the repository, and upload the `.lbpkg` file, allowing other users to install it in LangBot.

## Build Plugin

Execute the following command in the plugin directory:

```bash
lbp build
```

This will generate a `.lbpkg` file in the `dist` directory.

## Create Release

Upload your plugin to GitHub, then go to the Release page of your plugin repository, click to create a Release, and upload the `.lbpkg` file you just built.

![](https://langbot.app/docs/images/zh/plugin/dev/dist/github_release.png)

## Auto-create Release (GitHub Actions)

Plugins created by `lbp init` come with a built-in GitHub Actions workflow (`.github/workflows/release.yml`), so you don't have to build and upload manually.

After pushing your plugin repository to GitHub, whenever you bump the `version` field in `manifest.yaml` and push to the `main` or `master` branch, the workflow will automatically:

1. Install the `lbp` CLI and run `lbp build` to package the plugin;
2. Create a GitHub Release tagged `v<version>` and upload the generated `.lbpkg` file.

If a Release for that version already exists, the workflow skips it to avoid duplicate publishing. You can also trigger it manually from the repository's Actions page (`workflow_dispatch`).

> :
>
> The workflow relies on the repository's default `GITHUB_TOKEN` and requires the `contents: write` permission (already declared in the template). Make sure Actions is enabled for the repository, and that the `metadata.author`, `metadata.name`, and `metadata.version` fields in `manifest.yaml` are correct — the Release name and artifact filename are composed from these fields (`<author>-<name>-<version>.lbpkg`).

## Install Plugin

In LangBot's plugin management page, click the top-right corner to select the GitHub installation method.

---

# Publish to Plugin Marketplace

Source: https://langbot.app/docs/en/plugin/dev/publish/market

Publish plugins to [LangBot Plugin Marketplace](https://space.langbot.app/market) via CLI.

## Create Account on LangBot Space

LangBot Space is LangBot's centralized service platform. Please visit [LangBot Space](https://space.langbot.app), click the top-right corner to log in with GitHub and create an account.

![](https://langbot.app/docs/images/zh/plugin/dev/login_space.png)

This will redirect to GitHub authorization page, please complete authorization as prompted.

## Log in to LangBot Space Using CLI

### Option 1: Personal Access Token (Recommended)

1. Log in to [LangBot Space](https://space.langbot.app), click your avatar to open **Account Settings**, find **Personal Access Tokens** under the **Account** tab, and create a new token.
2. Copy the generated token (shown only once), then run:

```bash
➜  HelloPlugin > lbp login --token lbpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

==================================================
✅ Logged in with personal access token!
Token saved to: ~/.langbot/cli/config.json
==================================================
```

### Option 2: Device Code Verification

Execute command `lbp login` in any directory:

```bash
➜  HelloPlugin > lbp login
Starting LangBot CLI login process...
Generating device code...

==================================================
Please copy the user code and complete verification in your browser:
User Code: 6CD64D56
Verification URL: https://space.langbot.app/auth/device
Device code expires in: 120 seconds
==================================================

Waiting for verification...
```

Please click `Verification URL` to redirect to LangBot Space, enter `User Code` to complete login.

![](https://langbot.app/docs/images/zh/plugin/dev/space_device_flow.png)

```bash
==================================================
✅ Login successful!
Access token saved to: ~/.langbot/cli/config.json
Token type: Bearer
Expires in: 21600 seconds
==================================================
```

After successful login with either method, you can continue using CLI to upload plugins.

## Upload Plugin

Please execute `lbp publish` in your plugin directory:

```bash
➜  HelloPlugin > lbp publish
Building plugin to dist/tmp...
  - Skipping ignored directory: dist
  - Skipping ignored directory: __pycache__
  ...
Plugin built successfully: dist/tmp/RockChinQ-HelloPlugin-0.1.0.lbpkg
✅ Plugin published successfully. You can check it on https://https://space.langbot.app/market
```

You can now check your plugin submission task at [LangBot Plugin Marketplace](https://space.langbot.app/market). Please wait for approval, after which you can view your plugin in the marketplace.

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_submission.png)

Publishing does not involve certification: plugins run in dedicated mode by default. If this release should also be certified, see [Certified plugins and shared runtime](https://langbot.app/docs/en/plugin/certified-plugins.md).

If you have any questions, you can send an email to `hello@langbot.app` or contact us through [Community](https://langbot.app/docs/en/insight/community.md).

---

# Code Style Guide

Source: https://langbot.app/docs/en/plugin/dev/style

## Logging

In plugins, please use the `logging` module to record logs, do not use `print` statements (this will cause logs to not be output in the container environment).

```python
import logging

logger = logging.getLogger(__name__)  # Import logging module at the beginning of any Python file and define logger object

logger.info('This is an info message')  # Use logger.info to record info level logs
logger.warning('This is a warning message')
logger.error('This is an error message')
```

For Certified Plugins, raw process logs cannot be safely attributed to one Workspace and are operator-only. Runner code may use `RunnerContext.log()` for installation-scoped tenant-visible logs. Other component kinds do not yet have a generic tenant-visible logging API; their raw process logs are operator-only. Never emit tenant configuration, credentials or request data from module-global background work.

---

# Plugin Development Tutorial

Source: https://langbot.app/docs/en/plugin/dev/tutor

> info:
>
> To build a plugin for incoming messages, new group members, and other Bot events, complete the basic setup here and continue with the [Event Processor tutorial](https://langbot.app/docs/en/plugin/dev/components/runner.md).

## Architecture Foundation

In version 4.0, we introduced a high-security, high-flexibility production-grade plugin system and provided developers with rich APIs and easy-to-use supporting tools.

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_system_arch.png)

Plugin Runtime is used to manage plugin lifecycles and coordinate interactions between LangBot and plugins. It has two operating modes: `stdio` and `websocket`. When LangBot is started directly by users (not running in a container), it uses `stdio` mode, which is common for personal users or lightweight environments. When LangBot runs in a container, it uses `websocket` mode, designed specifically for production environments.

Plugin Runtime automatically starts each installed plugin and interacts through stdio. In plugin development scenarios, developers can use the `lbp` command-line tool to start plugins and connect to the running Runtime via WebSocket for debugging.

### Plugin Structure

A plugin's directory structure is similar to the following:

```bash
➜  HelloPlugin > tree
.
├── assets
│   └── icon.svg  # Plugin icon, displayed on the plugin marketplace page
├── components  # Plugin component directory, stores various component code and manifest files
│   ├── __init__.py
│   ├── commands
│   │   ├── __init__.py
│   │   ├── info.py
│   │   └── info.yaml
│   ├── event_listener
│   │   ├── __init__.py
│   │   ├── default.py
│   │   └── default.yaml
│   └── tools
│       ├── __init__.py
│       ├── get_weather_alerts.py
│       └── get_weather_alerts.yaml
├── main.py  # Plugin main program, listens to plugin lifecycle
├── manifest.yaml  # Plugin manifest file, describes plugin metadata
├── README.md  # Plugin documentation file, describes plugin functionality and usage, displayed on the plugin marketplace page
├── readme
│   └── README_zh_Hans.md  # Simplified Chinese documentation, for multi-language docs
├── requirements.txt  # Plugin dependencies file
└── .github
    └── workflows
        └── release.yml  # GitHub Actions workflow, automatically builds and publishes a Release when the version is bumped
```

The plugin class in main.py is common code for each plugin, initialized when the plugin starts and passed context information (configuration, etc.). You can implement initialization and shutdown logic for the plugin here. The plugin class inherits from `langbot_plugin.api.definition.plugin.BasePlugin` and provides [LangBot Global APIs](https://langbot.app/docs/en/plugin/dev/apis/common.md).

Each component is a core functional module of your plugin, which can be [added and removed](https://langbot.app/docs/en/plugin/dev/components/add.md) as needed. Different components are called in different situations, making it easy to extend plugin functionality later. Each component directly inherits from the various component base classes under the `langbot_plugin.api.definition.components` package and contains a `plugin: BasePlugin` object, allowing you to directly call the plugin's APIs.

> :
>
> - For detailed API documentation, please refer to [API Reference](https://langbot.app/docs/en/plugin/dev/apis/common.md).
>
> Please continue reading this tutorial to understand the plugin development process.

## AI-Assisted Development

- [skills-LangBotplugin](https://github.com/TyperBody/skills-LangBotplugin) - Skills contributed by community member [@TyperBody](https://github.com/TyperBody), use AI to quickly develop plugins, welcome to try
  - *langbotplugin* This skill provides automated plugin generation tools
  - *langbotplugindebug* This skill provides plugin debugging tools

## Installing CLI

Please ensure you have Python 3.10 or higher installed, and have installed the [uv package manager](https://docs.astral.sh/uv/).

Execute the command in any empty directory to install LangBot CLI and SDK:

```bash
pip install -U langbot_plugin
```

## Initializing Plugin Directory

Assuming your plugin name is `HelloPlugin`, create a directory `HelloPlugin` in any directory, enter that directory, and execute the command to initialize the plugin:

```bash
lbp init
```

Follow the prompts to enter `Author`, `Description`, and other information.

> :
>
> You can also use the `lbp init HelloPlugin` command to initialize the plugin in the subdirectory `HelloPlugin`.
>
> ![](https://langbot.app/docs/images/zh/plugin/dev/create_plugin.png)

This operation will generate the initial files for the plugin. You can now open the `HelloPlugin` directory in your favorite editor and start writing plugin code.

> :
>
> If you get a "command not found" error for `lbp`, it may be because you have not properly set the `PATH` environment variable.
> You can use `python -m langbot_plugin.cli.__init__` instead of the `lbp` command.
>
> For example:
>
> ```bash
> python -m langbot_plugin.cli.__init__ init HelloPlugin
> cd HelloPlugin
> ```

## Starting Debug Mode

You need to first deploy and start LangBot, ensuring that Plugin Runtime is running and listening on port `5401`.

> Runtime has two startup modes::
>
> - `Stdio` mode: When you start LangBot using source code without the startup parameter `--standalone-runtime`, LangBot will automatically start Plugin Runtime as a subprocess and communicate with Plugin Runtime through `stdio` (standard input/output streams). In this case, Runtime will load plugins from the `data/plugins` directory in the LangBot root directory and listen on port `5401` of the LangBot host as a debug port.
>
> - `WebSocket` mode:
>   - Production environment: When you start LangBot using the official `docker-compose.yaml`, Plugin Runtime will run in a separate container, and LangBot will communicate with Plugin Runtime in WebSocket mode due to the startup parameter `--standalone-runtime`. The 5401 port of the Runtime container will be mapped to the 5401 port of the host as default.
>   - Development environment: If you start LangBot through source code with the startup parameter `--standalone-runtime`, LangBot will connect to the already started Plugin Runtime according to the `plugin.runtime_ws_url` address (port usually 5400) configured in `data/config.yaml`. You need to start the standalone Plugin Runtime yourself, see [Developing Plugin Runtime](https://langbot.app/docs/en/develop/plugin-runtime.md).
>
> Whether in `stdio` or `websocket` mode, Plugin Runtime will listen on port `5401` of its host as a debug port for plugin debugging connections.
>
> When developing plugins, we recommend starting LangBot according to the [Development Configuration](https://langbot.app/docs/en/develop/dev-config.md) method, which will start Plugin Runtime in Stdio mode, making plugin development easier.

Copy `.env.example` to `.env`. In LangBot WebUI, open **Extensions → Debug Info** and copy the current Workspace's Debug URL and Debug Key into `DEBUG_RUNTIME_WS_URL` and `PLUGIN_DEBUG_KEY`. Every Workspace has a different key, and it rotates every two hours; copy it again after expiry.

```bash
cp .env.example .env
```

Start plugin debugging, and you will see the plugin output:

```bash
lbp run
```

![](https://langbot.app/docs/images/zh/plugin/dev/launch_debug_plugin.png)

And you can see this plugin has been loaded in LangBot's WebUI.

![](https://langbot.app/docs/images/zh/plugin/dev/debug_plugin_loaded.png)

## What's Next

This tutorial will guide you through step-by-step completion of plugin functionality.

- Modify Plugin Information: The plugin has been created with basic plugin information. Please [complete the plugin information](https://langbot.app/docs/en/plugin/dev/basic-info.md).
- Add Components: Plugin components are the core functional units of plugins. You can [add components](https://langbot.app/docs/en/plugin/dev/components/add.md) based on your needs.

---

# LangBot Plugins

Source: https://langbot.app/docs/en/plugin/plugin-intro

LangBot is composed of various internal components such as Large Language Model tools, commands, messaging platform adapters, LLM requesters, and more. To meet extensibility and flexibility requirements, we have implemented a production-grade plugin system.

Plugins are managed uniformly by the Plugin Runtime. Most plugins use a dedicated runtime; a release with a valid artifact-bound certificate may qualify for [cross-tenant shared execution](https://langbot.app/docs/en/plugin/certified-plugins.md) in LangBot Cloud. Review alone is not certification.

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_system_arch.png)

## Plugin Structure

Plugins can provide the following components based on their specific functionality:

- Event Handlers: Listen to events during pipeline execution and modify context or pipelines.
- Commands: Triggered by user command messages starting with `!` (or other configured prefixes).
- Tools: Called by LLMs during execution of LangBot's built-in Local Agent.
- Knowledge Engines: Manage document indexing and retrieval for knowledge bases.

More component types will be supported for plugin implementation in the future.

## Installing Plugins

Currently supports uploading plugin packages and installing plugins from the plugin marketplace.
In LangBot's plugin management page, click the top-right corner to choose the installation method.

![](https://langbot.app/docs/images/zh/plugin/install_method.png)

Click `Upload Local`, select `.lbpkg` files shared by others or downloaded from the Marketplace to install plugins.

Or click the Plugin Marketplace tab, select a plugin, and click install.

![](https://langbot.app/docs/images/zh/plugin/install_from_marketplace.png)

After installing plugins, you need to select the plugin in your pipeline configuration page.

![](https://langbot.app/docs/images/zh/plugin/pipeline_extensions.png)

## Plugin Management

### Plugin Configuration

Some plugins may require you to fill in specific configuration items (please refer to the plugin README instructions). Click on the plugin card to enter the plugin details page and obtain and input the required information as prompted.

![](https://langbot.app/docs/images/zh/plugin/plugin_config.png)

### Updating Plugins

Only plugins installed from the plugin marketplace can be updated.

![](https://langbot.app/docs/images/zh/plugin/update_plugin.png)

## Plugin Marketplace

The plugin marketplace can be accessed from LangBot's internal `Plugin Management` page, or you can visit the standalone site [LangBot Plugin Marketplace](https://space.langbot.app/market).

---

# Service API Overview

Source: https://langbot.app/docs/en/tags/readme

LangBot provides a set of RESTful APIs for external services to integrate and automate management. These APIs are authenticated with API keys, which are a subset of the HTTP API.

> warning:
>
> Service API is currently in Beta and some APIs may change frequently.

## Get API Key

Click the `API Keys` button in the sidebar of the WebUI to create an API Key.

![create\_api\_key](https://langbot.app/docs/images/zh/api/create_api_key.png)

After creation, copy the API Key and save it.

![copy\_api\_key](https://langbot.app/docs/images/zh/api/copy_api_key.png)

## Authentication

All Service APIs support two authentication methods:

- **API Key**: Via `X-API-Key: <your-key>` or `Authorization: Bearer <your-key>` header
- **User Token**: Via `Authorization: Bearer <user-token>` header (obtained after login)

## Use API

The left sidebar lists all available APIs. You can fill in your instance address (the port address exposed by the backend, default is `http://localhost:5300`) and API Key, then click the `Try it out` button to call the API.

## Core Concepts

### Provider + Model Architecture

LangBot uses a **Provider + Model** two-layer architecture for AI model management:

- **Provider**: Defines the API endpoint (`base_url`), requester type, and API keys. A single provider can be associated with multiple models.
- **Model**: Associated with a provider (via `provider_uuid`), defining the specific model name and parameters. Models inherit the provider's API endpoint and keys.

```
Provider (OpenAI)
├── base_url: https://api.openai.com/v1
├── api_keys: [sk-xxx]
├── LLM: gpt-4o
├── LLM: gpt-4o-mini
└── Embedding: text-embedding-3-small
```

This architecture allows you to manage multiple models under a single provider, sharing API configuration and avoiding redundant key entries.

### Requester

A requester defines the communication protocol with AI services. Use `GET /api/v1/provider/requesters` to list available requesters. Common requesters include:

- `openai-chat-completions` — OpenAI-compatible chat completions API (also works with SiliconFlow, DeepSeek, etc.)
- `anthropic-messages` — Anthropic Claude API
- `openai-embeddings` — OpenAI-compatible embeddings API

### Async Tasks

Some operations (plugin install/delete/upgrade) run asynchronously and return a `task_id`. You can track progress in the WebUI.

---

# Webhooks

Source: https://langbot.app/docs/en/tags/webhook

Webhooks allow you to send bot message events to external services for processing.

## Configure Webhooks

1. In LangBot WebUI, click "API Integration" in the sidebar
2. Switch to the "Webhooks" tab
3. Click "+" to create a new webhook
4. Fill in:
   - **Name**: Webhook identifier
   - **URL**: Target URL to receive events
   - **Description**: Optional
   - **Status**: Enable or disable

## Event Format

### Person Message (bot.person\_message)

```json
{
  "uuid": "event-unique-id",
  "event_type": "bot.person_message",
  "data": {
    "bot_uuid": "bot-uuid",
    "adapter_name": "AdapterName",
    "sender": {
      "id": "user-id",
      "name": "User Name"
    },
    "message": [
      {
        "type": "Plain",
        "text": "Message content"
      }
    ],
    "timestamp": 1234567890
  }
}
```

### Group Message (bot.group\_message)

```json
{
  "uuid": "event-unique-id",
  "event_type": "bot.group_message",
  "data": {
    "bot_uuid": "bot-uuid",
    "adapter_name": "AdapterName",
    "group": {
      "id": "group-id",
      "name": "Group Name"
    },
    "sender": {
      "id": "user-id",
      "name": "User Name"
    },
    "message": [
      {
        "type": "Plain",
        "text": "Message content"
      }
    ],
    "timestamp": 1234567890
  }
}
```

## Response Format

Webhook services should return JSON:

```json
{
  "status": "ok",
  "skip_pipeline": false
}
```

### Parameters

- **status**: Processing status (recommend "ok")
- **skip\_pipeline**: Whether to skip LangBot pipeline processing
  - `true`: Message won't continue in pipeline
  - `false`: Message proceeds normally

> idea:
>
> `skip_pipeline` lets you completely take over message processing. When `true`, the message is only handled by your webhook service and won't trigger LangBot's AI features.

## Integration Example

### Dify Workflow

Use the [dify-plugin-langbot-trigger](https://github.com/langbot-app/dify-plugin-langbot-trigger) plugin to receive LangBot webhook events and create workflows in Dify.

## Notes

- Webhook URL must be accessible
- Request timeout: 15 seconds
- Failed requests don't affect normal processing
- Multiple webhooks execute in parallel
- Any webhook returning `skip_pipeline: true` skips pipeline processing

---

# Knowledge Base

Source: https://langbot.app/docs/en/usage/knowledge/readme

Build RAG knowledge bases in LangBot. Give your AI bot document retrieval and grounded answers across messaging platforms.

LangBot natively supports RAG (Retrieval-Augmented Generation). You can create a knowledge base and bind it to a pipeline, allowing the pipeline to answer questions based on the contents of the knowledge base.

Knowledge bases are powered by Knowledge Engine plugins, with different Knowledge Engines providing different indexing and retrieval strategies. You can find available Knowledge Engine plugins in the [Plugin Marketplace](https://space.langbot.app/market).

## Creating a Knowledge Base

On the knowledge base page, click the `Create Knowledge Base` button:

1. Fill in the knowledge base name
2. Select a Knowledge Engine (provided by installed plugins)
3. Fill in the relevant parameters based on the selected engine's configuration form (e.g., embedding model, chunk size, etc.)
4. Click the `Create` button

> info:
>
> Different Knowledge Engines have different configuration parameters, depending on the engine's `creation_schema` definition. Some engines may require configuring an embedding model first. Please read [Configure Models](https://langbot.app/docs/en/usage/models/readme.md).

If the selected Knowledge Engine supports document upload (declares `DOC_INGESTION` capability), after creation go to the "Documents" tab of your knowledge base and upload documents. LangBot will automatically parse and index these in the background.

## Using the Knowledge Base

Go to your pipeline configuration, under the "AI" tab, choose `Local Agent` as the runner, then select the knowledge base you just created.

![use\_kb](https://langbot.app/docs/images/zh/deploy/knowledge/use_local_agent.png)

![use\_kb](https://langbot.app/docs/images/zh/deploy/knowledge/use_kb.png)

### Configure Reranking (Optional)

After selecting a knowledge base, you can configure a **Rerank Model** below to improve retrieval quality:

- **Rerank Model**: Select a configured rerank model (if none available, add one in [Model Configuration](https://langbot.app/docs/en/usage/models/readme.md) first)
- **Rerank Top-K**: Number of most relevant results to keep after reranking, default is 5

> idea:
>
> Rerank models are optional. When configured, candidate documents from knowledge base retrieval are re-scored by the rerank model, keeping only the top-K most relevant results before passing them to the LLM, significantly reducing noise from irrelevant content.

> info:
>
> LangBot's built-in knowledge base can be used only when the runner is set to `Local Agent`. For other runners, refer to their documentation.

Now you can use the knowledge base in `Chat Debug`, or through the bot linked to this pipeline:

![use\_kb\_in\_chat](https://langbot.app/docs/images/zh/deploy/knowledge/use_kb_in_chat.png)

## Developing Custom Knowledge Engines

If existing Knowledge engine plugins don't meet your needs, you can develop your own Knowledge engine plugin. See [Component: Knowledge Engine](https://langbot.app/docs/en/plugin/dev/components/knowledge-engine.md) for development details.

---

# MCP Server

Source: https://langbot.app/docs/en/usage/mcp/readme

Connect MCP (Model Context Protocol) servers to LangBot to extend your AI bot with external tools and data sources.

LangBot can call tools from MCP servers. Once an MCP server is added, the built-in Agent — with tool use enabled on its model — can invoke those tools during a conversation.

> MCP supports two modes: local (stdio) and remote.:
>
> Install from [LangBot Space](https://space.langbot.app) for the smoothest setup — listed MCPs are pre-configured and ready to use.
>
> You can also fetch from [ModelScope](https://modelscope.cn/mcp), [mcp.so](https://mcp.so), or [composio.dev](https://composio.dev/toolkits), then add them manually as shown below.

## Two Transport Modes

| Mode                            | When to use                             | Notes                                                                                                                                                   |
| ------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Remote (`mode: "remote"`)       | Remote MCP service — just paste the URL | LangBot connects to the remote URL directly and auto-detects the transport (tries Streamable HTTP first, falls back to SSE) — no need to choose by hand |
| Local / stdio (`mode: "stdio"`) | MCP server launched by a local command  | Only available when Box Runtime is up                                                                                                                   |

> info:
>
> Earlier versions split the remote mode into separate `http` (Streamable HTTP) and `sse` options; these are now unified into a single `remote` mode, with the transport auto-detected by the backend. Existing `http` / `sse` rows in the database are normalized to `remote` on upgrade, and their connection args (URL, headers, timeout) are preserved unchanged.

> info:
>
> MCP tools require the pipeline to use the **built-in Agent**, with a model that has **tool use enabled** — see [Models](https://langbot.app/docs/en/usage/models/readme.md). External runners (Dify, n8n, Langflow, Coze, etc.) use their own tool mechanisms.

## Installing an MCP Server

### From LangBot Space (Preferred)

[LangBot Space](https://space.langbot.app) is the official LangBot marketplace, with a curated list of ready-to-use MCP servers. In the WebUI, browse and install them with one click under `Plugin Management` → `MCP Management` — URL, command, and mode are filled in by the listing, so nothing has to be configured by hand.

This covers most cases. For services that aren't listed, use the manual flow below.

### Adding Manually

Open `Plugin Management` → `MCP Management`:

![MCP management page](https://langbot.app/docs/images/zh/deploy/mcp/mcp02.png)

Click `Add` in the top right, choose `Add MCP Server`, pick **Local (stdio)** or **Remote** mode: for remote just paste the URL, for local fill in the launch command. Click `Test` to verify connectivity, then `Submit`:

![create new MCP server](https://langbot.app/docs/images/zh/deploy/mcp/mcp03.png)

After saving, toggle the switch on the card to connect. Click the card to see details:

![MCP server detail](https://langbot.app/docs/images/zh/deploy/mcp/mcp05.png)

## Enabling in a Pipeline

Once an MCP server is added, the pipeline extension config decides which servers the Agent can see:

- Enable "all MCP servers", or
- Bind only specific MCP servers

Tools from unbound servers won't appear in that pipeline's tool list.

## Advanced: stdio MCP

stdio MCP is hosted by Box Runtime. Before the connection is ready, LangBot:

1. Creates or reuses a shared MCP Box session
2. If a local project path can be inferred from the command, stages the project into the workspace
3. Installs dependencies if the project has `requirements.txt`, `pyproject.toml`, `setup.py`, or `setup.cfg`
4. Connects the MCP process's stdin/stdout through a WebSocket relay

To fine-tune mount, network, or timeout behavior, add a `box` override under the MCP `extra_args`:

```json
{
  "mode": "stdio",
  "extra_args": {
    "command": "python",
    "args": ["server.py"],
    "env": {},
    "box": {
      "host_path": "/path/to/mcp-project",
      "network": "on",
      "host_path_mode": "ro",
      "startup_timeout_sec": 120,
      "image": "python:3.11-slim"
    }
  }
}
```

Common fields:

| Field                 | Notes                                                                                               |
| --------------------- | --------------------------------------------------------------------------------------------------- |
| `host_path`           | MCP project directory on the host. Must be within `box.local.allowed_mount_roots`                   |
| `network`             | Whether network is allowed (typically for dependency install)                                       |
| `host_path_mode`      | Access mode when staging `host_path`; defaults to `ro`. stdio MCP usually stages into the workspace |
| `startup_timeout_sec` | Box prep + dependency install timeout, default 120s. Connection wait gets about 30s extra           |
| `image`               | Runtime image when the Docker backend is used                                                       |
| `memory_mb`           | Per-server memory cap (MB); overrides global `box.default_memory_mb` for this server                |

> warning:
>
> stdio MCP runs inside Box. Dependency install and process startup are subject to the sandbox profile, network permission, resource limits, and the mount allowlist.

## Common Issues

| Symptom                     | What to check                                                                          |
| --------------------------- | -------------------------------------------------------------------------------------- |
| MCP connection fails        | URL, command, arguments, env vars are correct                                          |
| stdio MCP stuck connecting  | Box Runtime status; `startup_timeout_sec` may be too short                             |
| Dependency install fails    | Sandbox network permission; dependency files are correct                               |
| Local files inaccessible    | `host_path` exists; it's inside `allowed_mount_roots`                                  |
| Agent doesn't see MCP tools | Pipeline uses built-in Agent; model has tool use enabled; MCP is bound on the pipeline |

---

# Models

Source: https://langbot.app/docs/en/usage/models/readme

Configure LLM providers in LangBot: OpenAI GPT, Anthropic Claude, Google Gemini, DeepSeek, Qwen, Ollama and OpenAI-compatible models.

## LangBot Models

LangBot Models is an official model service provided by LangBot. When you initialize a local instance with your LangBot Space account, available models will be automatically added to your instance without any configuration. You will receive a certain amount of free quota to get started quickly.

![langbot\_models](https://langbot.app/docs/images/zh/deploy/models/langbot_models.png)

For specific available models, please check [LangBot Space](https://space.langbot.app/models).

## Custom Models

You can also add models from other sources.

### LLM Model

Models will be used by pipelines to process messages. The first model you configure will be set as the model for the default pipeline.

![arch](https://langbot.app/docs/images/zh/deploy/models/arch.png)

You can add multiple models, and then select which model to use in the pipeline.

![model\_config](https://langbot.app/docs/images/zh/deploy/models/model_config.png)

Enter these four parameters: `Model Name`, `Model Provider`, `Request URL`, and `API Key`, then submit.

For model capabilities, enable the ones the underlying model actually supports:

- **Vision**: enable to recognize images
- **Tool Use** (function calling / tool use): enable so the LLM can call tools during a conversation

> info:
>
> **Tool Use must be enabled on the model whenever you want to use tools from MCP servers, sandbox built-ins (`exec`/`read`/`write`/`edit`/`glob`/`grep`), or Skills.** Without it, even if the pipeline binds those extensions, the Agent won't call any tools.
>
> The underlying model has to actually support function calling for this checkbox to take effect — check the model provider's docs if unsure.

### Embedding Model

Embedding models are used to compute vector representations of messages. If you need to use knowledge bases, please configure this model.

![embedding\_model](https://langbot.app/docs/images/zh/deploy/models/embedding_model.png)

Enter these four parameters: `Model Name`, `Model Provider`, `Request URL`, and `API Key`, then submit. After that, please configure the knowledge base to use this model.

### Using the seekdb Built-in Embedding Model (Optional Dependency Required)

The model needs no request parameters. Use `uv sync --extra seekdb` for source deployments or `uvx --from 'langbot[seekdb]@latest' langbot` for package deployments. The official Docker/Kubernetes image already includes the SeekDB dependency. Native deployment support depends on the available `pylibseekdb` wheel.

- On the "Embedding Model" page, select "seekdb-built-in";
- Click "Save" to use it immediately;
- Then select this model in your knowledge base to take effect.

### Using Chroma Built-in Embedding Model (Zero Configuration)

The system has integrated Chroma's built-in embedding model (all-MiniLM-L6-v2), no parameters required.

- On the "Embedding Model" page, select "chroma-built-in";
- Click "Save" to use it immediately;
- Then select this model in your knowledge base to take effect.

### Rerank Model

Rerank models re-score RAG retrieval results to significantly improve the precision of knowledge base answers. When a knowledge base returns multiple candidate documents, the rerank model uses a cross-encoder to precisely score each document's relevance to the query, selecting only the most relevant content.

Enter `Model Name` and select `Model Provider`, then submit. After that, select this model in your pipeline's "AI" configuration.

> idea:
>
> Rerank models are optional. Without one, knowledge base results are used in their original retrieval order. With a rerank model configured, results are re-scored and only the top-K most relevant results are kept.

---

# Integrating Coze API

Source: https://langbot.app/docs/en/usage/pipelines/coze

Integrate Coze with LangBot. Connect your Coze bots and agents to Discord, Telegram, WeChat and other messaging platforms.

This document explains how to obtain the Token and Bot ID from the Coze platform and enter them into the LangBot pipeline configuration.

## 1. Obtaining the Token and Bot ID

1. Log in to the Coze platform and enter your developer console.
   ![Coze Application API Key](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze07.png)

2. In "API Management", create and copy the token.
   ![Coze Application API Key](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze06.png)

> info:
>
> In Coze authorization, coze.cn supports long-term authorization through "Service Identities and Credentials", while coze.com only provides Personal Access Tokens.

3. Select your own agent (or create a new one) from the project development section. The obtained ID is the `bot_id`.
   ![Coze bot\_id](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze05.png)

- Make sure to select the API option when publishing the agent
  ![Coze Application API Key](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze04.png)

Please securely store the following two pieces of information:

- **token**: The token generated by the Coze platform
- **bot\_id**: The Bot ID

## 2. Entering the Configuration in LangBot

1. Open the LangBot WebUI and navigate to the configuration page of a pipeline (or create a new pipeline and enter its configuration page)

2. Under "AI Capabilities", select the runner as `Coze API`

3. In the runner's configuration items, enter:

   - **token**: Paste the API Token you copied from the Coze platform
   - **bot\_id**: Paste the corresponding Bot ID
   - Please select the `API Base URL` according to the Coze site you are using: coze.cn please fill in `https://api.coze.cn`; coze.com please fill in `https://api.coze.com`

   ![Pipeline Configuration](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze08.png)

4. Click "Save" to complete the configuration

Once completed, you can invoke the Coze agent within this pipeline for dialogue processing

## Frequently Asked Questions (FAQ)

- **Save fails or invocation returns an error**: Please verify that the token and bot\_id are correct and do not contain extra spaces
- **Unable to select `Coze API`**: Please confirm whether the current version supports this runner. If not yet supported, please upgrade to a version that includes the Coze runner

For more general pipeline configuration instructions, please refer to [Modifying Dialogue Pipeline Configuration](https://langbot.app/docs/en/usage/pipelines/readme.md)

---

# Using DeerFlow with LangBot

Source: https://langbot.app/docs/en/usage/pipelines/deerflow

Use DeerFlow with LangBot to power your AI bot's conversation pipeline across messaging platforms.

[DeerFlow](https://github.com/bytedance/deer-flow) is an open-source AI Agent framework based on Large Language Models (LLMs), developed by ByteDance. It focuses on deep research, information retrieval, and multi-agent collaborative orchestration.\
The framework is built on LangGraph with a configurable workflow engine, supporting advanced features such as planning mode, sub-agent concurrency, and chain-of-thought reasoning. It is suitable for scenarios that require deep information gathering and structured analysis.

Current integration targets DeerFlow **2.0 `main` branch**. The DeerFlow official team has migrated the original Deep Research framework to the `main-1.x` branch for ongoing maintenance. Therefore, if you are using version 2.0, please refer to the official documentation and backend API of the `main` branch.

LangBot currently supports DeerFlow as an `AI Capabilities` runner, bringing deep research and agent orchestration capabilities to your conversation pipelines.

## Deploying DeerFlow

Please follow the [DeerFlow Official Documentation](https://github.com/bytedance/deer-flow) to install, configure, and start the service:

- [DeerFlow GitHub Repository](https://github.com/bytedance/deer-flow)
- [DeerFlow Website](https://deerflow.tech/)
- [DeerFlow Configuration Documentation](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md)

After deployment, please confirm that DeerFlow has started normally and note its gateway address. By default, the DeerFlow gateway address is `http://127.0.0.1:2026`.

> Network Configuration Tips:
>
> - The `API Base URL` must start with `http://` or `https://`.
> - If LangBot and DeerFlow are deployed on the same host and both use Docker deployment, you can refer to the article: [Network Configuration Details](https://langbot.app/docs/en/workshop/network-details.md#langbot-and-message-platform-both-running-in-docker-containers). Please add the DeerFlow container to `langbot-network` when starting, and set the `API Base URL` in LangBot configuration to the container interconnection address, for example `http://deerflow-app:2026`.
> - If deployed on different hosts or containers, please replace `127.0.0.1` with the actual accessible intranet address, hostname, or domain of DeerFlow.

## Configuring LangBot

Open the LangBot WebUI page, add a new pipeline or switch to the `AI Capabilities` configuration page in an existing pipeline.

![deerflow](https://langbot.app/docs/images/zh/deploy/pipelines/deerflow/creat_langbot_pipeline.png)

1. Select `DeerFlow API` in `Runner`.
2. In the runner configuration items, fill in:
   - `API Base URL`: The API gateway address of the DeerFlow service, default `http://127.0.0.1:2026`.
   - `API Key`: Optional. If your DeerFlow gateway uses Bearer Token authentication, you can enter the API Key here.
   - `Assistant ID`: Corresponds to DeerFlow 2.0 LangGraph's `assistant_id`, default `lead_agent`.
   - `Model Name Override`: Optional. Used to override the default model configured on the DeerFlow side. If DeerFlow has a model configured, this can be left empty.
   - `Enable Thinking Mode`: When enabled, DeerFlow will return chain-of-thought content, which can be used to display the reasoning process.
   - `Enable Planning Mode`: Corresponds to DeerFlow 2.0 runtime parameter `config.configurable.is_plan_mode`. When enabled, the Agent will formulate a research plan before execution.
   - `Enable Sub-Agents`: Corresponds to DeerFlow 2.0 runtime parameter `config.configurable.subagent_enabled`. When enabled, allows the Agent to dispatch sub-agents to complete tasks in parallel.
   - `Max Concurrent Sub-Agents`: Corresponds to DeerFlow 2.0 runtime parameter `config.configurable.max_concurrent_subagents`, only effective when sub-agents are enabled, default `3`.
   - `Recursion Limit`: Corresponds to LangGraph's `recursion_limit`, controls the maximum recursion depth of the workflow, default `1000`.
3. Click `Save` to complete the configuration.

> Configuration Suggestions:
>
> - It is only recommended to enable `Planning Mode` or `Sub-Agent` related options if the corresponding capabilities have been enabled on the DeerFlow side, otherwise the expected effects may not be achieved.
> - LangBot will send both the `config.configurable` runtime parameters recommended by DeerFlow 2.0 and retain backward-compatible legacy fields for easier integration with upstream recent versions.

After completion, you can use DeerFlow in the pipeline to complete deep research and intelligent Q\&A.

## Frequently Asked Questions

- **Save failed or invocation error**: Please verify that the `API Key` and `API Base URL` are correct, and ensure the DeerFlow service has started normally.
- **No expected content returned**: Please verify that the `Assistant ID` matches the actual available assistant in DeerFlow.
- **Cannot select `DeerFlow API`**: Please verify that your current LangBot version supports this runner; if not supported, please upgrade to a version that includes the DeerFlow runner.
- **Meaning of DeerFlow configuration items**: Please refer to the DeerFlow official documentation regarding runtime parameters and capabilities, or consult the DeerFlow community for recommended configurations.

For more pipeline general configuration instructions, please refer to [Modifying Conversation Pipeline Configuration](https://langbot.app/docs/en/usage/pipelines/readme.md).

---

# Using Dify with LangBot

Source: https://langbot.app/docs/en/usage/pipelines/dify

Connect Dify to LangBot. Deploy your Dify apps and agents as AI bots on Discord, Telegram, WeChat, Slack and more.

[Dify](https://dify.ai) is an open-source large language model (LLM) application development platform. It combines the concepts of Backend as Service and LLMOps, enabling developers to quickly build production-grade generative AI applications.\
Dify can create chat assistants (including Chatflow), Agents, text generation applications, workflows, and other types of applications.

LangBot currently supports three types of Dify applications: `Chat Assistant` (including Chatflow), `Agent`, and `Workflow`.

## Creating an Application in Dify

Please follow the [Dify documentation](https://docs.dify.ai) to deploy Dify and create your application.

After publishing your application, go to the `Access API` page of your application to generate an API key.

![Dify Application API Key](https://langbot.app/docs/images/zh/deploy/pipelines/dify/dify_sv_api_01.png)

Save the API server and API key for configuring LangBot's pipeline `AI Capability`.

> The above is an example for Dify cloud service version. If you are using the self-hosted community version, please use your own Dify service address as the \`base-url\` in LangBot, and add \`/v1\` as the path.:
>
> - If LangBot and Dify are deployed on the same host and both are deployed using Docker, you can refer to the article: [Network Configuration Details](https://langbot.app/docs/zh/workshop/network-details.md#langbot-%E5%92%8C%E6%B6%88%E6%81%AF%E5%B9%B3%E5%8F%B0%E5%9D%87%E8%BF%90%E8%A1%8C%E5%9C%A8-docker-%E5%AE%B9%E5%99%A8%E4%B8%AD). In this case, add `langbot-network` to the `networks` of all containers in the docker-compose.yaml file that starts Dify, add the container name `dify-nginx` to the `nginx` container, and finally set `base-url` to `http://dify-nginx/v1` in the LangBot configuration.
> - For other cases, please consult your company's operations team.

## Configuring LangBot

Open the LangBot WebUI page, add a new pipeline or switch to the AI capability configuration page in an existing pipeline.

![Setting Development Item](https://langbot.app/docs/images/zh/deploy/pipelines/dify/dify_sv_api_02.png)

> \### Workflow Output Key:
>
> If you are using a Dify workflow application, please use `summary` as the key to pass the output content.
>
> ![Dify Workflow Application Output Key](https://langbot.app/docs/images/zh/deploy/pipelines/dify/dify_workflow_output_key.png)
>
> ## Output Processing
>
> When using a workflow application or Agent application, if you enable `track-function-calls` in LangBot's pipeline `Output Processing`, a message of `calling function xxx` will be output to the user when Dify executes each tool call.\
> However, if you are using `ChatFlow` under the `chat` application (Chat Assistant -> Workflow Orchestration), it will only output the text returned by the Answer (direct reply) node regardless of the settings.

---

# Using Langflow with LangBot

Source: https://langbot.app/docs/en/usage/pipelines/langflow

Use Langflow with LangBot. Bring your Langflow flows to Discord, Telegram, WeChat and other IM platforms as AI bots.

[Langflow](https://langflow.com/) is an open-source project for building and deploying AI-based Agents and Workflows. It supports local and cloud deployment, and provides APIs for other applications to integrate.

LangBot currently supports using Langflow as the runner.

## Creating a Workflow in Langflow

Please follow the [Langflow documentation](https://langflow.com/docs/introduction) to deploy Langflow instance.

As an example of the default template's Simple Agent:

![create\_flow](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/create_flow.png)

You can modify the workflow according to your needs:

![edit\_flow](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/edit_flow.png)

## Configuring LangBot

Open the LangBot WebUI page, add a new pipeline or switch to the AI capability configuration page in an existing pipeline, and select `Langflow API` as the runner.

![set\_langflow\_runner](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/set_langflow_runner.png)

Fill in the other settings according to the prompts, including `Base URL` (fill in according to actual network conditions), `API Key`, `Flow ID`, etc. The API Key can be obtained from Langflow's Settings:

![get\_api\_key](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/get_api_key.png)

Flow ID can be obtained by clicking the `Share` -> `API access` button in the top right corner of the edit page and obtaining it from the example code:

![get\_flow\_id](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/get_flow_id.png)

---

# Using n8n with LangBot

Source: https://langbot.app/docs/en/usage/pipelines/n8n

Integrate n8n with LangBot to drive AI bot workflows and automations across messaging platforms.

[n8n](https://n8n.io/) is an open-source workflow automation platform that allows you to create, schedule, and execute various automated tasks.

LangBot currently supports triggering workflows and receiving responses through the `Webhook` node in n8n workflows.

## Using n8n as the runner

Please open the configuration page of an existing pipeline or create a new pipeline (recommended) and open the configuration page. Select `n8n Workflow API` as the runner in `AI`.

![n8n as the runner](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_runner.png)

Then configure and fill in the other settings according to the content below.

## Configuring n8n Workflow Connection

![n8n Workflow](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/create_wf.png)
or
![n8n Workflow](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/create_wf01.png)

Select `Webhook` or `On chat message` as the trigger and configure as follows:

- Webhook:
  ![n8n webhook configuration](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_webhook.png)
- On chat message:
  ![n8n on chat message configuration](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_n8n_onchatmessage.png)

> :
>
> If you need streaming responses, set `Response Mode` to `Streaming`.
>
> ![n8n streaming configuration](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_response_model.png)

> :
>
> Authentication corresponds to the authentication methods in LangBot's pipeline configuration, which you can modify as needed.
>
> ![n8n workflow configuration](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_auth.png)

Configure the node that calls the AI model as `AI Agent`, following the setup below:

> For streaming responses, add the items highlighted in the red box. If you don't need streaming, you can skip this.

![n8n AI model call configuration](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_call_ai.png)

For the workflow response content in n8n, please use the `Respond to Webhook` node and configure it according to the image below (if you choose streaming responses with the `AI Agent` node, you do not need this step):

![n8n workflow response configuration](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_respond.png)

The response content key name in `Response Body` needs to match the `output key name` in LangBot's pipeline configuration.

After completing the n8n workflow configuration, please click `Active` at the top to enable the workflow.

---

# Pipelines

Source: https://langbot.app/docs/en/usage/pipelines/readme

LangBot pipelines connect AI orchestration platforms (Dify, Coze, n8n, Langflow) to your messaging bots. Learn how they work.

The pipeline controls the processing flow after receiving a message, as well as the information exchange with the large language model. Each bot can be bound to one pipeline, and the same pipeline can be bound to multiple bots.

LangBot automatically creates a default pipeline when first started. When creating a bot, it is automatically bound to the default pipeline. When creating the first model, it is automatically set as the model for the default pipeline.

![arch](https://langbot.app/docs/images/zh/deploy/pipelines/arch.png)

You can create multiple pipelines for different bots to adapt to different scenarios.

The current pipeline can be configured with the following features:

## AI Capabilities

You can choose to use: `Built-in Agent`, [`Dify`](https://dify.ai/), [`n8n`](https://n8n.io/)

AI capabilities are mainly divided into two parts: selecting the runner and configuring runner parameters.

The runner defines how to schedule the large model to process messages. The default is `Built-in Agent`, which is a multi-round Agent strategy implemented by LangBot. Only when this runner is selected will the models and tools configured internally in LangBot be used.

![edit\_pipeline](https://langbot.app/docs/images/zh/deploy/pipelines/edit_pipeline_ai.png)

You can also choose to use external Agent platforms such as `Dify`, [`n8n`](https://n8n.io/). In this case, the models, prompts, tools, and other resources used will be provided by the Agent platform.

![more\_runner](https://langbot.app/docs/images/zh/deploy/pipelines/more_runner.png)

- For detailed steps on connecting to Dify, you can [refer to the tutorial](https://langbot.app/docs/en/usage/pipelines/dify.md).
- For detailed steps on connecting to n8n, you can [refer to the tutorial](https://langbot.app/docs/en/usage/pipelines/n8n.md).

### Conversation Variables

When using external Agent platforms, LangBot explicitly passes the following parameters, which you can add to the start node of the Agent platform workflow (the image below is an example of Dify):

- `launcher_type`: Launcher object type, `person` for private chat, `group` for group chat
- `launcher_id`: Launcher object ID, user ID for private chat, group ID for group chat
- `sender_id`: Sender ID
- `user_message_text`: The plain text of the user message
- `session_id`: User session ID, `person_<id>` for private chat, `group_<id>` for group chat
- `conversation_id`: String, user session ID, generated by LangBot. It will be regenerated after the user resets the session
- `msg_create_time`: Numeric type, timestamp (seconds) when this message was received
- `group_name`: Group name, only set when receiving group messages
- `sender_name`: Sender name

You can [customize any variable through plugins](https://langbot.app/docs/en/plugin/dev/apis/common.md#set-request-variables).

![Dify Workflow Start Node Configuration](https://langbot.app/docs/images/zh/workshop/dify-service-api/dify_workflow_var.png)

## Other Configurations

Please refer to the descriptions in the configuration form.

---

# Using WeKnora with LangBot

Source: https://langbot.app/docs/en/usage/pipelines/weknora

Use WeKnora with LangBot to add knowledge-based question answering to your AI messaging bots.

[WeKnora](https://weknora.weixin.qq.com/) is an open-source document understanding and semantic retrieval framework based on Large Language Models (LLMs), developed by Tencent. It is specifically designed for document scenarios with complex structures and heterogeneous content.\
The framework adopts a modular architecture, integrating multimodal preprocessing, semantic vector indexing, intelligent recall, and large model generation inference to build an efficient and controllable document Q\&A workflow. The core retrieval process is based on the RAG (Retrieval-Augmented Generation) mechanism, which combines contextually relevant passages with language models to achieve high-quality answer generation.

LangBot currently supports two application types for WeKnora: `Knowledge Base Q&A (chat)` and `Agent Intelligent Conversation (agent)`.

## Obtaining API Key from WeKnora

Please deploy the WeKnora service and complete knowledge base creation and document upload according to the [WeKnora Official Documentation](https://github.com/Tencent/WeKnora).

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_api_lead.png)

After deployment, access the WeKnora WebUI (default `http://localhost:80`), navigate to `Settings` -> `API Keys` page, click `Generate API Key` and copy it for safekeeping.

> API Key and Knowledge Base ID:
>
> - `API Key`: Used for authentication. Please keep it secure and do not expose it.
> - `Knowledge Base ID`: You can view the ID (formatted as `kb-00000001`) for each knowledge base on the knowledge base management page, which can be specified in LangBot to invoke the corresponding knowledge base.

After clicking, you can obtain the basic URL and key information.

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_api_information.png)

> Deployment Tips:
>
> - If LangBot and WeKnora are deployed on the same host and both use Docker deployment, you can refer to the article: [Network Configuration Details](https://langbot.app/docs/en/workshop/network-details.md#langbot-and-message-platform-both-running-in-docker-containers). Please add the WeKnora container to `langbot-network` when starting, and set the `API Base URL` in LangBot configuration to the container interconnection address, for example `http://weknora-app:8080/api/v1`.
> - For other scenarios, please consult your company's operations team.

## Obtaining WeKnora Agent Information

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_agent_lead.png)

On the 'Agents' page, click on the Agent you want to select to enter its details page. In `Agent Configuration`, you can view the `Agent ID` (formatted as `builtin-smart-reasoning`), and in `Tool List`, you can view the tool names (such as `web-search`, `file-search`, etc.) that the Agent can call. These information will be needed when configuring LangBot.

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_other_information.png)

At this point, you have prepared the necessary information to connect to the WeKnora API. Next, please follow the steps below to complete the configuration in LangBot.

## Configuring LangBot

Open the LangBot WebUI page, add a new pipeline or switch to the `AI Capabilities` configuration page in an existing pipeline.

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/creat_langbot_pipeline.png)

1. Select `WeKnora API` in `Runner`.
2. In the runner configuration items, fill in:
   - `API Base URL`: The API address of the WeKnora service, default `http://localhost:8080/api/v1`.
   - `API Key`: Paste the API Key generated on WeKnora.
   - `Application Type`: Select `agent` (Agent Intelligent Conversation, supports tool invocation, web search, chain of thought) or `chat` (Knowledge Base RAG Q\&A).
   - `Agent ID`: Built-in Agent identifier, common values:
     - `builtin-smart-reasoning`: Intelligent Reasoning Agent (recommended for `agent` mode)
     - `builtin-quick-answer`: Quick Answer Agent (recommended for `chat` mode)
   - `Knowledge Base ID List`: Fill in the knowledge base IDs to retrieve from (formatted as `kb-00000001`), multiple can be filled.
   - `Enable Web Search`: Only effective in `agent` mode, allows the Agent to call Web search tools when enabled.
   - `Timeout (seconds)`: Request timeout, default `120`.
   - `Default Prompt`: The default question used when the user does not send text content.
3. Click `Save` to complete the configuration.

After completion, you can invoke WeKnora in the pipeline to complete knowledge base-based intelligent conversation.

## Output Processing

- When using the `agent` application, if `track-function-calls` is enabled in LangBot pipeline `Output Processing`, a message `Calling function xxx` will be output to the user each time WeKnora executes a tool call.
- The `thinking` (chain of thought) content returned by WeKnora will be sent wrapped in `<think>` tags, which can be collapsed and displayed on the frontend.
- The `references` (knowledge base citation sources) returned by WeKnora will be attached after the answer as reference source messages.

## Frequently Asked Questions

- **Save failed or invocation error**: Please verify that the `API Key` and `API Base URL` are correct. The URL must include `/api/v1` at the end.
- **No knowledge base content returned**: Please verify that the `Knowledge Base ID` is correct, and that documents have been successfully uploaded and parsed in that knowledge base.
- **Cannot select `WeKnora API`**: Please verify that your current LangBot version supports this runner; if not supported, please upgrade to a version that includes the WeKnora runner.

For more pipeline general configuration instructions, please refer to [Modifying Conversation Pipeline Configuration](https://langbot.app/docs/en/usage/pipelines/readme.md).

---

# DingTalk

Source: https://langbot.app/docs/en/usage/platforms/dingtalk

Build a DingTalk AI bot with LangBot. Connect GPT, Claude, Dify and more to DingTalk groups and conversations.

Deploy LangBot to DingTalk.

## One-Click Setup (Recommended)

LangBot supports one-click DingTalk app creation with automatic credential filling — no manual copy-paste needed.

1. Open LangBot WebUI, go to **Bots > Create Bot**
2. Enter a bot name, select `DingTalk` as the platform/adapter
3. In the **One-Click Create App** section that appears, click the **Start** button

![One-Click Create App](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_oneclick_qrcode.png)

4. Scan the QR code with the DingTalk app. On your phone, select the organization to create the bot in

![Select Organization](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_select_org.png)

5. Choose to **create a new bot** or **select an existing one**

![Create or Select Bot](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_create_or_select.png)

6. After authorization, the phone will show "Configuration Successful", and Client ID / Client Secret will be **auto-filled** in the LangBot WebUI

![Config Success](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_config_success.png)

7. **Manually fill in the bot name** (must match the DingTalk bot name), and the **Robot Code** (required for image/file features — get it from DingTalk Developer Console > Bot Configuration)

![Fill Name and Code](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_fill_name_and_code.png)

8. Click **Submit** to complete

> warning:
>
> After one-click setup, normal text chat works immediately. However:
>
> - **Image/File support**: Requires the Robot Code (RobotCode) to be filled in. If not filled during one-click setup, get it from DingTalk Developer Console > Bot Configuration
> - **Streaming replies**: Requires manually configuring a card template ID — see the Card Template section below

***

## Manual Configuration

### Create Bot

Enter the [DingTalk Developer Backend](https://open-dev.dingtalk.com/?spm=ding_open_doc.document.0.0.74f445e5MkawbT#/), log in and enter the organization. After successful login, enter the open platform, which looks like this:
![DingTalk Open Platform](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk1.png)

Click `Application Development` at the top, then click the blue button `Create Application` on the right, fill in the basic information of the bot, and click save.

Enter the bot's backend, for example, if we have a bot named langbot2, its management page looks like this:
![Bot Page](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk2.png)

### Configure Bot

Click `Add Application Capability`, `Other Application Capabilities`, `Configure` in `Robot`, click configure and fill in the information, as shown below:
![Bot Configuration](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk3.png)

Click `Publish` at the bottom of the page, after successful publication, click `Version Management and Publishing` at the bottom left of the bot page, as shown:
![Version Management and Publishing](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk4.png)

If this is the first time creating a bot, the right side is empty, you need to click `Create New Version`, set information in it, then set `Application Visibility Range`, and click save.

Click `Event Subscription`, change the push method to `Stream Mode Push`.

If card streaming is needed, you must apply for card permissions in the permission management, as shown:
![Before applying for card permissions](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk6.png)

![After applying for card permissions](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk7.png)

Additionally, for card messages you mainly need to create a card template and record the template ID to fill in the configuration, the process is as follows:

> The card content template ID can be obtained by logging into the developer backend > [Card Platform](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV)

Fill in information when creating a new template, as shown:
![Fill in information for new template](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk8.png)

Select a preset template (just choose the first one and modify the template content later), as shown:
![Select preset template](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk9.png)
Click Use
![Click](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk10.png)
Create
![Create](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk11.png)

After clicking Create you'll be redirected to edit the template. As shown, you can freely edit your desired card message:
![Edit template](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk12.png)

For the main content, keep the default 'content' unchanged:
![Don't modify](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk13.png)

Widescreen configuration parameters, you need to add . in the template variables. See [DingTalk Widescreen Configuration](https://open.dingtalk.com/document/development/configure-widescreen-cards)
![Widescreen Configuration](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk16.png)

After editing and confirming everything is correct, save it and copy the template ID to fill in the configuration file:
![Save](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk14.png)
![Copy template ID](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk15.png)

### Fill in Configuration Information

Click `Credentials and Basic Information`, record `Client ID` and `Client Secret`,
Click `Application Capabilities`, `Robot`, record the RobotCode and Robot Name.
`markdown_card` is whether to enable Markdown form replies. When this configuration item is disabled, the `@Sender` configuration switch will not take effect.
Record the above configuration items and fill them in the LangBot bot configuration form

Click [Card Platform](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV), copy the corresponding bound template ID from the template list, and fill it into the card template ID field.

![Connect to LangBot](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/connect_to_langbot.png)

Streaming related:
![img.png](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk17.png)

**Start LangBot**.

### Add Bot

This article uses DingTalk Windows desktop version as an example, click `Search` at the top, `Features`, then enter the name of the bot you just created, as shown:
![robot\_png](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk5.png)

Click on the bot to chat with it.

If you want to add it to a group, click `Group Management`, `Robots`, `Add Robot` in the DingTalk group, then search for the bot name to use it in the group.

---

# Discord

Source: https://langbot.app/docs/en/usage/platforms/discord

Build a Discord AI bot with LangBot. Connect GPT, Claude, Gemini, DeepSeek and Dify to your Discord server in minutes.

## Create Bot

Go to the [Discord Developer Portal](https://discord.com/developers/applications), log in, and create an application.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_01.png)

Modify the basic information, click `Save Changes` to save.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_02.png)

Click `Bot` on the left, click `Reset Token`, copy the generated Token.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_03.png)

And check all options in `Privileged Gateway Intents` on this page, click `Save Changes` to save.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_05.png)

**Finally, click `OAuth2` on the left, copy the `Client ID` on the page.**

## Connect to LangBot

Click to add a new bot, fill in the `Client ID` and `Token` obtained in the previous step into the configuration.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/connect_to_langbot.png)

> warning:
>
> If you are using this adapter within mainland China, you may need to set up a network proxy.

After filling in, start LangBot. If configured successfully, the log will show `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: discord`, keep LangBot running.

## Invite Bot to Server

You need to create a server first, then invite the bot to the server.

Go to the `OAuth2` page, select `URL Generator`, select `bot`, check the permissions as shown in the image.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_06.png)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_07.png)

Click `Copy`, paste the generated URL into your browser to open it, and invite the bot to your server.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_08.png)

## Use Bot

Now you can use the bot normally in groups or private messages.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_09.png)

---

# HTTP Bot

Source: https://langbot.app/docs/en/usage/platforms/http-bot

Integrate any backend with LangBot over plain HTTP: push messages in via a signed webhook, receive replies on a callback URL. Server-to-server, no long-lived connection.

The `HTTP Bot` adapter integrates **any backend system** with a LangBot pipeline over plain HTTP. Ticketing systems, CRMs, internal tools, custom web apps — all can drive a pipeline through it:

- **Inbound**: your backend POSTs a signed message to a fixed LangBot URL;
- **Outbound**: LangBot POSTs replies to a callback URL you configure.

It needs **no long-lived connection** and fully preserves two native pipeline capabilities:

- **Message aggregation (N→1)**: a user fires several messages in a row, merged into one turn;
- **Multi-part replies (1→M)**: one turn may produce several replies (function calls, multi-message plugins, streamed chunks).

> info:
>
> If you want an **in-browser**, real-time chat widget, use the [Web Page Bot](https://langbot.app/docs/en/usage/platforms/webpage.md) instead. HTTP Bot is designed for backend-to-backend integration.

## How it works

```
Your backend  ──(1) POST signed message──►  LangBot   /bots/<bot_uuid>
                                            (pipeline: aggregate → think → reply)
Your callback ◄─(2) POST signed reply(s)──  LangBot   one POST per reply part
```

- **(1) Inbound** is *fire-and-collect*: LangBot returns `202 Accepted` immediately and does **not** carry the pipeline result on that response;
- **(2) Outbound** replies arrive later as separate signed POSTs to your `callback_url`; a single turn may produce several callbacks;
- Everything is keyed by a **`session_id` you choose** (e.g. a ticket number); each `session_id` maps to one isolated session.

## Create the bot

In the LangBot WebUI, go to **Bots > Create Bot**, fill in a name, and pick `HTTP Bot` as the platform/adapter.

## Configuration

| Field                      | Required | Notes                                                                                              |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| Inbound Signing Secret     | yes      | Your backend signs inbound requests with this; LangBot verifies every inbound request.             |
| Outbound Callback URL      | yes      | Where LangBot POSTs replies. **Config-only** — cannot be overridden per message (SSRF protection). |
| Outbound Signing Secret    | no       | LangBot signs callbacks with this; defaults to the inbound secret if blank.                        |
| Default Session Type       | no       | `person` (default) or `group`.                                                                     |
| Require Inbound Signature  | no       | Keep enabled in production.                                                                        |
| Callback Timeout (seconds) | no       | Per-callback HTTP timeout, default 15.                                                             |
| Callback Max Retries       | no       | Retries on timeout or 5xx with exponential backoff, default 3.                                     |

After binding a **pipeline** and **enabling** the bot, the config page shows the **Inbound Webhook URL**, like `https://your-langbot/bots/<bot_uuid>`. Copy it.

## Signature scheme

Both directions use the same dependency-free HMAC-SHA256 scheme:

```
signing_string = "{timestamp}." + raw_body_bytes
signature      = "sha256=" + hex(HMAC_SHA256(secret, signing_string))
```

Sent as headers:

| Header                 | Meaning                                                         |
| ---------------------- | --------------------------------------------------------------- |
| `X-LB-Timestamp`       | Unix seconds. Rejected if more than **±300s** from server time. |
| `X-LB-Signature`       | `sha256=<hex>` over `"{timestamp}." + body`.                    |
| `X-LB-Idempotency-Key` | *(optional, inbound)* dedup key; a repeat returns `409`.        |

Verify outbound callbacks the same way, using the **outbound** secret (or the inbound secret if left blank).

## Send your first message (curl)

```bash
BOT="https://your-langbot/bots/<bot_uuid>"
SECRET="your-inbound-secret"
BODY='{"session_id":"ticket-10293","message":[{"type":"Plain","text":"Export keeps failing on the dashboard."}]}'
TS=$(date +%s)
SIG="sha256=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)"

curl -sS -X POST "$BOT" \
  -H "Content-Type: application/json" \
  -H "X-LB-Timestamp: $TS" \
  -H "X-LB-Signature: $SIG" \
  -d "$BODY"
# -> 202 {"code":0,"msg":"accepted","data":{"session_id":"ticket-10293","accepted_message_id":"in_...","aggregating":true}}
```

Replies will be POSTed to your configured callback URL shortly after.

## Inbound request format

`POST /bots/{bot_uuid}`

```json
{
  "session_id": "ticket-10293",
  "session_type": "person",
  "sender": { "id": "user-5567", "name": "Alice" },
  "message": [
    { "type": "Plain", "text": "Export keeps failing on the dashboard." },
    { "type": "Image", "url": "https://example.com/screenshot.png" }
  ]
}
```

- `session_id` (**required**): your stable id, mapped 1:1 to a LangBot session;
- `message` (**required**): a LangBot message chain. Text uses `{"type":"Plain","text":"..."}`, images use `{"type":"Image","url":"..."}` (or `base64`); other types: `Voice`, `File`, `At`, `Quote`.

> warning:
>
> The callback URL is **not** accepted in the body — it is taken only from bot config. This is deliberate: even if the inbound secret leaks, an attacker cannot redirect replies to an arbitrary host.

### Aggregation (N → 1)

If the pipeline has **message aggregation** enabled, send several messages with the **same `session_id`** inside the aggregation window and they merge into **one** turn. No special flag — just reuse the `session_id`.

## Outbound callback format

LangBot POSTs each reply part to your callback URL:

```json
{
  "session_id": "ticket-10293",
  "reply_to": "in_01H...",
  "sequence": 1,
  "is_final": false,
  "stream": false,
  "message": [ { "type": "Plain", "text": "Looking into it…" } ],
  "timestamp": "2026-06-22T09:00:01Z"
}
```

Your endpoint should return `2xx` quickly. Non-2xx / timeout → LangBot retries with exponential backoff.

### Multi-part replies (1 → M)

One turn may emit multiple callbacks, delivered **in `sequence` order** for a given session:

```
seq=1 is_final=false  "Checking your export logs…"
seq=2 is_final=false  "Found 2 failed exports."
seq=3 is_final=true   "Fixed — please try again."
```

Stitch by `session_id` + `sequence`; the turn is complete when `is_final: true` arrives.

## Reset a session

Start a fresh conversation for a `session_id` (drops history):

```
POST /bots/{bot_uuid}/reset
{ "session_id": "ticket-10293", "session_type": "person" }
→ 200 { "code":0, "msg":"reset", "data": { "session_id":"ticket-10293", "removed": true } }
```

Signed exactly like an inbound message.

## Synchronous convenience mode

If you don't need streaming/multi-part and just want one reply back on the same HTTP call, POST to `/sync`. LangBot waits for the turn to finish and returns all reply parts **collapsed** into one array:

```
POST /bots/{bot_uuid}/sync
{ "session_id": "ticket-10293", "message": [ { "type":"Plain", "text":"hi" } ] }
→ 200 { "code":0, "msg":"ok",
        "data": { "session_id":"ticket-10293", "reply_to":"in_...", "message": [ ... ] } }
```

> warning:
>
> Sync mode is **lossy** (you lose `sequence` and streaming boundaries) and blocks up to `callback_timeout × 4` seconds. Prefer the callback model for anything real-time or multi-part. Only one in-flight `/sync` per `session_id`.

## Error codes

```json
{ "code": 40101, "msg": "invalid signature: signature_mismatch", "data": null }
```

| HTTP | code  | meaning                                            |
| ---- | ----- | -------------------------------------------------- |
| 202  | 0     | accepted                                           |
| 400  | 40001 | malformed body / missing `session_id` or `message` |
| 401  | 40101 | bad/expired signature                              |
| 409  | 40901 | duplicate idempotency key                          |
| 413  | 41301 | message too large (>1 MiB)                         |
| 500  | 50001 | internal error                                     |

## Reference clients & 5-minute demo

The main repo's [`examples/http-bot/`](https://github.com/langbot-app/LangBot/tree/master/examples/http-bot) ships an **interactive playground** plus Python and TypeScript reference clients.

### Interactive playground (run this first)

[`playground.py`](https://github.com/langbot-app/LangBot/blob/master/examples/http-bot/playground.py) is a single-file web app: type a message in your browser → it is signed and POSTed to a **running** `http_bot` bot → replies stream back into the page, with a debug panel showing the signature, the `202` ack, and each callback's `sequence` / verification.

```bash
# From the LangBot repo root, with the backend running:
PUBLIC_IP=<your-host-ip> ./.venv/bin/python examples/http-bot/playground.py
# then open  http://<your-host-ip>:8920/
```

On startup it reads the API key + the `http_bot` bot from `data/langbot.db` and points that bot's `callback_url` + secrets back at itself via the LangBot API (live reload, no restart). Requires an enabled `http_bot` bot bound to a working pipeline.

### Command-line reference clients

[`examples/http-bot/`](https://github.com/langbot-app/LangBot/tree/master/examples/http-bot) also ships Python and TypeScript reference clients (with a callback receiver):

```bash
cd examples/http-bot
pip install flask requests

# Terminal 1: callback receiver (point the bot's callback_url here; use cloudflared / ngrok locally)
python client.py serve --port 8900 --secret SHARED_SECRET

# Terminal 2: push a message
python client.py push \
  --url https://your-langbot/bots/<bot_uuid> \
  --secret SHARED_SECRET \
  --session ticket-1 \
  --text "hello"
```

Terminal 1 prints each reply part (`[part ]` / `[FINAL]`) with its sequence number — that's 1→M multi-reply with signature verification, live.

A machine-readable contract is in the main repo at [`docs/http-bot-openapi.json`](https://github.com/langbot-app/LangBot/blob/master/docs/http-bot-openapi.json).

## Security checklist

- Keep **Require Inbound Signature** on in production;
- Use **HTTPS** callback URLs, set only in config (no per-message override);
- Treat secrets like passwords; rotate via the dashboard;
- The inbound route is unauthenticated at the framework level **by design** — security comes entirely from the HMAC signature, so never disable it on a public deployment.

---

# KOOK

Source: https://langbot.app/docs/en/usage/platforms/kook

Build a KOOK AI bot with LangBot. Connect large language models to your KOOK (Kaiheila) channels.

## Create a Bot

Visit the [KOOK Developer Center](https://developer.kookapp.cn/), log in and access the console.

![KOOK Developer Console](https://langbot.app/docs/images/zh/deploy/bots/kook/01-dashboard.png)

Click "Create Application" and fill in the application information.

![Create Application](https://langbot.app/docs/images/zh/deploy/bots/kook/02-create-app.png)

After the application is created, enter the application details page.

![Application Created](https://langbot.app/docs/images/zh/deploy/bots/kook/03-app-created.png)

You can view the basic information of the application on the application overview page.

![Application Overview](https://langbot.app/docs/images/zh/deploy/bots/kook/04-app-overview.png)

## Get Bot Token

In the application page, click the "Bot" tab, copy the Bot Token and save it securely. You will need it later.

![Get Bot Token](https://langbot.app/docs/images/zh/deploy/bots/kook/05-bot-token.png)

## Configure Bot Permissions

**Important:** In the "Bot" settings, find the "Message Filtering" option and click to configure.

![Message Filter Settings](https://langbot.app/docs/images/zh/deploy/bots/kook/07-message-filters.png)

Enable all message-related event permissions, including channel messages and private message events. Otherwise, the bot will not be able to receive messages.

![Enable Permissions](https://langbot.app/docs/images/zh/deploy/bots/kook/08-permissions-enabled.png)

## Invite the Bot

In the bot settings page, you can generate an invitation link to invite the bot to your server.

![Generate Invitation Link](https://langbot.app/docs/images/zh/deploy/bots/kook/06-invite-link.png)

## Connect to LangBot

Open the LangBot Webui page, and click to create a new bot on the "Bots" page.

![LangBot Bot Management](https://langbot.app/docs/images/zh/deploy/bots/kook/09-langbot-bots.png)

Select the KOOK platform, fill in the bot name and Bot Token.

![Configure KOOK Bot](https://langbot.app/docs/images/zh/deploy/bots/kook/10-bot-config.png)

After saving, the bot will appear in the list.

![Bot Created](https://langbot.app/docs/images/zh/deploy/bots/kook/11-bot-created.png)

Click the enable button to start the bot. If successfully configured, the bot status will show as running.

![Bot Enabled](https://langbot.app/docs/images/zh/deploy/bots/kook/12-bot-enabled.png)

## Using the Bot

Now in the KOOK server, the bot can receive and reply to messages normally. The bot supports both channel messages and private messages.

---

# Feishu

Source: https://langbot.app/docs/en/usage/platforms/lark

Build a Feishu/Lark AI bot with LangBot. Connect GPT, Claude, Dify and more to Feishu groups and messaging.

## Select Platform Domain

When creating a bot, you need to select the **Platform Domain** in the **Adapter Configuration** section:

- **Feishu (open.feishu.cn)**: For mainland China Feishu users (default)
- **Lark (open.larksuite.com)**: For overseas Lark users
- **Custom**: For private deployment users

![Select Platform Domain](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_platform_domain.png)

> warning:
>
> If you select overseas Lark, make sure to use the `open.larksuite.com` domain, otherwise the connection may fail. For private deployment users, please select custom and fill in the corresponding domain based on your actual deployment address.

## One-Click Setup (Recommended)

LangBot supports one-click Feishu app creation with automatic credential filling — no manual copy-paste needed.

1. Open LangBot WebUI, go to **Bots > Create Bot**
2. Enter a bot name, select `Feishu` as the platform/adapter
3. In the **One-Click Create App** section that appears, click the **Start** button

![One-Click Create Feishu App](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_oneclick_qrcode.png)

4. Scan the QR code with Feishu. On your phone, you'll see the Feishu Open Platform's bot creation page
5. Choose to **use an existing app** or **create a new one**:

![Select on Phone](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_select_or_create_bot.png)

If you choose an existing app, a list of your apps will be shown:

![Select Existing App](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_select_existing.png)

6. After authorization, the phone will show "Configuration Successful", and app\_id / app\_secret will be **auto-filled** in the LangBot WebUI

![Config Success](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_config_success.png)

7. **Manually fill in the bot name** — it must match the Feishu bot name, otherwise the bot won't receive messages in groups

![Fill Bot Name](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_fill_bot_name.png)

8. Click **Submit** to complete

***

## Create Bot

Go to the [Feishu Open Platform](https://open.feishu.cn/app), log in, and create an enterprise self-built application or store application. [(difference introduction)](https://open.feishu.cn/document/platform-overveiw/overview)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_01.png)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_02.png)

Add bot capability to the application:
![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_03.png)

Add the permissions shown in the image in the permission management:

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_04.png)

If card streaming permissions are required, additionally add the following card creation and update permissions as shown in the image:

![img\_1.png](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_14.png)

> warning:
>
> If you need to change the default card template, you need to modify the card template in the platform adapter's code yourself.

### Connect to LangBot

Find `app_id` and `app_secret` on the `Credentials and Basic Information` page.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_05.png)

Open LangBot's Webui configuration page, create a new bot

Fill in the relevant information in the form

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/connect_to_langbot.png)

Streaming related:
![Streaming related](https://langbot.app/docs/images/zh/deploy/bots/lark/connect_to_langbot01.png)

After filling in, start LangBot. If configured successfully, the log will show `[01-29 23:42:56.796] manager.py (68) - [INFO] : Initializing platform adapter 1: lark`, keep LangBot running.

> :
>
> By default, WebSocket long connection mode is used, corresponding to the long connection subscription below. But in some cases (such as international version of Feishu), long connection mode is not available, in which case you need to use Webhook mode, corresponding to the `Send events to developer server` mode, please refer to the following configuration:
>
> - `enable-webhook`: Set to `true`
> - `encrypt-key`: Set to `Encrypt Key` in the `Encryption Strategy` of the `Events and Callbacks` page
>
> Note that in Webhook mode, LangBot needs to be deployed on a server with a public IP, and ensure that the firewall has opened the port configured above.

> idea:
>
> **No public server?** [LangBot Cloud](https://space.langbot.app/cloud) includes built-in domain and HTTPS — get Lark bots working out of the box.

### Configure Event Subscription

Go to the `Events and Callbacks` page, configure the subscription method as `Long Connection`:

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_07.png)

And add the event: `Receive Messages`

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_08.png)

Set up `Callback Configuration`, select the long connection callback (use webhook if using webhook mode)

![Set up callback configuration](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_16.png)

Add the callback `Card Callback Interaction`

![Add callback](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_17.png)

> :
>
> Webhook mode configuration method:
>
> ![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_13.png)
>
> Please start LangBot first, fill in the Webhook address obtained from LangBot here.

### Publish Bot

Click `Create Version` at the top, fill in the version number and other information, click `Save` below.

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_09.png)

Add the bot to a Feishu group to use it:

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_10.png)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_11.png)

Private chat can also be used directly

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_12.png)

## Common Issues

- Store app bots cannot respond to chat messages immediately after creation/saving. Due to the [app\_ticket event](https://open.feishu.cn/document/server-docs/application-v6/event/app_ticket-events) delay mechanism, you need to wait about 2 minutes before it can work normally.

---

# LINE

Source: https://langbot.app/docs/en/usage/platforms/line

Build a LINE AI bot with LangBot. Connect large language models to LINE chats and official accounts.

This article explains how to connect LangBot with the LINE platform to implement LINE bot functionality.

## Creating a LINE Bot

### Register a LINE Developer Account

1. Visit the [LINE Developers website](https://developers.line.biz/) and log in with your LINE account
2. After logging in, enter the developer console

### Create Provider and Channel

> [Developer Console](https://developers.line.biz/console)

1. In the developer console, create a new Provider (if you don't have one)
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line01.png)

2. Under the Provider, click "Create"
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line02.png)

3. Enter a name and click Create
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line03.png)

4. After being redirected, select Create a Message API
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line04.png)

- Continue by clicking Create a Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line05.png)
- After being redirected, fill in the basic information
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line06.png)
  - Channel Name
  - Channel Description
  - Category
  - Subcategory
  - Email Address

5. After filling in all information, click "Continue" to create
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line07.png)
6. Check the information you entered, and if there are no issues, click Submit
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line08.png)
7. Successfully created, proceed to use
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line09.png)

### Get Configuration Information

After creation, you will obtain the following important information, please record it:

1. Channel Secret

> [Page after clicking use](https://manager.line.biz/account)

- Select Settings
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line09.png)
- Click Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line11.png)
- Enable Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line12.png)
- Select the Provider you just created and click Agree
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line13.png)
- For privacy terms, simply click OK
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line14.png)
- Click OK to complete creation
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line15.png)
- Copy it
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line16.png)

2. Channel Access Token (need to click the "Issue" button to generate)

- Click console or directly visit [Console](https://developers.line.biz/console/)
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line17.png)
- Select the Provider you created and click Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line18.png)
- Click Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line19.png)
- Scroll to the bottom, click Issue
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line20.png)
- Click the icon to copy
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line21.png)

## Connecting to LangBot

Next, open the LangBot configuration page:

1. Click "Bots", then click "Add"
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line26.png)

2. Select "LINE" in "Platform/Adapter Selection"
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line27.png)

3. Fill in the configuration information:
   - Channel Secret: The Channel secret you obtained earlier
   - Channel Access Token: The Channel access token you obtained earlier
     ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line28.png)

4. Click "Save" to complete the configuration
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line29.png)

## Configure Webhook

> info:
>
> We recommend that you first refer to [Configure HTTP Reverse Proxy](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md) to configure the LangBot callback address.

> idea:
>
> **Don't want to set up a public server and domain?** [LangBot Cloud](https://space.langbot.app/cloud) includes built-in domain and HTTPS — get started right away.

- Get the Webhook callback URL from the LangBot configuration page
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line30.png)

- Click console or directly visit [Console](https://developers.line.biz/console/)
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line17.png)

- Select the Provider you created and click Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line18.png)

- Click Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line19.png)

- Click Edit to fill in the connection
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line22.png)

- Enter the connection (must be an HTTPS connection, which means you need an SSL certificate), click Update
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line23.png)

- Select Use Webhook
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line24.png)

5. Click the "Verify" button to test if the connection is successful
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line25.png)

## Feature Configuration

In the LINE developer console, you can further configure the bot's features:

1. In the "Messaging API" tab, find the "LINE Official Account Features" section
2. Enable or disable the following features as needed:
   - Auto-reply messages
   - Welcome messages when adding friends
   - Group and multi-person chat
   - Greeting when the bot joins a group

## Usage

After configuration, users can interact with your LINE bot through the following methods:

1. Scan the QR code provided in the LINE developer console to add the bot as a friend
2. Send messages in the chat, and the bot will process and reply through LangBot

## Common Issues

### Webhook Verification Failed

- Ensure your server can be accessed via HTTPS
- Check if the Webhook URL is correct
- Confirm that the LangBot service is running properly

### Unable to Receive Messages

- Check if the Channel Access Token is valid
- Confirm that the "Use Webhook" option is enabled
- Check the LangBot logs for error messages

### Permission Issues

- Ensure you have enabled the necessary permissions for the bot in the LINE developer console
- For some advanced features, a LINE Premium account may be required

---

# Mattermost

Source: https://langbot.app/docs/en/usage/platforms/mattermost

Connect a Mattermost bot to LangBot and bring agents and workflows to your Mattermost server in minutes.

> info:
>
> The screenshots below use the Chinese interface. Follow the corresponding menu items and fields described in the text.

## Create a bot account

Log in to your Mattermost instance (self-hosted or hosted by Mattermost). Click the `Mattermost icon` in the upper-left corner and select `Integrations` from the menu.

![Open Integrations from the Mattermost menu](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_main_page.png)

On the Integrations page, select `Bot Accounts` in the left menu, then click `Add Bot Account` in the upper-right corner.

![Open Bot Accounts and add a bot account](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_account.png)

Choose a username for the bot.

![Enter the bot username](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_add_new.png)

Set the role to `Member` (administrator-related features are not currently supported). Select `post:all` if you need direct messages, or select only `post:channels` if you only need public channels. Then click `Create Bot Account` in the lower-right corner.

![Select the bot role and posting permissions](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_deploy.png)

Click the button to copy the token. It is shown only once, so save it securely. Then click `Done` in the lower-right corner.

![Copy the bot token before completing account creation](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_token.png)

## Configure the bot in LangBot

Open LangBot Cloud or your self-hosted LangBot instance and follow the red arrows in the screenshot below:

- Hover over the `Bots` tab on the left and click the `+` icon that appears.
- Enter a name in the `Bot Name` field.
- Open the platform adapter dropdown and select `Mattermost`.
- Enter the address of your Mattermost instance and the token for the bot account you just created.
- (Optional) Disable streaming output if your pipeline or AI provider does not support it.
- Click `Submit` in the upper-right corner to open the bot editing page.

![Add a Mattermost bot and enter the instance address and token in LangBot](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_langbot_add_new.png)

Bind an existing pipeline, configure routing if needed, and click `Save` in the upper-right corner.

![Bind a pipeline and save the Mattermost bot configuration](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_langbot_deploy.png)

---

# Lagrange

Source: https://langbot.app/docs/en/usage/platforms/qq/aiocqhttp/lagrange

Connect QQ to LangBot via Lagrange (aiocqhttp). Run an AI bot in QQ groups and private chats.

## Lagrange Introduction

Lagrange is a QQNT protocol reverse engineering framework that is lightweight and relatively stable. Connect through the OneBot 11 protocol, you need to select `OneBot v11` as the adapter.

> warning:
>
> You need to use NT QQ to interact with the bot, old versions of QQ will not work properly

## Deployment Steps

The following only provides general steps for Windows, for detailed steps or other platforms, please refer to the [Lagrange official documentation](https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/)

### Environment Configuration

Install .NET 8 runtime, [Click here to go directly to Microsoft's official website to download](https://dotnet.microsoft.com/zh-cn/download/dotnet/thank-you/runtime-desktop-8.0.4-windows-x64-installer)

### Download the latest build from Github Actions

You need to log in to Github to download. If you don't need certain features, you can download from Release, see image 3

[Github Actions](https://github.com/KonataDev/Lagrange.Core/actions)

Follow the images to download:

![Image 1](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_1.png)

![Image 2](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_2.png)

![Image 3](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_3.png)

### Final Steps

Extract the zip you downloaded, navigate to the directory containing Lagrange.OneBot.exe, open a cmd command prompt in this directory, and enter

```bash
.\Lagrange.OneBot
```

Run it once, if a QR code is output, you can directly scan it with the bot account to log in (if the QR code is not clear, you can look for the image file in the lagrange data directory).

If you cannot log in, please check if you have correctly filled in the signature address SignServerUrl in the lagrange configuration file appsettings.json. Please look for the signature address in the lagrange documentation.

## Modify Configuration

You need to configure Lagrange to connect to LangBot. Please edit Lagrange's configuration file appsettings.json and ensure that the connection configuration in Implementations matches the content in the image below:

![Configure Connection](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/config_lgr.png)

The Type must be `ReverseWebSocket`;\
Host is the IP of the host running LangBot, if on the same host, you can write `127.0.0.1`;\
Suffix must be `/ws`;

## Lagrange Integration

Next, open the LangBot configuration page

Click on Bots, then click Add

Select `OneBot v11` for `Platform/Adapter Selection`

![napcat\_webui\_03](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png)

> info:
>
> Note, if you have network connection issues involving multiple docker containers, please refer to [Network Configuration Details](https://langbot.app/docs/en/workshop/network-details.md)

---

# LiteLoaderQQNT

Source: https://langbot.app/docs/en/usage/platforms/qq/aiocqhttp/llonebot

Connect QQ to LangBot via LiteLoaderQQNT (LLOneBot). Set up an AI bot for QQ groups and chats.

Connect through the OneBot 11 protocol, you need to select `OneBot v11` as the adapter.

# LiteLoaderQQNT

- [LiteLoaderQQNT's OneBot API plugin](https://github.com/LLOneBot/LLOneBot) injects into the QQ client and converts it to the OneBot 11 protocol

Installation tutorial for LiteLoaderQQNT: <https://llonebot.github.io/zh-CN/guide/getting-started>

![Image 1](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/llonebot/llob_cfg.png)

Make sure the IP address in the address is the address of the host running LangBot (if running on the same network, use 127.0.0.1)

## Lagrange Integration

Next, open the LangBot configuration page

Click on Bots, then click Add

Select `OneBot v11` for `Platform/Adapter Selection`

![napcat\_webui\_03](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png)

> info:
>
> Note, if you have network connection issues involving multiple docker containers, please refer to [Network Configuration Details](https://langbot.app/docs/en/workshop/network-details.md)

---

# NapCat

Source: https://langbot.app/docs/en/usage/platforms/qq/aiocqhttp/napcat

Connect QQ to LangBot via NapCat (aiocqhttp). Run an AI chatbot in QQ groups and private messages.

Connect through the OneBot 11 protocol, you need to select `OneBot v11` as the adapter.

## NapCat Installation Tutorial

Follow the [NapCat official documentation for installation](https://napcat.napneko.icu/guide/start-install)

## NapCat Configuration Tutorial

Only using webui operation as an example, for other configuration methods, please check the NapCat documentation.

After logging in, you can check the logs in the console or Bash, find `[NapCat] [WebUi] WebUi Publish Panel Url: http://x.x.x.x:6099/webui?token=xxxxx `
![napcat\_webui\_01](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_01.png)

Copy the Url to your browser or on Windows 11, press Ctrl and click the Url. After scanning the QR code to log in, you will enter the network configuration page.

Click Add Network Configuration, select WebSocket Client, click Enable, then fill in `ws://127.0.0.1:2280/ws` in the Url field and save.
![napcat\_webui\_02](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_02.png)

## NapCat Integration

Next, open the LangBot configuration page

Click on Bots, then click Add

Select `OneBot v11` for `Platform/Adapter Selection`

![napcat\_webui\_03](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png)

> info:
>
> Note, if you have network connection issues involving multiple docker containers, please refer to [Network Configuration Details](https://langbot.app/docs/en/workshop/network-details.md)

---

# QQ Official Bot API (Webhook)

Source: https://langbot.app/docs/en/usage/platforms/qq/official_webhook

Connect the QQ Official Bot API (Webhook) to LangBot to run a compliant AI bot on QQ.

This article only provides the deployment of test bots. For the official launch of bots, please follow the [release process](https://q.qq.com/qqbot/#/home).

> warning:
>
> QQ Official has issued an announcement prohibiting unauthorized access to AIGC features. Please use with caution.

## Register QQ Bot (Test Bot)

### Configure Basic Bot Information

Go to the [QQ Open Platform](https://q.qq.com/#/), find `Application Management` at the bottom, click Create Bot, fill in the basic information, and then enter the bot page, as shown:

![Bot Main Page](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial1.png)

The `Release Process` in the `Home` option is the step to launch the bot. Since you are deploying a test version bot, you only need to complete the `Information` and `Sandbox Configuration` sections.\


First fill in the information, then click on Sandbox Configuration.

#### Configure Sandbox Settings

Click on `Sandbox Configuration`.
If you want to deploy in a QQ group, follow the requirements under `QQ Group ID` to select a group chat, and add users with private chat permissions in the message list configuration.\

If you want to deploy in a QQ channel, follow the requirements under `Channel ID` to select a channel ID, with bot type 0.

#### Configure Development Management

Click on `Development Management`.

![Development Management Page](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial2.png)

Record the `AppID`, `Token`, and `AppSecret`, and add the IP address of the server where LangBot is located to the IP whitelist.

## Connect to LangBot

Next, open the LangBot configuration page

Click on Bots, then click Add

Select `QQ Official API` for `Platform/Adapter Selection`

![QQ Official Bot Integration with LangBot](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial3.png)

## Configure Callback Address

LangBot must be deployed on a server with a public IP address, and HTTPS must be successfully enabled. Please follow the documentation [Configure HTTP Reverse Proxy and SSL](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md) for configuration.

> idea:
>
> **Don't want to deal with public IPs and HTTPS?** [LangBot Cloud](https://space.langbot.app/cloud) includes built-in domain resolution — sign up and use QQ Official Bot right away.

#### Subsequent Configuration

If Caddy fails to start, please read the [Caddy documentation](https://caddy2.dengxiaolong.com/docs/quick-starts/caddyfile) or join the LangBot community group for help.\


Here are some possible issues:

- Port 443 is not open
- The domain is not resolved to your machine
- Caddyfile was not saved successfully

### Set Management Portal Callback Address

First **start LangBot**.

Click on `Callback Configuration` in the bot management portal, check all events under `Add Event`.

Go to the LangBot configuration page, enable and select the corresponding QQ bot, copy the Webhook callback address from the corresponding bot configuration page, replace the IP address and port with the domain name configured in Caddy, and enter it in the request address.

As shown in the image:
![Caddy Documentation](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial4.png)

For example, if the domain is `testlb.com`, then enter `testlb.com/bots/xxxxxx-xxxxxx` in the request address, and click to confirm the configuration. If the callback address is saved successfully, it means the deployment is successful. If you see `Verification Failed`, please carefully check if the above configuration items are filled in correctly.

## Publication Method

Enter the release process in `Home` and follow the process to publish and launch the bot.

---

# Bots

Source: https://langbot.app/docs/en/usage/platforms/readme

Connect LangBot to messaging platforms: Discord, Telegram, Slack, WeChat, QQ, Lark, DingTalk, LINE and more.

Bots are used to receive message events from messaging platforms and call pipelines to process messages.

![arch](https://langbot.app/docs/images/zh/deploy/bots/arch.png)

| Platform                  | Status | Notes                                                                                             | Tutorial                                                                                                                                                                                                                                               |
| ------------------------- | ------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Discord                   | ✅      |                                                                                                   | [Tutorial](https://langbot.app/docs/en/usage/platforms/discord.md)                                                                                                                                                                                     |
| Telegram                  | ✅      |                                                                                                   | [Tutorial](https://langbot.app/docs/en/usage/platforms/telegram.md)                                                                                                                                                                                    |
| Slack                     | ✅      |                                                                                                   | [Tutorial](https://langbot.app/docs/en/usage/platforms/slack.md)                                                                                                                                                                                       |
| Mattermost                | ✅      | Supports the open-source, Free, Professional, and Enterprise editions                             | [Tutorial](https://langbot.app/docs/en/usage/platforms/mattermost.md)                                                                                                                                                                                  |
| LINE                      | ✅      |                                                                                                   | [Tutorial](https://langbot.app/docs/en/usage/platforms/line.md)                                                                                                                                                                                        |
| KOOK                      | ✅      |                                                                                                   | [Tutorial](https://langbot.app/docs/en/usage/platforms/kook.md)                                                                                                                                                                                        |
| Lark                      | ✅      |                                                                                                   | [Tutorial](https://langbot.app/docs/en/usage/platforms/lark.md)                                                                                                                                                                                        |
| DingTalk                  | ✅      |                                                                                                   | [Tutorial](https://langbot.app/docs/en/usage/platforms/dingtalk.md)                                                                                                                                                                                    |
| WeCom (Enterprise WeChat) | ✅      | Enterprise internal bot                                                                           | [Tutorial](https://langbot.app/docs/en/usage/platforms/wecom/wecom.md)                                                                                                                                                                                 |
| WeCom Intelligent Bot     | ✅      | wecom intelligent bot                                                                             | [Tutorial](https://langbot.app/docs/en/usage/platforms/wecom/wecombot.md)                                                                                                                                                                              |
| WeCom Customer Service    | ✅      | Enterprise external bot                                                                           | [Tutorial](https://langbot.app/docs/en/usage/platforms/wecom/wecomcs.md)                                                                                                                                                                               |
| WeChat Official Account   | ✅      | WeChat public platform bot                                                                        | [Tutorial](https://langbot.app/docs/en/usage/platforms/wxoa.md)                                                                                                                                                                                        |
| OneBot v11                | ✅      | Uses a personal QQ account as a bot, requires an independent protocol client, supports OneBot v11 | [NapCat](https://langbot.app/docs/en/usage/platforms/qq/aiocqhttp/napcat.md)  [Lagrange](https://langbot.app/docs/en/usage/platforms/qq/aiocqhttp/lagrange.md)  [LiteLoaderQQNT](https://langbot.app/docs/en/usage/platforms/qq/aiocqhttp/llonebot.md) |
| QQ Official Bot           | ✅      | Connects to the QQ Open Platform bot API                                                          | [Tutorial](https://langbot.app/docs/en/usage/platforms/qq/official_webhook.md)                                                                                                                                                                         |

> idea:
>
> **Don't want to deal with public IPs and domain setup?** Platforms like Slack, LINE, WeCom, and Lark require webhook callback URLs, meaning you need a public server, domain, and HTTPS certificate. [LangBot Cloud](https://space.langbot.app/cloud) comes with built-in domain resolution and HTTPS — sign up and start using it right away, no network configuration needed.

---

# Lucky Lilla Desktop

Source: https://langbot.app/docs/en/usage/platforms/satori/llonebot

Connect LangBot via the Satori protocol (LLOneBot) to run an AI bot across supported messaging clients.

Connected via the Satori protocol, you need to select `Satori` as the adapter.

# LuckyLillia

- [LuckyLillia](https://github.com/LLOneBot/LuckyLilliaBot) Install the client to use the Satori protocol

LuckyLillia installation tutorial: <https://luckylillia.com/guide/choice_install>

![Image 1](https://langbot.app/docs/images/zh/deploy/bots/satori/llbot_local_setting.png)

Make sure the IP address in the address field is the address of the host running LangBot (use `127.0.0.1` if running on the same network). The default port `5600` can be changed as needed. Setting a token is recommended.

> ![Image 2](https://langbot.app/docs/images/zh/deploy/bots/satori/llbot_open_setting.png)
>
> This image shows the public network configuration. Make sure the IP address is the address of the host running LangBot. In this case, you need to expose the corresponding LangBot port.

## LangBot Integration

Next, open the LangBot configuration page.

Click on Bots, then click Add.

Select `Satori` for `Platform/Adapter`.

![Image 3](https://langbot.app/docs/images/zh/deploy/bots/satori/llone_langbot_build.png)

> If you use the default configuration (local network), you don't even need to modify any parameters.

After creation, you can still adjust the parameters.

![Image 4](https://langbot.app/docs/images/zh/deploy/bots/satori/llone_langbot_setting.png)

Make sure you have enabled this adapter.

![Image 5](https://langbot.app/docs/images/zh/deploy/bots/satori/satori_platform_open.png)

> info:
>
> Note: If you encounter network connectivity issues between multiple Docker containers, please refer to [Network Configuration Details](https://langbot.app/docs/en/workshop/network-details.md).

---

# Slack

Source: https://langbot.app/docs/en/usage/platforms/slack

Build a Slack AI bot with LangBot. Connect GPT, Claude, Dify and more to your Slack workspace.

## Create Bot

Go to the [Slack App Platform](https://api.slack.com/apps).

![Slack Platform](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_01.jpg)

Click `Create New App` in the top right corner, select `from a manifest`, select the workspace where you want to deploy the bot, select next, and choose to create the bot.

Enter the `Basic Information` option on the left, record the `signing_secret`.

Enter `OAuth & Permissions` on the left, scroll down to `Scopes`, add the following bot permissions:

![Bot Permissions 1](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_02.jpg)

![Bot Permissions 2](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_03.jpg)

After adding the above permissions, click `Install to your workspace`, record the token starting with `xoxb-xxxxx`.\


**Note:**
**If you didn't add all permissions at once, you'll need to reinstall the App later.**\


Enter the `App Home` tab on the left, scroll to the bottom where you'll find `Message Tab`, turn it on and check
`Allow users to send Slash commands and messages from the messages tab`.

## Connect to LangBot

Enter `Event Subscriptions` on the left, turn on the switch, click `Subscribe to bot events`,
add the following permissions:
![Event Permissions](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_04.jpg)

After completing all the above operations, open the LangBot Webui configuration page, add a new bot

![Event Permissions](https://langbot.app/docs/images/zh/deploy/bots/slack/connect_to_langbot.png)

## Start Bot

> info:
>
> Since Slack officially requires https, please configure reverse proxy first according to the documentation [Configure HTTP Reverse Proxy and SSL](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md).

After filling in the Slack configuration items, **start LangBot**.
Enable and open the Slack bot configuration page on the LangBot homepage, copy the WebHook URL from it, then in the `Request URL` of the Event Subscriptions you just configured, fill in the WebHook URL.

After filling in all the above configuration items, click save link. If it shows a green **Verified**, it means the deployment is successful.
Otherwise, check if the above configuration items are filled in correctly.

## Effect Demonstration

![Effect Demonstration](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_05.jpg)

---

# Telegram

Source: https://langbot.app/docs/en/usage/platforms/telegram

Build a Telegram AI bot with LangBot. Connect GPT, Claude, Gemini, DeepSeek and Dify to Telegram chats and groups.

## Create Bot

Go to the [Telegram Bot Creation Page](https://t.me/botfather), follow the prompts, and create a bot.

![Telegram Bot Creation](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_01.png)

![Telegram Bot Creation](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_02.png)

After creation, BotFather will return an API Token, please keep it safe. Next, turn off `Privacy Mode` to use it in group chats.

![Telegram Bot API Token](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_03.png)

## Connect to LangBot

Open the LangBot Webui page, create a new bot

![Connect to LangBot](https://langbot.app/docs/images/zh/deploy/bots/telegram/connect_to_langbot.png)

After filling in, start LangBot. If configured successfully, the log will show `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: telegram`, keep LangBot running.

## Use Bot

Now you can use the bot normally in groups or private messages.

![Telegram Bot Usage](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_04.png)

![Telegram Bot Usage](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_05.png)

---

# Web Page Bot

Source: https://langbot.app/docs/en/usage/platforms/webpage

Embed a LangBot AI chatbot on your web page. Add an LLM-powered chat widget to any website.

Embed a LangBot chat widget into any website with a single script tag.

## Create Bot

Open LangBot WebUI, go to **Bots > Create Bot**, enter a bot name, and select `Web Page Bot` as the platform/adapter.

![Create Web Page Bot](https://langbot.app/docs/images/zh/deploy/bots/web_page/webpage_01.png)

## Configuration

| Option               | Description                                                                                                                 |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Component Title      | Title displayed at the top of the chat widget, defaults to LangBot                                                          |
| Bubble Icon          | Icon displayed on the floating chat bubble                                                                                  |
| Component Language   | Display language for the chat widget (Simplified Chinese, English, etc.)                                                    |
| Turnstile Site Key   | Cloudflare Turnstile site key for anti-abuse protection. Leave empty to disable                                             |
| Turnstile Secret Key | Cloudflare Turnstile secret key, obtained together with the site key from Cloudflare console. Required when site key is set |

## Get Embed Code

After creating and saving the bot, an auto-generated `<script>` tag will appear in the **Embed Code** section of the bot configuration page.

![Embed Code](https://langbot.app/docs/images/zh/deploy/bots/web_page/webpage_02.png)

Copy this code and paste it into your website HTML (typically before `</body>`). A chat bubble will appear at the bottom-right corner of the page, allowing visitors to chat with your bot.

```html
<script data-title="LangBot" src="http://localhost:5300/api/v1/embed/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"></script>
```

> warning:
>
> The embed code URL defaults to `localhost`. If your LangBot is deployed on a server, replace `localhost:5300` with your actual address.

## Anti-Abuse (Optional)

To protect against abuse, you can enable Cloudflare Turnstile:

1. Go to [Cloudflare Turnstile](https://dash.cloudflare.com/) > Add Site
2. Get the **Site Key** and **Secret Key**
3. Fill them into the corresponding fields in the LangBot Web Page Bot configuration
4. Save to take effect

## Local Preview / Demo

Want to try the embed widget before wiring it into your own site? The LangBot
main repo ships a self-contained single-file demo page `index.html` under
[`examples/web-page-bot/`](https://github.com/langbot-app/LangBot/tree/master/examples/web-page-bot):
open it in a browser, fill in your LangBot address and Page Bot UUID, and it
loads the live embed widget so you can chat with the bot just like a site
visitor — and generates the exact `<script>` snippet to paste into your own site.

```bash
# Serve the repo root statically, then open it in a browser
python3 -m http.server 8930
# Visit http://localhost:8930/examples/web-page-bot/
```

## Start Using

After adding the embed code to your website, visitors can click the chat bubble at the bottom-right corner to start chatting with your bot.

---

# Personal WeChat (OpenClaw)

Source: https://langbot.app/docs/en/usage/platforms/wechat/weixin

Build a personal WeChat AI bot with LangBot. Connect large language models to your WeChat account.

## Introduction

[OpenClaw](https://github.com/dingxiang-me/OpenClaw-Wechat) is an open-source AI Agent framework. Through the OpenClaw WeChat adapter, you can connect LangBot to your personal WeChat account, supporting single chat, streaming output, whitelist control, and more.

## Quick Scan Login (Recommended)

LangBot supports one-click scan login for WeChat, automatically filling in credentials — no manual token entry needed.

> warning:
>
> Please make sure your mobile WeChat version is **8.0.69** or above, otherwise it may not work properly.

1. Open LangBot WebUI, go to **Bots > Create Bot**
2. Enter a bot name, select `Personal WeChat Bot` as the platform/adapter
3. In the **Scan Login** section that appears, click the **Start** button

![Select Scan Login](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_scan_login.png)

4. Scan the QR code with WeChat. On your phone, you'll see "Connect new OpenClaw to WeChat", tap **Continue**

![Scan and Connect](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_scan_connect.png)

5. After authorization, the token and account ID will be **auto-filled** in the form

![Config Auto Fill](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_config_auto_fill.png)

6. Click **Submit** to complete

> warning:
>
> If connection fails, please confirm your WeChat version is 8.0.69 or above.

### Confirm Successful Login

After scanning successfully, your phone will enter the ClawBot chat page on WeChat.

![WeChat ClawBot Chat Page](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_05.jpg)

At the same time, the LangBot logs will show a successful connection message, and the token and account fields on the configuration page will be automatically updated, indicating a successful login.

![Log Information](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_06.png)
![Configuration Page](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_07.png)

## Start Using

Once logged in, send messages to the ClawBot chat page you just entered using the scanned account, and LangBot will automatically reply.

---

# WeCom

Source: https://langbot.app/docs/en/usage/platforms/wecom/wecom

Connect WeCom (Enterprise WeChat) to LangBot. Deploy an LLM AI bot for your enterprise messaging.

Deploy the WeCom (Enterprise WeChat) bot to integrate with LangBot.

> \- This integration is for internal enterprise applications, used within your organization. If external customer support is needed, please refer to the \[WeCom Customer Service integration solution]\(wecomcs).:
>
> - The WeCom callback address requires a public IP and domain name. We recommend you first follow [Configure HTTP Reverse Proxy](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md) to configure the LangBot callback address.

> idea:
>
> **No public server?** [LangBot Cloud](https://space.langbot.app/cloud) includes built-in domain and HTTPS — get WeCom working out of the box.

## Record Corporate ID

Open the [WeCom Admin Portal](https://work.weixin.qq.com/), click `My Enterprise`, and record the `Corporate ID` at the bottom.

![Corp ID](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/03-corp-id.png)

## Create Bot

Click `App Management`, then `Build Your Own`, and click `Create App`.

![App Management](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/01-wecom-apps.png)

Fill in the basic information for the bot:

![Create Application](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/02-create-app.png)

View and record the bot's secret:

![Bot Secret](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/04-bot-secret.png)

Get it from the WeCom client as prompted.

## Enable Contact Sync Permission

> \- This configuration is required for LangBot to support mass messaging. The related code can be found at libs/wecom\_api/api.py.:
>
> - This feature has not been implemented yet as LangBot is still under development.
> - This field can be filled with any random characters, but **cannot be empty**.

Click `Security and Management`, then `Management Tools`, `Contact Sync`; configure the trusted IP by adding the IP address of the server where LangBot is deployed.

Click `View Secret` and record it - this is the contacts\_secret (Contact Sync Secret).

![Contact Sync Secret](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/08-contact-secret.png)

## Create Bot on LangBot

On the LangBot bot page, click `Create Bot`, enter a name, select `WeCom`, and fill in the Corporate ID, Bot Secret, and Contact Sync Secret.

![Create WeCom Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/05-fill-in-corpid-secret.png)

Click submit to enter the bot edit page, then click enable. At this point you'll see the Webhook callback address—copy it:

![Webhook Callback Address](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/06-webhook-callback-address.png)

## Set Callback Address

Return to the WeCom bot admin page, click `Receive Messages`, `Set API Reception`, and paste LangBot's Webhook callback address into the `URL` field:

![Set API Receiver](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/07-set-api-receiver.png)

Click to randomly generate the Token and EncodingAESKey, and record them. **Keep this page open.** Go back to the LangBot WeCom bot configuration page, enter the Token and EncodingAESKey, and click Save.

![Save WeCom Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/09-save-wecom-bot.png)

Return to the **page where you just filled in the Webhook callback address**, and click Save to complete the configuration. If you see **request URL failed**, please carefully double-check your configuration.

## Configure Corporate Trusted IP

Go back to this application's admin page, find `Enterprise Trusted IP` at the bottom, and add the IP address of your LangBot deployment server.

![Corp Trusted IP](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/10-corp-trusted-ip.png)

Click Save.

## FAQ

Q: Can't find the bot chat in WeCom?
A: Go to the app's detail page in WeCom admin, click `Features` > `Send Message` > `Send Message`, choose your own account, send a message, and you will see the bot in your chat window.

---

# WeCom Intelligent Bot

Source: https://langbot.app/docs/en/usage/platforms/wecom/wecombot

Build a WeCom (Enterprise WeChat) AI bot with LangBot to bring LLM chat into your organization.

## One-Click Setup (Recommended)

LangBot supports one-click WeCom bot creation with automatic BotId and Secret filling — no manual copy-paste needed.

1. Open LangBot WebUI, go to **Bots > Create Bot**
2. Enter a bot name, select `WeCom Intelligent Bot` as the platform/adapter
3. In the **One-Click Create Bot** section that appears, click the **Start** button

![One-Click Create Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_oneclick.png)

4. Scan the QR code with WeCom. On your phone, tap **One-Click Create Intelligent Bot**

![Phone One-Click Create](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_scan_create.png)

5. After authorization, BotId and Secret will be **auto-filled** in the form
6. **Manually fill in the bot name** — it must match the bot name in WeCom

![Fill Bot Name](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_fill_name.png)

7. Click **Submit** to complete

> warning:
>
> WeCom Intelligent Bot **cannot use existing bots** for one-click setup — only new bots. To use an existing bot, refer to the manual configuration below.

***

## Manual Configuration

### Creating a Bot

First, log in to the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#/).

![Homepage](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_1.png)

Click `Security And Management` in the left sidebar, then click `Intelligent Bot` under `Management Tool`.

As shown:

![Intelligent Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_2.png)

Click `Create Bot` and select `Manual Creation`, scroll to the bottom of the page, click `Create via API Mode`, and enter the page:

![Create via API Mode](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_3.png)

### Long Connection Configuration

#### Enable Long Connection API Mode

In the WeCom Admin Console, go to the Intelligent Bot configuration page, enable "API Mode" and select "Long Connection":

![Long Connection Mode](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_9.png)

#### Obtaining Credentials

After enabling the Long Connection API mode, you need to obtain the following credentials to establish the connection:

| Credential | Description                                                            |
| ---------- | ---------------------------------------------------------------------- |
| BotID      | The unique identifier of the intelligent bot, used to identify the bot |
| Secret     | The dedicated key for long connections, used for identity verification |

> warning:
>
> Note:
>
> - The Secret is a dedicated key for long connections, which is different from the Token/EncodingAESKey used in the callback URL mode
> - Please keep the Secret safe and avoid leaking it
> - Mode switching impact: API mode can only use one method (long connection or callback URL). Switching to "Callback URL" mode will invalidate existing long connections; conversely, switching from "Callback URL" to "Long Connection" mode will make the original callback URL no longer effective

#### Configuring the Bot

Start the LangBot main program, select the adapter `WeCom Intelligent Bot`, and fill in the configuration items.
Enter the BotID, Secret, and bot name from the long connection into the fields, click save and enable.

> The bot name must match the name of the newly created bot, otherwise the bot will not respond in group chats.

![Long Connection Configuration](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_10.png)

### URL Callback Configuration

Click to randomly generate Token and EncodingAESKey, then fill in the basic bot information above. **Pay attention to setting the visibility scope**.

![Parameter Retrieval](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_11.png)

Click `My Company` in the left sidebar and save the Company ID at the bottom.

#### Configuring Callback URL

Start the LangBot main program, select the adapter `WeCom Intelligent Bot`, and fill in the configuration items.\
Among them, the token is Token, the Encoding-AESKey is EncodingAESKey, and the Bot ID can be filled in as xxx (or filled in randomly, it will be changed later). After filling in, click\
`Save`, and `Enable` the robot.

![WeCom Intelligent Bot Adapter](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_4.png)

On the LangBot homepage, enable and select the corresponding bot, click to enter the configuration page, copy the Webhook callback address

> info:
>
> We recommend that you first refer to [Configure HTTP Reverse Proxy](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md) to configure the LangBot callback address.

![Webhook Callback Address](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_8.png)

Return to the WeCom robot configuration page and fill the copied webhook address into `URL Callback`. If the creation is successful, it will jump to the details page. If the message `Request URL Failed` appears, please double-check whether the above steps have been completed one by one.

Details page after successful creation:\
![Creation Successful](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_5.png)

Copy the `Bot ID` and bot name from the WeCom robot details page, return to the LangBot management page, change the Bot ID of the deployed intelligent robot to the copied ID, fill in the bot name, and restart the robot.

### Enable Streaming

A streaming toggle has been added for locally deployed models or models that do not support streaming.

![Streaming Toggle](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_12.png)

### Start Using

Enter WeCom, click `➕`, as shown:

![Add Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_6.png)

Click `Company-Created`, select the created bot, and enter the chat interface.

Similarly, if you want to invite the bot to a group chat, click the add member button in the group chat and add the bot from there.

### Effect Images

![Effect Image 1](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_7.png)

---

# WeCom Customer Service

Source: https://langbot.app/docs/en/usage/platforms/wecom/wecomcs

Set up WeCom Customer Service with LangBot to power AI-driven support conversations.

> This article details the process of deploying LangBot to a WeCom customer service account, which allows conversations between the customer service account and regular WeChat. If you only need to use it within WeCom, please refer to \[WeCom Internal Application Implementation]\(wecom).:
>
> **Deploying a WeCom customer service account requires enterprise qualifications**. Please check the [WeCom Customer Service Integration Guide](https://developer.work.weixin.qq.com/document/path/94638) and provide the corresponding enterprise qualification certificates according to this document.

## Effect Demonstration

![Effect Demonstration](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/wecomcs_01.jpg)

## Deploy WeCom Customer Service

#### Configure WeCom Customer Service Page

Open the [WeCom Customer Service Admin](https://kf.weixin.qq.com/kf), log in, click on `Enterprise Information`, and obtain the `Enterprise ID`.

![Home Page](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/wecomcs_03.png)

Save the Enterprise ID, then click on `Developer Settings`, click on `Start Using`, and randomly generate a Token and EncodingAESKey. Fill these three items into the LangBot configuration page. The Secret can be filled in arbitrarily, as shown below:

![connect](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/connect_to_langbot.png)

Click Submit on the LangBot configuration page to enable the robot, copy the Webhook callback address, and fill it into the URL in the WeCom Customer Service admin backend (remember to change it to your own IP or domain name), then click Save. If it saves successfully, it means the connection is working.

> idea:
>
> **Domain setup too complicated?** [LangBot Cloud](https://space.langbot.app/cloud) includes built-in domain and HTTPS — no configuration needed.

Copy the Secret from the page, then open the newly created LangBot WeCom Customer Service robot, fill in the new Secret, and restart.

Go back to the WeCom Customer Service configuration page, click on Customer Service Accounts, create a customer service account, and you can start using it.

---

# WeChat Official Account

Source: https://langbot.app/docs/en/usage/platforms/wxoa

Build a WeChat Official Account AI bot with LangBot. Connect LLMs to your WeChat public account.

Deploy WeChat Official Account bot to connect with LangBot.

## LangBot WeChat Official Account Integration Modes

Currently, LangBot provides two ways to integrate with WeChat Official Accounts:

1. **Traditional Message Exchange Mode**
   - Official accounts require requests to be processed within **15 seconds**, AI-generated content that exceeds this timeout cannot be sent.
   - When AI content generation timeout occurs, LangBot will print request timeout information in the console.

2. **"Send Any Text to Get Reply" Mode**
   - This method can break the **15 second** limit, but **very long text** may not be sent successfully.
   - When using this method, after sending a message to the official account, it will reply "AI is thinking, please send any content to get the answer". At this point, you need to send any content to get the answer.

For more complex functionality, please contact the **LangBot team** for customized support.

## Create Bot

Enter the [WeChat Official Account Platform](https://mp.weixin.qq.com/), if you already have an official account, scan the QR code to log in and enter the console.
If you haven't registered an official account before, click Register Now, select `Official Account`, fill in the information in sequence, and enter the console. The console looks like this:
![Console Page](https://langbot.app/docs/images/zh/deploy/bots/wxoa/wxoa1.png)

## Set Callback Address

> idea:
>
> **WeChat Official Account requires a public domain and HTTPS.** If you don't have a server, [LangBot Cloud](https://space.langbot.app/cloud) includes built-in domain resolution — sign up and get started immediately.

### Get Configuration Items

Click `Settings and Development`, `Development Interface Management`, and you'll see a page like this:
![Set Development Items](https://langbot.app/docs/images/zh/deploy/bots/wxoa/wxoa2.png)

Record the `Developer ID (AppID)`, `Developer Password (AppSecret)`, and add the server where LangBot is deployed to the `IP Whitelist`.

### Set Up Reverse Proxy for LangBot

Since WeChat Official Accounts only support http (port 80) and https (port 443), please follow the documentation [Configure HTTP Reverse Proxy and SSL](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md) for configuration.

### Save Callback Address

Click Set Server Configuration, enter `Token`, `EncodingAESKey`, and change the message encryption/decryption method to `Safe Mode`.

At this point, open the LangBot Webui page, create a new bot, and fill in the four configuration items obtained (AppID, AppSecret, token, EncodingAESKey)

![Set Development Items](https://langbot.app/docs/images/zh/deploy/bots/wxoa/connect_to_langbot.png)

In the configuration items, the `Mode` option is the selected integration mode, where the default is `drop`. `drop` is the traditional message exchange mode, and `passive` is the "send any text to get reply" mode.

The `LoadingMessage` option is the loading message, which can be changed to other content, and is only valid when the mode is `passive`. Set `enable` to `true`.

After filling in successfully, on the LangBot homepage, enable and select the corresponding bot, click to enter the configuration page, copy the Webhook callback address, return to the WeChat Official Account bot configuration page, and fill it into `URL`. For example, if the URL is filled as `https://your_domain_name/bots/xxxxx`, where `your_domain_name` is the domain name filled in Caddy. Click Save. If it can be saved successfully, it means the deployment is successful. If you see **System error, please try again later**, please recheck whether the above configuration content is filled in correctly.

---

# Sandbox Configuration

Source: https://langbot.app/docs/en/usage/sandbox/config

Configure LangBot Box Runtime with Docker, nsjail, E2B, or the explicitly enabled non-isolated Host backend.

Box settings are owned by the LangBot main process; Box Runtime performs the actual execution. For most deployments, you only need to choose a backend, set the workspace directory, and pick a security profile. Docker, nsjail, and E2B provide sandbox environments; the Host backend runs commands directly on the Box Runtime host.

> info:
>
> All `box.*` settings on this page live in `data/config.yaml`. See [System Environment Settings](https://langbot.app/docs/en/deploy/settings.md) for the file's location and how it's loaded.

## Recommended Configuration

```yaml
box:
  enabled: true
  backend: 'local'        # auto-pick from Docker / Nsjail
  local:
    profile: 'default'
    host_root: './data/box'
    skills_root: 'skills'
  docker:
    cpu_limit_enabled: true
```

- `enabled`: master switch. When `false`, all Box-dependent features are disabled (sandbox tools, skill add/edit, stdio MCP hosting).
- `backend`: see "Backend Selection" below.
- `local.profile`: security profile — controls network, mounts, and resource limits.
- `local.host_root`: host workspace directory, mapped to `/workspace` inside the sandbox.
- `local.skills_root`: skill package directory; relative paths resolve under `host_root` (defaults to `host_root/skills`).
- `docker.cpu_limit_enabled`: whether Docker sandbox containers get a CPU limit; set to `false` to omit `docker run --cpus` while keeping memory and PID limits.

> info:
>
> Skills are loaded only from the Box-managed skill store. When Box Runtime or the backend is unavailable, the skill list is empty and create/edit/`register_skill` are disabled — there's no fallback to `data/skills/`.

## Backend Selection

Box can run in **local containers**, in a **cloud sandbox**, or as a **process on the Box Runtime host**. `box.backend` picks which:

| `backend`         | Where it runs    | Behavior                                                                               |
| ----------------- | ---------------- | -------------------------------------------------------------------------------------- |
| `local` (default) | Local containers | Auto-pick from Docker / Nsjail (Docker preferred)                                      |
| `docker`          | Local containers | Force Docker; requires the Docker daemon                                               |
| `nsjail`          | Local containers | Force Nsjail (Linux only); no custom image support                                     |
| `e2b`             | Cloud            | Use [E2B](https://e2b.dev) cloud sandbox; requires API key                             |
| `host`            | Box Runtime host | Start local processes with the Box Runtime user's permissions; requires POSIX and `sh` |

`local` is shorthand for "auto-pick", not a fourth backend sitting next to `docker`/`nsjail`. It only tries Docker and Nsjail and **never auto-selects `host`**. Local backends use workspace settings from `box.local.*`; the cloud backend uses `box.e2b.*`.

> warning:
>
> `host` is **not a sandbox**. Commands have the Box Runtime user's host permissions, with no filesystem, process, network, namespace, cgroup, rootfs, or image isolation. Read-only mounts and hard disk quotas are not guaranteed. Use it only for single-user local development with trusted input; never use it for public services, shared hosts, or untrusted code.

> info:
>
> `backend` is a hard selection. Setting `docker` and finding Docker unavailable does **not** fall back to Nsjail or E2B — only `local` auto-fans-out.
>
> `BOX__BACKEND` environment variable overrides `box.backend` (highest priority).

## Security Profiles

`box.local.profile` controls network, mounts, and resource limits for the Docker / Nsjail local sandbox backends:

| Profile            | Network       | Mounts     | Resources      | When to use                           |
| ------------------ | ------------- | ---------- | -------------- | ------------------------------------- |
| `default`          | Off           | Read-write | Default limits | Default choice                        |
| `offline_readonly` | Off           | Read-only  | Stricter       | Reading untrusted files               |
| `network_basic`    | Basic network | Read-write | Default limits | API access or dependency install      |
| `network_extended` | Full network  | Read-write | Relaxed        | Development, debugging, complex tasks |

Prefer least privilege: skip the network unless you need it (`default` / `offline_readonly`); only add necessary directories to `allowed_mount_roots`.

> info:
>
> The Host backend does not enforce these isolation policies. A configured profile, CPU / memory / PID limit, read-only rootfs, or disabled network does not create a sandbox boundary around host processes.

## Local Workspace Configuration (box.local.\*)

Docker, Nsjail, and Host share workspace path settings. Isolation and resource settings only take effect when the selected sandbox backend can enforce them:

| Setting                     | Default       | Notes                                                                                          |
| --------------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| `local.profile`             | `default`     | Docker / Nsjail security profile; Host provides no matching isolation                          |
| `local.image`               | empty         | Docker-only custom image; empty = use profile default                                          |
| `local.host_root`           | `./data/box`  | Host workspace base, mapped to `/workspace` inside the sandbox                                 |
| `local.default_workspace`   | empty         | Default workspace name; empty = `<host_root>/default`                                          |
| `local.skills_root`         | `skills`      | Skill package directory; relative paths resolve under `host_root`                              |
| `local.allowed_mount_roots` | `[host_root]` | Allowlist of host directories the Agent can mount                                              |
| `local.workspace_quota_mb`  | `null`        | Workspace disk quota (MB); `null` = use profile default; Host provides no hard quota guarantee |
| `default_memory_mb`         | `1536`        | Memory limit for each MCP stdio process (MB); Host cannot enforce it through cgroups           |

## Host Backend (Trusted Local Development)

Host is the lowest-dependency local option and does not require Docker or Nsjail. It must be selected explicitly:

```yaml
box:
  enabled: true
  backend: 'host'
  local:
    host_root: './data/box'
    skills_root: 'skills'
```

The WebUI, Agent tools, and calling conventions stay the same: session scopes, `exec/read/write/edit/glob/grep`, Skills, and stdio MCP all use the existing Box APIs. Only the execution layer changes:

- `/workspace`, `workdir`, and Skill mount paths are translated to real paths on the Box Runtime host.
- Child processes inherit only a minimal path, locale, and terminal environment plus variables explicitly supplied by the request. LangBot / Box control secrets are not inherited automatically. This reduces accidental leakage but does not provide filesystem isolation.
- `exec` and managed processes start in separate process groups. Timeouts, cancellation, process stop, session deletion, and Runtime shutdown terminate the corresponding process trees.
- Idle cleanup, managed-process keepalive, and `persistent` rules match the other backends.
- Status responses include `unsafe_direct_execution: true` so operators can detect the lack of sandbox isolation.

> info:
>
> Host means the environment **where Box Runtime runs**. With LangBot's local stdio-managed Box Runtime, that is the current machine. If Box Runtime itself runs in a container, commands run directly in that container; Host does not automatically break through to the physical host.

The Host MVP supports POSIX systems with `sh` (Linux / macOS). Use WSL on Windows; a native Windows process backend is not yet supported.

When Host is used through an external WebSocket Box Runtime, set the same strong random `LANGBOT_BOX_CONTROL_TOKEN` on both LangBot and Box Runtime. The locally managed stdio Runtime needs no extra token configuration. Cloud environments with managed-sandbox admission still validate isolation capabilities and the required backend; Host does not bypass those checks.

## Box Sandbox Memory Configuration

`box.default_memory_mb` sets the nsjail cgroup memory cap for every stdio-mode MCP server process.

The Host backend has no cgroup memory isolation, so this value cannot limit MCP processes running on Host.

| Setting                 | Notes                       | Default |
| ----------------------- | --------------------------- | ------- |
| `box.default_memory_mb` | MCP process memory cap (MB) | 1536    |

Can be set in config.yaml or via the `BOX__DEFAULT_MEMORY_MB` environment variable.

**When to adjust:**

- Node.js MCP servers (launched via npx/bunx): V8 + WebAssembly module initialisation needs significant memory; keep at ≥ 1536 MB
- Python MCP servers (launched via uvx): 512 MB is usually enough, but the default is fine too
- When memory is exhausted, the process is forcibly killed (return\_code=137), logged as "Box managed process exited unexpectedly"

**Per-server override:** Set `box.memory_mb` in the individual MCP server config to override the global default.

## Docker Backend Configuration (box.docker.\*)

| Setting                    | Default | Notes                                                                                                                    |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `docker.cpu_limit_enabled` | `true`  | Docker backend only. When `false`, sandbox containers start without `--cpus`; `--memory` and `--pids-limit` still apply. |

## Cloud Backend Configuration (box.e2b.\*)

Configure after setting `backend: 'e2b'`:

| Setting        | Default | Notes                                                       |
| -------------- | ------- | ----------------------------------------------------------- |
| `e2b.api_key`  | empty   | E2B API key; can also be set via `E2B_API_KEY`              |
| `e2b.api_url`  | empty   | Self-hosted E2B endpoint; can also be set via `E2B_API_URL` |
| `e2b.template` | empty   | Default E2B template ID                                     |

E2B doesn't need Docker or Nsjail on the host — every execution goes through the remote sandbox.

## Docker Compose Deployment

In Docker Compose, sandbox settings live on the `langbot` service. LangBot forwards them to `langbot_box` via INIT RPC at startup.

```yaml
services:
  langbot_box:
    image: rockchin/langbot:latest
    container_name: langbot_box
    profiles: ["box", "all"]
    volumes:
      - ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - /var/run/docker.sock:/var/run/docker.sock
    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]

  langbot:
    image: rockchin/langbot:latest
    volumes:
      - ./data:/app/data
    environment:
      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__LOCAL__SKILLS_ROOT=skills
      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__DOCKER__CPU_LIMIT_ENABLED=${LANGBOT_BOX_DOCKER_CPU_LIMIT_ENABLED:-true}
```

> warning:
>
> `langbot_box` needs the Docker daemon. Only mount `docker.sock` in trusted environments, and keep the Box root path identical on the host and inside the `langbot_box` container.

To point LangBot at an externally-managed Box Runtime (e.g. a remote host), use `box.runtime.endpoint`:

```yaml
box:
  runtime:
    endpoint: 'ws://192.168.1.10:5410'
```

## Environment Variables

| Environment variable              | Maps to                                          |
| --------------------------------- | ------------------------------------------------ |
| `BOX__ENABLED`                    | `box.enabled`                                    |
| `BOX__BACKEND`                    | `box.backend`                                    |
| `BOX__LOCAL__PROFILE`             | `box.local.profile`                              |
| `BOX__LOCAL__IMAGE`               | `box.local.image`                                |
| `BOX__LOCAL__HOST_ROOT`           | `box.local.host_root`                            |
| `BOX__LOCAL__DEFAULT_WORKSPACE`   | `box.local.default_workspace`                    |
| `BOX__LOCAL__SKILLS_ROOT`         | `box.local.skills_root`                          |
| `BOX__LOCAL__ALLOWED_MOUNT_ROOTS` | `box.local.allowed_mount_roots`, comma-separated |
| `BOX__LOCAL__WORKSPACE_QUOTA_MB`  | `box.local.workspace_quota_mb`                   |
| `BOX__DEFAULT_MEMORY_MB`          | `box.default_memory_mb`                          |
| `BOX__DOCKER__CPU_LIMIT_ENABLED`  | `box.docker.cpu_limit_enabled`                   |
| `BOX__E2B__API_KEY`               | `box.e2b.api_key`                                |
| `BOX__E2B__API_URL`               | `box.e2b.api_url`                                |
| `BOX__E2B__TEMPLATE`              | `box.e2b.template`                               |

> info:
>
> Don't set `BOX__*` or `LANGBOT_BOX_*` on the `langbot_box` service — Box Runtime doesn't read them directly. Its configuration arrives over INIT RPC from LangBot.

---

# Sandbox

Source: https://langbot.app/docs/en/usage/sandbox/readme

LangBot Box Runtime gives the built-in Agent command and file tools with a choice of sandboxed or trusted-host backends.

Box Runtime gives the built-in Agent one execution interface for running commands, reading and writing files, and hosting long-lived processes. Everyday Agent use cases (data processing, file operations, running user code, hosting stdio MCP) all rely on it. Docker, nsjail, and E2B provide sandbox isolation; the explicitly selected Host backend is for trusted local development and provides no isolation.

Once Box is enabled, the built-in Agent automatically gains six tools — no need to wire each one into the pipeline.

## Built-in Tools

| Tool    | Purpose                               |
| ------- | ------------------------------------- |
| `exec`  | Run shell commands inside the sandbox |
| `read`  | Read workspace files                  |
| `write` | Create or overwrite files             |
| `edit`  | Modify files via string replacement   |
| `glob`  | Find files by glob pattern            |
| `grep`  | Search file contents by regex         |

`exec` runs in the selected Box backend; the other five operate directly on the workspace directory mapped to `/workspace`. With Host selected, commands also run directly on the Box Runtime host.

> info:
>
> These tools target the built-in Agent. When using external runners such as Dify, n8n, Langflow, or Coze, use that platform's own tool mechanism.

## Sandbox Scope

The pipeline's AI configuration lets you choose how the sandbox is shared across messages. The default "per chat" works for most cases.

| Scope              | Template                                          | Shared across                      |
| ------------------ | ------------------------------------------------- | ---------------------------------- |
| Global             | `{global}`                                        | All users share one sandbox        |
| Per chat (default) | `{launcher_type}_{launcher_id}`                   | Same group or DM shares one        |
| Per user           | `{launcher_type}_{launcher_id}_{sender_id}`       | Each member in a group is isolated |
| Per conversation   | `{launcher_type}_{launcher_id}_{conversation_id}` | Isolated by conversation           |
| Per message        | `{query_id}`                                      | Fully stateless                    |

> warning:
>
> Commands within the same scope share filesystem state. Choose "per message" for a separate workspace. Scope controls session reuse; it is not a security boundary. Host has no host-level isolation even when different scopes are used.

## Lifecycle

| Condition                                      | Behavior                              |
| ---------------------------------------------- | ------------------------------------- |
| Idle for more than 5 minutes                   | Cleaned up automatically              |
| Box-managed processes running (e.g. stdio MCP) | Kept alive until those processes exit |
| `persistent: true` configured                  | Never cleaned up automatically        |

These lifecycle rules also apply to Host. Cleanup terminates the session's managed process trees and removes its temporary session directory. A durable workspace mapped under `box.local.host_root` is not deleted as temporary state. Runtime shutdown and explicit session deletion also perform cleanup.

## Quick Start

Trusted local development on Linux / macOS can select Host without installing Docker:

1. **Edit `config.yaml`**:
   ```yaml
   box:
     enabled: true
     backend: 'host'
     local:
       host_root: './data/box'
   ```
2. **Start LangBot**: Box Runtime is enabled automatically
3. **In the pipeline**, select the built-in Agent plus a model that supports function calling

The Agent will then automatically receive the six tools. See [Sandbox Configuration](https://langbot.app/docs/en/usage/sandbox/config.md) for details.

> warning:
>
> Host executes commands directly with the LangBot / Box Runtime user's permissions and must only process trusted input. To execute untrusted code, set `backend` to `local` (auto-pick Docker / Nsjail), `docker`, `nsjail`, or `e2b`.

## Disabling Box

Set `box.enabled: false`. Everything that depends on the sandbox (built-in tools, Skill create/edit/activate, stdio MCP) is disabled together; MCP servers in http/sse mode are unaffected.

## Next Steps

- [Sandbox Configuration](https://langbot.app/docs/en/usage/sandbox/config.md) — backends, security profiles, mounts, environment variables
- [Runtimes & Extensions Compared](https://langbot.app/docs/en/usage/sandbox/runtime-relationships.md) — how the sandbox, Skills, MCP, and plugins divide responsibilities

---

# Runtimes and Extensions

Source: https://langbot.app/docs/en/usage/sandbox/runtime-relationships

Understand LangBot runtimes and extensions: how the Box Runtime, sandbox backends and MCP servers fit together.

LangBot ships four extension mechanisms in parallel — **plugins, MCP, Skills, and the sandbox** — and they are easy to confuse. This page sorts out what each one does and when to use it.

## One-line Summary

- **Box execution environment**: lets the Agent run commands and read/write files; isolation depends on the selected backend
- **Skills**: on-demand instruction packages that hand the Agent a specialized workflow when needed
- **MCP Server**: connects to external tool services
- **Plugin**: a long-running extension process that can ship its own config page, event listeners, and knowledge components

## Comparison

| Capability                | Provided by                                      | How the Agent sees it                                                       | When to use                                                                        |
| ------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Box execution environment | Box Runtime                                      | The six tools `exec/read/write/edit/glob/grep` are attached directly        | Agent needs to run code or read/write files                                        |
| Skills                    | Box Runtime skill store                          | After the Agent calls `activate`, instructions are injected via Tool Result | Hand the Agent a workflow, template, or script, triggered on demand                |
| MCP Server                | LangBot MCP Loader (stdio mode is hosted by Box) | Tools land directly in the Agent's tool list                                | Connect an existing MCP service                                                    |
| Plugin                    | Plugin Runtime                                   | Capabilities are exposed through the plugin system                          | Long-lived capability with a config page, event listeners, or knowledge components |

## Pipeline Binding

Skills, MCP Servers, and plugins are all **pipeline extensions**. After installing or creating them in the WebUI, the pipeline extension config still decides where they're enabled:

- Enable all extensions, or
- Bind only specific extensions

Skill binding decides **which skills the Agent can see** (it controls the `<available_skills>` list). The actual skill content is only injected after the Agent calls `activate`.

## Backends and Isolation Boundaries

The Box API, Agent tools, session scopes, lifecycle, Skills, and stdio MCP hosting work the same across backends, but their security properties differ. Docker, nsjail, and E2B provide their respective sandbox boundaries. Host uses processes on the Box Runtime host directly and is only for trusted local development. Selecting Host does not change the WebUI and does not give separate sessions host-level isolation.

## Troubleshooting Map

| Symptom                                     | Check first                                                                           |
| ------------------------------------------- | ------------------------------------------------------------------------------------- |
| Agent has no `exec/read/write` tools        | `box.enabled`, backend availability, and whether the pipeline uses the built-in Agent |
| Skill list is empty                         | Box Runtime status, `box.local.skills_root`, pipeline binding                         |
| stdio MCP fails to start                    | Box Runtime status, MCP command and environment variables, startup timeout            |
| Sandbox fails to start in Docker deployment | Whether `langbot_box` mounts `docker.sock`, and whether Box root paths match          |
| File read/write fails                       | `box.local.host_root`, `box.local.allowed_mount_roots`                                |
| Backend selection has no effect             | Confirm `BOX__BACKEND` is set on the `langbot` service, not on `langbot_box`          |
| Host backend is unavailable                 | Confirm the system is POSIX and `sh` is on `PATH`; use WSL on Windows                 |
| External Host Box connection is rejected    | Set the same `LANGBOT_BOX_CONTROL_TOKEN` on LangBot and Box Runtime                   |

> info:
>
> Sandbox built-in tools and Skills currently target the built-in Agent. External runners (Dify, n8n, Langflow, Coze, etc.) should use their own tools and execution model.

---

# Skills

Source: https://langbot.app/docs/en/usage/skills/readme

Use Skills in LangBot to load specialized know-how on demand, extending your AI Agent without bloating its context.

A Skill is an **on-demand instruction bundle**: when the user's request matches, the Agent calls the `activate` tool to pull the skill's instructions into context, then follows them. Skills that aren't activated don't consume context.

Use Skills to give the Agent a **specialized workflow, template, or script** — "analyze a Python project", "fill a PDF form", "code review" — instead of stuffing every prompt into the System Prompt.

## How Skills Compare to Plugins and MCP

| What you want to do                                             | Use this   |
| --------------------------------------------------------------- | ---------- |
| A workflow triggered on demand (optional scripts and templates) | Skill      |
| Connect an existing MCP tool service                            | MCP Server |
| Long-lived capability with config page, events, knowledge base  | Plugin     |

See [Runtimes and Extensions](https://langbot.app/docs/en/usage/sandbox/runtime-relationships.md) for the full picture.

## Installing Skills

> info:
>
> Skills require the sandbox. `box.enabled` must be `true` and at least one backend (Docker / Nsjail / E2B) must be available — otherwise you can't install, activate, or edit skills. See [Sandbox Configuration](https://langbot.app/docs/en/usage/sandbox/config.md).

### From LangBot Space (Preferred)

[LangBot Space](https://space.langbot.app) is the official LangBot marketplace, with a curated list of ready-to-use skills. In the WebUI Skills page, browse and install them with one click — no need to write a `SKILL.md` or prepare any resource files.

This covers most cases. For custom workflows, use the option below.

### Create Your Own

**WebUI** — create, upload a zip, or import from GitHub on the Skills page.

**Sandbox + `register_skill`**:

1. Prepare the directory and `SKILL.md` under the sandbox `/workspace`
2. Have the Agent call `register_skill(path="/workspace/my-skill")`

Both options write to the skill store managed by Box Runtime.

## Enabling in a Pipeline

Once a skill is installed, the pipeline extension config decides which skills the Agent can see:

- Enable "all skills", or
- Bind only specific skills

Binding only affects the `<available_skills>` list (what the Agent can choose from). The full instructions are always injected only after `activate` is called.

## Writing a SKILL.md

A skill is a directory plus a `SKILL.md`. The frontmatter holds metadata; the body is what the Agent receives after activation:

```markdown
---
name: code-reviewer
display_name: Code Review Assistant
description: Reviews code and gives improvement suggestions; triggered when the user mentions review, code review, or code improvement
---

## Steps

1. Use `read` to browse the relevant files
2. Check readability, potential bugs, and security issues
3. Provide improvement suggestions, sorted by priority
```

LangBot currently reads these three fields:

| Field          | Required                  | Notes                                                                          |
| -------------- | ------------------------- | ------------------------------------------------------------------------------ |
| `name`         | When creating/registering | Unique ID, 1–64 chars                                                          |
| `description`  | Strongly recommended      | The Agent uses this to decide when to activate — the more specific, the better |
| `display_name` | No                        | Shown in the UI                                                                |

`description` is the Agent's only signal for picking a skill. Make it concrete about **what it does, when it applies, and what trigger words to watch for**.

For the full spec see [agentskills.io](https://agentskills.io/home). Other fields (`license`, `metadata`, ...) can stay in the file for future compatibility but are not currently read.

**Skills with resources** place `scripts/`, `templates/`, etc. next to `SKILL.md`. After activation the Agent accesses them at `/workspace/.skills/{skill-name}/`.

### Tools the Agent Sees

| Tool             | Purpose                                                                              |
| ---------------- | ------------------------------------------------------------------------------------ |
| `activate`       | Called automatically by the Agent when it sees a match — pulls SKILL.md into context |
| `register_skill` | Registers a directory prepared in the sandbox as a new skill                         |

## Common Issues

| Symptom                        | What to check                                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Skill list is empty            | `box.enabled`, Box Runtime status, `box.local.skills_root`                                                               |
| Agent doesn't activate a skill | Whether `description` is specific, whether the pipeline has the skill bound, whether the model supports function calling |
| Files missing after activation | Files must live inside the Skill package; the path is `/workspace/.skills/{skill-name}/`                                 |
| `register_skill` errors        | The path must be under `/workspace`, and the directory or subdirectories within two levels must contain `SKILL.md`       |

> info:
>
> Skills currently target the built-in Agent and depend on function calling plus a sandbox backend. External runners (Dify, n8n, Langflow, Coze, etc.) should use their platform's equivalent mechanism.

---

# Integrating Models with 302 AI

Source: https://langbot.app/docs/en/workshop/302ai-integration

Open the WebUI page, and select [302 AI](https://share.302ai.cn/SuTG99) when adding a model.

![model](https://langbot.app/docs/images/zh/workshop/302ai-integration/model.png)

---

# Implementing a Message Platform Adapter

Source: https://langbot.app/docs/en/workshop/impl-platform-adapter

This article will use the `aiocqhttp` adapter as an example to explain how to implement a new message platform adapter for LangBot, in order to integrate new message platform protocols such as WhatsApp and Discord.

## Registration

```text
Add a new message platform adapter, for example: integrate WhatsApp, Discord, etc.

- Base class: `pkg.platform.adapter.MessageSourceAdapter`
- Decorator: `pkg.platform.adapter.adapter_class(name: str)`
- Reference implementation: `pkg.platform.sources/`
```

To implement a message platform adapter, we essentially need to implement a class that inherits from the `base class` and register it using the `decorator`. Finally, it will be available for users to select and use during runtime.

### Contributing to the Main Repository

Create a new file `aiocqhttp.py` in the `pkg/platform/sources/` directory:

```python
from .. import adapter

@adapter.adapter_class("aiocqhttp")
class AiocqhttpAdapter(adapter.MessageSourceAdapter):
    pass
```

Also import this module in `pkg/platform/manager.py` at line 40:

```python
        from .sources import nakuru, aiocqhttp, qqbotpy
```

Finally, write your own manifest file by referring to other adapters' manifest files.

## Event and Message Converters

The main work of a message platform adapter is to `receive events from the message platform protocol, convert them into LangBot's format`, pass them to the core components, and after LangBot's core components process them, pass the content that needs to be replied to the message platform adapter, which then `converts the content into the platform protocol format and sends it to the message platform`.

The following diagram shows the processing patterns for two scenarios: message platform protocol without SDK and with mature SDK. In the first case, we need to implement connection management and network format data conversion to LB message Python objects according to the message platform protocol documentation. In the second case, the message platform has a mature SDK, we only need to create connections according to the SDK documentation, register event listeners, and implement message converters.

![alt text](https://langbot.app/docs/images/zh/workshop/impl-platform-adapter/workshop_impl_platform_adapter_01.png)

In the `pkg.platform.sources.aiocqhttp` file, we can see not only `AiocqhttpAdapter`, but also `class AiocqhttpMessageConverter(adapter.MessageConverter):` and `class AiocqhttpEventConverter(adapter.EventConverter):`.

- `MessageConverter` is used for converting between LangBot messages and platform messages.
- `EventConverter` is used for converting between LangBot events and platform events.

TBC...

---

# MCP Ecosystem Details

Source: https://langbot.app/docs/en/workshop/mcp-details

The [MCP Protocol](https://modelcontextprotocol.io/) is a protocol that describes the interaction between applications and LLMs, and has been adopted by various products. LangBot can act as an MCP Client to connect to MCP Servers, providing extensive tools for LLMs to use during conversations with users.

## Finding MCP Servers

To use MCP tools in LangBot, you need to find and connect to existing MCP Servers.\
There are two types of MCP Servers in the market:

- Executable files implemented in Node or Python, communicating with LangBot through `stdio` (standard input/output)
- Web services based on HTTP protocol, communicating with LangBot through HTTP protocol

> \- You can check existing MCP Servers in the \[MCP Server List]\(https\://github.com/punkpeye/awesome-mcp-servers).:
>
> - For online hosted MCP Servers, you can find them at [Composio MCP](https://mcp.composio.dev/).
> - To write your own MCP Server, you can refer to the [MCP Protocol Documentation](https://modelcontextprotocol.io/quickstart/server) and [MCP Server Examples](https://modelcontextprotocol.io/examples).

## Configuring MCP Server

Please refer to the [System Settings Documentation](https://langbot.app/docs/en/deploy/settings.md)

After configuration, you can use the `!func` command in chat to view registered MCP tools. When chatting with models that support Function Calling, LangBot will automatically call MCP tools.

---

# Network Configuration Details

Source: https://langbot.app/docs/en/workshop/network-details

> Some messaging platforms (such as personal QQ accounts) require an independent protocol endpoint to process messages. If you are using such messaging platforms, please refer to the following network configuration.:
>
> At the same time, if your LangBot instance needs to connect to other services running in containers (such as Ollama), you can also refer to the following configuration, replacing `messaging platform` with `the service you want to connect to`.

LangBot and some messaging platforms can both be deployed using Docker. Below are network configuration details for four different scenarios.

> Table of Contents:
>
> \[\[toc]]

## Both LangBot and Messaging Platform Running in Docker Containers

If the messaging platform (NapCat/Lagrange) and LangBot are both started using Docker, you need to configure Docker's network connection.

Create a new network:

```bash
docker network create langbot-network
```

Add network configuration to the `docker-compose.yaml` file in the LangBot directory (add to the `services.langbot` field, and add the `langbot-network` network configuration under the `networks` field):

```yaml
services:
  langbot:
    ...
    networks:
      - langbot-network
    ...

networks:
  langbot-network:
    external: true
```

Then add the same network configuration to the messaging platform's `docker-compose.yaml` file (if started directly with docker run command, add `--network langbot-network` to the startup command). Then in the messaging platform configuration file, change the IP address in the WS reverse connection address to `langbot` (for example: `ws://langbot:2280/ws`).

Restart both containers.

## Only LangBot Running in Docker Container

When only LangBot is deployed using Docker, ports 2280 to 2290 are already mapped to outside the container by default. At this time, LangBot can only act as a WebSocket server, accepting connections from messaging platforms as clients.

Please set the messaging platform to ReverseWebSocket (called `reverse ws` or `WebSocket client`), with the port corresponding to the port enabled by LangBot's aiocqhttp adapter, connecting to local 127.0.0.1.

## Neither LangBot nor Messaging Platform Using Docker Deployment

Configure the messaging platform and LangBot settings according to the documentation, set both ports to the same unused port, and both connect to local 127.0.0.1.

## Only Messaging Platform Running in Docker Container (Not Recommended)

> warning:
>
> Only supports Linux, or other systems that support host mode docker networking.

Currently, LangBot's aiocqhttp adapter only supports reverse WebSocket connections. When the messaging platform runs in a Docker container while LangBot runs directly on the host machine, the messaging platform must act as a client connecting to LangBot. In this case, you can only set the messaging platform's network to `host` mode, and then set its WS connection address to 127.0.0.1, with the port corresponding to the port enabled by LangBot's aiocqhttp adapter.

---

# Integrating LangBot with New API

Source: https://langbot.app/docs/en/workshop/newapi-integration

New API is a next-generation large model gateway and AI asset management system, designed to address issues such as fragmented access to multiple AI service providers, difficulty in cost control, and insufficient service stability. Its core advantages are focused on three aspects:

1. **Multi-provider compatibility**: It has integrated **over 30 AI service providers** and achieved **100% OpenAI compatibility** (that is, it supports calling models from other service providers in the OpenAI interface format, reducing development costs);
2. **High availability**: It promises **99.9% service availability** to meet enterprise-level stability requirements;
3. **Ease of use and controllability**: It supports "one-click deployment" for quick access, and also provides a "flexible billing" function to help users control AI usage costs, while taking into account "security and stability" features.

## 1. Deploy New API Locally (Docker Container Method)

> For more deployment methods, refer to the [New API Deployment Guide](https://docs.newapi.pro/installation/)

This deployment method uses an SQLite database (lightweight, no additional deployment required).

Enter in the command line:

```bash
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./new-api/data:/data \
  calciumion/new-api:latest
```

> ⚠️ Note:
>
> - Replace `./new-api/data` with the actual folder you want to use.

After deployment, open `http://server-IP:3000` to configure New API.

## 2. Connect LangBot to Local New API

1. **Add New API Model**
   - Model Name: Enter the model name configured in New API
   - Model Provider: Select New API
   - Request URL: Enter `http://server-IP:3000/v1`
   - API Key: Enter the token created in New API

![](https://langbot.app/docs/images/zh/workshop/newapi-integration/model.png)

2. **Select the newly configured model in the pipeline**

![](https://langbot.app/docs/images/zh/workshop/newapi-integration/model2.png)

3. Now you can use the models in New API.

---

# Integrating Models with PPIO Cloud API

Source: https://langbot.app/docs/en/workshop/ppio-integration

Open the WebUI page, and select [PPIO Cloud](https://ppio.cn/user/register?from=ppinfra\&invited_by=QJKFYD\&utm_source=github_langbot) when adding a model.

![model](https://langbot.app/docs/images/zh/workshop/ppio-integration/model.png)

---

# Configure HTTP Reverse Proxy or Access LangBot Through Gateway

Source: https://langbot.app/docs/en/workshop/production/proxy-and-ssl

LangBot does not have built-in SSL support for HTTPS services. If you need to resolve a domain name to a LangBot instance, or need to use HTTPS to access LangBot WebUI and webhook addresses for various bots, please refer to this document to deploy NGINX or Caddy to implement HTTP reverse proxy.

You need to deploy LangBot on a host with a public IP address, purchase a domain name, and resolve the domain name to the host's public IP.

> idea:
>
> **Too much hassle?** [LangBot Cloud](https://space.langbot.app/cloud) comes with built-in domain and HTTPS — no need to buy a server, domain, or configure reverse proxies. Sign up and start using webhook-based platforms like Slack, LINE, and WeCom immediately.

> warning:
>
> If you need to use bots that require Webhook callback addresses such as QQ Official Bot, WeChat Official Account, WeCom, Slack, LINE, etc., you must configure HTTP reverse proxy according to this document.

## Caddy

Caddy is a modern HTTP server that supports automatic HTTPS certificate application and renewal, reverse proxy, and automatic DNS resolution configuration.

[Caddy Installation Documentation](https://caddy2.dengxiaolong.com/docs/install). Select the installation steps corresponding to your operating system and proceed with the installation.

### Configure Caddyfile

This document assumes using the Ubuntu system to deploy LangBot. In the system, the default location of Caddyfile is `/etc/caddy/Caddyfile`.
Use vim or nano to edit Caddyfile, and fill in the Caddyfile as follows:

```json
your.domain.com {
        reverse_proxy 127.0.0.1:5300
}
```

> info:
>
> If your Caddy and LangBot are deployed using containers, please check [Container Network Configuration Details](https://langbot.app/docs/en/workshop/network-details.md)

Now, you can access LangBot WebUI through your browser at `https://your.domain.com`.

### Set Bot Callback Address Prefix

If you need to use bots that require Webhook callback addresses such as QQ Official Bot, WeChat Official Account, WeCom, Slack, LINE, etc., please set `api.webhook_prefix` in the data/config.yaml file to your domain name. For example: `https://your.domain.com`.

After that, you will see the correctly displayed callback address on the bot management page.

## NGINX

NGINX is also a commonly used HTTP server and reverse proxy tool that can be used to implement HTTPS access to LangBot.

### Install NGINX

On Ubuntu, you can install NGINX with the following commands:

```bash
sudo apt update
sudo apt install nginx
```

### Prepare SSL Certificate

You can use [Let's Encrypt](https://letsencrypt.org/) to apply for a free SSL certificate. It is recommended to use the [Certbot](https://certbot.eff.org/) tool to obtain a certificate:

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx
```

Follow the prompts to enter your domain name, and certificate application and NGINX configuration will be completed automatically. Please refer to the following content to complete the NGINX configuration.

### Configure NGINX Reverse Proxy

LangBot's pipeline debugging feature requires using WebSocket connections, so NGINX needs to be configured to support WebSocket.

Edit the NGINX configuration file `/etc/nginx/sites-available/langbot` (you can use vim or nano editor):

```nginx
# WebSocket connection upgrade mapping (place outside server block)
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name your.domain.com;
    # Redirect HTTP traffic to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your.domain.com;

    ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Reverse proxy to LangBot instance
    location / {
        proxy_pass http://127.0.0.1:5300;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 86400;
    }
}
```

Replace `your.domain.com` with your actual domain name.

Enable this configuration and restart NGINX:

```bash
sudo ln -s /etc/nginx/sites-available/langbot /etc/nginx/sites-enabled/langbot
sudo nginx -t
sudo systemctl reload nginx
```

### Set Bot Callback Address Prefix

Similarly, set `api.webhook_prefix` to `https://your.domain.com` in the `data/config.yaml` configuration file, so that the bot Webhook callback address will be correct.

After completing the above configuration, you can securely access LangBot WebUI and bot Webhook services through `https://your.domain.com`.

---

# 创建机器人

Source: https://langbot.app/docs/ja/api-reference/bots/%E5%88%9B%E5%BB%BA%E6%9C%BA%E5%99%A8%E4%BA%BA

## POST /api/v1/platform/bots



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots": {
      "post": {
        "tags": [
          "Bots"
        ],
        "summary": "创建机器人",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BotCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BotCreate": {
        "type": "object",
        "required": [
          "name",
          "adapter",
          "config"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除机器人

Source: https://langbot.app/docs/ja/api-reference/bots/%E5%88%A0%E9%99%A4%E6%9C%BA%E5%99%A8%E4%BA%BA

## DELETE /api/v1/platform/bots/{bot_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}": {
      "delete": {
        "tags": [
          "Bots"
        ],
        "summary": "删除机器人",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新机器人

Source: https://langbot.app/docs/ja/api-reference/bots/%E6%9B%B4%E6%96%B0%E6%9C%BA%E5%99%A8%E4%BA%BA

## PUT /api/v1/platform/bots/{bot_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}": {
      "put": {
        "tags": [
          "Bots"
        ],
        "summary": "更新机器人",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BotUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BotUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个机器人

Source: https://langbot.app/docs/ja/api-reference/bots/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E6%9C%BA%E5%99%A8%E4%BA%BA

## GET /api/v1/platform/bots/{bot_uuid}

获取机器人信息，包括运行时信息（如 Webhook 地址等）。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}": {
      "get": {
        "tags": [
          "Bots"
        ],
        "summary": "获取单个机器人",
        "description": "获取机器人信息，包括运行时信息（如 Webhook 地址等）。",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bot": {
                          "$ref": "#/components/schemas/Bot"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Bot": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string",
            "example": "telegram"
          },
          "config": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有机器人

Source: https://langbot.app/docs/ja/api-reference/bots/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E6%9C%BA%E5%99%A8%E4%BA%BA

## GET /api/v1/platform/bots



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots": {
      "get": {
        "tags": [
          "Bots"
        ],
        "summary": "获取所有机器人",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bots": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Bot"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Bot": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string",
            "example": "telegram"
          },
          "config": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取机器人事件日志

Source: https://langbot.app/docs/ja/api-reference/bots/%E8%8E%B7%E5%8F%96%E6%9C%BA%E5%99%A8%E4%BA%BA%E4%BA%8B%E4%BB%B6%E6%97%A5%E5%BF%97

## POST /api/v1/platform/bots/{bot_uuid}/logs

获取指定机器人的事件日志记录。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}/logs": {
      "post": {
        "tags": [
          "Bots"
        ],
        "summary": "获取机器人事件日志",
        "description": "获取指定机器人的事件日志记录。",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from_index": {
                    "type": "integer",
                    "description": "起始索引（-1 表示从最新开始）",
                    "default": -1
                  },
                  "max_count": {
                    "type": "integer",
                    "description": "最大返回数量",
                    "default": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "logs": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "total_count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 通过机器人发送消息

Source: https://langbot.app/docs/ja/api-reference/bots/%E9%80%9A%E8%BF%87%E6%9C%BA%E5%99%A8%E4%BA%BA%E5%8F%91%E9%80%81%E6%B6%88%E6%81%AF

## POST /api/v1/platform/bots/{bot_uuid}/send_message

通过指定的机器人向目标发送消息。仅支持 API Key 认证。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}/send_message": {
      "post": {
        "tags": [
          "Bots"
        ],
        "summary": "通过机器人发送消息",
        "description": "通过指定的机器人向目标发送消息。仅支持 API Key 认证。",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "target_type",
                  "target_id",
                  "message_chain"
                ],
                "properties": {
                  "target_type": {
                    "type": "string",
                    "enum": [
                      "person",
                      "group"
                    ],
                    "description": "目标类型"
                  },
                  "target_id": {
                    "type": "string",
                    "description": "目标 ID（用户 ID 或群组 ID）"
                  },
                  "message_chain": {
                    "type": "array",
                    "description": "消息链",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "Plain",
                            "Image",
                            "At",
                            "Voice"
                          ],
                          "description": "消息元素类型"
                        },
                        "text": {
                          "type": "string",
                          "description": "文本内容（Plain 类型）"
                        },
                        "url": {
                          "type": "string",
                          "description": "图片 URL（Image 类型）"
                        },
                        "target": {
                          "type": "string",
                          "description": "@ 的目标 ID（At 类型）"
                        }
                      }
                    },
                    "example": [
                      {
                        "type": "Plain",
                        "text": "Hello, World!"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "发送成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "sent": {
                          "type": "boolean",
                          "example": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```

---

# 创建向量模型

Source: https://langbot.app/docs/ja/api-reference/embedding-models/%E5%88%9B%E5%BB%BA%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## POST /api/v1/provider/models/embedding

创建一个新的向量模型。模型必须关联到一个已存在的供应商。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding": {
      "post": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "创建向量模型",
        "description": "创建一个新的向量模型。模型必须关联到一个已存在的供应商。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingModelCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModelCreate": {
        "type": "object",
        "required": [
          "name",
          "provider_uuid"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "text-embedding-3-small"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除向量模型

Source: https://langbot.app/docs/ja/api-reference/embedding-models/%E5%88%A0%E9%99%A4%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## DELETE /api/v1/provider/models/embedding/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}": {
      "delete": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "删除向量模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新向量模型

Source: https://langbot.app/docs/ja/api-reference/embedding-models/%E6%9B%B4%E6%96%B0%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## PUT /api/v1/provider/models/embedding/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}": {
      "put": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "更新向量模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingModelUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModelUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 测试向量模型

Source: https://langbot.app/docs/ja/api-reference/embedding-models/%E6%B5%8B%E8%AF%95%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## POST /api/v1/provider/models/embedding/{model_uuid}/test

向指定的向量模型发送测试请求，验证模型是否可用。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}/test": {
      "post": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "测试向量模型",
        "description": "向指定的向量模型发送测试请求，验证模型是否可用。",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "测试用的文本",
                    "example": "Hello"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个向量模型

Source: https://langbot.app/docs/ja/api-reference/embedding-models/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## GET /api/v1/provider/models/embedding/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}": {
      "get": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "获取单个向量模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "model": {
                          "$ref": "#/components/schemas/EmbeddingModel"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModel": {
        "type": "object",
        "description": "向量模型。通过 provider_uuid 关联到供应商。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID）",
            "example": "text-embedding-3-small"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有向量模型

Source: https://langbot.app/docs/ja/api-reference/embedding-models/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## GET /api/v1/provider/models/embedding

获取所有向量模型列表。可通过 provider_uuid 过滤特定供应商的模型。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding": {
      "get": {
        "tags": [
          "Embedding Models"
        ],
        "summary": "获取所有向量模型",
        "description": "获取所有向量模型列表。可通过 provider_uuid 过滤特定供应商的模型。",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "按供应商 UUID 过滤"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "models": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/EmbeddingModel"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModel": {
        "type": "object",
        "description": "向量模型。通过 provider_uuid 关联到供应商。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID）",
            "example": "text-embedding-3-small"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 上传图片

Source: https://langbot.app/docs/ja/api-reference/files/%E4%B8%8A%E4%BC%A0%E5%9B%BE%E7%89%87

## POST /api/v1/files/images

上传图片文件，支持 jpg、jpeg、png、gif、webp 格式，大小限制 10MB。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/files/images": {
      "post": {
        "tags": [
          "Files"
        ],
        "summary": "上传图片",
        "description": "上传图片文件，支持 jpg、jpeg、png、gif、webp 格式，大小限制 10MB。",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "图片文件"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上传成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "file_key": {
                          "type": "string",
                          "description": "文件标识符，可用于引用图片"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 上传文档

Source: https://langbot.app/docs/ja/api-reference/files/%E4%B8%8A%E4%BC%A0%E6%96%87%E6%A1%A3

## POST /api/v1/files/documents

上传文档文件，大小限制 10MB。上传后可将 file_id 用于知识库关联。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/files/documents": {
      "post": {
        "tags": [
          "Files"
        ],
        "summary": "上传文档",
        "description": "上传文档文件，大小限制 10MB。上传后可将 file_id 用于知识库关联。",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "文档文件"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上传成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "file_id": {
                          "type": "string",
                          "description": "文件 ID，可用于知识库关联"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 从知识库删除文件

Source: https://langbot.app/docs/ja/api-reference/knowledge-bases/%E4%BB%8E%E7%9F%A5%E8%AF%86%E5%BA%93%E5%88%A0%E9%99%A4%E6%96%87%E4%BB%B6

## DELETE /api/v1/knowledge/bases/{kb_uuid}/files/{file_id}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": {
      "delete": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "从知识库删除文件",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 创建知识库

Source: https://langbot.app/docs/ja/api-reference/knowledge-bases/%E5%88%9B%E5%BB%BA%E7%9F%A5%E8%AF%86%E5%BA%93

## POST /api/v1/knowledge/bases



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases": {
      "post": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "创建知识库",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "engine_plugin_id": {
                    "type": "string",
                    "description": "知识引擎插件 ID（author/name 格式）"
                  },
                  "creation_settings": {
                    "type": "object",
                    "description": "引擎创建参数"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除知识库

Source: https://langbot.app/docs/ja/api-reference/knowledge-bases/%E5%88%A0%E9%99%A4%E7%9F%A5%E8%AF%86%E5%BA%93

## DELETE /api/v1/knowledge/bases/{kb_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}": {
      "delete": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "删除知识库",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 将文件存入知识库

Source: https://langbot.app/docs/ja/api-reference/knowledge-bases/%E5%B0%86%E6%96%87%E4%BB%B6%E5%AD%98%E5%85%A5%E7%9F%A5%E8%AF%86%E5%BA%93

## POST /api/v1/knowledge/bases/{kb_uuid}/files

将已上传的文件关联到知识库并开始解析。先通过 /api/v1/files/documents 上传文件获取 file_id。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/files": {
      "post": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "将文件存入知识库",
        "description": "将已上传的文件关联到知识库并开始解析。先通过 /api/v1/files/documents 上传文件获取 file_id。",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "file_id"
                ],
                "properties": {
                  "file_id": {
                    "type": "string",
                    "description": "已上传的文件 ID"
                  },
                  "parser_plugin_id": {
                    "type": "string",
                    "description": "指定的解析器插件 ID（可选）"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新知识库

Source: https://langbot.app/docs/ja/api-reference/knowledge-bases/%E6%9B%B4%E6%96%B0%E7%9F%A5%E8%AF%86%E5%BA%93

## PUT /api/v1/knowledge/bases/{kb_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}": {
      "put": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "更新知识库",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 检索知识库

Source: https://langbot.app/docs/ja/api-reference/knowledge-bases/%E6%A3%80%E7%B4%A2%E7%9F%A5%E8%AF%86%E5%BA%93

## POST /api/v1/knowledge/bases/{kb_uuid}/retrieve

对知识库进行语义检索，返回相关文档片段。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/retrieve": {
      "post": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "检索知识库",
        "description": "对知识库进行语义检索，返回相关文档片段。",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "检索查询文本"
                  },
                  "retrieval_settings": {
                    "type": "object",
                    "description": "检索参数（如 top_k 等）",
                    "properties": {
                      "top_k": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个知识库

Source: https://langbot.app/docs/ja/api-reference/knowledge-bases/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E7%9F%A5%E8%AF%86%E5%BA%93

## GET /api/v1/knowledge/bases/{kb_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}": {
      "get": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "获取单个知识库",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "base": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有知识库

Source: https://langbot.app/docs/ja/api-reference/knowledge-bases/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E7%9F%A5%E8%AF%86%E5%BA%93

## GET /api/v1/knowledge/bases



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases": {
      "get": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "获取所有知识库",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bases": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取知识库文件列表

Source: https://langbot.app/docs/ja/api-reference/knowledge-bases/%E8%8E%B7%E5%8F%96%E7%9F%A5%E8%AF%86%E5%BA%93%E6%96%87%E4%BB%B6%E5%88%97%E8%A1%A8

## GET /api/v1/knowledge/bases/{kb_uuid}/files



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/files": {
      "get": {
        "tags": [
          "Knowledge Bases"
        ],
        "summary": "获取知识库文件列表",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "files": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取可用知识引擎列表

Source: https://langbot.app/docs/ja/api-reference/knowledge-engines/%E8%8E%B7%E5%8F%96%E5%8F%AF%E7%94%A8%E7%9F%A5%E8%AF%86%E5%BC%95%E6%93%8E%E5%88%97%E8%A1%A8

## GET /api/v1/knowledge/engines

列出所有由插件提供的知识引擎，包含其能力和配置模式。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/engines": {
      "get": {
        "tags": [
          "Knowledge Engines"
        ],
        "summary": "获取可用知识引擎列表",
        "description": "列出所有由插件提供的知识引擎，包含其能力和配置模式。",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "engines": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取知识引擎创建配置模式

Source: https://langbot.app/docs/ja/api-reference/knowledge-engines/%E8%8E%B7%E5%8F%96%E7%9F%A5%E8%AF%86%E5%BC%95%E6%93%8E%E5%88%9B%E5%BB%BA%E9%85%8D%E7%BD%AE%E6%A8%A1%E5%BC%8F

## GET /api/v1/knowledge/engines/{plugin_id}/creation-schema

获取指定知识引擎的创建参数 JSON Schema。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/engines/{plugin_id}/creation-schema": {
      "get": {
        "tags": [
          "Knowledge Engines"
        ],
        "summary": "获取知识引擎创建配置模式",
        "description": "获取指定知识引擎的创建参数 JSON Schema。",
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "插件 ID（author/name 格式）"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取知识引擎检索配置模式

Source: https://langbot.app/docs/ja/api-reference/knowledge-engines/%E8%8E%B7%E5%8F%96%E7%9F%A5%E8%AF%86%E5%BC%95%E6%93%8E%E6%A3%80%E7%B4%A2%E9%85%8D%E7%BD%AE%E6%A8%A1%E5%BC%8F

## GET /api/v1/knowledge/engines/{plugin_id}/retrieval-schema

获取指定知识引擎的检索参数 JSON Schema。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/engines/{plugin_id}/retrieval-schema": {
      "get": {
        "tags": [
          "Knowledge Engines"
        ],
        "summary": "获取知识引擎检索配置模式",
        "description": "获取指定知识引擎的检索参数 JSON Schema。",
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "插件 ID（author/name 格式）"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 创建 LLM 模型

Source: https://langbot.app/docs/ja/api-reference/llm-models/%E5%88%9B%E5%BB%BA-llm-%E6%A8%A1%E5%9E%8B

## POST /api/v1/provider/models/llm

创建一个新的大语言模型。模型必须关联到一个已存在的供应商。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm": {
      "post": {
        "tags": [
          "LLM Models"
        ],
        "summary": "创建 LLM 模型",
        "description": "创建一个新的大语言模型。模型必须关联到一个已存在的供应商。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LLMModelCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModelCreate": {
        "type": "object",
        "required": [
          "name",
          "provider_uuid"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID）",
            "example": "gpt-4o"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "chat",
              "vision"
            ]
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除 LLM 模型

Source: https://langbot.app/docs/ja/api-reference/llm-models/%E5%88%A0%E9%99%A4-llm-%E6%A8%A1%E5%9E%8B

## DELETE /api/v1/provider/models/llm/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}": {
      "delete": {
        "tags": [
          "LLM Models"
        ],
        "summary": "删除 LLM 模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新 LLM 模型

Source: https://langbot.app/docs/ja/api-reference/llm-models/%E6%9B%B4%E6%96%B0-llm-%E6%A8%A1%E5%9E%8B

## PUT /api/v1/provider/models/llm/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}": {
      "put": {
        "tags": [
          "LLM Models"
        ],
        "summary": "更新 LLM 模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LLMModelUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModelUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 测试 LLM 模型

Source: https://langbot.app/docs/ja/api-reference/llm-models/%E6%B5%8B%E8%AF%95-llm-%E6%A8%A1%E5%9E%8B

## POST /api/v1/provider/models/llm/{model_uuid}/test

向指定的 LLM 模型发送测试请求，验证模型是否可用。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}/test": {
      "post": {
        "tags": [
          "LLM Models"
        ],
        "summary": "测试 LLM 模型",
        "description": "向指定的 LLM 模型发送测试请求，验证模型是否可用。",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "测试用的提示文本",
                    "example": "Hello"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个 LLM 模型

Source: https://langbot.app/docs/ja/api-reference/llm-models/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA-llm-%E6%A8%A1%E5%9E%8B

## GET /api/v1/provider/models/llm/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}": {
      "get": {
        "tags": [
          "LLM Models"
        ],
        "summary": "获取单个 LLM 模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "model": {
                          "$ref": "#/components/schemas/LLMModel"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModel": {
        "type": "object",
        "description": "大语言模型。通过 provider_uuid 关联到供应商，继承供应商的 API 地址和密钥。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID，发送到 API 的 model 参数值）",
            "example": "gpt-4o"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "模型能力标签",
            "example": [
              "chat",
              "vision",
              "tool-use"
            ]
          },
          "extra_args": {
            "type": "object",
            "description": "额外参数（如 temperature、max_tokens 等）"
          },
          "prefered_ranking": {
            "type": "integer",
            "description": "优先级排序（越大越优先）",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有 LLM 模型

Source: https://langbot.app/docs/ja/api-reference/llm-models/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89-llm-%E6%A8%A1%E5%9E%8B

## GET /api/v1/provider/models/llm

获取所有大语言模型列表。可通过 provider_uuid 过滤特定供应商的模型。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm": {
      "get": {
        "tags": [
          "LLM Models"
        ],
        "summary": "获取所有 LLM 模型",
        "description": "获取所有大语言模型列表。可通过 provider_uuid 过滤特定供应商的模型。",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "按供应商 UUID 过滤"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "models": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/LLMModel"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModel": {
        "type": "object",
        "description": "大语言模型。通过 provider_uuid 关联到供应商，继承供应商的 API 地址和密钥。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID，发送到 API 的 model 参数值）",
            "example": "gpt-4o"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "模型能力标签",
            "example": [
              "chat",
              "vision",
              "tool-use"
            ]
          },
          "extra_args": {
            "type": "object",
            "description": "额外参数（如 temperature、max_tokens 等）"
          },
          "prefered_ranking": {
            "type": "integer",
            "description": "优先级排序（越大越优先）",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 创建供应商

Source: https://langbot.app/docs/ja/api-reference/model-providers/%E5%88%9B%E5%BB%BA%E4%BE%9B%E5%BA%94%E5%95%86

## POST /api/v1/provider/providers

创建一个新的模型供应商。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers": {
      "post": {
        "tags": [
          "Model Providers"
        ],
        "summary": "创建供应商",
        "description": "创建一个新的模型供应商。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelProviderCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProviderCreate": {
        "type": "object",
        "required": [
          "name",
          "requester",
          "base_url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "OpenAI"
          },
          "requester": {
            "type": "string",
            "description": "请求器类型。可通过 GET /api/v1/provider/requesters 获取可用列表。",
            "example": "openai-chat-completions"
          },
          "base_url": {
            "type": "string",
            "example": "https://api.openai.com/v1"
          },
          "api_keys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "sk-xxx"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除供应商

Source: https://langbot.app/docs/ja/api-reference/model-providers/%E5%88%A0%E9%99%A4%E4%BE%9B%E5%BA%94%E5%95%86

## DELETE /api/v1/provider/providers/{provider_uuid}

删除供应商。如果还有模型引用该供应商，则无法删除。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers/{provider_uuid}": {
      "delete": {
        "tags": [
          "Model Providers"
        ],
        "summary": "删除供应商",
        "description": "删除供应商。如果还有模型引用该供应商，则无法删除。",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "description": "供应商仍有模型引用，无法删除",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新供应商

Source: https://langbot.app/docs/ja/api-reference/model-providers/%E6%9B%B4%E6%96%B0%E4%BE%9B%E5%BA%94%E5%95%86

## PUT /api/v1/provider/providers/{provider_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers/{provider_uuid}": {
      "put": {
        "tags": [
          "Model Providers"
        ],
        "summary": "更新供应商",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelProviderUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProviderUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "requester": {
            "type": "string"
          },
          "base_url": {
            "type": "string"
          },
          "api_keys": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个供应商

Source: https://langbot.app/docs/ja/api-reference/model-providers/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E4%BE%9B%E5%BA%94%E5%95%86

## GET /api/v1/provider/providers/{provider_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers/{provider_uuid}": {
      "get": {
        "tags": [
          "Model Providers"
        ],
        "summary": "获取单个供应商",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "provider": {
                          "$ref": "#/components/schemas/ModelProvider"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProvider": {
        "type": "object",
        "description": "模型供应商。定义了 API 地址和密钥，模型通过 provider_uuid 关联。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "OpenAI"
          },
          "requester": {
            "type": "string",
            "description": "请求器类型",
            "example": "openai-chat-completions"
          },
          "base_url": {
            "type": "string",
            "description": "API 基础地址",
            "example": "https://api.openai.com/v1"
          },
          "api_keys": {
            "type": "array",
            "description": "API 密钥列表",
            "items": {
              "type": "string"
            }
          },
          "llm_count": {
            "type": "integer",
            "description": "关联的 LLM 模型数量"
          },
          "embedding_count": {
            "type": "integer",
            "description": "关联的 Embedding 模型数量"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有供应商

Source: https://langbot.app/docs/ja/api-reference/model-providers/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E4%BE%9B%E5%BA%94%E5%95%86

## GET /api/v1/provider/providers

获取所有模型供应商列表，包含每个供应商关联的 LLM 和 Embedding 模型数量。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers": {
      "get": {
        "tags": [
          "Model Providers"
        ],
        "summary": "获取所有供应商",
        "description": "获取所有模型供应商列表，包含每个供应商关联的 LLM 和 Embedding 模型数量。",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "providers": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ModelProvider"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProvider": {
        "type": "object",
        "description": "模型供应商。定义了 API 地址和密钥，模型通过 provider_uuid 关联。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "OpenAI"
          },
          "requester": {
            "type": "string",
            "description": "请求器类型",
            "example": "openai-chat-completions"
          },
          "base_url": {
            "type": "string",
            "description": "API 基础地址",
            "example": "https://api.openai.com/v1"
          },
          "api_keys": {
            "type": "array",
            "description": "API 密钥列表",
            "items": {
              "type": "string"
            }
          },
          "llm_count": {
            "type": "integer",
            "description": "关联的 LLM 模型数量"
          },
          "embedding_count": {
            "type": "integer",
            "description": "关联的 Embedding 模型数量"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取可用解析器列表

Source: https://langbot.app/docs/ja/api-reference/parsers/%E8%8E%B7%E5%8F%96%E5%8F%AF%E7%94%A8%E8%A7%A3%E6%9E%90%E5%99%A8%E5%88%97%E8%A1%A8

## GET /api/v1/knowledge/parsers

列出所有由插件提供的文件解析器。可通过 mime_type 过滤。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/parsers": {
      "get": {
        "tags": [
          "Parsers"
        ],
        "summary": "获取可用解析器列表",
        "description": "列出所有由插件提供的文件解析器。可通过 mime_type 过滤。",
        "parameters": [
          {
            "name": "mime_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "按 MIME 类型过滤解析器"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "parsers": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 创建流水线

Source: https://langbot.app/docs/ja/api-reference/pipelines/%E5%88%9B%E5%BB%BA%E6%B5%81%E6%B0%B4%E7%BA%BF

## POST /api/v1/pipelines



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines": {
      "post": {
        "tags": [
          "Pipelines"
        ],
        "summary": "创建流水线",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PipelineCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PipelineCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除流水线

Source: https://langbot.app/docs/ja/api-reference/pipelines/%E5%88%A0%E9%99%A4%E6%B5%81%E6%B0%B4%E7%BA%BF

## DELETE /api/v1/pipelines/{pipeline_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}": {
      "delete": {
        "tags": [
          "Pipelines"
        ],
        "summary": "删除流水线",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 复制流水线

Source: https://langbot.app/docs/ja/api-reference/pipelines/%E5%A4%8D%E5%88%B6%E6%B5%81%E6%B0%B4%E7%BA%BF

## POST /api/v1/pipelines/{pipeline_uuid}/copy

复制一个已有的流水线，生成一个新的副本。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}/copy": {
      "post": {
        "tags": [
          "Pipelines"
        ],
        "summary": "复制流水线",
        "description": "复制一个已有的流水线，生成一个新的副本。",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "复制成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新流水线

Source: https://langbot.app/docs/ja/api-reference/pipelines/%E6%9B%B4%E6%96%B0%E6%B5%81%E6%B0%B4%E7%BA%BF

## PUT /api/v1/pipelines/{pipeline_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}": {
      "put": {
        "tags": [
          "Pipelines"
        ],
        "summary": "更新流水线",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PipelineUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PipelineUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "is_default": {
            "type": "boolean"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新流水线扩展配置

Source: https://langbot.app/docs/ja/api-reference/pipelines/%E6%9B%B4%E6%96%B0%E6%B5%81%E6%B0%B4%E7%BA%BF%E6%89%A9%E5%B1%95%E9%85%8D%E7%BD%AE

## PUT /api/v1/pipelines/{pipeline_uuid}/extensions

更新流水线绑定的插件和 MCP 服务器。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}/extensions": {
      "put": {
        "tags": [
          "Pipelines"
        ],
        "summary": "更新流水线扩展配置",
        "description": "更新流水线绑定的插件和 MCP 服务器。",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enable_all_plugins": {
                    "type": "boolean",
                    "default": true
                  },
                  "enable_all_mcp_servers": {
                    "type": "boolean",
                    "default": true
                  },
                  "bound_plugins": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "bound_mcp_servers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个流水线

Source: https://langbot.app/docs/ja/api-reference/pipelines/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E6%B5%81%E6%B0%B4%E7%BA%BF

## GET /api/v1/pipelines/{pipeline_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}": {
      "get": {
        "tags": [
          "Pipelines"
        ],
        "summary": "获取单个流水线",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "pipeline": {
                          "$ref": "#/components/schemas/Pipeline"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pipeline": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有流水线

Source: https://langbot.app/docs/ja/api-reference/pipelines/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E6%B5%81%E6%B0%B4%E7%BA%BF

## GET /api/v1/pipelines



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines": {
      "get": {
        "tags": [
          "Pipelines"
        ],
        "summary": "获取所有流水线",
        "parameters": [
          {
            "name": "sort_by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "created_at"
            }
          },
          {
            "name": "sort_order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ],
              "default": "DESC"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "pipelines": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Pipeline"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pipeline": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取流水线元数据

Source: https://langbot.app/docs/ja/api-reference/pipelines/%E8%8E%B7%E5%8F%96%E6%B5%81%E6%B0%B4%E7%BA%BF%E5%85%83%E6%95%B0%E6%8D%AE

## GET /api/v1/pipelines/_/metadata

获取流水线配置的元数据描述，包括可配置的字段和类型信息。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/_/metadata": {
      "get": {
        "tags": [
          "Pipelines"
        ],
        "summary": "获取流水线元数据",
        "description": "获取流水线配置的元数据描述，包括可配置的字段和类型信息。",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "configs": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取流水线扩展配置

Source: https://langbot.app/docs/ja/api-reference/pipelines/%E8%8E%B7%E5%8F%96%E6%B5%81%E6%B0%B4%E7%BA%BF%E6%89%A9%E5%B1%95%E9%85%8D%E7%BD%AE

## GET /api/v1/pipelines/{pipeline_uuid}/extensions

获取流水线绑定的插件和 MCP 服务器配置。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}/extensions": {
      "get": {
        "tags": [
          "Pipelines"
        ],
        "summary": "获取流水线扩展配置",
        "description": "获取流水线绑定的插件和 MCP 服务器配置。",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "enable_all_plugins": {
                          "type": "boolean"
                        },
                        "enable_all_mcp_servers": {
                          "type": "boolean"
                        },
                        "bound_plugins": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "available_plugins": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "bound_mcp_servers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "available_mcp_servers": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 从 GitHub 安装插件

Source: https://langbot.app/docs/ja/api-reference/plugins/%E4%BB%8E-github-%E5%AE%89%E8%A3%85%E6%8F%92%E4%BB%B6

## POST /api/v1/plugins/install/github

从 GitHub 仓库安装插件。异步操作，返回任务 ID。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/install/github": {
      "post": {
        "tags": [
          "Plugins"
        ],
        "summary": "从 GitHub 安装插件",
        "description": "从 GitHub 仓库安装插件。异步操作，返回任务 ID。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "GitHub 仓库 URL",
                    "example": "https://github.com/rocksclawbot/langbot-community-plugins/tree/main/disaster-alert"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 从 Marketplace 安装插件

Source: https://langbot.app/docs/ja/api-reference/plugins/%E4%BB%8E-marketplace-%E5%AE%89%E8%A3%85%E6%8F%92%E4%BB%B6

## POST /api/v1/plugins/install/marketplace

从 LangBot Marketplace 安装插件。异步操作，返回任务 ID。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/install/marketplace": {
      "post": {
        "tags": [
          "Plugins"
        ],
        "summary": "从 Marketplace 安装插件",
        "description": "从 LangBot Marketplace 安装插件。异步操作，返回任务 ID。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plugin_id"
                ],
                "properties": {
                  "plugin_id": {
                    "type": "string",
                    "description": "Marketplace 插件 ID（author/name 格式）",
                    "example": "kellz-dev/disaster-alert"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除插件

Source: https://langbot.app/docs/ja/api-reference/plugins/%E5%88%A0%E9%99%A4%E6%8F%92%E4%BB%B6

## DELETE /api/v1/plugins/{author}/{plugin_name}

异步删除插件，返回任务 ID。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}": {
      "delete": {
        "tags": [
          "Plugins"
        ],
        "summary": "删除插件",
        "description": "异步删除插件，返回任务 ID。",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "delete_data",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "是否同时删除插件数据"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 升级插件

Source: https://langbot.app/docs/ja/api-reference/plugins/%E5%8D%87%E7%BA%A7%E6%8F%92%E4%BB%B6

## POST /api/v1/plugins/{author}/{plugin_name}/upgrade

异步升级插件到最新版本，返回任务 ID。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}/upgrade": {
      "post": {
        "tags": [
          "Plugins"
        ],
        "summary": "升级插件",
        "description": "异步升级插件到最新版本，返回任务 ID。",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新插件配置

Source: https://langbot.app/docs/ja/api-reference/plugins/%E6%9B%B4%E6%96%B0%E6%8F%92%E4%BB%B6%E9%85%8D%E7%BD%AE

## PUT /api/v1/plugins/{author}/{plugin_name}/config



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}/config": {
      "put": {
        "tags": [
          "Plugins"
        ],
        "summary": "更新插件配置",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "插件配置键值对"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取已安装插件列表

Source: https://langbot.app/docs/ja/api-reference/plugins/%E8%8E%B7%E5%8F%96%E5%B7%B2%E5%AE%89%E8%A3%85%E6%8F%92%E4%BB%B6%E5%88%97%E8%A1%A8

## GET /api/v1/plugins



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins": {
      "get": {
        "tags": [
          "Plugins"
        ],
        "summary": "获取已安装插件列表",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "plugins": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取插件详情

Source: https://langbot.app/docs/ja/api-reference/plugins/%E8%8E%B7%E5%8F%96%E6%8F%92%E4%BB%B6%E8%AF%A6%E6%83%85

## GET /api/v1/plugins/{author}/{plugin_name}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}": {
      "get": {
        "tags": [
          "Plugins"
        ],
        "summary": "获取插件详情",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "plugin": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取插件配置

Source: https://langbot.app/docs/ja/api-reference/plugins/%E8%8E%B7%E5%8F%96%E6%8F%92%E4%BB%B6%E9%85%8D%E7%BD%AE

## GET /api/v1/plugins/{author}/{plugin_name}/config

获取插件的当前配置值和配置模式。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}/config": {
      "get": {
        "tags": [
          "Plugins"
        ],
        "summary": "获取插件配置",
        "description": "获取插件的当前配置值和配置模式。",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取系统信息

Source: https://langbot.app/docs/ja/api-reference/system/%E8%8E%B7%E5%8F%96%E7%B3%BB%E7%BB%9F%E4%BF%A1%E6%81%AF

## GET /api/v1/system/info

获取 LangBot 实例的版本、版本类型等基本信息。此接口无需认证。

No authentication required.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/system/info": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "获取系统信息",
        "description": "获取 LangBot 实例的版本、版本类型等基本信息。此接口无需认证。",
        "security": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string",
                          "example": "v4.9.5"
                        },
                        "debug": {
                          "type": "boolean"
                        },
                        "edition": {
                          "type": "string",
                          "example": "community"
                        },
                        "enable_marketplace": {
                          "type": "boolean"
                        },
                        "cloud_service_url": {
                          "type": "string"
                        },
                        "allow_modify_login_info": {
                          "type": "boolean"
                        },
                        "disable_models_service": {
                          "type": "boolean"
                        },
                        "limitation": {
                          "type": "object"
                        },
                        "wizard_status": {
                          "type": "string",
                          "enum": [
                            "none",
                            "skipped",
                            "completed"
                          ]
                        },
                        "wizard_progress": {
                          "type": "object",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {}
}
```

---

# ツール詳細を取得

Source: https://langbot.app/docs/ja/api-reference/%E3%83%84%E3%83%BC%E3%83%AB/%E3%83%84%E3%83%BC%E3%83%AB%E8%A9%B3%E7%B4%B0%E3%82%92%E5%8F%96%E5%BE%97

## GET /api/v1/tools/{tool_name}

指定されたツールの詳細情報を取得します。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/tools/{tool_name}": {
      "get": {
        "tags": [
          "ツール"
        ],
        "summary": "ツール詳細を取得",
        "description": "指定されたツールの詳細情報を取得します。",
        "operationId": "getToolDetail",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tool_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ツール名"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "msg": {
                      "type": "string",
                      "example": "ok"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "tool": {
                          "$ref": "#/components/schemas/ToolSummary"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tool not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ToolSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Tool name"
          },
          "label": {
            "type": "object",
            "description": "Display label (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "object",
            "description": "Tool description (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "icon": {
            "type": "string",
            "description": "Tool icon"
          },
          "spec": {
            "type": "object",
            "description": "Tool specification",
            "properties": {
              "llm_prompt": {
                "type": "string"
              },
              "parameters": {
                "type": "object",
                "description": "JSON Schema for tool parameters"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 利用可能なツール一覧を取得

Source: https://langbot.app/docs/ja/api-reference/%E3%83%84%E3%83%BC%E3%83%AB/%E5%88%A9%E7%94%A8%E5%8F%AF%E8%83%BD%E3%81%AA%E3%83%84%E3%83%BC%E3%83%AB%E4%B8%80%E8%A6%A7%E3%82%92%E5%8F%96%E5%BE%97

## GET /api/v1/tools

現在の LangBot インスタンスで利用可能なすべてのツール（プラグインツールおよび MCP ツール）を取得します。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete ja OpenAPI specification](https://langbot.app/docs/openapi/service-api-ja.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot external service API documentation. These endpoints support API Key authentication for programmatic access to LangBot resources.\n\n**Authentication:**\n- User Token (via `Authorization: Bearer <token>`)\n- API Key (via `X-API-Key: <key>` or `Authorization: Bearer <key>`)\n\nAll endpoints in this document support both authentication methods unless otherwise noted.\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/tools": {
      "get": {
        "tags": [
          "ツール"
        ],
        "summary": "利用可能なツール一覧を取得",
        "description": "現在の LangBot インスタンスで利用可能なすべてのツール（プラグインツールおよび MCP ツール）を取得します。",
        "operationId": "listTools",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "msg": {
                      "type": "string",
                      "example": "ok"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "tools": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ToolSummary"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ToolSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Tool name"
          },
          "label": {
            "type": "object",
            "description": "Display label (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "object",
            "description": "Tool description (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "icon": {
            "type": "string",
            "description": "Tool icon"
          },
          "spec": {
            "type": "object",
            "description": "Tool specification",
            "properties": {
              "llm_prompt": {
                "type": "string"
              },
              "parameters": {
                "type": "object",
                "description": "JSON Schema for tool parameters"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# LangBot 記事

Source: https://langbot.app/docs/ja/articles

LangBot Blog の製品アップデート、技術解説、チュートリアル、連携事例、お知らせをまとめています。

LangBot Blog の製品アップデート、技術解説、チュートリアル、連携事例、お知らせをまとめています。

## 製品アップデート

- [新しい LangBot Cloud が公開—オープンソース版もマルチユーザー Workspace に対応](https://langbot.app/docs/ja/articles/langbot-cloud-multi-user-workspaces.md) — 2026-08-25

## エンジニアリング

- [LangBot v4.10.0：Agent Sandbox と Skills](https://langbot.app/docs/ja/articles/langbot-v4100-sandbox-skills.md) — 2026-06-04
- [LangBot v4.9.0：完全プラグイン化された RAG アーキテクチャ](https://langbot.app/docs/ja/articles/langbot-v490-rag-plugin-architecture.md) — 2026-03-10
- [LangBot プラグインシステム詳解：プロセス分離・イベント駆動・コンポーネント設計](https://langbot.app/docs/ja/articles/langbot-plugin-system-deep-dive.md) — 2026-02-23

## チュートリアルと連携

- [LangTARS：Dify・n8n と連携するオープンソース PC 操作 Agent](https://langbot.app/docs/ja/articles/langtars-remote-pc-control-dify-n8n.md) — 2026-03-23
- [DeepSeek R1 を WeChat・Discord・Telegram に5分で接続する方法](https://langbot.app/docs/ja/articles/connect-deepseek-to-wechat.md) — 2026-02-21
- [AI Bot を Discord・Telegram・WeChat に5分でデプロイ](https://langbot.app/docs/ja/articles/deploy-ai-bot-in-5-minutes.md) — 2026-02-17
- [Dify Agent を Discord・Telegram・Slack で動かす](https://langbot.app/docs/ja/articles/dify-agent-discord-telegram-slack.md) — 2025-12-11
- [Langflow のドラッグ＆ドロップでマルチプラットフォーム AI Bot を構築](https://langbot.app/docs/ja/articles/langflow-drag-and-drop-ai-bot.md) — 2025-12-05
- [n8n と LangBot でマルチプラットフォーム AI Chatbot を構築](https://langbot.app/docs/ja/articles/n8n-multi-platform-ai-chatbot.md) — 2025-12-03
- [LangBot 4.6.0 外部ナレッジベース入門：Dify と連携した RAG 会話](https://langbot.app/docs/ja/articles/dify-langbot-rag-knowledge-base.md) — 2025-12-02

## お知らせ

- [LangBot Blog のご紹介](https://langbot.app/docs/ja/articles/welcome.md) — 2026-02-17

---

# DeepSeek R1 を WeChat・Discord・Telegram に5分で接続する方法

Source: https://langbot.app/docs/ja/articles/connect-deepseek-to-wechat

A step-by-step guide to connecting DeepSeek R1/V3 API to WeChat (Personal/Enterprise), Discord, Telegram, and more using LangBot. No coding required.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/connect-deepseek-to-wechat).

公開日：2026-02-21 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![DeepSeek x WeChat Integration](https://langbot.app/docs/images/articles/source/images/covers/deepseek-wechat.png)

DeepSeek has taken the AI world by storm. Its R1 reasoning model rivals OpenAI's o1 but is open-source and significantly cheaper.

However, the official DeepSeek app currently only supports "AI Search" in WeChat, and direct integration into group chats or private workflows is limited.

**What if you could have a fully functional DeepSeek R1 bot in your WeChat groups, Discord servers, and Telegram chats right now?**

With **LangBot**, you can. And it takes less than 5 minutes.

## Why LangBot?

LangBot is an open-source, production-grade IM bot platform. Unlike simple scripts or single-platform bots, LangBot gives you:

- **Unified Platform:** Connect once, deploy to WeChat, Discord, Telegram, Slack, Lark, and more.
- **Model Agnostic:** Use DeepSeek R1, V3, Claude 3.5, GPT-4, or local Ollama models.
- **No Coding:** robust WebUI for configuration.
- **Enterprise Features:** Knowledge base (RAG), Plugin system, and multi-user management.

## Prerequisites

1. **A Server or PC:** Docker installed (VPS, local computer, or Synology/NAS).
2. **DeepSeek API Key:**
   - **Official:** [platform.deepseek.com](https://platform.deepseek.com)
   - **SiliconFlow (Recommended for speed):** [cloud.siliconflow.cn](https://cloud.siliconflow.cn) (Faster R1 inference).

## Step 1: Deploy LangBot

If you haven't deployed LangBot yet, run this one command:

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose up -d
```

Access your dashboard at `http://localhost:5300` (or your server IP).

## Step 2: Configure DeepSeek Model

1. Go to **Models** -> **Provider List**.
2. Find **DeepSeek** (or **SiliconFlow** / **OpenAI Compatible**).
3. Enter your API Key.
4. Click **Save**.

Now create a **Model Instance**:

- **Name:** `DeepSeek-R1-Bot`
- **Model:** `deepseek-reasoner` (for R1) or `deepseek-chat` (for V3).

## Step 3: Create a Chat Pipeline

LangBot uses "Pipelines" to manage bot logic.

1. Go to **Pipelines** -> **New Pipeline**.
2. Choose **Chat Pipeline**.
3. Select your `DeepSeek-R1-Bot` model.
4. (Optional) Add a System Prompt:
   > "You are a helpful assistant powered by DeepSeek R1. You think deeply before answering."

## Step 4: Connect to WeChat (or any platform)

### For WeChat (Personal / Wechaty)

*Note: Personal WeChat access relies on third-party libraries and carries some risk. For business use, we recommend Enterprise WeChat (WeCom).*

1. Go to **Bots** -> **New Bot**.
2. Select **WeChat**.
3. Choose the **GeweChat** or **Wechaty** adapter (depending on your preference).
4. Click **Save**.
5. Scan the QR code that appears in the logs or UI.

### For Discord / Telegram

1. Select **Discord** or **Telegram**.
2. Paste your **Bot Token** (from Discord Developer Portal or BotFather).
3. Click **Save**.

## Step 5: Test It Out!

Open your chat app and send a message. You should see DeepSeek R1 "thinking" (if supported) and replying with high-quality reasoning.

## Advanced: Using Search & Tools

DeepSeek is great, but DeepSeek with **Internet Access** is better.

In LangBot:

1. Go to **Plugins**.
2. Install **Tavily Search** or **Google Search**.
3. Add the plugin to your DeepSeek Pipeline.

Now your bot can search the web for real-time info *before* reasoning with DeepSeek R1!

***

**Ready to build?**
[Star us on GitHub](https://github.com/langbot-app/LangBot) or [Read the Docs](https://langbot.app/docs/ja/insight/guide.md).

---

# AI Bot を Discord・Telegram・WeChat に5分でデプロイ

Source: https://langbot.app/docs/ja/articles/deploy-ai-bot-in-5-minutes

A step-by-step guide to deploying LangBot — the open-source platform that connects 20+ LLMs to 13+ messaging platforms with a single Docker command.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/deploy-ai-bot-in-5-minutes).

公開日：2026-02-17 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![LangBot Dashboard](https://langbot.app/docs/images/articles/source/images/covers/deploy-ai-bot.png)

What if you could have GPT-5, Claude, DeepSeek, and Gemini all answering questions in your Discord server, Telegram group, and WeChat — at the same time?

No API wrangling. No weeks of development. Just one Docker command.

That's **LangBot** — and it just crossed **15,000 stars** on GitHub.

## The Problem Everyone Faces

You want an AI assistant in your team's chat. Maybe for customer support on Telegram. Maybe for a coding helper in Discord. Maybe for a knowledge base bot in your company's WeChat or Lark group.

But then reality hits:

- Each platform has its own bot API, webhook format, and auth flow
- You need to handle message queuing, session management, and error recovery
- Switching LLM providers means rewriting your integration layer
- Adding RAG or tool calling is yet another project

LangBot solves all of this with a single, unified platform.

## What Makes LangBot Different

### 13+ Messaging Platforms, One Codebase

Deploy a single LangBot instance and connect it to:

**Global:** Discord, Telegram, Slack, LINE, WhatsApp
**Asia:** WeChat (Official Account), WeCom, QQ, Lark, DingTalk, Feishu, KOOK

Each platform gets its own adapter — you just fill in your bot token in the WebUI and you're live.

![LangBot Bot Management Page](https://langbot.app/docs/images/articles/source/images/article-mcp/13-bot-page.png)

### 20+ LLM Models, Zero Lock-in

Through **LangBot Space**, you get instant access to 20 cloud models out of the box — no API keys to manage:

- **Claude** (Opus 4.6, Sonnet 4.5, Haiku 4.5)
- **GPT** (GPT-5.2, GPT-5-mini, GPT-4.1-mini)
- **Gemini** (3 Pro, 2.5 Pro, 2.5 Flash)
- **DeepSeek** (R1, V3)
- **Grok** (4, 4.1)
- **Qwen** (3 Max)

Or add your own providers — OpenAI-compatible endpoints, Ollama for local models, any provider you want.

![Model Selection](https://langbot.app/docs/images/articles/source/images/article-mcp/08-model-select.png)

### Built-in Agent with Tool Calling

LangBot's Local Agent isn't just a chat wrapper — it's a full agent runtime:

- **Multi-round conversations** with configurable memory
- **Function calling / tool use** for LLM-driven actions
- **MCP (Model Context Protocol)** support for connecting to 100+ pre-built tools
- **Knowledge base (RAG)** with built-in vector search

![Pipeline AI Configuration](https://langbot.app/docs/images/articles/source/images/article-mcp/06-pipeline-ai.png)

### Plugin Marketplace

37+ community plugins and growing — install with one click:

- **WebSearch** — Let your bot search the web
- **AI Image Generator** — Generate images from text
- **LinkAnaly** — Auto-preview links in chat
- **ScheNotify** — Schedule reminders with natural language
- **Google Search**, **Tavily Search**, **RAGFlow Retriever**, and more

![LangBot Space Plugin Market](https://langbot.app/docs/images/articles/source/images/article-mcp/14-space-market.png)

## Deploy in 5 Minutes — For Real

### Step 1: Run Docker Compose

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose up -d
```

That's it. LangBot is now running at `http://localhost:5300`.

### Step 2: Initialize with LangBot Space

Open the WebUI and click **"Initialize with Space"**. This connects your instance to LangBot Space, giving you:

- 20 cloud models ready to use (with free credits)
- One-click plugin installation
- Managed API keys

![Initialize with Space](https://langbot.app/docs/images/articles/source/images/article-mcp/01-init-page.png)

### Step 3: Configure Your Pipeline

Go to **Pipelines** and edit the default `ChatPipeline`:

1. Select your model (e.g., `deepseek-v3`, `gpt-5-mini`, `claude-sonnet-4-5`)
2. Customize the system prompt
3. Optionally attach a knowledge base or enable tools

![Pipelines Page](https://langbot.app/docs/images/articles/source/images/article-mcp/05-pipelines.png)

### Step 4: Connect a Platform

Go to **Bots** → click **+** → choose your platform (Discord, Telegram, etc.) → enter your bot token.

Done. Your bot is live.

### Step 5: Test It

Use the built-in **Debug Chat** to test your pipeline before going live:

![Debug Chat](https://langbot.app/docs/images/articles/source/images/article-mcp/07-debug-chat.png)

## Real Conversations, Real Value

Here's what it looks like when LangBot is running in a QQ group — users asking technical questions and getting instant, accurate answers:

![Group Chat Demo](https://langbot.app/docs/images/articles/source/images/article-mcp/10-group-chat.png)

And in private chat:

![Private Chat Demo](https://langbot.app/docs/images/articles/source/images/article-mcp/11-private-chat.png)

## Architecture That Scales

LangBot is built for production:

- **Pipeline architecture** — each bot binds to a pipeline; pipelines handle AI logic, triggers, safety controls, and output formatting
- **Cross-process plugin isolation** — a bad plugin can't crash your bot
- **Multiple runner backends** — use LangBot's Local Agent, or connect to Dify, n8n, Langflow, Coze for complex workflows
- **Database flexibility** — SQLite for dev, PostgreSQL for production
- **Vector DB options** — Chroma, Qdrant, Milvus, pgvector, SeekDB

## Why 15,000+ Developers Choose LangBot

| Feature       | LangBot             | Building from Scratch |
| ------------- | ------------------- | --------------------- |
| Platforms     | 13+ ready           | Weeks per platform    |
| LLM Providers | 20+ models          | Manual integration    |
| Agent Runtime | Built-in            | Build your own        |
| RAG           | Native + external   | Separate project      |
| Plugin System | Marketplace         | DIY                   |
| Deployment    | `docker compose up` | Days of setup         |
| WebUI         | Included            | Build your own        |

## Get Started

- **GitHub:** [github.com/langbot-app/LangBot](https://github.com/langbot-app/LangBot) — give us a star!
- **Documentation:** [langbot.app/docs](https://langbot.app/docs/ja/insight/guide.md)
- **Plugin Market:** [space.langbot.app](https://space.langbot.app)

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose up -d
```

Your AI bot empire starts with one command.

---

# Dify Agent を Discord・Telegram・Slack で動かす

Source: https://langbot.app/docs/ja/articles/dify-agent-discord-telegram-slack

Finally Got My Dify Agent Working in Discord, Telegram and Slack

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/dify-agent-discord-telegram-slack).

公開日：2025-12-11 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![Finally Got My Dify Agent Working in Discord, Telegram and Slack](https://langbot.app/docs/images/articles/source/images/covers/dify-agent.png)

Want your Dify Agent to break free from the browser and chat directly in WeChat, QQ, or Telegram? Combine LangBot with Dify and you can set it up in under 10 minutes.

## Why This Combo?

[**LangBot**](https://github.com/langbot-app/LangBot) is the most powerful open-source multi-platform chatbot framework available. It supports major Chinese IMs (QQ, WeChat, Feishu, DingTalk) and international platforms (Telegram, Discord, Slack, LINE). Its core strength is connecting AI backends to messaging apps.

**Dify** is one of the hottest AI app development platforms, offering visual Agent orchestration, 50+ built-in tools, and RAG knowledge bases. Together, they let you build a multi-platform AI assistant fast.

## Deploy LangBot

Three commands with uvx:

```bash
mkdir langbot-instance
cd langbot-instance
uvx langbot@latest
```

Visit `http://127.0.0.1:5300` and register an admin account:

![LangBot Dashboard](https://langbot.app/docs/images/articles/external/c6d52212ba91-02-langbot-dashboard.png)

## Create a Dify Agent

Log in to [cloud.dify.ai](https://cloud.dify.ai) and create a new app. Choose **Agent** type - unlike basic chat apps, Agents can reason autonomously and call tools for complex tasks.

![Select Agent Type](https://langbot.app/docs/images/articles/external/3e5b1d8ec6ec-07-dify-create-app-types.png)

### Configure the Agent

In the orchestration interface, set up:

**System Instructions** - Define the Agent's role:

```
You are an intelligent assistant that helps users complete various tasks. You have the following capabilities:
1. Answer various user questions
2. Query weather information
3. Retrieve webpage content

Please always maintain a friendly and professional attitude. If you need to use tools to get information, proactively call the relevant tools.
```

**Add Tools** - Pick from Dify's 50+ built-in tools, like Weather and Web Scraper:

![Add Tools](https://langbot.app/docs/images/articles/external/9066d99b172c-11-dify-tools-panel.png)

**Select Model** - Supports GPT, Claude, Gemini, DeepSeek, and other major LLMs.

Final configuration:

![Configuration Complete](https://langbot.app/docs/images/articles/external/be278ca435e8-12-dify-agent-configured.png)

### Get the API Key

Click "Publish", then go to "Access API" to create a key:

![Create API Key](https://langbot.app/docs/images/articles/external/471b316018e5-13-dify-api-key-created.png)

Save the API key and server address `https://api.dify.ai/v1`.

## Connect Dify to LangBot

Back in LangBot, go to Pipelines > ChatPipeline > AI Capability:

![AI Capability Config](https://langbot.app/docs/images/articles/external/8f4b3820ed5b-14-langbot-pipeline-ai-capability.png)

Select **Dify Service API** as the Runner:

![Select Dify Runner](https://langbot.app/docs/images/articles/external/efa6fcae9c58-15-langbot-runner-dropdown.png)

Enter the configuration:

- **Base URL**: `https://api.dify.ai/v1`
- **API Key**: The key you just created
- **App Type**: Chat (including Chatflow)

![Enter Configuration](https://langbot.app/docs/images/articles/external/74f71a8bf1dc-17-langbot-dify-api-key-entered.png)

Save and click "Debug Conversation" to test:

![Test Conversation](https://langbot.app/docs/images/articles/external/9999c12907eb-20-langbot-chat-test.png)

If the Agent responds correctly and calls tools, the integration is working.

## Why This Architecture Rocks

- **Decoupled Design**: Agent capabilities live in Dify, LangBot handles message routing - each does what it's best at
- **One Config, Multi-Platform**: Same Agent serves QQ, WeChat, Telegram, and more simultaneously
- **Easy to Extend**: Add RAG knowledge bases, Workflow orchestration, or more tools in Dify later

## Next Steps

- Configure messaging platforms in LangBot (QQ bot, WeChat personal account, etc.)
- Add more tools in Dify (database queries, API calls)
- Try Dify Chatflow for complex conversation flows

If you're using n8n, FastGPT, Coze, or Langflow, LangBot supports those too.

***

**Resources**

- [LangBot Docs](https://langbot.app/docs/ja/insight/guide.md) | [GitHub](https://github.com/langbot-app/LangBot)
- [Dify Docs](https://docs.dify.ai) | [Cloud Platform](https://cloud.dify.ai)

---

# LangBot 4.6.0 外部ナレッジベース入門：Dify と連携した RAG 会話

Source: https://langbot.app/docs/ja/articles/dify-langbot-rag-knowledge-base

LangBot 4.6.0 External Knowledge Base Tutorial: Integrating Dify with LangBot for RAG-powered Conversations

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/dify-langbot-rag-knowledge-base).

公開日：2025-12-02 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![LangBot 4.6.0 External Knowledge Base Tutorial: Integrating Dify with LangBot for RAG-powered Conversations](https://langbot.app/docs/images/articles/source/images/covers/dify-rag.png)

LangBot 4.6.0 introduces external knowledge base functionality, allowing users to integrate external knowledge retrieval services such as Dify and RAGFlow into conversation pipelines. This tutorial demonstrates how to combine Dify knowledge base with LangBot to enable intelligent conversations based on domain-specific knowledge.

## Feature Overview

The external knowledge base feature enables LangBot to:

- Connect to various external knowledge retrieval services (Dify, RAGFlow, etc.)
- Provide professional answers based on domain-specific knowledge
- Flexibly extend knowledge retrieval capabilities through the plugin system
- Configure conveniently through WebUI without manual configuration file editing

## Prerequisites

Before starting, you need:

1. Deploy LangBot 4.6.0 or higher
2. Have a Dify account (register at <https://cloud.dify.ai>)
3. Configure a conversation model (this tutorial uses claude-opus-4-1-20250805)

## Step 1: Deploy LangBot

### 1.1 View LangBot Repository

First, visit the [LangBot GitHub repository](https://github.com/langbot-app/LangBot) to understand the project. LangBot is a production-grade instant messaging bot development platform supporting multiple messaging platforms and LLM services.

### 1.2 Learn About External Knowledge Base Feature

Visit the [official LangBot documentation](https://langbot.app/docs/ja/insight/guide.md) to view the external knowledge base usage instructions. The documentation provides detailed explanations on how to build built-in knowledge bases and connect to external knowledge bases.

### 1.3 Start LangBot

Use the `uvx langbot` command to quickly start LangBot, then visit <http://127.0.0.1:5300> for initialization. Fill in your email and password to complete registration, then log in.

### 1.4 Dashboard After Login

After successfully logging in, you will see the LangBot WebUI dashboard.

## Step 2: Configure Conversation Model

Before using the knowledge base, you need to configure a conversation model.

### 2.1 Navigate to Model Configuration Page

Click "Models" in the left navigation bar to enter the model configuration page.

### 2.2 Add New Model

Click the "+" button to open the model configuration dialog.

### 2.3 Fill in Model Information

Fill in the following information:

- **Model Name**: claude-opus-4-1-20250805
- **Model Provider**: New API
- **Request URL**: Your API endpoint
- **API Key**: Your API Key
- **Abilities**: Check Vision Ability and Function Call

Click "Submit" to save the configuration.

## Step 3: Create Knowledge Base in Dify

### 3.1 Log in to Dify Platform

Visit <https://cloud.dify.ai> and log in to your account.

### 3.2 Navigate to Knowledge Page

Click "Knowledge" in the top navigation bar to enter the knowledge base management page.

### 3.3 Create New Knowledge Base

Click "Create Knowledge" to start creating a knowledge base.

### 3.4 Select Data Source

You can choose from the following methods to import data:

- **Import from file**: Upload document files
- **Sync from Notion**: Sync from Notion
- **Sync from website**: Crawl website content

This tutorial selects "Import from file" and uploads prepared LangBot documentation.

### 3.5 Upload Document

After uploading the document, the system will display file information. Click "Next" to proceed.

### 3.6 Configure Document Processing Parameters

On the document processing page, you can configure chunk settings, index method, and retrieval settings:

- **Chunk Settings**: General mode, maximum chunk length 1024 characters
- **Index Method**: High Quality (uses embedding model)
- **Retrieval Setting**: Vector Search

Click "Save & Process" to start processing the document.

### 3.7 Knowledge Base Processing

The system starts processing the document and generating vector embeddings.

### 3.8 Embedding Completed

After processing is complete, the knowledge base is ready to use.

## Step 4: Get Dify API Information

### 4.1 Open Service API Panel

Click the "Service API" button in the bottom right. Record the following information:

- **Service API Endpoint**: <https://api.dify.ai/v1>
- **Dataset ID**: Get from the URL

### 4.2 Get API Key

Click the "API Key" button to view the API key. Record your API Key for use in subsequent configuration.

## Step 5: Configure External Knowledge Base in LangBot

### 5.1 Navigate to Knowledge Page

In the LangBot WebUI, click "Knowledge" in the left navigation bar.

### 5.2 Switch to External Knowledge Base Tab

Click the "External" tab.

### 5.3 Add External Knowledge Base

Click the "+" button to open the add external knowledge base dialog. In this dialog, you need to:

1. **Knowledge Base Name**: Give the knowledge base a name
2. **Knowledge Base Description**: Add a description (optional)
3. **Retriever**: Select a knowledge retriever plugin

**Note**: Using an external knowledge base requires installing the corresponding knowledge retriever plugin first. You can search for and install the Dify knowledge retriever plugin in the [plugin marketplace](https://space.langbot.app/market?category=KnowledgeRetriever).

After installing the plugin, select the corresponding plugin from the Retriever dropdown, then fill in the configuration information obtained from Dify (API Endpoint, API Key, Dataset ID).

## Step 6: Configure Pipeline

After configuring the external knowledge base, you need to enable it in the pipeline:

1. Navigate to the "Pipelines" page
2. Edit or create a new pipeline
3. On the "AI Capabilities" page, select "Built-in Agent" as the runner
4. In the knowledge base selection, check the external knowledge base you just configured
5. Save the pipeline configuration

## Step 7: Test the Effect

Test in the pipeline's "Conversation Testing" page, or bind the pipeline to a bot for actual conversation testing. When users ask questions, LangBot will automatically retrieve relevant content from the Dify knowledge base and generate answers combined with the retrieved knowledge.

## Frequently Asked Questions

### 1. How to Install Knowledge Retriever Plugins?

Visit the [LangBot plugin marketplace](https://space.langbot.app/market), search for "Knowledge Retriever" or "Dify", find the corresponding plugin and click install.

### 2. Which External Knowledge Retrieval Services Are Supported?

LangBot currently supports multiple external knowledge retrieval services through the plugin system, including:

- Dify
- RAGFlow
- Other custom knowledge retrieval services

Specific supported services can be viewed in the plugin marketplace.

### 3. What's the Difference Between External and Built-in Knowledge Bases?

- **Built-in Knowledge Base**: Data is stored locally in LangBot, with LangBot handling vectorization and retrieval
- **External Knowledge Base**: Data is stored in external services (like Dify), with retrieval performed through API calls

The advantage of external knowledge bases is the ability to leverage the capabilities of professional LLMOps platforms, such as Dify's advanced document processing and multiple retrieval strategies.

### 4. Can Multiple Knowledge Bases Be Used Simultaneously?

Yes. In the pipeline configuration, you can check multiple knowledge bases (built-in or external) simultaneously, and LangBot will comprehensively utilize the content from these knowledge bases to generate answers.

## Summary

Through this tutorial, you learned how to:

1. Create a knowledge base and upload documents on the Dify platform
2. Obtain Dify API key and related configuration information
3. Configure a conversation model in LangBot
4. Add an external knowledge base in LangBot
5. Configure pipelines to use external knowledge bases

The external knowledge base feature provides LangBot with more powerful and flexible knowledge management capabilities. Combined with professional LLMOps platforms like Dify, you can build more intelligent and professional conversational bots.

## Related Resources

- [LangBot Official Website](https://langbot.app)
- [LangBot Documentation](https://langbot.app/docs/ja/insight/guide.md)
- [LangBot GitHub](https://github.com/langbot-app/LangBot)
- [Dify Official Website](https://dify.ai)
- [LangBot Plugin Marketplace](https://space.langbot.app/market)

---

# 新しい LangBot Cloud が公開—オープンソース版もマルチユーザー Workspace に対応

Source: https://langbot.app/docs/ja/articles/langbot-cloud-multi-user-workspaces

LangBot は LLM とメッセージングアプリを接続するオープンソース AI Bot プラットフォームです。新しい Cloud とオープンソース版はマルチユーザー Workspace、招待、ロール権限に対応しました。

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/ja/blog/langbot-cloud-multi-user-workspaces).

公開日：2026-08-25 · 著者：LangBot Team

![LangBot マルチユーザー Workspace ダッシュボード](https://langbot.app/docs/images/articles/source/images/cloud-multi-user/oss-dashboard.png)

新しい [LangBot Cloud](https://cloud.langbot.app) を公開しました。今回まず整理したのは、複数人で LangBot を使うときに、誰がどのリソースへアクセスできるかという実務的な問題です。

同じマルチユーザーの基盤は、オープンソース版でも利用できます。Cloud とセルフホスト版では運用方法が異なりますが、メンバー、招待、権限の基本的な考え方は共通になりました。

## LangBot とは

LangBot は、複数のメッセージングアプリで AI Bot を構築・運用するためのオープンソースプラットフォームです。1つのダッシュボードで Bot、メッセージ Pipeline、ナレッジベース、モデル、拡張機能を管理し、LINE、Slack、Discord、Telegram、QQ、WeChat、WeCom、Lark、DingTalk、KOOK に接続できます。Satori と Matrix にも対応し、Matrix ブリッジを使えば WhatsApp、Signal、Messenger、Mattermost、Google Chat、IRC、XMPP、Zulip などにも展開できます。

モデルは特定の事業者に限定されません。OpenAI、Anthropic Claude、DeepSeek、Google Gemini、xAI Grok、Moonshot Kimi、Zhipu GLM に接続でき、Ollama と LM Studio ではローカルモデルも利用できます。SiliconFlow、Alibaba Cloud Model Studio（百錬）、Volcengine Ark、ModelScope、GiteeAI などのゲートウェイに加え、Dify と MCP を使った既存の Agent ワークフローにも対応します。

チームは複数のチャットサービス上の AI アシスタントを1か所で管理し、用途に応じてクラウドモデル、ローカルモデル、既存の Agent ワークフローを使い分けられます。

![新しい LangBot Cloud のログイン画面](https://langbot.app/docs/images/articles/source/images/cloud-multi-user/cloud-login.png)

## Cloud：自分の Workspace から始める

LangBot Cloud は LangBot Account でログインします。初回利用時には個人用 Workspace が用意され、招待を受けてチームの Workspace に参加できます。複数の Workspace に所属している場合は、画面上で作業先を切り替えられます。

Bot、Pipeline、モデル、ナレッジベース、拡張機能は、現在選択している Workspace に属します。Workspace を切り替えても、別のチームの設定やデータが混ざることはありません。

ホスティング、更新、実行環境は引き続き Cloud 側が管理します。サーバーを保守せず、チームですぐに Bot の設定を始めたい場合に向いています。

## 管理者アカウントを共有せず、メンバーを招待

Owner、またはメンバー管理権限を持つロールは、一度だけ使える招待を発行できます。招待された人は自分のアカウントで参加し、割り当てられたロールで Workspace を利用します。

![Workspace 名を匿名化した LangBot Cloud の招待画面](https://langbot.app/docs/images/articles/source/images/cloud-multi-user/cloud-invitation.png)

1つの管理者パスワードを共有するより、長期運用に適した形です。利用者ごとに独立した本人性があり、担当に合わせて権限を分けられます。

現在は5つの固定ロールを用意しています。

- **Owner**：Workspace の所有者。最上位の権限とメンバー管理を担当します。
- **Admin**：メンバーと大部分の Workspace 設定を管理します。
- **Developer**：Bot、Pipeline、モデル、拡張機能を設定します。
- **Operator**：日常的な運用操作を担当します。
- **Viewer**：読み取り専用で確認します。

## オープンソース版：1インスタンス、1 Workspace、複数ユーザー

セルフホスト版がマルチ Workspace の SaaS になるわけではありません。1つの LangBot インスタンスは引き続き1つの Workspace に対応しますが、その Workspace に複数のユーザーを追加できます。

初期設定で作成したアカウントが Owner になります。その後、ほかのメンバーを招待できます。SMTP を設定している場合は招待メールを送信でき、メール設定がない場合は一度だけ表示される招待リンクを信頼できる手段で共有できます。

参加後に使うのは、これまでと同じ LangBot のダッシュボードです。異なる点は、ログインした全員を管理者として扱うのではなく、Workspace とロールの両方に基づいてアクセスを確認することです。

## どちらを選ぶべきか

|           | LangBot Cloud   | オープンソース・セルフホスト版       |
| --------- | --------------- | --------------------- |
| 導入と保守     | LangBot がホスト・保守 | サーバーとデータを自分で管理        |
| Workspace | 複数を所有・参加可能      | 1インスタンスにつき1つ          |
| メンバーと招待   | 対応              | 対応                    |
| 固定ロール権限   | 対応              | 対応                    |
| 向いている用途   | チームですぐに使い始める    | プライベート環境とインフラを自分で管理する |

ホスト版を使う場合は [cloud.langbot.app](https://cloud.langbot.app) へ。実行環境とデータを自分のサーバーに置く場合は、[GitHub](https://github.com/langbot-app/LangBot) からオープンソース版を導入できます。

---

# LangBot プラグインシステム詳解：プロセス分離・イベント駆動・コンポーネント設計

Source: https://langbot.app/docs/ja/articles/langbot-plugin-system-deep-dive

A source-level deep dive into LangBot 4.0's plugin architecture — process-isolated communication, event-driven hooks, a component-based extension model, and comparisons with Dify and MCP.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/langbot-plugin-system-deep-dive).

公開日：2026-02-23 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![LangBot Plugin System](https://langbot.app/docs/images/articles/source/images/covers/plugin-system.png)

Most chatbot frameworks call their "plugin system" a glorified dynamic import of Python modules. LangBot 4.0 takes a harder but more principled approach — **every plugin runs in its own process**, communicating with the host through a structured JSON-RPC-style protocol.

This article dissects the system from source code, end to end.

## Overall Architecture: A Three-Layer Process Model

LangBot's plugin system consists of three cooperating process layers:

![LangBot Plugin System Architecture](https://langbot.app/docs/images/articles/source/images/plugin-system/architecture.png)

**Each layer has a distinct responsibility:**

1. **LangBot Main Process**: Runs business logic (message pipelines, platform adapters, model invocations), connects to Runtime via `PluginRuntimeConnector`.
2. **Plugin Runtime**: The orchestration layer — discovers, launches, and manages all plugin subprocesses, routes requests from the main process to the appropriate plugin.
3. **Plugin Subprocesses**: Each plugin runs in its own Python process, communicating with Runtime via stdio pipes.

### Why Three Layers Instead of Two?

The intuitive design would have the main process manage plugin processes directly. LangBot adds the Runtime layer for **deployment flexibility**:

- **Local development**: Main process spawns Runtime as a child via stdio (zero config)
- **Docker production**: Runtime runs as a separate container, connected via WebSocket
- **Windows compatibility**: Since Windows asyncio has incomplete stdio subprocess support, it automatically falls back to WebSocket

The same codebase — no config changes — adapts from development to production.

## Communication Protocol: JSON-RPC-Style Request/Response

All cross-process communication runs on a unified protocol layer. The core data structures are minimal:

```python
# Request
class ActionRequest(pydantic.BaseModel):
    seq_id: int    # Sequence number for matching request/response
    action: str    # Action name
    data: dict     # Payload

# Response
class ActionResponse(pydantic.BaseModel):
    seq_id: int
    code: int           # 0 = success
    message: str
    data: dict
    chunk_status: str   # "continue" | "end" (streaming support)
```

The `Handler` class is the system's core abstraction, acting as both RPC client and server:

```python
class Handler:
    async def call_action(self, action, data, timeout=15.0) -> dict:
        """Actively call an action provided by the peer, wait for response"""
        self.seq_id_index += 1
        request = ActionRequest.make_request(self.seq_id_index, action.value, data)
        future = asyncio.Future()
        self.resp_waiters[self.seq_id_index] = future
        await self.conn.send(json.dumps(request.model_dump()))
        response = await asyncio.wait_for(future, timeout)
        return response.data

    @action(SomeAction.DO_SOMETHING)
    async def handle_something(data: dict) -> ActionResponse:
        """Register an action for the peer to call"""
        return ActionResponse.success({"result": "ok"})
```

**Key design points:**

- `seq_id`-based request/response matching enables full-duplex concurrent calls
- Streaming responses via `chunk_status` for long-running operations like command execution
- Large messages auto-chunk (stdio: 16KB / WebSocket: 64KB per chunk)
- File transfer uses a separate base64 chunking mechanism

### Action Enums: Clear API Contracts

The system defines all cross-process calls through four enum groups:

```python
# Plugin → Runtime (plugin-initiated requests)
class PluginToRuntimeAction:
    REGISTER_PLUGIN = "register_plugin"
    SEND_MESSAGE = "send_message"        # Send message to a platform
    INVOKE_LLM = "invoke_llm"           # Call an LLM
    SET_PLUGIN_STORAGE = "set_plugin_storage"  # Persistent storage
    # ...

# Runtime → Plugin (runtime-dispatched commands)
class RuntimeToPluginAction:
    INITIALIZE_PLUGIN = "initialize_plugin"
    EMIT_EVENT = "emit_event"
    CALL_TOOL = "call_tool"
    EXECUTE_COMMAND = "execute_command"
    SHUTDOWN = "shutdown"
    # ...

# LangBot Main → Runtime
class LangBotToRuntimeAction:
    INSTALL_PLUGIN = "install_plugin"
    EMIT_EVENT = "emit_event"
    LIST_TOOLS = "list_tools"
    # ...

# Runtime → LangBot Main
class RuntimeToLangBotAction:
    GET_PLUGIN_SETTINGS = "get_plugin_settings"
    SET_BINARY_STORAGE = "set_binary_storage"
    # ...
```

This makes API boundaries crystal clear — what a plugin can and cannot do is defined entirely by these enums.

## Plugin Lifecycle

A plugin goes through these stages from installation to execution:

### 1. Discovery

On startup, Runtime scans the `data/plugins/` directory:

```python
async def launch_all_plugins(self):
    for plugin_path in glob.glob("data/plugins/*"):
        if not os.path.isdir(plugin_path):
            continue
        task = self.launch_plugin(plugin_path)
        self.plugin_run_tasks.append(task)
```

Directory names follow the `{author}__{name}` convention, each containing a `manifest.yaml` and plugin code.

### 2. Launch

Runtime spawns an independent subprocess for each plugin:

```python
async def launch_plugin(self, plugin_path: str):
    python_path = sys.executable
    args = ["-m", "langbot_plugin.cli.__init__", "run", "-s", "--prod"]

    ctrl = StdioClientController(
        command=python_path,
        args=args,
        working_dir=plugin_path,  # Each plugin runs in its own directory
    )
    await ctrl.run(new_plugin_connection_callback)
```

**Key detail**: The subprocess working directory is set to the plugin's own directory — natural filesystem isolation.

### 3. Registration

After starting, the plugin process actively registers itself with Runtime:

```python
# Runtime-side registration handler
async def register_plugin(self, handler, container_data, debug_plugin=False):
    plugin_container = PluginContainer.from_dict(container_data)
    # Fetch plugin settings from the main process
    plugin_settings = await self.context.control_handler.call_action(
        RuntimeToLangBotAction.GET_PLUGIN_SETTINGS, {...}
    )
    # Initialize the plugin (send config)
    await handler.initialize_plugin(plugin_settings)
    # Store the plugin container
    self.plugins.append(plugin_container)
```

### 4. Running

Once in `INITIALIZED` state, the plugin can receive events, tool calls, and command executions.

### 5. Shutdown

```python
async def shutdown_plugin(self, plugin_container):
    # 1. Notify the plugin to shut down gracefully
    await plugin_container._runtime_plugin_handler.shutdown_plugin()
    # 2. Close the communication connection
    await plugin_container._runtime_plugin_handler.conn.close()
    # 3. Kill the subprocess
    if handler.stdio_process is not None:
        handler.stdio_process.kill()
        await asyncio.wait_for(handler.stdio_process.wait(), timeout=2)
```

## Component System: Four Extension Types

A LangBot plugin isn't a single hook function — it's a **component container**. A single plugin can provide multiple component types simultaneously:

### EventListener

The most fundamental extension — listen for events in the message pipeline:

```python
from langbot_plugin.api.definition.components.common.event_listener import EventListener
from langbot_plugin.api.entities.events import PersonNormalMessageReceived
from langbot_plugin.api.entities.context import EventContext

class MyListener(EventListener):
    @EventListener.handler(PersonNormalMessageReceived)
    async def on_person_message(self, ctx: EventContext):
        event = ctx.event
        # Modify the user message before it reaches the LLM
        event.user_message_alter = "Answer in poetry: " + event.text_message

        # Or block further processing
        # ctx.prevent_default()
        # ctx.prevent_postorder()
```

Supported events cover the full message lifecycle:

| Event                         | Trigger                            |
| ----------------------------- | ---------------------------------- |
| `PersonMessageReceived`       | Any private message received       |
| `GroupMessageReceived`        | Any group message received         |
| `PersonNormalMessageReceived` | Private message deemed processable |
| `GroupNormalMessageReceived`  | Group message deemed processable   |
| `NormalMessageResponded`      | LLM response completed             |
| `PromptPreProcessing`         | Prompt preprocessing stage         |

Event propagation supports two interruption modes:

- `prevent_default()`: Skip default behavior (e.g., skip the LLM call)
- `prevent_postorder()`: Stop subsequent plugins from running

### Tool

Tools for LLM Function Calling:

```python
from langbot_plugin.api.definition.components.tool.tool import Tool

class WeatherTool(Tool):
    async def call(self, params: dict, session, query_id: int) -> str:
        city = params.get("city", "Beijing")
        # Call weather API...
        return f"{city}: Sunny, 25°C"
```

Tool metadata (name, description, parameter schema) is defined in a companion YAML manifest file. LangBot automatically converts this into the Function definition that LLMs understand.

### Command

User-triggered commands via `!command`, with subcommand support:

```python
from langbot_plugin.api.definition.components.command.command import Command

class MyCommand(Command):
    def __init__(self):
        super().__init__()

        @self.subcommand("hello", help="Say hello")
        async def hello(self, ctx):
            yield CommandReturn(text="Hello from plugin!")

        @self.subcommand("status", help="Show status")
        async def status(self, ctx):
            yield CommandReturn(text="All systems operational.")
```

Command results are returned via `AsyncGenerator`, providing natural streaming output.

### KnowledgeRetriever

A multi-instance component for connecting external knowledge bases:

```python
from langbot_plugin.api.definition.components.knowledge_retriever.retriever import KnowledgeRetriever

class MyRetriever(KnowledgeRetriever):
    async def retrieve(self, context) -> list:
        results = await self.search_external_db(context.query)
        return [RetrievalResultEntry(content=r) for r in results]
```

KnowledgeRetriever is a **polymorphic component** — a single retriever class can spawn multiple instances, each with independent configuration. This allows users to connect multiple different external knowledge bases.

## SDK API: What Plugins Can Do

Plugins gain rich capabilities through the `LangBotAPIProxy` inherited by `BasePlugin`:

```python
class LangBotAPIProxy:
    # Message operations
    async def send_message(self, bot_uuid, target_type, target_id, message_chain)

    # Model invocation
    async def get_llm_models(self) -> list[str]
    async def invoke_llm(self, model_uuid, messages, funcs=[], extra_args={})

    # Persistent storage (plugin-level isolation)
    async def set_plugin_storage(self, key, value: bytes)
    async def get_plugin_storage(self, key) -> bytes

    # Workspace storage (cross-plugin shared)
    async def set_workspace_storage(self, key, value: bytes)
    async def get_workspace_storage(self, key) -> bytes

    # System info
    async def get_langbot_version(self) -> str
    async def get_bots(self) -> list[str]
    async def list_plugins_manifest(self) -> list
```

**The storage API design is worth noting**: Two levels of KV storage — `plugin_storage` (plugin-private) and `workspace_storage` (globally shared), storing data as bytes (base64-serialized in transit). Simple but flexible enough.

## Event Dispatch Mechanism

The complete path from main process to plugin:

![Event Dispatch Flow](https://langbot.app/docs/images/articles/source/images/plugin-system/event-dispatch.png)

Key source code:

```python
async def emit_event(self, event_context, include_plugins=None):
    for plugin in self.plugins:
        if plugin.status != RuntimeContainerStatus.INITIALIZED:
            continue
        if not plugin.enabled:
            continue

        # Pipeline-level plugin filtering
        if include_plugins is not None:
            plugin_id = f"{plugin.manifest.metadata.author}/{plugin.manifest.metadata.name}"
            if plugin_id not in include_plugins:
                continue

        resp = await plugin._runtime_plugin_handler.emit_event(
            event_context.model_dump()
        )

        event_context = EventContext.model_validate(resp["event_context"])

        # Plugin requested propagation stop
        if event_context.is_prevented_postorder():
            break

    return emitted_plugins, event_context
```

The `include_plugins` parameter enables **pipeline-level plugin binding** — different message processing pipelines can use different subsets of plugins.

## Installation & Distribution

Plugins support three installation sources:

1. **Local upload**: `.lbpkg` files (actually zip archives containing manifest.yaml and code)
2. **Marketplace**: Install from LangBot Space online
3. **GitHub Release**: Download from a GitHub repository's Release assets

The installation flow:

```python
async def install_plugin(self, source, install_info):
    yield {"current_action": "downloading plugin package"}
    # 1. Fetch and extract the plugin package (unzip)
    plugin_path, author, name, version = await self.install_plugin_from_file(plugin_file)

    yield {"current_action": "installing dependencies"}
    # 2. Install dependencies (pip install -r requirements.txt)
    pkgmgr_helper.install_requirements(requirements_file)

    yield {"current_action": "initializing plugin settings"}
    # 3. Initialize configuration
    await self.context.control_handler.call_action(
        RuntimeToLangBotAction.INITIALIZE_PLUGIN_SETTINGS, {...}
    )

    yield {"current_action": "launching plugin"}
    # 4. Launch the plugin process
    task = self.launch_plugin(plugin_path)
```

The entire process reports progress via `AsyncGenerator`, enabling real-time installation status in the frontend.

## Developer Experience

The SDK provides a complete developer toolchain:

```bash
# Initialize a new plugin
lbp init

# Add a component
lbp component add

# Run locally for debugging
lbp run

# Package for publication
lbp publish
```

**Debug mode** has a particularly clever design: the developer's plugin connects to the running Runtime via WebSocket (instead of stdio), meaning you can hot-reload plugin code without restarting LangBot. Debug plugins are specially marked in the UI and protected from accidental deletion.

## Comparisons with Other Systems

### vs Dify Plugins

Dify's plugin system (`dify-plugin-daemon`) shares the process isolation philosophy with LangBot, but the focus differs:

- **Dify**: Plugins extend workflow node types (Tool, Model, Extension) — designed for AI application orchestration
- **LangBot**: Plugins extend the message processing pipeline (Event, Tool, Command, KnowledgeRetriever) — designed for instant messaging scenarios

LangBot's `EventListener` component provides a capability Dify lacks — injecting logic at any stage of message processing.

### vs MCP (Model Context Protocol)

MCP is a standardized protocol for AI tool invocation. LangBot's Tool component and MCP services overlap functionally, but serve different purposes:

- **MCP**: A universal "AI calls external capabilities" protocol, usable by any LLM application
- **LangBot Tool**: Deeply integrated with message processing context, with access to session info, user identity, etc.

In practice, LangBot natively supports MCP — users can configure MCP servers directly in LangBot without writing plugins. LangBot's Tool component is for scenarios requiring access to LangBot's internal context.

## Design Decisions Explained

**Why process isolation instead of threads/coroutines?**

- Plugin code quality is unpredictable; a segfault shouldn't crash the entire service
- Dependency isolation: different plugins may depend on different versions of the same library
- Resource control: you can set per-plugin process resource limits

**Why JSON instead of Protobuf/MessagePack?**

- Debug-friendly: developers can directly read communication logs
- Natively supported in Python, no extra dependencies
- The performance bottleneck isn't serialization (plugin call frequency is far below database queries)

**Why stdio over WebSocket by default?**

- stdio requires no network stack — lower latency
- Simpler process lifecycle management (child processes auto-cleanup when parent exits)
- WebSocket is only used where stdio isn't supported (Docker, Windows)

## Conclusion

LangBot's plugin system is a **production-grade, process-isolated, event-driven component framework for extensibility**.

Its core design principles:

1. **Safety first**: Process isolation ensures plugins can't destabilize the main service
2. **Deployment flexibility**: Dual stdio/WebSocket modes adapt to all environments
3. **Developer-friendly**: Complete SDK, CLI, and debug support
4. **Component-based**: Four component types cover the major extension needs

If you're interested in developing LangBot plugins, start with the [plugin development docs](https://langbot.app/docs/en/plugin/dev/tutor.md), or browse existing plugins on the [marketplace](https://space.langbot.app/market) for inspiration.

---

# LangBot v4.10.0：Agent Sandbox と Skills

Source: https://langbot.app/docs/ja/articles/langbot-v4100-sandbox-skills

LangBot v4.10.0 brings a real sandbox (Box Runtime) and an on-demand Skills system to the built-in Agent. It can now run commands and edit files in an isolated environment, and pull in specialized know-how exactly when a task needs it.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/langbot-v4100-sandbox-skills).

公開日：2026-06-04 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![LangBot v4.10.0 Agentic Sandbox & Skills](https://langbot.app/docs/images/articles/source/images/covers/sandbox-skills.png)

LangBot v4.10.0 is our biggest Agent update yet. It ships two features that point in the same direction — **letting the built-in Agent work like a real developer**:

1. **Sandbox**: the Agent now runs in a genuinely isolated environment where it can execute commands and work with files.
2. **Skills**: the Agent can load specialized know-how on demand, instead of cramming everything into its context.

Both capabilities were led by community contributor [@huanghuoguoguo](https://github.com/huanghuoguoguo). Let's dig in.

> **New to LangBot?** [LangBot](https://github.com/langbot-app/LangBot) is an open-source LLM bot platform (15k+ GitHub stars) that lets you deploy AI chatbots across **Discord, Telegram, WeChat (个人微信 / 企业微信), Slack, Lark (Feishu), DingTalk, QQ** and more — all from a single instance. It connects 20+ large language models (OpenAI GPT, Anthropic Claude, Google Gemini, DeepSeek, and others) to 13+ messaging platforms, with built-in Agent, RAG knowledge bases, MCP support, and a plugin ecosystem. You can self-host it with one Docker command or run it managed on [LangBot Cloud](https://space.langbot.app/cloud).

## 📦 Sandbox: a real workspace for your Agent

Until now, LangBot's built-in Agent could only call predefined tools. It couldn't "open a terminal and run a command," nor "write an intermediate result to a file and read it back later" — which is exactly what human developers do all day.

v4.10.0 introduces the new **Box Runtime**. It gives the Agent an isolated sandbox environment with six native tools built in:

| Tool    | Purpose                      |
| ------- | ---------------------------- |
| `exec`  | Run shell commands           |
| `read`  | Read file contents           |
| `write` | Write files                  |
| `edit`  | Make targeted edits to files |
| `glob`  | Find files by pattern        |
| `grep`  | Search inside file contents  |

With this toolkit, the Agent can work like a developer: run a script, save the output to a file, read it back to analyze, and post-process the result. All of it happens inside an isolated environment that never touches the host.

![LangBot sandbox in action](https://langbot.app/docs/images/articles/source/images/sandbox-skills/sandbox.png)

### Pluggable backends

The sandbox's execution backend is **pluggable**, and LangBot selects one automatically based on your deployment:

- **Docker**: spins up a dedicated `langbot_box` container that talks to the main process over WebSocket. Great for containerized deployments.
- **nsjail**: lightweight isolation based on Linux namespaces, no extra container needed. Great for bare-metal or single-container setups.
- **E2B**: cloud sandbox that runs execution in a remote isolated environment.

You don't have to pick manually — `box.enabled` is the master switch. Once on, LangBot probes for the most suitable backend and degrades gracefully if probing fails.

![Sandbox native tools](https://langbot.app/docs/images/articles/source/images/sandbox-skills/sandbox-tools.png)

### It also hosts MCP Servers

Beyond native tools, the Box Runtime takes on another important job: **hosting stdio-mode MCP Servers**.

Previously, stdio-mode MCP Servers had to be spawned as subprocesses directly inside the main process — neither safe nor easy to manage. Now they all run inside the sandbox, sharing the same isolation boundary as the Agent's execution environment. `http` / `sse` mode MCP is unaffected and works as before.

## 🎯 Skills: know-how, loaded on demand

The second big update is **Skills**.

As the Agent's capabilities grow, an old problem surfaces: **the context window is finite**. If you stuff every possible instruction, procedure, and reference doc into the system prompt, the context fills up fast — and most of it is irrelevant to the task at hand.

The design idea behind Skills is simple: **keep the table of contents in view, and open the book only when you need it.**

A Skill is an **on-demand instruction pack** containing:

- **A prompt**: tells the Agent what the skill does and when to use it
- **A procedure**: the steps to accomplish a class of tasks
- **Scripts**: ready-to-run helper scripts
- **Reference files**: API docs, templates, examples, and so on

By default the Agent only sees a **list of available skills** (name + summary), which costs almost nothing in context. When it decides a task needs a particular skill, it pulls the full content just in time via the `activate` action.

![LangBot Skills system](https://langbot.app/docs/images/articles/source/images/sandbox-skills/skills.png)

The benefits are clear:

1. **Lean context**: irrelevant skill content never takes up the window.
2. **Extensible capabilities**: want to teach the Agent a new trick? Write a skill pack — no core code changes.
3. **Instant effect**: skills load dynamically during execution, no restart required.

If you've used Claude's Skills or a similar mechanism, this pattern will feel familiar — it decouples "what the Agent knows" from "what the Agent needs right now."

## 🧩 Shipped early across 4.9.x

These were planned for v4.10.0 but shipped early in the 4.9.x line:

- **Plugin Extension Pages**: plugins can render custom UI via iframe + a Page SDK ([@TyperBody](https://github.com/TyperBody), #2107)
- **Monitoring**: feedback linked to message IDs, plus feedback export ([@6mvp6](https://github.com/6mvp6), #2120)
- **Security hardening**: path-traversal fixes and removal of an authenticated RCE endpoint ([@sebastiondev](https://github.com/sebastiondev), #2087 / #2178)

## 🚀 Getting started

The sandbox needs an execution backend, depending on how you deploy:

- **Docker**: run `docker compose --profile all up`, which also launches the `langbot_box` container.
- **Manual / `uvx`**: runs as a stdio subprocess automatically, nothing to do.
- **LangBot Cloud**: ready out of the box — the sandbox is already set up for you, nothing to install.

To turn the sandbox off, set `box.enabled: false` — built-in tools, Skill create/edit, and stdio-mode MCP are all disabled; `http` / `sse` mode MCP is unaffected. See the [Sandbox docs](https://langbot.app/docs/en/usage/sandbox/readme.md) for details.

This release also upgrades the plugin SDK to **`langbot-plugin 0.4.1`**.

## Closing thoughts

Sandbox and Skills are, at their core, answering the same question: **how do we let an Agent handle genuinely complex, open-ended tasks?**

The sandbox solves the "**hands**" problem — giving the Agent the ability to execute and room to experiment. Skills solve the "**brain**" problem — letting the Agent reach for the right knowledge at the right moment, without drowning in irrelevant information.

The fastest way to try it is to spin up a managed instance on [LangBot Cloud](https://space.langbot.app/cloud), where the sandbox is ready to go. You can also read the [full release notes](https://github.com/langbot-app/LangBot/releases/tag/v4.10.0) for every change.

Thank you to everyone building with LangBot. We'll keep making the cloud Agent experience more stable and more capable.

---

# LangBot v4.9.0：完全プラグイン化された RAG アーキテクチャ

Source: https://langbot.app/docs/ja/articles/langbot-v490-rag-plugin-architecture

LangBot v4.9.0 refactors the entire knowledge base system from a built-in implementation to a plugin-driven architecture, introducing KnowledgeEngine and Parser component types for boundless extensibility.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/langbot-v490-rag-plugin-architecture).

公開日：2026-03-10 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![LangBot v4.9.0 RAG Plugin Architecture](https://langbot.app/docs/images/articles/source/images/covers/rag-plugin.png)

LangBot v4.9.0, codenamed **"Knowledge Without Borders,"** does exactly what the name says: **the entire knowledge base capability has been refactored from a built-in implementation to a plugin-driven architecture.**

This isn't a minor tweak — it redefines what "knowledge" means in LangBot.

## The Problem with the Old Approach

Before v4.9.0, LangBot's knowledge base was split into two separate systems:

- **Built-in Knowledge Base**: Used Chroma as the vector database, with embedding models managed by LangBot directly. Document parsing, chunking, and indexing were all hardcoded.
- **External Knowledge Base**: Bridged services like Dify, RAGFlow, and FastGPT through the `KnowledgeRetriever` plugin component — retrieval only, no document ingestion.

These two systems lived behind separate UI tabs, with completely different data models and management flows.

**Why this was painful:**

1. **Poor extensibility**: Want a different vector database? A custom chunking strategy? Sorry, that's hardcoded.
2. **High maintenance cost**: Every RAG improvement required changes to LangBot's core code and a new release.
3. **Fragmented UX**: Two completely different knowledge base management flows meant a steep learning curve.

v4.9.0 solves this decisively: **extract RAG capabilities from LangBot's core and hand them to plugins.**

## What Changed

### 1. Unified Knowledge Base Model

The `internal` / `external` distinction is gone. All knowledge bases are managed through a single interface, differentiated only by their `rag_engine_plugin_id`. One list, one creation flow — just pick your engine.

### 2. KnowledgeEngine Component

This is the headline addition. `KnowledgeEngine` replaces the old `KnowledgeRetriever` and takes ownership of the full knowledge base lifecycle:

- **Document Ingestion**: The complete pipeline from file parsing to vector indexing
- **Knowledge Retrieval**: Returning relevant chunks at query time
- **Document Deletion**: Cleaning up documents and their associated vector data
- **Lifecycle Hooks**: Callbacks when knowledge bases are created or deleted

A KnowledgeEngine plugin has full control over indexing and retrieval strategies — not just retrieval.

![Knowledge Engine plugins in the Marketplace](https://langbot.app/docs/images/articles/external/b9a33a8551a7-8dd37939-4f10-4046-bd84-cce798005cd4.png)

### 3. Parser Component

Document parsing has been extracted into its own plugin component type. A Parser converts binary files (PDF, Word, Markdown, etc.) into structured text, which is then handed to the RAG engine for chunking and indexing.

**The data flow:**

![Data flow: Parser → KnowledgeEngine](https://langbot.app/docs/images/articles/source/images/rag-plugin/data-flow.png)

If a RAG engine declares `DOC_PARSING` capability, it can handle parsing internally and skip the external Parser.

### 4. Host RAG API

LangBot's core no longer executes RAG operations directly, but it still provides essential infrastructure through `RAGRuntimeService`, accessible to plugins via RPC:

- **Embedding invocation**: `invoke_embedding()` — plugins don't need to manage model connections
- **Vector database operations**: `vector_upsert()` / `vector_search()` / `vector_delete()`
- **File access**: `get_knowledge_file_stream()` — read raw files from storage

This means plugins can focus on RAG strategy (chunking algorithms, retrieval logic, re-ranking) while the host handles the "heavy" operations like vector storage and embedding models.

### 5. KnowledgeRetriever Deprecated

The old `KnowledgeRetriever` component has been removed. If you had external knowledge base plugins, they'll need to migrate to `KnowledgeEngine`. The good news: the new API is cleaner and migration is straightforward.

## Building a RAG Engine Plugin

### Scaffold the Component

```bash
lbp comp KnowledgeEngine
```

This generates the directory structure:

![Plugin directory structure](https://langbot.app/docs/images/articles/source/images/rag-plugin/dir-structure.png)

### Define Configuration Schemas

The YAML manifest defines two configuration schemas:

- **`creation_schema`**: Parameters filled when creating a knowledge base (e.g., chunk size, embedding model)
- **`retrieval_schema`**: Parameters adjustable at retrieval time (e.g., score threshold, top-K)

```yaml
spec:
  creation_schema:
    - name: chunk_size
      label:
        en_US: Chunk Size
      type: integer
      default: 500
    - name: chunk_overlap
      label:
        en_US: Chunk Overlap
      type: integer
      default: 50
  retrieval_schema:
    - name: score_threshold
      label:
        en_US: Score Threshold
      type: float
      default: 0.5
```

LangBot **dynamically renders** creation and retrieval forms based on these schemas — different engines show different configuration fields.

### Declare Capabilities

```python
class SimpleRag(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return [
            KnowledgeEngineCapability.DOC_INGESTION,   # Supports document upload
            # KnowledgeEngineCapability.DOC_PARSING,   # Optional: built-in parsing
        ]
```

| Capability      | Description                                                                             |
| --------------- | --------------------------------------------------------------------------------------- |
| `DOC_INGESTION` | Supports document upload and processing. UI shows "Documents" tab                       |
| `DOC_PARSING`   | Supports built-in document parsing. Without this, an external Parser plugin is required |

### Implement Core Methods

The three essential methods:

**Document Ingestion:**

```python
async def ingest(self, context: IngestionContext) -> IngestionResult:
    # 1. Get file content (or use Parser's pre-parsed result)
    if context.parsed_content:
        text = context.parsed_content.text
    else:
        file_bytes = await self.plugin.get_knowledge_file_stream(
            context.file_object.storage_path
        )
        text = file_bytes.decode('utf-8')

    # 2. Chunk the text
    chunks = self._split_text(text, chunk_size=500)

    # 3. Call host embedding model
    vectors = await self.plugin.invoke_embedding(
        embedding_model_uuid, chunks
    )

    # 4. Write to host vector database
    await self.plugin.vector_upsert(
        collection_id, vectors, ids, metadata
    )

    return IngestionResult(
        document_id=context.file_object.metadata.document_id,
        status=DocumentStatus.COMPLETED,
        chunks_created=len(chunks),
    )
```

**Knowledge Retrieval:**

```python
async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
    # 1. Generate query vector
    query_vectors = await self.plugin.invoke_embedding(
        embedding_model_uuid, [context.query]
    )

    # 2. Vector search
    results = await self.plugin.vector_search(
        collection_id, query_vectors[0], top_k=5
    )

    # 3. Convert and return
    return RetrievalResponse(results=entries, total_found=len(entries))
```

**Document Deletion:**

```python
async def delete_document(self, kb_id: str, document_id: str) -> bool:
    deleted = await self.plugin.vector_delete(
        collection_id=kb_id, file_ids=[document_id]
    )
    return deleted > 0
```

### Bridging External Services

If your goal is to bridge Dify, RAGFlow, FastGPT, or other external services rather than building a custom RAG pipeline, the implementation is even simpler — **don't declare `DOC_INGESTION` capability** and only implement `retrieve`:

```python
class DifyRAGEngine(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return []  # No document upload — managed externally

    async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
        # Call Dify/RAGFlow/FastGPT retrieval API
        ...
```

The knowledge base won't show a "Documents" tab — all content management happens in the external service.

## Building a Parser Plugin

Parser development is even more concise:

```bash
lbp comp Parser
```

Declare supported MIME types in the manifest:

```yaml
spec:
  supported_mime_types:
    - application/pdf
    - application/vnd.openxmlformats-officedocument.wordprocessingml.document
```

Implement the `parse` method:

```python
class PdfParser(Parser):

    async def parse(self, context: ParseContext) -> ParseResult:
        # context.file_content: raw file bytes
        # context.mime_type: detected MIME type
        # context.filename: original filename

        text = extract_text_from_pdf(context.file_content)

        return ParseResult(
            text=text,
            sections=[
                TextSection(content=page_text, heading=f"Page {i}", page=i)
                for i, page_text in enumerate(pages)
            ],
        )
```

Parsers also support **cross-plugin invocation** — a RAG engine plugin can call another plugin's Parser:

```python
result = await self.plugin.invoke_parser(
    plugin_author="author_name",
    plugin_name="plugin_name",
    storage_path=context.file_object.storage_path,
    mime_type=context.file_object.metadata.mime_type,
    filename=context.file_object.metadata.filename,
)
```

## Upgrade Notes

- Knowledge bases created in previous versions are **automatically migrated**. After updating, visit the Knowledge Base page to verify.
- The `KnowledgeRetriever` component is deprecated. Existing plugins need to migrate to `KnowledgeEngine`.
- Browse the [Plugin Marketplace](https://space.langbot.app/market?category=KnowledgeEngine) for available RAG engine plugins.

## The Bigger Picture

v4.9.0's knowledge base refactoring is the latest step in LangBot's plugin-first evolution. From event handlers and tools in v4.0, to knowledge retrievers, to now full RAG engines and parsers — LangBot's core capabilities are progressively moving from "built-in" to "pluggable."

The endgame: **LangBot's core provides pipeline orchestration and infrastructure; all business capabilities are plugin-driven.**

Custom chunking strategy? Write a KnowledgeEngine plugin. PDF parsing? Write a Parser plugin. Bridge your company's internal knowledge service? Also a plugin.

Knowledge, without borders.

***

**Links:**

- [v4.9.0 Release Notes](https://github.com/langbot-app/LangBot/releases/tag/v4.9.0)
- [KnowledgeEngine Development Guide](https://langbot.app/docs/en/plugin/dev/components/knowledge-engine.md)
- [Parser Development Guide](https://langbot.app/docs/en/plugin/dev/components/parser.md)
- [Plugin Marketplace](https://space.langbot.app/market)
- [LangBot Cloud](https://space.langbot.app/cloud)

---

# Langflow のドラッグ＆ドロップでマルチプラットフォーム AI Bot を構築

Source: https://langbot.app/docs/ja/articles/langflow-drag-and-drop-ai-bot

How I Built a Multi-Platform AI Bot with Langflow's Drag-and-Drop Workflows

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/langflow-drag-and-drop-ai-bot).

公開日：2025-12-05 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![How I Built a Multi-Platform AI Bot with Langflow's Drag-and-Drop Workflows](https://langbot.app/docs/images/articles/source/images/covers/langflow.png)

Drive chatbots across QQ, WeChat, Telegram, Discord, and more using visual workflows - no coding required.

***

[LangBot](https://github.com/langbot-app/LangBot) is an open-source instant messaging bot platform that connects AI workflow engines like Langflow, n8n, Dify, FastGPT, and Coze to platforms including WeChat, QQ, Feishu, DingTalk, Telegram, Discord, Slack, and LINE. This tutorial demonstrates how to use Langflow's visual workflows as LangBot's conversation engine.

## Why This Approach Works

- **True Multi-Platform**: One workflow powering 8+ messaging platforms simultaneously
- **Visual Orchestration**: Drag-and-drop conversation design with conditional branches, multi-turn dialogs, and external API calls
- **Flexible AI Models**: Support for OpenAI, Claude, Gemini, DeepSeek, and local models
- **Fully Open Source**: Both LangBot and Langflow are open-source projects for free deployment and customization

## Prerequisites

- Python 3.10+
- Docker (recommended for quick deployment)
- OpenAI API Key or API keys for other LLM services

## Step 1: Deploy LangBot

Launch with uvx in one command:

```bash
uvx langbot
```

First run auto-initializes and opens your browser to <http://127.0.0.1:5300>.

![LangBot Initial Page](https://langbot.app/docs/images/articles/external/0c8aa2c940ab-01-langbot-initial-page.png)

After registration, log in to access the dashboard:

![LangBot Dashboard](https://langbot.app/docs/images/articles/external/b93d97b5b830-04-langbot-dashboard.png)

## Step 2: Deploy Langflow

Deploy quickly with Docker:

```bash
docker run -d --name langflow -p 7860:7860 langflowai/langflow:latest
```

Visit <http://localhost:7860> to access Langflow:

![Langflow Welcome Page](https://langbot.app/docs/images/articles/external/7e7ebfc3ba58-01-langflow-welcome.png)

## Step 3: Create a Langflow Workflow

In Langflow, select the "Basic Prompting" template to get started quickly:

![Langflow Template Selection](https://langbot.app/docs/images/articles/external/b304cebf8ce9-02-langflow-template-selection.png)

This template includes four basic components:

- **Chat Input**: Receives user messages
- **Prompt**: Sets system instructions
- **Language Model**: Calls LLM to generate responses
- **Chat Output**: Returns results

![Langflow Workflow Editor](https://langbot.app/docs/images/articles/external/6e24402fd4a8-03-langflow-workflow-editor.png)

### Configure Language Model

Click the Language Model component and configure:

1. **Model Provider**: Select OpenAI (or other compatible providers like SiliconFlow, New API)
2. **Model Name**: Select gpt-4o-mini or deepseek-chat
3. **OpenAI API Key**: Enter your API Key

![Langflow OpenAI API Key Configured](https://langbot.app/docs/images/articles/external/bcd91ef5e4b3-14-langflow-openai-api-key-configured.png)

> Tip: You can use OpenAI-compatible API services like SiliconFlow or New API by simply modifying the Base URL.

Save the workflow after configuration.

## Step 4: Get Langflow API Information

### Generate API Key

In Langflow's upper right: Settings → API Keys, navigate to the API Keys page:

![Langflow API Keys Page](https://langbot.app/docs/images/articles/external/21fc47358066-05-langflow-api-keys-page.png)

Click Create New Key:

![Langflow Create API Key Dialog](https://langbot.app/docs/images/articles/external/8f04c7b00759-06-langflow-create-api-key-dialog.png)

Generate and save the API Key:

![Langflow API Key Generated](https://langbot.app/docs/images/articles/external/e5a019491ef8-07-langflow-api-key-generated.png)

Format: `sk-xxxxxxxxxxxxxxxxxxxxxxxx`

### Get Flow ID

Extract from the flow editor's URL:

```
http://localhost:7860/flow/{flow-id}
```

Record this `flow-id`.

## Step 5: Configure Langflow in LangBot

Return to LangBot dashboard and go to **Pipelines** page.

Click ChatPipeline to edit, in the AI tab:

![LangBot Pipeline AI Tab](https://langbot.app/docs/images/articles/external/3c7d6bc96738-08-langbot-pipeline-ai-tab.png)

Configure **Runner**, select **Langflow API**:

![LangBot Runner Dropdown](https://langbot.app/docs/images/articles/external/ef9bbef78165-09-langbot-runner-dropdown.png)

Fill in the Langflow configuration:

![LangBot Langflow Config Form](https://langbot.app/docs/images/articles/external/82d5e2ffb9a0-10-langbot-langflow-config-form.png)

Configuration items:

- **Base URL**: `http://localhost:7860` (local) or `http://langflow:7860` (Docker network)
- **API Key**: The API Key generated in Langflow
- **Flow ID**: The Flow ID recorded earlier

![LangBot Langflow Config Filled](https://langbot.app/docs/images/articles/external/2fb54ce0f7a2-11-langbot-langflow-config-filled.png)

> Docker Tip: If both services run in containers, ensure they're on the same network and use the container name for Base URL.

Click **Save** to save the configuration.

## Step 6: Test the Conversation

Click **Debug Chat** on the Pipelines page to open the debug chat interface:

![LangBot Debug Chat Interface](https://langbot.app/docs/images/articles/external/b36d6dea3702-12-langbot-debug-chat-interface.png)

Enter a test message like "Hello" and view the AI response:

![LangBot Chat Test Success](https://langbot.app/docs/images/articles/external/3d7fa393f210-13-langbot-chat-with-response.png)

## How It Works

1. User sends a message on a messaging platform
2. LangBot receives and passes it to the Pipeline
3. Pipeline calls Langflow API
4. Langflow executes the workflow: receives input → adds prompt → calls LLM → returns result
5. LangBot sends the response back to the user

## Common Issues

**Cannot connect to Langflow?**

Check Base URL. For Docker deployment, ensure containers are on the same network:

```bash
docker network create langbot_network
docker network connect langbot_network langflow
docker network connect langbot_network langbot
```

Use container name: `http://langflow:7860`

**API call fails?**

- Confirm API Key and Flow ID are correct
- Verify the Language Model in Langflow has a valid LLM API Key configured

## Advanced Use Cases

Langflow's power lies in visually orchestrating complex AI workflows:

- **Multi-Turn Memory**: Add Memory components for contextual understanding
- **Conditional Branches**: Execute different logic based on user input
- **External API Integration**: Connect databases, search engines, third-party services
- **Multi-Agent Collaboration**: Multiple LLM models working together
- **RAG Applications**: Integrate vector databases for knowledge base Q\&A

All achievable through drag-and-drop without writing code.

## Summary

With LangBot + Langflow, you can rapidly build powerful multi-platform AI chatbots. Langflow provides visual workflow orchestration, LangBot handles messaging platform integration - together they create a complete loop from workflow design to multi-platform deployment.

This approach is ideal for:

- Scenarios requiring the same AI capabilities across multiple platforms
- Teams wanting rapid iteration and testing of different conversation flows
- Developers wanting to build complex AI applications without deep coding

## Related Resources

- [LangBot Official Site](https://langbot.app) | [Documentation](https://langbot.app/docs/ja/insight/guide.md) | [GitHub](https://github.com/langbot-app/LangBot)
- [Langflow Official Site](https://www.langflow.org) | [Documentation](https://docs.langflow.org) | [GitHub](https://github.com/langflow-ai/langflow)

***

*This article is based on the latest version of LangBot. LangBot supports integration with Dify, n8n, FastGPT, Coze, and other AI platforms - choose the workflow engine that best fits your needs.*

---

# LangTARS：Dify・n8n と連携するオープンソース PC 操作 Agent

Source: https://langbot.app/docs/ja/articles/langtars-remote-pc-control-dify-n8n

LangTARS is a LangBot native plugin that lets you remotely control Mac/Windows/Linux from Telegram, Discord & WeChat — with Dify and n8n workflow support.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/langtars-remote-pc-control-dify-n8n).

公開日：2026-03-23 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![LangTARS Logo](https://langbot.app/docs/images/articles/external/3fe5bdc18716-icon.svg)

**LangBot Native Plugin | OpenClaw-like Experience | Ready to Use with One-Click Deployment**

***

## ✨ What is LangTARS?

**LangTARS** is a powerful **OpenClaw alternative** and native plugin for LangBot, inspired by the loyal and reliable robot TARS from the movie *Interstellar*.

As a versatile **AI agent** for **remote computer control**, LangTARS allows you to remotely command your **Mac, Windows, or Linux** machine directly through your favorite messaging apps like **Telegram, Discord, DingTalk, and WeChat**! If you've been looking for an **OpenClaw-like** computer use agent that integrates seamlessly into your existing **chatbot framework**, LangTARS is the perfect solution.

> 💡 **Deploy LangBot, and you can experience LangTARS instantly!** No extra standalone agent installation needed—just get it with one click from the plugin marketplace.

![LangTARS Demo](https://langbot.app/docs/images/articles/external/70b26e660a60-tars.gif)

***

## 🤖 The LangBot Ecosystem

LangTARS is just ONE plugin in the massive LangBot ecosystem. **LangBot** is a leading **open source chatbot** framework designed for connecting LLMs to messaging platforms.

- **Multi-platform bot integration**: Native support for Telegram, Discord, WeChat, DingTalk, Lark, LINE, Slack, and more.
- **Multi-model LLM chatbot**: Works flawlessly with OpenAI, Claude, Gemini, DeepSeek, and local models.
- **Rich Plugin Marketplace**: Access over 30+ plugins for endless functionality.
- **Advanced Features**: Pipeline-based message processing, RAG support, and multi-agent workflows.
- **Self-hosted AI**: Total control over your data and deployments.
- **AI Workflow Integrations**: Connect LangBot to platforms like **Dify**, **n8n**, **Langflow**, and **Coze**. LangBot can act as the messaging frontend for your complex AI workflows, meaning LangTARS + Dify/n8n = powerful automation!

Get started with LangBot:

- **Easiest**: [LangBot Cloud](https://cloud.langbot.app)
- Self-host: `uvx langbot@latest`
- Documentation: [langbot.app/docs](https://langbot.app/docs/ja/insight/guide.md)
- GitHub: [github.com/langbot-app/LangBot](https://github.com/langbot-app/LangBot) (15k+ stars)

***

## 🎯 What Can It Do?

As a comprehensive **automation tool**, just send a message, and the AI will handle your **task automation** and **browser automation**:

| You Say                                                                                      | AI Does                                                            |
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `!tars open Reddit in Chrome, post a thread with the title "Hello from LangTARS" and say hi` | 🌐 Automatically controls Chrome to open Reddit and publish a post |
| `!tars organize my desktop files`                                                            | 📁 Automatically categorizes and moves files                       |
| `!tars open the browser and search for today's AI news`                                      | 🌐 Opens a browser, searches the web, and summarizes the news      |
| `!tars create a meeting note for our marketing sync`                                         | 📝 Automatically creates a markdown note file                      |
| `!tars check system memory and CPU`                                                          | 💻 Uses MCP tools to get computer status                           |

![Usage Example](https://langbot.app/docs/images/articles/external/6613b3025b8b-usage-example.png)
![Plan Mode](https://langbot.app/docs/images/articles/external/ff42857251ab-planner-mode.png)

***

## 🔗 Supercharge with Dify & n8n

LangTARS becomes even more powerful when combined with **AI workflow platforms**:

- **Dify Integration**: Connect LangBot to [Dify](https://dify.ai) as a messaging frontend. Build complex AI workflows in Dify's visual editor, then trigger them from Telegram/Discord via LangTARS.
- **n8n Integration**: Use [n8n](https://n8n.io) workflows with LangBot for advanced automation chains. Combine LangTARS's computer control with n8n's 400+ integrations for unlimited possibilities.
- **Also supports**: Langflow, Coze, and any OpenAI-compatible API.

> 💡 **Example**: "Hey TARS, run my Dify workflow to analyze today's sales data and save the report to my desktop" — LangTARS handles the entire chain.

***

## 🚀 Why Choose LangTARS?

### 1️⃣ LangBot Native Plugin, Out of the Box

Instead of deploying a complex standalone agent, you can easily **deploy AI bot** capabilities right where you already chat.

```bash
# Deploy LangBot with one command
uvx langbot@latest

# Install LangTARS from the plugin market, configure your LLM, and start using!
```

**No complex configuration, no extra deployment. LangBot users can experience OpenClaw-style computer control directly!**

![Installation Flow](https://langbot.app/docs/images/articles/external/2a3a0d5f4ae9-install-flow.png)

***

### 2️⃣ Intelligent Task Planning, Autonomous Execution

Powered by an AI planning engine based on the **ReAct agent** loop:

```
Your Command → Understand Needs → Make a Plan → Execute Step-by-Step → Feedback Results
```

The AI assistant thinks like a human and automatically breaks down complex tasks using integrated **MCP tools**!

***

### 3️⃣ Multi-Browser Support for Web Automation

| Browser               | macOS | Windows | Linux |
| --------------------- | ----- | ------- | ----- |
| Playwright (Headless) | ✅     | ✅       | ✅     |
| Safari                | ✅     | -       | -     |
| Chrome                | ✅     | ✅       | ✅     |
| Edge                  | -     | ✅       | -     |
| Firefox               | -     | -       | ✅     |

***

### 4️⃣ Security-First Design

- 🚫 **Dangerous Command Interception** — Automatically blocks commands like `rm -rf /`
- 📂 **Workspace Isolation** — Restricts file operations to safe directories
- 📋 **Command Whitelist** — Configurable allowed commands
- 👤 **User Access Control** — Restricts usage to specific authorized users

![Security Features](https://langbot.app/docs/images/articles/external/a618d3d41416-security.png)

***

## 📱 Quick Start

### Step 1: Deploy LangBot

> 🚀 **Fastest way to start:** Use [LangBot Cloud](https://cloud.langbot.app) — deploy your LangBot instance in one click, no server needed! Install LangTARS from the plugin marketplace and start controlling your computer immediately.

*Alternative for power users (Self-hosted):*

```bash
uvx langbot@latest
```

### Step 2: Configure Chat Platform

Follow the documentation to configure your **Telegram bot**, **WeChat bot**, or **Discord bot**.

### Step 3: Install LangTARS

Search for **LangTARS** in the **plugin marketplace** and install it.

### Step 4: Start Chatting

```
!tars Hello, tell me what you can do
```

> 📱 **Recommendation**: Use it on Telegram or Discord for the best interactive experience!

***

## 🎮 Common Commands

| Command                    | Function               |
| -------------------------- | ---------------------- |
| `!tars <Task Description>` | Execute a task         |
| `!tars stop`               | Stop the current task  |
| `!tars what`               | Check execution status |
| `!tars reset`              | Reset the conversation |
| `!tars help`               | Show help              |

***

## 🌟 Project Information

| Item          | Information                                                                |
| ------------- | -------------------------------------------------------------------------- |
| **GitHub**    | [github.com/langbot-app/LangTARS](https://github.com/langbot-app/LangTARS) |
| **Language**  | Python 100%                                                                |
| **License**   | CC BY-NC-ND 4.0                                                            |
| **Platforms** | macOS / Windows / Linux                                                    |

***

## 🔗 Related Links

- 📖 **LangBot Documentation**: [langbot.app/docs](https://langbot.app/docs/ja/insight/guide.md)
- 💬 **Issue Feedback**: [GitHub Issues](https://github.com/langbot-app/LangTARS/issues)
- ⭐ **Support with a Star**: [GitHub](https://github.com/langbot-app/LangTARS)

***

## 🎉 Deploy LangBot and Experience LangTARS!

**Let AI be your loyal digital assistant, just like TARS.**

> 🚀 **Fastest way to start:** Use [LangBot Cloud](https://cloud.langbot.app) — deploy your LangBot instance in one click, no server needed! Install LangTARS from the plugin marketplace and start controlling your computer immediately.

*Alternative for power users (Self-hosted):*

```bash
uvx langbot@latest
```

---

# n8n と LangBot でマルチプラットフォーム AI Chatbot を構築

Source: https://langbot.app/docs/ja/articles/n8n-multi-platform-ai-chatbot

How I Built a Multi-Platform AI Chatbot with n8n and LangBot

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/n8n-multi-platform-ai-chatbot).

公開日：2025-12-03 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![How I Built a Multi-Platform AI Chatbot with n8n and LangBot](https://langbot.app/docs/images/articles/source/images/covers/n8n.png)

Connecting n8n's visual workflow automation with LangBot's multi-platform bot framework creates a powerful, code-free way to deploy AI chatbots across QQ, WeChat, Discord, Telegram, Slack, and more. This tutorial shows you how to integrate these tools in minutes.

## What You'll Need

- Python 3.8+ installed
- Node.js 18+ installed
- npm or npx available
- 15 minutes of your time

## Deploy LangBot in 3 Commands

LangBot is a production-ready bot framework that connects to multiple messaging platforms and AI services including Dify, FastGPT, Coze, OpenAI, Claude, and Gemini. Deploy it instantly:

```bash
cd your-workspace
mkdir -p langbot-instance && cd langbot-instance
uvx langbot@latest
```

On first launch, LangBot initializes automatically. Open `http://127.0.0.1:5300` in your browser.

![LangBot initialization screen](https://langbot.app/docs/images/articles/external/70ee40a6d232-01-langbot-initialization.png)

Register your admin account when prompted. You'll land on the dashboard where you can manage bots, models, pipelines, and integrations.

![LangBot dashboard](https://langbot.app/docs/images/articles/external/4f1f5c28fbfc-03-langbot-dashboard.png)

## Set Up n8n Workflow Automation

n8n is an open-source automation platform with 400+ integrations and powerful AI capabilities. Launch it locally:

```bash
cd your-workspace
mkdir -p n8n-data
export N8N_USER_FOLDER=$(pwd)/n8n-data
npx n8n
```

Visit `http://127.0.0.1:5678` and create your owner account.

![n8n initial setup](https://langbot.app/docs/images/articles/external/12d0e04600c5-05-n8n-setup.png)

## Build Your AI Workflow

Create a new workflow in n8n. You'll need two essential nodes:

![n8n workflow editor](https://langbot.app/docs/images/articles/external/e36d04ca4a5b-07-n8n-workflow-editor.png)

### Add the Webhook Trigger

Click "+" on the canvas and add a **Webhook** node. Configure it:

- **HTTP Method**: POST
- **Response Mode**: Streaming (enables real-time chat responses)
- **Authentication**: None (adjust for production)

![Webhook node configuration](https://langbot.app/docs/images/articles/external/03443176ae5c-08-n8n-webhook-node.png)

### Add the AI Agent

Press Tab, navigate to the "AI" category, and select **AI Agent**.

**Configure the Chat Model**: Click "Chat Model" and choose "OpenAI Chat Model". Add your credentials:

- **API Key**: Your OpenAI API key (or compatible service key)
- **Base URL**: For OpenAI alternatives like Claude, Gemini, or local models, update to your provider's endpoint

**Critical Step - Fix the Prompt Source**: By default, the AI Agent expects a Chat Trigger node, which won't work with webhooks. Here's how to fix it:

1. Find "Source for Prompt (User Message)" in the AI Agent settings
2. Change from "Connected Chat Trigger Node" to "Define below"
3. Switch to "Expression" mode
4. Enter: `{{ $json.body }}`

This expression pulls the user's message from the webhook request body.

![Configured webhook with AI Agent](https://langbot.app/docs/images/articles/external/621f3d526678-09-n8n-webhook-configured.png)

### Activate and Get Your Webhook URL

Save the workflow and toggle the activation switch (top-right). Switch to the "Production URL" tab and copy the webhook URL:

```
http://localhost:5678/webhook/{your-webhook-id}
```

## Connect LangBot to n8n

Back in the LangBot dashboard, navigate to **Pipelines** and click the default "ChatPipeline".

![LangBot pipelines page](https://langbot.app/docs/images/articles/external/ef2b2f83bd16-04-langbot-pipelines.png)

Switch to the **AI** tab and select "n8n Workflow API" from the Runner dropdown. Configure:

- **Webhook URL**: Paste your n8n production webhook URL
- **Authentication Type**: None (match your n8n webhook settings)
- **Timeout**: 120 seconds
- **Output Key**: response

Click **Save**.

## Test It Out

In the Pipeline editor, click "Debug Chat" on the left sidebar. Send a test message like "What is LangBot?"

If everything works, you'll see LangBot send the message to n8n, where the AI Agent processes it and streams back a response.

## Troubleshooting

**Error: "Expected to find the prompt in an input field called 'chatInput'"**

This means the AI Agent is still configured for a Chat Trigger node. Fix it:

1. Open the AI Agent configuration
2. Set "Source for Prompt (User Message)" to "Define below"
3. Switch to Expression mode
4. Enter: `{{ $json.body }}`

**Test Your Webhook Directly**

Verify the webhook works with curl:

```bash
curl -X POST http://localhost:5678/webhook/your-webhook-id \
  -H "Content-Type: application/json" \
  -d '{"body": "Hello, can you introduce yourself?"}'
```

You should receive streaming JSON with the AI's response.

## How the Integration Works

Here's the complete flow:

1. User sends a message via QQ, WeChat, Discord, Telegram, Slack, LINE, or any LangBot-supported platform
2. LangBot's Pipeline receives the message and calls the n8n Workflow API
3. n8n's Webhook node captures the request and passes it to the AI Agent
4. The AI Agent uses OpenAI, Claude, Gemini, or your configured LLM to generate a response
5. n8n streams the response back to LangBot
6. LangBot delivers the response to the user on their original platform

## Why This Combination Works

**LangBot + n8n** unlocks powerful capabilities:

1. **No-Code AI Logic**: Design conversation flows visually in n8n without touching code
2. **Multi-Platform Reach**: Deploy the same AI across QQ, WeChat, Discord, Telegram, Slack, LINE, DingTalk, and Lark simultaneously
3. **Flexible AI Models**: Swap between OpenAI GPT, Anthropic Claude, Google Gemini, Coze, Dify, local models, and more
4. **Rich Integrations**: Connect n8n's 400+ integrations - databases, APIs, Notion, Airtable, Google Sheets, Slack, and beyond
5. **Tool-Calling Agents**: AI Agent can trigger n8n tools like database queries, API calls, or custom functions
6. **Workflow Extensions**: Add preprocessing, content moderation, logging, or custom business logic

**Perfect For**:

- Enterprise customer support bots
- Knowledge base Q\&A systems
- Multi-platform community management
- Task automation assistants
- Unified chat interfaces for teams

## Next Steps

Extend your bot further:

- Integrate Dify or FastGPT for advanced RAG (retrieval-augmented generation)
- Add vector database nodes (Pinecone, Qdrant, Weaviate) for knowledge retrieval
- Connect business APIs for real-time data
- Implement conversation memory and context tracking
- Add content filtering and moderation workflows
- Use Langflow or Coze for additional AI orchestration

This integration gives you the flexibility of code-based AI frameworks like LangChain with the simplicity of visual workflow builders - all while reaching users across every major messaging platform.

Ready to deploy your multi-platform AI assistant? Start with LangBot and n8n today.

---

# LangBot Blog のご紹介

Source: https://langbot.app/docs/ja/articles/welcome

Welcome to the official LangBot blog. Stay up to date with product updates, new features, and milestones.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/welcome).

公開日：2026-02-17 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

![LangBot Blog](https://langbot.app/docs/images/articles/source/images/covers/welcome.png)

We're excited to launch the official LangBot blog! This is where we'll share product updates, new features, milestones, and insights from the LangBot team.

## What is LangBot?

LangBot is an open-source LLM-native instant messaging bot platform. It supports multiple messaging platforms and model providers, with integrations for Dify, Alibaba Cloud Bailian, and other LLMOps platforms. LangBot also provides a WebUI for quick deployment and management.

## What to Expect

On this blog, you'll find:

- **Release Notes** - Detailed breakdowns of each new version
- **Feature Spotlights** - Deep dives into new capabilities
- **Milestones** - Project growth and community achievements
- **Guides & Tips** - Best practices for getting the most out of LangBot

## Stay Connected

- [GitHub](https://github.com/langbot-app/LangBot) - Star us and follow development
- [Documentation](https://langbot.app/docs/ja/insight/guide.md) - Full guides and API reference
- [LangBot Home](https://langbot.app) - Main website

Stay tuned for more updates!

---

# コマンド

Source: https://langbot.app/docs/ja/deploy/command

LangBot コマンドラインリファレンス：ターミナルから AI ボットのインスタンス・設定・ランタイムを管理。

LangBotは`!`で始まるメッセージをコマンドとして認識します。公式では[`EssentialCommands`プラグイン](https://space.langbot.app/market?author=langbot-team\&plugin=EssentialCommands)を提供しており、よく使用されるコマンドが含まれています。

独自のコマンドプラグインを開発することもできます。詳細は[コマンドプラグイン開発](https://langbot.app/docs/en/plugin/dev/components/command.md)を参照してください。

---

# Dockerデプロイ

Source: https://langbot.app/docs/ja/deploy/langbot/docker

Windows、Linux、macOS で Docker Compose を使って LangBot を起動します。

## 1. 環境を準備する

- Git をインストールします。
- **Windows / macOS**：Docker Desktop をインストールして起動します。
- **Linux**：Docker と Docker Compose をインストールします。

## 2. プロジェクトをダウンロードする

書き込み権限のある通常のディレクトリを選んでください。Linux では `/root` や `/etc` などのシステムディレクトリを避け、`/opt` 配下を推奨します。これにより、安全規則によるサンドボックス機能の拒否を避けられます。

プロジェクトを保存したいディレクトリでターミナルを開き（Windows では PowerShell を使用できます）、1 行ずつ実行します：

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
```

### 中国本土：起動前にミラーへ変更する（任意）

Docker Hub からのダウンロードが遅い場合は、先に `LangBot/docker/docker-compose.yaml` を編集し、すべての `rockchin/langbot:latest` を次の値に置き換えてください：

```text
docker.langbot.app/langbot-public/rockchin/langbot:latest
```

保存してから起動してください。ほかの設定変更は不要です。

## 3. LangBot を起動する

> info:
>
> サーバーに設置する場合は、管理画面とランタイムのポートをファイアウォールで制限し、信頼できる接続元だけを許可してください。

同じターミナルで実行します：

```bash
docker compose --profile all up -d
```

初回はコンテナイメージをダウンロードします。Windows / macOS では Docker Desktop を起動したままにしてください。

## 4. 管理画面を開く

- **ローカルにインストールした場合**：`http://localhost:5300` を開きます。
- **サーバーにインストールした場合**：`http://サーバーのIP:5300` を開きます。ファイアウォールで自分の端末からこのポートへのアクセスを許可してください。

画面の案内に従って初期設定を完了し、[モデル](https://langbot.app/docs/ja/usage/models/readme.md)と[ボット](https://langbot.app/docs/ja/usage/platforms/readme.md)を追加してください。

## Beta 版（任意）

上記の安定版の代わりに Beta を試す場合は、[dev/4.11.x の Compose ファイル](https://raw.githubusercontent.com/langbot-app/LangBot/dev/4.11.x/docker/docker-compose.yaml)を別の書き込み可能なディレクトリに `compose.yaml` として保存します。**すべての** `rockchin/langbot` イメージを手動で `rockchin/langbot:beta` に変更してください。対象は Core（`langbot`）、プラグインランタイム（`langbot_plugin_runtime`）、Box（`langbot_box` がある場合）です。`beta` タグは Beta リリースごとに更新されます。そのディレクトリで次を実行して起動・更新します：

```bash
docker compose --profile all pull
docker compose --profile all up -d
```

---

# Kubernetes デプロイ

Source: https://langbot.app/docs/ja/deploy/langbot/kubernetes

Kubernetes 上に LangBot をデプロイし、スケーラブルで本番グレードの AI ボットホスティングを実現。

> warning:
>
> 事前に以下を理解しておく必要があります：
>
> - Kubernetes クラスタの基本操作（`kubectl`、Namespace、Deployment、Service、PVC）
> - コンテナ間ネットワークと永続ストレージの設定方法

LangBot リポジトリの `docker/` ディレクトリには、すぐに使える Kubernetes マニフェスト [`kubernetes.yaml`](https://github.com/langbot-app/LangBot/blob/master/docker/kubernetes.yaml) が用意されています。本ページはこのマニフェストのデプロイガイドで、Docker Compose デプロイと最も異なる部分である **Box サンドボックスランタイム** に焦点を当てます。

## コンポーネント構成

マニフェストは `langbot` ネームスペースに以下のコンポーネントを作成します：

| コンポーネント                  | 説明                      | ポート              |
| ------------------------ | ----------------------- | ---------------- |
| `langbot`                | メインアプリ（WebUI + webhook） | 5300 / 2280-2290 |
| `langbot-plugin-runtime` | プラグインランタイム              | 5400             |
| `langbot-box`            | Box サンドボックスランタイム（任意）    | 5410             |

永続ストレージ：`langbot-data`、`langbot-plugins`、`langbot-plugin-runtime-data` の 3 つの PVC。Box ワークスペースのルートは PVC ではなくノード上の `hostPath`（`/app/data/box`）を使用します。

## クイックスタート

```bash
# リポジトリをクローン
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker

# すべてのコンポーネントをデプロイ
kubectl apply -f kubernetes.yaml

# 状態を確認
kubectl get all -n langbot
```

ポートフォワードで WebUI にアクセスできます：

```bash
kubectl port-forward -n langbot svc/langbot 5300:5300
# http://localhost:5300 にアクセス
```

本番環境では Ingress + TLS での公開を推奨します（マニフェストにはコメントアウトされた Ingress / LoadBalancer / NodePort の例が含まれているので、必要に応じてコメントを解除してください）。

### SeekDB を使用する場合

公式イメージにはオプションの SeekDB 依存関係がすでに含まれているため、専用イメージや追加のビルド引数は不要です。`vdb.use` を `seekdb` に設定すると有効になり、不要な場合はデフォルトの `chroma` のまま使用できます。

## Box サンドボックスランタイム

`langbot-box` は LangBot にコードサンドボックス機能を提供し、サンドボックスツール（`exec` / `read` / `write` / `edit` / `glob` / `grep`）、スキルの `activate` ツールと追加・編集、および stdio モードの MCP サーバーを支えます。これは**任意のコンポーネント**です：デプロイしなくても LangBot は動作し、ダッシュボードとスキル一覧は読み取り専用で表示されますが、上記の機能は無効になります。その場合は `langbot` に `BOX__ENABLED=false` を設定してください。

### 仕組みと重要な制約

LangBot 公式イメージには **Docker CLI のみ**が含まれています（dockerd も nsjail も含まれません）。そのため Box ランタイムは、マウントされたノードの Docker socket（`/var/run/docker.sock`）経由でサンドボックスコンテナを作成します。Pod 内で dockerd を実行するわけではありません。

ここから**重要な制約**が生じます：実際にサンドボックスコンテナを作成するのは**ノード上の Docker デーモン**であり、bind-mount のパスを**ノードのファイルシステム**視点で解決します。したがって Box ワークスペースのルートは、以下の 3 か所で**同一の絶対パス**でなければなりません：

1. ノード上の実際のパス
2. `langbot-box` コンテナ内のマウントパス
3. それが作成する各サンドボックスコンテナ内のマウントパス

これがマニフェストで通常の PVC ではなく `hostPath`（`/app/data/box` に固定）を使う理由です：PVC のパスは Pod の mount namespace 内にしか存在せず、ノードの dockerd からは見えません。また `langbot` と `langbot-box` は `podAffinity` によって**同一ノード**にスケジュールされ、この hostPath を共有します。

> warning:
>
> hostPath + 同一ノードアフィニティに依存するため、`langbot` は複数レプリカの水平スケーリングをサポートしません（`ReadWriteOnce` PVC と同じ制約）。高可用性が必要な場合は別のアーキテクチャを検討してください。

### 接続と設定

- `langbot` は WebSocket で Box ランタイムに接続します。エンドポイントは ConfigMap の `BOX__RUNTIME__ENDPOINT: ws://langbot-box:5410` で指定します。

> info:
>
> コンテナ内のデフォルトホスト名は `langbot_box`（アンダースコア付き）ですが、アンダースコアは有効な Kubernetes DNS 名ではありません。そのためマニフェストでは、有効な Service 名 `langbot-box` を使ってエンドポイントを**明示的に**指定する必要があり、コンテナ内のデフォルト値に依存できません。

- Box ランタイムは自身の `box.local.*` / `BOX__*` 環境変数を**読み取りません**。設定は `langbot` が `BOX__LOCAL__*` を読み取り、INIT RPC で渡します。したがって `BOX__LOCAL__HOST_ROOT` / `DEFAULT_WORKSPACE` / `SKILLS_ROOT` / `ALLOWED_MOUNT_ROOTS` はすべて `langbot` Deployment に設定し、`HOST_ROOT` は両側の `box-root` マウントパス（`/app/data/box`）と一致させる必要があります。

### セキュリティに関する注意

ノードの Docker socket をマウントすると、Box ランタイム（およびサンドボックス内で実行される任意のコード）にノードへの**実質的な root 権限**を与えることになります。Box はこのワークロードを信頼できるノードにのみデプロイし、できればテイント/トレラレーションで隔離した専用ノードプールを使用してください。より強い隔離境界が必要な場合は、`box.backend` を `e2b` に切り替え（`E2B_API_KEY` を設定）、`docker.sock` のマウントと hostPath を削除します。詳細は[サンドボックス設定](https://langbot.app/docs/ja/usage/sandbox/config.md)を参照してください。

### Box の準備完了を確認する

```bash
# Box ランタイムのログ（選択された backend が表示されるはず、例: "using backend: docker"）
kubectl logs -n langbot -l app=langbot-box -f

# langbot が Box ランタイムに接続したことを確認
kubectl logs -n langbot -l app=langbot | grep -i "box runtime"
```

## サンドボックスが不要な場合

サンドボックス機能が不要な場合は、マニフェストから `langbot-box` の Deployment / Service を削除し、`langbot` Deployment に `BOX__ENABLED=false` を設定して接続失敗の警告ログを回避してください。

## 関連ドキュメント

- [Docker デプロイ](https://langbot.app/docs/ja/deploy/langbot/docker.md)
- [サンドボックスドキュメント](https://langbot.app/docs/ja/usage/sandbox/readme.md) と [サンドボックス設定](https://langbot.app/docs/ja/usage/sandbox/config.md)
- [スキルシステムドキュメント](https://langbot.app/docs/ja/usage/skills/readme.md)
- マニフェストのソースファイル：リポジトリ内の [`docker/kubernetes.yaml`](https://github.com/langbot-app/LangBot/blob/master/docker/kubernetes.yaml)

---

# 手動デプロイ

Source: https://langbot.app/docs/ja/deploy/langbot/manual

ソースから LangBot を手動デプロイ。Linux・Windows・macOS でオープンソース AI ボットプラットフォームを構築する手順。

## メインプログラムのインストール

1. [リリース](https://github.com/langbot-app/LangBot/releases)ページにアクセスし、最新バージョンのzipパッケージ(推奨)`langbot-xxx-all.zip`をダウンロードします(Source Codeはダウンロードしないでください。WebUIが含まれていません)。展開して、展開されたディレクトリでコマンドライン(ターミナル)を開きます。

![リリースのダウンロード](https://langbot.app/docs/images/zh/deploy/langbot/manual/dl_release.png)

2. 依存関係のインストール

依存関係の管理には[uv](https://docs.astral.sh/uv/)を使用します。

```bash
pip install uv
uv sync
```

デフォルトのインストールにはオプションの SeekDB サポートは含まれません。SeekDB ベクトルストアまたは組み込み埋め込みモデルを使用する場合は、次を実行します：

```bash
uv sync --extra seekdb
```

組み込みモードの対応プラットフォームは `pylibseekdb` wheel に依存します。Apple Silicon では現在 macOS 15 以降が必要です。その他の LangBot 機能はデフォルトの `uv sync` で利用できます。

3. メインプログラムを一度実行して設定ファイルを生成します

```bash
uv run main.py
```

以下のメッセージが表示されます:

```
 _                   ___      _
| |   __ _ _ _  __ _| _ ) ___| |_
| |__/ _` | ' \/ _` | _ \/ _ \  _|
|____\__,_|_||_\__, |___/\___/\__|
               |___/

⭐️オープンソース: https://github.com/langbot-app/LangBot
📖ドキュメント: https://langbot.app/docs

以下のファイルが存在しないため、自動的に生成されました。必要に応じて設定ファイルを変更して再起動してください:
- data/config.yaml
...
```

Ctrl+Cでプログラムを終了し、[ボットの設定](https://langbot.app/docs/ja/usage/platforms/readme.md)ページに進んでください。

---

# 1Panelデプロイ

Source: https://langbot.app/docs/ja/deploy/langbot/one-click/1panel

1Panel で LangBot をワンクリックデプロイ。コマンドライン不要でオープンソース AI チャットボットを導入。

[1Panel](https://www.bt.cn/new/download.html?r=dk_LangBot)を使用してLangBotをワンクリックでデプロイします。

## 1Panelのインストール

> 推奨サーバーシステム(1Panelより): Debian 12、Ubuntu 22など

この記事では、サーバーにデフォルトでパブリックIPv4アドレスがあることを前提としています。パブリックIPのないホームマシンを使用している場合は、以下で説明する内部ネットワーク経由で関連ページにアクセスできます。

[1Panel](https://www.bt.cn/new/download.html?r=dk_LangBot)にアクセスし、1Panelが公式に提供するLinuxパネルインストールスクリプトを使用します。お使いのオペレーティングシステムに応じて対応するスクリプトを選択してください。

![1Panelのインストール](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_install_01.png)

対応するスクリプトをコピーし、サーバーに貼り付けて実行します。

しばらく待つと、1Panelのインストールが完了します。

次に`外部アドレス`をコピーしてブラウザで開きます。

## LangBotのインストール

`アプリストア`を開き、`AI`カテゴリを選択し、LangBotをクリックしてインストールします。

![LangBotのインストール](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_langbot_01.png)

`外部ポートアクセス`のチェックボックスをオンにして、確認をクリックします。

![LangBotのインストール](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_langbot_02.png)

しばらく待つと、インストールが完了します。

左側の`コンテナ`をクリックし、`コンテナ`カテゴリを選択すると、LangBotコンテナバーが表示されます。

![LangBotコンテナ情報の表示](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_langbot_03.png)

サーバーのパブリックIPアドレスをコピーします。例: `http://xxx.xxx.xxx.xxx:5300`(xxx.xxx.xxx.xxxは1Panelが配置されているサーバーのIPアドレス、5300はポート番号)。

アドレスを開き、管理者のメールアドレスとパスワードを入力して、初期化をクリックします。

その後、ビジュアルインターフェースでLangBotを設定できます。

次に、[メッセージプラットフォームの設定](https://langbot.app/docs/ja/usage/platforms/readme.md)ページを引き続きお読みください。

---

# aaPanelデプロイ

Source: https://langbot.app/docs/ja/deploy/langbot/one-click/bt

aaPanel（宝塔パネル）で LangBot をワンクリックデプロイ。Web コントロールパネルから導入。

[aaPanel](https://www.bt.cn/new/download.html?r=dk_LangBot)を使用してLangBotをワンクリックでデプロイします。

> \- 追加のコンテナを必要としないDiscordやFeishuなどのメッセージプラットフォームを使用する予定がない場合、またはaaPanel上のDockerコンテナネットワーキングに精通していない場合は、aaPanelでのワンクリックデプロイは推奨されません。\[Dockerデプロイ]\(/en/deploy/langbot/docker)の使用を検討してください。:
>
> - 既にaaPanelがインストールされている場合は、バージョン**9.2.0**以上に更新してください

## aaPanelのインストール

> 推奨サーバーシステム(aaPanelより): Debian 12、Ubuntu 22など
>
> このドキュメントでは、パブリックIPv4アドレスを持つサーバーがあることを前提としています。パブリックIPのないホームマシンを使用している場合は、以下で言及する内部ネットワーク経由で関連ページにアクセスできます。

[aaPanel](https://www.bt.cn/new/download.html?r=dk_LangBot)を開き、aaPanel公式が提供するLinuxパネルインストールスクリプトを使用し、お使いのシステムに基づいて対応するスクリプトを選択します。

![aaPanelのインストール](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_install_01.png)

対応するスクリプトをコピーしてサーバーに貼り付けて実行します。

## LangBotのインストール

しばらく待つと、aaPanelのインストールが完了します。

このようなメッセージが表示されますので、外部パネルアドレスをコピーしてブラウザで開きます。

![aaPanelアクセスアドレス](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_install_02.png)

初めて開くと、`推奨インストールスイート`のポップアップが表示されます。閉じてスキップできます。

次にサイドバーの`docker`をクリックします。初めての場合、DockerとDocker Composeサービスのインストールを求められます。プロンプトが表示されたら「今すぐインストール」をクリックするか、既にインストールされている場合は無視してください。

次に`Docker -> アプリストア`に移動し、`LangBot`を検索し(大文字小文字に注意)、`インストール`をクリックし、デフォルト設定を使用します。

少し待つと、`langbot_XXXX`という名前のコンテナが`実行中`として表示されます。

![LangBotコンテナの作成](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_langbot_01.png)

上の画像の赤い円をクリックして実行ログを表示します。

![LangBotコンテナログの表示](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_langbot_02.png)

WebUI設定ページ(ビジュアル設定ページ)の外部および内部アクセスパスが表示されます。パブリックアドレスをコピーします。例: `http://xxx.xxx.xxx.xxx:5300`(xxx.xxx.xxx.xxxはaaPanelのIP、5300はポート番号で、画像に示されているように異なる場合があります)。

開いた後、管理者のメールアドレスとパスワードを入力し、初期化をクリックします。

その後、ビジュアルインターフェースで設定を進めることができます。

JSON設定ファイルを直接変更したい場合は、上の画像に示されているローカルマッピングディレクトリを参照できます。インストールディレクトリに移動すると、`data`フォルダは設定ファイルの保存に使用され、`plugins`フォルダはプラグイン関連ファイルに使用されます。

次に、[メッセージプラットフォームの設定](https://langbot.app/docs/ja/usage/platforms/readme.md)ページを引き続きお読みください。

---

# パッケージマネージャーでのデプロイ

Source: https://langbot.app/docs/ja/deploy/langbot/package

パッケージマネージャ（uv/uvx）で LangBot をデプロイ。オープンソース LLM チャットボットを素早く導入。

> info:
>
> Windows、Linux、Mac OSなどをサポート。テスト環境および個人使用シナリオに推奨。本番レベルの環境では[Dockerデプロイ](https://langbot.app/docs/en/deploy/langbot/docker.md)を使用してください。

LangBotはパッケージ化されてPyPIにリリースされています。[uv](https://docs.astral.sh/uv/getting-started/installation/)をインストールしてから、空のディレクトリで以下のコマンドを実行してください:

```bash
uvx langbot@latest
```

これにより現在のディレクトリが作業ディレクトリとして設定され、`http://localhost:5300`にアクセスして使用を開始できます。

## Beta 版（任意）

Beta 3 を試す場合は、代わりに次のコマンドを使います。`--prerelease=allow` は依存パッケージのプレリリースも許可し、`--refresh` はキャッシュされたパッケージ情報を更新します。

```bash
uvx --prerelease=allow --refresh langbot==4.11.0b3
```

## オプションの SeekDB サポート

デフォルトのインストールでは Chroma を使用し、SeekDB の Python SDK とネイティブコンポーネントは含まれません。SeekDB をベクトルストアとして使用する場合、または組み込み埋め込みモデルを使用する場合だけ `seekdb` extra を指定します：

```bash
uvx --from 'langbot[seekdb]@latest' langbot
```

SeekDB の組み込みモードには、現在のプラットフォームに対応する `pylibseekdb` wheel も必要です。Apple Silicon では現在 macOS 15 以降が必要です。macOS 14 ARM64 の対応予定は [oceanbase/seekdb#1324](https://github.com/oceanbase/seekdb/issues/1324) を参照してください。現在の `pyseekdb` package metadata のため、macOS 14 ARM64 ではサーバーモードだけを使う場合も extra を解決できません。SeekDB をインストールしない場合、この制限は LangBot に影響しません。

---

# システム環境設定

Source: https://langbot.app/docs/ja/deploy/settings

LangBot config.yaml の API、並行処理、DB、ストレージ、プラグイン、MCP、監視、Box の完全リファレンス。

LangBot の実行設定は `data/config.yaml` にあります。初回起動時に既定テンプレートから生成されます。以下の例は [`src/langbot/templates/config.yaml`](https://github.com/langbot-app/LangBot/blob/master/src/langbot/templates/config.yaml) と同期しています。

> info:
>
> 通常のセルフホストで変更が必要なのは主に公開 URL、DB/ベクトルストア、オブジェクトストレージ、Box Runtime です。用途を理解していない容量・Cloud 安全上限は既定値を維持してください。

## 完全なデフォルト設定

```yaml
# HTTP API と WebUI の設定です。
api:
    port: 5300
    webhook_prefix: 'http://127.0.0.1:5300'
    extra_webhook_prefix: ''
    # WebUI と API を別オリジンで配置する場合のブラウザー側 URL です。OAuth はこの値と webhook_prefix のみを信頼します。
    webui_url: ''
    # グローバル API キーです。空の場合は無効です。本番環境では環境変数から注入し、秘密として管理してください。
    global_api_key: ''
# Workspace 関連の設定です。
workspace:
    # メンバー招待リンクと任意のメール送信設定です。
    invitations:
        # 招待リンクに使う WebUI の公開 URL です。空の場合は api.webui_url、api.webhook_prefix の順にフォールバックします。
        public_web_url: ''
        # provider が空の場合はリンクだけを生成します。resend または smtp を選べます。
        email:
            provider: ''
            from: ''
            timeout_seconds: 10
            resend:
                api_url: 'https://api.resend.com/emails'
                api_key: ''
            smtp:
                host: ''
                port: 587
                username: ''
                password: ''
                starttls: true
                ssl: false
# コマンド機能、プレフィックス、権限マッピングです。
command:
    enable: true
    prefix:
    - '!'
    - ！
    privilege: {}
# パイプライン、セッション、待機中クエリの同時実行上限です。
concurrency:
    pipeline: 20
    session: 1
    pending_queries: 1000
    pending_queries_per_workspace: 100
# Webhook 数とインスタンス全体の同時送信数を制限し、無制限な待機を防ぎます。
webhooks:
    max_per_workspace: 16
    max_inflight_requests: 16
# Cloud の単一論理インスタンスに対する運用上の安全上限であり、プラン権限ではありません。
cloud:
    # 上限を超える正式なディレクトリ更新は、切り捨てず全体を拒否します。
    directory:
        max_active_workspaces: 1000
        max_snapshot_workspaces: 1000
        max_snapshot_memberships: 20000
        max_response_bytes: 33554432
# 外向き HTTP/HTTPS プロキシです。
proxy:
    http: ''
    https: ''
# インスタンス識別子、全体リソース制限、ランタイム保持方針です。
system:
    instance_id: ''
    edition: community
    recovery_key: ''
    allow_modify_login_info: true
    disabled_adapters: []
    # すべての asyncio.to_thread 処理で共有する上限付きスレッドプールです。
    blocking_executor:
        max_workers: 8
        max_pending: 128
        max_inflight_per_scope: 4
    # 外向き IP アドレスです。一部のボット基盤では信頼済み IP への登録が必要です。
    outbound_ips: []
    # インスタンス単位の件数制限です。-1 は無制限を示します。
    limitation:
        max_bots: -1
        max_pipelines: -1
        max_extensions: -1
        max_knowledge_bases: -1
        # SaaS でサンドボックス範囲を強制する設定です。通常のセルフホストでは空のままにします。
        force_box_session_id_template: ''
    # 非同期タスク記録、ログ、ユーザー起動タスクの同時実行上限です。
    task_retention:
        completed_limit: 200
        max_log_chars: 200000
        max_active_user_tasks: 256
        max_active_user_tasks_per_workspace: 8
    # プロセス内セッションキャッシュの上限です。永続的な会話履歴ではありません。
    session_retention:
        max_entries: 2000
        max_entries_per_workspace: 200
        idle_ttl_seconds: 86400
        max_conversations_per_session: 20
        max_messages_per_conversation: 100
    # ブラウザー接続、Workspace プロキシキャッシュ、送信キューの上限です。
    websocket_retention:
        max_connections: 1024
        max_connections_per_workspace: 32
        max_workspace_proxies: 1024
        max_conversations_per_workspace: 200
        max_messages_per_conversation: 100
        conversation_idle_ttl_seconds: 86400
        send_queue_size: 100
    # 上流レスポンスの文字数とストリーミングチャンク数の上限です。
    response_limits:
        max_generated_chars: 1048576
        max_stream_chunks: 100000
    # JWT の有効期間と署名鍵です。本番環境ではランダムな秘密鍵を設定してください。
    jwt:
        expire: 604800
        secret: ''
# 業務データベースです。sqlite または postgresql を選択できます。
database:
    use: sqlite
    sqlite:
        path: 'data/langbot.db'
    # PostgreSQL の接続プールとタイムアウト設定です。
    postgresql:
        # 空でない場合は個別フィールドより優先され、TLS とクエリオプションを保持します。
        url: ''
        host: '127.0.0.1'
        port: 5432
        user: 'postgres'
        password: 'postgres'
        database: 'postgres'
        pool_size: 10
        max_overflow: 10
        pool_timeout_seconds: 30
        pool_recycle_seconds: 1800
        statement_timeout_ms: 60000
        lock_timeout_ms: 5000
        idle_in_transaction_session_timeout_ms: 60000
    # Cloud リリース移行用の運用者接続設定です。
    cloud_migration:
        # 環境変数名だけを指定します。運用者ロールは実行時ロールと分離してください。
        operator_dsn_env: 'LANGBOT_CLOUD_MIGRATION_DSN'
# ベクトルデータベースです。use で選択したバックエンドだけを設定します。
vdb:
    use: chroma
    # プロセス内のコレクションまたはインデックスハンドル数を制限します。
    runtime_cache_limit: 1024
    # Qdrant の接続設定です。
    qdrant:
        url: ''
        host: localhost
        port: 6333
        api_key: ''
    # SeekDB はオプションです。ソース/package デプロイでは `seekdb` extra が必要です。
    # 公式 Docker/Kubernetes イメージにはすでに含まれています。
    # 組み込みモードの対応環境は pylibseekdb wheel に依存します。
    seekdb:
        mode: embedded
        path: './data/seekdb'
        database: 'langbot'
        host: 'localhost'
        port: 2881
        user: 'root'
        password: ''
        tenant: ''
    # Milvus の接続設定です。
    milvus:
        uri: 'http://127.0.0.1:19530'
        token: ''
        db_name: ''
    # pgvector は業務用 PostgreSQL を再利用するか、独立 DB に接続できます。
    pgvector:
        use_business_database: false
        # リリース移行では、ここに指定した次元だけに ANN インデックスを作成します。
        allowed_dimensions: [384, 512, 768, 1024, 1536]
        host: '127.0.0.1'
        port: 5433
        database: 'langbot'
        user: 'postgres'
        password: 'postgres'
    # Search モジュールを有効にした Valkey が必要です。
    valkey_search:
        host: 'localhost'
        port: 6379
        db: 0
        password: ''
        username: ''
        tls: false
        index_algorithm: 'HNSW'
        distance_metric: 'COSINE'
        request_timeout: 5000
# オブジェクトストレージ、読み込み上限、定期クリーンアップです。
storage:
    use: local
    # Core メモリへ一度に読み込むオブジェクトの上限です。組み込み実装の絶対上限は 64 MiB です。
    max_object_read_bytes: 10485760
    # ローカルまたは S3 のアップロードファイルと古いログを定期削除します。
    cleanup:
        enabled: true
        check_interval_hours: 1
        uploaded_file_retention_days: 7
        log_retention_days: 3
        max_files_per_run: 1000
    # S3 接続と同期処理の同時実行上限です。
    s3:
        endpoint_url: ''
        access_key_id: ''
        secret_access_key: ''
        region: 'us-east-1'
        bucket: 'langbot-storage'
        max_concurrency: 16
# プラグイン Worker のインスタンス全体のハード上限と受け入れ予算です。
plugin:
    enable: true
    runtime_ws_url: 'ws://langbot_plugin_runtime:5400/control/ws'
    enable_marketplace: true
    display_plugin_debug_url: 'ws://localhost:5401/plugin/debug/ws'
    # プラグインマニフェストからこれらの上限を引き上げることはできません。
    worker:
        max_cpus: 1.0
        max_memory_mb: 512
        max_pids: 128
        max_open_files: 256
        max_file_size_mb: 512
        max_workers: 16
        max_total_cpus: 8.0
        max_total_memory_mb: 8192
        max_installations: 10000
        max_concurrent_restarts: 1
        restart_failure_threshold: 8
        restart_failure_window_seconds: 30.0
        restart_circuit_open_seconds: 60.0
        require_hard_limits: false
    # プラグインのバイナリストレージにおける単一値のサイズ上限です。
    binary_storage:
        max_value_bytes: 10485760
# MCP ライフサイクルの同時実行数とローカル stdio トランスポートの設定です。
mcp:
    # インスタンス全体の MCP 起動・停止同時実行数です。絶対上限は 128 です。
    lifecycle_concurrency: 16
    # 無効にしてもローカル stdio MCP だけが停止し、HTTP/SSE MCP には影響しません。
    stdio:
        enabled: true
# 監視クエリの作業量と履歴データの削除方針です。
monitoring:
    # ページング、エクスポート、詳細、時系列バケット、高 offset クエリを制限します。
    query_limits:
        page_rows: 1000
        export_rows: 10000
        detail_rows: 2000
        timeseries_buckets: 1000
        max_offset: 1000000
    # 期限切れ監視レコードをバッチ単位で自動削除します。
    auto_cleanup:
        enabled: true
        retention_days: 30
        check_interval_hours: 1
        delete_batch_size: 1000
        max_batches_per_table_per_run: 4
# Box サンドボックス Runtime 全体の設定です。
box:
    # 無効にすると Box に接続・起動せず、サンドボックス依存ツールと stdio MCP も無効になります。
    enabled: true
    # local、docker、nsjail、e2b から選択します。
    backend: 'local'
    # 外部 WebSocket Runtime の URL です。空の場合はローカル Runtime を自動管理します。
    runtime:
        endpoint: ''
    # セッション、プロセス、Workspace 走査、受け入れ記録、RPC ファイルの上限です。
    limits:
        max_sessions: 64
        max_managed_processes: 64
        max_completed_processes: 256
        max_workspace_entries: 100000
        max_admission_records: 100000
        max_rpc_file_bytes: 20971520
    # Cloud v2 の強制受け入れとハードクォータです。通常の OSS では既定で無効です。
    admission:
        required: false
        logical_session_id: 'global'
        required_backend: 'nsjail'
        max_sessions: 1
        max_managed_processes: 0
        max_grant_ttl_sec: 300
        max_timeout_sec: 120
        cpus: 1.0
        memory_mb: 512
        pids_limit: 128
        read_only_rootfs: true
        workspace_quota_mb: 0
        readiness_cache_sec: 15
    # ローカル作業領域、Skill ディレクトリ、マウントルート、任意のディスククォータです。
    local:
        profile: 'default'
        image: ''
        # Docker 配置では、コンテナからマウントできるホストの絶対パスに変更します。
        host_root: './data/box'
        default_workspace: ''
        skills_root: 'skills'
        allowed_mount_roots:
            - './data/box'
            - '/tmp'
        workspace_quota_mb: null
    # 各 MCP stdio プロセスに対する nsjail cgroup の既定メモリ上限（MiB）です。
    default_memory_mb: 1536
    # Docker サンドボックスの追加設定です。
    docker:
        cpu_limit_enabled: true
    # E2B またはセルフホスト互換サービスの設定です。
    e2b:
        api_key: ''
        api_url: ''
        template: ''
# LangBot Space の OAuth、モデルゲートウェイ、テレメトリ設定です。
space:
    url: 'https://space.langbot.app'
    models_gateway_api_url: 'https://api.langbot.cloud/v1'
    oauth_authorize_url: 'https://space.langbot.app/auth/authorize'
    disable_models_service: false
    disable_telemetry: false
```

## 設定グループの説明

### API、WebUI、招待

- `api.port` は HTTP API と WebUI のポートです。`api.webhook_prefix` はプラットフォームのコールバック URL を生成する公開ベース URL で、本番環境では通常 HTTPS リバースプロキシのオリジンを指定します。
- WebUI と API のオリジンが異なる場合は `api.webui_url` を設定します。OAuth リダイレクトはこのサーバー側設定と `webhook_prefix` のみを信頼し、リクエストの `Host` / `Origin` ヘッダーは信頼しません。
- `api.global_api_key` は `X-API-Key` または `Authorization: Bearer` で HTTP Service API と組み込み MCP サーバーを認証します。ログインセッションや DB 保存の `lbk_` キーは不要で、空文字列は無効を意味します。
- `workspace.invitations.public_web_url` は招待リンクの公開 URL です。空の場合は `api.webui_url`、次に `api.webhook_prefix` へフォールバックします。メール配信は `resend` または `smtp` を選び、`provider` が空ならリンクのみを生成します。

> warning:
>
> グローバル API キー、JWT シークレット、DB/S3 認証情報、メールプロバイダーのシークレット、E2B キーは機密情報です。本番では環境変数を優先し、実値を Git にコミットせず、認証対象のエンドポイントは HTTPS で公開してください。

### 受付・容量制限

- `concurrency` は実行中・待機中のパイプライン処理をインスタンス全体および Workspace 単位で制限します。
- `webhooks` は Workspace ごとの有効な宛先数とインスタンス全体の送信中リクエスト数を制限します。
- `cloud.directory` は 1 つの Cloud 論理インスタンスに対する運用上の安全上限であり、サブスクリプション権限ではありません。上限超過の権威ディレクトリ更新は切り捨てず、全体を拒否します。通常のセルフホストでは既定値を維持してください。
- `system.blocking_executor`、各 `*_retention`、`response_limits` はスレッド、キャッシュ、ソケット、上流レスポンスのメモリ使用を有界にします。
- `system.limitation` の `-1` は無制限です。`force_box_session_id_template` は SaaS のサンドボックス制約用で、通常のセルフホストでは空のままにします。

### データベースとベクトルストア

- `database.use` で SQLite または PostgreSQL を選択します。`database.postgresql.url` が空でなければ分割された接続項目より優先され、TLS/クエリオプションも保持できます。
- PostgreSQL のプールとタイムアウトは共有ランタイム資源を制限します。`database.cloud_migration.operator_dsn_env` は運用者専用のマイグレーション DSN を格納する環境変数名で、ランタイムロールとは分離してください。
- `vdb.use` で利用するベクトルバックエンドを選びます。実際に選択したバックエンドだけを設定します。
- `vdb.use: seekdb` は、ソースデプロイでは `uv sync --extra seekdb`、パッケージデプロイでは `uvx --from 'langbot[seekdb]@latest' langbot` が必要です。公式 Docker/Kubernetes イメージには依存関係がすでに含まれており、追加のビルド引数は不要です。
- `vdb.pgvector.use_business_database` は `database.postgresql` を再利用します。`allowed_dimensions` はリリースマイグレーションが作成する ANN インデックスの次元を制御します。
- Valkey Search には Search モジュール入りの Valkey（例: `valkey/valkey-bundle:9.1.0`）が必要です。

### ストレージ、プラグイン、MCP、監視

- `storage.max_object_read_bytes` は Core のメモリへ読み込む 1 オブジェクトの上限です。クリーンアップ項目は 1 回のファイル走査量を、`s3.max_concurrency` はワーカースレッドへ委譲する boto3 操作数を制限します。
- `plugin.worker` は各インストールとインスタンス全体のハード上限です。プラグイン manifest から緩和できません。再起動関連項目は Runtime の再起動ストームを抑制します。
- `mcp.lifecycle_concurrency` は MCP の起動・停止バーストを制限します。`mcp.stdio.enabled` は HTTP/SSE MCP を維持したままローカル stdio MCP だけを無効化できます。
- `monitoring.query_limits` と `auto_cleanup` は大きなページ、CSV、offset、古いレコードがメモリや PostgreSQL を独占しないようにします。

### Box サンドボックス

- `box.enabled` は総合スイッチです。無効にするとネイティブサンドボックスツール、Skill の追加/編集、stdio MCP も無効になりますが、読み取り専用 Skill 一覧と HTTP/SSE MCP は利用できます。
- `box.backend` は `local`、`docker`、`nsjail`、`e2b` から選び、`runtime.endpoint` は外部 WebSocket Runtime への接続に使います。
- `box.limits` はセッション、プロセス、Workspace 走査、保持する受付フェンス、RPC ファイルサイズを制限します。
- `box.admission` は Cloud v2 の強制受付ポリシーです。OSS の既定値は `required: false` で、パイプラインや Workspace 権限、ツール呼び出しから Runtime 所有の上限を緩和できません。
- Docker では `box.local.host_root` に Box コンテナからマウント可能な絶対ホストパスを指定します。
- `box.default_memory_mb` は各 stdio MCP プロセスの nsjail cgroup メモリ既定値です。Node.js MCP は Python MCP より多く必要になりやすく、低すぎる場合は終了コード `137` がよく発生します。

### LangBot Space

`space.url`、`models_gateway_api_url`、`oauth_authorize_url` は Space OAuth/API と MaaS の接続先です。2 つの `disable_*` でモデルサービスとテレメトリーを個別に無効化できます。

## 環境変数による上書き

ネストしたキーを大文字にし、階層を二重アンダースコアで連結します。

- `API__PORT` → `api.port`
- `WORKSPACE__INVITATIONS__PUBLIC_WEB_URL` → `workspace.invitations.public_web_url`
- `CONCURRENCY__PENDING_QUERIES_PER_WORKSPACE` → `concurrency.pending_queries_per_workspace`
- `DATABASE__POSTGRESQL__POOL_SIZE` → `database.postgresql.pool_size`
- `STORAGE__CLEANUP__MAX_FILES_PER_RUN` → `storage.cleanup.max_files_per_run`
- `PLUGIN__WORKER__MAX_TOTAL_MEMORY_MB` → `plugin.worker.max_total_memory_mb`
- `MCP__STDIO__ENABLED` → `mcp.stdio.enabled`
- `BOX__DEFAULT_MEMORY_MB` → `box.default_memory_mb`

起動時に LangBot が環境変数を適用し、結果を `data/config.yaml` に書き込みます。

> info:
>
> Docker では統一された `BOX__*` 環境変数を `langbot` サービスに設定してください。LangBot は INIT RPC で Box 設定を `langbot_box` へ渡すため、`langbot_box` に直接設定した変数は読み取られません。

## 任意のテレメトリ

既定で有効ですが、無効にできます。

`data/config.yaml` の既存の `space` セクションで次を設定し、他の設定を保持したうえで LangBot を再起動します。

```yaml
space:
  disable_telemetry: true
```

このスイッチはクエリ統計、ハートビート、実行テレメトリ、およびアンケート取得を無効にします。引用符を付けず YAML の真偽値を使用してください。既定の有効状態に戻すには `false` に変更し、再起動します。

環境変数 `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時にファイルの設定を上書きするため、併せて変更または削除してください。コンテナの環境変数を変更する場合はコンテナを再作成します。Cloud ではインスタンスの運用者が設定し、そのインスタンスの全ワークスペースに適用されます。Bot の動作や、メッセージングプラットフォーム、モデル提供者、プラグイン自体のプライバシー設定は変更しません。

### イベント単位の実行チェーン

実行テレメトリは、サンプリングしたイベント単位のチェーン（受信した 1 つのプラットフォームイベントが、発生元からルーティング、処理、その結果生じたプラットフォーム API 呼び出しに至るまで）も報告します。サンプリングは同じ `space` セクションで調整します。

```yaml
space:
  execution_trace: sampled    # off | failures | sampled | all
  execution_trace_sample: 20  # sampled の場合：成功したチェーンの N 件に 1 件を保持
```

`failures` は失敗・キャンセル・タイムアウトした段階を含むチェーンのみを保持します。`off` はチェーンを無効にしますが、集計カウンターは継続します。WebUI のデバッグ実行は常に保持され、模擬実行として記録されます。チェーンの保持期間は実行記録と同じ 30 日です。

[データ収集ポリシー](https://langbot.app/docs/ja/insight/data-collection-policy.md)も参照してください。

---

# LangBotの更新

Source: https://langbot.app/docs/ja/deploy/update

LangBot を最新版へ更新。セルフホスト型 AI チャットボットを安全にアップグレードする手順。

## パッケージマネージャーを使用

LangBotをデプロイしたディレクトリで再度実行してください:

```bash
uvx langbot@latest
```

このコマンドは最新バージョンのLangBotをダウンロードして起動します。

## Dockerを使用(またはDockerベースのワンクリックデプロイ)

LangBotをクローンしたディレクトリで実行してください:

```bash
git pull
```

`docker/`ディレクトリで実行してください:

```bash
docker compose up --force-recreate --pull always -d
```

このコマンドは最新のLangBotイメージをプルしてコンテナを再構築します。

> info:
>
> 4.3.0バージョンでは`docker-compose.yaml`ファイルの内容と場所が変更されました。以前のバージョンから更新した場合は、[ドキュメントに従って再デプロイ](https://langbot.app/docs/en/deploy/langbot/docker.md)してください。

## 手動デプロイ

[リリース](https://github.com/langbot-app/LangBot/releases)ページのAssetsセクションから最新リリースの`langbot-<version>-all.zip`をダウンロードし、元のデプロイディレクトリに展開して再起動してください。

---

# AI アシスタント開発コンテキスト

Source: https://langbot.app/docs/ja/develop/agent-context

AI コーディングアシスタントにページ全体をそのままコピー＆ペーストできる LangBot のコンテキスト：ディレクトリ構成、コンポーネントの構成方法、実行時の接続関係、開発環境のセットアップ。

> このページは AI コーディングアシスタント（Claude Code / Cursor / Copilot / Codex など）向けです。:
>
> このページの**すべての内容**をコピーして AI アシスタントに貼り付けてください。そうすれば、LangBot の全体アーキテクチャ、各コンポーネントの構成方法、実行時の接続関係、開発環境の設定方法を、あなたが逐一説明しなくても把握できます。

このページは各リポジトリのルートにある `AGENTS.md`（`CLAUDE.md` はそのシンボリックリンク）と内容を一致させており、LangBot プロジェクトの開発者および AI アシスタント向け「1 ページ入門」です。

## プロジェクト概要

LangBot はオープンソースの LLM ネイティブなインスタントメッセージングボット開発プラットフォームです。すぐに使える IM ボット開発体験を提供し、Agent、RAG、MCP などの LLM アプリケーション機能を内蔵し、世界の主要 IM プラットフォームに対応し、カスタム開発のための豊富な API を提供します。

LangBot は充実した Web フロントエンドを備えており、ほぼすべての操作をフロントエンドから行えます。

- **バックエンド**：Python（`>=3.11,<4.0`）、依存関係は `uv` で管理。Web フレームワークは Quart（Flask の非同期版）。HTTP API とビルド済みフロントエンドはいずれもバックエンドが `http://127.0.0.1:5300` で提供します。
- **フロントエンド**：`web/` は **Vite + React Router 7 + shadcn/ui + Tailwind CSS** の SPA で、`pnpm` で管理します（注意：Next.js では**ありません**。`dev` スクリプトは `vite` です）。
- **プラグインシステム**：プラグイン SDK、CLI（`lbp`）、プラグインランタイム、Box（サンドボックス）ランタイム、および LangBot とプラグインで共有されるエンティティ/API 定義は、すべて別リポジトリ [`langbot-plugin-sdk`](https://github.com/langbot-app/langbot-plugin-sdk) にあります。LangBot は `pyproject.toml` でバージョン固定した `langbot-plugin` パッケージを通じて依存します。

## リポジトリ構成

```
LangBot/
├── main.py                     # エントリーシム -> langbot.__main__.main()
├── pyproject.toml              # Python プロジェクト + 依存（uv）、langbot-plugin==<x.y.z> を固定
├── src/langbot/
│   ├── __main__.py             # 実際のエントリーポイント、CLI 引数（--standalone-runtime / --standalone-box / --debug）
│   ├── pkg/                    # コアバックエンドパッケージ
│   │   ├── api/                # HTTP API コントローラ + サービス（Quart）
│   │   ├── core/               # アプリ起動、ステージ、タスクマネージャ
│   │   ├── platform/           # IM プラットフォームアダプタ、ボット管理、セッション管理
│   │   ├── provider/           # LLM プロバイダ、リクエスタ、ツールプロバイダ
│   │   ├── pipeline/           # パイプライン、ステージ、クエリプール
│   │   ├── plugin/             # プラグインランタイムへのブリッジ（connector.py / handler.py）
│   │   ├── box/                # コードサンドボックスサブシステム（Docker / nsjail / E2B バックエンド）
│   │   ├── skill/              # スキルサブシステム
│   │   ├── rag/ , vector/      # RAG とベクトルストア
│   │   ├── command/            # 組み込みコマンド
│   │   ├── persistence/        # ORM モデル + Alembic マイグレーション（SQLite & PostgreSQL）
│   │   ├── storage/            # オブジェクト/ファイルストレージ抽象
│   │   ├── config/, entity/, discover/, utils/, telemetry/, survey/
│   ├── libs/                   # 同梱 SDK（qq_official_api、wecom_api など）
│   └── templates/              # 設定/コンポーネントテンプレート（例：templates/config.yaml）
├── web/                        # フロントエンド SPA（Vite + React Router 7 + shadcn + Tailwind）
└── docker/                     # docker-compose デプロイファイル
```

## コンポーネントの構成方法

コアバックエンドパッケージ `src/langbot/pkg/` は責務ごとに疎結合なサブモジュールに分割されています：

| モジュール                      | 責務                                                                           |
| -------------------------- | ---------------------------------------------------------------------------- |
| `core`                     | アプリケーションのライフサイクル：起動ステージが設定読み込み・DB 接続・各サブシステムの起動を順に行い、バックグラウンドタスクを管理。         |
| `platform`                 | 各 IM プラットフォーム（Discord、Telegram、QQ、WeCom、Lark など）のアダプタ。メッセージ送受信、ボットとセッションの管理。 |
| `provider`                 | LLM プロバイダとリクエスタ（OpenAI 互換および各社ネイティブ API）、Agent が呼び出すツールプロバイダ。                |
| `pipeline`                 | メッセージ処理パイプライン：1 つのメッセージをトリガー・AI 処理・出力・安全の各ステージに通す。                           |
| `plugin`                   | LangBot 本体とプラグインランタイム間のブリッジ。接続・アクション送受信・イベント転送。                              |
| `box`                      | コードサンドボックスサブシステム。スキル/ツールに隔離されたコード実行環境を提供し、可用性に応じて Docker / nsjail / E2B を選択。 |
| `skill` / `rag` / `vector` | スキル、検索拡張生成、ベクトルストアの機能。                                                       |
| `persistence`              | ORM エンティティ定義と Alembic マイグレーション。単一のスクリプトセットで SQLite と PostgreSQL の両方に対応。      |

プラグイン側のコンポーネント（`langbot-plugin-sdk` で定義、`lbp comp` で生成）は 1 つの `BasePlugin` を中心に構成されます。現在 6 種類のコンポーネントに対応しています：

- **Command**：ユーザーが能動的に起動するコマンド（例：`!weather tokyo`）。
- **Tool**：LLM が Agent 実行中に呼び出す関数（例：天気取得、データベース照会）。
- **EventListener**：メッセージパイプライン中のイベントを監視するハンドラ（例：自動返信、コンテンツフィルタ）。
- **KnowledgeEngine**：RAG が利用する、カスタムナレッジベースの検索/接続実装。
- **Parser**：メッセージ/コンテンツのカスタム解析処理。
- **Page**：プラグインが提供するカスタム Web ページ。LangBot 管理パネルに組み込めます。

各プラグインは独立したプロセスで実行され、プラグインランタイムがライフサイクルを統一管理します（発見 → 依存インストール → ロード → 初期化 → コンポーネント登録 → 準備完了 → 終了）。

## 実行時の接続関係

```
┌──────────────┐   HTTP/API    ┌──────────────┐
│ ブラウザ/Web   │ ────────────► │              │
│ (Vite SPA)   │ :3000/同一    │   LangBot    │
└──────────────┘   オリジン      │   バックエンド │
                               │  (Quart)     │
   ┌───────────────────────────┤  :5300       ├─────────────────────────┐
   │ stdio または WebSocket       └──────────────┘   stdio または WebSocket │
   ▼                                                ▼
┌──────────────┐                            ┌──────────────┐
│ プラグイン      │  独立プロセス、              │ Box          │  コードサンドボックス
│ ランタイム     │  各プラグインを起動          │ ランタイム    │  Docker/nsjail/E2B
│ :5400 / :5401│                            │ :5410        │
└──────────────┘                            └──────────────┘
```

- **フロントエンド ↔ バックエンド**：開発時はフロントエンドが `:3000` で単独動作し、`web/.env` の `VITE_API_BASE_URL` を通じてバックエンド `:5300` にアクセス。本番ではフロントエンドが静的ファイルにビルドされ、バックエンドが同一オリジンで提供します。
- **バックエンド ↔ プラグインランタイム**：
  - LangBot を**直接起動**した場合（コンテナ外）、バックエンドが自らランタイムを**起動**し、**stdio** で通信します（軽量/個人向け）。stdio は**自動再接続できません**——切断後は LangBot の再起動が必要です。よくある障害は、前のバックエンドが残した**孤児ランタイムプロセス**が `5400`/`5401` を占有しているケースで、それを kill して再起動します。
  - LangBot を**コンテナ**で実行する場合、**WebSocket** で独立したランタイムに接続します（本番向け）。制御ポートは既定 `5400`、デバッグポートは `5401`。設定：`data/config.yaml` の `plugin.runtime_ws_url`（例：`ws://langbot_plugin_runtime:5400/control/ws`）。
- **バックエンド ↔ Box ランタイム**：Box サブシステムは制御チャネル（既定ポート `5410`）で Box ランタイムに接続し、ランタイムが Docker / nsjail / E2B でサンドボックスコードを実行します。設定（`data/config.yaml` の `box:` セクション）：`box.enabled`（マスタースイッチ）、`box.backend`（`'local'`/`'docker'`/`'nsjail'`/`'e2b'`）、`box.runtime.endpoint`（外部 Box ランタイムの URL、例：`ws://127.0.0.1:5410`、空なら ローカル自動管理）。プラグインランタイムと同様、このエンドポイントを設定し `--standalone-box` で起動すると外部 Box ランタイムに接続できます。
- ランタイム・CLI・SDK のデバッグ方法の詳細は[「プラグインランタイム、CLI、SDK のデバッグ」](https://langbot.app/docs/ja/develop/plugin-runtime.md)を参照。詳細なフラグとアーキテクチャは `langbot-plugin-sdk` リポジトリの `AGENTS.md` にあります。

## 開発環境のセットアップ

詳細は[「開発設定」](https://langbot.app/docs/ja/develop/dev-config.md)を参照。要点：

### バックエンド

```bash
pip install uv
uv sync --dev          # uv が .venv/ を自動作成。エディタのインタプリタをそこに向ける
uv run main.py         # http://127.0.0.1:5300 で API + フロントエンドを提供
```

初回起動時に設定ファイルが `data/config.yaml` に生成されます。既定は SQLite（設定不要）で、PostgreSQL にも対応。マイグレーションは起動時に自動実行されます。

### フロントエンド

Node.js と [pnpm](https://pnpm.io/ja/installation) が必要です。

```bash
cd web
cp .env.example .env   # Windows: copy .env.example .env
pnpm install
pnpm dev               # http://127.0.0.1:3000（npm install / npm run dev も可）
```

`pnpm dev` は `web/.env` の `VITE_API_BASE_URL` を読み込み、開発時のフロントエンドがバックエンド `:5300` にアクセスできるようにします。

### コードフォーマット

CI で lint + format チェックが走ります。pre-commit フックをインストールして、同じチェックを各コミット前にローカルで実行してください：

```bash
uv run pre-commit install
```

### データベースマイグレーション

ORM モデルを変更したらマイグレーションを生成します：

```bash
# プロジェクトルートで実行（data/config.yaml が必要）
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "変更内容の説明"
```

`autogenerate` はスキーマ変更（列・テーブルの追加/削除、型変更）を検出しますが、**データマイグレーション**（JSON フィールドの内容変更など）は生成スクリプトに手書きする必要があります。`env.py` で `render_as_batch=True` が設定されており、SQLite の ALTER TABLE 制限が自動処理されるため、データベース種別ごとの分岐は不要です。マイグレーションは起動時に自動実行されます。

## 開発規約

- LangBot はグローバルなプロジェクトです：**すべてのコードコメントと docstring は英語**で、ユーザー向けの文字列はすべて **i18n** に対応する必要があります（最低限 `en_US` + `zh_Hans`、リポジトリに日本語がある箇所は `ja_JP` も）。
- LangBot は toC・toB の両シナリオで採用されているため、常に互換性とセキュリティを考慮してください。
- **コミットメッセージ形式**：`<type>(<scope>): <subject>`
  - `type`：`feat`、`fix`、`docs`、`style`、`refactor`、`perf`、`test`、`chore` など。
  - `scope`：影響を受けるパッケージ/モジュール/ファイル/クラス。
  - `subject`：変更内容の簡潔な説明。

## Agent 向けの機能（MCP + スキル）

LangBot は設計上**AI エージェントに優しく**、HTTP API と厳密に整合した 3 つの
Agent 向けサーフェスを提供します:

1. **MCP サーバー**: `src/langbot/pkg/api/mcp/` が `/mcp` で API の厳選サブセットを
   MCP ツールとして公開します（API キー認証、config.yaml の `api.global_api_key`
   を含む）。`server.py` がツールを定義し（service 層を直接呼び出す）、`mount.py`
   が ASGI ディスパッチャです。
2. **リポジトリ内スキル**: `skills/` ディレクトリは LangBot の全 Agent スキル
   （プラグイン開発、コア開発、デプロイ、e2e、MCP 操作など）の**唯一の信頼できる
   情報源**です。ドキュメントとランディングページは内容を複製せず、ここへリンク
   します。
3. **API キー認証**: `api.global_api_key`（config.yaml）はログインセッションなしで
   API と MCP を認証します。`docs/API_KEY_AUTH.md` を参照してください。

> **メンテナンスルール（重要）**: Agent からアクセス可能であるべき HTTP API
> エンドポイントを追加・削除・変更する際は、`src/langbot/pkg/api/mcp/server.py`
> の対応する MCP ツール**と** `skills/` 配下の関連スキル（特に
> `skills/skills/langbot-mcp-ops`）の**両方**を必ず更新してください。API・MCP
> ツール群・スキルは一つのシステムであり、ずれはバグです。

## いくつかの原則

- Keep it simple, stupid.
- 必要がなければエンティティを増やさない。
- 八荣八耻（八つの栄誉と八つの恥）：

  以瞎猜接口为耻，以认真查询为荣。
  以模糊执行为耻，以寻求确认为荣。
  以臆想业务为耻，以人类确认为荣。
  以创造接口为耻，以复用现有为荣。
  以跳过验证为耻，以主动测试为荣。
  以破坏架构为耻，以遵循规范为荣。
  以假装理解为耻，以诚实无知为荣。
  以盲目修改为耻，以谨慎重构为荣。

---

# コンポーネントアーキテクチャ

Source: https://langbot.app/docs/ja/develop/comp-arch

![コンポーネントアーキテクチャ図](https://langbot.app/docs/images/zh/develop/comp_arch/develop_comp_arch_1.png)

---

# 開発設定

Source: https://langbot.app/docs/ja/develop/dev-config

LangBotはフロントエンドとバックエンドに分かれています。フロントエンドはVite + React Router + shadcnを使用して開発され、バックエンドはQuart(Flaskの非同期版)を使用して開発されています。

## バックエンド

コードは`pkg`ディレクトリにあり、ルートディレクトリの`main.py`ファイルによって起動されます。

依存関係をインストールします。依存関係の管理にはuvを使用します。

```bash
pip install uv
uv sync --dev
```

バックエンドを起動します

```bash
uv run main.py
```

この時点で、設定ファイルは`data/config.yaml`ファイルに自動的に生成されます。

## フロントエンド

コードは`web`ディレクトリにあり、Node.jsと[pnpm](https://pnpm.io/installation)が必要です。

`.env.example`を`.env`にコピーして、値を入力します。

- Linuxおよびその他の環境での使用

```bash
cp .env.example .env
```

- Windows環境での使用

```bash
copy .env.example .env
```

依存関係をインストールしてフロントエンドを起動します

```bash
pnpm install
pnpm dev

# pnpmがインストールされていない場合は、npmを使用して依存関係を解決して起動することもできます
npm install
npm run dev
```

その後、出力情報に従って、`http://127.0.0.1:3000`にアクセスして、スタンドアロンフロントエンドページを表示します。

> \`pnpm dev\`を使用してローカルで起動すると、環境変数\`VITE\_API\_BASE\_URL\`がフロントエンドによって自動的に使用され、フロントエンドがローカルで実行中のバックエンドの\`5300\`ポートにアクセスできるようになります。:
>
> 本番環境では、フロントエンドは静的ファイルにプリコンパイルされ、バックエンドによって提供され、フロントエンドは同じドメインのバックエンドアドレスに自動的にアクセスします。

## コードフォーマット

リポジトリにはlintとformatのチェックワークフローが含まれており、コードをプッシュすると自動的にチェックされます。pre-commitを設定して、コードをローカルで事前にチェックしてください。

```bash
uv run pre-commit install
```

## APIドキュメント

各インターフェースを開発する前に、APIFoxでAPIドキュメントを作成します。[APIドキュメント(中国語)](https://ok52vhsenr.apifox.cn/)を参照してください。

## データベースマイグレーション

LangBotは[Alembic](https://alembic.sqlalchemy.org/)を使用してデータベースマイグレーションを管理しており、SQLiteとPostgreSQLの両方をシームレスにサポートします。データベース固有の分岐コードは不要です。

### マイグレーションファイルの場所

```
src/langbot/pkg/persistence/alembic/versions/
```

### 新しいマイグレーションの作成

**autogenerate** を使用してマイグレーションスクリプトを自動生成することを推奨します。ORMモデルとデータベーススキーマの差分を比較して生成します：

```bash
# プロジェクトルートで実行（data/config.yaml が必要）
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "変更内容の説明"
```

生成されたファイルは `src/langbot/pkg/persistence/alembic/versions/` に作成されます。生成されたスクリプトを確認・編集し、変更が正しいことを確認してからコミットしてください。

> info:
>
> autogenerateは列の追加/削除、テーブルの変更、型の変更などを自動検出できます。ただし、**データマイグレーション**（JSONフィールドの内容変更など）は、生成されたスクリプトに手動でコードを追加する必要があります。

手動でマイグレーションファイルを作成することもできます。命名規則 `NNNN_description.py` に従ってください：

```python
"""マイグレーションの説明

Revision ID: 0003_add_bot_description
Revises: 0002_sample
Create Date: 2026-04-08
"""
from alembic import op
import sqlalchemy as sa

revision = '0003_add_bot_description'
down_revision = '0002_sample'  # 前のマイグレーションのrevisionを指定
branch_labels = None
depends_on = None


def upgrade() -> None:
    # スキーマ変更（SQLiteとPostgreSQLの両方で動作）
    op.add_column('bots', sa.Column('description', sa.String(512), server_default=''))


def downgrade() -> None:
    op.drop_column('bots', 'description')
```

### マイグレーションパターン

**スキーマ変更（列の追加/削除、テーブル作成）**

```python
def upgrade() -> None:
    # 列を追加
    op.add_column('table_name', sa.Column('new_col', sa.String(255), server_default=''))
    
    # 新しいテーブルを作成
    op.create_table(
        'new_table',
        sa.Column('id', sa.Integer, primary_key=True, autoincrement=True),
        sa.Column('name', sa.String(255), nullable=False),
    )
```

> info:
>
> `env.py`で`render_as_batch=True`が設定されているため、AlembicはSQLiteのALTER TABLE制限を自動的に処理します（一時テーブルによる再構築）。データベースタイプによる分岐は不要です。

**データマイグレーション（データの読み取りと変更）**

```python
import json

def upgrade() -> None:
    conn = op.get_bind()
    rows = conn.execute(sa.text("SELECT uuid, config FROM pipelines")).fetchall()
    for row in rows:
        config = json.loads(row[1]) if isinstance(row[1], str) else row[1]
        config.setdefault('ai', {})['new_key'] = 'default_value'
        conn.execute(
            sa.text("UPDATE pipelines SET config = :cfg WHERE uuid = :uuid"),
            {"cfg": json.dumps(config), "uuid": row[0]}
        )
```

### 動作の仕組み

マイグレーションはLangBot起動時に自動的に実行されます。手動コマンドは不要です：

1. 初回起動時、ベースラインバージョンが自動的にスタンプされます（既存データベースのマーキング）
2. 以降の起動時、未適用のすべてのマイグレーションが適用されます（`alembic upgrade head`）

### CIテスト

リポジトリには`test-migrations.yml`ワークフローが含まれており、`persistence/`関連ファイルが変更された際に、SQLiteとPostgreSQLの両方でマイグレーションスクリプトが自動テストされます。

### CLIツール

```bash
# マイグレーションを自動生成（ORMモデルとDBの差分を比較）
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "説明"

# データベースをアップグレード
uv run python -m langbot.pkg.persistence.alembic_runner upgrade

# 現在のリビジョンを表示
uv run python -m langbot.pkg.persistence.alembic_runner current

# リビジョンをスタンプ（マイグレーションを実行せず）
uv run python -m langbot.pkg.persistence.alembic_runner stamp head
```

---

# プラグインランタイム、CLI、SDKのデバッグ

Source: https://langbot.app/docs/ja/develop/plugin-runtime

> info:
>
> プラグインランタイム、CLI、SDKはこちらでオープンソース化されています: <https://github.com/langbot-app/langbot-plugin-sdk>

LangBotはlangbot-plugin-sdkで定義されたエンティティに依存するため、新しいディレクトリでVS Codeを開き、LangBotとlangbot-plugin-sdk（git clone <https://github.com/langbot-app/langbot-plugin-sdk）をサブディレクトリとして配置することをお勧めします。ディレクトリ構造は以下の通りです：>

```bash
langbot-projects
├── LangBot
├── langbot-plugin-sdk
```

LangBotディレクトリに移動し、依存関係をインストールします：

```bash
cd LangBot
uv sync --dev
```

この時点で、uvは自動的に仮想環境(.venv)を作成します。エディターがこの仮想環境を使用するかどうかを尋ねる場合は、`Yes`を選択してください。

![](https://langbot.app/docs/images/zh/develop/confirm_venv.png)

プロンプトが表示されない場合は、右下隅からPythonインタープリターのパスをvenv内のインタープリターに手動で設定してください。

次に、VS Code下部のターミナルを開きます。これにより自動的にvenvがアクティブ化されます。

または、この仮想環境を手動でアクティブ化できます：

```bash
# .venvのパスに応じてコマンドを変更してください
source .venv/bin/activate
```

## プラグインランタイムの起動

```bash
python -m langbot_plugin.cli.__init__ rt
```

プラグインランタイムは以下のパラメーターを受け入れます:

- `--debug-only`: `data/plugins`ディレクトリのプラグインを起動せず、デバッグ接続を通じたプラグインの読み込みのみを許可します。
- `--ws-debug-port`: リッスンするデバッグポート、デフォルトは`5401`です。
- `--ws-control-port`: リッスンする制御ポート(LangBotメインプログラム接続用)、デフォルトは`5400`です。
- `-s`: `stdio`を使用して制御接続を受け入れます。**本番環境でのみ使用してください**。
- `--skip-deps-check`: すべてのプラグイン依存関係がインストールされていることを確認するため、ランタイムは起動時に毎回すべてのインストール済みプラグインの依存関係をチェックしてインストールします。このパラメーターを使用してこのチェックを無効にします。

### LangBotでローカル修正したlangbot-plugin-sdkを使用する

メッセージエンティティやプラグインデータ定義などを変更した場合、実行時のデータ形式の互換性を確保するために、LangBot環境に更新する必要があります。

**LangBotディレクトリの仮想環境（.venv）がアクティブ化されたターミナル**で、langbot-plugin-sdkディレクトリに移動し、以下を実行します：

```bash
uv pip install .
```

これにより、修正したlangbot-plugin-sdkがLangBotの環境にインストールされます。

### LangBotをこのランタイムに接続する

LangBotの`data/config.yaml`で`plugin.runtime_ws_url`を`ws://localhost:5400/control/ws`に設定します。

```yaml
plugin:
  runtime_ws_url: ws://localhost:5400/control/ws
```

LangBot の仮想環境を有効にしたターミナルで、Python を直接使用してメインプログラムを起動し、`--standalone-runtime` を追加します（例：`python main.py --standalone-runtime`）。現在の仮想環境の Python を直接呼び出す場合、依存関係は再同期されないため、インストールしたローカルの langbot-plugin-sdk がリモート版で上書きされることはありません。\
LangBotを再起動すると、WebSocketを使用してこのランタイムに接続されます。

`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` は既定では省略可能です。LangBot と Runtime の両方で未設定の場合、ローカル OSS の制御接続はトークンなしで確立されます。公開された 5400 ポートを保護する場合は、両側に同じ 32 文字以上の高エントロピー値を設定してください。Runtime 側に token を設定すると、同じ値を送信しない LangBot は拒否されます。LangBot 側だけに設定しても Runtime 側の認証は有効になりません。

### `lbp run` でプラグインをデバッグする

Multi-Workspace 版では、デバッグプラグインは `5401` ポートへ到達できるだけでは Runtime に接続できません。Workspace ごとに、有効期限付きの個別デバッグキーが必要です：

1. 上記の手順で LangBot と Plugin Runtime が起動し、接続済みであることを確認します。
2. LangBot WebUI の「プラグイン」ページで「デバッグ情報」を開き、デバッグ URL とデバッグキーをコピーします。この操作には現在の Workspace のリソース管理権限が必要です。
3. プラグインプロジェクトの `.env` に設定します：

```bash
DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws
PLUGIN_DEBUG_KEY=<WebUI からコピーしたデバッグキー>
```

4. プラグインプロジェクトのディレクトリで起動します：

```bash
python -m langbot_plugin.cli.__init__ run
```

`.env` に保存せず、`python -m langbot_plugin.cli.__init__ run --plugin-debug-key '<デバッグキー>'` を使用することもできます。キーは Workspace ごとに分離され、有効期限は 2 時間です。期限切れ、Runtime の再起動、または Workspace の切り替え後は WebUI から再取得してください。`DEBUG_RUNTIME_WS_URL` だけを設定したクライアントは拒否されます。

## Box Runtime を standalone モードで起動する

Box Runtime の制御接続ルールは Plugin Runtime と同じです。OSS standalone 開発では token は省略可能で、両側で `LANGBOT_BOX_CONTROL_TOKEN` が未設定の場合も接続できます：

```bash
# ターミナル 1：langbot-plugin-sdk ディレクトリ
python -m langbot_plugin.cli.__init__ box
```

LangBot の `data/config.yaml` でローカル Box Runtime を指定します：

```yaml
box:
  enabled: true
  backend: local
  runtime:
    endpoint: ws://127.0.0.1:5410
```

```bash
# ターミナル 2：LangBot ディレクトリ
python main.py --standalone-runtime --standalone-box
```

公開された 5410 ポートを保護する場合は、両方のプロセスを起動する前に、同じ 32 文字以上で空白を含まない高エントロピー値を設定してください：

```bash
export LANGBOT_BOX_CONTROL_TOKEN='<両側で完全に同じ高エントロピーシークレット>'
```

Box Runtime 側に token を設定すると、同じ値を送信しない LangBot は拒否されます。LangBot 側だけに設定しても Box Runtime 側の認証は有効になりません。明示的に設定した値が 32 文字未満の場合は、引き続き両側で拒否されます。実際の値を設定ファイルや Git にコミットしないでください。

## langbot-plugin-sdkアーキテクチャ

このコードベースには以下が含まれています:

- `langbot_plugin.api`: プラグイン関連のエンティティとAPI定義。
- `langbot_plugin.assets`: プラグインテンプレート。
- `langbot_plugin.cli`: プラグイン開発CLIツール。
- `langbot_plugin.entities`: APIで定義されていないプラグインシステム関連のエンティティ。
- `langbot_plugin.runtime`: プラグインランタイムと基礎通信(stdioおよびwebsocket)の実装。

## `lbp` CLIツール

CLIツールは、ランタイムの起動、プラグインの初期化、プラグインコンポーネント管理、Marketplaceとのインタラクションなどの機能を提供します。

詳細なプログラムエントリポイントについては、[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)を参照してください。

---

# コミュニティリソース

Source: https://langbot.app/docs/ja/insight/community

LangBot コミュニティリソース：オープンソース AI ボットの GitHub・Discord・ドキュメント・サポート。

## 簡易チュートリアル

> 簡易チュートリアル:ビデオチュートリアル、より簡単なテキストチュートリアルなど、初心者に適しています

こちらで収集されています: <https://blog.thelazy.top/tags/langbot>

## 🥰 コミュニティ

Discordコミュニティに参加してください: [![Discord](https://img.shields.io/discord/1335141740050649118?logo=discord\&labelColor=%20%235462eb\&logoColor=%20%23f5f5f5\&color=%20%235462eb)](https://discord.gg/wdNEHETs87)

---

# データ収集ポリシー

Source: https://langbot.app/docs/ja/insight/data-collection-policy

任意のテレメトリ、実行記録と無効化の方法

LangBot は利用状況の把握と信頼性の改善のため、設定された LangBot Space サービス（既定は `https://space.langbot.app`）にテレメトリを送信します。**既定で有効ですが、無効にできます。** 実行記録は既存のテレメトリを利用し、独立した Beta 診断の送信機能は使用しません。

## 既存の製品テレメトリ

有効な場合、既存のクエリ処理経路から次のデータが送信されることがあります。

| データ          | 内容                                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| 識別子と環境       | `instance_id`、`workspace_uuid`、ランダムな `query_id`、バージョン、アダプターとランナーの種類                                    |
| クエリ統計        | モデル名、処理時間、タイムスタンプ、パイプラインプラグイン名                                                                         |
| 機能利用         | 呼び出し元別のツール呼び出し数、ツール呼び出しラウンド数、ナレッジベースと検索結果の件数、ナレッジエンジンプラグイン ID、サンドボックス実行/エラー数、有効化したスキル名、設定された MCP サーバー名 |
| エラー          | 旧 `error` フィールドには、例外メッセージを含む生の traceback が入ることがあります                                                    |
| マネージド実行環境の活動 | マネージド SaaS クエリの `runtime_instance_id` はアイドルタイムアウトの活動更新に使用され、分析イベントレコードには保存されません                        |

機能カウンターは、ツールの引数/結果、検索テキスト、サンドボックスのコード/出力を意図的に含めません。**ただし、旧方式の例外テキストやユーザー定義のモデル・スキル・MCP 名には機密情報が含まれる可能性があります。実行記録の内容制限は、この既存ストリームを無害化するものではありません。** 既存のテレメトリについて、ユーザーコンテンツを一切含まないとは保証できません。

アクティブなワークスペースは、起動直後とその後毎日ハートビートを送信します。デプロイ環境、データベース/ベクトルデータベースの種類、サンドボックス設定と可用性、有効なアダプターの種類、リソース数を含みますが、リソース内容や接続情報は含めません。

任意参加のアプリ内アンケートでは、アンケート ID、送信した回答、インスタンス ID、バージョン、完了/閉じた状態を送信します。回答はユーザーが提供するコンテンツであり、Beta 診断ではありません。

## 実行テレメトリ

プラットフォームイベント、ルーティング、Pipeline / Agent / プラグインのイベントプロセッサー、プラットフォーム API の実行を記録します。コードで定義された操作識別子、アダプターとランナーの種類、処理モード、結果、回数、最初と最後の観測時刻、インスタンスとワークスペースの識別子、バージョン、模擬実行フラグを含みます。Core は上限付きのカウンターをメモリ内で集計し、バックグラウンドで送信します。カバレッジ分析は Space が行います。

この実行記録には、メッセージ、プロンプト、モデルの回答、プラットフォームのユーザー/グループ ID、ツール/API の引数や結果、認証情報、生の例外 traceback は含めません。インスタンスとワークスペースの識別子がデプロイ環境やアカウントに結び付く場合があります。この制限は実行記録に適用され、上記の既存クエリテレメトリの収集範囲は変更しません。

### イベント単位の実行チェーン

サンプリングされた実行記録は、1 つの受信イベントの処理過程を順序付きで示す場合があります。推測できないランダムなチェーン識別子、観測された段階（プラットフォームイベント → ルーティング判断 → Pipeline / Agent / プラグインのイベントプロセッサー → プラットフォーム API 呼び出し）、各段階の結果、ルーティング先の識別子、実行した Runner の実行識別子、チェーンを閉じた理由です。各項目は上記と同じコード定義の識別子のみを使用し、ルーティング先は `type:uuid` 形式で報告され、ユーザー定義のルール名は使用しません。Core は 1 チェーンあたりの段階数と同時に保持するチェーン数に上限を設け、超過分は破棄します。

チェーンのサンプリングは `space.execution_trace` で設定します。`off`、`failures`（失敗・キャンセル・タイムアウトした段階を含むチェーンを保持）、`sampled`（既定。それらに加えて成功したチェーンの N 件に 1 件を保持。N = `space.execution_trace_sample`）、`all` です。WebUI のデバッグ実行は常に保持され、模擬実行として記録されるため、実際の実行統計には含まれません。

接続障害、タイムアウト、サーバーエラーが通常の操作を妨げることはありません。失敗の詳細は DEBUG ログのみに記録します。キューには上限があり、障害時に記録が失われる場合があります。記録は分析の補助情報であり、プラットフォーム API の成功応答だけではメッセージが読まれたことを確認できません。

## 保存と保持期間

データは設定された Space サービスに保存されます。実行の生データは 30 日の保持期間に基づき、定期的に上限付きのバッチで削除します。処理の滞留やサービス停止で削除が遅れる場合があります。既存のクエリテレメトリ、アンケート、アカウント、サービスログの保持規則は変更しません。カバレッジ分析は、権限を持つテレメトリ管理ユーザーまたはサービスクライアントのみが利用できます。

無効化すると以後の送信は停止しますが、サーバーに保存済みの記録は削除されません。過去のデータについては <hello@langbot.app> または利用中の Space 管理者にお問い合わせください。

## テレメトリの無効化

`data/config.yaml` の既存の `space` セクションで次を設定し、他の設定を保持したうえで LangBot を再起動します。

```yaml
space:
  disable_telemetry: true
```

このスイッチはクエリ統計、ハートビート、実行テレメトリ、およびアンケート取得を無効にします。引用符を付けず YAML の真偽値を使用してください。既定の有効状態に戻すには `false` に変更し、再起動します。

環境変数 `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時にファイルの設定を上書きするため、併せて変更または削除してください。コンテナの環境変数を変更する場合はコンテナを再作成します。Cloud ではインスタンスの運用者が設定し、そのインスタンスの全ワークスペースに適用されます。Bot の動作や、メッセージングプラットフォーム、モデル提供者、プラグイン自体のプライバシー設定は変更しません。

[システム設定](https://langbot.app/docs/ja/deploy/settings.md)も参照してください。

---

# 機能

Source: https://langbot.app/docs/ja/insight/features

LangBot は、オープンソースで本番運用に耐える LLM ネイティブのインスタントメッセージングボット開発プラットフォームです。LINE、Slack、Discord、Telegram、QQ、WeChat、企業微信、Lark、DingTalk などに対応し、Agent・RAG ナレッジベース・MCP・スキル（Skills）・コードサンドボックスを内蔵。Dify、Coze、n8n、Langflow などの Agent プラットフォームと深く統合します。

LangBot は、**オープンソースで本番運用に耐える**、LLM ネイティブのインスタントメッセージングボット開発プラットフォームです。単一のコードベースで AI エージェントを LINE、Slack、Discord、Telegram、QQ、WeChat、企業微信、Lark、DingTalk などに導入でき、**Agent・RAG ナレッジベース・MCP・スキル（Skills）・コードサンドボックス**を内蔵。Dify・Coze・n8n・Langflow などの Agent プラットフォームと深く統合し、設定と監視はすべてブラウザの Web 管理パネルから行えます——設定ファイルを手書きする必要はありません。

> idea:
>
> **自分でデプロイしたくない？** [LangBot Cloud](https://space.langbot.app/cloud) をお試しください — サーバー不要、登録すればすぐに使い始められます。

## コア機能の概要

- **AI 対話 & Agent** — マルチターン対話、ツール呼び出し（function calling）、マルチモーダル（画像/音声/ファイル）、ストリーミング出力にすぐ対応。
- **RAG ナレッジベース** — ナレッジベースエンジン（ベクトル検索 + Rerank 再順位付け）を内蔵し、あなたのプライベートな知識に基づいて回答。さらにプラグインで拡張でき、RAGFlow、Dify、FastGPT などの外部ナレッジベースサービスとシームレスに接続できます。
- **全プラットフォーム対応** — 単一コードベースで LINE、Slack、Discord、Telegram、KOOK、Matrix、QQ、WeChat、企業微信、Lark、DingTalk などに到達。
- **Agent プラットフォームとの深い統合** — Dify、Coze、n8n、Langflow、Deerflow、Aliyun Bailian、Ant TBox などのオーケストレーション/ワークフロープラットフォーム向けネイティブコネクタ。
- **スキル & コードサンドボックス** — オンデマンドで起動する命令パックと、安全に隔離されたコード実行サンドボックスを組み合わせ、エージェントが実際に「作業をこなす」。
- **MCP プロトコル** — Model Context Protocol のツールエコシステムにクライアントとして接続し、Stdio と HTTP の両トランスポートに対応。
- **Web 管理パネル** — ブラウザ上で視覚的にボットを設定・管理・監視。手動での設定ファイル編集は不要。
- **本番グレードのプラグインシステム** — クロスプロセス・イベント駆動アーキテクチャ上に数百のコミュニティプラグイン。安全でホットプラグ可能。
- **マルチパイプラインアーキテクチャ** — 1 インスタントで複数のパイプラインを実行し、異なるボットが異なるシナリオを担当。アクセス制御、レート制限、センシティブワードフィルタ、包括的な監視を備える。

## インスタントメッセージングプラットフォームのサポート

LangBot は統一されたアダプター層を通じて世界の主要 IM プラットフォームをカバーします。一度開発すれば、どこへでも届きます。

| プラットフォーム        | ステータス | 備考                                                                                                          |
| --------------- | ----- | ----------------------------------------------------------------------------------------------------------- |
| QQ個人アカウント       | ✅     | OneBot v11 プロトコルをサポートするサードパーティアプリにより対応、プライベート/グループチャット                                                      |
| QQ公式ボット         | ✅     | チャンネル、プライベートチャット、グループチャットに対応                                                                                |
| WeChat          | ✅     | 個人 WeChat                                                                                                   |
| WeChat公式アカウント   | ✅     |                                                                                                             |
| 企業微信            | ✅     | 内部アプリケーションメッセージ                                                                                             |
| 企業微信インテリジェントボット | ✅     | ストリーミング出力をサポート                                                                                              |
| 企業微信カスタマーサービス   | ✅     |                                                                                                             |
| Lark            | ✅     | ストリーミング出力をサポート                                                                                              |
| DingTalk        | ✅     | ストリーミング出力をサポート                                                                                              |
| Discord         | ✅     |                                                                                                             |
| Telegram        | ✅     | ストリーミング出力をサポート                                                                                              |
| Slack           | ✅     |                                                                                                             |
| LINE            | ✅     |                                                                                                             |
| KOOK            | ✅     |                                                                                                             |
| Satori          | ✅     | [Satori](https://satori.chat/zh-CN/introduction.html) は汎用チャットプロトコルで、理論的に QQ、Zulip、米游社など 15 以上のプラットフォームをサポート |
| Matrix          | ✅     | ブリッジ経由で Signal、WhatsApp、Messenger、iMessage、Mattermost、Google Chat、IRC、XMPP、Zulip などに到達                      |
| Email（メール）      | ✅     | メールを対話チャネルとして利用                                                                                             |
| Web ページボット      | ✅     | Web ページに埋め込めるチャットウィジェット                                                                                     |
| WhatsApp        | 🚧    | 開発中（Matrix ブリッジ経由でも利用可能）                                                                                    |

🚧: 開発中

各プラットフォーム固有の機能サポート（画像・音声・ファイル・リッチテキストの送受信、ストリーミング応答など）については、[プラットフォーム機能ドキュメント](https://langbot.app/docs/ja/insight/platform-features.md)をご覧ください。

## モデルと Agent プラットフォームのサポート

LangBot は **LiteLLM を統一的なモデルリクエストバックエンド**として採用しています。そのため、下表の内蔵プロバイダーに加え、任意の OpenAI / Anthropic API 形式または LiteLLM 対応モデルにも接続できます。

### LLM・集約・GPU プラットフォーム

| プロバイダー/サービス                                                                         | ステータス | 備考                                |
| ----------------------------------------------------------------------------------- | ----- | --------------------------------- |
| [OpenAI](https://platform.openai.com/)                                              | ✅     | 任意の OpenAI 形式モデルに利用可能             |
| [Anthropic](https://www.anthropic.com/)                                             | ✅     |                                   |
| [DeepSeek](https://www.deepseek.com/)                                               | ✅     |                                   |
| [Google Gemini](https://aistudio.google.com/prompts/new_chat)                       | ✅     |                                   |
| [xAI](https://x.ai/)                                                                | ✅     |                                   |
| [Moonshot](https://www.moonshot.cn/)                                                | ✅     |                                   |
| [Zhipu AI](https://open.bigmodel.cn/)                                               | ✅     |                                   |
| [Mistral](https://mistral.ai/)                                                      | ✅     |                                   |
| [Groq](https://groq.com/)                                                           | ✅     |                                   |
| [OpenRouter](https://openrouter.ai/)                                                | ✅     | グローバル LLM ゲートウェイ                  |
| [Ollama](https://ollama.com/)                                                       | ✅     | ローカル LLM 実行プラットフォーム               |
| [LMStudio](https://lmstudio.ai/)                                                    | ✅     | ローカル LLM 実行プラットフォーム               |
| [SiliconFlow](https://siliconflow.cn/)                                              | ✅     | LLM ゲートウェイ(MaaS)                  |
| [Aliyun Bailian](https://bailian.console.aliyun.com/)                               | ✅     | LLM ゲートウェイ(MaaS) / Agent プラットフォーム |
| [Volc Engine Ark](https://console.volcengine.com/ark)                               | ✅     | LLM ゲートウェイ(MaaS) / Agent プラットフォーム |
| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro)          | ✅     | LLM ゲートウェイ(MaaS)                  |
| [GiteeAI](https://ai.gitee.com/)                                                    | ✅     | LLM インターフェースゲートウェイ(MaaS)          |
| [ShengSuanYun](https://www.shengsuanyun.com/?from=CH_KYIPP758)                      | ✅     | グローバル LLM 集約（推奨）                  |
| [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot)                       | ✅     | LLM および GPU リソースプラットフォーム          |
| [PPIO](https://ppio.com/user/register?invited_by=QJKFYD\&utm_source=github_langbot) | ✅     | LLM および GPU リソースプラットフォーム          |
| [302.AI](https://share.302ai.cn/SuTG99)                                             | ✅     | LLM ゲートウェイ(MaaS)                  |
| [Jiekou AI](https://jiekou.ai/)                                                     | ✅     | LLM ゲートウェイ(MaaS)                  |
| [TokenPony](https://www.tokenpony.cn/453z1)                                         | ✅     | LLM ゲートウェイ(MaaS)                  |
| [Qiniu](https://www.qiniu.com/ai/agent)                                             | ✅     | LLM ゲートウェイ(MaaS)                  |

### Agent プラットフォーム

既存のワークフローやエージェントをそのまま IM プラットフォームに接続でき、ビジネスロジックを書き直す必要はありません。

| プラットフォーム                                 | ステータス | 備考                       |
| ---------------------------------------- | ----- | ------------------------ |
| [Dify](https://dify.ai)                  | ✅     | Agent プラットフォーム           |
| [Coze](https://coze.cn)                  | ✅     | エージェントオーケストレーションプラットフォーム |
| [n8n](https://n8n.io/)                   | ✅     | ワークフロー自動化プラットフォーム        |
| [Langflow](https://langflow.org/)        | ✅     | ビジュアルオーケストレーションプラットフォーム  |
| [Deerflow](https://deerflow.tech)        | ✅     | ディープリサーチフレームワーク          |
| [Weknora](https://weknora.weixin.qq.com) | ✅     | WeChat ナレッジベース Q\&A      |
| [Ant TBox](https://tbox.cn/)             | ✅     | エージェントプラットフォーム           |

### Rerank（再順位付け）モデル

| プロバイダー                             | ステータス | 備考       |
| ---------------------------------- | ----- | -------- |
| [Cohere](https://cohere.com/)      | ✅     | 再順位付けモデル |
| [Jina](https://jina.ai/)           | ✅     | 再順位付けモデル |
| [Voyage AI](https://voyageai.com/) | ✅     | 再順位付けモデル |

## LLM アプリケーションパラダイムの実装

LangBot は主流の LLM アプリケーションパラダイムをすぐに使える機能として実装し、「会話できる」から「作業をこなせる」までの全パスをカバーします。

| パラダイム        | ステータス | 説明                                                                                                |
| ------------ | ----- | ------------------------------------------------------------------------------------------------- |
| Agent        | ✅     | ツール呼び出し、マルチターン推論、マルチモーダル、ストリーミング出力に対応した内蔵エージェント                                                   |
| RAG（ナレッジベース） | ✅     | ナレッジベースエンジンを内蔵（デフォルトは Chroma ベクトルストア + Rerank 再順位付け）。RAGFlow、Dify、FastGPT などの外部ナレッジベースにプラグインで接続可能 |
| MCP          | ✅     | MCP クライアントとしてツールエコシステムに接続、Stdio と HTTP に対応                                                        |
| スキル（Skills）  | ✅     | オンデマンドで起動する命令パック。マッチしたときだけコンテキストに読み込まれ、追加オーバーヘッドはゼロ                                               |
| コードサンドボックス   | ✅     | Docker / nsjail / E2B バックエンドを備えた、安全に隔離されたコード実行環境                                                  |

- **スキル（Skills）**：専門的なワークフロー、テンプレート、スクリプトをオンデマンドの命令パックとしてパッケージ化。ユーザーのリクエストにマッチしたときだけエージェントがコンテキストに読み込むため、System Prompt を汚しません。[スキルドキュメント](https://langbot.app/docs/ja/usage/skills/readme.md)を参照。
- **コードサンドボックス**：エージェントに安全に隔離されたコード実行能力を提供し、Docker / nsjail / E2B バックエンドの中から最適なものを自動選択。スキルとネイティブツールの実行基盤です。[サンドボックスドキュメント](https://langbot.app/docs/ja/usage/sandbox/readme.md)を参照。

## システムの拡張性

LangBot は二次開発とエンタープライズ統合のための完全な拡張面を提供します。

- **HTTP Service API**：API キー認証付きの HTTP インターフェースを通じて LangBot の各種エンティティにアクセスでき、既存システムとの統合が容易。
- **Outgoing Webhook**：LangBot の内部イベントを外部システムにリアルタイムでプッシュし、イベント駆動の自動化を構築。
- **本番グレードのプラグインシステム**：クロスプロセス通信と非同期技術に基づき、さまざまなコンポーネント拡張をサポート。安全・安定・ホットプラグ可能で、数百のコミュニティプラグインを[拡張マーケットプレイス](https://space.langbot.app)からワンクリックでインストール可能。
- **Web 管理パネル**：ボット、モデル、パイプライン、ナレッジベース、プラグインのすべての設定と監視を視覚的に実行。

## デプロイ方法

LangBot は 1 行のコマンドから Kubernetes クラスターまで、さまざまなデプロイ方法をサポートします。

- **LangBot Cloud（推奨）**：[デプロイ不要、すぐに使えるホスト版](https://space.langbot.app/cloud)。
- **ワンラインで起動**：`uvx langbot` を実行し、`http://localhost:5300` にアクセス。
- **Docker Compose**、**aaPanel（宝塔パネル）**、**Kubernetes**、**Zeabur / Railway でのワンクリッククラウドデプロイ**など。

詳細は[デプロイドキュメント](https://langbot.app/docs/ja/deploy/langbot/kubernetes.md)と[クイックスタート](https://langbot.app/docs/ja/insight/guide.md)をご覧ください。

## ケーススクリーンショット

![LangBot ボット設定ページ：Web 管理画面でウェブページボットをパイプラインに紐付け](https://langbot.app/docs/images/zh/insight/features/bot-page.png)

![LangBot モデル設定：OpenAI / Anthropic API 形式に対応した任意の LLM を接続](https://langbot.app/docs/images/zh/insight/features/create-model.png)

![LangBot パイプライン AI 設定：内蔵エージェントランナーとメインモデルを選択](https://langbot.app/docs/images/zh/insight/features/edit-pipeline.png)

![LangBot 拡張機能マーケットプレイス：数百のコミュニティプラグインと MCP ツールをワンクリックでインストール](https://langbot.app/docs/images/zh/insight/features/plugin-market.png)

![LangBot 内蔵エージェントがコードサンドボックスを呼び出し、Python をリアルタイム実行して正確に計算](https://langbot.app/docs/images/zh/insight/features/agent-sandbox.png)

![LangBot スキル駆動エージェント：事前定義したスキルに従って構造化された結果を出力](https://langbot.app/docs/images/zh/insight/features/agent-skill.png)

---

# LangBotドキュメントへようこそ

Source: https://langbot.app/docs/ja/insight/guide

LangBot は Discord・Telegram・WeChat・Slack 等を GPT・Claude・Gemini・DeepSeek・Dify に接続するオープンソース LLM ボットプラットフォーム。

LangBotは、**オープンソースで本番運用に耐える**、LLM ネイティブのインスタントメッセージングボットプラットフォームです。OpenAI、Anthropic、Gemini、DeepSeek などの大規模言語モデルや、Dify、Coze、n8n などの Agent プラットフォームを、LINE、Slack、Discord、Telegram、QQ、WeChat、企業微信、Lark、DingTalk といった主要メッセージングプラットフォームに接続します。Agent、RAG ナレッジベース、MCP、スキル（Skills）、コードサンドボックスを内蔵し、すぐに使える Web 管理パネルを提供——設定ファイルを手書きする必要はなく、数分で AI ボットを公開できます。

![LangBot Web 管理パネルのダッシュボード：メッセージ量、モデル呼び出し、成功率、アクティブセッション、トラフィック傾向をリアルタイム監視](https://langbot.app/docs/images/zh/insight/dashboard-overview.png)

## 何ができるか

- **AI カスタマーサービス / 企業アシスタント**：ナレッジベースに基づく AI エージェントを LINE、Slack、Lark、企業微信、DingTalk に展開し、顧客や従業員の質問に自動応答。
- **コミュニティ運営**：Discord、Telegram、QQ グループで AI による Q\&A、コンテンツモデレーション、インタラクションを提供。
- **ワークフロー統合**：既存の Dify / n8n / Coze ワークフローをそのままチャットプラットフォームに接続。ビジネスロジックの書き直しは不要。
- **マルチプラットフォーム到達**：1 つのボットですべてのプラットフォームをカバーし、統一パネルから集中管理。

## はじめに

次の順序で LangBot の全体像をつかみ、必要なガイドへ進んでください。

1. **機能と対応プラットフォームを知る**：[機能概要](https://langbot.app/docs/ja/insight/features.md)と[プラットフォーム対応状況](https://langbot.app/docs/ja/insight/platform-features.md)で、用途に合うか確認できます。
2. **導入方法を選ぶ**：サーバーを自分で管理しないなら [LangBot Cloud](https://space.langbot.app/cloud)、セルフホストするなら [Docker](https://langbot.app/docs/ja/deploy/langbot/docker.md) または[パッケージマネージャー](https://langbot.app/docs/ja/deploy/langbot/package.md)のガイドへ。
3. **ボットとモデルを接続する**：[ボット設定](https://langbot.app/docs/ja/usage/platforms/readme.md)、[モデル設定](https://langbot.app/docs/ja/usage/models/readme.md)、[パイプライン](https://langbot.app/docs/ja/usage/pipelines/readme.md)で、チャットプラットフォームと AI 機能のつなぎ方を確認できます。
4. **ボットの機能を拡張する**：[ナレッジベース](https://langbot.app/docs/ja/usage/knowledge/readme.md)、[プラグイン](https://langbot.app/docs/ja/plugin/plugin-intro.md)、[MCP](https://langbot.app/docs/ja/usage/mcp/readme.md)、[スキル](https://langbot.app/docs/ja/usage/skills/readme.md)を活用できます。
5. **活用例を探す・開発に参加する**：[活用記事](https://langbot.app/docs/ja/articles.md)でアイデアを探すか、[プラグイン開発](https://langbot.app/docs/ja/plugin/dev/tutor.md)と[コア開発環境](https://langbot.app/docs/ja/develop/dev-config.md)をご覧ください。

困ったときは[トラブルシューティング](https://langbot.app/docs/ja/insight/troubleshooting.md)を確認するか、[コミュニティ](https://langbot.app/docs/ja/insight/community.md)で相談してください。

> AI エージェントに導入・利用を手伝ってもらう:
>
> 以下のプロンプトを AI アシスタントにコピーしてください。公式ドキュメントを読み、環境と目的に合った方法でサポートします。
>
> ```text
> LangBot の導入と利用を手伝ってください。まず公式ドキュメントを読み、私の環境に合った方法を提案してください。
>
> 日本語ドキュメント索引 https://langbot.app/docs/ja/llms.txt と、次の主要ページを読んでください。
> - 機能概要：https://langbot.app/docs/ja/insight/features.md
> - 対応プラットフォーム：https://langbot.app/docs/ja/insight/platform-features.md
> - ボット設定：https://langbot.app/docs/ja/usage/platforms/readme.md
> - モデル設定：https://langbot.app/docs/ja/usage/models/readme.md
> - パイプライン：https://langbot.app/docs/ja/usage/pipelines/readme.md
>
> 最初に、使いたいチャットプラットフォームとモデル、既存の LangBot 環境の有無を確認してください。導入が必要なら、OS、サーバーまたはローカル環境、クラウドかセルフホストかの希望を確認し、索引から該当する導入・接続ガイドを読んでください。コマンドや設定項目は推測しないでください。
>
> ドキュメントに基づいて、導入、ボット接続、モデル、パイプラインの設定を支援してください。実行ツールがあれば、私が許可した環境内で実行して結果を検証し、なければ環境に合った操作手順を案内してください。既存の環境があれば優先して利用してください。設定の上書き、データ削除、課金を伴う操作は事前に確認し、チャットにシークレットを貼り付けるよう求めないでください。
>
> 最後に実際のテストメッセージを送り、ボットが返信することを確認するまで手伝ってください。基本機能が動いてから、必要に応じてナレッジベース、プラグイン、MCP、スキルを案内してください。文書を読めない場合や操作が失敗した場合は明示し、未検証の作業を完了したと報告しないでください。
> ```

---

# 各メッセージプラットフォームの機能サポート

Source: https://langbot.app/docs/ja/insight/platform-features

各メッセージングプラットフォームでの LangBot 機能サポートを比較：Discord・Telegram・WeChat・Slack・QQ・Lark・DingTalk 等。

以下は各プラットフォームで実装およびテスト済みの機能リストです。予期しない動作が発生した場合は、[GitHub Issues](https://github.com/langbot-app/LangBot/issues)に報告するか、Pull Requestを直接提出して修正にご協力ください。

## OneBot v11

### 受信

| 機能                      | ステータス | 備考            |
| ----------------------- | ----- | ------------- |
| プライベートメッセージの受信          | ✅     |               |
| グループメンションメッセージの受信       | ✅     |               |
| グループ通常メッセージの受信          | ✅     |               |
| 画像メッセージの受信              | ✅     |               |
| 音声メッセージの受信              | ✅     |               |
| ファイルメッセージの受信            | ✅     |               |
| リッチテキストメッセージの受信         | ✅     | テキストと画像の組み合わせ |
| プライベートメッセージイベントのユーザー名取得 | ✅     |               |
| グループメッセージイベントのグループ名取得   | ✅     |               |
| グループメッセージイベントの送信者名取得    | ✅     |               |

### 送信

| 機能               | ステータス | 備考            |
| ---------------- | ----- | ------------- |
| プライベートメッセージへの返信  | ✅     |               |
| グループメッセージへの返信    | ✅     |               |
| 画像メッセージでの返信      | ✅     |               |
| 音声メッセージでの返信      | ✅     |               |
| ファイルメッセージでの返信    | ✅     |               |
| リッチテキストメッセージでの返信 | ✅     | テキストと画像の組み合わせ |
| 能動的メッセージの送信      | ✅     |               |
| ストリーミングレスポンスの送信  | ❌     |               |

## QQ公式ボット

## 企業微信（内部アプリケーション）

### 受信

| 機能                      | ステータス | 備考                               |
| ----------------------- | ----- | -------------------------------- |
| プライベートメッセージの受信          | ✅     |                                  |
| グループメンションメッセージの受信       | ❌     | 企業微信内部アプリケーションはグループ追加をサポートしていません |
| グループ通常メッセージの受信          | ❌     |                                  |
| 画像メッセージの受信              | ✅     |                                  |
| 音声メッセージの受信              | ✅     |                                  |
| ファイルメッセージの受信            | ✅     |                                  |
| リッチテキストメッセージの受信         | ❌     |                                  |
| プライベートメッセージイベントのユーザー名取得 | ✅     |                                  |
| グループメッセージイベントのグループ名取得   | ❌     |                                  |
| グループメッセージイベントの送信者名取得    | ❌     |                                  |

### 送信

| 機能               | ステータス | 備考 |
| ---------------- | ----- | -- |
| プライベートメッセージへの返信  | ✅     |    |
| グループメッセージへの返信    | ❌     |    |
| 画像メッセージでの返信      | ✅     |    |
| 音声メッセージでの返信      | ✅     |    |
| ファイルメッセージでの返信    | ✅     |    |
| リッチテキストメッセージでの返信 | ❌     |    |
| 能動的メッセージの送信      | ✅     |    |
| ストリーミングレスポンスの送信  | ❌     |    |

## Satori

### 受信

| 機能                      | ステータス | 備考            |
| ----------------------- | ----- | ------------- |
| プライベートメッセージの受信          | ✅     |               |
| グループメンションメッセージの受信       | ✅     |               |
| グループ通常メッセージの受信          | ✅     |               |
| 画像メッセージの受信              | ✅     |               |
| 音声メッセージの受信              | ✅     |               |
| ファイルメッセージの受信            | ✅     |               |
| リッチテキストメッセージの受信         | ✅     | テキストと画像の組み合わせ |
| プライベートメッセージイベントのユーザー名取得 | ✅     |               |
| グループメッセージイベントのグループ名取得   | ✅     |               |
| グループメッセージイベントの送信者名取得    | ✅     |               |

### 送信

| 機能               | ステータス | 備考            |
| ---------------- | ----- | ------------- |
| プライベートメッセージへの返信  | ✅     |               |
| グループメッセージへの返信    | ✅     |               |
| 画像メッセージでの返信      | ✅     |               |
| 音声メッセージでの返信      | ✅     |               |
| ファイルメッセージでの返信    | ✅     |               |
| リッチテキストメッセージでの返信 | ✅     | テキストと画像の組み合わせ |
| 能動的メッセージの送信      | ✅     |               |
| ストリーミングレスポンスの送信  | ❌     |               |

## 企業微信（カスタマーサービス）

## 企業微信インテリジェントボット

## WeChat公式アカウント

## Lark

### 受信

| 機能                      | ステータス | 備考                          |
| ----------------------- | ----- | --------------------------- |
| プライベートメッセージの受信          | ✅     |                             |
| グループメンションメッセージの受信       | ✅     |                             |
| グループ通常メッセージの受信          | ❌     | Larkはボットをメンションしたメッセージのみ受信可能 |
| 画像メッセージの受信              | ✅     |                             |
| 音声メッセージの受信              | ❌     | Larkには音声メッセージがありません         |
| ファイルメッセージの受信            | ✅     |                             |
| リッチテキストメッセージの受信         | ✅     | テキストと画像の組み合わせ               |
| プライベートメッセージイベントのユーザー名取得 | ❌     | Larkはユーザー名の取得をサポートしていません    |
| グループメッセージイベントのグループ名取得   | ❌     | Larkはグループ名の取得をサポートしていません    |
| グループメッセージイベントの送信者名取得    | ❌     | Larkは送信者名の取得をサポートしていません     |

### 送信

| 機能               | ステータス | 備考 |
| ---------------- | ----- | -- |
| プライベートメッセージへの返信  | ✅     |    |
| グループメッセージへの返信    | ✅     |    |
| 画像メッセージでの返信      | ✅     |    |
| 音声メッセージでの返信      | ❌     |    |
| ファイルメッセージでの返信    | ❌     |    |
| リッチテキストメッセージでの返信 | ❌     |    |
| 能動的メッセージの送信      | ✅     |    |
| ストリーミングレスポンスの送信  | ✅     |    |

## DingTalk

### 受信

| 機能                      | ステータス | 備考                              |
| ----------------------- | ----- | ------------------------------- |
| プライベートメッセージの受信          | ✅     |                                 |
| グループメンションメッセージの受信       | ✅     |                                 |
| グループ通常メッセージの受信          | ❌     | DingTalkはボットをメンションしたメッセージのみ受信可能 |
| 画像メッセージの受信              | ✅     |                                 |
| 音声メッセージの受信              | ✅     |                                 |
| ファイルメッセージの受信            | ✅     |                                 |
| リッチテキストメッセージの受信         | ✅     | テキストと画像の組み合わせ                   |
| プライベートメッセージイベントのユーザー名取得 | ✅     |                                 |
| グループメッセージイベントのグループ名取得   | ✅     |                                 |
| グループメッセージイベントの送信者名取得    | ✅     |                                 |

### 送信

| 機能               | ステータス | 備考            |
| ---------------- | ----- | ------------- |
| プライベートメッセージへの返信  | ✅     |               |
| グループメッセージへの返信    | ✅     |               |
| 画像メッセージでの返信      | ✅     |               |
| 音声メッセージでの返信      | ❌     |               |
| ファイルメッセージでの返信    | ❌     |               |
| リッチテキストメッセージでの返信 | ✅     | テキストと画像の組み合わせ |
| 能動的メッセージの送信      | ✅     |               |
| ストリーミングレスポンスの送信  | ✅     |               |

## KOOK

P.S. 音声とファイルの送信にエラーがあり、未修正

### 受信

| 機能                      | ステータス | 備考            |
| ----------------------- | ----- | ------------- |
| プライベートメッセージの受信          | ✅     |               |
| グループメンションメッセージの受信       | ✅     |               |
| グループ通常メッセージの受信          | ✅     |               |
| 画像メッセージの受信              | ✅     |               |
| 音声メッセージの受信              | ✅     |               |
| ファイルメッセージの受信            | ✅     |               |
| リッチテキストメッセージの受信         | ✅     | テキストと画像の組み合わせ |
| プライベートメッセージイベントのユーザー名取得 | ✅     |               |
| グループメッセージイベントのグループ名取得   | ✅     |               |
| グループメッセージイベントの送信者名取得    | ✅     |               |

### 送信

| 機能               | ステータス | 備考                          |
| ---------------- | ----- | --------------------------- |
| プライベートメッセージへの返信  | ✅     |                             |
| グループメッセージへの返信    | ✅     |                             |
| 画像メッセージでの返信      | ✅     |                             |
| 音声メッセージでの返信      | ❌     | KOOKは音声メッセージでの返信をサポートしていません |
| ファイルメッセージでの返信    | ❌     |                             |
| リッチテキストメッセージでの返信 | ✅     | テキストと画像の組み合わせ               |
| 能動的メッセージの送信      | ✅     |                             |
| ストリーミングレスポンスの送信  | ❌     |                             |

## Discord

### 受信

| 機能                      | ステータス | 備考            |
| ----------------------- | ----- | ------------- |
| プライベートメッセージの受信          | ✅     |               |
| グループメンションメッセージの受信       | ✅     |               |
| グループ通常メッセージの受信          | ✅     |               |
| 画像メッセージの受信              | ✅     |               |
| 音声メッセージの受信              | ❌     |               |
| ファイルメッセージの受信            | ✅     |               |
| リッチテキストメッセージの受信         | ✅     | テキストと画像の組み合わせ |
| プライベートメッセージイベントのユーザー名取得 | ✅     |               |
| グループメッセージイベントのグループ名取得   | ✅     |               |
| グループメッセージイベントの送信者名取得    | ✅     |               |

### 送信

| 機能               | ステータス | 備考              |
| ---------------- | ----- | --------------- |
| プライベートメッセージへの返信  | ✅     |                 |
| グループメッセージへの返信    | ✅     |                 |
| 画像メッセージでの返信      | ✅     | ファイル添付として送信     |
| 音声メッセージでの返信      | ✅     | ファイル添付として送信     |
| ファイルメッセージでの返信    | ✅     |                 |
| リッチテキストメッセージでの返信 | ✅     | テキストとファイルの組み合わせ |
| 能動的メッセージの送信      | ✅     |                 |
| ストリーミングレスポンスの送信  | ❌     |                 |

## Telegram

P.S. 未テスト

### 受信

| 機能                      | ステータス | 備考 |
| ----------------------- | ----- | -- |
| プライベートメッセージの受信          | ✅     |    |
| グループメンションメッセージの受信       | ✅     |    |
| グループ通常メッセージの受信          | ✅     |    |
| 画像メッセージの受信              | ✅     |    |
| 音声メッセージの受信              | ❌     |    |
| ファイルメッセージの受信            | ✅     |    |
| リッチテキストメッセージの受信         | ✅     |    |
| プライベートメッセージイベントのユーザー名取得 | ✅     |    |
| グループメッセージイベントのグループ名取得   | ✅     |    |
| グループメッセージイベントの送信者名取得    | ✅     |    |

### 送信

| 機能               | ステータス | 備考 |
| ---------------- | ----- | -- |
| プライベートメッセージへの返信  | ✅     |    |
| グループメッセージへの返信    | ✅     |    |
| 画像メッセージでの返信      | ✅     |    |
| 音声メッセージでの返信      | ✅     |    |
| ファイルメッセージでの返信    | ✅     |    |
| リッチテキストメッセージでの返信 | ✅     |    |
| 能動的メッセージの送信      | ✅     |    |
| ストリーミングレスポンスの送信  | ❌     |    |

## Slack

## LINE

---

# トラブルシューティング

Source: https://langbot.app/docs/ja/insight/troubleshooting

LangBot のローカルデプロイと実行時によくある問題を、症状・原因・解決方法ごとにまとめます。現在は Docker デプロイの問題を扱います。

このページは、よくある問題の調査手順をまとめるためのものです。現在は Docker デプロイ時の問題を扱います。今後、モデル、ボットアダプター、MCP、Skills などの章を追加できます。

以下のコマンドは `LangBot/docker` ディレクトリで実行する前提です。

## Docker デプロイ

### 起動前の確認

サンドボックス、stdio MCP ホスティング、Skill の追加/編集を使う場合は、`all` profile で起動してください:

```bash
docker compose --profile all up -d
```

サービス状態を確認します:

```bash
docker compose --profile all ps
```

通常は次のサービスが表示されます:

- `langbot`: WebUI とバックエンドサービス。既定で `5300` と `2280-2285` を公開します。
- `langbot_plugin_runtime`: プラグインランタイム。既定で `5401` を公開します。
- `langbot_box`: Box Runtime のコントロールプレーン。サンドボックスコンテナを作成します。

`docker compose up` だけを実行した場合、`langbot_box` は起動しません。そのため stdio MCP、Skill の追加/編集、一部のサンドボックス依存機能は利用できません。

### ポート競合

#### 症状

- `docker compose up` がポートバインドエラーで失敗する。
- `http://127.0.0.1:5300` で WebUI を開けない。
- ログに `port is already allocated` や `bind: address already in use` が出る。

#### 解決方法

ポートを使用しているプロセスを確認します。Linux/macOS:

```bash
lsof -i :5300
lsof -i :5401
```

Windows PowerShell:

```powershell
Get-NetTCPConnection -LocalPort 5300,5401 | Select-Object LocalPort,OwningProcess
Get-Process -Id <PID>
```

古い LangBot、プラグインランタイム、テストプロセスであることを確認できた場合は停止し、再起動します:

```bash
docker compose --profile all up -d
```

停止できないプロセスの場合は、`docker-compose.yaml` の該当ポートマッピングを変更してください。

### Box Runtime が利用できない

#### 症状

- UI またはログに `No sandbox backend (Docker/nsjail/E2B) is ready` と表示される。
- stdio MCP サーバーが利用できない。
- Skills をインストール、アクティベート、編集できない。

#### 主な原因

- `--profile all` または `--profile box` で起動していない。
- `langbot_box` が起動していない。
- Docker Desktop または現在のユーザーが Docker にアクセスできない。
- Linux で現在のユーザーに Docker socket への権限がない。

#### 解決方法

`langbot_box` が起動しているか確認します:

```bash
docker compose --profile all ps
docker logs langbot_box --tail 100
```

Docker 自体が利用できるか確認します:

```bash
docker info
```

Linux で必要な場合は、現在のユーザーを `docker` グループに追加し、再ログインします:

```bash
sudo usermod -aG docker $USER
newgrp docker
docker info
```

その後、コンテナを再作成します:

```bash
docker compose --profile all up -d --force-recreate
```

### Box root のマウントに失敗する

#### 症状

- ログに `host_path is outside allowed_mount_roots` が出る。
- ログに `host_path must point to an existing directory on the host` が出る。
- Docker Desktop 環境で Box root が `/run/desktop/...` に解決され、拒否される。
- stdio MCP または Skill のサンドボックスコンテナを作成できない。

#### 原因

`langbot_box` はホスト Docker socket 経由でサンドボックスコンテナを作成します。サンドボックスコンテナから見えるのはホスト側のパスなので、Box root はホスト側とコンテナ内で同一パスである必要があり、かつ `allowed_mount_roots` の配下でなければなりません。

#### 解決方法

Docker がマウントでき、Box の安全チェックで許可される絶対パスを `LangBot/docker/.env` に設定します:

```dotenv
LANGBOT_BOX_ROOT=/var/lib/langbot/box
```

Windows Docker Desktop では、Docker VM から見えるパスを使用します。例:

```dotenv
LANGBOT_BOX_ROOT=/host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
```

ディレクトリが存在することを確認し、コンテナを再作成します:

```bash
docker compose --profile all up -d --force-recreate
```

以前に `docker/data/config.yaml` を手動で変更している場合は、同じ root を指しているか確認してください:

```yaml
box:
  local:
    host_root: /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
    allowed_mount_roots:
      - /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
```

### 多数の stdio MCP が失敗する、または connecting のままになる

#### 症状

- MCP の状態が `connecting` のまま、または `error` になる。
- `docker logs langbot_box` に `Cannot fork` が出る。
- 多数の stdio MCP をインストールしたあと、以前は動いていた MCP も起動に失敗する。

#### 原因

stdio MCP は Box サンドボックス内で実行されます。既定の Box profile は PID 制限が比較的小さいため、`npx` や `uvx` ベースの MCP を同時に多く起動するとプロセス数の上限に達することがあります。

#### 解決方法

`docker/data/config.yaml` で、より大きな組み込み Box profile を使います:

```yaml
box:
  local:
    profile: network_extended
```

次に LangBot と Box を停止し、古い共有サンドボックスを削除して、コンテナを再作成します。

Linux/macOS:

```bash
docker compose --profile all stop langbot langbot_box
docker rm -f $(docker ps -aq --filter "name=langbot-box-mcp-shared")
docker compose --profile all up -d --force-recreate
```

Windows PowerShell:

```powershell
docker compose --profile all stop langbot langbot_box
docker ps -a --filter "name=langbot-box-mcp-shared" --format "{{.Names}}" | ForEach-Object { docker rm -f $_ }
docker compose --profile all up -d --force-recreate
```

MCP のコールドスタート完了後、MCP 管理ページで対象サーバーが `connected` になり、ツール数が `0` ではないことを確認します。

### MCP はインストール済みだがツールがない、または接続できない

#### 症状

- MCP サーバーは一覧にあるが、状態が `error` または長時間 `connecting` のまま。
- ツール数が `0`。
- リモート MCP のログに `401 Unauthorized`、接続タイムアウト、ハンドシェイク失敗が出る。

#### 主な原因

- リモート MCP に API Key または OAuth 認証が必要だが、設定されていない。
- MCP パッケージが `npx` または `uvx` で初回起動中で、依存関係のダウンロードに時間がかかっている。
- 現在の Docker ネットワークから MCP サービスまたはパッケージレジストリに到達できない。
- stdio MCP のサンドボックスリソースが不足している。

#### 解決方法

LangBot Space では、認証情報が不要な MCP を優先するか、必要な認証情報を正しく設定してください。認証が必要な MCP では、インストール時に環境変数、ヘッダー、URL パラメーターを入力します。

実行時ログを確認します:

```bash
docker logs langbot --tail 200
docker logs langbot_box --tail 200
```

現在の環境で接続できないサーバーは、MCP 管理ページで無効化または削除し、以後の確認結果を混乱させないようにします。

### イメージタグまたはレジストリが一致しない

#### 症状

- `docker compose ps` で古いイメージが表示される。
- イメージのレジストリやタグを変更しても、再起動後に反映されない。
- `langbot`、`langbot_plugin_runtime`、`langbot_box` が異なるイメージタグを使用している。

#### 解決方法

3 つの LangBot サービスのイメージタグを一致させてから、pull と再作成を行います:

```bash
docker pull rockchin/langbot:latest
docker compose --profile all up -d --force-recreate
```

既定以外のタグを意図的に使う場合は、`docker-compose.yaml` の `langbot`、`langbot_plugin_runtime`、`langbot_box` の 3 箇所をすべて同じタグに変更してください。

### 修正後の確認

修正後は、次の確認を行うことを推奨します:

```bash
docker compose --profile all ps
docker inspect langbot langbot_plugin_runtime langbot_box --format '{{.Name}} {{.Config.Image}} {{.State.Status}}'
```

WebUI を確認します:

```bash
curl -I http://127.0.0.1:5300/
```

UI でも以下を確認します:

- ログインできる。
- Box / サンドボックス機能が利用できる。
- 対象 MCP サーバーが `connected` になっている。
- stdio MCP のツール数が想定どおり表示される。

---

# 認証プラグインと共有実行

Source: https://langbot.app/docs/ja/plugin/certified-plugins

認証とは何か、なぜ存在するのか、いつ必要か、そして shared-runtime-v1 / stateless-v1 の規約。

## 認証とは

認証とは、LangBot が**正確で不変な 1 つのプラグイン artifact** に対して付与する資格です。その artifact は LangBot Cloud で**テナントをまたいで共有実行**することが承認されます。

- 認証は artifact そのもの（digest で識別される特定の公開バージョン）に紐付き、プラグイン名や作者には紐付きません。新しいバージョンを公開しても、前のバージョンの認証は引き継がれません。
- 認証は品質評価ではなく、セキュリティ監査の保証でもありません。

## なぜ認証が必要か

LangBot は既定ではプラグインを共有実行しません。共有の単位が artifact だからです。

- **専用モード**：共有に参加せず、単独で実行します。
- **共有モード**：同じ artifact digest のすべての installation が 1 つの Worker を共有します。

共有の利点は、プロセス数と起動コストが installation 数に比例して増えないことです。代償は、**1 つのプロセスが複数の Workspace からの呼び出しを同時に処理する**ことです。インスタンスにテナントデータを置いているプラグインは、テナント間でデータが混ざります。

そのためプラットフォームは、この artifact を審査してステートレス規約を満たすことを確認し、その信頼を署名で artifact に固定したうえで、共有配置に載せます。これが認証の目的です。

## 認証が必要な場合

**ほとんどのプラグインには認証は不要です。** 認証しなくてもマーケットプレイスへの公開は可能で、ユーザーの利用も妨げられません。プラグインは専用モードで動作します。

| 状況                                                        | 認証の要否             |
| --------------------------------------------------------- | ----------------- |
| マーケットプレイスに公開してユーザーに使ってもらいたいだけ                             | 不要                |
| 呼び出しをまたぐプロセス内状態が必要（常駐する外部セッションプロセスなど）                     | 不要。専用実行のままにしてください |
| バックグラウンドタスク、タイマー、長期のテナントキャッシュがある                          | 不要。専用モードのほうが安全です  |
| 認証プラグインの表示がほしい                                            | 必要                |
| 同じ artifact の複数 installation で 1 つのプロセスを共有し、コストと起動負荷を下げたい | 必要                |
| Cloud のマルチテナント向けで、共有配置されたい                                | 必要                |

判断基準は 1 つだけです。**インスタンスにテナントや installation に紐づくデータを一切保存しないと本当に言い切れる場合にのみ、認証に意味があります。**

## 認証後の効果

審査を通過すると、次のようになります。

- artifact が署名され、インストール時は**共有モード**で実行されます。同じ digest の複数の installation が 1 つの Worker を共有します。
- その Worker 内には `BasePlugin` が 1 つ、宣言した各コンポーネント manifest につき 1 つのインスタンス（EventListener、Tool、Command、KnowledgeEngine、Parser、Page、Runner）だけが存在します。
- 各 installation は軽量な設定・権限・ライフサイクルコンテキストを 1 つだけ保持し、呼び出しごとに現在のリクエストがどれを使うかを決定します。
- 認証プラグインの表示が付与されます。
- セルフホスト OSS は認証発行者の公開鍵を既定で持たないため、認証済みの artifact でもセルフホスト環境では専用モードで動作します。

同時に継続的な義務も発生します。**以降のすべてのバージョンがステートレス規約を満たし続ける必要があります。** コードを変更したら新しいバージョンを提出して再審査を受けます。認証は自動更新されません。

## 必要な対応

### 宣言

`manifest.yaml` の `execution` 配下に 2 つのフィールドを同時に宣言します。

```yaml
apiVersion: v1
kind: Plugin
metadata:
  author: your-name
  name: YourPlugin
  version: 0.1.1
spec:
  config: []
  components: {}
execution:
  python:
    path: main.py
    attr: YourPlugin
  sharedRuntime: shared-runtime-v1
  componentModel: stateless-v1
```

| フィールド                      | 有効な値                | 説明                                |
| -------------------------- | ------------------- | --------------------------------- |
| `execution.sharedRuntime`  | `shared-runtime-v1` | この値のみ受け付けます。他の値を書くとマニフェスト検証に失敗します |
| `execution.componentModel` | `stateless-v1`      | この値のみ受け付けます                       |

- 2 つのフィールドは**必ず同時に**宣言します。`sharedRuntime` だけを宣言し `componentModel` を書かないパッケージは、認証検証の段階で拒否されます。
- これらのフィールドは **SDK 0.7.0** 以降で認識されます。それ以前の SDK は無視するため、古い SDK で宣言の有効性を確認しないでください。

> warning:
>
> 宣言は申請であり、承認ではありません。宣言だけでは認証表示も付与されず、実行モードも変わりません。

### ステートレス規約

- `BasePlugin.initialize()` とコンポーネントの `initialize()` は**プロセス単位**の初期化で、Worker ごとに 1 回だけ実行されます。この時点では「現在のインストール」も「現在の Workspace」も存在しません。
- コンポーネントインスタンスは異なる Workspace から同時に呼び出されるため、すべてのメソッドは再入可能でなければなりません。
- 現在のインストール設定は呼び出しごとに読み取ります。`BasePlugin` では `self.get_config()`、コンポーネントでは `self.get_plugin_config()` または `self.plugin.get_config()`、Runner では `ctx.config` を使用します。
- 設定、資格情報、Workspace / installation ID、リクエストデータをインスタンス属性やモジュールグローバルに保存しないでください。
- `initialize()` でインストール設定を読み取り、保持しないでください。
- ストレージ、ファイル、資格情報、ログ、モデルなどのプラットフォーム機能は SDK の Host API 経由で利用します。権限は呼び出しごとに解決されるため、自分でキャッシュしないでください。
- 呼び出しをまたいで保持する必要があるテナント状態は Host サービスに置きます。Runner は `ctx.state_get()` / `ctx.state_set()` などを使用します（`ctx.context.available_apis.state` が `true` である必要があります）。プロセス内キャッシュは artifact レベルの公開データのみ許可されます。テナントデータをキャッシュする場合は、キーに完全な installation 識別子を含め、インストール削除時に解放できるようにしてください。
- テナントデータを伴うバックグラウンドタスクやスレッドを開始しないでください。SDK は自分で作成した処理の所有権を**追跡しません**。どうしてもハンドラーから切り離す場合は、installation binding をキーにした登録表を保ち、`on_installation_revoked()` で停止してください。ハンドラーが戻った時点で、その呼び出しのコンテキストと実行関連の呼び出しは無効になります。

### 1 つの installation、複数の用途

1 つの Workspace でプラグインをインストールできるのは 1 回ですが、その installation は**複数のプロダクトオブジェクト**から再利用されます。

| コンポーネント種別                             | 再利用するもの              | 分離のされ方                                                               |
| ------------------------------------- | -------------------- | -------------------------------------------------------------------- |
| Agent / パイプラインの Runner                | 各プロセッサ               | `ctx.state.*` は既にプロセッサ単位（スコープに `binding_identity`（Agent UUID 由来）を含む） |
| ナレッジベースの KnowledgeEngine / Parser     | 各ナレッジベース             | **プラグイン自身がナレッジベース ID で分離する必要があります**                                  |
| Tool / Command / EventListener / Page | 複数のプロセッサ、会話、ページリクエスト | 呼び出しごとに読み取り、インスタンスに蓄積しない                                             |

プラットフォームのストレージキーは `(instance, Workspace, owner type, plugin, key)` で、**プロセッサやナレッジベースの次元を含みません**。したがって永続化やキャッシュを行う場合は、キーにプロダクトオブジェクトの識別子を含めてください。

- **設定**：呼び出しごとに読み取る（`ctx.config`、または task-local な `self.get_plugin_config()`）。インスタンスにキャッシュしない。
- **永続化**：キーにプロダクトの識別子（プロセッサ ID / ナレッジベース ID / 会話 ID）を含める。
- **プロセス内キャッシュ**：キーに完全な installation binding **と** プロダクトの識別子の両方を含め、installation が取り消されたときに解放する（下記）。
- **ロックとフェンス**：`(installation, プロダクトオブジェクト)` 単位で記録する。**1 つのプロセッサやナレッジベースの失敗が、同じ installation の他を遮断してはいけません。**
- **失敗の切り分け**：手動対账が必要な状態に入るのは、送出済みで結果不明の変更だけにします。決定的な検証エラーや送出前のキャンセルは後続に影響させない。
- **ログとテレメトリ**：診断の失敗が業務に影響してはいけませんし、テナントデータをプロセス全体のシングルトンに書かないでください。

### installation が取り消されたとき

共有配置では 1 つのオブジェクトグラフが同じ artifact の全 installation にサービスするため、**1 つの installation を取り消してもオブジェクトグラフは破棄されません**。プラグインが binding 単位のプロセス内状態を自分で解放する必要があります。

```python
class MyPlugin(BasePlugin):
    def __init__(self) -> None:
        super().__init__()
        self._caches: dict[str, Cache] = {}

    async def on_installation_revoked(self, binding) -> None:
        self._caches.pop(binding.installation_uuid, None)
```

- **呼ばれる場面**：アンインストール、無効化、Workspace の削除、および**アップグレード**（旧 binding が取り消される）。共有配置でのみ呼ばれます。専用ワーカーは停止されるため、プロセス内状態はプロセスとともに消えます。
- **呼び出し中は有効な invocation がありません**。Host API（ストレージ、設定、binding 参照）は利用できず、解放できるのはプロセス内状態だけです。installation は引数で渡されます。
- 例外はログに記録され、**取り消し処理を妨げません**。
- `BasePlugin.on_installation_revoked` を提供する SDK バージョンが必要です。それ以前のバージョンではこのフックは呼ばれません。

### 許可 / 禁止の対照表

| 項目                      | 許可                                                     | 禁止                                             |
| ----------------------- | ------------------------------------------------------ | ---------------------------------------------- |
| 設定の読み取り                 | 呼び出しごとに読み取る（`self.get_plugin_config()`、`ctx.config`）   | `initialize()` で読み取り `self` に保持する              |
| コネクションプール / HTTP クライアント | テナント資格情報を含まない共有プール                                     | インストールの endpoint や api key をインスタンスに固定する        |
| キャッシュ                   | artifact レベルの公開データ、または完全な installation 識別子をキーとし解放可能なもの | Workspace やユーザーをキーにしたモジュールレベルの `dict` を長期間保持する |
| 呼び出しをまたぐ状態              | Host サービス（Runner は `ctx.state_*`）                      | インスタンス属性、モジュールグローバル                            |
| バックグラウンド処理              | なし                                                     | ハンドラーが戻った後もそのコンテキストや実行関連の呼び出しを保持する             |
| ログ                      | `ctx.log()` または SDK のログ API                            | モジュールレベルのバックグラウンドスレッドからテナント設定や資格情報を出力する        |

### よくある反例

**1. 初期化時にインストール設定を読み取る**

```python
async def initialize(self):
    self.endpoint = self.plugin.config["endpoint"]  # プロセス単位の初期化。現在のインストールは存在しない
    self.api_key = self.plugin.config["api_key"]
```

共有初期化の段階にはインストール設定がないため、空の値または前回の値しか読めません。

**2. テナントデータをモジュールグローバルにキャッシュする**

```python
_CACHE = {}  # Workspace やユーザーをキーにすると、インストールやテナントをまたいで残留する

async def call(self, params, **kwargs):
    if params["user"] not in _CACHE:
        _CACHE[params["user"]] = await fetch(params["user"])
```

**3. ハンドラーが戻った後も処理を続ける**

```python
async def call(self, params, **kwargs):
    config = self.get_plugin_config()
    asyncio.create_task(self._upload_later(config))  # ハンドラーは既に戻っており、コンテキストと権限は無効
    return ok()
```

**4. インスタンス属性を設定の入れ物として扱う**

```python
async def initialize(self):
    self.default_endpoint = "https://api.example.com"  # 公開定数は問題ない
    self.last_config = {}  # インストール設定を書き込むと違反になる
```

正しい形：

```python
class LookupTool(Tool):
    async def initialize(self):
        # artifact レベルでテナント情報を含まないオブジェクトのみを置く
        self.transport = StatelessHTTPTransport()

    async def call(self, params, **kwargs):
        config = self.get_plugin_config()  # 呼び出しごとに現在のインストール設定を読み取る
        return await self.transport.lookup(config["endpoint"], params)
```

### Runner コンポーネントの注意点

Runner はステートレス規約との緊張が最も大きくなります。実行器はセッションやコンテキストをプロセス内に保持しがちだからです。

- `RunnerContext` は**今回の実行中のみ有効**です。コンテキストやその要素をインスタンスに保存して呼び出しをまたいで再利用しないでください。
- Runner が呼び出しをまたいで保持する必要があるセッション状態は、`ctx.state_get()` / `ctx.state_set()`（スコープは `conversation`、`actor`、`subject`、`runner`）または Host が提供するその他のストレージに置き、インスタンス属性は使わないでください。
- ハンドラーが戻った後、バックグラウンドタスクで `ctx` を使い続けたり、`self.plugin` 経由の実行関連呼び出しを使い続けたりしないでください。
- 設計上どうしてもプロセス内の呼び出しをまたぐ状態（長期間常駐する外部セッションプロセスなど）に依存する場合、**`stateless-v1` を宣言しないでください**。専用 Worker のままにします。

コンテキスト API の全体は[実行コンテキスト（RunnerContext）](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md)を参照してください。

## 自己チェックと提出

提出前に 1 つずつ確認してください。

- [ ] `manifest.yaml` に 2 つのフィールドが正しい値で宣言されている。
- [ ] リポジトリ全体を検索し、モジュールレベルの可変グローバルが存在しないことを確認した。
- [ ] `initialize()` はプロセス単位の初期化のみを行い、インストール設定を読み取っていない。
- [ ] すべてのインストール設定を呼び出し時に読み取っている。
- [ ] ハンドラーが戻った後に動作し続けるタスクやスレッドがない。
- [ ] 呼び出しをまたぐ状態は Host API 経由で保存している（Runner は `ctx.state_*`）。

### 提出方法

認証は公開と同じ経路で、追加の手続きはありません。`manifest.yaml` に上記 2 つのフィールドを宣言し、いつもどおり `lbp publish` で**新しいバージョン**を提出します（公開済みのバージョンに後から宣言を追加することはできません）。LangBot Space は提出された正確なパッケージを確認し、補助的なコードレビューを行い、人による承認後に認証プラグインの表示を発行します。認証は審査済みのバージョンとチェックサムに紐付きます。

要件を満たせないと判断された場合は、まず署名なしの通常のプラグインとして公開し、後続の不変バージョンで修正してください。

このチェックで共有実行に不向きだと分かった場合は、通常のプラグインとして提出してください。認証は必須ではありません。公開の流れは[マーケットプレイスへの公開](https://langbot.app/docs/ja/plugin/dev/publish/market.md)を参照してください。

---

# システム互換性

Source: https://langbot.app/docs/ja/plugin/compatibility

LangBotのプラグインシステムは、`Asyncio`や`Subprocess`などのメカニズムを利用しています。これらはUnix系システム(LinuxやmacOSなど)では正常に動作しますが、Windowsではいくつかの問題があり、プラグインが正常に動作しない場合があります。

PythonのWindowsでの非同期イベントループはデフォルトで`ProactorEventLoop`を使用しますが、このイベントループはStdioのサポートが不足しています。一方、LangBotは非Docker環境においてStdioを使用してPlugin Runtimeと通信し、Plugin Runtimeもプラグインとの通信にStdioを使用します。

`SelectorEventLoop`に切り替えた場合、`SelectorEventLoop`は`Subprocess`をサポートしていないため、Plugin Runtimeとプラグインが正常に起動できなくなります。

これらの問題の詳細については、次を参照してください: [Python公式ドキュメント](https://docs.python.org/3.13/library/asyncio-platforms.html)

## 解決策

Unix系システムにおけるサブプロセス管理とStdio通信の密結合とは異なり、LangBotとPlugin RuntimeはWindows上で自動的にハイブリッドなサブプロセス + WebSocket通信戦略に切り替わります。LangBotは引き続きサブプロセスを介してPlugin Runtimeを起動しますが、WebSocketで通信します。同様に、Plugin Runtimeは各インストール済みプラグインをサブプロセスで起動しながら、WebSocketを通じて通信します。

この動作はOSに基づいて自動的に選択されるため、手動での設定は不要です。

---

# コンテキスト API

Source: https://langbot.app/docs/ja/plugin/dev/apis/agent-run

コンテキストには、1 回のコンポーネント呼び出しに関するデータが含まれます。コンポーネントごとに受け取るコンテキストが異なるため、まず対象コンポーネントの入口を確認してください。

| コンポーネント            | ハンドラーの入口                              | コンテキスト型                               |
| ------------------ | ------------------------------------- | ------------------------------------- |
| EventListener      | `handler(event_context)`              | `EventContext`                        |
| Command            | `subcommand(context)`                 | `ExecuteContext`                      |
| Tool               | `call(params, session, query_id)`     | 独立したコンテキストオブジェクトなし                    |
| Runner             | `run(ctx)` または `handler(ctx)`         | `RunnerContext`                       |
| KnowledgeEngine    | `ingest(context)`、`retrieve(context)` | `IngestionContext`、`RetrievalContext` |
| KnowledgeRetriever | `retrieve(context)`                   | `RetrievalContext`                    |
| Parser             | `parse(context)`                      | `ParseContext`                        |
| Page               | `handle_api(request)`                 | `PageRequest`                         |

このページでは、コンテキストのデータとメソッドのみを説明します。モデル、ナレッジベース、ストレージなどの LangBot 機能には `self.plugin` を使用します。詳細は [LangBot API](https://langbot.app/docs/ja/plugin/dev/apis/common.md) を参照してください。プラットフォーム操作は[プラットフォーム API](https://langbot.app/docs/ja/plugin/dev/apis/platform.md)に記載しています。

`EventContext`、`ExecuteContext`、`Session` には `instance_uuid`、`workspace_uuid`、`placement_generation` も含まれます。これらは現在の実行に対応するインスタンスとワークスペースを示すためのもので、プラグイン側の認可情報として使用しないでください。

## EventListener

EventListener はパイプラインイベントを処理します。イベントハンドラーは `EventContext` を受け取ります。

```python
event = event_context.event
sender_id = event.sender_id
```

### コンテキストデータ

| プロパティ                  | 型                | 説明                                              |
| ---------------------- | ---------------- | ----------------------------------------------- |
| `event`                | `BaseEventModel` | 現在のイベントオブジェクト。実際の型は登録したイベント型と一致します              |
| `event_name`           | `str`            | 現在のイベントクラス名                                     |
| `query_id`             | `int`            | 現在のパイプラインリクエスト ID                               |
| `query_uuid`           | `str \| None`    | 現在のパイプラインリクエストの安定した識別子                          |
| `eid`                  | `int`            | Plugin Runtime 内の一時的なイベント番号。永続化しないでください         |
| `is_prevent_default`   | `bool`           | デフォルト処理を停止済みか。変更には `prevent_default()` を使用します   |
| `is_prevent_postorder` | `bool`           | 後続プラグインを停止済みか。変更には `prevent_postorder()` を使用します |

イベントのフィールドと購読可能なイベントは[パイプラインイベント](https://langbot.app/docs/ja/plugin/dev/apis/pipeline-events.md)を参照してください。

### コンテキストメソッド

| メソッド                                                                               | 戻り値                    | 説明                                      |
| ---------------------------------------------------------------------------------- | ---------------------- | --------------------------------------- |
| `await event_context.reply(message_chain, quote_origin=False)`                     | -                      | 現在のリクエストの会話に返信                          |
| `await event_context.get_bot_uuid()`                                               | `str`                  | 送信元 Bot の UUID を取得                      |
| `await event_context.set_query_var(key, value)`                                    | -                      | 現在のリクエストに変数を設定                          |
| `await event_context.get_query_var(key)`                                           | `Any`                  | リクエスト変数を 1 つ取得                          |
| `await event_context.get_query_vars()`                                             | `dict[str, Any]`       | すべてのリクエスト変数を取得                          |
| `await event_context.create_new_conversation()`                                    | `dict[str, Any]`       | 現在のパイプライン会話をクリアし、後続リクエストで新しい会話を作成       |
| `await event_context.list_pipeline_knowledge_bases()`                              | `list[dict[str, Any]]` | 現在のパイプラインの Local Agent に設定されたナレッジベースを取得 |
| `await event_context.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)` | `list[dict[str, Any]]` | 現在のパイプラインに設定されたナレッジベースを検索               |
| `event_context.prevent_default()`                                                  | -                      | 現在のイベントのデフォルト処理を停止                      |
| `event_context.prevent_postorder()`                                                | -                      | 後続プラグインによる現在のイベント処理を停止                  |

`reply()` は [MessageChain](https://langbot.app/docs/ja/plugin/dev/apis/messages.md) を受け取ります。リクエスト変数、返信、パイプラインのナレッジベース API には、関連付けられたパイプラインリクエストが必要です。`retrieve_knowledge()` の `kb_id` は `list_pipeline_knowledge_bases()` の結果から指定します。

`prevent_default()` はデフォルトフローを停止できるイベントにのみ作用します。詳細は[パイプラインイベント](https://langbot.app/docs/ja/plugin/dev/apis/pipeline-events.md#デフォルト動作を阻止)を参照してください。

## Command

Command のサブコマンドハンドラーは `ExecuteContext` を受け取ります。

```python
query = " ".join(context.crt_params)
session = context.session
```

### コンテキストデータ

| プロパティ               | 型             | 説明                     |
| ------------------- | ------------- | ---------------------- |
| `session`           | `Session`     | 現在のメッセージが属するセッション      |
| `command_text`      | `str`         | コマンド接頭辞を除いた完全なコマンド文字列  |
| `full_command_text` | `str`         | 接頭辞を含む完全なコマンド文字列       |
| `command`           | `str`         | ルートコマンド名               |
| `crt_command`       | `str`         | 現在実行中のサブコマンド名          |
| `params`            | `list[str]`   | ルートコマンド以降のすべての引数       |
| `crt_params`        | `list[str]`   | 現在のサブコマンドで未処理の引数       |
| `privilege`         | `int`         | 現在のユーザーのコマンド権限レベル      |
| `query_id`          | `int`         | 現在のパイプラインリクエスト ID      |
| `query_uuid`        | `str \| None` | 現在のパイプラインリクエストの安定した識別子 |

SDK は現在のサブコマンドに入る前に `context.shift()` を呼び出します。コンポーネントから直接呼び出す必要はありません。

### コンテキストメソッド

| メソッド                                                                         | 戻り値                    | 説明                                      |
| ---------------------------------------------------------------------------- | ---------------------- | --------------------------------------- |
| `await context.reply(message_chain, quote_origin=False)`                     | -                      | 現在のリクエストの会話に返信                          |
| `await context.get_bot_uuid()`                                               | `str`                  | 送信元 Bot の UUID を取得                      |
| `await context.set_query_var(key, value)`                                    | -                      | 現在のリクエストに変数を設定                          |
| `await context.get_query_var(key)`                                           | `Any`                  | リクエスト変数を 1 つ取得                          |
| `await context.get_query_vars()`                                             | `dict[str, Any]`       | すべてのリクエスト変数を取得                          |
| `await context.create_new_conversation()`                                    | `dict[str, Any]`       | 現在のパイプライン会話をクリアし、後続リクエストで新しい会話を作成       |
| `await context.list_pipeline_knowledge_bases()`                              | `list[dict[str, Any]]` | 現在のパイプラインの Local Agent に設定されたナレッジベースを取得 |
| `await context.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)` | `list[dict[str, Any]]` | 現在のパイプラインに設定されたナレッジベースを検索               |

これらのリクエストメソッドは EventListener と同じ動作です。登録方法と戻り値は [Command コンポーネント](https://langbot.app/docs/ja/plugin/dev/components/command.md)を参照してください。

## Tool

Tool には独立したコンテキストオブジェクトがありません。`call()` の引数として呼び出し情報を受け取ります。

```python
conversation_type = session.launcher_type.value
conversation_id = session.launcher_id
sender_id = session.sender_id
```

| 引数         | 説明                                                      |
| ---------- | ------------------------------------------------------- |
| `params`   | ツールの JSON Schema に基づいてモデルまたは呼び出し元が生成した引数                |
| `session`  | 現在のセッションデータ                                             |
| `query_id` | 現在のパイプラインリクエスト ID。リクエストコンテキストが必要な LangBot API にそのまま渡します |

`Session` の主なプロパティは次のとおりです。

| プロパティ                       | 説明                        |
| --------------------------- | ------------------------- |
| `launcher_type`             | 会話種別：`person` または `group` |
| `launcher_id`               | 個人チャットのユーザー ID またはグループ ID |
| `sender_id`                 | 現在のメッセージ送信者 ID            |
| `bot_uuid`                  | 現在の Bot UUID              |
| `using_conversation`        | 現在のパイプライン会話               |
| `conversations`             | この Session に保存されたパイプライン会話 |
| `use_prompt_name`           | 使用中のプロンプト名                |
| `create_time`、`update_time` | Session の作成時刻と更新時刻        |

`session` はデータオブジェクトであり、`reply()` などのコンテキストメソッドはありません。ツールの戻り値は呼び出し元へ返され、チャットプラットフォームには自動送信されません。LangBot とプラットフォームの機能には `self.plugin` を使用します。API が `session` と `query_id` を要求する場合は、現在の呼び出しで受け取った値を渡してください。

## Runner

独自の `run(ctx)` と Runner のイベントハンドラーは、どちらも `RunnerContext` を受け取ります。このコンテキストは現在の実行中だけ有効です。

```python
text = ctx.input.to_text()
event_type = ctx.event.event_type
```

### コンテキストデータ

| プロパティ            | 型                             | 説明                                    |
| ---------------- | ----------------------------- | ------------------------------------- |
| `run_id`         | `str`                         | 現在の実行 ID                              |
| `trigger`        | `AgentTrigger`                | トリガーの種類、発生元、時刻                        |
| `event`          | `AgentEventContext`           | イベント ID、種類、発生元、時刻、元データを含む標準イベントエンベロープ |
| `platform_event` | プラットフォームイベント型                 | イベント型に応じて解析されたプラットフォームイベント            |
| `conversation`   | `ConversationContext \| None` | 現在の会話、スレッド、Bot、ワークスペースの識別子            |
| `actor`          | `ActorContext \| None`        | イベントを発生させた主体                          |
| `subject`        | `SubjectContext \| None`      | イベントの対象となるメッセージやグループなど                |
| `input`          | `AgentInput`                  | 現在のテキスト、構造化コンテンツ、添付ファイル               |
| `delivery`       | `DeliveryContext`             | 出力先とストリーミング、編集、リアクションの対応状況            |
| `resources`      | `AgentResources`              | 今回の実行で許可されたモデル、ツール、ナレッジベース、スキル、ストレージ  |
| `context`        | `ContextAccess`               | 会話カーソル、インライン方針、利用可能なコンテキスト API        |
| `state`          | `AgentRunState`               | 実行開始時に読み込まれたスコープ別状態のスナップショット          |
| `runtime`        | `AgentRuntimeContext`         | LangBot バージョン、トレース ID、期限              |
| `config`         | `dict[str, Any]`              | 現在の Agent またはプラグインプロセッサーの設定           |
| `adapter`        | `AdapterContext \| None`      | エントリーアダプターの追加データ                      |
| `variables`      | `dict[str, Any]`              | Runner テンプレートで使える公開リクエスト変数            |
| `metadata`       | `dict[str, Any]`              | ホストが提供するその他のメタデータ                     |

上表の安定したプロパティを優先してください。`event.data` と `adapter.extra` には、安定したフィールドに含まれない追加データが入ります。

### 返信とログ

| メソッド                                                 | 戻り値             | 説明                                               |
| ---------------------------------------------------- | --------------- | ------------------------------------------------ |
| `await ctx.get_bot_uuid()`                           | `str`           | 送信元 Bot UUID を取得。関連する Bot がなければエラー               |
| `await ctx.reply(message_chain, quote_origin=False)` | `Any`           | 文字列または `MessageChain` で現在のイベントに返信                |
| `ctx.reply_stream()`                                 | 非同期コンテキストマネージャー | 1 件の返信を完全なテキストで逐次更新                              |
| `await ctx.log(text, level="info")`                  | -               | 今回の実行ログへ記録。レベルは `debug`、`info`、`warning`、`error` |

`reply_stream().update(text)` には、その時点の完全なテキストを渡します。プラットフォームがストリーミングに対応しない場合、終了時に完全なメッセージを 1 件送信します。デバッグモードでは送信をシミュレートします。

### 利用可能なツール

| メソッド                                              | 戻り値                    | 説明                                               |
| ------------------------------------------------- | ---------------------- | ------------------------------------------------ |
| `await ctx.get_available_tools()`                 | `list[dict[str, Any]]` | 今回呼び出せるコンテキスト操作、プラットフォーム API、プラグインツール、MCP ツールを取得 |
| `await ctx.call_tool(tool_name, parameters=None)` | `dict[str, Any]`       | 上記一覧のツールを呼び出す                                    |

`get_available_tools()` の各項目には `name`、`description`、`parameters`、`type`、`operations` が含まれます。結果は現在の Agent またはプラグインプロセッサーの設定とイベント機能で絞り込まれています。一覧にないツールは `ctx.call_tool()` で呼び出せません。

### Box と添付ファイル

Box の有効化、取得、再利用方針は Runner が決めます。リソースの取得には [LangBot API](https://langbot.app/docs/ja/plugin/dev/apis/common.md#box-サンドボックス)、実行中の操作には以下を使います。

| メソッド                                                    | 戻り値             | 説明                                                 |
| ------------------------------------------------------- | --------------- | -------------------------------------------------- |
| `await ctx.bind_box(box_id)`                            | `BoxBinding`    | Box を現在の実行にバインドし、`box_id`、`outbox` を返す。同じ実行内では変更不可 |
| `await ctx.import_box_attachments(attachment_ids=None)` | `list[BoxFile]` | 入力の `ref` を指定してインポート。省略時は全件。サンドボックスの `path` を返す    |
| `await ctx.export_box_files()`                          | `list[BoxFile]` | 現在の実行の outbox をファイルハンドルとしてエクスポート。メッセージは送信しない       |
| `await ctx.reply_files(file_ids)`                       | `Any`           | エクスポートした ID で返信。返信ツールの権限制限が適用される                   |

`BoxFile` は `id`、`name`、`type`、`size`、任意の `path` を含みます。入力の元 URL と内容は保持され、明示的にインポートして初めてファイルパスが生成されます。ハンドルは今回の実行でのみ有効で、重複送信できません。

ネイティブツールやファイル操作の前に Box をバインドします。Box を共有しても添付ディレクトリは実行ごとに分かれます。`ctx.variables` の公開リクエスト変数で再利用キーを計算できます。

Pipeline では `ctx.delivery.automatic_reply` が `True` になり、`RunnerResult.message_completed(ctx.run_id, message, file_ids=[...])` で添付を返せます。Agent とプラグインプロセッサーは `ctx.reply_files()` で明示的に送信します。

外部ランナーも `AgentRunExternalTools` で同じ手順を使用できます：`langbot_get_box_status`、`langbot_list_boxes`、`langbot_acquire_box`、`langbot_bind_box`、`langbot_import_box_attachments`、`langbot_export_box_files`。イベントへの返信権限がある場合は `langbot_reply_files` も利用できます。すべての呼び出しに現在の実行の権限が適用されます。

### プロンプト、履歴、イベント

| メソッド                                                                                                                                             | 戻り値                    | 利用可否フィールド        |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ---------------- |
| `await ctx.get_prompt()`                                                                                                                         | `list[dict[str, Any]]` | `prompt_get`     |
| `await ctx.history_page(conversation_id=None, before_cursor=None, after_cursor=None, limit=50, direction="backward", include_attachments=False)` | `HistoryPage`          | `history_page`   |
| `await ctx.history_search(query, filters=None, top_k=10)`                                                                                        | `HistorySearchResult`  | `history_search` |
| `await ctx.event_get(event_id)`                                                                                                                  | `AgentEventRecord`     | `event_get`      |
| `await ctx.event_page(conversation_id=None, event_types=None, before_cursor=None, limit=50)`                                                     | `EventPage`            | `event_page`     |
| `await ctx.steering_pull(mode="all", limit=None)`                                                                                                | `SteeringPullResult`   | `steering_pull`  |

### 状態

| メソッド                                                  | 戻り値              | 説明                   |
| ----------------------------------------------------- | ---------------- | -------------------- |
| `await ctx.state_get(scope, key)`                     | `dict[str, Any]` | 状態値を取得               |
| `await ctx.state_set(scope, key, value)`              | `dict[str, Any]` | JSON シリアライズ可能な状態値を保存 |
| `await ctx.state_delete(scope, key)`                  | `dict[str, Any]` | 状態値を削除               |
| `await ctx.state_list(scope, prefix=None, limit=100)` | `dict[str, Any]` | 指定スコープの状態キーを一覧表示     |

`scope` は `conversation`、`actor`、`subject`、`runner` のいずれかです。これらのメソッドには `ctx.context.available_apis.state` が `true` である必要があります。

### 実行記録

| メソッド                                                                                                           | 戻り値             | 利用可否フィールド           |
| -------------------------------------------------------------------------------------------------------------- | --------------- | ------------------- |
| `await ctx.run_get(run_id=None)`                                                                               | `AgentRun`      | `run_get`           |
| `await ctx.run_list(conversation_id=None, statuses=None, before_cursor=None, limit=50)`                        | `RunPage`       | `run_list`          |
| `await ctx.run_events_page(run_id=None, before_cursor=None, after_cursor=None, limit=50, direction="forward")` | `RunEventPage`  | `run_events_page`   |
| `await ctx.run_cancel(run_id=None, reason=None)`                                                               | `AgentRun`      | `run_cancel`        |
| `await ctx.run_append_result(result)`                                                                          | `AgentRunEvent` | `run_append_result` |
| `await ctx.run_finalize(run_id=None, status=None, reason=None)`                                                | `AgentRun`      | `run_finalize`      |

`run_id=None` は現在の実行を指します。通常のイベントハンドラーは SDK が自動的に完了します。独自の `run(ctx)` が `RunnerResult` を yield する場合、同じ結果を `run_append_result()` で重複登録しないでください。

### 利用可否と権限

プロンプト、履歴、イベント、状態、実行記録の API が利用可能かどうかは `ctx.context.available_apis` で確認します。許可されたモデル、ツール、ナレッジベースはそれぞれ `ctx.resources.models`、`ctx.resources.tools`、`ctx.resources.knowledge_bases` にあります。

Runner の実行中に `self.plugin` から呼び出すモデル、ツール、ナレッジベース、ストレージ、プラットフォーム API は、自動的に現在の実行へ関連付けられ、`ctx.resources` に基づいて再検証されます。`run_id` を渡す必要はありません。ハンドラー終了後にバックグラウンドタスクからこのコンテキストや実行に紐づく呼び出しを使用しないでください。

`ctx.api` は低レベルの実行スコーププロキシです。通常のコンポーネントコードでは、このページに記載した `ctx` メソッドと、LangBot API 用の `self.plugin` を使用してください。

## データ専用コンテキスト

以下のコンポーネントが受け取るものはタスク入力であり、EventListener や Runner の実行コンテキストメソッドはありません。フィールド、戻り値、完全な例は各コンポーネントガイドに記載しています。

| コンポーネントの入口                                               | 主なデータ                       | コンポーネントガイド                                                                                              |
| -------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `KnowledgeEngine.ingest(context: IngestionContext)`      | ファイル、対象ナレッジベース、作成設定、解析結果    | [KnowledgeEngine](https://langbot.app/docs/ja/plugin/dev/components/knowledge-engine.md#ドキュメント取り込み)     |
| `KnowledgeEngine.retrieve(context: RetrievalContext)`    | クエリ、対象ナレッジベース、検索設定、フィルター    | [KnowledgeEngine](https://langbot.app/docs/ja/plugin/dev/components/knowledge-engine.md#ナレッジ検索)         |
| `KnowledgeRetriever.retrieve(context: RetrievalContext)` | クエリと外部ナレッジベース設定             | [KnowledgeRetriever](https://langbot.app/docs/ja/plugin/dev/components/knowledge-retriever.md#検索コンテキスト) |
| `Parser.parse(context: ParseContext)`                    | ファイル内容、ファイル名、MIME タイプ、メタデータ | [Parser](https://langbot.app/docs/ja/plugin/dev/components/parser.md#解析メソッド)                            |
| `Page.handle_api(request: PageRequest)`                  | エンドポイント、HTTP メソッド、本文、ヘッダー   | [Page](https://langbot.app/docs/ja/plugin/dev/components/page.md#pagerequest-フィールド)                     |

---

# LangBot API

Source: https://langbot.app/docs/ja/plugin/dev/apis/common

モデル、ツール、ナレッジベース、ストレージには `self.plugin` を使用します。現在のイベント、返信、会話の状態については[コンテキスト API](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md) を参照してください。

## LangBot API

これらのAPIは、通常のプラグインコンポーネントで呼び出すことができます。アクセス方法:

- プラグインルートディレクトリの`main.py`内: `self`オブジェクトの内部メソッド。これらのAPIはすべて、プラグインクラスの親クラス`BasePlugin`によって提供されます。
- 通常のプラグインコンポーネントクラス内: `self.plugin`オブジェクトの内部メソッド。

### プラグイン設定の取得

プラグイン設定フォーマットは`manifest.yaml`に記述でき、ユーザーはLangBotのプラグイン管理でプラグイン設定フォーマットに従って入力する必要があります。プラグインコードはこのAPIを呼び出してプラグイン設定情報を取得できます。

```python
def get_config(self) -> dict[str, typing.Any]:
    """プラグインの設定を取得する。"""

# 使用例
config = self.plugin.get_config()
```

### LangBotバージョンの取得

LangBotのバージョン番号を取得します。`v<major>.<minor>.<patch>`形式の文字列として返されます。

```python
async def get_langbot_version(self) -> str:
    """LangBotバージョンを取得する"""

# 使用例
langbot_version = await self.plugin.get_langbot_version()
```

### 設定済みBotリストの取得

すべてのBot UUIDのリストを返します。

```python
async def get_bots(self) -> list[str]:
    """すべてのBotを取得する"""

# 使用例
bots = await self.plugin.get_bots()
```

### Bot情報の取得

Bot情報を取得します。

```python
async def get_bot_info(self, bot_uuid: str) -> dict[str, Any]:
    """Bot情報を取得する"""

# 使用例
bot_info = await self.plugin.get_bot_info("de639861-be05-4018-859b-c2e2d3e0d603")

# 返り値の例
{
    "uuid": "de639861-be05-4018-859b-c2e2d3e0d603",
    "name": "aiocqhttp",
    "description": "Migrated from LangBot v3",
    "adapter": "aiocqhttp",
    "enable": true,
    "use_pipeline_name": "ChatPipeline",
    "use_pipeline_uuid": "c30a1dca-e91c-452b-83ec-84d635a30028",
    "created_at": "2025-05-10T13:53:08",
    "updated_at": "2025-08-12T11:27:30",
    "adapter_runtime_values": {  # Botが現在実行中の場合に存在
        "bot_account_id": 960164003  # BotアカウントID
    }
}
```

### プロアクティブメッセージの送信

Bot UUIDとターゲットセッションIDを通じてプロアクティブメッセージを送信します。

メッセージチェーンの構築方法については、[メッセージプラットフォームエンティティ](https://langbot.app/docs/en/plugin/dev/apis/messages.md)を参照してください。

```python
async def send_message(
    self,
    bot_uuid: str,
    target_type: str,
    target_id: str,
    message_chain: platform_message.MessageChain,
) -> None:
    """セッションにメッセージを送信する"""

# 使用例
await self.plugin.send_message(
    bot_uuid="de639861-be05-4018-859b-c2e2d3e0d603",
    target_type="person",
    target_id="1010553892",
    message_chain=platform_message.MessageChain([platform_message.Plain(text="Hello, world!")]),
)
```

### 設定済みLLMモデルリストの取得

設定されたすべてのLLMモデルのUUIDのリストを返します。

```python
async def get_llm_models(self) -> list[str]:
    """すべてのLLMモデルを取得する"""

# 使用例
llm_models = await self.plugin.get_llm_models()
```

### LLMモデルの呼び出し

LLMモデルを呼び出し、LLMメッセージを返します。非ストリーミング。

```python
async def invoke_llm(
    self,
    llm_model_uuid: str,
    messages: list[provider_message.Message],
    funcs: list[resource_tool.LLMTool] = [],
    extra_args: dict[str, Any] = {},
    timeout: float | None = None,
) -> provider_message.Message:
    """LLMモデルを呼び出す"""

# 使用例
llm_message = await self.plugin.invoke_llm(
    llm_model_uuid="llm_model_uuid",
    messages=[provider_message.Message(role="user", content="Hello, world!")],
    funcs=[],
    extra_args={},
)
```

### モデルのストリーミングと使用量

| メソッド                                                                                     | 戻り値                         |
| ---------------------------------------------------------------------------------------- | --------------------------- |
| `invoke_llm_with_usage(llm_model_uuid, messages, funcs=[], extra_args={}, timeout=None)` | `LLMInvokeResult`           |
| `invoke_llm_stream(llm_model_uuid, messages, funcs=[], extra_args={})`                   | `MessageChunk` の非同期イテレーター   |
| `invoke_llm_stream_events(llm_model_uuid, messages, funcs=[], extra_args={})`            | `LLMStreamEvent` の非同期イテレーター |

引数は `invoke_llm` と同じです。`timeout` は秒数で、非ストリーミング呼び出しの既定値は 120 秒です。トークン使用量が必要な場合は `invoke_llm_with_usage` を使用します：

```python
from langbot_plugin.api.entities.builtin.provider.message import Message

result = await self.plugin.invoke_llm_with_usage(
    llm_model_uuid=model_uuid,
    messages=[Message(role="user", content="Hello!")],
)
print(result.message.content)
if result.usage is not None:
    print(result.usage.total_tokens)
```

`usage` は `None` の場合があり、`prompt_tokens`、`completion_tokens`、`total_tokens` も欠ける場合があります。未取得は使用量ゼロを意味しません。キャッシュなどの追加フィールドは保持されます。

```python
async for event in self.plugin.invoke_llm_stream_events(
    llm_model_uuid=model_uuid,
    messages=[Message(role="user", content="Hello!")],
):
    if event.chunk is not None:
        print(event.chunk.content)
    if event.usage is not None:
        print(event.usage.model_dump())
```

`LLMStreamEvent` は任意の `chunk` と `usage` を持ち、最後が使用量のみの場合もあります。`invoke_llm_stream` はメッセージ・ツール呼び出しのチャンクのみ返します。`MessageChunk.content` は現在の断片、`all_content` は提供される場合に累積テキストです。累積テキストは置換し、差分だけ追加します。`is_final` のチャンクにもテキストが含まれる場合があります。モデルのストリーミングはプラットフォームに送信しません。送信方法は[実行コンテキスト API](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md)を参照してください。

### 利用可能な Parser の一覧取得

ホスト上で現在利用可能な Parser プラグインを列挙します。MIME タイプで絞り込むこともできます。

```python
async def list_parsers(self, mime_type: str | None = None) -> list[dict[str, Any]]:
    """List available Parser plugins"""

# 使用例
parsers = await self.plugin.list_parsers(mime_type="application/pdf")
# 各要素には plugin_id、plugin_author、plugin_name、name、description、supported_mime_types が含まれます
```

### 利用可能なツール一覧を取得

現在の LangBot インスタンスで利用可能なすべてのツール（プラグインツールおよび MCP ツール）を取得します。

```python
async def list_tools(self) -> list[dict[str, Any]]:
    """利用可能なすべてのツールを取得

    Returns:
        ツールのリスト。各要素に以下が含まれます：
        - name: ツール名
        - label: 表示名（多言語）
        - description: ツールの説明（多言語）
        - icon: ツールアイコン
        - spec: ツール仕様（llm_prompt と parameters を含む）
    """

# 使用例
tools = await self.plugin.list_tools()
for tool in tools:
    print(f"Tool: {tool['name']}")
```

### ツール詳細を取得

特定のツールの詳細情報を取得します。

```python
async def get_tool_detail(self, tool_name: str) -> dict[str, Any]:
    """特定のツールの詳細情報を取得

    Args:
        tool_name: ツール名（metadata.name、例: "get_weather_alerts"）

    Returns:
        ツール詳細 dict（name、label、description、spec を含む）
    """

# 使用例
detail = await self.plugin.get_tool_detail("get_weather_alerts")
print(detail['spec']['parameters'])
```

### ツールを呼び出す

指定されたツールを呼び出します。

```python
async def call_tool(
    self,
    tool_name: str,
    parameters: dict[str, Any],
    session: dict[str, Any],
    query_id: int,
) -> dict[str, Any]:
    """特定のツールを呼び出す

    Args:
        tool_name: ツール名（metadata.name）
        parameters: ツールパラメータ
        session: セッション情報
        query_id: クエリ ID

    Returns:
        ツールの応答 dict
    """

# 使用例
result = await self.plugin.call_tool(
    tool_name="get_weather_alerts",
    parameters={"state": "CA"},
    session={},
    query_id=0,
)
print(result)
```

> idea:
>
> ツール名は `metadata.name`（例: `echo_tool`、`get_weather_alerts`）を使用します。作者やプラグイン名のプレフィックスは不要です。

### プラグイン永続データの設定

プラグインデータを永続的に保存します。このインターフェースを通じて保存されたデータは、このプラグインのみがアクセスできます。値は手動でbytesに変換する必要があります。

```python
async def set_plugin_storage(self, key: str, value: bytes) -> None:
    """プラグインストレージ値を設定する"""

# 使用例
await self.plugin.set_plugin_storage("key", b"value")
```

### プラグイン永続データの取得

```python
async def get_plugin_storage(self, key: str) -> bytes:
    """プラグインストレージ値を取得する"""

# 使用例
plugin_storage = await self.plugin.get_plugin_storage("key")
```

### すべてのプラグイン永続データキーの取得

```python
async def get_plugin_storage_keys(self) -> list[str]:
    """すべてのプラグインストレージキーを取得する"""

# 使用例
plugin_storage_keys = await self.plugin.get_plugin_storage_keys()
```

### プラグイン永続データの削除

```python
async def delete_plugin_storage(self, key: str) -> None:
    """プラグインストレージ値を削除する"""

# 使用例
await self.plugin.delete_plugin_storage("key")
```

### ワークスペース永続データの取得

このインターフェースを通じて保存されたデータは、すべてのプラグインがアクセスできます。値は手動でbytesに変換する必要があります。

```python
async def set_workspace_storage(self, key: str, value: bytes) -> None:
    """ワークスペースストレージ値を設定する"""

# 使用例
await self.plugin.set_workspace_storage("key", b"value")
```

### ワークスペース永続データの取得

```python
async def get_workspace_storage(self, key: str) -> bytes:
    """ワークスペースストレージ値を取得する"""

# 使用例
workspace_storage = await self.plugin.get_workspace_storage("key")
```

### すべてのワークスペース永続データキーの取得

```python
async def get_workspace_storage_keys(self) -> list[str]:
    """すべてのワークスペースストレージキーを取得する"""

# 使用例
workspace_storage_keys = await self.plugin.get_workspace_storage_keys()
```

### ワークスペース永続データの削除

```python
async def delete_workspace_storage(self, key: str) -> None:
    """ワークスペースストレージ値を削除する"""

# 使用例
await self.plugin.delete_workspace_storage("key")
```

### プラグインファイル型設定フィールドデータの取得

```python
async def get_config_file(self, file_key: str) -> bytes:
    """設定ファイル値を取得する"""

# 使用例
file_bytes = await self.plugin.get_config_file("key")
```

これは[`fileまたはarray[file`](https://langbot.app/docs/en/plugin/dev/basic-info.md#type-file)型の設定フィールドと組み合わせて使用します。

## ナレッジベース API

これらのAPIは通常のコンポーネントから`self.plugin`経由でアクセスでき、パイプライン制限なしにLangBotインスタンス内のすべてのナレッジベースの一覧取得と検索が可能です。

### すべてのナレッジベースの一覧取得

LangBotインスタンスで利用可能なすべてのナレッジベースを一覧取得します。

```python
async def list_knowledge_bases(self) -> list[dict[str, Any]]:
    """すべてのナレッジベースを一覧取得

    Returns:
        ナレッジベースのリスト、各要素は以下を含む：
        - uuid: ナレッジベースUUID
        - name: ナレッジベース名
        - description: ナレッジベースの説明
    """

# 使用例
knowledge_bases = await self.plugin.list_knowledge_bases()
for kb in knowledge_bases:
    print(f"KB: {kb['name']} ({kb['uuid']})")
```

### ナレッジベースからの検索

任意のナレッジベースから関連ドキュメントを検索します。

```python
async def retrieve_knowledge(
    self,
    kb_id: str,
    query_text: str,
    top_k: int = 5,
    filters: dict[str, Any] | None = None,
) -> list[dict[str, Any]]:
    """ナレッジベースから検索

    Args:
        kb_id: ナレッジベースUUID（list_knowledge_basesから取得）
        query_text: 検索クエリテキスト
        top_k: 返す結果の数（デフォルト：5）
        filters: オプションのメタデータフィルター

    Returns:
        検索結果エントリのリスト
    """

# 使用例
results = await self.plugin.retrieve_knowledge(
    kb_id="kb-uuid-here",
    query_text="システムの設定方法は？",
    top_k=3,
)
for entry in results:
    print(entry)
```

> idea:
>
> これらのAPIは`query_id`を必要とせず、通常のコンポーネント（Toolコンポーネントを含む）で使用できます。現在のパイプライン設定に制限されることなく、すべてのナレッジベースにアクセスできます。

## RAG API

これらのAPIは`KnowledgeEngine`コンポーネントがLangBotホストの埋め込みモデル、ベクトルデータベース、ファイルストレージにアクセスするために使用できます。アクセス方法:

- `KnowledgeEngine`コンポーネントクラス内: `self.plugin`オブジェクトの内部メソッド。

### 埋め込みモデルの呼び出し

ホストに設定された埋め込みモデルを使用してテキストのベクトルを生成します。

```python
async def invoke_embedding(
    self,
    embedding_model_uuid: str,
    texts: list[str],
) -> list[list[float]]:
    """埋め込みモデルを使用してベクトルを生成

    Args:
        embedding_model_uuid: 埋め込みモデルUUID
        texts: 埋め込むテキストのリスト

    Returns:
        ベクトルのリスト、入力テキストごとに1つ
    """

# 使用例
vectors = await self.plugin.invoke_embedding("model_uuid", ["Hello", "World"])
```

### ベクトルの書き込み

ホストのベクトルデータベースにベクトルを書き込みます。

```python
async def vector_upsert(
    self,
    collection_id: str,
    vectors: list[list[float]],
    ids: list[str],
    metadata: list[dict[str, Any]] | None = None,
    documents: list[str] | None = None,
) -> None:
    """ベクトルの書き込み

    Args:
        collection_id: ターゲットコレクションID
        vectors: ベクトルのリスト
        ids: ベクトルの一意識別子リスト
        metadata: オプションのメタデータリスト
        documents: オプションの生テキストドキュメントリスト。全文検索や
            混合検索をサポートするバックエンドで必要です。
    """

# 使用例
await self.plugin.vector_upsert(
    collection_id="kb_uuid",
    vectors=[[0.1, 0.2, ...], [0.3, 0.4, ...]],
    ids=["chunk_0", "chunk_1"],
    metadata=[{"document_id": "doc1"}, {"document_id": "doc1"}],
    documents=["チャンクテキスト 0", "チャンクテキスト 1"],
)
```

### ベクトル検索

ホストのベクトルデータベースで類似ベクトルを検索します。

```python
async def vector_search(
    self,
    collection_id: str,
    query_vector: list[float],
    top_k: int = 5,
    filters: dict[str, Any] | None = None,
    search_type: str = "vector",
    query_text: str = "",
) -> list[dict[str, Any]]:
    """ベクトル検索

    Args:
        collection_id: ターゲットコレクションID
        query_vector: 類似性検索のクエリベクトル
        top_k: 返す結果の数
        filters: オプションのメタデータフィルター
        search_type: 検索方式、'vector'、'full_text'、'hybrid' のいずれか
        query_text: 生のクエリテキスト、全文検索と混合検索で使用

    Returns:
        検索結果のリスト（id, score, metadataなどを含むdict）
    """

# 使用例
results = await self.plugin.vector_search(
    collection_id="kb_uuid",
    query_vector=[0.1, 0.2, ...],
    top_k=5,
    search_type="hybrid",
    query_text="検索クエリ",
)
# 返却フォーマット: [{"id": "chunk_0", "score": 0.123, "metadata": {"document_id": "doc1", ...}}, ...]
```

> info:
>
> `vector_search`が返す各結果はdictで、`id`（ベクトルID）、`score`（距離スコア）、`metadata`（upsert時に提供したメタデータ）の3つのフィールドを含みます。検索結果にテキスト内容が必要な場合は、取り込み時にmetadataにテキストを保存してください。

### ベクトルの削除

ホストのベクトルデータベースからベクトルを削除します。

```python
async def vector_delete(
    self,
    collection_id: str,
    file_ids: list[str] | None = None,
    filters: dict[str, Any] | None = None,
) -> int:
    """ベクトルの削除

    Args:
        collection_id: ターゲットコレクションID
        file_ids: 削除するファイルIDのリスト
        filters: オプションのメタデータフィルター

    Returns:
        削除されたアイテム数
    """

# 使用例
deleted = await self.plugin.vector_delete(
    collection_id="kb_uuid",
    file_ids=["doc_001"],
)
```

> info:
>
> `filters`パラメータはChromaスタイルの`where`構文によるメタデータフィルタリングをサポートしています。複数のトップレベルキーはAND条件として結合されます。サポートされる演算子：`$eq`、`$ne`、`$gt`、`$gte`、`$lt`、`$lte`、`$in`、`$nin`。
>
> ```python
> # 暗黙的な $eq
> results = await self.plugin.vector_search(
>     collection_id="kb_uuid",
>     query_vector=[0.1, 0.2, ...],
>     filters={"file_id": "abc"},
> )
>
> # 比較演算子
> results = await self.plugin.vector_search(
>     collection_id="kb_uuid",
>     query_vector=[0.1, 0.2, ...],
>     filters={"created_at": {"$gte": 1700000000}},
> )
>
> # リスト演算子
> results = await self.plugin.vector_search(
>     collection_id="kb_uuid",
>     query_vector=[0.1, 0.2, ...],
>     filters={"file_type": {"$in": ["pdf", "docx"]}},
> )
>
> # フィルターによる削除
> deleted = await self.plugin.vector_delete(
>     collection_id="kb_uuid",
>     filters={"file_type": {"$eq": "pdf"}},
> )
> ```
>
> **注意：** Chroma、Qdrant、SeekDBは完全なメタデータを保存し、任意のフィールドでフィルタリングできます。MilvusとpgvectorはDB側に`text`、`file_id`、`chunk_uuid`のみ保存しており、それ以外のフィールドでのフィルタリングは無視されます。

ホストストレージからアップロードされたファイルの内容を取得します。

```python
async def get_knowledge_file_stream(self, storage_path: str) -> bytes:
    """ファイル内容を取得

    Args:
        storage_path: ファイルのストレージパス（FileObject.storage_pathから取得）

    Returns:
        ファイル内容のバイトデータ
    """

# 使用例
file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)
```

## その他のリソース API

以下も `self.plugin` から呼び出します。

### リランクモデルの呼び出し

```python
async def invoke_rerank(
    self, rerank_model_uuid: str, query: str, documents: list[str],
    top_k: int | None = None, extra_args: dict[str, Any] | None = None,
    timeout: float = 60.0,
) -> list[dict[str, Any]]:
    ...

scores = await self.plugin.invoke_rerank(
    rerank_model_uuid=rerank_model_uuid,
    query="How do I configure a bot?",
    documents=["Bot configuration guide", "Plugin publishing guide"],
    top_k=1,
)
```

結果には通常、元の文書の `index` と関連度 `relevance_score` が含まれます。

### パーサーの呼び出し

```python
async def invoke_parser(
    self, plugin_author: str, plugin_name: str, storage_path: str,
    mime_type: str, filename: str, metadata: dict[str, Any] | None = None,
) -> dict[str, Any]:
    ...

parsers = await self.plugin.list_parsers(mime_type="application/pdf")
if parsers:
    parser = parsers[0]
    parsed = await self.plugin.invoke_parser(
        plugin_author=parser["plugin_author"],
        plugin_name=parser["plugin_name"],
        storage_path=storage_path,
        mime_type="application/pdf",
        filename="guide.pdf",
    )
```

`storage_path` はナレッジ取り込み時の `context.file_object.storage_path` など、ホストの保存先です。プラグインのローカルパスではありません。結果の辞書には `text`、`sections`、`metadata` が含まれます。

### ベクトルレコード一覧

```python
async def vector_list(
    self, collection_id: str, filters: dict[str, Any] | None = None,
    limit: int = 20, offset: int = 0,
) -> dict[str, Any]:
    ...

page = await self.plugin.vector_list(
    collection_id=collection_id,
    filters={"file_id": "doc_001"},
    limit=20,
    offset=0,
)
for item in page["items"]:
    print(item["id"], item.get("metadata"))
```

`items` と `total` を返します。各項目は `id`、`document`、`metadata` を含み、`total` はストレージが取得可能な一致件数です。フィルターは上記のベクトル API と同じ形式です。

### プラグインとコマンド一覧

```python
manifests = await self.plugin.list_plugins_manifest()
commands = await self.plugin.list_commands()
```

いずれも引数なしで、ホストが提供するプラグインのマニフェスト一覧とコマンド一覧を返します。

### Box サンドボックス

`self.plugin` から現在のワークスペースに対して呼び出します。Runner 内では実行権限が自動的に引き継がれます。

| メソッド                                                     | 戻り値                | 説明                                                                                                  |
| -------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------- |
| `await self.plugin.get_box_status()`                     | `BoxStatus`        | `enabled`、`available`、上限 `limit`、使用数 `used`、残数 `remaining`、任意の `required_reuse_key`、利用不可理由 `reason` |
| `await self.plugin.list_boxes()`                         | `list[BoxSession]` | `id` と状態 `status`（`idle`、`running`、`closing`）のスナップショット                                              |
| `await self.plugin.acquire_box(reuse_key, options=None)` | `BoxSession`       | 同一キーで再利用、または上限内で作成。`options` は `image` をサポート                                                        |

不明な数量は `None` です。残数がゼロでも既存 Box の再利用は可能です。新規作成時の上限は Runtime が原子的に確認します。キーは Runner が計算しますが、`required_reuse_key` が返された場合はその値を使います。異なるワークスペース間では同じキーでも共有されません。

取得後は[Runner コンテキスト](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md#runner)でバインドしてから、添付のインポートやツール実行を行います。

---

# メッセージプラットフォームエンティティ

Source: https://langbot.app/docs/ja/plugin/dev/apis/messages

LangBotは複数のメッセージングプラットフォームをサポートしており、各プラットフォームには異なる`メッセージエンティティ`フォーマットがあります。これらの違いを抽象化するために、統一された標準を実装しました。プラグイン開発者は、プラグイン内でこのページに記載されているメッセージエンティティを習得して使用するだけで、LangBotの内部メッセージ処理ロジックがメッセージの解析と変換を自動的に処理します。

## メッセージチェーン

メッセージングプラットフォーム上の`メッセージ`は、AI対話に使用されるメッセージとは異なります。メッセージングプラットフォーム上のメッセージは、`メッセージチェーン`の形式で記述されます。QQに表示される各独立したメッセージはメッセージチェーンであり、`テキスト`、`画像`、`@メンション`などのさまざまな`メッセージチェーンコンポーネント`を含むことができます。例えば:

![](https://langbot.app/docs/images/zh/plugin/dev/apis/plugin_dev_messages_01.png)

これは、1つのPlainコンポーネント(Hello World)と1つのImageコンポーネント(Usagi)を含むメッセージチェーンです。

メッセージチェーンとメッセージチェーンコンポーネントの定義は、`langbot_plugin.api.entities.builtin.platform.message`にあります。

### メッセージチェーンの構築

まず、`langbot_plugin.api.entities.builtin.platform.message`パッケージをインポートして、その中のメッセージコンポーネントを使用してください。

```python
from langbot_plugin.api.entities.builtin.platform.message import *

# テキスト「Hello LangBot」と画像(URLから)を含むメッセージを構築
msg_chain = MessageChain([
    Plain(text="Hello LangBot"),
    Image(url='https://qchatgpt.rockchin.top/langbot-logo.png')
])

# @全員とテキスト「Hello LangBot」を含むメッセージを構築
msg_chain = MessageChain([
    AtAll(),
    Plain(text="Hello LangBot")
])

# @特定のメンバーとテキスト「Hello LangBot」を含むメッセージを構築
msg_chain = MessageChain([
    At(target=123456),
    Plain(text="Hello LangBot")
])
```

現在サポートされているメッセージチェーンコンポーネント:

- `Source` - ソースメッセージチェーン情報。メッセージングプラットフォームから受信したメッセージには、メッセージ情報を記録するためにメッセージチェーンの先頭にこのコンポーネントが含まれます
- `Plain` - プレーンテキストメッセージ
- `Quote` - 引用メッセージ
- `Image` - 画像メッセージ
- `AtAll` - @全員メッセージ
- `At` - @特定のメンバーメッセージ
- `Voice` - 音声メッセージ
  - メッセージングプラットフォームのサポートを確認する必要があります
- `Forward` - 転送メッセージ
  - 多くのプラットフォームでサポートされていないため、推奨されません
- `File` - ファイルメッセージ

コンポーネントを作成する際は、名前付きパラメータを使用する必要があります。具体的な使用方法については、ソースコード`langbot_plugin.api.entities.builtin.platform.message`の定義を確認してください。

## その他のエンティティ

上記のエンティティに加えて、`Friend`や`Group`などのエンティティもあります。これらのエンティティは`langbot_plugin.api.entities.builtin.platform.entities`で定義されています。

## プラットフォーム API

ユーザー取得、グループ管理、固有の操作には[プラットフォーム API](https://langbot.app/docs/ja/plugin/dev/apis/platform.md)を使用してください。Runner も同じ `self.plugin` を使用し、現在の会話には `ctx.reply()` で返信します。

---

# パイプラインイベントとAPI

Source: https://langbot.app/docs/ja/plugin/dev/apis/pipeline-events

LangBotプラグインはパイプラインイベントを登録して処理できます。使用方法については、[コンポーネント: イベントリスナー](https://langbot.app/docs/ja/plugin/dev/components/event-listener.md)を参照してください。

## イベント一覧

一部のイベントには`設定可能な属性`があり、プラグインコードで変更して、その後のLangBot処理で使用できます。

### \*MessageReceived

グループチャットまたはプライベートチャットでメッセージを受信したときにトリガーされます。

```python
class PersonMessageReceived(BaseEventModel):
    """プライベートチャットメッセージを受信したとき"""

    event_name: str = "PersonMessageReceived"

    launcher_type: str
    """起動元オブジェクトタイプ(person)"""

    launcher_id: typing.Union[int, str]
    """送信者ID"""

    sender_id: typing.Union[int, str]
    """送信者ID、プライベートチャットの場合はlauncher_idと同じ"""

    message_event: platform_events.PersonMessage
    """元のメッセージイベントオブジェクト。送信者情報を含みます。"""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """メッセージチェーン"""


class GroupMessageReceived(BaseEventModel):
    """グループチャットメッセージを受信したとき"""

    event_name: str = "GroupMessageReceived"

    launcher_type: str
    """起動元オブジェクトタイプ(group)"""

    launcher_id: typing.Union[int, str]
    """グループID"""

    sender_id: typing.Union[int, str]
    """送信者ID"""

    message_event: platform_events.GroupMessage
    """元のメッセージイベントオブジェクト。グループと送信者情報を含みます。"""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """メッセージチェーン"""
```

### \*NormalMessageReceived

グループチャットまたはプライベートチャットメッセージを受信し、LLMで処理する必要があるメッセージ(コマンドでないメッセージ)であると判定されたときにトリガーされます。

```python
class PersonNormalMessageReceived(BaseEventModel):
    """処理すべきプライベートチャット通常メッセージが判定されたときにトリガーされる"""

    event_name: str = "PersonNormalMessageReceived"

    launcher_type: str
    """起動元オブジェクトタイプ(person)"""

    launcher_id: typing.Union[int, str]
    """起動元オブジェクトID"""

    sender_id: typing.Union[int, str]
    """送信者ID、プライベートチャットの場合はlauncher_idと同じ"""

    text_message: str
    """メッセージテキスト"""

    message_event: platform_events.PersonMessage
    """元のメッセージイベントオブジェクト。送信者情報を含みます。"""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """メッセージチェーン"""

    # ========== 設定可能な属性 ==========

    user_message_alter: typing.Optional[provider_message.ContentElement] = None
    """変更されたメッセージテキスト、langbot_plugin.api.entities.builtin.provider.message.ContentElement型"""

    reply_message_chain: typing.Optional[platform_message.MessageChain] = None
    """直接返信メッセージチェーン、デフォルト動作を防止した場合のみ有効"""


class GroupNormalMessageReceived(BaseEventModel):
    """処理すべきグループチャット通常メッセージが判定されたときにトリガーされる"""

    event_name: str = "GroupNormalMessageReceived"

    launcher_type: str
    """起動元オブジェクトタイプ(group)"""

    launcher_id: typing.Union[int, str]
    """グループID"""

    sender_id: typing.Union[int, str]
    """送信者ID"""

    text_message: str
    """メッセージテキスト"""

    message_event: platform_events.GroupMessage
    """元のメッセージイベントオブジェクト。グループと送信者情報を含みます。"""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """メッセージチェーン"""

    # ========== 設定可能な属性 ==========

    user_message_alter: typing.Optional[provider_message.ContentElement] = None
    """変更されたメッセージテキスト、langbot_plugin.api.entities.builtin.provider.message.ContentElement型"""

    reply_message_chain: typing.Optional[platform_message.MessageChain] = None
    """直接返信メッセージチェーン、デフォルト動作を防止した場合のみ有効"""
```

### \*CommandSent

> warning:
>
> 使用は推奨されなくなりました。代わりに[コンポーネント: Command](https://langbot.app/docs/ja/plugin/dev/components/command.md)を使用してください。

グループチャットまたはプライベートチャットでコマンドを受信したときにトリガーされます。

```python
class PersonCommandSent(BaseEventModel):
    """処理すべきプライベートチャットコマンドが判定されたときにトリガーされる"""

    event_name: str = "PersonCommandSent"

    launcher_type: str

    launcher_id: typing.Union[int, str]

    sender_id: typing.Union[int, str]

    command: str
    """コマンドテキスト"""

    params: list[str]
    """コマンドパラメータ"""

    text_message: str
    """メッセージテキスト"""

    is_admin: bool
    """管理者かどうか"""


class GroupCommandSent(BaseEventModel):
    """処理すべきグループチャットコマンドが判定されたときにトリガーされる"""

    event_name: str = "GroupCommandSent"

    launcher_type: str

    launcher_id: typing.Union[int, str]

    sender_id: typing.Union[int, str]

    command: str
    """コマンドテキスト"""

    params: list[str]
    """コマンドパラメータ"""

    text_message: str
    """メッセージテキスト"""

    is_admin: bool
    """管理者かどうか"""
```

### NormalMessageResponded

メッセージがLLMレスポンスを受信したときにトリガーされます。

```python
class NormalMessageResponded(BaseEventModel):
    """通常メッセージに返信するときにトリガーされる"""

    event_name: str = "NormalMessageResponded"

    launcher_type: str

    launcher_id: typing.Union[int, str]

    sender_id: typing.Union[int, str]

    session: provider_session.Session
    """セッションオブジェクト"""

    prefix: str
    """返信メッセージプレフィックス"""

    response_text: str
    """返信メッセージテキスト"""

    finish_reason: str
    """レスポンス終了理由"""

    funcs_called: list[str]
    """呼び出された関数のリスト"""

    # ========== 設定可能な属性 ==========

    reply_message_chain: typing.Optional[platform_message.MessageChain] = None
    """返信メッセージコンポーネントリスト、デフォルト動作を防止した場合のみ有効"""
```

### PromptPreProcessing

LLMレスポンスコンテキスト(プロンプト)を構築するときにトリガーされます。

```python
class PromptPreProcessing(BaseEventModel):
    """セッション内のプロンプトを前処理するときにトリガーされる"""

    event_name: str = "PromptPreProcessing"

    session_name: str
    """セッション名、形式は person_1234567890 または group_1234567890"""

    # ========== 設定可能な属性 ==========

    default_prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]]
    """この会話のシナリオプリセット(システムプロンプト)、変更可能、langbot_plugin.api.entities.builtin.provider.message.Messageまたはlangbot_plugin.api.entities.builtin.provider.message.MessageChunk型"""

    prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]]
    """この会話の既存メッセージレコード、変更可能、langbot_plugin.api.entities.builtin.provider.message.Messageまたはlangbot_plugin.api.entities.builtin.provider.message.MessageChunk型"""
```

## EventListener コンテキスト

イベントハンドラーは `event_context.event` から現在のイベントを取得します。`EventContext` の完全なプロパティとメソッドは[コンテキスト API](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md#eventlistener)を参照してください。

### デフォルト動作を阻止

`event_context.prevent_default()` を呼び出すと、現在のイベントのデフォルト処理が停止します。この操作を利用できるイベントは次のとおりです。

> info:
>
> 以下のイベントのみデフォルト動作を阻止できます：
>
> - PersonMessageReceived
> - GroupMessageReceived
> - PersonNormalMessageReceived
> - GroupNormalMessageReceived
> - PersonCommandSent
> - GroupCommandSent
> - NormalMessageResponded

`event_context.prevent_postorder()` を呼び出すと、後続プラグインによる現在のイベント処理を停止できます。

---

# プラットフォーム API

Source: https://langbot.app/docs/ja/plugin/dev/apis/platform

ボット UUID を指定してプラットフォームアダプターの API を呼び出します。メッセージチェーンの送信は `self.plugin.send_message()`、グループやユーザーの取得などは以下を使用します。

## プラットフォーム API の呼び出し

```python
async def call_platform_api(
    self,
    bot_uuid: str,
    action: str,
    params: dict[str, Any] | None = None,
) -> Any:
    ...
```

Command、EventListener、Tool などのコンポーネントでは `self.plugin` から呼び出します。戻り値は操作に応じた辞書、リスト、スカラー、`None` で、プラットフォーム SDK のオブジェクトではありません。

```python
group = await self.plugin.call_platform_api(
    bot_uuid=bot_uuid,
    action="get_group_info",
    params={"group_id": "123456"},
)
```

`bot_uuid` は `await self.plugin.get_bots()`、またはパイプラインイベントの `await event_context.get_bot_uuid()` で取得できます。プラットフォーム ID には実際のイベントや設定の値を使用します。

### 主な操作

| `action`                         | `params`                             |
| -------------------------------- | ------------------------------------ |
| `get_user_info`                  | `user_id`                            |
| `get_friend_list`                | `{}`                                 |
| `get_group_info`                 | `group_id`                           |
| `get_group_list`                 | `{}`                                 |
| `get_group_member_list`          | `group_id`                           |
| `get_group_member_info`          | `group_id`, `user_id`                |
| `get_message` / `delete_message` | `chat_type`, `chat_id`, `message_id` |
| `set_group_name`                 | `group_id`, `name`                   |
| `mute_member`                    | `group_id`, `user_id`, `duration`    |
| `unmute_member` / `kick_member`  | `group_id`, `user_id`                |
| `leave_group`                    | `group_id`                           |
| `approve_friend_request`         | `request_id`, `approve`, `remark`    |
| `approve_group_invite`           | `request_id`, `approve`              |
| `get_file_url`                   | `file_id`                            |

対応する操作はプラットフォームごとに異なり、ボットの管理者権限が必要な場合があります。`duration` は秒数で、`0` の意味はプラットフォームに依存します。共通の永久ミュート値ではありません。取得結果がキャッシュに依存することもあります。ボットが未起動、未対応の操作、引数不正の場合は例外になります。

## プラットフォーム固有の API

外側の `action` を `call_platform_api` にし、`params` にプラットフォームの操作と引数を指定します。OneBot Omni でボットのアカウント情報を取得する例です：

```python
account = await self.plugin.call_platform_api(
    bot_uuid=bot_uuid,
    action="call_platform_api",
    params={"action": "get_login_info", "params": {}},
)
```

アダプターが宣言した操作のみ呼び出せます。すべてのプラットフォーム API を任意に転送できるわけではありません。プラグインはランタイム経由でホストを呼び出し、`ctx.query.adapter` や `adapter.bot` には直接アクセスしません。

## Runner

Runner の実行中、`self.plugin` によるモデル、ツール、ナレッジベース、ストレージ、プラットフォーム呼び出しは現在の実行と権限に自動的に関連付けられます。`run_id` の指定は不要です。同時実行は互いに分離されます。ハンドラー終了後に実行に紐づく API を呼び続けないでください。

現在のボットは `await ctx.get_bot_uuid()` で取得します。プラットフォーム呼び出しは今回のツール権限に従い、イベント対象だけが許可されている場合は別の対象を指定できません。プラットフォーム固有の操作を含む未許可の操作は拒否されます。デバッグではこれらの呼び出しも Mock を使用します。

```python
tools = await ctx.get_available_tools()
if any(tool["name"] == "event_get_actor" for tool in tools):
    actor = await ctx.call_tool("event_get_actor")
    await ctx.log(str(actor))
```

---

# プラグイン技術詳細

Source: https://langbot.app/docs/ja/plugin/dev/apis/tech-details

## アーキテクチャ

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_system_arch.png)

バージョン4.0では、高セキュリティで柔軟性の高い本番環境グレードのプラグインシステムを導入し、開発者に豊富なAPIと使いやすいサポートツールを提供しています。

Plugin Runtimeは、プラグインのライフサイクルを管理し、LangBotとプラグイン間の相互作用を調整するために使用されます。`stdio`と`websocket`の2つの動作モードがあります。LangBotがユーザーによって直接起動される場合(コンテナ内で実行されていない場合)、`stdio`モードを使用します。これは個人ユーザーや軽量環境で一般的です。LangBotがコンテナ内で実行される場合、`websocket`モードを使用します。これは本番環境専用に設計されています。

Plugin Runtimeは、インストールされた各プラグインを自動的に起動し、stdioを通じて相互作用します。プラグイン開発シナリオでは、開発者は`lbp`コマンドラインツールを使用してプラグインを起動し、WebSocketを介して実行中のRuntimeに接続してデバッグできます。

---

# プラグイン設定情報の完成

Source: https://langbot.app/docs/ja/plugin/dev/basic-info

## マニフェストファイルの修正

プラグインディレクトリ内の`manifest.yaml`ファイルは、プラグインの基本情報を宣言します。これはLangBot UIまたはプラグインマーケットプレイスのインターフェースに表示されます。

```yaml
apiVersion: v1  # 変更しないでください
kind: Plugin  # 変更しないでください
metadata:
  author: RockChinQ  # 作成者、正規表現^[a-zA-Z0-9_-]+$に一致する必要があります
  name: HelloPlugin  # プラグイン名、プラグインを区別するために使用、正規表現^[a-zA-Z0-9-]+$に一致する必要があります
  repository: 'https://github.com/langbot-app/HelloPlugin'  # プラグインリポジトリURL
  version: 0.1.0  # プラグインバージョン
  description:
    en_US: 'Hello LangBot Plugin'  # プラグイン説明、多言語対応
    zh_Hans: 'Hello LangBot Plugin'
  label:
    en_US: HelloPlugin  # プラグインラベル、インターフェースに表示、多言語対応
    zh_Hans: HelloPlugin
  icon: assets/icon.svg  # プラグインアイコン、デフォルトはassets/icon.svg、さまざまな画像形式に置き換え可能
spec:
  config: []  # プラグイン設定項目フォーマット
  components: {}  # プラグインコンポーネントリスト、手動で変更する必要はありません
execution:
  python:
    path: main.py  # 変更しないでください
    attr: HelloPlugin  # 変更しないでください
```

認証を申請し、複数のインストールで 1 つのランタイムを共有する場合は、`execution` 配下に `sharedRuntime` と `componentModel` も宣言します。詳細は[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

プラグインの多言語サポートは[RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646)標準に従います。現在サポートされている言語は次のとおりです:

- `en_US` 英語（必須）
- `zh_Hans` 簡体字中国語
- `zh_Hant` 繁体字中国語
- `ja_JP` 日本語
- `vi_VN` ベトナム語
- `th_TH` タイ語
- `es_ES` スペイン語

## プラグイン設定項目フォーマット

`manifest.yaml`ファイルの`spec.config`で宣言されたフィールドは、LangBotによってユーザーが入力するための設定項目フォームとしてレンダリングされます。プラグインは、SDKが提供するAPIを通じて、ユーザーが入力した設定項目を取得できます(後のセクションを参照)。

例えば:

```yaml
spec:
  config:
    - name: github_token  # 必須; 設定項目名、プラグイン内での取得に使用
      type: string  # 必須; 設定項目タイプ、string、integer、float、boolean、select、prompt-editor、llm-model-selector、bot-selector、tools-selectorなどをサポート
      label:  # 必須; 設定項目表示名、多言語サポート。言語コードはRFC 4646標準に従います。
        en_US: Github Token
        zh_Hans: Github Token
      description:  # 設定項目説明、多言語サポート。オプション。
        en_US: Image downloading requires a Github token
        zh_Hans: 如果不填的話、图片可能會下載失败
      default: ''  # 設定項目のデフォルト値、オプション。
      required: false  # 設定項目が必須かどうか、オプション。
      show_if:  # 条件付きレンダリング（条件を満たす場合にのみ表示）、オプション。
        field: mode
        operator: eq
        value: mode1
    - name: mode
      type: select
      ...
```

設定項目でサポートされるタイプとフィールドは次のとおりです:

### 条件付きレンダリング (`show_if`)

すべてのタイプの設定項目は、`show_if` フィールドを使用した条件付きレンダリングをサポートしています。同じ（または関連する）フォーム内の他のフィールドの値に基づいて、現在のフィールドをレンダリングして表示するかどうかを決定できます。

```yaml
- name: advanced_setting
  type: string
  show_if:
    field: mode          # 依存するフィールドの名前
    operator: eq         # 判定演算子。'eq' (等しい)、'neq' (等しくない)、'in' (リストに含まれる) をサポートします
    value: advanced      # 判断の基準値
```

> **注意：** クロスフォームのカスケード関係（例：RAG エンジンの `creation_schema` 設定が `retrieval_schema` の値を読み取る、またはその逆）は、LangBot の最新フロントエンドでサポートされています。

### type: string

文字列型。オプションで`options`を設定してプリセット値をサポートできます。設定すると、入力フィールドの横にドロップダウンボタンが表示され、ユーザーがプリセット値をすばやく入力できます。自由入力も可能です。

```yaml
- name: api_key
  type: string
  ...
```

プリセットオプション付き：

```yaml
- name: api_url
  type: string
  options:  # オプションのプリセット値、入力フィールドの横にドロップダウンボタンとして表示。
    - name: "https://api.openai.com/v1"  # 選択時に入力される値。
      label:  # 表示名、多言語サポート。
        en_US: OpenAI Official
        zh_Hans: OpenAI 官方
    - name: "https://api.deepseek.com/v1"
      label:
        en_US: DeepSeek
        zh_Hans: DeepSeek
  ...
```

### type: array\[string]

文字列配列。

```yaml
- name: tags
  type: array[string]
  ...
```

### type: integer

整数型。

```yaml
- name: progress
  type: integer
  ...
```

### type: float

浮動小数点型。

```yaml
- name: temperature
  type: float
  ...
```

### type: boolean

ブール型。

```yaml
- name: is_enabled
  type: boolean
  ...
```

### type: select

ドロップダウンメニュー。`options`の設定が必要で、ドロップダウンメニューのオプションを表します。各オプションは`label`をメインテキストとして表示し、`name`（値）を小さなテキストで下に表示します。

```yaml
- name: mode
  type: select
  allow_custom: true
  options:  # ドロップダウンオプション、多言語サポート。
    - name: mode1  # 値、ドロップダウンで小さなテキストとして表示。
      label:  # 表示名、多言語サポート。
        en_US: Mode 1
        zh_Hans: 模式 1
    - name: mode2
      label:  # 表示名、多言語サポート。
        en_US: Mode 2
        zh_Hans: 模式 2
  ...
```

`allow_custom: true` を設定すると、プリセットに「カスタム」が追加され、その選択時だけ入力欄が表示されます。保存される値は選択した `name` または入力した文字列であり、「カスタム」というマーカーではありません。ランナーの `spec.config` にも使用できます。

### type: prompt-editor

プロンプトエディター。パイプライン設定ページからプロンプトエディターを表示し、最終結果はOpenAIの`messages`形式で表されます。

```yaml
- name: prompt
  type: prompt-editor
  ...
```

### type: text

大きなテキスト入力。フロントエンドでtextareaとしてレンダリングされ、ユーザーが入力し、文字列としてプラグインに渡されます。

```yaml
- name: prompt
  type: text
  ...
```

### type: file

ファイルアップロード。最大10MBのファイルアップロードをサポートし、`{"file_key": "xxxxx.xxx", "mimetype": "xxxxx"}`形式でプラグインに渡されます。プラグインは`get_config_file` APIを使用してファイルの内容を取得できます。

```yaml
- name: config_file
  type: file
  accept: 'application/json'  # オプション、受け入れるファイルMIMEタイプを指定
  ...
```

プラグインでファイルを取得する:

```python
# 設定からファイル情報を取得
file_config = self.get_config()['config_file']
file_key = file_config['file_key']
mimetype = file_config['mimetype']

# 出力例: {'file_input': {'file_key': 'plugin_config_d2234fd802054faf80babe0679a97fa9.json', 'mimetype': 'application/json'}}
print(file_config)

# ファイルの内容を取得
file_bytes = await self.get_config_file(file_key)
```

> info:
>
> 一般的なMIMEタイプとファイル拡張子のリファレンス: [MDNドキュメント](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types)

### type: array\[file]

複数ファイルアップロード。fileタイプと似ていますが、複数のファイルのアップロードをサポートし、`[{"file_key": "xxxxx.xxx", "mimetype": "xxxxx"}]`形式でプラグインに渡されます。

```yaml
- name: resource_files
  type: array[file]
  accept: 'image/*'  # オプション、受け入れるファイルMIMEタイプを指定
  ...
```

プラグインでファイルを取得する:

```python
# 設定からファイルリストを取得
files_config = self.get_config()['resource_files']

for file_config in files_config:
    file_key = file_config['file_key']
    mimetype = file_config['mimetype']

    # ファイルの内容を取得
    file_bytes = await self.get_config_file(file_key)
```

### type: llm-model-selector

LLMモデルセレクター。設定されたLLMモデルを選択できるLLMモデルセレクターを表示し、最終結果はLLMモデルUUIDとして表されます。

```yaml
- name: model
  type: llm-model-selector
  ...
```

### type: bot-selector

Botセレクター。設定されたBotを選択できるBotセレクターを表示し、最終結果はBot UUIDとして表されます。

```yaml
- name: bot
  type: bot-selector
  ...
```

プラグインでBot UUIDを使用する:

```python
# 設定からBot UUIDを取得
bot_uuid = self.get_config()['bot']
print(bot_uuid)  # 出力: '550e8400-e29b-41d4-a716-446655440000'
```

### type: tools-selector

ツールセレクター。登録済みのツール（プラグインツールおよび MCP ツール）を複数選択できるセレクターを表示します。最終結果はツール名の配列として表現されます。

```yaml
- name: selected_tools
  type: tools-selector
  ...
```

プラグインで選択されたツール名を使用する:

```python
# 設定から選択されたツール名リストを取得
selected_tools = self.get_config()['selected_tools']
print(selected_tools)  # 出力: ['get_weather_alerts', 'web_search']

# 選択されたツールを呼び出す
for tool_name in selected_tools:
    result = await self.plugin.call_tool(
        tool_name=tool_name,
        parameters={"query": "hello"},
        session={},
        query_id=0,
    )
```

## 次のステップ

このチュートリアルでは、プラグイン機能を段階的に完成させる方法を案内します。

- コンポーネントの追加: プラグインコンポーネントはプラグインのコア機能ユニットです。必要に応じて[コンポーネントを追加](https://langbot.app/docs/en/plugin/dev/components/add.md)できます。

---

# コンポーネントの追加

Source: https://langbot.app/docs/ja/plugin/dev/components/add

プラグインは、LangBotにさまざまな機能を提供する1つ以上のコンポーネントで構成されています。現在サポートされているコンポーネントタイプには次のものがあります:

- プラグインプロセッサー（Runner）：インスタンスを作成してイベントに紐付け、プラグインのコードで処理します。[チュートリアル](https://langbot.app/docs/ja/plugin/dev/components/runner.md)を参照してください。
- Agent ランナー（Runner）：Agent の設定で選択する実行コンポーネントです。独立したプラグインプロセッサーとは異なります。
- イベントリスナー(EventListener): パイプライン実行中のイベントをリッスンし、コンテキストやパイプラインを変更します。
- コマンド(Command): `!`(または他の設定されたプレフィックス)で始まるユーザーコマンドメッセージによってトリガーされます。
- ツール(Tool): LangBotの組み込みLocal Agentの実行中にLLMによって呼び出されます。
- RAGエンジン(KnowledgeEngine): LangBotにナレッジベースのインデックス作成と検索機能を提供し、ドキュメントの取り込み、検索、削除を管理します。
- パーサー(Parser): ドキュメント取り込みの前にPDF、Wordなどのバイナリファイルを構造化テキストに解析し、RAGエンジンで使用できるようにします。
- ページ(Page): LangBot WebUIのサイドバーにカスタムビジュアルページを登録し、管理パネルやデータ表示などのインタラクティブなインターフェースを提供します。

## コンポーネントの追加

プラグインディレクトリでコマンドを実行します:

```bash
lbp comp <component_type>
```

例えば、イベントリスナーを追加する場合:

```bash
lbp comp EventListener
```

プロンプトに従って、コンポーネント設定(ある場合)を入力します。

```bash
➜  HelloPlugin > lbp comp EventListener
Generating component EventListener...
Component EventListener generated successfully.
組件 EventListener 生成成功。
➜  HelloPlugin >
```

> :
>
> CLIはプラグインディレクトリに`components`ディレクトリを生成し、その中に対応するコンポーネントディレクトリを作成します。
>
> ```
> .
> ├── assets
> │   └── icon.svg
> ├── components
> │   ├── __init__.py
> │   └── event_listener
> │       ├── __init__.py
> │       ├── default.py
> │       └── default.yaml
> ├── main.py
> ├── manifest.yaml
> ├── README.md
> └── requirements.txt
> ```
>
> 同時に、プラグインの`manifest.yaml`にコンポーネント検出設定が追加されます:
>
> ```yaml
> ...
> components:
>     EventListener:
>       fromDirs:
>       - path: components/event_listener/
> ...
> ```
>
> コンポーネントを削除するには、対応する情報を手動で削除できます。

## コンポーネントタイプ

各コンポーネントの詳細な使用方法については、次を参照してください:

- [Runner](https://langbot.app/docs/ja/plugin/dev/components/runner.md)
- [EventListener](https://langbot.app/docs/ja/plugin/dev/components/event-listener.md)
- [Command](https://langbot.app/docs/ja/plugin/dev/components/command.md)
- [Tool](https://langbot.app/docs/ja/plugin/dev/components/tool.md)
- [KnowledgeEngine](https://langbot.app/docs/ja/plugin/dev/components/knowledge-engine.md)
- [Parser](https://langbot.app/docs/ja/plugin/dev/components/parser.md)
- [Page](https://langbot.app/docs/ja/plugin/dev/components/page.md)

---

# コンポーネント: Command

Source: https://langbot.app/docs/ja/plugin/dev/components/command

Commandコンポーネントは、`!`(または他の設定されたプレフィックス)で始まるユーザーコマンドメッセージによってトリガーされます。`!help`コマンドをトリガーする例を次に示します:

![](https://langbot.app/docs/images/zh/plugin/dev/components/command_use.png)

## Commandコンポーネントの追加

1つのプラグインには任意の数のコマンドを含めることができます。プラグインディレクトリでコマンド`lbp comp Command`を実行し、プロンプトに従ってコマンド設定を入力します。

```bash
➜  HelloPlugin > lbp comp Command
Generating component Command...
Command name: info
Command description: Show information of the query
Component Command generated successfully.
組件 Command 生成成功。
```

これにより、`components/commands/`ディレクトリに`info.yaml`と`info.py`ファイルが生成されます。`.yaml`ファイルは`!info`コマンドの基本情報を定義し、`.py`ファイルはコマンドハンドラです:

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   ├── commands
│   │   ├── __init__.py
│   │   ├── info.py
│   │   └── info.yaml
...
```

## マニフェストファイル: Commandコンポーネント

```yaml
apiVersion: v1  # 変更しないでください
kind: Command  # 変更しないでください
metadata:
  name: info  # コマンド名、ユーザーは!infoでこのコマンドをトリガーします
  label:  # コマンド表示名、LangBot UIに表示、多言語対応
    en_US: Info
    zh_Hans: Info
  description:  # コマンド説明、LangBot UIに表示、多言語対応。オプション。
    en_US: 'Show information of the query'
    zh_Hans: '発送此次消息的詳細信息'
spec:
execution:
  python:
    path: info.py  # コマンドハンドラ、変更しないでください
    attr: Info  # コマンドハンドラクラス名、info.pyのクラス名と一致
```

## プラグイン処理

以下のコードがデフォルトで生成されます(`components/command/<command_name>.py`)。`Info`クラスの`initialize`メソッドでサブコマンド処理ロジックを登録して実装する必要があります。

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from typing import Any, AsyncGenerator

from langbot_plugin.api.definition.components.command.command import Command, Subcommand
from langbot_plugin.api.entities.builtin.command.context import ExecuteContext, CommandReturn


class Info(Command):

    async def initialize(self):
        await super().initialize()

        "Fill with your code here"
```

サブコマンドの追加:

```python
...
class Info(Command):

    async def initialize(self):
        await super().initialize()

        @self.subcommand(
            name="",  # 空文字列はルートコマンドを表す
            help="Show information of the query", # コマンドヘルプ情報
            usage="info", # コマンド使用例、コマンドヘルプに表示
            aliases=["i"], # コマンドエイリアス
        )
        async def send(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]:
            print(context)

            reply_text = f"Query ID: {context.query_id}\n"
            reply_text += f"command: {context.command}\n"
            reply_text += f"command_text: {context.command_text}\n"
            reply_text += f"params: {context.params}\n"
            reply_text += f"crt_params: {context.crt_params}\n"
            reply_text += f"privilege: {context.privilege}\n"
            reply_text += f"session: {context.session.launcher_type.value}_{context.session.launcher_id}\n"

            yield CommandReturn(
                text=reply_text,
            )

        @self.subcommand(
            name="field",
            help="Show information of the field",
            usage="info field",
            aliases=["f"],
        )
        async def field(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]:
            print(context)

            field_name = context.crt_params[0]
            field_value = getattr(context, field_name)

            yield CommandReturn(
                text=f"{field_name}: {field_value}",
            )
```

このコードでは、`@self.subcommand`デコレータを通じて`send`関数がサブコマンドとして登録され、コマンドコンテキスト(ExecuteContext)情報を出力し、それを返信メッセージに連結します。

### サブコマンド登録

`name`はサブコマンド名です。空のままにすると、メインコマンドを処理することを意味します。空でない場合、2番目のパラメータをコマンドとして照合します。例えば:

- `!info`は、name=""のサブコマンドに一致
- `!info field`は、name="field"のサブコマンドに一致
- `!info field value`は、name="field"のサブコマンドに一致し、`value`がサブコマンドパラメータ
- 特に、`name="*"`は、一致しないすべての第1レベルサブコマンドに一致し、`info`の後の各セクションをパラメータとして渡します。例えば`!info 123`、`!info abc`。ユーザーの入力に応じて、`context.crt_params`から`['123']`または`['abc']`を取得できます。

サブコマンド関数では、`context`変数を通じてコマンドパラメータを読み取ることができます。

上記のコマンドの効果は画像に示されています:

![](https://langbot.app/docs/images/zh/plugin/dev/components/info_command_demo.png)

### コマンドコンテキスト

```python

class ExecuteContext(pydantic.BaseModel):
    """単一コマンド実行コンテキスト"""

    query_id: int
    """リクエストID"""

    session: provider_session.Session
    """このメッセージのセッションオブジェクト"""

    command_text: str
    """完全なコマンドテキスト"""

    command: str
    """コマンド名"""

    crt_command: str
    """現在のコマンド

    マルチレベルコマンドでは、crt_commandは現在のコマンド、commandはルートコマンド。
    例: !plugin on Webwlkr
    pluginを処理する場合、commandはplugin、crt_commandはplugin
    onを処理する場合、commandはplugin、crt_commandはon
    """

    params: list[str]
    """コマンドパラメータ

    コマンド全体をスペースで分割した後のパラメータリスト
    """

    crt_params: list[str]
    """現在のコマンドパラメータ

    マルチレベルコマンドでは、crt_paramsは現在のコマンドパラメータ、paramsはルートコマンドパラメータ。
    例: !plugin on Webwlkr
    pluginを処理する場合、paramsは['on', 'Webwlkr']、crt_paramsは['on', 'Webwlkr']
    onを処理する場合、paramsは['on', 'Webwlkr']、crt_paramsは['Webwlkr']
    """

    privilege: int
    """セッション権限レベル"""

    ...
```

### コマンド戻り値

コマンド戻り値(CommandReturn)は、現在テキスト、画像(image\_url、画像リンク)、エラーの返却をサポートしています。

```python
yield CommandReturn(
    text=reply_text,
)

yield CommandReturn(
    image_url=image_url,
)
```

コマンド処理は複数のメッセージを返すことをサポートしているため、`yield`ステートメントを使用してメッセージを返してください。

具体的な戻り値については、`CommandReturn`の定義を参照してください: [langbot\_plugin.api.entities.builtin.command.context.CommandReturn](https://github.com/langbot-app/langbot-plugin-sdk/tree/main/src/langbot_plugin/api/entities/builtin/command/context.py)

## 1 つの installation、複数の用途

1 つのコマンドは**複数の会話から同時に**起動されます：

- 設定は呼び出しごとに読み取ってください。`initialize()` で読み取ってインスタンスにキャッシュしないでください。
- コマンド引数、戻り値、会話データをインスタンスフィールドやモジュールレベルの変数に残さないでください。`ExecuteContext` は今回の実行でのみ有効です。
- 同時起動ではインスタンスフィールドの書き込みが交錯します。「現在の会話」のような状態をそこに保存しないでください。呼び出しをまたいで保持するデータは Host ストレージに置き、キーに会話の識別子を含めてください。
- installation 単位でプロセス内キャッシュを保持する場合は、`on_installation_revoked(binding)` で解放してください。

完全な仕様は[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

## 次のステップ

コマンド登録とコマンド実行の基本情報を学びました。次は:

- 完全な [`ExecuteContext` API リファレンス](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md#command)を確認します。
- [LangBot API](https://langbot.app/docs/ja/plugin/dev/apis/common.md)を確認します。

---

# コンポーネント: イベントリスナー

Source: https://langbot.app/docs/ja/plugin/dev/components/event-listener

> info:
>
> このコンポーネントはパイプラインの処理を拡張します。メッセージ受信やメンバー参加などの Bot イベントを処理する場合は、[イベントプロセッサー](https://langbot.app/docs/ja/plugin/dev/components/runner.md)を参照してください。

LangBotのパイプラインは実行時にイベントを生成し、プラグインがフックして処理できるようにします。各プラグインは1つのイベントリスナー(components/event\_listener/default.yaml)のみを持つことができますが、その中で任意の数のイベントを登録できます。

## イベントリスナーコンポーネントの追加

プラグインディレクトリでコマンド`lbp comp EventListener`を実行します。イベントリスナーコンポーネントの作成には設定は必要ありません。

```bash
➜  HelloPlugin > lbp comp EventListener
Generating component EventListener...
Component EventListener generated successfully.
組件 EventListener 生成成功。
```

これにより、`components/event_listener/`ディレクトリに`default.yaml`と`default.py`ファイルが生成されます。`.yaml`ファイルはイベントリスナーの基本情報を定義し、`.py`ファイルはイベントリスナーハンドラです:

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   └── event_listener
│       ├── __init__.py
│       ├── default.py
│       └── default.yaml
...
```

## マニフェストファイル: イベントリスナー

各プラグインは1つのイベントリスナーのみを持つことができるため、マニフェストファイルでの変更は必要ありません。

## プラグイン処理

以下のコードがデフォルトで生成されます(components/event\_listener/default.py)。`DefaultEventListener`クラスの`initialize`メソッドでイベント処理ロジックを登録して実装する必要があります。

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from langbot_plugin.api.definition.components.common.event_listener import EventListener
from langbot_plugin.api.entities import events, context


class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()

        "Fill with your code here"
```

特定のイベントのリスナーを追加:

```python
...
class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()

        @self.handler(events.PersonMessageReceived)
        async def handler(event_context: context.EventContext):
            print("Hello LangBot Plugin!")
            print(event_context)

            await event_context.reply(
                platform_message.MessageChain([
                    platform_message.Plain(text=f"Hello from Nahida Plugin!"),
                ])
            )
```

このコードは、`PersonMessageReceived`(プライベートチャットからのメッセージを受信)イベントのリスナーを登録し、イベントがトリガーされたときにイベントコンテキスト(EventContext)情報を出力し、イベントコンテキストAPIを呼び出してメッセージで返信します。

EventContextはこのイベントトリガーの共通コンテキスト情報を保存し、EventContext.eventはPersonMessageReceived(または他の対応するイベントタイプ)のオブジェクトで、イベントの詳細情報を保存します。

```python
# EventContext定義の概要
class EventContext(pydantic.BaseModel):
    """イベントコンテキスト、このイベント実行の情報を保存"""
    ...

    event: pydantic.SerializeAsAny[BaseEventModel]
    """イベントオブジェクト、具体的な型はハンドラ登録時に指定された型、events.pyで見つけることができます"""

    ...
```

## イベント登録

イベント登録は`@self.handler`デコレータを通じて実装され、デコレータのパラメータはイベントタイプです。監視可能なすべてのイベントは`langbot_plugin.api.entities.builtin.events`で定義されています。

## 1 つの installation、複数の用途

同じイベントリスナーは**複数の Workspace、複数のイベントから同時に**呼び出されます：

- イベント単位の状態（カウンタ、直近のイベント、会話マップなど）をインスタンスに蓄積しないでください。同時実行のコールバックが互いを上書きします。
- コールバックは現在の `EventContext` からのみデータを取得し、コンテキストやそのフィールドを呼び出しをまたいで再利用しないでください。
- 呼び出しをまたいで保持するデータは Host ストレージに置き、キーに installation の識別子とイベントに関連する識別子（Workspace、会話など）を含めてください。
- installation 単位でプロセス内状態を保持する場合は、`on_installation_revoked(binding)` で解放してください。

完全な仕様は[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

## 次のステップ

イベントリスナーの基本情報を学びました。次は:

- [パイプラインイベント](https://langbot.app/docs/ja/plugin/dev/apis/pipeline-events.md)でイベントの種類とフィールドを確認します。
- 完全な [`EventContext` API リファレンス](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md#eventlistener)を確認します。
- [LangBot API](https://langbot.app/docs/ja/plugin/dev/apis/common.md)を確認します。

---

# コンポーネント: 知識エンジン

Source: https://langbot.app/docs/ja/plugin/dev/components/knowledge-engine

RAGエンジン（KnowledgeEngine）コンポーネントにより、プラグインはLangBotにナレッジベースの完全なインデックス作成と検索機能を提供できます。ユーザーがLangBotでナレッジベースを作成する際、プラグインが提供するRAGエンジンを選択して、ドキュメントの取り込み、検索、削除を管理できます。また、プラグインを通じてDify、RAGFlow、FastGPTなどの業界先進のナレッジベースサービスとブリッジすることも可能です。

## RAGエンジンコンポーネントの追加

1つのプラグインには任意の数のRAGエンジンを追加できます。プラグインディレクトリでコマンド`lbp comp KnowledgeEngine`を実行し、プロンプトに従ってRAGエンジンの設定を入力します。

```bash
➜  MyRAGPlugin > lbp comp KnowledgeEngine
Generating component KnowledgeEngine...
Knowledge Engine name: simple_rag
Knowledge Engine description: A simple Knowledge Engine with built-in chunking and retrieval
Component KnowledgeEngine generated successfully.
組件 KnowledgeEngine 生成成功。
```

これにより、`components/knowledge_engine/`ディレクトリに`simple_rag.yaml`と`simple_rag.py`ファイルが生成されます。`.yaml`ファイルはRAGエンジンの基本情報と設定スキーマを定義し、`.py`ファイルはこのエンジンのハンドラです:

```bash
➜  MyRAGPlugin > tree
...
├── components
│   ├── __init__.py
│   └── knowledge_engine
│       ├── __init__.py
│       ├── simple_rag.py
│       └── simple_rag.yaml
...
```

## マニフェストファイル: RAGエンジン

```yaml
apiVersion: v1  # 変更しないでください
kind: KnowledgeEngine  # 変更しないでください
metadata:
  name: simple_rag  # RAGエンジン名、このエンジンを識別するために使用
  label:
    en_US: Simple Knowledge Engine  # エンジン表示名、LangBotのUIに表示、多言語対応
    zh_Hans: 简易 RAG 引擎
    ja_JP: シンプル RAG エンジン
  description:
    en_US: 'A simple Knowledge Engine with built-in chunking and retrieval'
    zh_Hans: '内置分块和检索能力的简易 RAG 引擎'
    ja_JP: 'チャンキングと検索を内蔵したシンプルなRAGエンジン'
spec:
  creation_schema:  # ナレッジベース作成時にユーザーが入力する設定パラメータ
    - name: chunk_size
      label:
        en_US: Chunk Size
        zh_Hans: 分块大小
      type: integer
      required: false
      default: 500
    - name: chunk_overlap
      label:
        en_US: Chunk Overlap
        zh_Hans: 分块重叠
      type: integer
      required: false
      default: 50
  retrieval_schema:  # 検索時に設定可能なパラメータ
    - name: score_threshold
      label:
        en_US: Score Threshold
        zh_Hans: 分数阈值
      type: float
      required: false
      default: 0.5
execution:
  python:
    path: simple_rag.py  # エンジンハンドラ、変更しないでください
    attr: SimpleRag  # エンジンハンドラのクラス名、simple_rag.pyのクラス名と一致
```

設定項目フォーマットのリファレンスについては、[プラグインマニフェスト設定フォーマット](https://langbot.app/docs/ja/plugin/dev/basic-info.md)を参照してください。

### creation\_schema と retrieval\_schema

旧バージョンの`KnowledgeRetriever`コンポーネントが単一の`spec.config`を使用していたのとは異なり、KnowledgeEngineは2つの独立したスキーマを使用します:

- **creation\_schema**: ナレッジベース作成時にユーザーが入力するパラメータ。取り込みと検索時に`creation_settings`を通じてプラグインに渡されます。
- **retrieval\_schema**: ナレッジベースのクエリ時にユーザーが調整できるパラメータ。`retrieval_settings`を通じてプラグインに渡されます。

## 能力宣言

KnowledgeEngineはサポートする能力を宣言でき、LangBotはこれらの能力宣言に基づいてUIの表示と利用可能な操作を決定します:

```python
from langbot_plugin.api.definition.components.knowledge_engine.engine import KnowledgeEngine, KnowledgeEngineCapability

class SimpleRag(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return [
            KnowledgeEngineCapability.DOC_INGESTION,    # ドキュメントのアップロードと処理をサポート
        ]
```

利用可能な能力定数:

| 能力              | 説明                                                                                                                                                                                                                      |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOC_INGESTION` | ドキュメントのアップロードと処理をサポート。宣言すると、LangBotはナレッジベースの詳細に「ドキュメント」タブを表示します。プラグインが他のナレッジベースサービスとのブリッジ用である場合や、ユーザーによるドキュメントのアップロードが不要な場合は、この能力宣言を省略できます。                                                                             |
| `DOC_PARSING`   | ネイティブドキュメント解析（ファイルからテキストへの抽出）をサポート。宣言すると、ユーザーはドキュメントアップロード時にRAGエンジンの内蔵解析機能を選択でき、外部[Parserプラグイン](https://langbot.app/docs/ja/plugin/dev/components/parser.md)が不要になります。未宣言の場合、ドキュメントをアップロードするには外部Parserプラグインのインストールが必要です。 |

> info:
>
> その他の検索動作（リランキング、ハイブリッド検索など）はプラグインの`retrieval_schema`で制御され、能力フラグは不要です。

## プラグインハンドラ

以下のコードがデフォルトで生成されます（`components/knowledge_engine/<エンジン名>.py`）。`ingest`、`retrieve`、`delete_document`の3つのコアメソッドを実装する必要があります。完全なコードは[langbot-plugin-demo](https://github.com/langbot-app/langbot-plugin-demo)の`SimpleKnowledgeEngine`で見つけることができます。

```python
from langbot_plugin.api.definition.components.knowledge_engine.engine import KnowledgeEngine, KnowledgeEngineCapability
from langbot_plugin.api.entities.builtin.rag.models import (
    IngestionContext,
    IngestionResult,
)
from langbot_plugin.api.entities.builtin.rag.context import (
    RetrievalContext,
    RetrievalResponse,
    RetrievalResultEntry,
)
from langbot_plugin.api.entities.builtin.rag.enums import DocumentStatus
from langbot_plugin.api.entities.builtin.provider.message import ContentElement


class SimpleRag(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return [KnowledgeEngineCapability.DOC_INGESTION]

    async def on_knowledge_base_create(self, kb_id: str, config: dict) -> None:
        """ナレッジベース作成時のコールバック、リソースの初期化に使用できます"""
        pass

    async def on_knowledge_base_delete(self, kb_id: str) -> None:
        """ナレッジベース削除時のコールバック、リソースのクリーンアップに使用できます"""
        pass

    async def ingest(self, context: IngestionContext) -> IngestionResult:
        """ドキュメントをナレッジベースに取り込む"""

        # 1. ファイル内容を取得
        file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)

        # 2. ドキュメントを解析してチャンクに分割
        text = file_bytes.decode('utf-8')
        chunk_size = context.creation_settings.get('chunk_size', 500)
        chunk_overlap = context.creation_settings.get('chunk_overlap', 50)
        chunks = self._split_text(text, chunk_size, chunk_overlap)

        # 3. ホストの埋め込みモデルを使用してベクトルを生成
        embedding_model_uuid = context.creation_settings.get('embedding_model_uuid', '')
        vectors = await self.plugin.invoke_embedding(embedding_model_uuid, chunks)

        # 4. ホストのベクトルデータベースに書き込み
        collection_id = context.get_collection_id()
        ids = [f"{context.file_object.metadata.document_id}_{i}" for i in range(len(chunks))]
        metadata = [{"document_id": context.file_object.metadata.document_id, "chunk_index": i, "text": chunks[i]} for i in range(len(chunks))]
        await self.plugin.vector_upsert(collection_id, vectors, ids, metadata)

        return IngestionResult(
            document_id=context.file_object.metadata.document_id,
            status=DocumentStatus.COMPLETED,
            chunks_created=len(chunks),
        )

    async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
        """ナレッジベースから関連コンテンツを検索"""

        # 1. クエリベクトルを生成
        embedding_model_uuid = context.creation_settings.get('embedding_model_uuid', '')
        query_vectors = await self.plugin.invoke_embedding(embedding_model_uuid, [context.query])
        query_vector = query_vectors[0]

        # 2. ベクトル検索
        collection_id = context.get_collection_id()
        results = await self.plugin.vector_search(collection_id, query_vector, top_k=context.retrieval_settings.get('top_k', 5))

        # 3. 検索結果に変換
        entries = []
        for r in results:
            entry = RetrievalResultEntry(
                id=r.get('id', ''),
                content=[ContentElement.from_text(r.get('metadata', {}).get('text', ''))],
                metadata=r.get('metadata', {}),
                distance=r.get('score', 0.0),
            )
            entries.append(entry)

        return RetrievalResponse(
            results=entries,
            total_found=len(entries),
            metadata={},
        )

    async def delete_document(self, kb_id: str, document_id: str) -> bool:
        """ナレッジベースからドキュメントと関連データを削除"""
        collection_id = kb_id
        deleted = await self.plugin.vector_delete(collection_id, file_ids=[document_id])
        return deleted > 0
```

### ライフサイクルフック

KnowledgeEngineは、ナレッジベースの作成・削除時に呼び出される2つのライフサイクルフックを提供します:

```python
async def on_knowledge_base_create(self, kb_id: str, config: dict) -> None:
    """このエンジンを使用するナレッジベースが作成された時のコールバック

    Args:
        kb_id: ナレッジベースUUID
        config: ユーザーが作成時に入力した設定（creation_schemaのフィールド）
    """

async def on_knowledge_base_delete(self, kb_id: str) -> None:
    """このエンジンを使用するナレッジベースが削除された時のコールバック

    Args:
        kb_id: ナレッジベースUUID
    """
```

### ドキュメントの取り込み

`ingest`メソッドは、ユーザーがナレッジベースにドキュメントをアップロードした時に呼び出されます:

```python
async def ingest(self, context: IngestionContext) -> IngestionResult:
```

**IngestionContext**には以下の情報が含まれます:

```python
class IngestionContext(pydantic.BaseModel):
    file_object: FileObject        # 取り込むファイルオブジェクト
    knowledge_base_id: str         # ターゲットのナレッジベースID
    collection_id: str | None      # ベクトルコレクションID（デフォルトはknowledge_base_idにフォールバック）
    creation_settings: dict        # ナレッジベース作成時の設定パラメータ
    parsed_content: ParseResult | None  # 外部Parserプラグインの事前解析コンテンツ（存在する場合）
```

**FileObject**にはファイルのメタ情報が含まれます:

```python
class FileObject(pydantic.BaseModel):
    metadata: FileMetadata    # filename, file_size, mime_type, document_id, knowledge_base_id等を含む
    storage_path: str         # ストレージシステム内のファイルパス
```

**IngestionResult**は取り込み結果を返す必要があります:

```python
class IngestionResult(pydantic.BaseModel):
    document_id: str                  # ドキュメントID
    status: DocumentStatus            # 処理ステータス: COMPLETED / FAILED
    chunks_created: int = 0           # 作成されたチャンク数
    error_message: str | None = None  # 失敗時のエラーメッセージ
    metadata: dict = {}               # 追加メタデータ
```

### ナレッジ検索

`retrieve`メソッドは、ナレッジベースがクエリされた時に呼び出されます:

```python
async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
```

**RetrievalContext**には以下の情報が含まれます:

```python
class RetrievalContext(pydantic.BaseModel):
    query: str                           # クエリテキスト
    knowledge_base_id: str | None        # ナレッジベースID
    collection_id: str | None            # ベクトルコレクションID
    retrieval_settings: dict             # 検索時の設定パラメータ（retrieval_schemaのフィールド）
    creation_settings: dict              # ナレッジベース作成時の設定パラメータ
    filters: dict                        # メタデータフィルター条件（Chromaスタイルwhere構文）
```

> info:
>
> LangBotホストは`retrieval_settings`をプラグインに渡す前にデフォルトの`top_k`値（デフォルト5）を自動的に注入します。プラグインは`context.retrieval_settings.get('top_k', 5)`でアクセスできます。
>
> `filters`フィールドには`retrieval_settings`から抽出されたChromaスタイルの`where`フィルター条件が含まれます。呼び出し元が検索設定で`filters`を指定した場合（例：時間範囲、ファイルタイプ、カスタムメタデータフィールドによるドキュメントフィルタリング）、ホストがこのフィールドを設定し、プラグインは検索時にフィルタリングを適用できます。フィルターが指定されていない場合、このフィールドは空のdictです。

**RetrievalResponse**は検索結果を返す必要があります:

```python
class RetrievalResponse(pydantic.BaseModel):
    results: list[RetrievalResultEntry]  # 検索結果リスト
    total_found: int                     # 一致した総数
    metadata: dict                       # 追加メタデータ
```

**RetrievalResultEntry**は単一の検索結果を表します:

```python
class RetrievalResultEntry(pydantic.BaseModel):
    id: str                       # 結果ID
    content: list[ContentElement] # コンテンツ、ContentElement.from_text()を使用して作成
    metadata: dict                # メタデータ
    distance: float               # 距離スコア（小さいほど関連性が高い）
    score: float | None = None    # 類似度スコア（大きいほど関連性が高い）
```

### ドキュメントの削除

`delete_document`メソッドは、ユーザーがナレッジベースからドキュメントを削除した時に呼び出されます:

```python
async def delete_document(self, kb_id: str, document_id: str) -> bool:
    """ドキュメントと関連データを削除

    Args:
        kb_id: ナレッジベースID
        document_id: ドキュメントID

    Returns:
        削除が成功したかどうか
    """
```

## ホストRAG API

KnowledgeEngineコンポーネントは`self.plugin`を通じて、LangBotホストが提供する埋め込みモデル呼び出し、ベクトルデータベース操作、ファイル読み取りなどのRAG関連APIを呼び出すことができます。

### 埋め込みモデルの呼び出し

```python
async def invoke_embedding(
    self,
    embedding_model_uuid: str,
    texts: list[str],
) -> list[list[float]]:
    """ホストの埋め込みモデルを使用してベクトルを生成

    Args:
        embedding_model_uuid: 埋め込みモデルUUID
        texts: 埋め込むテキストのリスト

    Returns:
        ベクトルのリスト、入力テキストごとに1つ
    """

# 使用例
vectors = await self.plugin.invoke_embedding("model_uuid", ["Hello", "World"])
```

### ベクトルの書き込み

```python
async def vector_upsert(
    self,
    collection_id: str,
    vectors: list[list[float]],
    ids: list[str],
    metadata: list[dict] | None = None,
) -> None:
    """ホストのベクトルデータベースにベクトルを書き込む

    Args:
        collection_id: ターゲットコレクションID
        vectors: ベクトルのリスト
        ids: ベクトルの一意識別子リスト
        metadata: オプションのメタデータリスト
    """

# 使用例
await self.plugin.vector_upsert(
    collection_id="kb_uuid",
    vectors=[[0.1, 0.2, ...], [0.3, 0.4, ...]],
    ids=["chunk_0", "chunk_1"],
    metadata=[{"document_id": "doc1"}, {"document_id": "doc1"}],
)
```

### ベクトル検索

```python
async def vector_search(
    self,
    collection_id: str,
    query_vector: list[float],
    top_k: int = 5,
    filters: dict | None = None,
) -> list[dict]:
    """ホストのベクトルデータベースで類似ベクトルを検索

    Args:
        collection_id: ターゲットコレクションID
        query_vector: 類似性検索のクエリベクトル
        top_k: 返す結果の数
        filters: オプションのメタデータフィルター

    Returns:
        検索結果のリスト（id, score, metadataなどを含むdict）
    """

# 使用例
results = await self.plugin.vector_search(
    collection_id="kb_uuid",
    query_vector=[0.1, 0.2, ...],
    top_k=5,
)
# 返却フォーマット: [{"id": "chunk_0", "score": 0.123, "metadata": {"document_id": "doc1", ...}}, ...]
```

> info:
>
> `vector_search`が返す各結果はdictで、`id`（ベクトルID）、`score`（距離スコア）、`metadata`（upsert時に提供したメタデータ）の3つのフィールドを含みます。検索結果にテキスト内容が必要な場合は、取り込み時にmetadataにテキストを保存してください。

### ベクトルの削除

```python
async def vector_delete(
    self,
    collection_id: str,
    file_ids: list[str] | None = None,
    filters: dict | None = None,
) -> int:
    """ホストのベクトルデータベースからベクトルを削除

    Args:
        collection_id: ターゲットコレクションID
        file_ids: 削除するファイルIDのリスト
        filters: オプションのメタデータフィルター

    Returns:
        削除されたアイテム数
    """

# 使用例
deleted = await self.plugin.vector_delete(
    collection_id="kb_uuid",
    file_ids=["doc_001"],
)
```

> info:
>
> `filters`パラメータはChromaスタイルの`where`構文によるメタデータフィルタリングをサポートしています。複数のトップレベルキーはAND条件として結合されます。サポートされる演算子：`$eq`、`$ne`、`$gt`、`$gte`、`$lt`、`$lte`、`$in`、`$nin`。例：`{"file_id": {"$eq": "abc"}}`。
>
> **注意：** Chroma、Qdrant、SeekDBは完全なメタデータを保存し、任意のフィールドでフィルタリングできます。MilvusとpgvectorはDB側に`text`、`file_id`、`chunk_uuid`のみ保存しており、それ以外のフィールドでのフィルタリングは無視されます。

```python
async def get_knowledge_file_stream(self, storage_path: str) -> bytes:
    """ホストストレージからファイル内容を取得

    Args:
        storage_path: ファイルのストレージパス（FileObject.storage_pathから取得）

    Returns:
        ファイル内容のバイトデータ
    """

# 使用例
file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)
```

## 1 つの installation、複数の用途

1 つの RAG エンジンは**複数のナレッジベース**から同時に使われ、プラットフォームのストレージキー `(instance, Workspace, owner type, plugin, key)` にはナレッジベースの次元がありません：

- 永続化とキャッシュのキーには**ナレッジベース ID** を含めてください。含めないと、別々のナレッジベースのベクトルやドキュメント状態が互いを上書きします。
- ロックと「要対账」状態は `(installation, ナレッジベース)` 単位で記録してください。**1 つのナレッジベースの取り込み失敗が、同じ installation の他のナレッジベースの取り込みや検索を遮断してはいけません。**
- 手動対账が必要な状態に入るのは、送出済みで結果不明の変更だけにしてください。決定的な検証エラーや送出前のキャンセルは後続の呼び出しに影響させないでください。
- テレメトリや診断の失敗は業務に影響させないでください。ログや送信の失敗で取り込みや検索を中断せず、テナントデータをプロセス全体のシングルトンに書き込まないでください。
- installation 単位でプロセス内キャッシュや状態を保持する場合は、`on_installation_revoked(binding)` で解放してください。

完全な仕様は[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

## RAGエンジンのテスト

作成後、プラグインディレクトリでコマンド`lbp run`を実行してデバッグを開始します。その後、LangBotで:

1. 「ナレッジベース」ページに移動
2. 「ナレッジベースを作成」をクリック
3. プラグインが提供するRAGエンジンを選択し、エンジンの`creation_schema`に基づいて設定を入力
4. 作成後、ドキュメントをアップロードして取り込み機能をテスト（エンジンが`DOC_INGESTION`能力を宣言している場合）
5. パイプラインにナレッジベースをバインドし、検索機能をテスト

---

# コンポーネント: ナレッジリトリーバー

Source: https://langbot.app/docs/ja/plugin/dev/components/knowledge-retriever

ナレッジリトリーバーコンポーネントにより、プラグインはLangBotに外部ナレッジベース検索機能を提供できます。ユーザーがLangBotで外部ナレッジベースを作成する際、プラグインが提供するナレッジリトリーバーを選択してナレッジを検索できます。

![](https://langbot.app/docs/images/zh/plugin/dev/components/knowledge_retriever_use.png)

## ナレッジリトリーバーコンポーネントの追加

1つのプラグインには任意の数のナレッジリトリーバーを追加できます。プラグインディレクトリでコマンド`lbp comp KnowledgeRetriever`を実行し、プロンプトに従ってナレッジリトリーバーの設定を入力します。

```bash
➜  FastGPTRetriever > lbp comp KnowledgeRetriever
Generating component KnowledgeRetriever...
KnowledgeRetriever name: fastgpt
KnowledgeRetriever description: Retrieve knowledge from FastGPT knowledge bases
Component KnowledgeRetriever generated successfully.
```

これにより、`components/knowledge_retriever/`ディレクトリに`fastgpt.yaml`と`fastgpt.py`ファイルが生成されます。`.yaml`ファイルはナレッジリトリーバーの基本情報と設定パラメータを定義し、`.py`ファイルはこのリトリーバーのハンドラです:

```bash
➜  FastGPTRetriever > tree
...
├── components
│   ├── __init__.py
│   └── knowledge_retriever
│       ├── __init__.py
│       ├── fastgpt.py
│       └── fastgpt.yaml
...
```

## マニフェストファイル: ナレッジリトリーバー

```yaml
apiVersion: v1  # 変更しないでください
kind: KnowledgeRetriever  # 変更しないでください
metadata:
  name: fastgpt  # ナレッジリトリーバー名、このリトリーバーを識別するために使用
  label:
    en_US: FastGPT Knowledge Base  # リトリーバー表示名、LangBotのUIに表示、多言語対応
    zh_Hans: FastGPT 知識庫
    ja_JP: FastGPT ナレッジベース
  description:
    en_US: 'Retrieve knowledge from FastGPT knowledge bases'  # リトリーバー説明、LangBotのUIに表示、多言語対応。オプション
    zh_Hans: '従 FastGPT 知識庫中検索知識'
    ja_JP: 'FastGPT ナレッジベースから知識を取得'
  icon: assets/icon.svg  # リトリーバーアイコン、外部ナレッジベース設定ページに表示
spec:
  config:  # リトリーバー設定パラメータ、ユーザーは外部ナレッジベース作成時にこれらのパラメータを入力する必要があります
    - name: api_base_url  # パラメータ名
      type: string  # パラメータタイプ: string、number、boolean、select
      label:
        en_US: API Base URL
        zh_Hans: API 基礎地址
        ja_JP: API ベース URL
      description:
        en_US: 'Base URL for FastGPT API'
        zh_Hans: 'FastGPT API 基礎地址'
        ja_JP: 'FastGPT API ベース URL'
      default: 'http://localhost:3000'  # デフォルトパラメータ値
      required: true  # 必須かどうか
    - name: api_key
      type: string
      label:
        en_US: FastGPT API Key
        zh_Hans: FastGPT API Key
        ja_JP: FastGPT API キー
      description:
        en_US: 'API key from your FastGPT instance'
        zh_Hans: '従您的 FastGPT 実例獲取的 API Key'
        ja_JP: 'FastGPT インスタンスから取得した API Key'
      default: ''
      required: true
    - name: search_mode  # select型パラメータの例
      type: select
      label:
        en_US: Search Mode
        zh_Hans: 搜索模式
        ja_JP: 検索モード
      description:
        en_US: 'The search method to use'
        zh_Hans: '使用的搜索方法'
        ja_JP: '使用する検索方法'
      default: 'embedding'
      options:  # select型パラメータはオプションリストを定義する必要があります
      - name: 'embedding'
        label:
          en_US: 'Embedding Search'
          zh_Hans: '向量搜索'
          ja_JP: '埋め込み検索'
      - name: 'fullTextRecall'
        label:
          en_US: 'Full-Text Recall'
          zh_Hans: '全文検索'
          ja_JP: '全文検索'
    - name: using_rerank  # boolean型パラメータの例
      type: boolean
      label:
        en_US: Use Re-ranking
        zh_Hans: 使用重排序
        ja_JP: リランキングを使用
      description:
        en_US: 'Whether to use re-ranking'
        zh_Hans: '是否使用重排序'
        ja_JP: 'リランキングを使用するかどうか'
      default: false
      required: false
execution:
  python:
    path: fastgpt.py  # リトリーバーハンドラ、変更しないでください
    attr: FastGPT  # リトリーバーハンドラのクラス名、fastgpt.pyのクラス名と一致
```

設定項目フォーマットのリファレンスについては、[プラグインマニフェスト設定フォーマット](https://langbot.app/docs/en/plugin/dev/basic-info.md)を参照してください。

## プラグインハンドラ

以下のコードがデフォルトで生成されます(`components/knowledge_retriever/<retriever_name>.py`)。`FastGPT`クラスの`retrieve`メソッドでナレッジ検索ロジックを実装する必要があります。完全なコードは[langbot-plugin-demo](https://github.com/langbot-app/langbot-plugin-demo)で見つけることができます。

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
...

class FastGPT(KnowledgeRetriever):

    async def retrieve(self, context: RetrievalContext) -> list[RetrievalResultEntry]:
        """FastGPTナレッジベースからナレッジを検索"""

        # 1. 設定パラメータを取得
        api_base_url = self.config.get('api_base_url', 'http://localhost:3000')
        api_key = self.config.get('api_key')
        dataset_id = self.config.get('dataset_id')
        search_mode = self.config.get('search_mode', 'embedding')
        using_rerank = self.config.get('using_rerank', False)

        # 2. パラメータ検証
        if not api_key or not dataset_id:
            logger.error("Missing required configuration: api_key or dataset_id")
            return []

        # 3. APIリクエストを構築
        url = f"{api_base_url.rstrip('/')}/api/core/dataset/searchTest"
        headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
        payload = {
            "datasetId": dataset_id,
            "text": context.query,  # RetrievalContextからクエリテキストを取得
            "searchMode": search_mode,
            "usingReRank": using_rerank,
        }

        try:
            # 4. 外部APIを呼び出す
            async with httpx.AsyncClient() as client:
                response = await client.post(url, json=payload, headers=headers, timeout=30.0)
                response.raise_for_status()
                result = response.json()

            # 5. レスポンスを解析してRetrievalResultEntryに変換
            results = []
            for record in result.get('data', []):
                # メインデータと補助データをコンテンツとして結合
                content_text = '\n'.join([
                    record.get('q', ''),
                    record.get('a', '')
                ]).strip()

                # 検索結果エントリを作成
                entry = RetrievalResultEntry(
                    id=record.get('id', ''),
                    content=[ContentElement.from_text(content_text)],
                    metadata={
                        'dataset_id': record.get('datasetId', ''),
                        'source_name': record.get('sourceName', ''),
                        'score': record.get('score', 0.0),
                    },
                    # 類似度スコアを距離に変換(スコアが高いほど距離が小さい)
                    distance=1.0 - float(record.get('score', 0.0)),
                )
                results.append(entry)

            logger.info(f"Retrieved {len(results)} chunks from FastGPT dataset {dataset_id}")
            return results

        except httpx.HTTPStatusError as e:
            logger.error(f"HTTP error from FastGPT API: {e.response.status_code} - {e.response.text}")
            return []
        except httpx.RequestError as e:
            logger.error(f"Request error when calling FastGPT API: {str(e)}")
            return []
        except Exception as e:
            traceback.print_exc()
            logger.error(f"Unexpected error during retrieval: {str(e)}")
            return []
```

### 検索コンテキスト

`RetrievalContext`にはこの検索のコンテキスト情報が含まれます:

```python
class RetrievalContext(pydantic.BaseModel):
    """ナレッジ検索コンテキスト"""

    query: str
    """クエリテキスト、ユーザーの検索質問"""
```

### 検索結果

検索結果は`RetrievalResultEntry`オブジェクトのリストに変換する必要があり、各オブジェクトは検索されたナレッジチャンクを表します:

```python
class RetrievalResultEntry(pydantic.BaseModel):
    """単一検索結果エントリ"""

    id: str
    """結果ID、このエントリを一意に識別"""

    content: list[ContentElement]
    """結果コンテンツ、ContentElement.from_text()を使用してテキストコンテンツを作成"""

    metadata: dict[str, Any]
    """結果メタデータ、ソース、スコアなど、任意のキーと値のペアを含めることができます"""

    distance: float
    """距離スコア、クエリとの関連性を示します(小さいほど関連性が高い)
    通常は1.0 - similarity_scoreとして計算されます"""
```

### 設定パラメータの取得

`self.config.get(パラメータ名, デフォルト値)`を使用して、ユーザーが設定したパラメータ値を取得します:

```python
# 文字列パラメータを取得
api_base_url = self.config.get('api_base_url', 'http://localhost:3000')

# 数値パラメータを取得
limit = self.config.get('limit', 5000)
similarity = self.config.get('similarity', 0.0)

# ブールパラメータを取得
using_rerank = self.config.get('using_rerank', False)

# selectパラメータを取得
search_mode = self.config.get('search_mode', 'embedding')
```

## 1 つの installation、複数の用途

1 つのナレッジリトリーバーは**複数のナレッジベース**から使われ、プラットフォームのストレージキー `(instance, Workspace, owner type, plugin, key)` にはナレッジベースの次元がありません：

- 検索に使うキャッシュ、インデックス、中間結果は**ナレッジベース ID** で分離し、キーにナレッジベース ID を含めてください。インスタンスに置かないでください。
- 検索のロックと「要対账」状態は `(installation, ナレッジベース)` 単位で記録してください。あるナレッジベースの検索失敗が、同じ installation の他のナレッジベースの検索を利用不能にしてはいけません。
- `RetrievalContext` は 1 回の検索でのみ有効です。インスタンスフィールドに保存して呼び出しをまたいで再利用しないでください。
- 呼び出しをまたいで保持するナレッジベースのデータは Host ストレージに置き、キーに installation の識別子とナレッジベース ID の両方を含めてください。
- installation 単位で接続、インデックス、その他のプロセス内状態をキャッシュする場合は、`on_installation_revoked(binding)` で解放してください。

完全な仕様は[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

## リトリーバーのテスト

作成後、プラグインディレクトリでコマンド`lbp run`を実行してデバッグを開始します。その後、LangBotで:

1. 「ナレッジベース」ページに移動
2. 外部ナレッジベースを追加
3. プラグインが提供するナレッジリトリーバーを選択し、設定を入力

![](https://langbot.app/docs/images/zh/plugin/dev/components/knowledge_retriever_config.png)

保存後、LangBotパイプラインでこのナレッジベースを選択できます。

---

# コンポーネント：ページ

Source: https://langbot.app/docs/ja/plugin/dev/components/page

Pageコンポーネントを使用すると、プラグインはLangBot WebUIのサイドバーにカスタムビジュアルページを登録できます。ページはiframeサンドボックス内で実行され、Page SDKを介してホストと通信し、プラグインのバックエンドAPIを呼び出すことができます。

## ユースケース

- **管理パネル**：プラグインに視覚的な設定やデータ管理インターフェースを提供（例：FAQ管理、分析ダッシュボード）
- **データ表示**：ランタイムの統計データ、ログ、チャートなどを表示
- **インタラクティブツール**：フォーム、エディタなどの対話式インターフェースを提供

![](https://langbot.app/docs/images/zh/plugin/dev/components/plugin-page-demo.png)

## ページコンポーネントの追加

プラグインディレクトリでコマンドを実行します：

```bash
lbp comp Page
```

ページ名を入力すると、`components/pages/`ディレクトリにページファイルが生成されます：

```bash
├── components
│   └── pages
│       └── dashboard
│           ├── dashboard.yaml   # ページマニフェスト
│           ├── dashboard.py     # バックエンドハンドラー
│           ├── index.html       # ページエントリポイント
│           └── i18n             # 翻訳ファイル（オプション）
│               ├── en_US.json
│               └── ja_JP.json
```

`manifest.yaml`にもコンポーネント検出設定が追加されます：

```yaml
spec:
  components:
    Page:
      fromDirs:
      - path: components/pages/
        maxDepth: 2
```

## マニフェストファイル：ページ

```yaml
apiVersion: v1  # 変更しないでください
kind: Page  # 変更しないでください
metadata:
  name: dashboard  # プラグイン内で一意のページID
  label:
    en_US: Dashboard  # WebUIサイドバーに表示される名前、多言語対応
    ja_JP: ダッシュボード
spec:
  path: index.html  # HTMLエントリファイル（このYAMLファイルからの相対パス）
execution:
  python:
    path: dashboard.py  # バックエンドハンドラーファイル
    attr: DashboardPage  # ハンドラークラス名
```

## バックエンド処理

Pageコンポーネントのバックエンドハンドラーは`Page`基底クラスを継承し、`handle_api`メソッドを実装してフロントエンドページからのAPIリクエストを処理します。

```python
from langbot_plugin.api.definition.components.page import Page, PageRequest, PageResponse


class DashboardPage(Page):

    async def handle_api(self, request: PageRequest) -> PageResponse:
        # request.endpoint: APIエンドポイントパス（例：'/stats'）
        # request.method:   HTTPメソッド（GET、POST、PUT、DELETE）
        # request.body:     リクエストボディ（解析済みJSON、またはNone）

        if request.endpoint == '/stats' and request.method == 'GET':
            # Host storage から現在の installation のデータを読む
            entries = await self.load_entries_for_current_installation()
            return PageResponse.ok({'total': len(entries)})

        return PageResponse.fail(f'不明なエンドポイント: {request.endpoint}')
```

### PageRequestフィールド

| フィールド      | 型     | 説明                                    |
| ---------- | ----- | ------------------------------------- |
| `endpoint` | `str` | APIエンドポイントパス（例：`'/entries'`）          |
| `method`   | `str` | HTTPメソッド（`GET`、`POST`、`PUT`、`DELETE`） |
| `body`     | `Any` | リクエストボディ（解析済みJSON、または`None`）          |

### PageResponseの構築

| メソッド                       | 説明                           |
| -------------------------- | ---------------------------- |
| `PageResponse.ok(data)`    | 成功レスポンス。`data`はJSON変換可能な任意の値 |
| `PageResponse.fail(error)` | エラーレスポンス。`error`はエラーメッセージ文字列 |

## フロントエンドページ開発

HTMLファイルにPage SDKを読み込んで、プラグインバックエンドと通信します：

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <style>
    body {
      background: var(--langbot-bg, #ffffff);
      color: var(--langbot-text, #0a0a0a);
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      padding: 24px;
    }
  </style>
</head>
<body>
  <h1 data-i18n="title">ダッシュボード</h1>
  <p id="stats"></p>

  <script src="/api/v1/plugins/_sdk/page-sdk.js"></script>
  <script>
    langbot.onReady(async function(ctx) {
      // バックエンドAPIを呼び出す
      var data = await langbot.api('/stats', null, 'GET');
      document.getElementById('stats').textContent = '合計: ' + data.total;
    });
  </script>
</body>
</html>
```

### Page SDK API

| メソッド                                    | 説明                                                         |
| --------------------------------------- | ---------------------------------------------------------- |
| `langbot.onReady(callback)`             | SDK準備完了時に呼ばれる。`callback`は`ctx`（`theme`と`language`を含む）を受け取る |
| `langbot.api(endpoint, body?, method?)` | プラグインの`handle_api`を呼び出す。Promiseを返す                         |
| `langbot.t(key, fallback?)`             | 翻訳文字列を取得                                                   |
| `langbot.onThemeChange(callback)`       | テーマ変更時のコールバック                                              |
| `langbot.onLanguageChange(callback)`    | 言語変更時のコールバック                                               |
| `langbot.applyI18n()`                   | `data-i18n`翻訳を手動で再適用                                       |

### ダークモード

SDKはページにCSSカスタムプロパティを自動設定します。直接使用できます：

| CSS変数                  | 用途       |
| ---------------------- | -------- |
| `--langbot-bg`         | ページ背景色   |
| `--langbot-bg-card`    | カード背景色   |
| `--langbot-text`       | メインテキスト色 |
| `--langbot-text-muted` | サブテキスト色  |
| `--langbot-border`     | ボーダー色    |
| `--langbot-accent`     | アクセント色   |

### ページi18n

ページディレクトリ内に`i18n/`ディレクトリを作成し、JSON翻訳ファイルを配置します：

```
pages/dashboard/
├── index.html
└── i18n/
    ├── en_US.json
    └── ja_JP.json
```

翻訳ファイルはフラットなJSONキーバリューペアです：

```json
{
  "title": "ダッシュボード",
  "totalEntries": "エントリ数"
}
```

HTML要素に`data-i18n`属性を追加すると、SDKが自動的にテキストを翻訳します：

```html
<h1 data-i18n="title">Dashboard</h1>
```

## 完全な例：FAQ管理ページ

FAQエントリのCRUD操作を実装した完全なPageコンポーネントの例です。

**バックエンドハンドラー**（`components/pages/manager/manager.py`）：

```python
from langbot_plugin.api.definition.components.page import Page, PageRequest, PageResponse


class ManagerPage(Page):

    async def handle_api(self, request: PageRequest) -> PageResponse:
        if request.endpoint == '/entries' and request.method == 'GET':
            entries = await self.load_entries_for_current_installation()
            return PageResponse.ok({'entries': entries})

        if request.endpoint == '/entries' and request.method == 'POST':
            question = (request.body or {}).get('question', '').strip()
            answer = (request.body or {}).get('answer', '').strip()
            if not question or not answer:
                return PageResponse.fail('質問と回答は必須です')
            entry = {'question': question, 'answer': answer}
            await self.save_entry_for_current_installation(entry)
            return PageResponse.ok({'entry': entry})

        if request.endpoint == '/entries' and request.method == 'DELETE':
            entry_id = (request.body or {}).get('id', '')
            if await self.delete_entry_for_current_installation(entry_id):
                return PageResponse.ok({'deleted': entry_id})
            return PageResponse.fail('エントリが見つかりません')

        return PageResponse.fail(f'不明: {request.method} {request.endpoint}')
```

**フロントエンドページ**（`components/pages/manager/index.html`）では`langbot.api()`でバックエンドを呼び出します：

```javascript
// エントリを読み込む
var data = await langbot.api('/entries', null, 'GET');

// エントリを追加
await langbot.api('/entries', { question: '...', answer: '...' }, 'POST');

// エントリを削除
await langbot.api('/entries', { id: '...' }, 'DELETE');
```

完全なサンプルコードは[FAQManagerプラグイン](https://github.com/langbot-app/langbot-plugin-demo/tree/main/FAQManager)を参照してください。

## 1 つの installation、複数の用途

同じ Page は**複数のページリクエスト**から呼び出されます（同じ installation の別々のリクエスト、別々の Workspace）：

- 前回のリクエストのデータをインスタンスに残さないでください。エンドポイント、メソッド、body、現在の installation の情報は、毎回現在の `PageRequest` / binding から取得します。
- ページのデータは常に installation スコープの Host ストレージに置いてください。`self.plugin` はプロセスレベルの共有オブジェクトであり、テナントデータを保存できません。
- 別々の Workspace のリクエストは同じ Page インスタンスを共有するため、インスタンスフィールドの使用が交錯します。リクエストをまたいで保持するデータは Host ストレージに置いてください。
- installation 単位でプロセス内キャッシュを保持する場合は、`on_installation_revoked(binding)` で解放してください。

完全な仕様は[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

## 注意事項

- ページは`sandbox="allow-scripts allow-forms"`のiframe内で実行され、ポップアップを開いたり親ページをナビゲートすることはできません
- 認証 Page のテナントデータは installation-scoped Host storage に保存します。`self.plugin` はプロセス全体で共有されるため、テナントのエントリを保持してはいけません。上記 helper 名は説明用です。現在の SDK Host storage API を使用してください。
- `PageResponse.ok()`と`PageResponse.fail()`を使用してレスポンスを構築し、一貫したフォーマットを確保してください
- Page SDKの`<script>`タグは、`langbot`オブジェクトを使用するコードの前に配置する必要があります

---

# コンポーネント: パーサー

Source: https://langbot.app/docs/ja/plugin/dev/components/parser

パーサー（Parser）コンポーネントにより、プラグインはLangBotにドキュメント解析機能を提供できます。ユーザーがナレッジベースにドキュメントをアップロードする際、LangBotはRAGエンジンの`ingest`ステップの前にパーサーを呼び出し、PDF、Word、Markdownなどのバイナリファイルから構造化テキストを抽出します。

ParserとKnowledgeEngineの関係:

- **Parser** はファイルをテキストに変換する役割（file → text）
- **KnowledgeEngine** はテキストのインデックス作成と検索を行う役割（text → chunks → vectors）

RAGエンジン自体がドキュメント解析機能を持っている場合（`DOC_PARSING`能力を宣言）、ユーザーはRAGエンジンの内蔵解析機能を使用するか、外部Parserプラグインを使用するかを選択できます。

## パーサーコンポーネントの追加

1つのプラグインには任意の数のパーサーを追加できます。プラグインディレクトリでコマンド`lbp comp Parser`を実行し、プロンプトに従ってパーサーの設定を入力します。

```bash
➜  MyParserPlugin > lbp comp Parser
Generating component Parser...
Parser name: pdf_parser
Parser description: A PDF document parser
Component Parser generated successfully.
組件 Parser 生成成功。
```

これにより、`components/parser/`ディレクトリに`pdf_parser.yaml`と`pdf_parser.py`ファイルが生成されます。`.yaml`ファイルはパーサーの基本情報とサポートするMIMEタイプを定義し、`.py`ファイルはこのパーサーのハンドラです:

```bash
➜  MyParserPlugin > tree
...
├── components
│   ├── __init__.py
│   └── parser
│       ├── __init__.py
│       ├── pdf_parser.py
│       └── pdf_parser.yaml
...
```

## マニフェストファイル: パーサー

```yaml
apiVersion: v1  # 変更しないでください
kind: Parser  # 変更しないでください
metadata:
  name: pdf_parser  # パーサー名、このパーサーを識別するために使用
  label:
    en_US: PDF Parser  # パーサー表示名、LangBotのUIに表示、多言語対応
    zh_Hans: PDF 解析器
  description:
    en_US: 'A PDF document parser'
    zh_Hans: 'PDF 文档解析器'
spec:
  supported_mime_types:  # サポートするファイルのMIMEタイプを宣言
    - application/pdf
execution:
  python:
    path: pdf_parser.py  # パーサーハンドラ、変更しないでください
    attr: PdfParser  # パーサーハンドラのクラス名、pdf_parser.pyのクラス名と一致
```

### supported\_mime\_types

`supported_mime_types`はこのパーサーがサポートするファイルタイプを宣言します。一般的なMIMEタイプ:

| MIMEタイプ                                                                   | 説明                |
| ------------------------------------------------------------------------- | ----------------- |
| `application/pdf`                                                         | PDFドキュメント         |
| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | Wordドキュメント（.docx） |
| `text/markdown`                                                           | Markdownファイル      |
| `text/plain`                                                              | プレーンテキストファイル      |
| `text/html`                                                               | HTMLファイル          |

## プラグインハンドラ

以下のコードがデフォルトで生成されます（`components/parser/<パーサー名>.py`）。`parse`メソッドを実装する必要があります。

```python
from langbot_plugin.api.definition.components.parser.parser import Parser
from langbot_plugin.api.entities.builtin.rag.models import (
    ParseContext,
    ParseResult,
    TextSection,
)


class PdfParser(Parser):
    """ファイルからテキストを抽出するパーサーコンポーネント。"""

    async def parse(self, context: ParseContext) -> ParseResult:
        """ファイルを解析して構造化テキストを抽出。

        Args:
            context: file_content（bytes）、mime_type、filename、metadataを含む。

        Returns:
            抽出されたテキストとオプションの構造化セクションを含むParseResult。
        """
        # TODO: 解析ロジックを実装
        text = context.file_content.decode("utf-8", errors="replace")

        return ParseResult(
            text=text,
            sections=[
                TextSection(
                    content=text,
                    heading=context.filename,
                    level=0,
                ),
            ],
            metadata={
                "filename": context.filename,
                "mime_type": context.mime_type,
            },
        )
```

### 解析メソッド

`parse`メソッドは、ドキュメントがナレッジベースにアップロードされた時（RAGエンジンの取り込み前）に呼び出されます:

```python
async def parse(self, context: ParseContext) -> ParseResult:
```

**ParseContext**には以下の情報が含まれます:

```python
class ParseContext(pydantic.BaseModel):
    file_content: bytes          # 生のファイルバイト（LangBotがストレージから読み取り）
    mime_type: str               # 検出されたファイルのMIMEタイプ
    filename: str                # 元のファイル名
    metadata: dict[str, Any]     # FileObjectからの追加メタデータ
```

**ParseResult**は解析結果を返す必要があります:

```python
class ParseResult(pydantic.BaseModel):
    text: str                            # 抽出された完全なプレーンテキスト
    sections: list[TextSection] = []     # 構造化セクション（オプション）
    metadata: dict[str, Any] = {}        # 解析メタデータ（例: page_count, language）
```

**TextSection**はドキュメントから抽出されたテキストのセクションを表します:

```python
class TextSection(pydantic.BaseModel):
    content: str                   # セクションのテキスト内容
    heading: str | None = None     # セクション見出し
    level: int = 0                 # ネストレベル
    page: int | None = None        # ソースページ番号（PDFなど）
    metadata: dict[str, Any] = {}  # 追加セクションメタデータ
```

## KnowledgeEngineとの連携

ユーザーがドキュメントをアップロードする際、LangBotは以下のロジックで解析フローを決定します:

- ユーザーが外部Parserプラグインを選択した場合、LangBotはまずParserの`parse`メソッドを呼び出し、その結果を`IngestionContext.parsed_content`を通じてRAGエンジンの`ingest`メソッドに渡します。
- RAGエンジンが`DOC_PARSING`能力を宣言しており、ユーザーが外部パーサーを選択していない場合、RAGエンジンが自身でドキュメント解析を処理します。

KnowledgeEngineは`IngestionContext.parsed_content`をチェックして、事前解析されたコンテンツが利用可能かどうかを判断できます:

```python
async def ingest(self, context: IngestionContext) -> IngestionResult:
    if context.parsed_content:
        # 外部Parserの解析結果を使用
        text = context.parsed_content.text
        sections = context.parsed_content.sections
    else:
        # ドキュメントを内部で解析
        file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)
        text = file_bytes.decode('utf-8')
    ...
```

## クロスプラグインパーサー呼び出し

他のプラグインが提供するパーサーを呼び出す前に、`self.plugin.list_parsers` を使ってホスト上で現在利用可能なパーサーを列挙できます:

```python
parsers = await self.plugin.list_parsers(mime_type="application/pdf")
# 各要素には plugin_id、plugin_author、plugin_name、name、description、supported_mime_types が含まれます
```

空配列が返る場合、その MIME タイプに対応する接続済みの Parser プラグインは現在存在しません。

`plugin_author` と `plugin_name` を取得したら、`self.plugin.invoke_parser` で対象のパーサーを呼び出せます:

```python
parser = parsers[0]
result = await self.plugin.invoke_parser(
    plugin_author=parser["plugin_author"],
    plugin_name=parser["plugin_name"],
    storage_path=context.file_object.storage_path,
    mime_type=context.file_object.metadata.mime_type,
    filename=context.file_object.metadata.filename,
    metadata={},
)
# resultはtext、sections、metadataを含むdict
```

## 1 つの installation、複数の用途

1 つの Parser は**複数のナレッジベース**から使われます（同じ installation の別々のナレッジベースが異なる MIME タイプのファイルをアップロードします）。プラットフォームのストレージキーにはナレッジベースの次元がありません：

- 解析キャッシュと一時ファイルは**ナレッジベース ID** で分離し、キーにナレッジベース ID を含めてください。インスタンスにキャッシュしないでください。
- `ParseContext` と解析の中間結果は 1 回の解析でのみ有効です。インスタンスフィールドやモジュールレベルの変数に保存しないでください。
- 解析の失敗が影響するのは現在のナレッジベースのそのアップロードだけです。他のナレッジベースの解析を利用不能にしてはいけません。
- installation 単位でモデル、パーサー、一時ディレクトリをキャッシュする場合は、`on_installation_revoked(binding)` で解放し、一時ファイルを確実に削除できるようにしてください。

完全な仕様は[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

## パーサーのテスト

作成後、プラグインディレクトリでコマンド`lbp run`を実行してデバッグを開始します。その後、LangBotで:

1. 「ナレッジベース」ページに移動
2. ナレッジベースを選択してドキュメント管理に入る
3. ファイルのアップロード時、パーサーセレクターでプラグインが提供するパーサーを選択
4. アップロード後、ドキュメントが正しく取り込まれたことを確認

---

# コンポーネント: Runner

Source: https://langbot.app/docs/ja/plugin/dev/components/runner

Runner は Agent の実行ロジック、または「プラグインプロセッサー」用のイベント処理関数を実装するコンポーネントです。どちらも `RunnerContext` を受け取り、インストール後にユーザーがコンポーネントを選択・設定します。

環境の準備は[プラグイン開発チュートリアル](https://langbot.app/docs/ja/plugin/dev/tutor.md)を参照してください。

`RunnerContext` の完全なフィールドとメソッドは[コンテキスト API](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md#runner)を参照してください。

## Runner コンポーネントの追加

1 つのプラグインに複数のイベントプロセッサーを追加できます。プラグインのディレクトリで `lbp comp Runner` を実行し、名前に `welcome`、説明に `Welcome new members` を入力します。

```bash
lbp comp Runner
```

生成される `components/runner/welcome.yaml` はコンポーネントを定義するファイルで、`welcome.py` に処理を記述します。

## 実行ロジックの実装

モデルの接続や独自の実行ループには `spec.usages: [agent]` を宣言し、`run(ctx)` から結果を返します：

```python
from langbot_plugin.api.definition.components.runner import Runner, RunnerContext, RunnerResult
from langbot_plugin.api.entities.builtin.provider.message import Message


class Echo(Runner):
    async def run(self, ctx: RunnerContext):
        yield RunnerResult.run_completed(
            ctx.run_id,
            message=Message(role="assistant", content=ctx.input.to_text()),
        )
```

## マニフェストファイル: Runner

`welcome.yaml` を次の内容に変更します。

```yaml
apiVersion: langbot/v1
kind: Runner
metadata:
  name: welcome
  label:
    en_US: Welcome members
    zh_Hans: 欢迎新成员
    ja_JP: 新しいメンバーを歓迎
  description:
    en_US: Welcome new members and respond to /hello.
    zh_Hans: 欢迎新成员，并响应 /hello 消息。
    ja_JP: 新しいメンバーを歓迎し、/hello に返信します。
spec:
  usages: [event]
  events:
    - group.member_joined
    - message.received
  capabilities:
    tool_calling: true
  permissions:
    tools: [detail, call]
  config:
    - name: greeting
      type: string
      label:
        en_US: Greeting
        zh_Hans: 欢迎语
        ja_JP: 歓迎メッセージ
      required: true
      default: Welcome aboard!
    - name: reply_enabled
      type: boolean
      label:
        en_US: Send replies
        zh_Hans: 发送回复
        ja_JP: 返信する
      default: true
execution:
  python:
    path: ./welcome.py
    attr: Welcome
```

`spec.events` は対応するイベント、`spec.config` は詳細画面でユーザーが変更できる設定です。この例ではメンバー参加とメッセージ受信に対応し、歓迎メッセージと返信の有効・無効を設定できます。返信には、上記の `tool_calling` と `permissions.tools` の指定が必要です。

`spec.usages` は必須で、デフォルト値はありません。`spec.usages` は選択先を指定します。`agent` は Agent とパイプライン、`event` はプラグインプロセッサーです。`[agent, event]` の併記も可能です。`event` には `spec.events` が必要です。以下はイベント処理関数の例です。独自の `run(ctx)` から `await super().run(ctx)` で呼び出すこともできます。

## プラグインの実装

`Welcome` クラスの `initialize` メソッド内で処理関数を登録します。`welcome.py` を次の内容に変更してください。

```python
from langbot_plugin.api.definition.components.runner import (
    Runner,
    RunnerContext,
)
from langbot_plugin.api.entities.builtin.platform.events import (
    MemberJoinedEvent,
    MessageReceivedEvent,
)
from langbot_plugin.api.entities.builtin.platform.message import Plain


class Welcome(Runner):
    async def initialize(self):
        await super().initialize()

        @self.handler(MemberJoinedEvent)
        async def on_join(ctx: RunnerContext):
            name = ctx.platform_event.member.nickname or str(ctx.platform_event.member.id)
            await ctx.log(f"Member joined: {name}")
            if not ctx.config.get("reply_enabled", True):
                await ctx.log("Replies are disabled for this processor")
                return
            greeting = ctx.config.get("greeting", "Welcome aboard!")
            await ctx.reply(f"{name}, {greeting}")
            await ctx.log("Welcome action completed")

        @self.handler(MessageReceivedEvent)
        async def on_message(ctx: RunnerContext):
            text = "".join(
                item.text for item in ctx.platform_event.message_chain if isinstance(item, Plain)
            ).strip()
            if text != "/hello":
                await ctx.log("Message ignored: expected /hello")
                return
            if ctx.config.get("reply_enabled", True):
                await ctx.reply(ctx.config.get("greeting", "Welcome aboard!"))
            else:
                await ctx.log("Replies are disabled for this processor")
```

`on_join` は参加したメンバーに挨拶し、`on_message` は `/hello` に返信します。「返信する」を無効にすると、ログだけを記録します。

`ctx.platform_event` は現在のイベント、`ctx.config` はこのプロセッサーの設定です。返信には `ctx.reply()`、ログの記録には `ctx.log()` を使います。関数の実行が終わると、イベントの処理も終了します。

## ストリーミング返信

`ctx.reply_stream()` で同じ返信を更新します。`update(text)` には、その時点の全文を渡します。

```python
async with ctx.reply_stream() as reply:
    await reply.update("処理中…")
    await reply.update("完了しました。")
```

`async with` ブロックが正常終了すると返信が完了します。ストリーミングが未対応・無効の場合やメッセージ以外のイベントでは、最後に全文を一度だけ送信します。例外時には、バッファ内の未完成テキストを送信しません。デバッグでは送信をシミュレーションします。

## イベントの登録

`@self.handler(イベントクラス)` で処理関数を登録し、対応する識別子を `spec.events` に追加します。例えば `MemberJoinedEvent` は `group.member_joined` に対応します。

| イベント            | マニフェストの識別子                | SDK のイベントクラス                 |
| --------------- | ------------------------- | ---------------------------- |
| メッセージ受信         | `message.received`        | `MessageReceivedEvent`       |
| メッセージ編集         | `message.edited`          | `MessageEditedEvent`         |
| メッセージ削除         | `message.deleted`         | `MessageDeletedEvent`        |
| メッセージへのリアクション   | `message.reaction`        | `MessageReactionEvent`       |
| フィードバック受信       | `feedback.received`       | `FeedbackReceivedEvent`      |
| メンバー参加          | `group.member_joined`     | `MemberJoinedEvent`          |
| メンバー退出          | `group.member_left`       | `MemberLeftEvent`            |
| メンバーのミュート       | `group.member_banned`     | `MemberBannedEvent`          |
| グループ情報更新        | `group.info_updated`      | `GroupInfoUpdatedEvent`      |
| 友達申請受信          | `friend.request_received` | `FriendRequestReceivedEvent` |
| 友達追加            | `friend.added`            | `FriendAddedEvent`           |
| 友達削除            | `friend.removed`          | `FriendRemovedEvent`         |
| Bot のグループ招待     | `bot.invited_to_group`    | `BotInvitedToGroupEvent`     |
| Bot のグループからの削除  | `bot.removed_from_group`  | `BotRemovedFromGroupEvent`   |
| Bot のミュート       | `bot.muted`               | `BotMutedEvent`              |
| Bot のミュート解除     | `bot.unmuted`             | `BotUnmutedEvent`            |
| プラットフォーム固有のイベント | `platform.specific`       | `PlatformSpecificEvent`      |

利用できるイベントとフィールドは、SDK の [events.py](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/api/entities/builtin/platform/events.py)を参照してください。対応イベントはプラットフォームによって異なります。

## イベントプロセッサーのテスト

[プラグイン開発チュートリアル](https://langbot.app/docs/ja/plugin/dev/tutor.md)に従ってデバッグ接続を設定し、プラグインのディレクトリで `lbp run` を実行します。LangBot で次の操作を行ってください。

1. 「プラグインプロセッサー」を作成し、詳細画面で「新しいメンバーを歓迎」を選び、設定を保存します。
2. 左側でメンバー参加を選択し、ニックネーム、メンバー ID、グループ ID を入力してテストを実行します。
3. 返信とログを確認します。メッセージ受信を選んで `/hello` を入力すると、返信のテストもできます。

デバッグ中の返信は Mock で再現され、実際のメッセージは送信されません。コンポーネントの YAML を変更したら `lbp run` を再起動してください。

インストール後、ボット詳細の「プラグインプロセッサー」でこの設定を追加して保存します。この画面でコンポーネントを選択し、設定を入力して新規作成・紐付けすることもできます。宣言されたイベントは自動で配信され、イベントごとのルート設定は不要です。

プラグインの購読は Agent／パイプラインのルートと独立して実行されます。同じイベントを複数のプロセッサーが処理でき、一つが失敗しても他の実行を妨げません。同じ設定を使用するボットは設定内容と実行状態を共有します。個別に設定する場合は、新しい設定を作成してください。返信などの任意の動作はコンポーネントの設定として提供し、重複返信を避けてください。

## 1 つの installation、複数の用途

1 つの Workspace でプラグインをインストールできるのは 1 回ですが、その installation は**複数のプロセッサ**（Agent / パイプライン）から再利用されます。Runner はプロセッサ間でデータが混ざらないよう自分で保証する必要があります：

- `ctx.state.*` はすでにプロセッサ単位で分離されています。スコープに `binding_identity`（Agent UUID 由来）が含まれるため、同じ installation の別プロセッサが互いを上書きしません。
- プラットフォームのストレージキーは `(instance, Workspace, owner type, plugin, key)` で、**プロセッサの次元を含みません**。したがって自分で Host ストレージやキャッシュに書くキーには、プロセッサまたは会話の識別子も含めてください。
- `RunnerContext`（`ctx`）は 1 回の実行でのみ有効です。インスタンスに保存して呼び出しをまたいで再利用しないでください。呼び出しをまたいで保持する会話状態は `ctx.state_get()` / `ctx.state_set()` を使います。
- 複数のプロセッサは同じ Runner インスタンスを共有するため、現在の実行のデータをインスタンスフィールドに蓄積しないでください。長期常駐の外部セッションプロセスのように、プロセス内に呼び出しをまたぐ状態を持つ必要がある Runner は、共有実行を宣言せず専用のままにしてください。
- installation 単位でプロセス内キャッシュを保持する場合は、`on_installation_revoked(binding)` で解放してください。

完全な仕様は[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

## 次のステップ

- [`RunnerContext` API リファレンス](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md#runner)を確認します。
- モデル、ツール、ナレッジベース、ストレージについては [LangBot API](https://langbot.app/docs/ja/plugin/dev/apis/common.md)を確認します。
- メッセージ送信などについては[プラットフォーム API](https://langbot.app/docs/ja/plugin/dev/apis/platform.md)を確認します。
- [RunnerDemo](https://github.com/langbot-app/langbot-plugin-demo/tree/main/Runner/RunnerDemo)で他の実装例を確認できます。
- パイプラインの前処理やモデル呼び出し完了時などに機能を追加する場合は、[イベントリスナー](https://langbot.app/docs/ja/plugin/dev/components/event-listener.md)を使用してください。

---

# コンポーネント: Tool

Source: https://langbot.app/docs/ja/plugin/dev/components/tool

LangBotの組み込みLocal Agentは、実行中にツールを呼び出して外部世界と対話します。現在、プラグインとMCPの両方を通じてツールを追加することがサポートされています。

## Toolコンポーネントの追加

1つのプラグインには任意の数のツールを含めることができます。プラグインディレクトリでコマンド`lbp comp Tool`を実行し、プロンプトに従ってツール設定を入力します。

```bash
➜  HelloPlugin > lbp comp Tool
Generating component Tool...
Tool name: get_weather_alerts
Tool description: Get weather alerts for a US state.
Component Tool generated successfully.
組件 Tool 生成成功。
```

これにより、`components/tools/`ディレクトリに`get_weather_alerts.yaml`と`get_weather_alerts.py`ファイルが生成されます。`.yaml`ファイルはツールの基本情報を定義し、`.py`ファイルはツールハンドラです:

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   └── tools
│       ├── __init__.py
│       ├── get_weather_alerts.py
│       └── get_weather_alerts.yaml
...
```

## マニフェストファイル: Tool

```yaml
apiVersion: v1  # 変更しないでください
kind: Tool  # 変更しないでください
metadata:
  name: get_weather_alerts  # ツール名、LLM認識用
  label:
    en_US: GetWeatherAlerts  # ツール表示名、LangBot UIに表示、多言語対応
    zh_Hans: GetWeatherAlerts
  description:
    en_US: 'Get weather alerts for a US state.'  # ツール説明、LangBot UIに表示、多言語対応。オプション
    zh_Hans: '獲取美国某个州的天気預警'
spec:
  parameters: []  # ツールパラメータ、会話コンテキストに基づいてLLMが生成する値
  llm_prompt: 'Get weather alerts for a US state.'  # ツールプロンプト、LLMがこのツールを呼び出すかどうかを判断するため
execution:
  python:
    path: get_weather_alerts.py  # ツールハンドラ、変更しないでください
    attr: GetWeatherAlerts  # ツールハンドラクラス名、get_weather_alerts.pyのクラス名と一致
```

## プラグイン処理

以下のコードがデフォルトで生成されます(`components/tools/<tool_name>.py`)。`GetWeatherAlerts`クラスの`call`メソッドでこのツールの呼び出しと戻り値のロジックを実装する必要があります。

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from typing import Any

from langbot_plugin.api.definition.components.tool.tool import Tool
from langbot_plugin.api.entities.builtin.provider import session as provider_session


class GetWeatherAlerts(Tool):

    async def call(self, params: dict[str, Any], session: provider_session.Session, query_id: int) -> str:
        """Fill your tool code here"""
        return {}
```

`call`メソッドでこのツールを実装します:

> info:
>
> 天気検索ツールの例は、MCPの[サーバー作成例](https://modelcontextprotocol.io/quickstart/server)から来ています。

```python
from __future__ import annotations

from typing import Any

from langbot_plugin.api.definition.components.tool.tool import Tool
from langbot_plugin.api.entities.builtin.provider import session as provider_session
import httpx

# 定数
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"


async def make_nws_request(url: str) -> dict[str, Any] | None:
    """適切なエラー処理を使用してNWS APIにリクエストを行う。"""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """アラート機能を読みやすい文字列にフォーマットする。"""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

class GetWeatherAlerts(Tool):

    async def call(self, params: dict[str, Any], session: provider_session.Session, query_id: int) -> str:
        """Fill your tool code here"""
        state = params.get("state", "CA")

        url = f"{NWS_API_BASE}/alerts/active/area/{state}"
        data = await make_nws_request(url)

        if not data or "features" not in data:
            return "Unable to fetch alerts or no alerts found."

        if not data["features"]:
            return "No active alerts for this state."

        alerts = [format_alert(feature) for feature in data["features"]]
        return "\n---\n".join(alerts)
```

このツールでは、`params`から`state`パラメータを取得し、NWS APIを呼び出してその州の天気アラートを取得する必要があるため、マニフェストファイルの`parameters`で`state`パラメータを定義する必要があります。

`parameters`フォーマットは[JSON Schema](https://json-schema.org/docs)に従い、[OpenAI Function Calling機能](https://platform.openai.com/docs/guides/function-calling#defining-functions)でサポートされており、そのルートタイプは`type: object`に固定されています。`properties`にパラメータを追加し、`required`に必須パラメータの説明を追加してください。

```yaml
...
spec:
  parameters:
    type: object  # 変更しないでください
    properties:  # 変更しないでください、ここにパラメータを追加
      state:
        type: string
        description: 'Two-letter US state code (e.g. CA, NY)'
    required:  # ここに必須パラメータの説明を追加
      - state
...
```

このツールは`httpx`ライブラリも使用しているため、プラグインディレクトリの`requirements.txt`に`httpx`依存関係を追加する必要があります。

```txt
# HelloPlugin/requirements.txt
langbot-plugin  # デフォルトで既に存在
httpx
```

次に、プラグインディレクトリでコマンド`lbp run`を実行してデバッグを開始します。LangBotでツール呼び出しをサポートするモデルを設定し、対応するパイプラインでそのモデルの使用を選択してこのツールを使用します。

![](https://langbot.app/docs/images/zh/plugin/dev/components/tool_use_in_chat.png)

## 1 つの installation、複数の用途

1 つの Tool は**複数のプロセッサと会話**から呼び出されます（1 つのイベントで複数のプラグインプロセッサが起動し得ます）：

- 設定は呼び出しごとに読み取ってください（`self.get_plugin_config()` または `ctx.config`）。`initialize()` で読み取ってインスタンスにキャッシュしないでください。
- 呼び出し引数、戻り値、会話データをインスタンスフィールドやモジュールレベルの変数に残さないでください。会話の識別子は現在の呼び出しの `session` / `query_id` から取得します。
- 同時呼び出しは同じインスタンスを共有するため、インスタンスフィールドは書き込みが交錯します。呼び出しをまたいで保持するデータは Host ストレージに置き、対応するプロセッサまたは会話の識別子をキーに含めてください。
- installation 単位でプロセス内キャッシュを保持する場合は、`on_installation_revoked(binding)` で解放してください。

完全な仕様は[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

## 次のステップ

ツールの基本的な使い方を学びました。次は:

- Tool が受け取る [`session` と `query_id`](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md#tool)を確認します。
- [LangBot API](https://langbot.app/docs/ja/plugin/dev/apis/common.md)を確認します。

---

# プラグインディレクトリ構造

Source: https://langbot.app/docs/ja/plugin/dev/directory-structure

このドキュメントでは、LangBotプラグインの標準ディレクトリ構造とファイル組織仕様を紹介し、開発者が準拠したプラグインを作成できるように支援します。

## 基本ディレクトリ構造

標準的なLangBotプラグインは次のディレクトリ構造に従う必要があります:

```
MyPlugin/
├── manifest.yaml          # プラグインマニフェストファイル(必須)
├── main.py               # プラグインメインエントリファイル(必須)
├── README.md             # 英語プラグインドキュメント(必須)
├── readme/               # 多言語READMEディレクトリ(オプション)
│   ├── README_zh_Hans.md # 簡体字中国語ドキュメント
│   ├── README_ja_JP.md   # 日本語ドキュメント
│   └── README_zh_Hant.md # 繁体字中国語ドキュメント(オプション)
├── assets/               # リソースファイルディレクトリ
│   ├── icon.svg         # プラグインアイコン(推奨)
│   └── ...              # その他のリソースファイル
├── components/           # コンポーネントディレクトリ
│   ├── event_listener/  # イベントリスナーコンポーネント
│   ├── commands/        # コマンドコンポーネント
│   └── tools/           # ツールコンポーネント
├── requirements.txt      # Python依存関係(オプション)
└── config/              # 設定ディレクトリ(オプション)
```

## 多言語README仕様

### ファイル配置仕様

LangBotプラグインは、異なる言語のユーザーにローカライズされたプラグイン説明を提供するために、多言語READMEドキュメントをサポートしています。

**重要な仕様:**

1. **`ルートREADME.md(必須)`**
   - **英語**で記述する必要があります
   - プラグインのデフォルトドキュメントとして機能します
   - 要求された言語バージョンが存在しない場合のフォールバックとして使用されます
2. **`readme/ディレクトリ(オプション)`**
   - **非英語**のREADMEドキュメントを保存するために使用
   - ファイル命名形式: `README_{言語コード}.md`

### サポートされる言語コード

[RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646)標準に従い、LangBotは現在次の言語コードをサポートしています:

| 言語     | 言語コード          | ファイル名               | 配置場所               |
| ------ | -------------- | ------------------- | ------------------ |
| 英語     | `en`または`en_US` | `README.md`         | **プラグインルートディレクトリ** |
| 簡体字中国語 | `zh_Hans`      | `README_zh_Hans.md` | `readme/`ディレクトリ    |
| 繁体字中国語 | `zh_Hant`      | `README_zh_Hant.md` | `readme/`ディレクトリ    |
| 日本語    | `ja_JP`        | `README_ja_JP.md`   | `readme/`ディレクトリ    |
| ベトナム語  | `vi_VN`        | `README_vi_VN.md`   | `readme/`ディレクトリ    |
| タイ語    | `th_TH`        | `README_th_TH.md`   | `readme/`ディレクトリ    |
| スペイン語  | `es_ES`        | `README_es_ES.md`   | `readme/`ディレクトリ    |

### ディレクトリ構造の例

```
MyPlugin/
├── README.md                    # ✅ 英語版(必須、ルートディレクトリ)
└── readme/                      # ✅ 多言語ディレクトリ
    ├── README_zh_Hans.md       # ✅ 簡体字中国語
    ├── README_ja_JP.md         # ✅ 日本語
    └── README_zh_Hant.md       # ✅ 繁体字中国語
```

### 誤った例

❌ **誤り: readme/ディレクトリに英語READMEを配置**

```
MyPlugin/
├── readme/
│   ├── README_en.md        # ❌ 誤り: 英語はreadme/に配置すべきではない
│   └── README_zh_Hans.md
```

❌ **誤り: ルートREADME.mdに非英語コンテンツが含まれる**

```markdown
# MyPlugin

This is a plugin...

これはプラグインです...    # ❌ 誤り: ルートREADME.mdは英語のみを含むべき
```

### README言語フォールバックロジック

ユーザーが特定の言語でREADMEを要求した場合、LangBotは次の順序で検索します:

1. `readme/README_{言語コード}.md`を読み取ろうとします
2. 見つからない場合は、ルート`README.md`(英語版)にフォールバックします

**例:**

- ユーザーが簡体字中国語(`zh_Hans`)を要求
  - → `readme/README_zh_Hans.md`を検索
  - → 見つからない場合は、`README.md`(英語版)を返します
- ユーザーが日本語(`ja_JP`)を要求
  - → `readme/README_ja_JP.md`を検索
  - → 見つからない場合は、`README.md`(英語版)を返します

## リソースファイルディレクトリ

### assets/ディレクトリ

`assets/`ディレクトリはプラグインの静的リソースファイルを保存するために使用されます。

**推奨構造:**

```
assets/
├── icon.svg              # プラグインアイコン(SVG形式推奨)
├── example.png           # 例画像
├── screenshot1.png       # スクリーンショット
└── logo.png             # ロゴ画像
```

**アイコン仕様:**

- プラグインアイコンとして`icon.svg`を使用することを推奨
- サポートされる形式: `.svg`、`.png`、`.jpg`、`.jpeg`、`.gif`
- 推奨サイズ: 最低256x256ピクセル
- `manifest.yaml`での参照: `icon: assets/icon.svg`

### READMEでのリソース参照

READMEドキュメントで相対パスを使用してassets/ディレクトリの画像を参照できます:

```markdown
# MyPlugin

![例](./assets/example.png)

![スクリーンショット](./assets/screenshot1.png)
```

**注意:** プラグインをLangBot Spaceにアップロードすると、リソースファイルが自動的に処理およびホストされ、ユーザーがREADMEを表示したときに画像が正しく表示されます。

## コンポーネントディレクトリ

プラグイン機能はコンポーネントを通じて実装され、タイプ別に`components/`ディレクトリに整理する必要があります:

```
components/
├── event_listener/       # イベントリスナー
│   ├── on_message.py
│   └── on_message.yaml
├── commands/            # コマンド
│   ├── hello.py
│   └── hello.yaml
└── tools/               # ツール
    ├── search.py
    └── search.yaml
```

コンポーネント開発の詳細な仕様については、[コンポーネントの追加](https://langbot.app/docs/en/plugin/dev/components/add.md)を参照してください。

## 設定ファイル

### manifest.yaml

プラグインマニフェストファイル`manifest.yaml`はコア設定ファイルであり、プラグインメタデータ、設定項目、コンポーネントリストなどの情報が含まれます。

詳細な手順については、[プラグイン設定情報の完成](https://langbot.app/docs/en/plugin/dev/basic-info.md)を参照してください。

### requirements.txt

プラグインが追加のPython依存関係を必要とする場合は、ルートディレクトリに`requirements.txt`ファイルを作成します:

```
requests>=2.28.0
beautifulsoup4>=4.11.0
pillow>=9.0.0
```

**注意:** LangBotは、プラグインのインストール時に`requirements.txt`にリストされている依存関係を自動的にインストールします。

## 関連ドキュメント

- [基本チュートリアル](https://langbot.app/docs/en/plugin/dev/tutor.md) - 最初のプラグインを作成する方法を学ぶ
- [プラグイン設定情報の完成](https://langbot.app/docs/en/plugin/dev/basic-info.md) - manifest.yamlの設定
- [コンポーネントの追加](https://langbot.app/docs/en/plugin/dev/components/add.md) - プラグインコンポーネントの開発
- [マーケットプレイスに公開](https://langbot.app/docs/en/plugin/dev/publish/market.md) - プラグインを配布

---

# 移行ガイド

Source: https://langbot.app/docs/ja/plugin/dev/migration

このチュートリアルでは特定の考慮事項を強調しています。まず現在のバージョンのプラグインチュートリアルをお読みいただき、その後このドキュメントをプラグイン移行のリファレンスとしてご使用ください。

## 3.xサポートの非同期プラグインからの移行

> プラグインの特徴::
>
> - 主な期間: 2024.2 \~ 2025.8
> - 登録方法: `main.py`のプラグインクラスで`@handler`デコレータを使用してイベントリスナーを登録し、`@llm_func`デコレータを使用してコンテンツ関数(ツール)を登録; すべてのハンドラ関数は非同期関数(async def)

- プラグインとコンポーネント登録方法: 以前の単一プラグインクラスデコレータ登録方法から、マニフェストファイル登録方法に変更されました。[マニフェストファイル](https://langbot.app/docs/en/plugin/dev/basic-info.md)を参照してください; そして、異なるタイプのコンポーネントを独立して分離しました。詳細については、[コンポーネントの追加](https://langbot.app/docs/en/plugin/dev/components/add.md)を参照してください。
- メッセージチェーンエンティティ: リファクタリングされました。各メッセージチェーン要素の構築方法では、**名前付きパラメータ**の明示的な渡しが必要になりました。[メッセージプラットフォームエンティティ](https://langbot.app/docs/en/plugin/dev/apis/messages.md)を参照してください。
- イベントリスナー: 後方互換性を提供しますが、コンテキストで`query: Query`オブジェクトは提供されなくなりました。詳細については、[パイプラインイベント](https://langbot.app/docs/en/plugin/dev/apis/pipeline-events.md)を参照してください。
- コマンドコンポーネント: リファクタリングされました。[Commandコンポーネント](https://langbot.app/docs/en/plugin/dev/components/command.md)を参照してください。

## 2.xおよび3.xサポートの同期プラグインからの移行

> プラグインの特徴::
>
> - 主な期間: 2023.1 \~ 2024.2
> - 登録方法: `main.py`のプラグインクラスで`@on`デコレータを使用してイベントリスナーを登録し、`@func`デコレータを使用してコンテンツ関数(ツール)を登録; すべてのハンドラ関数は同期関数(def)

- 同期から非同期へ: プラグインランタイムは完全に非同期(asyncioベース)に変更されました。IO操作を含むすべてのプラグインコードを非同期記述に変更してください。
- 詳細な内容については、上記の3.x非同期プラグイン移行ガイドを参照してください。

---

# GitHub経由でプラグインを配布

Source: https://langbot.app/docs/ja/plugin/dev/publish/github

プラグインをGitHubにアップロードし、リポジトリのReleaseを作成して`.lbpkg`ファイルをアップロードすることで、他のユーザーがLangBotでインストールできるようになります。

## プラグインのビルド

プラグインディレクトリで次のコマンドを実行します:

```bash
lbp build
```

これにより、`dist`ディレクトリに`.lbpkg`ファイルが生成されます。

## Releaseの作成

プラグインをGitHubにアップロードし、プラグインリポジトリのReleaseページに移動し、Releaseを作成をクリックして、先ほどビルドした`.lbpkg`ファイルをアップロードします。

![](https://langbot.app/docs/images/zh/plugin/dev/dist/github_release.png)

## Releaseの自動作成（GitHub Actions）

`lbp init` で作成されたプラグインには、GitHub Actions ワークフロー（`.github/workflows/release.yml`）が組み込まれているため、手動でビルドしてアップロードする必要はありません。

プラグインリポジトリを GitHub にプッシュした後、`manifest.yaml` の `version` フィールドを変更して `main` または `master` ブランチにプッシュするたびに、ワークフローが自動的に以下を実行します:

1. `lbp` CLI をインストールし、`lbp build` を実行してプラグインをパッケージ化；
2. `v<version>` をタグとして GitHub Release を作成し、生成された `.lbpkg` ファイルをアップロード。

該当バージョンの Release が既に存在する場合、ワークフローはスキップして重複公開を回避します。リポジトリの Actions ページから手動でトリガーすることもできます（`workflow_dispatch`）。

> :
>
> このワークフローはリポジトリのデフォルトの `GITHUB_TOKEN` に依存し、`contents: write` 権限が必要です（テンプレートで宣言済み）。リポジトリの Actions が有効になっていること、`manifest.yaml` の `metadata.author`、`metadata.name`、`metadata.version` フィールドが正しく入力されていることを確認してください。Release 名と成果物のファイル名はこれらのフィールドから構成されます（`<author>-<name>-<version>.lbpkg`）。

## プラグインのインストール

LangBotのプラグイン管理ページで、右上隅をクリックしてGitHubインストール方法を選択します。

---

# プラグインマーケットプレイスに公開

Source: https://langbot.app/docs/ja/plugin/dev/publish/market

CLI経由で[LangBotプラグインマーケットプレイス](https://space.langbot.app/market)にプラグインを公開します。

## LangBot Spaceでアカウントを作成

LangBot SpaceはLangBotの集中サービスプラットフォームです。[LangBot Space](https://space.langbot.app)にアクセスし、右上隅をクリックしてGitHubでログインし、アカウントを作成してください。

![](https://langbot.app/docs/images/zh/plugin/dev/login_space.png)

GitHubの認証ページにリダイレクトされますので、プロンプトに従って認証を完了してください。

## CLIを使用してLangBot Spaceにログイン

### 方法1：個人アクセストークンを使用（推奨）

1. [LangBot Space](https://space.langbot.app)にログインし、アバターをクリックして**アカウント設定**を開き、**アカウント**タブの**個人アクセストークン**で新しいトークンを作成します。
2. 生成されたトークンをコピーし（一度しか表示されません）、ターミナルで以下を実行します：

```bash
➜  HelloPlugin > lbp login --token lbpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

==================================================
✅ 個人アクセストークンでログインしました！
トークンの保存先：~/.langbot/cli/config.json
==================================================
```

### 方法2：デバイスコード認証を使用

任意のディレクトリでコマンド`lbp login`を実行します：

```bash
➜  HelloPlugin > lbp login
Starting LangBot CLI login process...
Generating device code...

==================================================
Please copy the user code and complete verification in your browser:
User Code: 6CD64D56
Verification URL: https://space.langbot.app/auth/device
Device code expires in: 120 seconds
==================================================

Waiting for verification...
```

`Verification URL`をクリックしてLangBot Spaceにリダイレクトし、`User Code`を入力してログインを完了してください。

![](https://langbot.app/docs/images/zh/plugin/dev/space_device_flow.png)

```bash
==================================================
✅ Login successful!
Access token saved to: ~/.langbot/cli/config.json
Token type: Bearer
Expires in: 21600 seconds
==================================================
```

どちらの方法でもログインが成功したら、CLIを使用してプラグインをアップロードできます。

## プラグインのアップロード

プラグインディレクトリで`lbp publish`を実行してください：

```bash
➜  HelloPlugin > lbp publish
Building plugin to dist/tmp...
  - Skipping ignored directory: dist
  - Skipping ignored directory: __pycache__
  ...
Plugin built successfully: dist/tmp/RockChinQ-HelloPlugin-0.1.0.lbpkg
✅ Plugin published successfully. You can check it on https://https://space.langbot.app/market
```

[LangBotプラグインマーケットプレイス](https://space.langbot.app/market)でプラグイン提出タスクを確認できます。承認をお待ちください。承認後、マーケットプレイスでプラグインを表示できます。

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_submission.png)

公開の流れ自体に認証は関係しません。プラグインは既定で専用モードで動作します。このバージョンで認証も申請する場合は、[認証プラグインと共有実行](https://langbot.app/docs/ja/plugin/certified-plugins.md)を参照してください。

ご質問がある場合は、`hello@langbot.app`にメールを送信するか、[コミュニティ](https://langbot.app/docs/ja/insight/community.md)を通じてお問い合わせください。

---

# コードスタイルガイド

Source: https://langbot.app/docs/ja/plugin/dev/style

## ロギング

プラグインでは、`logging`モジュールを使用してログを記録してください。`print`文を使用しないでください（これはコンテナ環境でログが出力されなくなります）。

```python
import logging

logger = logging.getLogger(__name__)  # 任意の Python ファイルの先頭で logging モジュールをインポートし、logger オブジェクトを定義します

logger.info('This is an info message')  # logger.info を使用して info レベルのログを記録します
logger.warning('This is a warning message')
logger.error('This is an error message')
```

認証プラグインでは、生のプロセスログを 1 つの Workspace に安全に帰属できないため、運用診断専用です。Runner は `RunnerContext.log()` で installation-scoped なテナント表示ログを記録できます。その他のコンポーネントには汎用テナントログ API がまだないため、生のプロセスログは運用者専用です。モジュールグローバルなバックグラウンド処理から設定、認証情報、リクエストデータを出力してはいけません。

---

# プラグイン開発チュートリアル

Source: https://langbot.app/docs/ja/plugin/dev/tutor

> info:
>
> メッセージ受信やメンバー参加などを処理するプラグインを作る場合は、基本環境を準備した後、[イベントプロセッサーのチュートリアル](https://langbot.app/docs/ja/plugin/dev/components/runner.md)に進んでください。

## アーキテクチャの基礎

バージョン4.0では、高セキュリティで柔軟性の高い本番環境グレードのプラグインシステムを導入し、開発者に豊富なAPIと使いやすいサポートツールを提供しています。

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_system_arch.png)

Plugin Runtimeは、プラグインのライフサイクルを管理し、LangBotとプラグイン間の相互作用を調整するために使用されます。`stdio`と`websocket`の2つの動作モードがあります。LangBotがユーザーによって直接起動される場合(コンテナ内で実行されていない場合)、`stdio`モードを使用します。これは個人ユーザーや軽量環境で一般的です。LangBotがコンテナ内で実行される場合、`websocket`モードを使用します。これは本番環境専用に設計されています。

Plugin Runtimeは、インストールされた各プラグインを自動的に起動し、stdioを通じて相互作用します。プラグイン開発シナリオでは、開発者は`lbp`コマンドラインツールを使用してプラグインを起動し、WebSocketを介して実行中のRuntimeに接続してデバッグできます。

### プラグイン構造

プラグインのディレクトリ構造は次のようになります:

```bash
➜  HelloPlugin > tree
.
├── assets
│   └── icon.svg  # プラグインアイコン、プラグインマーケットプレイスページに表示
├── components  # プラグインコンポーネントディレクトリ、さまざまなコンポーネントコードとマニフェストファイルを保存
│   ├── __init__.py
│   ├── commands
│   │   ├── __init__.py
│   │   ├── info.py
│   │   └── info.yaml
│   ├── event_listener
│   │   ├── __init__.py
│   │   ├── default.py
│   │   └── default.yaml
│   └── tools
│       ├── __init__.py
│       ├── get_weather_alerts.py
│       └── get_weather_alerts.yaml
├── main.py  # プラグインメインプログラム、プラグインライフサイクルをリッスン
├── manifest.yaml  # プラグインマニフェストファイル、プラグインメタデータを記述
├── README.md  # プラグインドキュメントファイル、プラグイン機能と使用方法を記述、プラグインマーケットプレイスページに表示
├── readme
│   └── README_zh_Hans.md  # 簡体字中国語ドキュメント、多言語ドキュメント用
├── requirements.txt  # プラグイン依存関係ファイル
└── .github
    └── workflows
        └── release.yml  # GitHub Actions ワークフロー、バージョン変更をプッシュすると自動的にビルドして Release を公開
```

main.pyのプラグインクラスは各プラグインの共通コードで、プラグイン起動時に初期化され、コンテキスト情報(設定など)が渡されます。ここでプラグインの初期化とシャットダウンロジックを実装できます。プラグインクラスは`langbot_plugin.api.definition.plugin.BasePlugin`を継承し、[LangBotグローバルAPI](https://langbot.app/docs/en/plugin/dev/apis/common.md)を提供します。

各コンポーネントはプラグインのコア機能モジュールであり、必要に応じて[追加および削除](https://langbot.app/docs/en/plugin/dev/components/add.md)できます。異なるコンポーネントは異なる状況で呼び出され、後でプラグイン機能を簡単に拡張できます。各コンポーネントは`langbot_plugin.api.definition.components`パッケージ下のさまざまなコンポーネント基底クラスから直接継承し、`plugin: BasePlugin`オブジェクトを含み、プラグインのAPIを直接呼び出すことができます。

> :
>
> - 詳細なAPIドキュメントについては、[APIリファレンス](https://langbot.app/docs/en/plugin/dev/apis/common.md)を参照してください。
>
> このチュートリアルを続けて読んで、プラグイン開発プロセスを理解してください。

## AI 支援開発

- [skills-LangBotplugin](https://github.com/TyperBody/skills-LangBotplugin) - コミュニティメンバー [@TyperBody](https://github.com/TyperBody) が提供する Skills、AI を使ってプラグインを迅速に開発できます、ぜひお試しください
  - *langbotplugin* このSkillはプラグインの自動生成ツールを提供します
  - *langbotplugindebug* このSkillはプラグインのデバッグツールを提供します

## CLIのインストール

Python 3.10以上がインストールされており、[uvパッケージマネージャー](https://docs.astral.sh/uv/)がインストールされていることを確認してください。

任意の空のディレクトリで次のコマンドを実行して、LangBot CLIとSDKをインストールします:

```bash
pip install -U langbot_plugin
```

## プラグインディレクトリの初期化

プラグイン名が`HelloPlugin`であると仮定して、任意のディレクトリに`HelloPlugin`ディレクトリを作成し、そのディレクトリに入り、コマンドを実行してプラグインを初期化します:

```bash
lbp init
```

プロンプトに従って`Author`、`Description`などの情報を入力します。

> :
>
> `lbp init HelloPlugin`コマンドを使用して、サブディレクトリ`HelloPlugin`でプラグインを初期化することもできます。
>
> ![](https://langbot.app/docs/images/zh/plugin/dev/create_plugin.png)

この操作により、プラグインの初期ファイルが生成されます。お気に入りのエディターで`HelloPlugin`ディレクトリを開き、プラグインコードの記述を開始できます。

> :
>
> `lbp`コマンドで「command not found」エラーが発生した場合、`PATH`環境変数が適切に設定されていない可能性があります。
> `lbp`コマンドの代わりに`python -m langbot_plugin.cli.__init__`を使用できます。
>
> 例えば:
>
> ```bash
> python -m langbot_plugin.cli.__init__ init HelloPlugin
> cd HelloPlugin
> ```

## デバッグモードの開始

まずLangBotをデプロイして起動し、Plugin Runtimeが実行されてポート`5401`をリッスンしていることを確認する必要があります。

> Runtimeには2つの起動モードがあります::
>
> - `Stdio`モード: 起動パラメータ`--standalone-runtime`なしでソースコードを使用してLangBotを起動すると、LangBotは自動的にPlugin Runtimeをサブプロセスとして起動し、`stdio`(標準入出力ストリーム)を通じてPlugin Runtimeと通信します。この場合、RuntimeはLangBotルートディレクトリの`data/plugins`ディレクトリからプラグインをロードし、LangBotホストのポート`5401`をデバッグポートとしてリッスンします。
>
> - `WebSocket`モード:
>   - 本番環境: 公式の`docker-compose.yaml`を使用してLangBotを起動すると、Plugin Runtimeは別のコンテナで実行され、起動パラメータ`--standalone-runtime`のためにLangBotはWebSocketモードでPlugin Runtimeと通信します。Runtimeコンテナの5401ポートはデフォルトでホストの5401ポートにマッピングされます。
>   - 開発環境: 起動パラメータ`--standalone-runtime`を使用してソースコードでLangBotを起動すると、LangBotは`data/config.yaml`で設定された`plugin.runtime_ws_url`アドレス(ポートは通常5400)に従って既に起動されているPlugin Runtimeに接続します。スタンドアロンのPlugin Runtimeを自分で起動する必要があります。[Plugin Runtimeの開発](https://langbot.app/docs/en/develop/plugin-runtime.md)を参照してください。
>
> `stdio`または`websocket`モードのいずれの場合でも、Plugin Runtimeはそのホストのポート`5401`をプラグインデバッグ接続のデバッグポートとしてリッスンします。
>
> プラグインを開発する際は、[開発設定](https://langbot.app/docs/en/develop/dev-config.md)方法に従ってLangBotを起動することをお勧めします。これによりPlugin RuntimeがStdioモードで起動され、プラグイン開発が容易になります。

`.env.example` を `.env` にコピーします。LangBot WebUI の **拡張機能 → デバッグ情報** を開き、現在の Workspace のデバッグ URL とデバッグキーを `DEBUG_RUNTIME_WS_URL` と `PLUGIN_DEBUG_KEY` に設定します。キーは Workspace ごとに異なり、2 時間ごとにローテーションするため、期限切れ後は再度コピーしてください。

```bash
cp .env.example .env
```

プラグインデバッグを開始すると、プラグインの出力が表示されます:

```bash
lbp run
```

![](https://langbot.app/docs/images/zh/plugin/dev/launch_debug_plugin.png)

そして、LangBotのWebUIでこのプラグインがロードされたことを確認できます。

![](https://langbot.app/docs/images/zh/plugin/dev/debug_plugin_loaded.png)

## 次のステップ

このチュートリアルでは、プラグイン機能を段階的に完成させる方法を案内します。

- プラグイン情報の変更: プラグインは基本的なプラグイン情報で作成されました。[プラグイン情報を完成させて](https://langbot.app/docs/en/plugin/dev/basic-info.md)ください。
- コンポーネントの追加: プラグインコンポーネントはプラグインのコア機能ユニットです。必要に応じて[コンポーネントを追加](https://langbot.app/docs/en/plugin/dev/components/add.md)できます。

---

# LangBotプラグイン

Source: https://langbot.app/docs/ja/plugin/plugin-intro

LangBotは、大規模言語モデルツール、コマンド、メッセージングプラットフォームアダプター、LLMリクエスターなど、さまざまな内部コンポーネントで構成されています。拡張性と柔軟性の要件を満たすために、本番環境グレードのプラグインシステムを実装しました。

プラグインは Plugin Runtime により統一して管理されます。多くのプラグインは専用ランタイムを使用し、正確な artifact の有効な署名が確認されたリリースのみ、LangBot Cloud で[ワークスペース間の共有資格](https://langbot.app/docs/ja/plugin/certified-plugins.md)を得られます。レビューだけでは認証になりません。

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_system_arch.png)

## プラグイン構造

プラグインは、特定の機能に基づいて次のコンポーネントを提供できます:

- イベントハンドラー: パイプライン実行中のイベントをリッスンし、コンテキストやパイプラインを変更します。
- コマンド: `!`(または他の設定されたプレフィックス)で始まるユーザーコマンドメッセージによってトリガーされます。
- ツール: LangBotの組み込みLocal Agentの実行中にLLMによって呼び出されます。
- RAGエンジン: ナレッジベースのドキュメントインデックス作成と検索を管理します。

将来的には、プラグイン実装のためにより多くのコンポーネントタイプがサポートされます。

## プラグインのインストール

現在、プラグインパッケージのアップロードとプラグインマーケットプレイスからのプラグインのインストールをサポートしています。
LangBotのプラグイン管理ページで、右上隅をクリックしてインストール方法を選択します。

![](https://langbot.app/docs/images/zh/plugin/install_method.png)

`Upload Local`をクリックして、他の人が共有した`.lbpkg`ファイルまたはマーケットプレイスからダウンロードしたファイルを選択してプラグインをインストールします。

または、プラグインマーケットプレイスタブをクリックし、プラグインを選択してインストールをクリックします。

![](https://langbot.app/docs/images/zh/plugin/install_from_marketplace.png)

プラグインをインストールした後、パイプライン設定ページでプラグインを選択する必要があります。

![](https://langbot.app/docs/images/zh/plugin/pipeline_extensions.png)

## プラグイン管理

### プラグイン設定

一部のプラグインでは、特定の設定項目を入力する必要がある場合があります(プラグインREADMEの指示を参照)。プラグインカードをクリックしてプラグイン詳細ページに入り、プロンプトに従って必要な情報を取得して入力します。

![](https://langbot.app/docs/images/zh/plugin/plugin_config.png)

### プラグインの更新

プラグインマーケットプレイスからインストールされたプラグインのみを更新できます。

![](https://langbot.app/docs/images/zh/plugin/update_plugin.png)

## プラグインマーケットプレイス

プラグインマーケットプレイスには、LangBotの内部`プラグイン管理`ページからアクセスするか、スタンドアロンサイト[LangBotプラグインマーケットプレイス](https://space.langbot.app/market)にアクセスできます。

---

# Service API 概要

Source: https://langbot.app/docs/ja/tags/readme

LangBotは、外部サービスと統合・自動管理するための RESTful API を提供します。これらのAPIはAPIキーで認証され、HTTP APIのサブセットです。

> warning:
>
> Service APIは現在ベータ版であり、一部のAPIは頻繁に変更される可能性があります。

## APIキーの取得

WebUIのサイドバーにある `API Keys` ボタンをクリックして、APIキーを作成します。

![create\_api\_key](https://langbot.app/docs/images/zh/api/create_api_key.png)

作成後、APIキーをコピーして保存します。

![copy\_api\_key](https://langbot.app/docs/images/zh/api/copy_api_key.png)

## 認証方法

すべてのService APIは、以下の2つの認証方法をサポートしています：

- **APIキー**: `X-API-Key: <your-key>` または `Authorization: Bearer <your-key>` ヘッダー経由
- **ユーザートークン**: `Authorization: Bearer <user-token>` ヘッダー経由（ログイン後に取得）

## APIの使用

左サイドバーには、利用可能なすべてのAPIが一覧表示されています。インスタンスアドレス（デフォルトは `http://localhost:5300`）とAPIキーを入力し、`Try it out` ボタンをクリックしてAPIを呼び出せます。

## コアコンセプト

### Provider + Model アーキテクチャ

LangBotは **プロバイダー（Provider）+ モデル（Model）** の2層アーキテクチャでAIモデルを管理します：

- **プロバイダー**: APIエンドポイント（`base_url`）、リクエスタータイプ、APIキーを定義。1つのプロバイダーに複数のモデルを関連付け可能。
- **モデル**: プロバイダーに関連付け（`provider_uuid` 経由）、具体的なモデル名とパラメータを定義。プロバイダーのAPIエンドポイントとキーを継承。

```
Provider (OpenAI)
├── base_url: https://api.openai.com/v1
├── api_keys: [sk-xxx]
├── LLM: gpt-4o
├── LLM: gpt-4o-mini
└── Embedding: text-embedding-3-small
```

### リクエスター

リクエスターはAIサービスとの通信プロトコルを定義します。`GET /api/v1/provider/requesters` で利用可能なリクエスター一覧を取得できます。

### 非同期タスク

一部の操作（プラグインのインストール/削除/アップグレード）は非同期で実行され、`task_id` を返します。WebUIで進捗を確認できます。

---

# Webhook

Source: https://langbot.app/docs/ja/tags/webhook

Webhookを使用すると、ボットメッセージイベントを外部サービスに送信して処理できます。

## Webhookの設定

1. LangBot WebUIで、サイドバーの「API統合」をクリックします
2. 「Webhooks」タブに切り替えます
3. 「+」をクリックして新しいWebhookを作成します
4. 以下を入力します:
   - **Name**: Webhook識別子
   - **URL**: イベントを受信するターゲットURL
   - **Description**: オプション
   - **Status**: 有効または無効

## イベント形式

### 個人メッセージ (bot.person\_message)

```json
{
  "uuid": "event-unique-id",
  "event_type": "bot.person_message",
  "data": {
    "bot_uuid": "bot-uuid",
    "adapter_name": "AdapterName",
    "sender": {
      "id": "user-id",
      "name": "User Name"
    },
    "message": [
      {
        "type": "Plain",
        "text": "Message content"
      }
    ],
    "timestamp": 1234567890
  }
}
```

### グループメッセージ (bot.group\_message)

```json
{
  "uuid": "event-unique-id",
  "event_type": "bot.group_message",
  "data": {
    "bot_uuid": "bot-uuid",
    "adapter_name": "AdapterName",
    "group": {
      "id": "group-id",
      "name": "Group Name"
    },
    "sender": {
      "id": "user-id",
      "name": "User Name"
    },
    "message": [
      {
        "type": "Plain",
        "text": "Message content"
      }
    ],
    "timestamp": 1234567890
  }
}
```

## レスポンス形式

WebhookサービスはJSONを返す必要があります:

```json
{
  "status": "ok",
  "skip_pipeline": false
}
```

### パラメーター

- **status**: 処理ステータス(「ok」を推奨)
- **skip\_pipeline**: LangBotパイプライン処理をスキップするかどうか
  - `true`: メッセージはパイプラインで続行されません
  - `false`: メッセージは通常どおり続行されます

> idea:
>
> `skip_pipeline`を使用すると、メッセージ処理を完全に引き継ぐことができます。`true`の場合、メッセージはWebhookサービスによってのみ処理され、LangBotのAI機能はトリガーされません。

## 統合例

### Dify Workflow

[dify-plugin-langbot-trigger](https://github.com/langbot-app/dify-plugin-langbot-trigger)プラグインを使用して、LangBotのWebhookイベントを受信し、Difyでワークフローを作成できます。

## 注意事項

- Webhook URLはアクセス可能である必要があります
- リクエストタイムアウト: 15秒
- 失敗したリクエストは通常の処理に影響しません
- 複数のWebhookは並行して実行されます
- `skip_pipeline: true`を返すWebhookがある場合、パイプライン処理はスキップされます

---

# ナレッジベース

Source: https://langbot.app/docs/ja/usage/knowledge/readme

LangBot で RAG ナレッジベースを構築。AI ボットにドキュメント検索と根拠ある回答を付与。

LangBotはRAG（Retrieval-Augmented Generation）をネイティブサポートしています。ナレッジベースを作成してパイプラインにバインドすることで、ナレッジベースの内容に基づいて質問に答えることができます。

ナレッジベースはRAGエンジンプラグインによって駆動され、異なるRAGエンジンは異なるインデックス作成と検索戦略を提供します。利用可能なRAGエンジンプラグインは[プラグインマーケットプレイス](https://space.langbot.app/market)で見つけることができます。

## ナレッジベースの作成

ナレッジベースページで`ナレッジベースを作成`ボタンをクリックします:

1. ナレッジベース名を入力
2. RAGエンジンを選択（インストール済みのプラグインが提供）
3. 選択したエンジンの設定フォームに基づいて関連パラメータを入力（例: 埋め込みモデル、チャンクサイズなど）
4. `作成`ボタンをクリック

> info:
>
> RAGエンジンによって設定パラメータが異なり、エンジンの`creation_schema`定義に依存します。一部のエンジンでは、まず埋め込みモデルの設定が必要な場合があります。[モデルの設定](https://langbot.app/docs/ja/usage/models/readme.md)をお読みください。

選択したRAGエンジンがドキュメントのアップロードをサポートしている場合（`DOC_INGESTION`能力を宣言している場合）、作成後にナレッジベースの「ドキュメント」タブに移動してドキュメントをアップロードします。LangBotはバックグラウンドで自動的に解析とインデックス化を行います。

## ナレッジベースの使用

パイプライン設定に移動し、「AI」タブで`Local Agent`をランナーとして選択してから、先ほど作成したナレッジベースを選択します。

![use\_kb](https://langbot.app/docs/images/zh/deploy/knowledge/use_local_agent.png)

![use\_kb](https://langbot.app/docs/images/zh/deploy/knowledge/use_kb.png)

### 再順位付けの設定（オプション）

ナレッジベースを選択した後、下方で**再順位付けモデル**を設定して検索品質を向上させることができます：

- **再順位付けモデル**：設定済みのRerankモデルを選択（未設定の場合は先に[モデル設定](https://langbot.app/docs/ja/usage/models/readme.md)で追加してください）
- **再順位付け保持数（Top-K）**：再順位付け後に保持する最も関連性の高い結果数、デフォルトは5

> idea:
>
> 再順位付けモデルはオプションです。設定すると、ナレッジベース検索から返される候補ドキュメントが再順位付けモデルで再スコアリングされ、最も関連性の高い上位K件のみが保持され、大規模モデルに渡されます。無関係な情報の干渉が大幅に減少します。

> info:
>
> LangBotの組み込みナレッジベースは、ランナーが`Local Agent`に設定されている場合にのみ使用できます。他のランナーについては、それぞれのドキュメントを参照してください。

これで`チャットデバッグ`でナレッジベースを使用したり、このパイプラインにリンクされたボットを通じて使用できます:

![use\_kb\_in\_chat](https://langbot.app/docs/images/zh/deploy/knowledge/use_kb_in_chat.png)

## カスタムRAGエンジンの開発

既存の知識エンジンプラグインがニーズを満たさない場合、独自の知識エンジンプラグインを開発できます。開発方法については、[コンポーネント: 知識エンジン](https://langbot.app/docs/ja/plugin/dev/components/knowledge-engine.md)を参照してください。

---

# MCP サーバー

Source: https://langbot.app/docs/ja/usage/mcp/readme

MCP（Model Context Protocol）サーバーを LangBot に接続し、外部ツールやデータソースで AI ボットを拡張。

LangBot は MCP サーバー由来のツールを利用できます。MCP サーバーを追加すれば、ツール使用を有効にしたモデルを持つ組み込み Agent が会話中にそのツールを呼び出せます。

> MCP はローカル（stdio）とリモートの 2 モードに対応しています。:
>
> まずは [LangBot Space](https://space.langbot.app) からのインストールを推奨します。掲載されている MCP サーバーは設定済みで、そのまま使えます。
>
> [ModelScope](https://modelscope.cn/mcp)、[mcp.so](https://mcp.so)、[composio.dev](https://composio.dev/toolkits) から入手して、後述の手動追加で登録することも可能です。

## 2 つの通信モード

| モード                            | 適した場面                      | 備考                                                                                          |
| ------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------- |
| リモート (`mode: "remote"`)        | リモート MCP サービス。URL を貼り付けるだけ | LangBot がリモート URL に直接接続し、トランスポート（まず Streamable HTTP を試行し、失敗時は SSE にフォールバック）を自動検出します。手動選択は不要 |
| ローカル / stdio (`mode: "stdio"`) | ローカルコマンドで起動する MCP サーバー     | Box Runtime が利用可能なときのみサポート                                                                  |

> info:
>
> 以前のバージョンではリモートモードを `http`（Streamable HTTP）と `sse` の 2 つに分けていましたが、現在は単一の `remote` に統合され、トランスポートはバックエンドが自動検出します。データベース内の既存 `http` / `sse` レコードはアップグレード時に `remote` へ正規化され、接続パラメータ（URL、ヘッダー、タイムアウト）はそのまま保持されます。

> info:
>
> MCP ツールを使うには、パイプラインで**組み込み Agent** を選択し、**ツール使用が有効化されたモデル**を使用する必要があります。[モデル](https://langbot.app/docs/ja/usage/models/readme.md)を参照。Dify、n8n、Langflow、Coze などの外部 Runner は各プラットフォームのツール機構を使います。

## MCP サーバーをインストール

### LangBot Space から（推奨）

[LangBot Space](https://space.langbot.app) は LangBot 公式のマーケットプレイスで、設定済みの MCP サーバーが多数掲載されています。WebUI の `プラグイン管理` → `MCP 管理` から閲覧して 1 クリックでインストールでき、URL、コマンド、モードなどのパラメータはマーケット側が提供するため、手動入力は不要です。

ほとんどのケースはこれで十分です。掲載されていないサービスを利用する場合は、下記の手動追加を使ってください。

### 手動で追加

`プラグイン管理` → `MCP 管理` を開きます：

![MCP 管理ページ](https://langbot.app/docs/images/zh/deploy/mcp/mcp02.png)

右上の `追加` → `MCP サーバーを追加` をクリック。**ローカル（stdio）**または**リモート**モードを選びます。リモートは URL を貼り付けるだけ、ローカルは起動コマンドを入力します。`テスト` で接続を確認、`送信` で保存します：

![MCP サーバー作成](https://langbot.app/docs/images/zh/deploy/mcp/mcp03.png)

保存後、カードのスイッチをオンにして接続します。カードをクリックすると詳細を確認できます：

![MCP サーバー詳細](https://langbot.app/docs/images/zh/deploy/mcp/mcp05.png)

## パイプラインで有効化

MCP サーバーを追加したあと、パイプライン拡張設定で Agent から見える MCP を決めます：

- 「すべての MCP サーバーを有効化」をオン、または
- 指定した MCP サーバーのみをバインド

バインドしていない MCP のツールはそのパイプラインのツール一覧に入りません。

## 高度な設定：stdio MCP

stdio MCP は Box Runtime によってホストされます。接続前に LangBot は以下を行います：

1. 共有の MCP Box session を作成または再利用
2. コマンドからローカルプロジェクトのパスを推測できれば、プロジェクトをワークスペースに staging
3. プロジェクトに `requirements.txt`、`pyproject.toml`、`setup.py`、`setup.cfg` がある場合は依存をインストール
4. WebSocket relay 経由で MCP プロセスの stdin/stdout に接続

マウント、ネットワーク、タイムアウトを細かく調整したい場合、MCP 設定の `extra_args` に `box` オーバーライドを追加できます：

```json
{
  "mode": "stdio",
  "extra_args": {
    "command": "python",
    "args": ["server.py"],
    "env": {},
    "box": {
      "host_path": "/path/to/mcp-project",
      "network": "on",
      "host_path_mode": "ro",
      "startup_timeout_sec": 120,
      "image": "python:3.11-slim"
    }
  }
}
```

主なフィールド：

| フィールド                 | 説明                                                                                |
| --------------------- | --------------------------------------------------------------------------------- |
| `host_path`           | ホスト上の MCP プロジェクトディレクトリ。`box.local.allowed_mount_roots` の許可範囲内である必要があります           |
| `network`             | ネットワークを許可するか（依存インストールでよく使う）                                                       |
| `host_path_mode`      | `host_path` を staging するときのアクセスモード。デフォルトは `ro`。stdio MCP は通常ワークスペースに staging されます |
| `startup_timeout_sec` | Box 準備と依存インストールのタイムアウト、デフォルト 120 秒。接続待ちで約 30 秒追加されます                              |
| `image`               | Docker バックエンドで使用するランタイムイメージ                                                       |

> warning:
>
> stdio MCP は Box 内で実行されます。依存インストールとプロセス起動は sandbox profile、ネットワーク権限、リソース制限、マウント許可リストの影響を受けます。

## よくある問題

| 症状                    | 確認項目                                                                |
| --------------------- | ------------------------------------------------------------------- |
| MCP の接続に失敗            | URL、コマンド、引数、環境変数が正しいか                                               |
| stdio MCP が接続中のまま     | Box Runtime の状態、`startup_timeout_sec` が短すぎないか                       |
| 依存インストールに失敗           | sandbox がネットワークを許可しているか、依存ファイルが正しいか                                 |
| ローカルファイルにアクセスできない     | `host_path` が存在し、`allowed_mount_roots` 内にあるか                        |
| Agent が MCP ツールを認識しない | パイプラインで組み込み Agent を使っているか、モデルでツール使用を有効にしているか、MCP がパイプラインにバインドされているか |

---

# モデル (Models)

Source: https://langbot.app/docs/ja/usage/models/readme

LangBot で LLM プロバイダを設定：OpenAI GPT・Anthropic Claude・Google Gemini・DeepSeek・Qwen・Ollama・OpenAI 互換モデル。

## LangBot Models

LangBot Modelsは、LangBotが公式に提供するモデルサービスです。LangBot Spaceアカウントでローカルインスタンスを初期化すると、利用可能なモデルが自動的にインスタンスに追加され、設定は不要です。すぐに始められるように、一定の無料枠が提供されます。

![langbot\_models](https://langbot.app/docs/images/zh/deploy/models/langbot_models.png)

具体的な利用可能モデルについては、[LangBot Space](https://space.langbot.app/models)をご確認ください。

## カスタムモデル

他のソースからモデルを追加することもできます。

### 対話モデル (LLM Model)

モデルはパイプラインによってメッセージ処理に使用されます。最初に設定したモデルがデフォルトパイプラインのモデルとして設定されます。

![arch](https://langbot.app/docs/images/zh/deploy/models/arch.png)

複数のモデルを追加して、パイプラインでどのモデルを使用するかを選択できます。

![model\_config](https://langbot.app/docs/images/zh/deploy/models/model_config.png)

これら4つのパラメータを入力します: `モデル名`、`モデルプロバイダー`、`リクエストURL`、`APIキー`、そして送信します。

モデルの機能は、ベースモデルが実際にサポートしているものを有効化します：

- **ビジョン**：有効にすると画像を認識可能
- **ツール使用**（function calling / tool use）：有効にすると LLM が会話中にツールを呼び出せる

> info:
>
> **MCP サーバー、サンドボックスの組み込みツール（`exec`/`read`/`write`/`edit`/`glob`/`grep`）、Skills のいずれかを利用したい場合は、モデルでツール使用を必ず有効にしてください。** 有効でなければ、パイプラインで拡張機能をバインドしていても Agent はツールを呼び出しません。
>
> ベースモデル自体が function calling に対応している必要があります。不明な場合はモデル提供元のドキュメントを確認してください。

### 埋め込みモデル (Embedding Model)

埋め込みモデルはメッセージのベクトル表現を計算するために使用されます。ナレッジベースを使用する場合は、このモデルを設定してください。

![embedding\_model](https://langbot.app/docs/images/zh/deploy/models/embedding_model.png)

これら4つのパラメータを入力します: `モデル名`、`モデルプロバイダー`、`リクエストURL`、`APIキー`、そして送信します。その後、ナレッジベースでこのモデルを使用するように設定してください。

### seekdb 内蔵埋め込みモデルの使用（オプション依存関係が必要）

リクエストパラメータの入力は不要です。ソースデプロイでは `uv sync --extra seekdb`、パッケージデプロイでは `uvx --from 'langbot[seekdb]@latest' langbot` を使用します。公式 Docker/Kubernetes イメージには SeekDB 依存関係がすでに含まれています。ネイティブデプロイの対応環境は `pylibseekdb` wheel に依存します。

- 「埋め込みモデル」ページで「seekdb-内蔵」を選択します；
- 「保存」をクリックするとすぐに使用できます；
- その後、ナレッジベースでこのモデルを選択すると有効になります。

### Chroma内蔵埋め込みモデルの使用（ゼロ設定）

システムにはChromaの内蔵埋め込みモデル（all-MiniLM-L6-v2）が統合されており、パラメータの入力は不要です。

- 「埋め込みモデル」ページで「chroma-内蔵」を選択します；
- 「保存」をクリックするとすぐに使用できます；
- その後、ナレッジベースでこのモデルを選択すると有効になります。

### 再順位付けモデル (Rerank Model)

再順位付けモデルはRAG検索結果を再スコアリングし、ナレッジベース回答の精度を大幅に向上させます。ナレッジベースが複数の候補ドキュメントを返す場合、再順位付けモデルはクロスエンコーダを使用して各ドキュメントとクエリの関連性を正確にスコアリングし、最も関連性の高いコンテンツのみを選択します。

`モデル名`を入力し、`モデルプロバイダー`を選択して送信します。その後、パイプラインの「AI」設定でこのモデルを選択してください。

> idea:
>
> 再順位付けモデルはオプションです。設定しない場合、ナレッジベースの結果は元の検索順序で使用されます。再順位付けモデルを設定すると、結果が再スコアリングされ、最も関連性の高い上位K件のみが保持されます。

---

# Coze APIの統合

Source: https://langbot.app/docs/ja/usage/pipelines/coze

Coze を LangBot と統合。Coze のボットやエージェントを Discord・Telegram・WeChat 等に接続。

このドキュメントでは、CozeプラットフォームからTokenとBot IDを取得し、LangBotパイプライン設定に入力する方法を説明します。

## 1. TokenとBot IDの取得

1. Cozeプラットフォームにログインし、開発者コンソールに入ります。
   ![Coze Application API Key](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze07.png)

2. 「API管理」でトークンを作成してコピーします。
   ![Coze Application API Key](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze06.png)

> info:
>
> Coze認証では、coze.cnは「サービスIDと認証情報」を通じた長期認証をサポートしていますが、coze.comはPersonal Access Tokenのみを提供しています。

3. プロジェクト開発セクションから自分のエージェントを選択します(または新しいエージェントを作成します)。取得したIDが`bot_id`です。
   ![Coze bot\_id](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze05.png)

- エージェントを公開する際は、必ずAPIオプションを選択してください
  ![Coze Application API Key](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze04.png)

以下の2つの情報を安全に保管してください:

- **token**: Cozeプラットフォームで生成されたトークン
- **bot\_id**: Bot ID

## 2. LangBotでの設定入力

1. LangBot WebUIを開き、パイプラインの設定ページに移動します(または新しいパイプラインを作成してその設定ページに入ります)

2. 「AI機能」で、ランナーとして`Coze API`を選択します

3. ランナーの設定項目に入力します:

   - **token**: CozeプラットフォームからコピーしたAPIトークンを貼り付けます
   - **bot\_id**: 対応するBot IDを貼り付けます
   - 使用しているCozeサイトに応じて`API Base URL`を選択してください: coze.cnの場合は`https://api.coze.cn`を入力してください; coze.comの場合は`https://api.coze.com`を入力してください

   ![パイプライン設定](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze08.png)

4. 「保存」をクリックして設定を完了します

完了すると、このパイプライン内でCozeエージェントを呼び出して対話処理ができます

## よくある質問(FAQ)

- **保存が失敗するか、呼び出しがエラーを返す**: トークンとbot\_idが正しく、余分なスペースが含まれていないことを確認してください
- **`Coze API`を選択できない**: 現在のバージョンがこのランナーをサポートしているか確認してください。まだサポートされていない場合は、Cozeランナーを含むバージョンにアップグレードしてください

一般的なパイプライン設定の詳細については、[対話パイプライン設定の変更](https://langbot.app/docs/ja/usage/pipelines/readme.md)を参照してください

---

# LangBot で DeerFlow を使用する

Source: https://langbot.app/docs/ja/usage/pipelines/deerflow

DeerFlow を LangBot と組み合わせ、AI ボットの会話パイプラインを構築。

[DeerFlow](https://github.com/bytedance/deer-flow) は、ByteDance がオープンソース化した大規模言語モデル（LLM）ベースの AI エージェントフレームワークであり、深度研究、情報検索、マルチエージェントの協調オーケストレーションに焦点を当てています。\
フレームワークは LangGraph 上に構築され、設定可能なワークフローエンジンを採用し、計画モード、サブエージェントの並行処理、思考連鎖などの高度な機能をサポートしています。深度情報収集と構造化分析が必要なシナリオに適しています。

現在の統合は DeerFlow **2.0 `main` ブランチ**を対象としています。DeerFlow 公式は元の Deep Research フレームワークを `main-1.x` ブランチに移管して継続的にメンテナンスしています。そのため、バージョン 2.0 を使用している場合は、`main` ブランチの公式ドキュメントとバックエンド API を参照してください。

LangBot は現在、DeerFlow を `AI 機能` ランナーとして会話パイプラインに接続し、深度研究とエージェントオーケストレーション機能を提供します。

## DeerFlow のデプロイ

[DeerFlow 公式ドキュメント](https://github.com/bytedance/deer-flow) に従って、サービスのインストール、設定、起動を完了してください：

- [DeerFlow GitHub リポジトリ](https://github.com/bytedance/deer-flow)
- [DeerFlow ウェブサイト](https://deerflow.tech/)
- [DeerFlow 設定ドキュメント](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md)

デプロイ完了後、DeerFlow が正常に起動していることを確認し、ゲートウェイアドレスをメモしてください。デフォルトでは、DeerFlow のゲートウェイアドレスは `http://127.0.0.1:2026` です。

> ネットワーク設定のヒント:
>
> - `API ベース URL` は `http://` または `https://` で始まる必要があります。
> - LangBot と DeerFlow が同じホストにデプロイされ、どちらも Docker を使用してデプロイされている場合、次の記事を参照してください：[ネットワーク設定の詳細](https://langbot.app/docs/ja/workshop/network-details.md#langbot-およびメッセージプラットフォームが-docker-コンテナで実行されている場合)。DeerFlow を起動する際に、コンテナを `langbot-network` に追加し、LangBot 設定の `API ベース URL` をコンテナ相互接続アドレス（例：`http://deerflow-app:2026`）に設定してください。
> - 異なるホストやコンテナにデプロイされている場合は、`127.0.0.1` を DeerFlow が実際にアクセス可能な社内アドレス、ホスト名、またはドメインに置き換えてください。

## LangBot の設定

LangBot WebUI ページを開き、新しいパイプラインを追加するか、既存のパイプラインで `AI 機能` 設定ページに切り替えます。

![deerflow](https://langbot.app/docs/images/zh/deploy/pipelines/deerflow/creat_langbot_pipeline.png)

1. `ランナー` で `DeerFlow API` を選択します。
2. ランナーの設定項目に以下を入力します：
   - `API ベース URL`：DeerFlow サービスの API ゲートウェイアドレス、デフォルト `http://127.0.0.1:2026`。
   - `API キー`：オプション。DeerFlow ゲートウェイが Bearer Token 認証を使用している場合、ここに入力できます。
   - `Assistant ID`：DeerFlow 2.0 LangGraph の `assistant_id` に対応、デフォルト `lead_agent`。
   - `モデル名オーバーライド`：オプション。DeerFlow 側に設定されたデフォルトモデルを上書きするために使用します。DeerFlow にモデルが設定されている場合は空白のままにできます。
   - `思考モードを有効化`：有効にすると、DeerFlow は思考連鎖コンテンツを返し、推論プロセスの表示に使用できます。
   - `計画モードを有効化`：DeerFlow 2.0 ランタイムパラメータ `config.configurable.is_plan_mode` に対応。有効にすると、エージェントは実行前に研究計画を立てます。
   - `サブエージェントを有効化`：DeerFlow 2.0 ランタイムパラメータ `config.configurable.subagent_enabled` に対応。有効にすると、エージェントがサブエージェントをディスパッチしてタスクを並行処理できるようになります。
   - `サブエージェント最大同時実行数`：DeerFlow 2.0 ランタイムパラメータ `config.configurable.max_concurrent_subagents` に対応。サブエージェントが有効な場合のみ有効、デフォルト `3`。
   - `再帰深度上限`：LangGraph の `recursion_limit` に対応。ワークフローの最大再帰深度を制御、デフォルト `1000`。
3. `保存` をクリックして設定を完了します。

> 設定の推奨事項:
>
> - DeerFlow 側で対応する機能が有効になっている場合にのみ、`計画モード` または `サブエージェント` 関連オプションを有効にすることをお勧めします。そうでない場合、期待される効果が得られない可能性があります。
> - LangBot は DeerFlow 2.0 が推奨する `config.configurable` ランタイムパラメータを送信すると同時に、上位の最新バージョンとの連携を容易にするために後方互換性の旧フィールドを保持します。

完了後、パイプラインで DeerFlow を使用して深度研究とインテリジェント Q\&A を完了できます。

## よくある質問

- **保存に失敗するか、呼び出しでエラー**：`API キー` と `API ベース URL` が正しいか確認し、DeerFlow サービスが正常に起動していることを確認してください。
- **期待されるコンテンツが返されない**：`Assistant ID` が DeerFlow で実際に使用可能なアシスタントと一致しているか確認してください。
- **`DeerFlow API` を選択できない**：現在の LangBot バージョンがこのランナーをサポートしているか確認してください。サポートされていない場合は、DeerFlow ランナーを含むバージョンにアップグレードしてください。
- **DeerFlow 設定項目の意味**：ランタイムパラメータと機能に関する DeerFlow 公式ドキュメントを参照するか、DeerFlow コミュニティに推奨設定を相談してください。

パイプラインの一般的な設定の詳細については、[会話パイプライン設定の変更](https://langbot.app/docs/ja/usage/pipelines/readme.md) を参照してください。

---

# LangBotでのDifyの使用

Source: https://langbot.app/docs/ja/usage/pipelines/dify

Dify を LangBot に接続。Dify アプリやエージェントを Discord・Telegram・WeChat・Slack 等の AI ボットとしてデプロイ。

[Dify](https://dify.ai)は、オープンソースの大規模言語モデル(LLM)アプリケーション開発プラットフォームです。Backend as ServiceとLLMOpsの概念を組み合わせ、開発者が本番グレードの生成AIアプリケーションを迅速に構築できるようにします。
Difyは、チャットアシスタント(Chatflowを含む)、エージェント、テキスト生成アプリケーション、ワークフローなどのタイプのアプリケーションを作成できます。

LangBotは現在、3種類のDifyアプリケーションをサポートしています: `チャットアシスタント`(Chatflowを含む)、`エージェント`、`ワークフロー`。

## Difyでのアプリケーション作成

[Difyドキュメント](https://docs.dify.ai)に従ってDifyをデプロイし、アプリケーションを作成してください。

アプリケーションを公開した後、アプリケーションの`Access API`ページに移動してAPIキーを生成します。

![Dify Application API Key](https://langbot.app/docs/images/zh/deploy/pipelines/dify/dify_sv_api_01.png)

LangBotのパイプライン`AI機能`を設定するために、APIサーバーとAPIキーを保存します。

> 上記はDifyクラウドサービスバージョンの例です。セルフホストコミュニティバージョンを使用している場合は、LangBotの\`base-url\`として独自のDifyサービスアドレスを使用し、パスとして\`/v1\`を追加してください。:
>
> - LangBotとDifyが同じホストにデプロイされており、両方ともDockerを使用してデプロイされている場合は、記事[ネットワーク設定の詳細](https://langbot.app/docs/zh/workshop/network-details.md#langbot-%E5%92%8C%E6%B6%88%E6%81%AF%E5%B9%B3%E5%8F%B0%E5%9D%87%E8%BF%90%E8%A1%8C%E5%9C%A8-docker-%E5%AE%B9%E5%99%A8%E4%B8%AD)を参照してください。この場合、Difyを起動するdocker-compose.yamlファイル内のすべてのコンテナの`networks`に`langbot-network`を追加し、`nginx`コンテナにコンテナ名`dify-nginx`を追加し、最後にLangBot設定で`base-url`を`http://dify-nginx/v1`に設定します。
> - その他のケースについては、会社の運用チームにお問い合わせください。

## LangBotの設定

LangBot WebUIページを開き、新しいパイプラインを追加するか、既存のパイプラインのAI機能設定ページに切り替えます。

![設定開発項目](https://langbot.app/docs/images/zh/deploy/pipelines/dify/dify_sv_api_02.png)

> \### ワークフロー出力キー:
>
> Difyワークフローアプリケーションを使用している場合は、出力コンテンツを渡すキーとして`summary`を使用してください。
>
> ![Difyワークフローアプリケーション出力キー](https://langbot.app/docs/images/zh/deploy/pipelines/dify/dify_workflow_output_key.png)
>
> ## 出力処理
>
> ワークフローアプリケーションまたはエージェントアプリケーションを使用している場合、LangBotのパイプライン`出力処理`で`track-function-calls`を有効にすると、Difyが各ツール呼び出しを実行する際に`calling function xxx`というメッセージがユーザーに出力されます。
> ただし、`chat`アプリケーション(チャットアシスタント -> ワークフローオーケストレーション)の下で`ChatFlow`を使用している場合は、設定に関係なく、Answer(直接返信)ノードによって返されるテキストのみが出力されます。

---

# LangBotでのLangflowの使用

Source: https://langbot.app/docs/ja/usage/pipelines/langflow

Langflow を LangBot と連携。Langflow のフローを Discord・Telegram・WeChat 等の AI ボットとして展開。

[Langflow](https://langflow.com/)は、AIベースのエージェントとワークフローを構築およびデプロイするためのオープンソースプロジェクトです。ローカルおよびクラウドデプロイをサポートし、他のアプリケーションが統合できるAPIを提供します。

LangBotは現在、ランナーとしてLangflowの使用をサポートしています。

## Langflowでのワークフロー作成

[Langflowドキュメント](https://langflow.com/docs/introduction)に従ってLangflowインスタンスをデプロイしてください。

デフォルトテンプレートのSimple Agentの例:

![create\_flow](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/create_flow.png)

必要に応じてワークフローを変更できます:

![edit\_flow](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/edit_flow.png)

## LangBotの設定

LangBot WebUIページを開き、新しいパイプラインを追加するか、既存のパイプラインのAI機能設定ページに切り替え、ランナーとして`Langflow API`を選択します。

![set\_langflow\_runner](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/set_langflow_runner.png)

プロンプトに従って他の設定を入力します。`Base URL`(実際のネットワーク状況に応じて入力)、`API Key`、`Flow ID`などが含まれます。API KeyはLangflowの設定から取得できます:

![get\_api\_key](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/get_api_key.png)

Flow IDは、編集ページの右上にある`共有` -> `APIアクセス`ボタンをクリックし、サンプルコードから取得できます:

![get\_flow\_id](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/get_flow_id.png)

---

# LangBotでのn8nの使用

Source: https://langbot.app/docs/ja/usage/pipelines/n8n

n8n を LangBot と統合し、メッセージングプラットフォーム横断の AI ボットワークフローと自動化を実現。

[n8n](https://n8n.io/)は、さまざまな自動化タスクを作成、スケジュール、実行できるオープンソースのワークフロー自動化プラットフォームです。

LangBotは現在、n8nワークフローの`Webhook`ノードを通じてワークフローをトリガーし、レスポンスを受信することをサポートしています。

## ランナーとしてのn8nの使用

既存のパイプラインの設定ページを開くか、新しいパイプライン(推奨)を作成して設定ページを開いてください。`AI`で`n8n Workflow API`をランナーとして選択します。

![ランナーとしてのn8n](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_runner.png)

次に、以下の内容に従って他の設定を構成して入力します。

## n8nワークフロー接続の設定

![n8nワークフロー](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/create_wf.png)
または
![n8nワークフロー](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/create_wf01.png)

トリガーとして`Webhook`または`On chat message`を選択し、以下のように設定します:

- Webhook:
  ![n8n webhook設定](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_webhook.png)
- On chat message:
  ![n8n on chat message設定](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_n8n_onchatmessage.png)

> :
>
> ストリーミングレスポンスが必要な場合は、`Response Mode`を`Streaming`に設定します。
>
> ![n8nストリーミング設定](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_response_model.png)

> :
>
> 認証は、LangBotのパイプライン設定の認証方法に対応しており、必要に応じて変更できます。
>
> ![n8nワークフロー設定](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_auth.png)

AIモデルを呼び出すノードを`AI Agent`として設定し、以下のセットアップに従います:

> ストリーミングレスポンスの場合、赤い枠で強調表示されている項目を追加します。ストリーミングが不要な場合は、このステップをスキップできます。

![n8n AIモデル呼び出し設定](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_call_ai.png)

n8nのワークフローレスポンスコンテンツについては、`Respond to Webhook`ノードを使用し、以下の画像に従って設定してください(`AI Agent`ノードでストリーミングレスポンスを選択した場合、このステップは不要です):

![n8nワークフローレスポンス設定](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_respond.png)

`Response Body`のレスポンスコンテンツキー名は、LangBotのパイプライン設定の`出力キー名`と一致する必要があります。

n8nワークフロー設定の完了後、上部の`Active`をクリックしてワークフローを有効にしてください。

---

# 対話パイプライン (Pipelines)

Source: https://langbot.app/docs/ja/usage/pipelines/readme

LangBot のパイプラインは AI オーケストレーション基盤（Dify・Coze・n8n・Langflow）をボットに接続。仕組みを解説。

パイプラインは、メッセージを受信した後の処理フローと、大規模言語モデルとの情報交換を制御します。各ボットは1つのパイプラインにバインドでき、同じパイプラインは複数のボットにバインドできます。

LangBotは最初の起動時にデフォルトパイプラインを自動的に作成します。ボットを作成すると、自動的にデフォルトパイプラインにバインドされます。最初のモデルを作成すると、自動的にデフォルトパイプラインのモデルとして設定されます。

![arch](https://langbot.app/docs/images/zh/deploy/pipelines/arch.png)

異なるシナリオに適応するために、異なるボット用に複数のパイプラインを作成できます。

現在、パイプラインでは以下の機能を設定できます:

## AI機能

以下を選択して使用できます: `組み込みエージェント`、[`Dify`](https://dify.ai/)、[`n8n`](https://n8n.io/)

AI機能は主に2つの部分に分かれています: ランナーの選択とランナーパラメータの設定。

ランナーは、メッセージを処理するために大規模モデルをスケジュールする方法を定義します。デフォルトは`組み込みエージェント`で、これはLangBotによって実装された複数ラウンドのエージェント戦略です。このランナーが選択されている場合のみ、LangBot内で設定されたモデルとツールが使用されます。

![edit\_pipeline](https://langbot.app/docs/images/zh/deploy/pipelines/edit_pipeline_ai.png)

`Dify`、[`n8n`](https://n8n.io/)などの外部Agent プラットフォームを使用することもできます。この場合、使用されるモデル、プロンプト、ツール、その他のリソースはAgent プラットフォームによって提供されます。

![more\_runner](https://langbot.app/docs/images/zh/deploy/pipelines/more_runner.png)

- Difyへの接続の詳細手順は、[チュートリアルを参照](https://langbot.app/docs/ja/usage/pipelines/dify.md)してください。
- n8nへの接続の詳細手順は、[チュートリアルを参照](https://langbot.app/docs/ja/usage/pipelines/n8n.md)してください。

### 会話変数

外部Agent プラットフォームを使用する場合、LangBotは以下のパラメータを明示的に渡します。これらをAgent プラットフォームワークフローの開始ノードに追加できます(以下の画像はDifyの例です):

- `launcher_type`: ランチャーオブジェクトタイプ、プライベートチャットの場合は`person`、グループチャットの場合は`group`
- `launcher_id`: ランチャーオブジェクトID、プライベートチャットの場合はユーザーID、グループチャットの場合はグループID
- `sender_id`: 送信者ID
- `user_message_text`: ユーザーメッセージのプレーンテキスト
- `session_id`: ユーザーセッションID、プライベートチャットの場合は`person_<id>`、グループチャットの場合は`group_<id>`
- `conversation_id`: 文字列、ユーザーセッションID、LangBotによって生成されます。ユーザーがセッションをリセットした後に再生成されます
- `msg_create_time`: 数値型、このメッセージが受信されたタイムスタンプ(秒)
- `group_name`: グループ名、グループメッセージを受信した場合のみ設定されます
- `sender_name`: 送信者名

[プラグインを通じて任意の変数をカスタマイズできます](https://langbot.app/docs/en/plugin/dev/apis/common.md#set-request-variables)。

![Difyワークフロー開始ノード設定](https://langbot.app/docs/images/zh/workshop/dify-service-api/dify_workflow_var.png)

## その他の設定

設定フォームの説明を参照してください。

---

# LangBot で WeKnora を使用する

Source: https://langbot.app/docs/ja/usage/pipelines/weknora

WeKnora を LangBot と組み合わせ、AI メッセージングボットに知識ベース QA を追加。

[WeKnora](https://weknora.weixin.qq.com/) は、Tencent がオープンソース化した大規模言語モデル（LLM）ベースの文書理解・意味検索フレームワークであり、複雑な構造と異種コンテンツを持つ文書シナリオ向けに設計されています。\
フレームワークはモジュラーアーキテクチャを採用し、マルチモーダル前処理、意味ベクトルインデックス、インテリジェントリコール、大規模モデル推論を統合して、効率的で制御可能な文書 Q\&A ワークフローを構築します。コア検索プロセスは RAG（Retrieval-Augmented Generation）メカニズムに基づいており、文脈に関連する段落と言語モデルを組み合わせることで、高品質な回答生成を実現します。

LangBot は現在、WeKnora の `ナレッジベース Q&A（chat）` と `エージェント インテリジェント会話（agent）` の 2 つのアプリケーションタイプをサポートしています。

## WeKnora で API キーを取得する

[WeKnora 公式ドキュメント](https://github.com/Tencent/WeKnora) に従って WeKnora サービスをデプロイし、ナレッジベースの作成と文書のアップロードを完了してください。

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_api_lead.png)

デプロイ完了後、WeKnora の WebUI（デフォルト `http://localhost:80`）にアクセスし、`設定` -> `API キー` ページで `API キーを生成` をクリックし、コピーして保存してください。

> API キーとナレッジベース ID:
>
> - `API キー`：認証に使用されます。安全に保管し、漏洩しないでください。
> - `ナレッジベース ID`：ナレッジベース管理ページで各ナレッジベースの ID（`kb-00000001` の形式）を確認でき、LangBot で呼び出すナレッジベースを指定できます。

クリックすると、基本的な URL とキー情報を取得できます。

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_api_information.png)

> デプロイのヒント:
>
> - LangBot と WeKnora が同じホストにデプロイされ、どちらも Docker を使用してデプロイされている場合、次の記事を参照してください：[ネットワーク設定の詳細](https://langbot.app/docs/ja/workshop/network-details.md#langbot-およびメッセージプラットフォームが-docker-コンテナで実行されている場合)。WeKnora を起動する際に、コンテナを `langbot-network` に追加し、LangBot 設定の `API ベース URL` をコンテナ相互接続アドレス（例：`http://weknora-app:8080/api/v1`）に設定してください。
> - その他のシナリオについては、会社の運用チームにお問い合わせください。

## WeKnora エージェント情報を取得する

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_agent_lead.png)

「エージェント」ページで、選択したいエージェントをクリックして詳細ページに移動します。`エージェント設定` で `エージェント ID`（`builtin-smart-reasoning` の形式）を確認でき、`ツールリスト` でエージェントが呼び出せるツール名（`web-search`、`file-search` など）を確認できます。LangBot の設定時にこれらの情報が必要になります。

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_other_information.png)

これで WeKnora API に接続するために必要な情報が揃いました。次に、以下の手順に従って LangBot での設定を完了してください。

## LangBot の設定

LangBot WebUI ページを開き、新しいパイプラインを追加するか、既存のパイプラインで `AI 機能` 設定ページに切り替えます。

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/creat_langbot_pipeline.png)

1. `ランナー` で `WeKnora API` を選択します。
2. ランナーの設定項目に以下を入力します：
   - `API ベース URL`：WeKnora サービスの API アドレス、デフォルト `http://localhost:8080/api/v1`。
   - `API キー`：WeKnora で生成された API キーを貼り付けます。
   - `アプリケーションタイプ`：`agent`（エージェント インテリジェント会話、ツール呼び出し、ウェブ検索、思考チェーンをサポート）または `chat`（ナレッジベース RAG Q\&A）を選択します。
   - `エージェント ID`：組み込みエージェント識別子、一般的な値：
     - `builtin-smart-reasoning`：インテリジェント推論エージェント（`agent` モード推奨）
     - `builtin-quick-answer`：クイック回答エージェント（`chat` モード推奨）
   - `ナレッジベース ID リスト`：検索するナレッジベース ID（`kb-00000001` の形式）を入力します。複数入力可能です。
   - `ウェブ検索を有効化`：`agent` モードでのみ有効になり、有効にするとエージェントがウェブ検索ツールを呼び出せるようになります。
   - `タイムアウト（秒）`：リクエストのタイムアウト時間、デフォルト `120`。
   - `デフォルトプロンプト`：ユーザーがテキストコンテンツを送信しない場合に使用されるデフォルトの質問文。
3. `保存` をクリックして設定を完了します。

完了後、パイプラインで WeKnora を呼び出して、ナレッジベースに基づくインテリジェント会話を完了できます。

## 出力処理

- `agent` アプリケーションを使用する場合、LangBot パイプラインの `出力処理` で `track-function-calls` を有効にしていると、WeKnora がツール呼び出しを実行するたびに `関数 xxx を呼び出し中` というメッセージがユーザーに出力されます。
- WeKnora が返す `thinking`（思考チェーン）コンテンツは `<think>` タグで囲まれて送信され、フロントエンドで折りたたんで表示できます。
- WeKnora が返す `references`（ナレッジベースの引用元）は、回答の後に参照元メッセージとして添付されます。

## よくある質問

- **保存に失敗するか、呼び出しでエラー**：`API キー` と `API ベース URL` が正しいか確認してください。URL の末尾に `/api/v1` が含まれている必要があります。
- **ナレッジベースのコンテンツが返されない**：入力した `ナレッジベース ID` が正しいか、そのナレッジベースで文書が正常にアップロード・解析されているか確認してください。
- **`WeKnora API` を選択できない**：現在の LangBot バージョンがこのランナーをサポートしているか確認してください。サポートされていない場合は、WeKnora ランナーを含むバージョンにアップグレードしてください。

パイプラインの一般的な設定の詳細については、[会話パイプライン設定の変更](https://langbot.app/docs/ja/usage/pipelines/readme.md) を参照してください。

---

# DingTalk

Source: https://langbot.app/docs/ja/usage/platforms/dingtalk

LangBot で DingTalk AI ボットを構築。GPT・Claude・Dify 等を DingTalk のグループや会話に接続。

DingTalk に LangBot をデプロイします。

## 一键設定（おすすめ）

LangBot は DingTalk アプリのワンクリック作成とクレデンシャルの自動入力に対応しています。手動でのコピペは不要です。

1. LangBot WebUI を開き、**ボット > ボットを作成** に移動
2. ボット名を入力し、プラットフォーム/アダプターで `钉钉` を選択
3. 表示される **一键创建应用** エリアで **開始** ボタンをクリック

![一键创建應用](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_oneclick_qrcode.png)

4. DingTalk で QR コードをスキャンし、手机端で组织を選択

![組織を選択](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_select_org.png)

5. **新しいボットを作成** または **既存のボットを選択** できます

![作成または選択](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_create_or_select.png)

6. 認証成功後、手机端に「設定成功」と表示され、Client ID と Client Secret が LangBot WebUI に**自動入力**されます

![設定成功](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_config_success.png)

7. **ボット名を手動で入力**（DingTalk のボット名と一致させる必要があります）と**ロボットコード**（画像/ファイル機能に必須、DingTalk 開発者コンソール > ボット設定から取得）を入力

![名前とコードの入力](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_fill_name_and_code.png)

8. **送信** をクリックして完了

> warning:
>
> 一键設定後、テキストの送受信はすぐに利用できます。ただし：
>
> - **画像/ファイル対応**：ロボットコード（RobotCode）の入力が必要です。一键設定時に未入力の場合は、DingTalk 開発者コンソール > ボット設定から取得して入力してください
> - **ストリーミング返信**：カードテンプレート ID の手動設定が必要です。下記「ボットの設定」のカードテンプレート作成セクションを参照してください

***

## 手動設定

### ボットの作成

[DingTalk 開発者バックエンド](https://open-dev.dingtalk.com/?spm=ding_open_doc.document.0.0.74f445e5MkawbT#/)にアクセスし、ログインして組織に入ります。ログインに成功したら、オープンプラットフォームに入ります。以下のように表示されます：
![DingTalk Open Platform](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk1.png)

上部の「アプリケーション開発」をクリックし、右側の青いボタン「アプリケーションを作成」をクリックして、ボットの基本情報を入力し、保存をクリックします。

ボットのバックエンドに入ります。例えば、langbot2 という名前のボットがある場合、管理ページは以下のように表示されます：
![Bot Page](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk2.png)

### ボットの設定

「アプリケーション機能を追加」、「その他のアプリケーション機能」、「ロボット」の「設定」をクリックし、設定をクリックして情報を入力します。以下のように：
![Bot Configuration](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk3.png)

ページ下部の「公開」をクリックし、公開が成功したら、ボットページの左下にある「バージョン管理と公開」をクリックします。以下のように：
![Version Management and Publishing](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk4.png)

初めてボットを作成する場合、右側は空なので、「新しいバージョンを作成」をクリックし、その中で情報を設定し、「アプリケーションの表示範囲」を設定して、保存をクリックします。

「イベントサブスクリプション」をクリックし、プッシュ方式を「ストリームモードプッシュ」に変更します。

カードストリーミングが必要な場合は、権限管理でカード権限を申請する必要があります。以下のように：
![Before applying for card permissions](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk6.png)

![After applying for card permissions](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk7.png)

さらに、カードメッセージの場合、主にカードテンプレートを作成し、テンプレート ID を記録して設定に入力する必要があります。手順は以下の通りです：

> カードコンテンツテンプレート ID は、開発者バックエンドにログイン > [カードプラットフォーム](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV)から取得できます

新しいテンプレートを作成する際に情報を入力します。以下のように：
![Fill in information for new template](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk8.png)

プリセットテンプレートを選択します（最初のものを選択し、後でテンプレートの内容を変更します）。以下のように：
![Select preset template](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk9.png)
使用をクリック
![Click](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk10.png)
作成
![Create](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk11.png)

作成をクリックすると、テンプレートの編集にリダイレクトされます。以下のように、希望するカードメッセージを自由に編集できます：
![Edit template](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk12.png)

メインコンテンツについては、デフォルトの「content」をそのままにしておきます：
![Don't modify](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk13.png)

ワイドスクリーン設定パラメータ。テンプレート変数に . を追加する必要があります。参考[DingTalk ワイドスクリーン設定](https://open.dingtalk.com/document/development/configure-widescreen-cards)
![Widescreen Configuration](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk16.png)

編集を終え、すべて正しいことを確認したら、保存してテンプレート ID をコピーし、設定ファイルに入力します：
![Save](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk14.png)
![Copy template ID](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk15.png)

### 設定情報の入力

「認証情報と基本情報」をクリックし、「Client ID」と「Client Secret」を記録します。
「アプリケーション機能」、「ロボット」をクリックし、RobotCode とロボット名を記録します。
`markdown_card` は Markdown 形式の返信を有効にするかどうかです。この設定項目が無効になっている場合、`@送信者` 設定スイッチは有効になりません。
上記の設定項目を記録し、LangBot ボット設定フォームに入力します

[カードプラットフォーム](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV)をクリックし、テンプレートリストから対応するバインドされたテンプレート ID をコピーし、カードテンプレート ID フィールドに入力します。

![Connect to LangBot](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/connect_to_langbot.png)

ストリーミング関連：
![img.png](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk17.png)

**LangBot を起動します**。

### ボットの追加

この記事では DingTalk Windows デスクトップ版を例として使用します。上部の「検索」、「機能」をクリックし、先ほど作成したボットの名前を入力します。以下のように：
![robot\_png](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk5.png)

ボットをクリックしてチャットします。

グループに追加したい場合は、DingTalk グループの「グループ管理」、「ロボット」、「ロボットを追加」をクリックし、ボット名を検索してグループで使用します。

---

# Discord

Source: https://langbot.app/docs/ja/usage/platforms/discord

LangBot で Discord AI ボットを構築。GPT・Claude・Gemini・DeepSeek・Dify を数分で Discord サーバーに接続。

## ボットの作成

[Discord Developer Portal](https://discord.com/developers/applications)にアクセスし、ログインしてアプリケーションを作成します。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_01.png)

基本情報を変更し、「Save Changes」をクリックして保存します。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_02.png)

左側の「Bot」をクリックし、「Reset Token」をクリックして、生成された Token をコピーします。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_03.png)

そして、このページの「Privileged Gateway Intents」のすべてのオプションをチェックし、「Save Changes」をクリックして保存します。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_05.png)

**最後に、左側の「OAuth2」をクリックし、ページの「Client ID」をコピーします。**

## LangBot に接続

新しいボットを追加するためにクリックし、前の手順で取得した「Client ID」と「Token」を設定に入力します。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/connect_to_langbot.png)

> :
>
> 中国本土内でこのアダプターを使用している場合、ネットワークプロキシを設定する必要がある場合があります。

入力後、LangBot を起動します。設定が成功した場合、ログに `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: discord` と表示されます。LangBot を実行し続けてください。

## ボットをサーバーに招待

まずサーバーを作成し、次にボットをサーバーに招待する必要があります。

「OAuth2」ページに移動し、「URL Generator」を選択し、「bot」を選択して、画像に示されている権限をチェックします。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_06.png)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_07.png)

「Copy」をクリックし、生成された URL をブラウザに貼り付けて開き、ボットをサーバーに招待します。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_08.png)

## ボットの使用

グループまたはプライベートメッセージでボットを通常どおり使用できるようになりました。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_09.png)

---

# HTTP ボット

Source: https://langbot.app/docs/ja/usage/platforms/http-bot

任意のバックエンドを HTTP で LangBot に接続：署名付き Webhook でメッセージを送信し、コールバック URL で返信を受信。サーバー間連携、長時間接続不要。

`HTTP ボット`アダプターは、**任意のバックエンドシステム**を LangBot パイプラインに接続します。チケットシステム、CRM、社内ツール、自作 Web アプリなど、すべてこれを通じてパイプラインを駆動できます。

- **受信**：バックエンドが署名付きメッセージを LangBot の固定 URL に `POST` します；
- **送信**：LangBot が返信を設定済みのコールバック URL に `POST` します。

**長時間接続は不要**で、パイプラインの 2 つのネイティブ機能を完全に保持します。

- **メッセージ集約（N→1）**：ユーザーが連続して複数のメッセージを送ると、1 ターンにまとめて処理；
- **マルチパート返信（1→M）**：1 ターンで複数の返信が発生し得る（関数呼び出し、複数メッセージのプラグイン、ストリーミング分割）。

> info:
>
> **ブラウザ内**のリアルタイムチャットウィジェットが必要な場合は、[ページボット](https://langbot.app/docs/ja/usage/platforms/webpage.md)を使用してください。HTTP ボットはバックエンド間連携のために設計されています。

## 仕組み

```
バックエンド  ──(1) 署名付きメッセージを POST──►  LangBot   /bots/<bot_uuid>
                                              （パイプライン：集約 → 推論 → 返信）
コールバック  ◄─(2) 署名付き返信を POST──────   LangBot   返信パートごとに 1 回 POST
```

- **(1) 受信**は「まず受け取り、後で処理」：LangBot は即座に `202 Accepted` を返し、そのレスポンスにパイプライン結果は**含めません**；
- **(2) 送信**返信は後で、独立した署名付き POST としてあなたの `callback_url` に届きます。1 ターンで複数回のコールバックが発生し得ます；
- すべては**あなたが指定する `session_id`**（例：チケット番号）をキーとし、各 `session_id` は 1 つの独立したセッションに対応します。

## ボットの作成

LangBot WebUI で**ボット > ボット作成**に進み、名前を入力し、プラットフォーム/アダプターに `HTTP ボット` を選択します。

## 設定項目

| 設定項目            | 必須  | 説明                                                          |
| --------------- | --- | ----------------------------------------------------------- |
| 受信署名シークレット      | はい  | バックエンドが受信リクエストの HMAC-SHA256 署名に使用。LangBot は受信ごとに検証します。      |
| 送信コールバック URL    | はい  | LangBot が返信を POST する先。**設定からのみ**取得し、メッセージ単位で上書き不可（SSRF 対策）。 |
| 送信署名シークレット      | いいえ | LangBot がコールバックの署名に使用。空の場合は受信シークレットを使用。                     |
| デフォルトセッションタイプ   | いいえ | `person`（既定）または `group`。                                    |
| 受信署名を必須にする      | いいえ | 本番環境では有効のままに。                                               |
| コールバックタイムアウト（秒） | いいえ | コールバックごとの HTTP タイムアウト、既定 15。                                |
| コールバック最大リトライ回数  | いいえ | タイムアウトまたは 5xx 時に指数バックオフでリトライ、既定 3。                          |

**パイプライン**にバインドして**有効化**すると、設定ページに**受信 Webhook URL**（`https://your-langbot/bots/<bot_uuid>` の形式）が表示されます。コピーしてください。

## 署名スキーム

両方向で同じ依存関係なしの HMAC-SHA256 スキームを使用します。

```
signing_string = "{timestamp}." + 生のリクエストボディのバイト列
signature      = "sha256=" + hex(HMAC_SHA256(secret, signing_string))
```

ヘッダーで送信します。

| ヘッダー                   | 意味                                           |
| ---------------------- | -------------------------------------------- |
| `X-LB-Timestamp`       | Unix 秒。サーバー時刻と **±300 秒**以上離れていると拒否。         |
| `X-LB-Signature`       | `"{timestamp}." + body` に対する `sha256=<hex>`。 |
| `X-LB-Idempotency-Key` | （任意、受信）重複排除キー。再送は `409` を返す。                 |

送信コールバックの検証も同様に、**送信シークレット**（空なら受信シークレット）を使用します。

## 最初のメッセージを送る（curl）

```bash
BOT="https://your-langbot/bots/<bot_uuid>"
SECRET="あなたの受信シークレット"
BODY='{"session_id":"ticket-10293","message":[{"type":"Plain","text":"ダッシュボードでエクスポートが失敗し続けます。"}]}'
TS=$(date +%s)
SIG="sha256=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)"

curl -sS -X POST "$BOT" \
  -H "Content-Type: application/json" \
  -H "X-LB-Timestamp: $TS" \
  -H "X-LB-Signature: $SIG" \
  -d "$BODY"
# -> 202 {"code":0,"msg":"accepted","data":{"session_id":"ticket-10293","accepted_message_id":"in_...","aggregating":true}}
```

返信はまもなく設定済みのコールバック URL に POST されます。

## 受信リクエスト形式

`POST /bots/{bot_uuid}`

```json
{
  "session_id": "ticket-10293",
  "session_type": "person",
  "sender": { "id": "user-5567", "name": "Alice" },
  "message": [
    { "type": "Plain", "text": "ダッシュボードでエクスポートが失敗し続けます。" },
    { "type": "Image", "url": "https://example.com/screenshot.png" }
  ]
}
```

- `session_id`（**必須**）：あなたの安定した識別子、1 つの LangBot セッションに 1:1 対応；
- `message`（**必須**）：LangBot メッセージチェーン。テキストは `{"type":"Plain","text":"..."}`、画像は `{"type":"Image","url":"..."}`（または `base64`）；その他 `Voice`、`File`、`At`、`Quote` をサポート。

> warning:
>
> コールバック URL はボディでは**受け付けず**、ボット設定からのみ取得します。これは意図的な設計です：受信シークレットが漏洩しても、攻撃者が返信を任意のホストにリダイレクトすることはできません。

### メッセージ集約（N → 1）

パイプラインで**メッセージ集約**が有効な場合、**同じ `session_id`** で集約ウィンドウ内に複数のメッセージを送ると、**1 ターン**にまとめられます。特別なフラグは不要、`session_id` を再利用するだけです。

## 送信コールバック形式

LangBot は各返信パートをコールバック URL に POST します。

```json
{
  "session_id": "ticket-10293",
  "reply_to": "in_01H...",
  "sequence": 1,
  "is_final": false,
  "stream": false,
  "message": [ { "type": "Plain", "text": "調査中です…" } ],
  "timestamp": "2026-06-22T09:00:01Z"
}
```

受信側は速やかに `2xx` を返してください。2xx 以外やタイムアウトの場合、LangBot は指数バックオフでリトライします。

### マルチパート返信（1 → M）

1 ターンで複数のコールバックが発生し得て、同一セッションには `sequence` 順で届きます。

```
seq=1 is_final=false  "エクスポートログを確認中…"
seq=2 is_final=false  "失敗したエクスポートが 2 件見つかりました。"
seq=3 is_final=true   "修正しました。再試行してください。"
```

`session_id` + `sequence` で結合します。`is_final: true` が届いたらそのターンは完了です。

## セッションのリセット

ある `session_id` の会話を新規に開始（履歴を破棄）します。

```
POST /bots/{bot_uuid}/reset
{ "session_id": "ticket-10293", "session_type": "person" }
→ 200 { "code":0, "msg":"reset", "data": { "session_id":"ticket-10293", "removed": true } }
```

署名方法は受信メッセージと同じです。

## 同期便利モード

ストリーミング/マルチパートが不要で、同じ HTTP 呼び出しで返信を受け取りたい場合は `/sync` に POST します。LangBot はターンの終了を待ち、すべての返信パートを 1 つの配列に**まとめて**返します。

```
POST /bots/{bot_uuid}/sync
{ "session_id": "ticket-10293", "message": [ { "type":"Plain", "text":"こんにちは" } ] }
→ 200 { "code":0, "msg":"ok",
        "data": { "session_id":"ticket-10293", "reply_to":"in_...", "message": [ ... ] } }
```

> warning:
>
> 同期モードは**ロスあり**（`sequence` とストリーミング境界が失われる）で、最大 `コールバックタイムアウト × 4` 秒ブロックします。リアルタイムやマルチパートの場合はコールバックモードを優先してください。`session_id` ごとに進行中の `/sync` は 1 つのみです。

## エラーコード

```json
{ "code": 40101, "msg": "invalid signature: signature_mismatch", "data": null }
```

| HTTP | code  | 意味                                    |
| ---- | ----- | ------------------------------------- |
| 202  | 0     | 受理                                    |
| 400  | 40001 | ボディ不正 / `session_id` または `message` 欠如 |
| 401  | 40101 | 署名が不正または期限切れ                          |
| 409  | 40901 | 冪等キーの重複                               |
| 413  | 41301 | メッセージが大きすぎる（>1 MiB）                   |
| 500  | 50001 | 内部エラー                                 |

## リファレンスクライアントと 5 分デモ

メインリポジトリの [`examples/http-bot/`](https://github.com/langbot-app/LangBot/tree/master/examples/http-bot) には**インタラクティブなプレイグラウンド**と Python / TypeScript のリファレンスクライアントがあります。

### インタラクティブ・プレイグラウンド（まずこれを実行）

[`playground.py`](https://github.com/langbot-app/LangBot/blob/master/examples/http-bot/playground.py) は単一ファイルの Web アプリです:ブラウザでメッセージを入力 → 署名して**稼働中**の `http_bot` ボットへ POST → 返信がページにストリーム表示され、右側のデバッグパネルに署名・`202` 確認・各コールバックの `sequence` と検証結果が表示されます。

```bash
# LangBot リポジトリのルートで、バックエンドが稼働している状態で:
PUBLIC_IP=<あなたのホストIP> ./.venv/bin/python examples/http-bot/playground.py
# その後  http://<あなたのホストIP>:8920/  を開く
```

起動時に `data/langbot.db` から API Key と `http_bot` ボットを読み取り、LangBot API 経由でそのボットの `callback_url` とシークレットを自分自身に向けます(ボットはライブリロード、再起動不要)。有効化され、動作するパイプラインにバインドされた `http_bot` ボットが必要です。

### コマンドラインのリファレンスクライアント

[`examples/http-bot/`](https://github.com/langbot-app/LangBot/tree/master/examples/http-bot) には Python と TypeScript のリファレンスクライアント（コールバックレシーバー付き）もあります。

```bash
cd examples/http-bot
pip install flask requests

# ターミナル 1：コールバックレシーバー（ボットの callback_url をここに向ける。ローカルは cloudflared / ngrok で）
python client.py serve --port 8900 --secret SHARED_SECRET

# ターミナル 2：メッセージを送信
python client.py push \
  --url https://your-langbot/bots/<bot_uuid> \
  --secret SHARED_SECRET \
  --session ticket-1 \
  --text "こんにちは"
```

ターミナル 1 が各返信パート（`[part ]` / `[FINAL]`）をシーケンス番号付きで表示します——これが署名検証済みの 1→M マルチパート返信のライブ動作です。

機械可読の契約はメインリポジトリの [`docs/http-bot-openapi.json`](https://github.com/langbot-app/LangBot/blob/master/docs/http-bot-openapi.json) にあります。

## セキュリティチェックリスト

- 本番環境では**受信署名を必須にする**を有効に；
- コールバック URL は **HTTPS** を使用し、設定でのみ指定（メッセージ単位の上書き不可）；
- シークレットはパスワードと同様に扱い、ダッシュボードでローテーション；
- 受信ルートはフレームワークレベルで未認証です（**意図的な設計**）。セキュリティは完全に HMAC 署名に依存するため、公開デプロイでは絶対に無効化しないでください。

---

# KOOK

Source: https://langbot.app/docs/ja/usage/platforms/kook

LangBot で KOOK AI ボットを構築。大規模言語モデルを KOOK（開黒啦）チャンネルに接続。

## ボットの作成

[KOOK Developer Center](https://developer.kookapp.cn/)にアクセスし、ログインしてコンソールにアクセスします。

![KOOK Developer Console](https://langbot.app/docs/images/zh/deploy/bots/kook/01-dashboard.png)

「アプリケーションを作成」をクリックし、アプリケーション情報を入力します。

![Create Application](https://langbot.app/docs/images/zh/deploy/bots/kook/02-create-app.png)

アプリケーションが作成されたら、アプリケーション詳細ページに入ります。

![Application Created](https://langbot.app/docs/images/zh/deploy/bots/kook/03-app-created.png)

アプリケーション概要ページでアプリケーションの基本情報を表示できます。

![Application Overview](https://langbot.app/docs/images/zh/deploy/bots/kook/04-app-overview.png)

## Bot Token の取得

アプリケーションページで、「Bot」タブをクリックし、Bot Token をコピーして安全に保存します。後で必要になります。

![Get Bot Token](https://langbot.app/docs/images/zh/deploy/bots/kook/05-bot-token.png)

## ボット権限の設定

**重要：**「Bot」設定で、「メッセージフィルタリング」オプションを見つけてクリックして設定します。

![Message Filter Settings](https://langbot.app/docs/images/zh/deploy/bots/kook/07-message-filters.png)

チャンネルメッセージやプライベートメッセージイベントを含む、すべてのメッセージ関連イベント権限を有効にします。そうしないと、ボットはメッセージを受信できません。

![Enable Permissions](https://langbot.app/docs/images/zh/deploy/bots/kook/08-permissions-enabled.png)

## ボットの招待

ボット設定ページで、招待リンクを生成してボットをサーバーに招待できます。

![Generate Invitation Link](https://langbot.app/docs/images/zh/deploy/bots/kook/06-invite-link.png)

## LangBot に接続

LangBot Webui ページを開き、「Bots」ページで新しいボットを作成するためにクリックします。

![LangBot Bot Management](https://langbot.app/docs/images/zh/deploy/bots/kook/09-langbot-bots.png)

KOOK プラットフォームを選択し、ボット名と Bot Token を入力します。

![Configure KOOK Bot](https://langbot.app/docs/images/zh/deploy/bots/kook/10-bot-config.png)

保存後、ボットがリストに表示されます。

![Bot Created](https://langbot.app/docs/images/zh/deploy/bots/kook/11-bot-created.png)

有効化ボタンをクリックしてボットを起動します。正常に設定されている場合、ボットのステータスは実行中として表示されます。

![Bot Enabled](https://langbot.app/docs/images/zh/deploy/bots/kook/12-bot-enabled.png)

## ボットの使用

KOOK サーバーで、ボットは正常にメッセージを受信して返信できるようになりました。ボットはチャンネルメッセージとプライベートメッセージの両方をサポートしています。

---

# Feishu

Source: https://langbot.app/docs/ja/usage/platforms/lark

LangBot で Feishu/Lark AI ボットを構築。GPT・Claude・Dify 等を Feishu のグループやメッセージに接続。

## プラットフォームドメインの選択

ボットを作成する際、**アダプター設定**で**プラットフォームドメイン**を選択する必要があります：

- **飞书 (open.feishu.cn)**：国内の飛書ユーザー向け（デフォルト）
- **Lark (open.larksuite.com)**：海外のLarkユーザー向け
- **カスタム (custom)**：プライベートデプロイユーザー向け

![プラットフォームドメインの選択](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_platform_domain.png)

> warning:
>
> 海外版のLarkを選択する場合、`open.larksuite.com`ドメインを使用してください。そうしないと、接続に失敗する可能性があります。プライベートデプロイユーザーは、実際のデプロイアドレスに応じてカスタムを選択し、対応するドメインを入力してください。

## 一键設定（おすすめ）

LangBot は Feishu アプリのワンクリック作成とクレデンシャルの自動入力に対応しています。手動でのコピペは不要です。

1. LangBot WebUI を開き、**ボット > ボットを作成** に移動
2. ボット名を入力し、プラットフォーム/アダプターで `飞书` を選択
3. 表示される **一键创建应用** エリアで **開始** ボタンをクリック

![一键创建飞书应用](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_oneclick_qrcode.png)

4. 飛書で QR コードをスキャンし、手机端で飞書開放平台のボット作成ページが表示されます
5. **既存のアプリを使用** または **新規作成** を選択できます：

![手机端で選択](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_select_or_create_bot.png)

既存のアプリを選択すると、アプリ一覧が表示されます：

![既存アプリを選択](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_select_existing.png)

6. 認証成功後、手机端に「設定成功」と表示され、app\_id と app\_secret が LangBot WebUI に**自動入力**されます

![設定成功](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_config_success.png)

7. **ボット名を手動で入力** — 飛書のボット名と一致させる必要があります。一致しない場合、グループ内でメッセージを受信できません

![ボット名の入力](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_fill_bot_name.png)

8. **送信** をクリックして完了

***

## ボットの作成

[Feishu Open Platform](https://open.feishu.cn/app)にアクセスし、ログインして、企業の自己構築アプリケーションまたはストアアプリケーションを作成します。[(違いの紹介)](https://open.feishu.cn/document/platform-overveiw/overview)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_01.png)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_02.png)

アプリケーションにボット機能を追加します：
![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_03.png)

権限管理で画像に示されている権限を追加します：

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_04.png)

カードストリーミング権限が必要な場合は、画像に示されている次のカード作成と更新権限を追加します：

![img\_1.png](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_14.png)

> warning:
>
> デフォルトのカードテンプレートを変更する必要がある場合は、プラットフォームアダプターのコードでカードテンプレートを自分で修正する必要があります。

### LangBot に接続

「認証情報と基本情報」ページで `app_id` と `app_secret` を見つけます。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_05.png)

LangBot の Webui 設定ページを開き、新しいボットを作成します

フォームに関連情報を入力します

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/connect_to_langbot.png)

ストリーミング関連：
![Streaming related](https://langbot.app/docs/images/zh/deploy/bots/lark/connect_to_langbot01.png)

入力後、LangBot を起動します。設定が成功した場合、ログに `[01-29 23:42:56.796] manager.py (68) - [INFO] : Initializing platform adapter 1: lark` と表示されます。LangBot を実行し続けてください。

> :
>
> デフォルトでは、WebSocket 長時間接続モードが使用されます。これは以下の長時間接続サブスクリプションに対応しています。ただし、場合によっては（国際版の Feishu など）、長時間接続モードが利用できない場合があります。その場合は、Webhook モードを使用する必要があります。これは、「開発者サーバーにイベントを送信」モードに対応しています。次の設定を参照してください：
>
> - `enable-webhook`：`true` に設定
> - `encrypt-key`：「イベントとコールバック」ページの「暗号化戦略」の「Encrypt Key」に設定
>
> Webhook モードでは、LangBot をパブリック IP を持つサーバーにデプロイし、ファイアウォールが上記で設定したポートを開いていることを確認する必要があることに注意してください。

> idea:
>
> **パブリックサーバーがありませんか？** [LangBot Cloud](https://space.langbot.app/cloud) にはドメインと HTTPS が含まれており、Lark ボットをすぐに使用できます。

### イベントサブスクリプションの設定

「イベントとコールバック」ページに移動し、サブスクリプション方式を「長時間接続」として設定します：

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_07.png)

そして、イベント：「メッセージを受信」を追加します

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_08.png)

`コールバック設定`を設定し、長時間接続のコールバックを選択します（webhook の場合は webhook を使用）

![コールバック設定](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_16.png)

コールバック`カードコールバックインタラクション`を追加します

![コールバックを追加](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_17.png)

> :
>
> Webhook モード設定方法：
>
> ![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_13.png)
>
> まず LangBot を起動してください。ここに LangBot から取得した Webhook アドレスを入力します。

### ボットの公開

上部の「バージョンを作成」をクリックし、バージョン番号とその他の情報を入力し、下部の「保存」をクリックします。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_09.png)

ボットを Feishu グループに追加して使用します：

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_10.png)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_11.png)

プライベートチャットでも直接使用できます

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_12.png)

## よくある問題

- ストアアプリのボットは、作成/保存直後にチャットメッセージに応答できません。[app\_ticket イベント](https://open.feishu.cn/document/server-docs/application-v6/event/app_ticket-events)の遅延メカニズムにより、正常に動作するまで約 2 分待つ必要があります。

---

# LINE

Source: https://langbot.app/docs/ja/usage/platforms/line

LangBot で LINE AI ボットを構築。大規模言語モデルを LINE のチャットや公式アカウントに接続。

この記事では、LangBot を LINE プラットフォームと接続して LINE ボット機能を実装する方法について説明します。

## LINE ボットの作成

### LINE 開発者アカウントの登録

1. [LINE Developers ウェブサイト](https://developers.line.biz/)にアクセスし、LINE アカウントでログインします
2. ログイン後、開発者コンソールに入ります

### Provider と Channel の作成

> [Developer Console](https://developers.line.biz/console)

1. 開発者コンソールで、新しい Provider を作成します（ない場合）
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line01.png)

2. Provider の下で、「Create」をクリックします
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line02.png)

3. 名前を入力して Create をクリックします
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line03.png)

4. リダイレクト後、Message API の作成を選択します
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line04.png)

- Message API の作成をクリックして続行します
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line05.png)
- リダイレクト後、基本情報を入力します
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line06.png)
  - Channel Name
  - Channel Description
  - Category
  - Subcategory
  - Email Address

5. すべての情報を入力したら、「Continue」をクリックして作成します
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line07.png)
6. 入力した情報を確認し、問題がなければ Submit をクリックします
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line08.png)
7. 正常に作成されました。使用に進みます
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line09.png)

### 設定情報の取得

作成後、次の重要な情報を取得します。記録してください：

1. Channel Secret

> [使用をクリックした後のページ](https://manager.line.biz/account)

- Settings を選択
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line09.png)
- Message API をクリック
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line11.png)
- Message API を有効にします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line12.png)
- 作成したばかりの Provider を選択し、Agree をクリックします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line13.png)
- プライバシー規約については、単に OK をクリックします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line14.png)
- OK をクリックして作成を完了します
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line15.png)
- コピーします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line16.png)

2. Channel Access Token（「Issue」ボタンをクリックして生成する必要があります）

- console をクリックするか、直接 [Console](https://developers.line.biz/console/) にアクセスします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line17.png)
- 作成した Provider を選択し、Message API をクリックします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line18.png)
- Message API をクリックします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line19.png)
- 一番下までスクロールし、Issue をクリックします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line20.png)
- アイコンをクリックしてコピーします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line21.png)

## LangBot に接続

次に、LangBot 設定ページを開きます：

1. 「Bots」をクリックし、次に「Add」をクリックします
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line26.png)

2. 「Platform/Adapter Selection」で「LINE」を選択します
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line27.png)

3. 設定情報を入力します：
   - Channel Secret：以前に取得した Channel secret
   - Channel Access Token：以前に取得した Channel access token
     ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line28.png)

4. 「Save」をクリックして設定を完了します
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line29.png)

## Webhook の設定

> info:
>
> まず、[HTTP リバースプロキシの設定](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md)を参照して LangBot コールバックアドレスを設定することをお勧めします。

> idea:
>
> **パブリックサーバーとドメインの設定が不要です。** [LangBot Cloud](https://space.langbot.app/cloud) にはドメインと HTTPS が含まれており、すぐに使用できます。

- LangBot 設定ページから Webhook コールバック URL を取得します
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line30.png)

- console をクリックするか、直接 [Console](https://developers.line.biz/console/) にアクセスします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line17.png)

- 作成した Provider を選択し、Message API をクリックします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line18.png)

- Message API をクリックします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line19.png)

- Edit をクリックして接続を入力します
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line22.png)

- 接続を入力します（HTTPS 接続である必要があります。つまり、SSL 証明書が必要です）、Update をクリックします
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line23.png)

- Use Webhook を選択します
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line24.png)

5. 「Verify」ボタンをクリックして、接続が成功したかどうかをテストします
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line25.png)

## 機能設定

LINE 開発者コンソールで、ボットの機能をさらに設定できます：

1. 「Messaging API」タブで、「LINE Official Account Features」セクションを見つけます
2. 必要に応じて次の機能を有効または無効にします：
   - 自動返信メッセージ
   - 友達追加時のウェルカムメッセージ
   - グループおよび複数人チャット
   - ボットがグループに参加したときの挨拶

## 使用方法

設定後、ユーザーは次の方法で LINE ボットとやり取りできます：

1. LINE 開発者コンソールで提供される QR コードをスキャンして、ボットを友達として追加します
2. チャットでメッセージを送信すると、ボットは LangBot を通じて処理して返信します

## よくある問題

### Webhook 検証失敗

- サーバーが HTTPS 経由でアクセスできることを確認してください
- Webhook URL が正しいかどうかを確認してください
- LangBot サービスが正常に実行されていることを確認してください

### メッセージを受信できない

- Channel Access Token が有効かどうかを確認してください
- 「Use Webhook」オプションが有効になっていることを確認してください
- LangBot ログでエラーメッセージを確認してください

### 権限の問題

- LINE 開発者コンソールでボットに必要な権限を有効にしていることを確認してください
- 一部の高度な機能には、LINE Premium アカウントが必要な場合があります

---

# Mattermost

Source: https://langbot.app/docs/ja/usage/platforms/mattermost

LangBot に Mattermost ボットを接続し、エージェントやワークフローを数分で Mattermost サーバーに導入します。

> info:
>
> 以下のスクリーンショットは中国語の画面です。本文で説明する対応するメニューや入力欄を参照して操作してください。

## ボットアカウントの作成

Mattermost インスタンス（セルフホスト版または Mattermost が提供するホスト版）にログインします。左上の `Mattermost アイコン`をクリックし、メニューから「統合機能（Integrations）」を選択します。

![Mattermost メニューから統合機能を開く](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_main_page.png)

統合機能のページで、左側のメニューから「ボットアカウント（Bot Accounts）」を選択し、右上の「ボットアカウントを追加（Add Bot Account）」をクリックします。

![ボットアカウントの一覧から新しいアカウントを追加する](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_account.png)

ボットのユーザー名を入力します。

![ボットのユーザー名を入力する](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_add_new.png)

ロールは「メンバー（Member）」を選択します（管理者向けの機能には現在対応していません）。ダイレクトメッセージが必要な場合は `post:all`、公開チャンネルのみを使用する場合は `post:channels` だけを選択します。右下の「ボットアカウントを作成（Create Bot Account）」をクリックします。

![ボットのロールと投稿権限を選択する](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_deploy.png)

ボタンをクリックしてトークンをコピーします。トークンは一度しか表示されないため、安全な場所に保存してください。右下の「完了（Done）」をクリックします。

![アカウント作成を完了する前にボットのトークンをコピーする](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_token.png)

## LangBot でのボット設定

LangBot Cloud またはセルフホストの LangBot インスタンスを開き、以下の画像の赤い矢印の順に操作します。

- 左側の「ボット」タブにカーソルを合わせ、表示される `+` アイコンをクリックします。
- 「ボット名」欄にボットの名前を入力します。
- プラットフォームアダプターのドロップダウンを開き、`Mattermost` を選択します。
- Mattermost インスタンスのアドレスと、先ほど作成したボットアカウントのトークンを入力します。
- （任意）パイプラインまたは AI プロバイダーがストリーミング出力に対応していない場合は、このオプションを無効にします。
- 右上の「送信（Submit）」をクリックすると、ボットの編集画面が開きます。

![LangBot に Mattermost ボットを追加し、インスタンスのアドレスとトークンを入力する](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_langbot_add_new.png)

既存のパイプラインを紐付け、必要に応じてルーティングを設定し、右上の「保存（Save）」をクリックします。

![パイプラインを紐付けて Mattermost ボットの設定を保存する](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_langbot_deploy.png)

---

# Lagrange

Source: https://langbot.app/docs/ja/usage/platforms/qq/aiocqhttp/lagrange

Lagrange（aiocqhttp）経由で QQ を LangBot に接続。QQ のグループ・個人チャットで AI ボットを運用。

## Lagrange の紹介

Lagrange は、軽量で比較的安定した QQNT プロトコルリバースエンジニアリングフレームワークです。OneBot 11 プロトコルを通じて接続します。アダプターとして `OneBot v11` を選択する必要があります。

> warning:
>
> ボットとやり取りするには NT QQ を使用する必要があります。古いバージョンの QQ は正常に動作しません

## デプロイ手順

以下は Windows の一般的な手順のみを提供します。詳細な手順または他のプラットフォームについては、[Lagrange 公式ドキュメント](https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/)を参照してください

### 環境設定

.NET 8 ランタイムをインストールします。[ここをクリックして Microsoft の公式ウェブサイトから直接ダウンロード](https://dotnet.microsoft.com/zh-cn/download/dotnet/thank-you/runtime-desktop-8.0.4-windows-x64-installer)

### Github Actions から最新のビルドをダウンロード

Github にログインしてダウンロードする必要があります。特定の機能が必要ない場合は、Release からダウンロードできます。画像 3 を参照してください

[Github Actions](https://github.com/KonataDev/Lagrange.Core/actions)

画像に従ってダウンロードします：

![Image 1](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_1.png)

![Image 2](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_2.png)

![Image 3](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_3.png)

### 最終ステップ

ダウンロードした zip を解凍し、Lagrange.OneBot.exe を含むディレクトリに移動し、このディレクトリで cmd コマンドプロンプトを開き、次のように入力します

```bash
.\Lagrange.OneBot
```

一度実行します。QR コードが出力された場合、ボットアカウントで直接スキャンしてログインできます（QR コードが不鮮明な場合は、lagrange data ディレクトリで画像ファイルを探すことができます）。

ログインできない場合は、lagrange 設定ファイル appsettings.json で署名アドレス SignServerUrl を正しく入力したかどうかを確認してください。署名アドレスは lagrange ドキュメントで確認してください。

## 設定の変更

Lagrange を LangBot に接続するように設定する必要があります。Lagrange の設定ファイル appsettings.json を編集し、Implementations の接続設定が以下の画像の内容と一致することを確認してください：

![Configure Connection](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/config_lgr.png)

Type は `ReverseWebSocket` である必要があります；
Host は LangBot を実行しているホストの IP です。同じホストにある場合は、`127.0.0.1` と記述できます；
Suffix は `/ws` である必要があります；

## Lagrange 統合

次に、LangBot 設定ページを開きます

Bots をクリックし、次に Add をクリックします

`Platform/Adapter Selection` で `OneBot v11` を選択します

![napcat\_webui\_03](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png)

> info:
>
> 注意：複数の docker コンテナに関連するネットワーク接続の問題がある場合は、[ネットワーク設定の詳細](https://langbot.app/docs/en/workshop/network-details.md)を参照してください

---

# LiteLoaderQQNT

Source: https://langbot.app/docs/ja/usage/platforms/qq/aiocqhttp/llonebot

LiteLoaderQQNT（LLOneBot）経由で QQ を LangBot に接続。QQ のグループやチャット向け AI ボットを構築。

OneBot 11 プロトコルを通じて接続します。アダプターとして `OneBot v11` を選択する必要があります。

# LiteLoaderQQNT

- [LiteLoaderQQNT の OneBot API プラグイン](https://github.com/LLOneBot/LLOneBot)は QQ クライアントに注入し、OneBot 11 プロトコルに変換します

LiteLoaderQQNT のインストールチュートリアル：<https://llonebot.github.io/zh-CN/guide/getting-started>

![Image 1](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/llonebot/llob_cfg.png)

アドレスの IP アドレスが LangBot を実行しているホストのアドレスであることを確認してください（同じネットワークで実行している場合は、127.0.0.1 を使用します）

## Lagrange 統合

次に、LangBot 設定ページを開きます

Bots をクリックし、次に Add をクリックします

`Platform/Adapter Selection` で `OneBot v11` を選択します

![napcat\_webui\_03](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png)

> info:
>
> 注意：複数の docker コンテナに関連するネットワーク接続の問題がある場合は、[ネットワーク設定の詳細](https://langbot.app/docs/en/workshop/network-details.md)を参照してください

---

# NapCat

Source: https://langbot.app/docs/ja/usage/platforms/qq/aiocqhttp/napcat

NapCat（aiocqhttp）経由で QQ を LangBot に接続。QQ のグループ・個人メッセージで AI チャットボットを運用。

OneBot 11 プロトコルを通じて接続します。アダプターとして `OneBot v11` を選択する必要があります。

## NapCat インストールチュートリアル

[NapCat 公式ドキュメントに従ってインストール](https://napcat.napneko.icu/guide/start-install)してください

## NapCat 設定チュートリアル

webui 操作のみを例として使用します。他の設定方法については、NapCat ドキュメントを確認してください。

ログイン後、コンソールまたは Bash でログを確認し、`[NapCat] [WebUi] WebUi Publish Panel Url: http://x.x.x.x:6099/webui?token=xxxxx ` を見つけます
![napcat\_webui\_01](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_01.png)

Url をブラウザにコピーするか、Windows 11 では Ctrl を押しながら Url をクリックします。QR コードをスキャンしてログインすると、ネットワーク設定ページに入ります。

ネットワーク設定を追加をクリックし、WebSocket Client を選択し、有効をクリックして、Url フィールドに `ws://127.0.0.1:2280/ws` を入力して保存します。
![napcat\_webui\_02](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_02.png)

## NapCat 統合

次に、LangBot 設定ページを開きます

Bots をクリックし、次に Add をクリックします

`Platform/Adapter Selection` で `OneBot v11` を選択します

![napcat\_webui\_03](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png)

> info:
>
> 注意：複数の docker コンテナに関連するネットワーク接続の問題がある場合は、[ネットワーク設定の詳細](https://langbot.app/docs/en/workshop/network-details.md)を参照してください

---

# QQ 公式ボット API（Webhook）

Source: https://langbot.app/docs/ja/usage/platforms/qq/official_webhook

QQ 公式ボット API（Webhook）を LangBot に接続し、QQ で準拠した AI ボットを運用。

この記事では、テストボットのデプロイのみを提供します。ボットの正式な起動については、[リリースプロセス](https://q.qq.com/qqbot/#/home)に従ってください。

> warning:
>
> QQ 公式は、AIGC 機能への不正アクセスを禁止する発表を行いました。注意して使用してください。

## QQ ボットの登録（テストボット）

### 基本ボット情報の設定

[QQ Open Platform](https://q.qq.com/#/)にアクセスし、下部の「アプリケーション管理」を見つけ、ボットを作成をクリックし、基本情報を入力して、ボットページに入ります。以下のように：

![Bot Main Page](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial1.png)

「ホーム」オプションの「リリースプロセス」は、ボットを起動する手順です。テストバージョンのボットをデプロイしているため、「情報」と「サンドボックス設定」セクションを完了するだけで済みます。\


まず情報を入力し、次にサンドボックス設定をクリックします。

#### サンドボックス設定の構成

「サンドボックス設定」をクリックします。
QQ グループにデプロイする場合は、「QQ グループ ID」の下の要件に従ってグループチャットを選択し、メッセージリスト設定でプライベートチャット権限を持つユーザーを追加します。\

QQ チャンネルにデプロイする場合は、「チャンネル ID」の下の要件に従ってチャンネル ID を選択します。ボットタイプは 0 です。

#### 開発管理の構成

「開発管理」をクリックします。

![Development Management Page](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial2.png)

「AppID」、「Token」、「AppSecret」を記録し、LangBot が配置されているサーバーの IP アドレスを IP ホワイトリストに追加します。

## LangBot に接続

次に、LangBot 設定ページを開きます

Bots をクリックし、次に Add をクリックします

`Platform/Adapter Selection` で `QQ Official API` を選択します

![QQ Official Bot Integration with LangBot](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial3.png)

## コールバックアドレスの設定

LangBot は、パブリック IP アドレスを持つサーバーにデプロイする必要があり、HTTPS が正常に有効になっている必要があります。ドキュメント [HTTP リバースプロキシと SSL の設定](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md)に従って設定してください。

> idea:
>
> **パブリック IP と HTTPS の設定が面倒ですか？** [LangBot Cloud](https://space.langbot.app/cloud) にはドメイン解決が組み込まれており、登録するだけで QQ 公式ボットをすぐに使用できます。

#### 後続の設定

Caddy の起動に失敗した場合は、[Caddy ドキュメント](https://caddy2.dengxiaolong.com/docs/quick-starts/caddyfile)を読むか、LangBot コミュニティグループに参加してヘルプを求めてください。\


以下は、考えられる問題の一部です：

- ポート 443 が開いていない
- ドメインがマシンに解決されていない
- Caddyfile が正常に保存されなかった

### 管理ポータルのコールバックアドレスの設定

まず **LangBot を起動します**。

ボット管理ポータルの「コールバック設定」をクリックし、「イベントを追加」の下のすべてのイベントをチェックします。

LangBot 設定ページに移動し、対応する QQ ボットを有効にして選択し、対応するボット設定ページから Webhook コールバックアドレスをコピーし、IP アドレスとポートを Caddy で設定したドメイン名に置き換えて、リクエストアドレスに入力します。

画像に示されているように：
![Caddy Documentation](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial4.png)

たとえば、ドメインが `testlb.com` の場合、リクエストアドレスに `testlb.com/bots/xxxxxx-xxxxxx` を入力し、設定の確認をクリックします。コールバックアドレスが正常に保存された場合、デプロイは成功です。「検証失敗」が表示された場合は、上記の設定項目が正しく入力されているかどうかを注意深く確認してください。

## 公開方法

「ホーム」のリリースプロセスに入り、プロセスに従ってボットを公開して起動します。

---

# ボット（Bots）

Source: https://langbot.app/docs/ja/usage/platforms/readme

LangBot を各メッセージングプラットフォームに接続：Discord・Telegram・Slack・WeChat・QQ・Lark・DingTalk・LINE 等。

ボットは、メッセージングプラットフォームからメッセージイベントを受信し、パイプラインを呼び出してメッセージを処理するために使用されます。

![arch](https://langbot.app/docs/images/zh/deploy/bots/arch.png)

| プラットフォーム                 | ステータス | 備考                                                             | チュートリアル                                                                                                                                                                                                                                                |
| ------------------------ | ----- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Discord                  | ✅     |                                                                | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/discord.md)                                                                                                                                                                                      |
| Telegram                 | ✅     |                                                                | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/telegram.md)                                                                                                                                                                                     |
| Slack                    | ✅     |                                                                | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/slack.md)                                                                                                                                                                                        |
| Mattermost               | ✅     | オープンソース版・無料版・Professional 版・Enterprise 版に対応                    | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/mattermost.md)                                                                                                                                                                                   |
| LINE                     | ✅     |                                                                | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/line.md)                                                                                                                                                                                         |
| KOOK                     | ✅     |                                                                | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/kook.md)                                                                                                                                                                                         |
| Lark                     | ✅     |                                                                | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/lark.md)                                                                                                                                                                                         |
| DingTalk                 | ✅     |                                                                | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/dingtalk.md)                                                                                                                                                                                     |
| WeCom（Enterprise WeChat） | ✅     | 企業内部ボット                                                        | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/wecom/wecom.md)                                                                                                                                                                                  |
| WeCom Intelligent Bot    | ✅     | wecom インテリジェントボット                                              | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/wecom/wecombot.md)                                                                                                                                                                               |
| WeCom Customer Service   | ✅     | 企業外部ボット                                                        | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/wecom/wecomcs.md)                                                                                                                                                                                |
| WeChat Official Account  | ✅     | WeChat 公式プラットフォームボット                                           | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/wxoa.md)                                                                                                                                                                                         |
| OneBot v11               | ✅     | 個人 QQ アカウントをボットとして使用し、独立したプロトコルクライアントが必要です。OneBot v11 をサポートします | [NapCat](https://langbot.app/docs/ja/usage/platforms/qq/aiocqhttp/napcat.md)  [Lagrange](https://langbot.app/docs/ja/usage/platforms/qq/aiocqhttp/lagrange.md)  [LiteLoaderQQNT](https://langbot.app/docs/ja/usage/platforms/qq/aiocqhttp/llonebot.md) |
| QQ Official Bot          | ✅     | QQ Open Platform ボット API に接続します                                | [チュートリアル](https://langbot.app/docs/ja/usage/platforms/qq/official_webhook.md)                                                                                                                                                                          |

> idea:
>
> **パブリック IP やドメインの設定が面倒ですか？** Slack、LINE、WeCom、Lark などのプラットフォームでは Webhook コールバック URL が必要で、パブリックサーバー、ドメイン、HTTPS 証明書が必要です。[LangBot Cloud](https://space.langbot.app/cloud) にはドメイン解決と HTTPS が組み込まれており、登録するだけですぐに使用できます。

---

# Lucky Lilla Desktop

Source: https://langbot.app/docs/ja/usage/platforms/satori/llonebot

Satori プロトコル（LLOneBot）経由で LangBot を接続し、対応クライアントで AI ボットを運用。

Satoriプロトコル経由で接続するため、アダプターとして`Satori`を選択する必要があります。

# LuckyLillia

- [LuckyLillia](https://github.com/LLOneBot/LuckyLilliaBot) Satoriプロトコルを使用するためにクライアントをインストールしてください

LuckyLilliaのインストールチュートリアル: <https://luckylillia.com/guide/choice_install>

![画像1](https://langbot.app/docs/images/zh/deploy/bots/satori/llbot_local_setting.png)

アドレスフィールドのIPアドレスがLangBotを実行しているホストのアドレスであることを確認してください（同じネットワーク内で実行している場合は`127.0.0.1`を使用）。デフォルトポート`5600`は必要に応じて変更できます。トークンの設定を推奨します。

> ![画像2](https://langbot.app/docs/images/zh/deploy/bots/satori/llbot_open_setting.png)
>
> この画像はパブリックネットワーク設定を示しています。IPアドレスがLangBotを実行しているホストのアドレスであることを確認してください。この場合、LangBotの該当ポートを公開する必要があります。

## LangBot 連携

次に、LangBotの設定ページを開きます。

ボットをクリックし、追加をクリックします。

`プラットフォーム/アダプター`で`Satori`を選択します。

![画像3](https://langbot.app/docs/images/zh/deploy/bots/satori/llone_langbot_build.png)

> デフォルト設定（ローカルネットワーク）を使用する場合、パラメータを変更する必要はありません。

作成後もパラメータを調整できます。

![画像4](https://langbot.app/docs/images/zh/deploy/bots/satori/llone_langbot_setting.png)

このアダプターが有効になっていることを確認してください。

![画像5](https://langbot.app/docs/images/zh/deploy/bots/satori/satori_platform_open.png)

> info:
>
> 注意：複数のDockerコンテナ間のネットワーク接続に問題がある場合は、[ネットワーク設定の詳細](https://langbot.app/docs/ja/workshop/network-details.md)を参照してください。

---

# Slack

Source: https://langbot.app/docs/ja/usage/platforms/slack

LangBot で Slack AI ボットを構築。GPT・Claude・Dify 等を Slack ワークスペースに接続。

## ボットの作成

[Slack App Platform](https://api.slack.com/apps)にアクセスします。

![Slack Platform](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_01.jpg)

右上の「Create New App」をクリックし、「from a manifest」を選択し、ボットをデプロイするワークスペースを選択し、next を選択して、ボットを作成します。

左側の「Basic Information」オプションに入り、`signing_secret` を記録します。

左側の「OAuth & Permissions」に入り、「Scopes」までスクロールダウンし、次のボット権限を追加します：

![Bot Permissions 1](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_02.jpg)

![Bot Permissions 2](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_03.jpg)

上記の権限を追加した後、「Install to your workspace」をクリックし、`xoxb-xxxxx` で始まるトークンを記録します。\


**注意：**
**すべての権限を一度に追加しなかった場合は、後で App を再インストールする必要があります。**\


左側の「App Home」タブに入り、一番下までスクロールして「Message Tab」を見つけ、オンにして
「Allow users to send Slash commands and messages from the messages tab」をチェックします。

## LangBot に接続

左側の「Event Subscriptions」に入り、スイッチをオンにし、「Subscribe to bot events」をクリックし、
次の権限を追加します：
![Event Permissions](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_04.jpg)

上記のすべての操作を完了した後、LangBot Webui 設定ページを開き、新しいボットを追加します

![Event Permissions](https://langbot.app/docs/images/zh/deploy/bots/slack/connect_to_langbot.png)

## ボットの起動

> info:
>
> Slack 公式が https を要求しているため、まずドキュメント [HTTP リバースプロキシと SSL の設定](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md)に従ってリバースプロキシを設定してください。

Slack 設定項目を入力した後、**LangBot を起動します**。
LangBot ホームページで Slack ボットを有効にして開き、ボット設定ページから WebHook URL をコピーし、先ほど設定した Event Subscriptions の「Request URL」に WebHook URL を入力します。

上記のすべての設定項目を入力した後、リンクを保存をクリックします。緑色の **Verified** が表示されれば、デプロイは成功です。
それ以外の場合は、上記の設定項目が正しく入力されているかどうかを確認してください。

## 効果のデモンストレーション

![Effect Demonstration](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_05.jpg)

---

# Telegram

Source: https://langbot.app/docs/ja/usage/platforms/telegram

LangBot で Telegram AI ボットを構築。GPT・Claude・Gemini・DeepSeek・Dify を Telegram のチャットやグループに接続。

## ボットの作成

[Telegram Bot Creation Page](https://t.me/botfather)にアクセスし、プロンプトに従ってボットを作成します。

![Telegram Bot Creation](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_01.png)

![Telegram Bot Creation](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_02.png)

作成後、BotFather は API Token を返しますので、安全に保管してください。次に、グループチャットで使用するために「Privacy Mode」をオフにします。

![Telegram Bot API Token](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_03.png)

## LangBot に接続

LangBot Webui ページを開き、新しいボットを作成します

![Connect to LangBot](https://langbot.app/docs/images/zh/deploy/bots/telegram/connect_to_langbot.png)

入力後、LangBot を起動します。設定が成功した場合、ログに `[02-02 16:48:15.263] manager.py (68) - [INFO] : Initializing platform adapter 1: telegram` と表示されます。LangBot を実行し続けてください。

## ボットの使用

グループまたはプライベートメッセージでボットを通常どおり使用できるようになりました。

![Telegram Bot Usage](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_04.png)

![Telegram Bot Usage](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_05.png)

---

# ウェブページボット

Source: https://langbot.app/docs/ja/usage/platforms/webpage

Web ページに LangBot AI チャットボットを埋め込み。任意のサイトに LLM チャットウィジェットを追加。

一行のスクリプトタグで LangBot チャットウィジェットを任意のウェブサイトに埋め込みます。

## ボットの作成

LangBot WebUI を開き、**ボット > ボットを作成** に移動し、ボット名を入力し、プラットフォーム/アダプターで `ページボット` を選択します。

![ページボットの作成](https://langbot.app/docs/images/zh/deploy/bots/web_page/webpage_01.png)

## 設定項目

| 項目                 | 説明                                                                       |
| ------------------ | ------------------------------------------------------------------------ |
| コンポーネントタイトル        | チャットウィジェットの上部に表示されるタイトル。デフォルトは LangBot                                   |
| バブルアイコン            | フローティングチャットバブルに表示されるアイコン                                                 |
| コンポーネント言語          | チャットウィジェットの表示言語（簡体字中国語、英語など）                                             |
| Turnstile サイトキー    | Cloudflare Turnstile のサイトキー。bot 対策用。空なら無効                                |
| Turnstile シークレットキー | Cloudflare Turnstile のシークレットキー。サイトキーと一緒に Cloudflare コンソールで取得。サイトキー設定時に必須 |

## 埋め込みコードの取得

作成・保存後、ボット設定ページの **埋め込みコード** エリアに自動生成された `<script>` タグが表示されます。

![埋め込みコード](https://langbot.app/docs/images/zh/deploy/bots/web_page/webpage_02.png)

このコードをコピーしてウェブサイトの HTML に貼り付けます（通常は `</body>` の前）。ページの右下にチャットバブルが表示され、ビジターがボットとチャットできるようになります。

```html
<script data-title="LangBot" src="http://localhost:5300/api/v1/embed/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"></script>
```

> warning:
>
> 埋め込みコードの URL はデフォルトで `localhost` です。LangBot をサーバーにデプロイしている場合は、`localhost:5300` を実際のアドレスに置き換えてください。

## bot 対策（オプション）

Cloudflare Turnstile を有効にして bot 対策を行えます：

1. [Cloudflare Turnstile](https://dash.cloudflare.com/) > サイトを追加 に移動
2. **サイトキー** と **シークレットキー** を取得
3. LangBot ページボットの対応するフィールドに入力
4. 保存して反映

## ローカルプレビュー / デモ

自分のサイトに組み込む前に埋め込みウィジェットを試したい場合、LangBot 本体リポジトリの
[`examples/web-page-bot/`](https://github.com/langbot-app/LangBot/tree/master/examples/web-page-bot)
に自己完結型の単一ファイルデモページ `index.html` が用意されています。ブラウザで開いて
LangBot のアドレスとページボットの UUID を入力すると、実際の埋め込みウィジェットが読み込まれ、
サイト訪問者と同じようにボットとチャットでき、さらに自分のサイトに貼り付ける `<script>`
スニペットもリアルタイムで生成されます。

```bash
# リポジトリのルートを静的配信し、ブラウザで開く
python3 -m http.server 8930
# http://localhost:8930/examples/web-page-bot/ にアクセス
```

## 使い方

埋め込みコードをウェブサイトに追加後、ページ右下のチャットバブルをクリックするとボットとチャットできます。

---

# 個人 WeChat（OpenClaw）

Source: https://langbot.app/docs/ja/usage/platforms/wechat/weixin

LangBot で個人 WeChat AI ボットを構築。大規模言語モデルを WeChat アカウントに接続。

## はじめに

[OpenClaw](https://github.com/dingxiang-me/OpenClaw-Wechat) はオープンソースの AI Agent フレームワークです。OpenClaw WeChat アダプターを使用することで、LangBot を個人の WeChat アカウントに接続でき、単一チャット、ストリーミング出力、ホワイトリスト制御などの機能をサポートしています。

## クイックスキャンログイン（おすすめ）

LangBot は WeChat のワンクリックスキャンログインをサポートしており、クレデンシャルを自動入力します。手動でのトークン入力は不要です。

> warning:
>
> スマートフォンの WeChat バージョンが **8.0.69** 以上であることを確認してください。それ以外の場合、正常に動作しない可能性があります。

1. LangBot WebUI を開き、**ボット > ボットを作成** に移動
2. ボット名を入力し、プラットフォーム/アダプターで `個人微信ボット` を選択
3. 表示される **スキャンログイン** エリアで **開始** ボタンをクリック

![スキャンログインを選択](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_scan_login.png)

4. WeChat で QR コードをスキャンし、手机端で「新しい OpenClaw を WeChat に接続」をタップし **続行** をクリック

![スキャンして接続](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_scan_connect.png)

5. 認証成功後、トークンとアカウント ID がフォームに**自動入力**されます

![設定自動入力](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_config_auto_fill.png)

6. **送信** をクリックして完了

> warning:
>
> 接続に失敗した場合は、WeChat のバージョンが 8.0.69 以上であることを確認してください。

### ログイン成功の確認

スキャンが成功すると、スマートフォンに ClawBot のチャット画面が表示されます。

![WeChat ClawBot チャット画面](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_05.jpg)

同時に、LangBot のログに接続成功のメッセージが表示され、設定ページのトークンとアカウントが自動的に更新されます。これでログイン成功です。

![ログ情報](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_06.png)
![設定ページ](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_07.png)

## 使い方

ログイン成功後、スキャンしたアカウントで先ほど入った ClawBot のチャット画面に話しかけると、LangBot が自動的に返信します。

---

# WeCom

Source: https://langbot.app/docs/ja/usage/platforms/wecom/wecom

WeCom（企業微信）を LangBot に接続。企業向けメッセージングに LLM AI ボットをデプロイ。

WeCom（企業微信）ボットをデプロイして LangBot に接続します。

> \- この統合方法は、企業内部アプリケーション用であり、企業内で使用されます。外部カスタマーサービスが必要な場合は、\[WeCom Customer Service 統合ソリューション]\(wecomcs)を確認してください。:
>
> - WeCom コールバックアドレスにはパブリック IP とドメイン名が必要です。まず [HTTP リバースプロキシの設定](https://langbot.app/docs/ja/workshop/production/proxy-and-ssl.md)を参照して LangBot コールバックアドレスを設定することをお勧めします。

> idea:
>
> **パブリックサーバーがありませんか？** [LangBot Cloud](https://space.langbot.app/cloud) にはドメインと HTTPS が含まれており、WeCom をすぐに使用できます。

## 企業 ID の記録

[WeCom 管理ポータル](https://work.weixin.qq.com/)を開き、`私の企業`をクリックして、一番下の`企業 ID`を記録します。

![Corp ID](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/03-corp-id.png)

## ボットの作成

`アプリ管理`、`自社開発`、`アプリを作成`をクリックします。

![App Management](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/01-wecom-apps.png)

ボットの基本情報を入力します:

![Create Application](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/02-create-app.png)

ボットのシークレット（Secret）を確認して記録します:

![Bot Secret](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/04-bot-secret.png)

WeCom クライアントからプロンプトに従って取得します。

## 連絡先同期権限の有効化

> \- この設定項目は、LangBot の一斉送信機能を実装するためのものです。具体的なコードは libs/wecom\_api/api.py にあります。:
>
> - LangBot はまだ開発中であるため、この設定項目に関連する機能はまだ実装されていません。
> - この設定項目はランダムな文字で埋めることができますが、**空にすることはできません**。

`セキュリティと管理`、`管理ツール`、`連絡先同期`をクリックします。まず信頼できる IP を設定し、LangBot がデプロイされているサーバーの IP を追加します。

`Secret を表示`をクリックして記録します。これが contacts\_secret（連絡先同期 Secret）です。

![Contact Sync Secret](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/08-contact-secret.png)

## LangBot でボットを作成

LangBot のボットページで、`ボットを作成`をクリックし、名前を入力し、`企業微信`を選択します。このステップでは、企業 ID、ボットシークレット、連絡先同期 Secret のみを入力する必要があります。

![Create WeCom Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/05-fill-in-corpid-secret.png)

送信をクリックして、ボット編集ページにジャンプし、有効化をクリックします。この時点で Webhook コールバックアドレスが表示されるので、コピーします:

![Webhook Callback Address](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/06-webhook-callback-address.png)

## コールバックアドレスの設定

WeCom のボット管理ページに戻り、`メッセージを受信`、`API 受信を設定`をクリックし、LangBot の Webhook コールバックアドレスを`URL`に入力します:

![Set API Receiver](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/07-set-api-receiver.png)

Token と EncodingAESKey の`ランダム生成`をクリックして記録し、**このページを開いたままにします**。LangBot の WeCom ボット設定ページに戻り、Token と EncodingAESKey を入力して、保存をクリックします。

![Save WeCom Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/09-save-wecom-bot.png)

**先ほど Webhook コールバックアドレスを入力したページ**に戻り、保存をクリックして設定を完了します。**リクエスト URL 失敗**が表示された場合は、設定項目が正しく入力されているか再度確認してください。

## アプリの企業信頼 IP の設定

このアプリの管理ページに戻り、下部の`企業信頼 IP`を見つけ、LangBot がデプロイされているサーバーの IP を追加します。

![Corp Trusted IP](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/10-corp-trusted-ip.png)

保存をクリックして完了です。

## よくある質問

Q: WeCom でボットのチャットが見つかりませんか?
A: WeCom 管理ページのこのアプリの詳細ページに移動し、`機能`->`メッセージを送信`->`メッセージを送信`をクリックし、自分のアカウントを選択してメッセージを送信すると、自分のチャットウィンドウでボットが表示されます。

---

# WeCom インテリジェントボット

Source: https://langbot.app/docs/ja/usage/platforms/wecom/wecombot

LangBot で WeCom（企業微信）AI ボットを構築し、組織に LLM チャットを導入。

## 一键設定（おすすめ）

LangBot は WeCom ボットのワンクリック作成と BotId/Secret の自動入力に対応しています。手動でのコピペは不要です。

1. LangBot WebUI を開き、**ボット > ボットを作成** に移動
2. ボット名を入力し、プラットフォーム/アダプターで `企业微信智能机器人` を選択
3. 表示される **一键创建机器人** エリアで **開始** ボタンをクリック

![一键创建机器人](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_oneclick.png)

4. 企業微信で QR コードをスキャンし、手机端で **一键创建智能机器人** をタップ

![手机端一键作成](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_scan_create.png)

5. 認証成功後、BotId と Secret がフォームに**自動入力**されます
6. **ボット名を手動で入力** — 企業微信のボット名と一致させる必要があります

![ボット名の入力](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_fill_name.png)

7. **送信** をクリックして完了

> warning:
>
> 企業微信インテリジェントボットは**既存のボットを使用できない**ため、一键設定は新規作成のみ対応しています。既存のボットを使用する場合は、下記の手動設定を参照してください。

***

## 手動設定

### ボットの作成

まず、[WeCom Admin Console](https://work.weixin.qq.com/wework_admin/frame#/)にログインします。

![Homepage](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_1.png)

左側のサイドバーの「セキュリティと管理」をクリックし、次に「管理ツール」の下の「インテリジェントボット」をクリックします。

以下のように：

![Intelligent Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_2.png)

「ボットを作成」をクリックし、「手動作成」を選択して、ページの一番下までスクロールして「API モードで作成」をクリックし、ページに入ります：

![Create via API Mode](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_3.png)

### ロングコネクション設定

#### ロングコネクション API モードの有効化

WeCom 管理コンソールで、インテリジェントボットの設定ページに移動し、「API モード」を有効にして「ロングコネクション」を選択します：

![ロングコネクションモード](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_9.png)

#### 認証情報の取得

ロングコネクション API モードを有効にした後、接続を確立するために以下の認証情報を取得する必要があります：

| 認証情報   | 説明                                |
| ------ | --------------------------------- |
| BotID  | インテリジェントボットの一意の識別子で、ボットの識別に使用されます |
| Secret | ロングコネクション専用の秘密鍵で、本人確認に使用されます      |

> warning:
>
> 注意：
>
> - Secret はロングコネクション専用の秘密鍵であり、コールバック URL モードで使用される Token/EncodingAESKey とは異なります
> - Secret を安全に保管し、漏洩を避けてください
> - モード切り替えの影響：API モードは一つの方式のみ使用できます（ロングコネクションまたはコールバック URL）。「コールバック URL」モードに切り替えると、既存のロングコネクションが無効になります。逆に、「コールバック URL」から「ロングコネクション」モードに切り替えると、元のコールバック URL は無効になります

#### ボットの設定

LangBot メインプログラムを起動し、アダプター「WeCom Intelligent Bot」を選択し、設定項目を入力します。
ロングコネクションの BotID、Secret、およびボット名を入力し、保存して有効化をクリックします。

> ボット名は新しく作成したボットの名前と一致している必要があります。一致しない場合、グループチャットで応答しません。

![ロングコネクション設定](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_10.png)

### URL コールバック設定

Token と EncodingAESKey をランダムに生成するためにクリックし、次に上部に基本的なボット情報を入力します。**表示範囲の設定に注意してください**。

![パラメータ取得](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_11.png)

左側のサイドバーの「私の会社」をクリックし、下部の会社 ID を保存します。

#### コールバック URL の設定

LangBot メインプログラムを起動し、アダプター「WeCom Intelligent Bot」を選択し、設定項目を入力します。
その中で、token は Token、Encoding-AESKey は EncodingAESKey、Bot ID は xxx として入力できます（またはランダムに入力でき、後で変更されます）。入力後、
「保存」をクリックし、ロボットを「有効化」します。

![WeCom Intelligent Bot Adapter](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_4.png)

LangBot ホームページで、対応するボットを有効にして選択し、設定ページをクリックして入り、Webhook コールバックアドレスをコピーします

> info:
>
> まず、[HTTP リバースプロキシの設定](https://langbot.app/docs/ja/workshop/production/proxy-and-ssl.md)を参照して LangBot コールバックアドレスを設定することをお勧めします。

![Webhook Callback Address](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_8.png)

WeCom ロボット設定ページに戻り、コピーした webhook アドレスを「URL Callback」に入力します。作成が成功すると、詳細ページにジャンプします。「Request URL Failed」というメッセージが表示された場合は、上記の手順が 1 つずつ完了しているかどうかを再度確認してください。

作成成功後の詳細ページ：
![Creation Successful](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_5.png)

WeCom ロボット詳細ページから「Bot ID」とボット名をコピーし、LangBot 管理ページに戻り、デプロイされたインテリジェントロボットの Bot ID をコピーした ID に変更し、ボット名を入力して、ロボットを再起動します。

### ストリーミングの有効化

ローカルでデプロイされたモデルやストリーミングをサポートしていないモデル向けに、ストリーミングのオン・オフスイッチが追加されました。

![ストリーミングスイッチ](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_12.png)

### 使用開始

WeCom に入り、「➕」をクリックします。以下のように：

![Add Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_6.png)

「会社作成」をクリックし、作成したボットを選択し、チャットインターフェイスに入ります。

同様に、ボットをグループチャットに招待したい場合は、グループチャットでメンバーを追加ボタンをクリックし、そこからボットを追加します。

### 効果の画像

![Effect Image 1](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_7.png)

---

# 企業微信カスタマーサービス

Source: https://langbot.app/docs/ja/usage/platforms/wecom/wecomcs

LangBot で WeCom カスタマーサービスを設定し、AI 主導のサポート会話を実現。

> この記事では、LangBot を企業微信カスタマーサービスアカウントにデプロイするプロセスについて詳しく説明します。これにより、カスタマーサービスアカウントと通常の WeChat との間の会話が可能になります。企業微信内でのみ使用する必要がある場合は、\[企業微信内部アプリケーションの実装]\(wecom)を参照してください。:
>
> **企業微信カスタマーサービスアカウントのデプロイには企業資格が必要です**。[企業微信カスタマーサービス統合ガイド](https://developer.work.weixin.qq.com/document/path/94638)を確認し、このドキュメントに従って対応する企業資格証明書を提供してください。

## 効果のデモンストレーション

![効果のデモンストレーション](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/wecomcs_01.jpg)

## 企業微信カスタマーサービスをデプロイする

#### 企業微信カスタマーサービスページの構成

[企業微信カスタマーサービス管理画面](https://kf.weixin.qq.com/kf)を開き、ログイン後、「企業情報」をクリックし、「企業ID」を取得します。

![ホーム画面](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/wecomcs_03.png)

企業IDを保存したら、「開発構成」をクリックし、「開始使用」をクリックして、Token と EncodingAESKey をランダムに生成します。この3つの項目を LangBot 設定ページに入力します。Secret は適当に填写如下图所示：

![connect](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/connect_to_langbot.png)

LangBot 設定ページの提交をクリックして 로봇を有効化し、Webhook コールバックアドレスをコピーし、企業微信カスタマーサービス管理画面の URL に入力します（自分の IP またはドメインに変更することを忘れないでください）。保存をクリックし、成功すれば正常に接続できることを意味します。

> idea:
>
> **ドメイン設定が面倒ですか？** [LangBot Cloud](https://space.langbot.app/cloud) にはドメインと HTTPS が含まれており、設定不要ですぐに使用できます。

ページの Secret をコピーし、新しく作成した LangBot 企業微信カスタマーサービス 로봇を開き、新しい Secret を入力して再起動します。

企業微信カスタマーサービス設定画面に戻り、カスタマーサービスアカウントをクリックしてカスタマーサービスアカウントを作成すれば、使用できます。

---

# WeChat Official Account

Source: https://langbot.app/docs/ja/usage/platforms/wxoa

LangBot で WeChat 公式アカウント AI ボットを構築。LLM を WeChat 公衆号に接続。

WeChat Official Account ボットをデプロイして LangBot に接続します。

## LangBot WeChat Official Account 統合モード

現在、LangBot は WeChat Official Accounts と統合する 2 つの方法を提供しています：

1. **従来のメッセージ交換モード**
   - 公式アカウントはリクエストを **15 秒**以内に処理する必要があり、このタイムアウトを超える AI 生成コンテンツは送信できません。
   - AI コンテンツ生成のタイムアウトが発生すると、LangBot はコンソールにリクエストタイムアウト情報を出力します。

2. **「任意のテキストを送信して返信を取得」モード**
   - この方法は **15 秒**の制限を破ることができますが、**非常に長いテキスト**は正常に送信されない場合があります。
   - この方法を使用する場合、公式アカウントにメッセージを送信すると、「AI が考えています。回答を得るには任意のコンテンツを送信してください」と返信されます。この時点で、回答を得るために任意のコンテンツを送信する必要があります。

より複雑な機能については、カスタマイズされたサポートのために **LangBot チーム**にお問い合わせください。

## ボットの作成

[WeChat Official Account Platform](https://mp.weixin.qq.com/)に入り、すでに公式アカウントをお持ちの場合は、QR コードをスキャンしてログインしてコンソールに入ります。
以前に公式アカウントを登録したことがない場合は、今すぐ登録をクリックし、「公式アカウント」を選択し、順番に情報を入力し、コンソールに入ります。コンソールは次のようになります：
![Console Page](https://langbot.app/docs/images/zh/deploy/bots/wxoa/wxoa1.png)

## コールバックアドレスの設定

> idea:
>
> **WeChat 公式アカウントにはパブリックドメインと HTTPS が必要です。** サーバーがない場合、[LangBot Cloud](https://space.langbot.app/cloud) にはドメイン解決が組み込まれており、登録するだけですぐに使用できます。

### 設定項目の取得

「設定と開発」、「開発インターフェイス管理」をクリックすると、次のようなページが表示されます：
![Set Development Items](https://langbot.app/docs/images/zh/deploy/bots/wxoa/wxoa2.png)

「開発者 ID（AppID）」、「開発者パスワード（AppSecret）」を記録し、LangBot がデプロイされているサーバーを「IP ホワイトリスト」に追加します。

### LangBot のリバースプロキシの設定

WeChat Official Accounts は http（ポート 80）と https（ポート 443）のみをサポートしているため、ドキュメント [HTTP リバースプロキシと SSL の設定](https://langbot.app/docs/en/workshop/production/proxy-and-ssl.md)に従って設定してください。

### コールバックアドレスの保存

サーバー設定を設定をクリックし、「Token」、「EncodingAESKey」を入力し、メッセージの暗号化/復号化方式を「Safe Mode」に変更します。

この時点で、LangBot Webui ページを開き、新しいボットを作成し、取得した 4 つの設定項目（AppID、AppSecret、token、EncodingAESKey）を入力します

![Set Development Items](https://langbot.app/docs/images/zh/deploy/bots/wxoa/connect_to_langbot.png)

設定項目の「Mode」オプションは、選択された統合モードです。デフォルトは「drop」です。「drop」は従来のメッセージ交換モードで、「passive」は「任意のテキストを送信して返信を取得」モードです。

「LoadingMessage」オプションはローディングメッセージで、他のコンテンツに変更でき、モードが「passive」の場合にのみ有効です。「enable」を「true」に設定します。

正常に入力した後、LangBot ホームページで対応するボットを有効にして選択し、設定ページをクリックして入り、Webhook コールバックアドレスをコピーし、WeChat Official Account ボット設定ページに戻って「URL」に入力します。たとえば、URL を「https\://your\_domain\_name/bots/xxxxx」として入力します。ここで「your\_domain\_name」は Caddy に入力したドメイン名です。保存をクリックします。正常に保存できれば、デプロイは成功です。**システムエラー、後でもう一度お試しください**が表示された場合は、上記の設定内容が正しく入力されているかどうかを再確認してください。

---

# サンドボックス設定

Source: https://langbot.app/docs/ja/usage/sandbox/config

LangBot Box Runtime を設定し、Docker・nsjail・E2B、または明示的に有効化する非隔離 Host バックエンドを選択。

Box の設定は LangBot メインプロセスが管理し、Box Runtime が実際の実行を担当します。通常のデプロイでは、バックエンド、ワークスペースディレクトリ、セキュリティプロファイルだけを決めれば十分です。Docker、nsjail、E2B はサンドボックス環境を提供し、Host バックエンドは Box Runtime のホスト上でコマンドを直接実行します。

> info:
>
> このページの `box.*` 設定はすべて `data/config.yaml` に記述します。ファイルの場所と読み込みの仕組みは[システム環境設定](https://langbot.app/docs/ja/deploy/settings.md)を参照してください。

## 推奨設定

```yaml
box:
  enabled: true
  backend: 'local'        # Docker / Nsjail から利用可能なものを自動選択
  local:
    profile: 'default'
    host_root: './data/box'
    skills_root: 'skills'
  docker:
    cpu_limit_enabled: true
```

- `enabled`：サンドボックスのマスタースイッチ。`false` にすると、サンドボックス組み込みツール、Skill の追加 / 編集、stdio MCP のホスティングなど Box 依存の機能はすべて無効になります。
- `backend`：下記「バックエンドの選択」を参照。
- `local.profile`：セキュリティプロファイル。ネットワーク、マウント、リソース制限を制御。
- `local.host_root`：ホスト側のサンドボックス作業ディレクトリ。サンドボックス内では `/workspace` にマウントされます。
- `local.skills_root`：Skill パッケージのディレクトリ。相対パスは `host_root` 配下に解決され、デフォルトは `host_root/skills`。
- `docker.cpu_limit_enabled`：Docker サンドボックスコンテナに CPU 制限を付けるかどうか。`false` にすると `docker run --cpus` を省略し、メモリと PID 制限は維持します。

> info:
>
> Skill は Box Runtime が管理する skill store からのみ読み込まれます。Box Runtime またはバックエンドが利用できない場合、Skill 一覧は空になり、追加 / 編集 / `register_skill` も使えません。`data/skills/` へのフォールバックは行いません。

## バックエンドの選択

Box は**ローカルコンテナ**、**クラウドサンドボックス**、または **Box Runtime ホスト上のプロセス**として動作させられます。`box.backend` で使用する方式を指定します：

| `backend`   | 実行場所            | 動作                                                 |
| ----------- | --------------- | -------------------------------------------------- |
| `local`（既定） | ローカルコンテナ        | Docker / Nsjail から利用可能なものを自動選択（Docker 優先）          |
| `docker`    | ローカルコンテナ        | Docker を強制使用。Docker daemon が必要                     |
| `nsjail`    | ローカルコンテナ        | Nsjail を強制使用（Linux のみ）。カスタムイメージ非対応                 |
| `e2b`       | クラウド            | [E2B](https://e2b.dev) クラウドサンドボックスを使用。API キーが必要    |
| `host`      | Box Runtime ホスト | Box Runtime ユーザーの権限でローカルプロセスを直接起動。POSIX と `sh` が必要 |

`local` は「自動選択」のショートハンドであり、`docker` / `nsjail` と並列の 4 つ目のバックエンドではありません。試行対象は Docker と Nsjail だけで、**`host` が自動選択されることはありません**。ローカル系バックエンドは `box.local.*` のワークスペース設定を使い、クラウドバックエンドは `box.e2b.*` を使います。

> warning:
>
> `host` は**サンドボックスではありません**。コマンドは Box Runtime ユーザーのホスト権限を持ち、ファイルシステム、プロセス、ネットワーク、namespace、cgroup、rootfs、イメージの隔離はありません。読み取り専用マウントやハードディスククォータも保証されません。単一ユーザーかつ信頼できる入力を扱うローカル開発にのみ使用し、公開サービス、共有ホスト、信頼できないコードには使用しないでください。

> info:
>
> `backend` は強制値です。`docker` を指定して Docker が使えない場合、Nsjail や E2B に**自動でフォールバックしません**。自動 fan-out するのは `local` だけです。
>
> 環境変数 `BOX__BACKEND` で `box.backend` を上書きできます（`config.yaml` より優先）。

## セキュリティプロファイル

`box.local.profile` は Docker / Nsjail ローカルサンドボックスバックエンドのネットワーク、マウント、リソース制限を制御します：

| Profile            | ネットワーク   | マウント   | リソース | 推奨シーン               |
| ------------------ | -------- | ------ | ---- | ------------------- |
| `default`          | オフ       | 読み書き   | 既定制限 | 既定の選択               |
| `offline_readonly` | オフ       | 読み取り専用 | より厳格 | 信頼できないファイルの読み込み     |
| `network_basic`    | 基本ネットワーク | 読み書き   | 既定制限 | API アクセス、依存関係インストール |
| `network_extended` | フルネットワーク | 読み書き   | 緩和   | 開発、デバッグ、複雑なタスク      |

最小権限を優先：ネットワークが不要なら `default` または `offline_readonly`；`allowed_mount_roots` には必要なディレクトリのみを追加。

> info:
>
> Host バックエンドはこれらの隔離ポリシーを適用しません。profile、CPU / メモリ / PID 制限、読み取り専用 rootfs、ネットワーク無効化を設定しても、ホストプロセスにサンドボックス境界は作られません。

## ローカルワークスペース設定（box.local.\*）

Docker、Nsjail、Host はワークスペースパス設定を共有します。隔離とリソース設定は、選択したサンドボックスバックエンドが実施できる場合にのみ有効です：

| 設定項目                        | 既定値           | 説明                                                          |
| --------------------------- | ------------- | ----------------------------------------------------------- |
| `local.profile`             | `default`     | Docker / Nsjail のセキュリティプロファイル。Host には対応する隔離なし               |
| `local.image`               | 空             | Docker バックエンドのカスタムイメージ。空 = プロファイル既定を使用                      |
| `local.host_root`           | `./data/box`  | ホスト作業ディレクトリのベース。サンドボックス内の `/workspace` にマップ                 |
| `local.default_workspace`   | 空             | 既定ワークスペース名。空 = `<host_root>/default`                        |
| `local.skills_root`         | `skills`      | Skill パッケージディレクトリ。相対パスは `host_root` 配下に解決                   |
| `local.allowed_mount_roots` | `[host_root]` | Agent がマウント要求できるホストディレクトリの許可リスト                             |
| `local.workspace_quota_mb`  | `null`        | ワークスペースのディスククォータ（MB）。`null` = プロファイル既定。Host ではハードクォータを保証しない |

## Host バックエンド（信頼できるローカル開発）

Host は依存関係が最も少ないローカルオプションで、Docker や Nsjail は不要です。必ず明示的に選択します：

```yaml
box:
  enabled: true
  backend: 'host'
  local:
    host_root: './data/box'
    skills_root: 'skills'
```

WebUI、Agent ツール、呼び出し方法は変わりません。セッションスコープ、`exec/read/write/edit/glob/grep`、Skills、stdio MCP は既存の Box API をそのまま使います。違いは実行層だけです：

- `/workspace`、`workdir`、Skill のマウントパスは Box Runtime ホスト上の実パスに変換されます。
- 子プロセスは最小限のパス、ロケール、端末環境と、リクエストで明示的に渡された変数だけを継承します。LangBot / Box の制御シークレットは自動継承されません。これは意図しない漏えいを減らしますが、ファイルシステム隔離を提供するものではありません。
- `exec` と管理対象プロセスは個別のプロセスグループで起動します。タイムアウト、キャンセル、プロセス停止、セッション削除、Runtime 終了時には対応するプロセスツリーを終了します。
- アイドルクリーンアップ、管理対象プロセスによる維持、`persistent` のルールは他のバックエンドと同じです。
- ステータスレスポンスには `unsafe_direct_execution: true` が含まれ、サンドボックス隔離がないことを運用側で識別できます。

> info:
>
> Host は **Box Runtime が動作する環境**を指します。LangBot がローカル stdio Box Runtime を管理する場合は現在のマシンです。Box Runtime 自体がコンテナ内で動作している場合、コマンドはそのコンテナ内で直接実行され、物理ホストへ自動的に抜けることはありません。

Host MVP は `sh` を備えた POSIX システム（Linux / macOS）をサポートします。Windows では WSL を使用してください。Windows ネイティブのプロセスバックエンドはまだサポートされていません。

外部 WebSocket Box Runtime で Host を使う場合、LangBot と Box Runtime の両方に同じ強力なランダム値の `LANGBOT_BOX_CONTROL_TOKEN` を設定してください。ローカル管理の stdio Runtime では追加のトークン設定は不要です。管理サンドボックス admission を有効にした Cloud 環境では、隔離能力と必須バックエンドの検証が継続され、Host がこれらを迂回することはありません。

## Docker バックエンド設定（box.docker.\*）

| 設定項目                       | 既定値    | 説明                                                                                                     |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `docker.cpu_limit_enabled` | `true` | Docker バックエンドのみ有効。`false` の場合、サンドボックスコンテナは `--cpus` なしで起動しますが、`--memory` と `--pids-limit` は引き続き適用されます。 |

## クラウドバックエンド設定（box.e2b.\*）

`backend: 'e2b'` を指定したうえで設定します：

| 設定項目           | 既定値 | 説明                                           |
| -------------- | --- | -------------------------------------------- |
| `e2b.api_key`  | 空   | E2B API キー。環境変数 `E2B_API_KEY` でも設定可          |
| `e2b.api_url`  | 空   | セルフホスト E2B のエンドポイント。環境変数 `E2B_API_URL` でも設定可 |
| `e2b.template` | 空   | 既定の E2B テンプレート ID                            |

E2B はホスト側に Docker や Nsjail を必要とせず、毎回の実行をリモートサンドボックスで行います。

## Docker Compose デプロイ

Docker Compose では、サンドボックス設定は `langbot` サービス側に記述します。LangBot は起動時に INIT RPC で設定を `langbot_box` に転送します。

```yaml
services:
  langbot_box:
    image: rockchin/langbot:latest
    container_name: langbot_box
    profiles: ["box", "all"]
    volumes:
      - ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - /var/run/docker.sock:/var/run/docker.sock
    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]

  langbot:
    image: rockchin/langbot:latest
    volumes:
      - ./data:/app/data
    environment:
      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__LOCAL__SKILLS_ROOT=skills
      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__DOCKER__CPU_LIMIT_ENABLED=${LANGBOT_BOX_DOCKER_CPU_LIMIT_ENABLED:-true}
```

> warning:
>
> `langbot_box` は Docker daemon にアクセスします。`docker.sock` のマウントは信頼できる環境でのみ行い、Box のルートパスをホストと `langbot_box` コンテナ内で一致させてください。

外部の Box Runtime（リモートホストなど）に接続する場合は `box.runtime.endpoint` で URL を指定します：

```yaml
box:
  runtime:
    endpoint: 'ws://192.168.1.10:5410'
```

## 環境変数

| 環境変数                              | 対応する設定                                 |
| --------------------------------- | -------------------------------------- |
| `BOX__ENABLED`                    | `box.enabled`                          |
| `BOX__BACKEND`                    | `box.backend`                          |
| `BOX__LOCAL__PROFILE`             | `box.local.profile`                    |
| `BOX__LOCAL__IMAGE`               | `box.local.image`                      |
| `BOX__LOCAL__HOST_ROOT`           | `box.local.host_root`                  |
| `BOX__LOCAL__DEFAULT_WORKSPACE`   | `box.local.default_workspace`          |
| `BOX__LOCAL__SKILLS_ROOT`         | `box.local.skills_root`                |
| `BOX__LOCAL__ALLOWED_MOUNT_ROOTS` | `box.local.allowed_mount_roots`、カンマ区切り |
| `BOX__LOCAL__WORKSPACE_QUOTA_MB`  | `box.local.workspace_quota_mb`         |
| `BOX__DOCKER__CPU_LIMIT_ENABLED`  | `box.docker.cpu_limit_enabled`         |
| `BOX__E2B__API_KEY`               | `box.e2b.api_key`                      |
| `BOX__E2B__API_URL`               | `box.e2b.api_url`                      |
| `BOX__E2B__TEMPLATE`              | `box.e2b.template`                     |

> info:
>
> `langbot_box` サービス側には `BOX__*` や `LANGBOT_BOX_*` を設定しないでください。Box Runtime はこれらを直接読みません——設定は LangBot から INIT RPC 経由で渡されます。

---

# サンドボックス (Sandbox)

Source: https://langbot.app/docs/ja/usage/sandbox/readme

LangBot Box Runtime は組み込み Agent にコマンド・ファイルツールを提供し、サンドボックスまたは信頼済み Host バックエンドを選択可能。

Box Runtime は組み込み Agent に、コマンド実行、ファイルの読み書き、長期常駐プロセスの実行を行う統一インターフェースを提供します。日常的な Agent 用途（データ処理、ファイル操作、ユーザーコードの実行、stdio MCP のホスティング）はすべてこれに依存します。Docker、nsjail、E2B はサンドボックス隔離を提供しますが、明示的に選択する Host バックエンドは信頼できるローカル開発向けで、隔離は提供しません。

Box を有効化すると、組み込み Agent は自動的に 6 つのツールを取得します。パイプラインで個別に有効化する必要はありません。

## 組み込みツール

| ツール     | 用途                      |
| ------- | ----------------------- |
| `exec`  | サンドボックス内で Shell コマンドを実行 |
| `read`  | ワークスペースのファイルを読み取る       |
| `write` | ファイルを作成または上書き           |
| `edit`  | 文字列置換でファイルを編集           |
| `glob`  | glob パターンでファイルを検索       |
| `grep`  | 正規表現でファイル内容を検索          |

`exec` は選択した Box バックエンドで実行されます。残り 5 つは `/workspace` にマッピングされたワークスペースディレクトリを直接読み書きします。Host を選択した場合、コマンドも Box Runtime ホスト上で直接実行されます。

> info:
>
> これらのツールは組み込み Agent 向けです。Dify、n8n、Langflow、Coze などの外部 Runner を使用する場合は、各プラットフォーム独自のツール機構を利用してください。

## サンドボックススコープ

パイプラインの AI 設定で、メッセージ間でサンドボックスをどのように共有するかを選べます。デフォルトの「チャットごと」で多くのシナリオに対応できます。

| スコープ          | テンプレート                                            | 共有範囲                  |
| ------------- | ------------------------------------------------- | --------------------- |
| グローバル         | `{global}`                                        | 全ユーザーが 1 つのサンドボックスを共有 |
| チャットごと（デフォルト） | `{launcher_type}_{launcher_id}`                   | 同じグループ／個人チャットで共有      |
| ユーザーごと        | `{launcher_type}_{launcher_id}_{sender_id}`       | グループ内の各メンバーが独立        |
| 会話ごと          | `{launcher_type}_{launcher_id}_{conversation_id}` | 会話単位で隔離               |
| メッセージごと       | `{query_id}`                                      | 完全にステートレス             |

> warning:
>
> 同一スコープ内のコマンドはファイルシステム状態を共有します。独立したワークスペースが必要な場合は「メッセージごと」を選択してください。スコープはセッション再利用の規則であり、セキュリティ境界ではありません。Host では異なるスコープを使ってもホストレベルの隔離はありません。

## ライフサイクル

| 状況                               | 動作                    |
| -------------------------------- | --------------------- |
| 5 分以上アイドル                        | 自動クリーンアップ             |
| Box がホストするプロセス（stdio MCP など）が稼働中 | クリーンアップしない。プロセス終了後に解放 |
| `persistent: true` 設定時           | 自動クリーンアップなし           |

これらのライフサイクル規則は Host にも適用されます。クリーンアップ時にはセッションの管理対象プロセスツリーを終了し、一時セッションディレクトリを削除します。`box.local.host_root` 配下にマッピングされた永続ワークスペースは一時状態として削除されません。Runtime 終了時や明示的なセッション削除時にもクリーンアップが行われます。

## クイックスタート

Linux / macOS 上の信頼できるローカル開発では、Docker をインストールせず Host を選択できます：

1. **`config.yaml` に記述**:
   ```yaml
   box:
     enabled: true
     backend: 'host'
     local:
       host_root: './data/box'
   ```
2. **LangBot を起動**: Box Runtime は自動的に有効化
3. **パイプラインで** 組み込み Agent と関数呼び出し対応モデルを選択

その後、Agent は自動的に 6 つのツールを取得します。詳細な設定は [サンドボックス設定](https://langbot.app/docs/ja/usage/sandbox/config.md) を参照してください。

> warning:
>
> Host は LangBot / Box Runtime ユーザーの権限でコマンドを直接実行するため、信頼できる入力だけを扱ってください。信頼できないコードを実行する場合は、`backend` を `local`（Docker / Nsjail の自動選択）、`docker`、`nsjail`、または `e2b` に設定してください。

## Box を無効化する

`box.enabled: false` を設定します。サンドボックスに依存するすべての機能（組み込みツール、Skill の作成／編集／起動、stdio MCP）が同時に無効になります。http/sse モードの MCP は影響を受けません。

## 次のステップ

- [サンドボックス設定](https://langbot.app/docs/ja/usage/sandbox/config.md) — バックエンド、セキュリティプリセット、マウント、環境変数
- [ランタイムと拡張機能の関係](https://langbot.app/docs/ja/usage/sandbox/runtime-relationships.md) — サンドボックス、Skills、MCP、プラグインの役割分担

---

# ランタイムと拡張機能の関係

Source: https://langbot.app/docs/ja/usage/sandbox/runtime-relationships

LangBot のランタイムと拡張を理解：Box Runtime・サンドボックスバックエンド・MCP サーバーの関係。

LangBot には **プラグイン、MCP、Skills、サンドボックス** という 4 種類の拡張機構が併存しており、混同されやすい部分です。本ページではそれぞれの役割と使い分けを整理します。

## 一行で区別する

- **Box 実行環境**: Agent がコマンド実行やファイル読み書きを行う場所。隔離の有無は選択したバックエンドによる
- **Skills**: オンデマンドで起動する指示パック。Agent に一時的に専門的なワークフローを追加する
- **MCP サーバー**: 外部のツールサービスに接続する
- **プラグイン**: 長期常駐する拡張プロセス。設定ページ、イベント監視、ナレッジベースを持てる

## 対応表

| 機能       | 提供元                                     | Agent への入り方                                         | いつ使うか                                         |
| -------- | --------------------------------------- | --------------------------------------------------- | --------------------------------------------- |
| Box 実行環境 | Box Runtime                             | `exec/read/write/edit/glob/grep` の 6 点セットを直接付与      | Agent がコード実行やファイル読み書きを行うとき                    |
| Skills   | Box Runtime skill store                 | Agent が `activate` を呼び出した後、指示が Tool Result として注入される | Agent にワークフロー／テンプレート／スクリプトを追加し、必要時にのみ発火させたいとき |
| MCP サーバー | LangBot MCP Loader（stdio モードは Box がホスト） | ツールが利用可能ツール一覧に直接入る                                  | 既存の MCP サービスに接続したいとき                          |
| プラグイン    | Plugin Runtime                          | プラグインシステムから能力が公開される                                 | 長期的な機能、設定ページ／イベント監視／ナレッジコンポーネントが必要なとき         |

## パイプラインへのバインド

Skills、MCP サーバー、プラグインはすべて **パイプライン拡張** に属します。WebUI でインストール／作成した後、パイプライン拡張設定で有効化範囲を決定する必要があります。

- すべての拡張を有効化する、または
- 指定した拡張のみをバインドする

Skills のバインドは Agent が **どの Skill を見えるか** を決定します（`<available_skills>` 一覧に影響）。具体的な Skill 内容は Agent が `activate` を呼び出した後にのみ注入されます。

## バックエンドと隔離境界

Box API、Agent ツール、セッションスコープ、ライフサイクル、Skills、stdio MCP ホスティングの使い方は各バックエンドで同じですが、セキュリティ特性は異なります。Docker、nsjail、E2B はそれぞれのサンドボックス境界を提供します。Host は Box Runtime ホスト上のプロセスを直接使用し、信頼できるローカル開発専用です。Host を選択しても WebUI は変わらず、別々のセッションにホストレベルの隔離が追加されることもありません。

## トラブルシューティングの入口

| 症状                               | まず確認すること                                                          |
| -------------------------------- | ----------------------------------------------------------------- |
| Agent に `exec/read/write` ツールがない | `box.enabled`、バックエンドが利用可能か、パイプラインが組み込み Agent を使用しているか             |
| Skill 一覧が空                       | Box Runtime の状態、`box.local.skills_root`、パイプラインのバインド               |
| stdio MCP の起動に失敗                 | Box Runtime の状態、MCP コマンドと環境変数、起動タイムアウト                            |
| Docker デプロイでサンドボックスが起動しない        | `langbot_box` が `docker.sock` をマウントしているか、Box ルートディレクトリのパスが一致しているか |
| ファイル読み書きに失敗                      | `box.local.host_root`、`box.local.allowed_mount_roots`             |
| バックエンド選択が効かない                    | `BOX__BACKEND` が `langbot_box` ではなく `langbot` サービスに設定されているか確認     |
| Host バックエンドが利用できない               | システムが POSIX で、`PATH` に `sh` があることを確認。Windows では WSL を使用           |
| 外部 Host Box への接続が拒否される           | LangBot と Box Runtime に同じ `LANGBOT_BOX_CONTROL_TOKEN` を設定         |

> info:
>
> サンドボックスの組み込みツールと Skills は、現在は組み込み Agent 向けです。外部 Runner（Dify、n8n、Langflow、Coze など）では、各プラットフォーム独自のツールと実行機構を使用してください。

---

# スキル (Skills)

Source: https://langbot.app/docs/ja/usage/skills/readme

LangBot の Skills を活用し、専門知識を必要に応じて読み込み。コンテキストを圧迫せず AI Agent を拡張。

Skill は**必要時に起動する**指示パックです。ユーザーのリクエストが該当する内容になると、Agent が `activate` ツールを呼び出してその Skill の指示をコンテキストに取り込み、それに従ってタスクを完了させます。起動されていない Skill はコンテキストを消費しません。

Agent に**専門的なワークフロー、テンプレート、スクリプト**を一つ追加するのに向いています。たとえば「Python プロジェクトの解析」「PDF フォーム入力」「コードレビュー」など。System Prompt に全部詰め込む必要はありません。

## プラグイン・MCP との違い

| やりたいこと                             | 使うもの     |
| ---------------------------------- | -------- |
| 必要時に起動する一連のワークフロー（スクリプトやテンプレート付き可） | Skill    |
| 既存の MCP ツールサービスに接続                 | MCP サーバー |
| 長期常駐機能、設定画面、イベント、ナレッジベース           | プラグイン    |

詳細は[ランタイムと拡張機能の関係](https://langbot.app/docs/ja/usage/sandbox/runtime-relationships.md)を参照。

## Skill のインストール

> info:
>
> Skill はサンドボックスに依存します。`box.enabled` が `true` で、Docker / Nsjail / E2B のいずれかが利用可能なときのみ、Skill のインストール、起動、編集ができます。詳細は[サンドボックス設定](https://langbot.app/docs/ja/usage/sandbox/config.md)を参照。

### LangBot Space から（推奨）

[LangBot Space](https://space.langbot.app) は LangBot 公式のマーケットプレイスで、すぐに使える Skill が多数掲載されています。WebUI の Skills ページから閲覧して 1 クリックでインストールでき、`SKILL.md` の作成やリソースファイルの準備は不要です。

ほとんどのケースはこれで十分です。独自のワークフローが必要な場合は下記の方法を使ってください。

### 自分で作る

**WebUI** — Skills ページで新規作成、zip アップロード、GitHub からのインポートが可能。

**サンドボックス + `register_skill`**：

1. サンドボックスの `/workspace` 配下にディレクトリと `SKILL.md` を準備
2. Agent に `register_skill(path="/workspace/my-skill")` を呼び出させる

いずれの方法でも Box Runtime が管理する skill store に書き込まれます。

## パイプラインで有効化

Skill をインストールしたあと、パイプラインの拡張設定で Agent から見える Skill を決めます：

- 「すべての Skill を有効化」をオンにする、または
- 指定した Skill のみをバインドする

バインドは `<available_skills>` 一覧（Agent が選択肢として認識する対象）にのみ影響します。完全な指示は常に `activate` が呼ばれた後に注入されます。

## SKILL.md を書く

Skill はディレクトリと `SKILL.md` 1 つで構成されます。frontmatter にメタデータを書き、本文は Agent が起動後に受け取る指示です：

```markdown
---
name: code-reviewer
display_name: コードレビューアシスタント
description: コードをレビューして改善提案を行う。ユーザーが review、レビュー、コード改善に言及したときに起動
---

## 実行手順

1. `read` で関連ファイルをざっと確認
2. 可読性、潜在的なバグ、セキュリティ問題をチェック
3. 優先度順に改善提案を提示
```

LangBot は現在、以下の 3 つのフィールドを読み取ります：

| フィールド          | 必須     | 説明                                   |
| -------------- | ------ | ------------------------------------ |
| `name`         | 作成／登録時 | 一意の識別子、1–64 文字                       |
| `description`  | 強く推奨   | Agent はこれをもとに起動可否を判断する——具体的なほど選ばれやすい |
| `display_name` | 任意     | UI 表示名                               |

`description` は Agent が Skill を選ぶ唯一の手がかりです。**機能・適用シーン・想定されるトリガーワード**を具体的に書きましょう。

完全な仕様は [agentskills.io](https://agentskills.io/home) を参照してください。その他のフィールド（`license`、`metadata` など）は将来の互換のために残せますが、現在は読み取られません。

**リソースを伴う Skill** では `SKILL.md` と同じ階層に `scripts/`、`templates/` などを置きます。起動後、Agent は `/workspace/.skills/{skill-name}/` でこれらにアクセスできます。

### Agent が使えるツール

| ツール              | 用途                                             |
| ---------------- | ---------------------------------------------- |
| `activate`       | Agent が該当を判断したときに自動で呼び出し、SKILL.md をコンテキストに取り込む |
| `register_skill` | サンドボックスに用意したディレクトリを新しい Skill として登録             |

## よくある問題

| 症状                    | 確認項目                                                                  |
| --------------------- | --------------------------------------------------------------------- |
| Skill 一覧が空            | `box.enabled`、Box Runtime の状態、`box.local.skills_root`                 |
| Agent が Skill を起動しない  | `description` が具体的か、パイプラインでバインドされているか、モデルが関数呼び出しに対応しているか              |
| 起動後にファイルが見つからない       | ファイルは Skill パッケージ内に置く必要があり、パスは `/workspace/.skills/{skill-name}/`     |
| `register_skill` がエラー | パスは `/workspace` 配下である必要があり、ディレクトリまたは 2 階層以内のサブディレクトリに `SKILL.md` が必要 |

> info:
>
> Skills は現在、組み込み Agent 向けで、関数呼び出しとサンドボックスバックエンドに依存します。外部 Runner（Dify、n8n、Langflow、Coze など）では各プラットフォームの同等機構を利用してください。

---

# 302 AIとのモデル統合

Source: https://langbot.app/docs/ja/workshop/302ai-integration

WebUIページを開き、モデルを追加する際に[302 AI](https://share.302ai.cn/SuTG99)を選択します。

![model](https://langbot.app/docs/images/zh/workshop/302ai-integration/model.png)

---

# メッセージプラットフォームアダプターの実装

Source: https://langbot.app/docs/ja/workshop/impl-platform-adapter

この記事では、`aiocqhttp`アダプターを例として、LangBotの新しいメッセージプラットフォームアダプターを実装し、WhatsAppやDiscordなどの新しいメッセージプラットフォームプロトコルを統合する方法を説明します。

## 登録

```text
新しいメッセージプラットフォームアダプターを追加します。例: WhatsApp、Discordなどを統合

- 基底クラス: `pkg.platform.adapter.MessageSourceAdapter`
- デコレーター: `pkg.platform.adapter.adapter_class(name: str)`
- 参考実装: `pkg.platform.sources/`
```

メッセージプラットフォームアダプターを実装するには、基本的に`基底クラス`を継承するクラスを実装し、`デコレーター`を使用して登録する必要があります。最後に、実行時にユーザーが選択して使用できるようになります。

### メインリポジトリへの貢献

`pkg/platform/sources/`ディレクトリに新しいファイル`aiocqhttp.py`を作成します:

```python
from .. import adapter

@adapter.adapter_class("aiocqhttp")
class AiocqhttpAdapter(adapter.MessageSourceAdapter):
    pass
```

また、`pkg/platform/manager.py`の40行目でこのモジュールをインポートします:

```python
        from .sources import nakuru, aiocqhttp, qqbotpy
```

最後に、他のアダプターのマニフェストファイルを参考にして、独自のマニフェストファイルを作成します。

## イベントとメッセージコンバーター

メッセージプラットフォームアダプターの主な作業は、`メッセージプラットフォームプロトコルからイベントを受信し、LangBotの形式に変換する`ことです。これをコアコンポーネントに渡し、LangBotのコアコンポーネントが処理した後、返信する必要のあるコンテンツをメッセージプラットフォームアダプターに渡します。次に、`コンテンツをプラットフォームプロトコル形式に変換してメッセージプラットフォームに送信します`。

次の図は、2つのシナリオの処理パターンを示しています: SDKのないメッセージプラットフォームプロトコルと成熟したSDKを持つプロトコル。最初のケースでは、メッセージプラットフォームプロトコルのドキュメントに従って、接続管理とネットワーク形式データのLBメッセージPythonオブジェクトへの変換を実装する必要があります。2番目のケースでは、メッセージプラットフォームに成熟したSDKがあり、SDKドキュメントに従って接続を作成し、イベントリスナーを登録し、メッセージコンバーターを実装するだけです。

![alt text](https://langbot.app/docs/images/zh/workshop/impl-platform-adapter/workshop_impl_platform_adapter_01.png)

`pkg.platform.sources.aiocqhttp`ファイルでは、`AiocqhttpAdapter`だけでなく、`class AiocqhttpMessageConverter(adapter.MessageConverter):`と`class AiocqhttpEventConverter(adapter.EventConverter):`も確認できます。

- `MessageConverter`は、LangBotメッセージとプラットフォームメッセージ間の変換に使用されます。
- `EventConverter`は、LangBotイベントとプラットフォームイベント間の変換に使用されます。

TBC...

---

# MCPエコシステムの詳細

Source: https://langbot.app/docs/ja/workshop/mcp-details

[MCPプロトコル](https://modelcontextprotocol.io/)は、アプリケーションとLLM間のインタラクションを記述するプロトコルであり、さまざまな製品で採用されています。LangBotはMCPクライアントとして動作し、MCPサーバーに接続して、ユーザーとの会話中にLLMが使用する広範なツールを提供できます。

## MCPサーバーの検索

LangBotでMCPツールを使用するには、既存のMCPサーバーを見つけて接続する必要があります。
市場には2種類のMCPサーバーがあります:

- NodeまたはPythonで実装された実行可能ファイルで、`stdio`(標準入出力)を通じてLangBotと通信します
- HTTPプロトコルに基づくWebサービスで、HTTPプロトコルを通じてLangBotと通信します

> \- 既存のMCPサーバーは\[MCPサーバーリスト]\(https\://github.com/punkpeye/awesome-mcp-servers)で確認できます。:
>
> - オンラインでホストされているMCPサーバーについては、[Composio MCP](https://mcp.composio.dev/)で見つけることができます。
> - 独自のMCPサーバーを作成するには、[MCPプロトコルドキュメント](https://modelcontextprotocol.io/quickstart/server)および[MCPサーバーの例](https://modelcontextprotocol.io/examples)を参照してください。

## MCPサーバーの設定

[システム設定ドキュメント](https://langbot.app/docs/en/deploy/settings.md)を参照してください

設定後、チャットで`!func`コマンドを使用して、登録されたMCPツールを表示できます。Function Callingをサポートするモデルとチャットする際、LangBotは自動的にMCPツールを呼び出します。

---

# ネットワーク設定の詳細

Source: https://langbot.app/docs/ja/workshop/network-details

> 一部のメッセージングプラットフォーム(個人QQアカウントなど)では、メッセージを処理するために独立したプロトコルエンドポイントが必要です。このようなメッセージングプラットフォームを使用している場合は、以下のネットワーク設定を参照してください。:
>
> 同時に、LangBotインスタンスがコンテナで実行されている他のサービス(Ollamaなど)に接続する必要がある場合も、以下の設定を参照して、`メッセージングプラットフォーム`を`接続したいサービス`に置き換えてください。

LangBotと一部のメッセージングプラットフォームは、どちらもDockerを使用してデプロイできます。以下は、4つの異なるシナリオのネットワーク設定の詳細です。

> 目次:
>
> \[\[toc]]

## LangBotとメッセージングプラットフォームの両方がDockerコンテナで実行されている場合

メッセージングプラットフォーム(NapCat/Lagrange)とLangBotの両方がDockerを使用して起動される場合、Dockerのネットワーク接続を設定する必要があります。

新しいネットワークを作成します:

```bash
docker network create langbot-network
```

LangBotディレクトリの`docker-compose.yaml`ファイルにネットワーク設定を追加します(`services.langbot`フィールドに追加し、`networks`フィールドの下に`langbot-network`ネットワーク設定を追加します):

```yaml
services:
  langbot:
    ...
    networks:
      - langbot-network
    ...

networks:
  langbot-network:
    external: true
```

次に、メッセージングプラットフォームの`docker-compose.yaml`ファイルに同じネットワーク設定を追加します(docker runコマンドで直接起動する場合は、起動コマンドに`--network langbot-network`を追加します)。その後、メッセージングプラットフォームの設定ファイルで、WSリバース接続アドレスのIPアドレスを`langbot`に変更します(例: `ws://langbot:2280/ws`)。

両方のコンテナを再起動します。

## LangBotのみがDockerコンテナで実行されている場合

LangBotのみがDockerを使用してデプロイされている場合、ポート2280から2290はデフォルトでコンテナの外部にマッピングされています。この場合、LangBotはWebSocketサーバーとしてのみ動作し、メッセージングプラットフォームからクライアントとしての接続を受け入れることができます。

メッセージングプラットフォームをReverseWebSocket(`reverse ws`または`WebSocketクライアント`と呼ばれます)に設定し、LangBotのaiocqhttpアダプターによって有効にされたポートに対応するポートで、ローカル127.0.0.1に接続します。

## LangBotもメッセージングプラットフォームもDockerデプロイを使用していない場合

ドキュメントに従ってメッセージングプラットフォームとLangBotの設定を行い、両方のポートを同じ未使用のポートに設定し、両方ともローカル127.0.0.1に接続します。

## メッセージングプラットフォームのみがDockerコンテナで実行されている場合(推奨されません)

> warning:
>
> Linuxまたはホストモードのdockerネットワークをサポートする他のシステムのみサポートします。

現在、LangBotのaiocqhttpアダプターはリバースWebSocket接続のみをサポートしています。メッセージングプラットフォームがDockerコンテナで実行され、LangBotがホストマシンで直接実行される場合、メッセージングプラットフォームはLangBotに接続するクライアントとして動作する必要があります。この場合、メッセージングプラットフォームのネットワークを`host`モードに設定し、そのWS接続アドレスを127.0.0.1に設定し、ポートをLangBotのaiocqhttpアダプターによって有効にされたポートに対応させることしかできません。

---

# LangBotとNew APIの統合

Source: https://langbot.app/docs/ja/workshop/newapi-integration

New APIは次世代の大規模モデルゲートウェイおよびAI資産管理システムであり、複数のAIサービスプロバイダーへの断片的なアクセス、コスト管理の難しさ、サービス安定性の不足などの問題に対処するように設計されています。その中心的な利点は、次の3つの側面に焦点を当てています:

1. **マルチプロバイダー互換性**: **30以上のAIサービスプロバイダー**を統合し、**100% OpenAI互換**を実現しています(つまり、OpenAIインターフェース形式で他のサービスプロバイダーのモデルを呼び出すことをサポートし、開発コストを削減します)
2. **高可用性**: **99.9%のサービス可用性**を約束し、エンタープライズレベルの安定性要件を満たします
3. **使いやすさと制御性**: 迅速なアクセスのための「ワンクリックデプロイ」をサポートし、ユーザーがAI使用コストを管理するのに役立つ「柔軟な請求」機能も提供し、「セキュリティと安定性」機能も考慮しています

## 1. New APIをローカルにデプロイする(Dockerコンテナ方式)

> その他のデプロイ方法については、[New APIデプロイガイド](https://docs.newapi.pro/installation/)を参照してください

このデプロイ方法はSQLiteデータベースを使用します(軽量で、追加のデプロイは不要です)。

コマンドラインで次のように入力します:

```bash
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./new-api/data:/data \
  calciumion/new-api:latest
```

> ⚠️ 注意:
>
> - `./new-api/data`を使用したい実際のフォルダーに置き換えてください。

デプロイ後、`http://server-IP:3000`を開いてNew APIを設定します。

## 2. LangBotをローカルのNew APIに接続する

1. **New APIモデルを追加**
   - モデル名: New APIで設定されたモデル名を入力します
   - モデルプロバイダー: New APIを選択します
   - リクエストURL: `http://server-IP:3000/v1`を入力します
   - APIキー: New APIで作成したトークンを入力します

![](https://langbot.app/docs/images/zh/workshop/newapi-integration/model.png)

2. **パイプラインで新しく設定したモデルを選択**

![](https://langbot.app/docs/images/zh/workshop/newapi-integration/model2.png)

3. これで、New APIのモデルを使用できます。

---

# PPIO Cloud APIとのモデル統合

Source: https://langbot.app/docs/ja/workshop/ppio-integration

WebUIページを開き、モデルを追加する際に[PPIO Cloud](https://ppio.cn/user/register?from=ppinfra\&invited_by=QJKFYD\&utm_source=github_langbot)を選択します。

![model](https://langbot.app/docs/images/zh/workshop/ppio-integration/model.png)

---

# HTTPリバースプロキシの設定またはゲートウェイ経由でのLangBotへのアクセス

Source: https://langbot.app/docs/ja/workshop/production/proxy-and-ssl

LangBotにはHTTPSサービス用の組み込みSSLサポートがありません。ドメイン名をLangBotインスタンスに解決する必要がある場合、またはHTTPSを使用してLangBot WebUIとさまざまなボット用のWebhookアドレスにアクセスする必要がある場合は、このドキュメントを参照してNGINXまたはCaddyをデプロイし、HTTPリバースプロキシを実装してください。

公開IPアドレスを持つホストにLangBotをデプロイし、ドメイン名を購入し、ドメイン名をホストの公開IPに解決する必要があります。

> idea:
>
> **設定が面倒ですか？** [LangBot Cloud](https://space.langbot.app/cloud) にはドメインと HTTPS が組み込まれています。サーバーやドメインの購入、リバースプロキシの設定は不要です。登録するだけで Slack、LINE、WeCom などの Webhook プラットフォームをすぐに使用できます。

> warning:
>
> QQ公式ボット、WeChat公式アカウント、WeCom、Slack、LINEなどのWebhookコールバックアドレスが必要なボットを使用する必要がある場合は、このドキュメントに従ってHTTPリバースプロキシを設定する必要があります。

## Caddy

Caddyは、自動HTTPS証明書申請と更新、リバースプロキシ、自動DNS解決設定をサポートする最新のHTTPサーバーです。

[Caddyインストールドキュメント](https://caddy2.dengxiaolong.com/docs/install)。お使いのオペレーティングシステムに対応するインストール手順を選択して、インストールを進めてください。

### Caddyfileの設定

このドキュメントでは、LangBotをデプロイするためにUbuntuシステムを使用することを前提としています。システムでは、Caddyfileのデフォルトの場所は`/etc/caddy/Caddyfile`です。
vimまたはnanoを使用してCaddyfileを編集し、次のようにCaddyfileに記入します:

```json
your.domain.com {
        reverse_proxy 127.0.0.1:5300
}
```

> info:
>
> CaddyとLangBotがコンテナを使用してデプロイされている場合は、[コンテナネットワーク設定の詳細](https://langbot.app/docs/en/workshop/network-details.md)を確認してください

これで、ブラウザを通じて`https://your.domain.com`でLangBot WebUIにアクセスできます。

### ボットコールバックアドレスプレフィックスの設定

QQ公式ボット、WeChat公式アカウント、WeCom、Slack、LINEなどのWebhookコールバックアドレスが必要なボットを使用する必要がある場合は、data/config.yamlファイルで`api.webhook_prefix`をドメイン名に設定してください。例: `https://your.domain.com`。

その後、ボット管理ページに正しく表示されたコールバックアドレスが表示されます。

## NGINX

NGINXも一般的に使用されるHTTPサーバーおよびリバースプロキシツールであり、LangBotへのHTTPSアクセスを実装するために使用できます。

### NGINXのインストール

Ubuntuでは、次のコマンドでNGINXをインストールできます:

```bash
sudo apt update
sudo apt install nginx
```

### SSL証明書の準備

[Let's Encrypt](https://letsencrypt.org/)を使用して無料のSSL証明書を申請できます。証明書を取得するには、[Certbot](https://certbot.eff.org/)ツールの使用をお勧めします:

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx
```

プロンプトに従ってドメイン名を入力すると、証明書の申請とNGINXの設定が自動的に完了します。以下の内容を参照してNGINX設定を完了してください。

### NGINXリバースプロキシの設定

LangBotのパイプラインデバッグ機能では、WebSocket接続を使用する必要があるため、NGINXをWebSocketをサポートするように設定する必要があります。

NGINX設定ファイル`/etc/nginx/sites-available/langbot`を編集します(vimまたはnanoエディターを使用できます):

```nginx
# WebSocket接続アップグレードマッピング(serverブロックの外側に配置)
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name your.domain.com;
    # HTTPトラフィックをHTTPSにリダイレクト
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your.domain.com;

    ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # LangBotインスタンスへのリバースプロキシ
    location / {
        proxy_pass http://127.0.0.1:5300;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocketサポート
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 86400;
    }
}
```

`your.domain.com`を実際のドメイン名に置き換えてください。

この設定を有効にし、NGINXを再起動します:

```bash
sudo ln -s /etc/nginx/sites-available/langbot /etc/nginx/sites-enabled/langbot
sudo nginx -t
sudo systemctl reload nginx
```

### ボットコールバックアドレスプレフィックスの設定

同様に、`data/config.yaml`設定ファイルで`api.webhook_prefix`を`https://your.domain.com`に設定すると、ボットWebhookコールバックアドレスが正しくなります。

上記の設定を完了すると、`https://your.domain.com`を通じてLangBot WebUIとボットWebhookサービスに安全にアクセスできます。

---

# 创建向量模型

Source: https://langbot.app/docs/zh/api-reference/%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B/%E5%88%9B%E5%BB%BA%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## POST /api/v1/provider/models/embedding

创建一个新的向量模型。模型必须关联到一个已存在的供应商。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding": {
      "post": {
        "tags": [
          "向量模型"
        ],
        "summary": "创建向量模型",
        "description": "创建一个新的向量模型。模型必须关联到一个已存在的供应商。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingModelCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModelCreate": {
        "type": "object",
        "required": [
          "name",
          "provider_uuid"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "text-embedding-3-small"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除向量模型

Source: https://langbot.app/docs/zh/api-reference/%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B/%E5%88%A0%E9%99%A4%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## DELETE /api/v1/provider/models/embedding/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}": {
      "delete": {
        "tags": [
          "向量模型"
        ],
        "summary": "删除向量模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新向量模型

Source: https://langbot.app/docs/zh/api-reference/%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B/%E6%9B%B4%E6%96%B0%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## PUT /api/v1/provider/models/embedding/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}": {
      "put": {
        "tags": [
          "向量模型"
        ],
        "summary": "更新向量模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingModelUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModelUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 测试向量模型

Source: https://langbot.app/docs/zh/api-reference/%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B/%E6%B5%8B%E8%AF%95%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## POST /api/v1/provider/models/embedding/{model_uuid}/test

向指定的向量模型发送测试请求，验证模型是否可用。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}/test": {
      "post": {
        "tags": [
          "向量模型"
        ],
        "summary": "测试向量模型",
        "description": "向指定的向量模型发送测试请求，验证模型是否可用。",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "description": "测试用的文本",
                    "example": "Hello"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个向量模型

Source: https://langbot.app/docs/zh/api-reference/%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## GET /api/v1/provider/models/embedding/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding/{model_uuid}": {
      "get": {
        "tags": [
          "向量模型"
        ],
        "summary": "获取单个向量模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "model": {
                          "$ref": "#/components/schemas/EmbeddingModel"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModel": {
        "type": "object",
        "description": "向量模型。通过 provider_uuid 关联到供应商。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID）",
            "example": "text-embedding-3-small"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有向量模型

Source: https://langbot.app/docs/zh/api-reference/%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E5%90%91%E9%87%8F%E6%A8%A1%E5%9E%8B

## GET /api/v1/provider/models/embedding

获取所有向量模型列表。可通过 provider_uuid 过滤特定供应商的模型。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/embedding": {
      "get": {
        "tags": [
          "向量模型"
        ],
        "summary": "获取所有向量模型",
        "description": "获取所有向量模型列表。可通过 provider_uuid 过滤特定供应商的模型。",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "按供应商 UUID 过滤"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "models": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/EmbeddingModel"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EmbeddingModel": {
        "type": "object",
        "description": "向量模型。通过 provider_uuid 关联到供应商。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID）",
            "example": "text-embedding-3-small"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 创建 LLM 模型

Source: https://langbot.app/docs/zh/api-reference/%E5%A4%A7%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9E%8B/%E5%88%9B%E5%BB%BA-llm-%E6%A8%A1%E5%9E%8B

## POST /api/v1/provider/models/llm

创建一个新的大语言模型。模型必须关联到一个已存在的供应商。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm": {
      "post": {
        "tags": [
          "大语言模型"
        ],
        "summary": "创建 LLM 模型",
        "description": "创建一个新的大语言模型。模型必须关联到一个已存在的供应商。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LLMModelCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModelCreate": {
        "type": "object",
        "required": [
          "name",
          "provider_uuid"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID）",
            "example": "gpt-4o"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "chat",
              "vision"
            ]
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer",
            "default": 0
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除 LLM 模型

Source: https://langbot.app/docs/zh/api-reference/%E5%A4%A7%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9E%8B/%E5%88%A0%E9%99%A4-llm-%E6%A8%A1%E5%9E%8B

## DELETE /api/v1/provider/models/llm/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}": {
      "delete": {
        "tags": [
          "大语言模型"
        ],
        "summary": "删除 LLM 模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新 LLM 模型

Source: https://langbot.app/docs/zh/api-reference/%E5%A4%A7%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9E%8B/%E6%9B%B4%E6%96%B0-llm-%E6%A8%A1%E5%9E%8B

## PUT /api/v1/provider/models/llm/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}": {
      "put": {
        "tags": [
          "大语言模型"
        ],
        "summary": "更新 LLM 模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LLMModelUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModelUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "extra_args": {
            "type": "object"
          },
          "prefered_ranking": {
            "type": "integer"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 测试 LLM 模型

Source: https://langbot.app/docs/zh/api-reference/%E5%A4%A7%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9E%8B/%E6%B5%8B%E8%AF%95-llm-%E6%A8%A1%E5%9E%8B

## POST /api/v1/provider/models/llm/{model_uuid}/test

向指定的 LLM 模型发送测试请求，验证模型是否可用。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}/test": {
      "post": {
        "tags": [
          "大语言模型"
        ],
        "summary": "测试 LLM 模型",
        "description": "向指定的 LLM 模型发送测试请求，验证模型是否可用。",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "description": "测试用的提示文本",
                    "example": "Hello"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个 LLM 模型

Source: https://langbot.app/docs/zh/api-reference/%E5%A4%A7%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9E%8B/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA-llm-%E6%A8%A1%E5%9E%8B

## GET /api/v1/provider/models/llm/{model_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm/{model_uuid}": {
      "get": {
        "tags": [
          "大语言模型"
        ],
        "summary": "获取单个 LLM 模型",
        "parameters": [
          {
            "name": "model_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "model": {
                          "$ref": "#/components/schemas/LLMModel"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModel": {
        "type": "object",
        "description": "大语言模型。通过 provider_uuid 关联到供应商，继承供应商的 API 地址和密钥。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID，发送到 API 的 model 参数值）",
            "example": "gpt-4o"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "模型能力标签",
            "example": [
              "chat",
              "vision",
              "tool-use"
            ]
          },
          "extra_args": {
            "type": "object",
            "description": "额外参数（如 temperature、max_tokens 等）"
          },
          "prefered_ranking": {
            "type": "integer",
            "description": "优先级排序（越大越优先）",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有 LLM 模型

Source: https://langbot.app/docs/zh/api-reference/%E5%A4%A7%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9E%8B/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89-llm-%E6%A8%A1%E5%9E%8B

## GET /api/v1/provider/models/llm

获取所有大语言模型列表。可通过 provider_uuid 过滤特定供应商的模型。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/models/llm": {
      "get": {
        "tags": [
          "大语言模型"
        ],
        "summary": "获取所有 LLM 模型",
        "description": "获取所有大语言模型列表。可通过 provider_uuid 过滤特定供应商的模型。",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "按供应商 UUID 过滤"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "models": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/LLMModel"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LLMModel": {
        "type": "object",
        "description": "大语言模型。通过 provider_uuid 关联到供应商，继承供应商的 API 地址和密钥。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "模型名称（即模型 ID，发送到 API 的 model 参数值）",
            "example": "gpt-4o"
          },
          "provider_uuid": {
            "type": "string",
            "format": "uuid",
            "description": "关联的供应商 UUID"
          },
          "abilities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "模型能力标签",
            "example": [
              "chat",
              "vision",
              "tool-use"
            ]
          },
          "extra_args": {
            "type": "object",
            "description": "额外参数（如 temperature、max_tokens 等）"
          },
          "prefered_ranking": {
            "type": "integer",
            "description": "优先级排序（越大越优先）",
            "default": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取工具详情

Source: https://langbot.app/docs/zh/api-reference/%E5%B7%A5%E5%85%B7/%E8%8E%B7%E5%8F%96%E5%B7%A5%E5%85%B7%E8%AF%A6%E6%83%85

## GET /api/v1/tools/{tool_name}

获取指定工具的详细信息。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/tools/{tool_name}": {
      "get": {
        "tags": [
          "工具"
        ],
        "summary": "获取工具详情",
        "description": "获取指定工具的详细信息。",
        "operationId": "getToolDetail",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tool_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "工具名称"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "msg": {
                      "type": "string",
                      "example": "ok"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "tool": {
                          "$ref": "#/components/schemas/ToolSummary"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Tool not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ToolSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Tool name"
          },
          "label": {
            "type": "object",
            "description": "Display label (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "object",
            "description": "Tool description (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "icon": {
            "type": "string",
            "description": "Tool icon"
          },
          "spec": {
            "type": "object",
            "description": "Tool specification",
            "properties": {
              "llm_prompt": {
                "type": "string"
              },
              "parameters": {
                "type": "object",
                "description": "JSON Schema for tool parameters"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有可用工具

Source: https://langbot.app/docs/zh/api-reference/%E5%B7%A5%E5%85%B7/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E5%8F%AF%E7%94%A8%E5%B7%A5%E5%85%B7

## GET /api/v1/tools

获取当前 LangBot 实例中所有可用的工具，包括插件工具和 MCP 工具。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/tools": {
      "get": {
        "tags": [
          "工具"
        ],
        "summary": "获取所有可用工具",
        "description": "获取当前 LangBot 实例中所有可用的工具，包括插件工具和 MCP 工具。",
        "operationId": "listTools",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "msg": {
                      "type": "string",
                      "example": "ok"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "tools": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ToolSummary"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ToolSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Tool name"
          },
          "label": {
            "type": "object",
            "description": "Display label (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "description": {
            "type": "object",
            "description": "Tool description (i18n)",
            "additionalProperties": {
              "type": "string"
            }
          },
          "icon": {
            "type": "string",
            "description": "Tool icon"
          },
          "spec": {
            "type": "object",
            "description": "Tool specification",
            "properties": {
              "llm_prompt": {
                "type": "string"
              },
              "parameters": {
                "type": "object",
                "description": "JSON Schema for tool parameters"
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 从 GitHub 安装插件

Source: https://langbot.app/docs/zh/api-reference/%E6%8F%92%E4%BB%B6/%E4%BB%8E-github-%E5%AE%89%E8%A3%85%E6%8F%92%E4%BB%B6

## POST /api/v1/plugins/install/github

从 GitHub 仓库安装插件。异步操作，返回任务 ID。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/install/github": {
      "post": {
        "tags": [
          "插件"
        ],
        "summary": "从 GitHub 安装插件",
        "description": "从 GitHub 仓库安装插件。异步操作，返回任务 ID。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "GitHub 仓库 URL",
                    "example": "https://github.com/rocksclawbot/langbot-community-plugins/tree/main/disaster-alert"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 从 Marketplace 安装插件

Source: https://langbot.app/docs/zh/api-reference/%E6%8F%92%E4%BB%B6/%E4%BB%8E-marketplace-%E5%AE%89%E8%A3%85%E6%8F%92%E4%BB%B6

## POST /api/v1/plugins/install/marketplace

从 LangBot Marketplace 安装插件。异步操作，返回任务 ID。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/install/marketplace": {
      "post": {
        "tags": [
          "插件"
        ],
        "summary": "从 Marketplace 安装插件",
        "description": "从 LangBot Marketplace 安装插件。异步操作，返回任务 ID。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plugin_id"
                ],
                "properties": {
                  "plugin_id": {
                    "type": "string",
                    "description": "Marketplace 插件 ID（author/name 格式）",
                    "example": "kellz-dev/disaster-alert"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除插件

Source: https://langbot.app/docs/zh/api-reference/%E6%8F%92%E4%BB%B6/%E5%88%A0%E9%99%A4%E6%8F%92%E4%BB%B6

## DELETE /api/v1/plugins/{author}/{plugin_name}

异步删除插件，返回任务 ID。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}": {
      "delete": {
        "tags": [
          "插件"
        ],
        "summary": "删除插件",
        "description": "异步删除插件，返回任务 ID。",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "delete_data",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "是否同时删除插件数据"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 升级插件

Source: https://langbot.app/docs/zh/api-reference/%E6%8F%92%E4%BB%B6/%E5%8D%87%E7%BA%A7%E6%8F%92%E4%BB%B6

## POST /api/v1/plugins/{author}/{plugin_name}/upgrade

异步升级插件到最新版本，返回任务 ID。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}/upgrade": {
      "post": {
        "tags": [
          "插件"
        ],
        "summary": "升级插件",
        "description": "异步升级插件到最新版本，返回任务 ID。",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新插件配置

Source: https://langbot.app/docs/zh/api-reference/%E6%8F%92%E4%BB%B6/%E6%9B%B4%E6%96%B0%E6%8F%92%E4%BB%B6%E9%85%8D%E7%BD%AE

## PUT /api/v1/plugins/{author}/{plugin_name}/config



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}/config": {
      "put": {
        "tags": [
          "插件"
        ],
        "summary": "更新插件配置",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "插件配置键值对"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取已安装插件列表

Source: https://langbot.app/docs/zh/api-reference/%E6%8F%92%E4%BB%B6/%E8%8E%B7%E5%8F%96%E5%B7%B2%E5%AE%89%E8%A3%85%E6%8F%92%E4%BB%B6%E5%88%97%E8%A1%A8

## GET /api/v1/plugins



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins": {
      "get": {
        "tags": [
          "插件"
        ],
        "summary": "获取已安装插件列表",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "plugins": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取插件详情

Source: https://langbot.app/docs/zh/api-reference/%E6%8F%92%E4%BB%B6/%E8%8E%B7%E5%8F%96%E6%8F%92%E4%BB%B6%E8%AF%A6%E6%83%85

## GET /api/v1/plugins/{author}/{plugin_name}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}": {
      "get": {
        "tags": [
          "插件"
        ],
        "summary": "获取插件详情",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "plugin": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取插件配置

Source: https://langbot.app/docs/zh/api-reference/%E6%8F%92%E4%BB%B6/%E8%8E%B7%E5%8F%96%E6%8F%92%E4%BB%B6%E9%85%8D%E7%BD%AE

## GET /api/v1/plugins/{author}/{plugin_name}/config

获取插件的当前配置值和配置模式。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/plugins/{author}/{plugin_name}/config": {
      "get": {
        "tags": [
          "插件"
        ],
        "summary": "获取插件配置",
        "description": "获取插件的当前配置值和配置模式。",
        "parameters": [
          {
            "name": "author",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "plugin_name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 上传图片

Source: https://langbot.app/docs/zh/api-reference/%E6%96%87%E4%BB%B6/%E4%B8%8A%E4%BC%A0%E5%9B%BE%E7%89%87

## POST /api/v1/files/images

上传图片文件，支持 jpg、jpeg、png、gif、webp 格式，大小限制 10MB。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/files/images": {
      "post": {
        "tags": [
          "文件"
        ],
        "summary": "上传图片",
        "description": "上传图片文件，支持 jpg、jpeg、png、gif、webp 格式，大小限制 10MB。",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "图片文件"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上传成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "file_key": {
                          "type": "string",
                          "description": "文件标识符，可用于引用图片"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 上传文档

Source: https://langbot.app/docs/zh/api-reference/%E6%96%87%E4%BB%B6/%E4%B8%8A%E4%BC%A0%E6%96%87%E6%A1%A3

## POST /api/v1/files/documents

上传文档文件，大小限制 10MB。上传后可将 file_id 用于知识库关联。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/files/documents": {
      "post": {
        "tags": [
          "文件"
        ],
        "summary": "上传文档",
        "description": "上传文档文件，大小限制 10MB。上传后可将 file_id 用于知识库关联。",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "文档文件"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上传成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "file_id": {
                          "type": "string",
                          "description": "文件 ID，可用于知识库关联"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 创建机器人

Source: https://langbot.app/docs/zh/api-reference/%E6%9C%BA%E5%99%A8%E4%BA%BA/%E5%88%9B%E5%BB%BA%E6%9C%BA%E5%99%A8%E4%BA%BA

## POST /api/v1/platform/bots



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots": {
      "post": {
        "tags": [
          "机器人"
        ],
        "summary": "创建机器人",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BotCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BotCreate": {
        "type": "object",
        "required": [
          "name",
          "adapter",
          "config"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除机器人

Source: https://langbot.app/docs/zh/api-reference/%E6%9C%BA%E5%99%A8%E4%BA%BA/%E5%88%A0%E9%99%A4%E6%9C%BA%E5%99%A8%E4%BA%BA

## DELETE /api/v1/platform/bots/{bot_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}": {
      "delete": {
        "tags": [
          "机器人"
        ],
        "summary": "删除机器人",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新机器人

Source: https://langbot.app/docs/zh/api-reference/%E6%9C%BA%E5%99%A8%E4%BA%BA/%E6%9B%B4%E6%96%B0%E6%9C%BA%E5%99%A8%E4%BA%BA

## PUT /api/v1/platform/bots/{bot_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}": {
      "put": {
        "tags": [
          "机器人"
        ],
        "summary": "更新机器人",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BotUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BotUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个机器人

Source: https://langbot.app/docs/zh/api-reference/%E6%9C%BA%E5%99%A8%E4%BA%BA/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E6%9C%BA%E5%99%A8%E4%BA%BA

## GET /api/v1/platform/bots/{bot_uuid}

获取机器人信息，包括运行时信息（如 Webhook 地址等）。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}": {
      "get": {
        "tags": [
          "机器人"
        ],
        "summary": "获取单个机器人",
        "description": "获取机器人信息，包括运行时信息（如 Webhook 地址等）。",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bot": {
                          "$ref": "#/components/schemas/Bot"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Bot": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string",
            "example": "telegram"
          },
          "config": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有机器人

Source: https://langbot.app/docs/zh/api-reference/%E6%9C%BA%E5%99%A8%E4%BA%BA/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E6%9C%BA%E5%99%A8%E4%BA%BA

## GET /api/v1/platform/bots



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots": {
      "get": {
        "tags": [
          "机器人"
        ],
        "summary": "获取所有机器人",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bots": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Bot"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Bot": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "adapter": {
            "type": "string",
            "example": "telegram"
          },
          "config": {
            "type": "object"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取机器人事件日志

Source: https://langbot.app/docs/zh/api-reference/%E6%9C%BA%E5%99%A8%E4%BA%BA/%E8%8E%B7%E5%8F%96%E6%9C%BA%E5%99%A8%E4%BA%BA%E4%BA%8B%E4%BB%B6%E6%97%A5%E5%BF%97

## POST /api/v1/platform/bots/{bot_uuid}/logs

获取指定机器人的事件日志记录。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}/logs": {
      "post": {
        "tags": [
          "机器人"
        ],
        "summary": "获取机器人事件日志",
        "description": "获取指定机器人的事件日志记录。",
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from_index": {
                    "type": "integer",
                    "description": "起始索引（-1 表示从最新开始）",
                    "default": -1
                  },
                  "max_count": {
                    "type": "integer",
                    "description": "最大返回数量",
                    "default": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "logs": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "total_count": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 通过机器人发送消息

Source: https://langbot.app/docs/zh/api-reference/%E6%9C%BA%E5%99%A8%E4%BA%BA/%E9%80%9A%E8%BF%87%E6%9C%BA%E5%99%A8%E4%BA%BA%E5%8F%91%E9%80%81%E6%B6%88%E6%81%AF

## POST /api/v1/platform/bots/{bot_uuid}/send_message

通过指定的机器人向目标发送消息。仅支持 API Key 认证。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v1/platform/bots/{bot_uuid}/send_message": {
      "post": {
        "tags": [
          "机器人"
        ],
        "summary": "通过机器人发送消息",
        "description": "通过指定的机器人向目标发送消息。仅支持 API Key 认证。",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bot_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "target_type",
                  "target_id",
                  "message_chain"
                ],
                "properties": {
                  "target_type": {
                    "type": "string",
                    "enum": [
                      "person",
                      "group"
                    ],
                    "description": "目标类型"
                  },
                  "target_id": {
                    "type": "string",
                    "description": "目标 ID（用户 ID 或群组 ID）"
                  },
                  "message_chain": {
                    "type": "array",
                    "description": "消息链",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "Plain",
                            "Image",
                            "At",
                            "Voice"
                          ],
                          "description": "消息元素类型"
                        },
                        "text": {
                          "type": "string",
                          "description": "文本内容（Plain 类型）"
                        },
                        "url": {
                          "type": "string",
                          "description": "图片 URL（Image 类型）"
                        },
                        "target": {
                          "type": "string",
                          "description": "@ 的目标 ID（At 类型）"
                        }
                      }
                    },
                    "example": [
                      {
                        "type": "Plain",
                        "text": "Hello, World!"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "发送成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "sent": {
                          "type": "boolean",
                          "example": true
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```

---

# 创建供应商

Source: https://langbot.app/docs/zh/api-reference/%E6%A8%A1%E5%9E%8B%E4%BE%9B%E5%BA%94%E5%95%86/%E5%88%9B%E5%BB%BA%E4%BE%9B%E5%BA%94%E5%95%86

## POST /api/v1/provider/providers

创建一个新的模型供应商。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers": {
      "post": {
        "tags": [
          "模型供应商"
        ],
        "summary": "创建供应商",
        "description": "创建一个新的模型供应商。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelProviderCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProviderCreate": {
        "type": "object",
        "required": [
          "name",
          "requester",
          "base_url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "OpenAI"
          },
          "requester": {
            "type": "string",
            "description": "请求器类型。可通过 GET /api/v1/provider/requesters 获取可用列表。",
            "example": "openai-chat-completions"
          },
          "base_url": {
            "type": "string",
            "example": "https://api.openai.com/v1"
          },
          "api_keys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "sk-xxx"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除供应商

Source: https://langbot.app/docs/zh/api-reference/%E6%A8%A1%E5%9E%8B%E4%BE%9B%E5%BA%94%E5%95%86/%E5%88%A0%E9%99%A4%E4%BE%9B%E5%BA%94%E5%95%86

## DELETE /api/v1/provider/providers/{provider_uuid}

删除供应商。如果还有模型引用该供应商，则无法删除。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers/{provider_uuid}": {
      "delete": {
        "tags": [
          "模型供应商"
        ],
        "summary": "删除供应商",
        "description": "删除供应商。如果还有模型引用该供应商，则无法删除。",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          },
          "400": {
            "description": "供应商仍有模型引用，无法删除",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新供应商

Source: https://langbot.app/docs/zh/api-reference/%E6%A8%A1%E5%9E%8B%E4%BE%9B%E5%BA%94%E5%95%86/%E6%9B%B4%E6%96%B0%E4%BE%9B%E5%BA%94%E5%95%86

## PUT /api/v1/provider/providers/{provider_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers/{provider_uuid}": {
      "put": {
        "tags": [
          "模型供应商"
        ],
        "summary": "更新供应商",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModelProviderUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProviderUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "requester": {
            "type": "string"
          },
          "base_url": {
            "type": "string"
          },
          "api_keys": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个供应商

Source: https://langbot.app/docs/zh/api-reference/%E6%A8%A1%E5%9E%8B%E4%BE%9B%E5%BA%94%E5%95%86/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E4%BE%9B%E5%BA%94%E5%95%86

## GET /api/v1/provider/providers/{provider_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers/{provider_uuid}": {
      "get": {
        "tags": [
          "模型供应商"
        ],
        "summary": "获取单个供应商",
        "parameters": [
          {
            "name": "provider_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "provider": {
                          "$ref": "#/components/schemas/ModelProvider"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProvider": {
        "type": "object",
        "description": "模型供应商。定义了 API 地址和密钥，模型通过 provider_uuid 关联。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "OpenAI"
          },
          "requester": {
            "type": "string",
            "description": "请求器类型",
            "example": "openai-chat-completions"
          },
          "base_url": {
            "type": "string",
            "description": "API 基础地址",
            "example": "https://api.openai.com/v1"
          },
          "api_keys": {
            "type": "array",
            "description": "API 密钥列表",
            "items": {
              "type": "string"
            }
          },
          "llm_count": {
            "type": "integer",
            "description": "关联的 LLM 模型数量"
          },
          "embedding_count": {
            "type": "integer",
            "description": "关联的 Embedding 模型数量"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有供应商

Source: https://langbot.app/docs/zh/api-reference/%E6%A8%A1%E5%9E%8B%E4%BE%9B%E5%BA%94%E5%95%86/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E4%BE%9B%E5%BA%94%E5%95%86

## GET /api/v1/provider/providers

获取所有模型供应商列表，包含每个供应商关联的 LLM 和 Embedding 模型数量。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/provider/providers": {
      "get": {
        "tags": [
          "模型供应商"
        ],
        "summary": "获取所有供应商",
        "description": "获取所有模型供应商列表，包含每个供应商关联的 LLM 和 Embedding 模型数量。",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "providers": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ModelProvider"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ModelProvider": {
        "type": "object",
        "description": "模型供应商。定义了 API 地址和密钥，模型通过 provider_uuid 关联。",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "OpenAI"
          },
          "requester": {
            "type": "string",
            "description": "请求器类型",
            "example": "openai-chat-completions"
          },
          "base_url": {
            "type": "string",
            "description": "API 基础地址",
            "example": "https://api.openai.com/v1"
          },
          "api_keys": {
            "type": "array",
            "description": "API 密钥列表",
            "items": {
              "type": "string"
            }
          },
          "llm_count": {
            "type": "integer",
            "description": "关联的 LLM 模型数量"
          },
          "embedding_count": {
            "type": "integer",
            "description": "关联的 Embedding 模型数量"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 创建流水线

Source: https://langbot.app/docs/zh/api-reference/%E6%B5%81%E6%B0%B4%E7%BA%BF/%E5%88%9B%E5%BB%BA%E6%B5%81%E6%B0%B4%E7%BA%BF

## POST /api/v1/pipelines



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines": {
      "post": {
        "tags": [
          "流水线"
        ],
        "summary": "创建流水线",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PipelineCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PipelineCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除流水线

Source: https://langbot.app/docs/zh/api-reference/%E6%B5%81%E6%B0%B4%E7%BA%BF/%E5%88%A0%E9%99%A4%E6%B5%81%E6%B0%B4%E7%BA%BF

## DELETE /api/v1/pipelines/{pipeline_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}": {
      "delete": {
        "tags": [
          "流水线"
        ],
        "summary": "删除流水线",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 复制流水线

Source: https://langbot.app/docs/zh/api-reference/%E6%B5%81%E6%B0%B4%E7%BA%BF/%E5%A4%8D%E5%88%B6%E6%B5%81%E6%B0%B4%E7%BA%BF

## POST /api/v1/pipelines/{pipeline_uuid}/copy

复制一个已有的流水线，生成一个新的副本。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}/copy": {
      "post": {
        "tags": [
          "流水线"
        ],
        "summary": "复制流水线",
        "description": "复制一个已有的流水线，生成一个新的副本。",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "复制成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新流水线

Source: https://langbot.app/docs/zh/api-reference/%E6%B5%81%E6%B0%B4%E7%BA%BF/%E6%9B%B4%E6%96%B0%E6%B5%81%E6%B0%B4%E7%BA%BF

## PUT /api/v1/pipelines/{pipeline_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}": {
      "put": {
        "tags": [
          "流水线"
        ],
        "summary": "更新流水线",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PipelineUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PipelineUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "is_default": {
            "type": "boolean"
          }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新流水线扩展配置

Source: https://langbot.app/docs/zh/api-reference/%E6%B5%81%E6%B0%B4%E7%BA%BF/%E6%9B%B4%E6%96%B0%E6%B5%81%E6%B0%B4%E7%BA%BF%E6%89%A9%E5%B1%95%E9%85%8D%E7%BD%AE

## PUT /api/v1/pipelines/{pipeline_uuid}/extensions

更新流水线绑定的插件和 MCP 服务器。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}/extensions": {
      "put": {
        "tags": [
          "流水线"
        ],
        "summary": "更新流水线扩展配置",
        "description": "更新流水线绑定的插件和 MCP 服务器。",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enable_all_plugins": {
                    "type": "boolean",
                    "default": true
                  },
                  "enable_all_mcp_servers": {
                    "type": "boolean",
                    "default": true
                  },
                  "bound_plugins": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "bound_mcp_servers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个流水线

Source: https://langbot.app/docs/zh/api-reference/%E6%B5%81%E6%B0%B4%E7%BA%BF/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E6%B5%81%E6%B0%B4%E7%BA%BF

## GET /api/v1/pipelines/{pipeline_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}": {
      "get": {
        "tags": [
          "流水线"
        ],
        "summary": "获取单个流水线",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "pipeline": {
                          "$ref": "#/components/schemas/Pipeline"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pipeline": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有流水线

Source: https://langbot.app/docs/zh/api-reference/%E6%B5%81%E6%B0%B4%E7%BA%BF/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E6%B5%81%E6%B0%B4%E7%BA%BF

## GET /api/v1/pipelines



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines": {
      "get": {
        "tags": [
          "流水线"
        ],
        "summary": "获取所有流水线",
        "parameters": [
          {
            "name": "sort_by",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "created_at"
            }
          },
          {
            "name": "sort_order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ],
              "default": "DESC"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "pipelines": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Pipeline"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pipeline": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "config": {
            "type": "object"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取流水线元数据

Source: https://langbot.app/docs/zh/api-reference/%E6%B5%81%E6%B0%B4%E7%BA%BF/%E8%8E%B7%E5%8F%96%E6%B5%81%E6%B0%B4%E7%BA%BF%E5%85%83%E6%95%B0%E6%8D%AE

## GET /api/v1/pipelines/_/metadata

获取流水线配置的元数据描述，包括可配置的字段和类型信息。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/_/metadata": {
      "get": {
        "tags": [
          "流水线"
        ],
        "summary": "获取流水线元数据",
        "description": "获取流水线配置的元数据描述，包括可配置的字段和类型信息。",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "configs": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取流水线扩展配置

Source: https://langbot.app/docs/zh/api-reference/%E6%B5%81%E6%B0%B4%E7%BA%BF/%E8%8E%B7%E5%8F%96%E6%B5%81%E6%B0%B4%E7%BA%BF%E6%89%A9%E5%B1%95%E9%85%8D%E7%BD%AE

## GET /api/v1/pipelines/{pipeline_uuid}/extensions

获取流水线绑定的插件和 MCP 服务器配置。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/pipelines/{pipeline_uuid}/extensions": {
      "get": {
        "tags": [
          "流水线"
        ],
        "summary": "获取流水线扩展配置",
        "description": "获取流水线绑定的插件和 MCP 服务器配置。",
        "parameters": [
          {
            "name": "pipeline_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "enable_all_plugins": {
                          "type": "boolean"
                        },
                        "enable_all_mcp_servers": {
                          "type": "boolean"
                        },
                        "bound_plugins": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "available_plugins": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "bound_mcp_servers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "available_mcp_servers": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 从知识库删除文件

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BA%93/%E4%BB%8E%E7%9F%A5%E8%AF%86%E5%BA%93%E5%88%A0%E9%99%A4%E6%96%87%E4%BB%B6

## DELETE /api/v1/knowledge/bases/{kb_uuid}/files/{file_id}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": {
      "delete": {
        "tags": [
          "知识库"
        ],
        "summary": "从知识库删除文件",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "file_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 创建知识库

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BA%93/%E5%88%9B%E5%BB%BA%E7%9F%A5%E8%AF%86%E5%BA%93

## POST /api/v1/knowledge/bases



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases": {
      "post": {
        "tags": [
          "知识库"
        ],
        "summary": "创建知识库",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "engine_plugin_id": {
                    "type": "string",
                    "description": "知识引擎插件 ID（author/name 格式）"
                  },
                  "creation_settings": {
                    "type": "object",
                    "description": "引擎创建参数"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "创建成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "uuid": {
                          "type": "string",
                          "format": "uuid"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 删除知识库

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BA%93/%E5%88%A0%E9%99%A4%E7%9F%A5%E8%AF%86%E5%BA%93

## DELETE /api/v1/knowledge/bases/{kb_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}": {
      "delete": {
        "tags": [
          "知识库"
        ],
        "summary": "删除知识库",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 将文件存入知识库

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BA%93/%E5%B0%86%E6%96%87%E4%BB%B6%E5%AD%98%E5%85%A5%E7%9F%A5%E8%AF%86%E5%BA%93

## POST /api/v1/knowledge/bases/{kb_uuid}/files

将已上传的文件关联到知识库并开始解析。先通过 /api/v1/files/documents 上传文件获取 file_id。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/files": {
      "post": {
        "tags": [
          "知识库"
        ],
        "summary": "将文件存入知识库",
        "description": "将已上传的文件关联到知识库并开始解析。先通过 /api/v1/files/documents 上传文件获取 file_id。",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "file_id"
                ],
                "properties": {
                  "file_id": {
                    "type": "string",
                    "description": "已上传的文件 ID"
                  },
                  "parser_plugin_id": {
                    "type": "string",
                    "description": "指定的解析器插件 ID（可选）"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "task_id": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 更新知识库

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BA%93/%E6%9B%B4%E6%96%B0%E7%9F%A5%E8%AF%86%E5%BA%93

## PUT /api/v1/knowledge/bases/{kb_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}": {
      "put": {
        "tags": [
          "知识库"
        ],
        "summary": "更新知识库",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/Success"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Success": {
        "description": "操作成功",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "integer",
                  "example": 0
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 检索知识库

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BA%93/%E6%A3%80%E7%B4%A2%E7%9F%A5%E8%AF%86%E5%BA%93

## POST /api/v1/knowledge/bases/{kb_uuid}/retrieve

对知识库进行语义检索，返回相关文档片段。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/retrieve": {
      "post": {
        "tags": [
          "知识库"
        ],
        "summary": "检索知识库",
        "description": "对知识库进行语义检索，返回相关文档片段。",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "query"
                ],
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "检索查询文本"
                  },
                  "retrieval_settings": {
                    "type": "object",
                    "description": "检索参数（如 top_k 等）",
                    "properties": {
                      "top_k": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取单个知识库

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BA%93/%E8%8E%B7%E5%8F%96%E5%8D%95%E4%B8%AA%E7%9F%A5%E8%AF%86%E5%BA%93

## GET /api/v1/knowledge/bases/{kb_uuid}



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}": {
      "get": {
        "tags": [
          "知识库"
        ],
        "summary": "获取单个知识库",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "base": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "NotFound": {
        "description": "资源未找到",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer",
            "example": -1
          },
          "msg": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取所有知识库

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BA%93/%E8%8E%B7%E5%8F%96%E6%89%80%E6%9C%89%E7%9F%A5%E8%AF%86%E5%BA%93

## GET /api/v1/knowledge/bases



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases": {
      "get": {
        "tags": [
          "知识库"
        ],
        "summary": "获取所有知识库",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bases": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取知识库文件列表

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BA%93/%E8%8E%B7%E5%8F%96%E7%9F%A5%E8%AF%86%E5%BA%93%E6%96%87%E4%BB%B6%E5%88%97%E8%A1%A8

## GET /api/v1/knowledge/bases/{kb_uuid}/files



Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/bases/{kb_uuid}/files": {
      "get": {
        "tags": [
          "知识库"
        ],
        "summary": "获取知识库文件列表",
        "parameters": [
          {
            "name": "kb_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "files": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取可用知识引擎列表

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BC%95%E6%93%8E/%E8%8E%B7%E5%8F%96%E5%8F%AF%E7%94%A8%E7%9F%A5%E8%AF%86%E5%BC%95%E6%93%8E%E5%88%97%E8%A1%A8

## GET /api/v1/knowledge/engines

列出所有由插件提供的知识引擎，包含其能力和配置模式。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/engines": {
      "get": {
        "tags": [
          "知识引擎"
        ],
        "summary": "获取可用知识引擎列表",
        "description": "列出所有由插件提供的知识引擎，包含其能力和配置模式。",
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "engines": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取知识引擎创建配置模式

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BC%95%E6%93%8E/%E8%8E%B7%E5%8F%96%E7%9F%A5%E8%AF%86%E5%BC%95%E6%93%8E%E5%88%9B%E5%BB%BA%E9%85%8D%E7%BD%AE%E6%A8%A1%E5%BC%8F

## GET /api/v1/knowledge/engines/{plugin_id}/creation-schema

获取指定知识引擎的创建参数 JSON Schema。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/engines/{plugin_id}/creation-schema": {
      "get": {
        "tags": [
          "知识引擎"
        ],
        "summary": "获取知识引擎创建配置模式",
        "description": "获取指定知识引擎的创建参数 JSON Schema。",
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "插件 ID（author/name 格式）"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取知识引擎检索配置模式

Source: https://langbot.app/docs/zh/api-reference/%E7%9F%A5%E8%AF%86%E5%BC%95%E6%93%8E/%E8%8E%B7%E5%8F%96%E7%9F%A5%E8%AF%86%E5%BC%95%E6%93%8E%E6%A3%80%E7%B4%A2%E9%85%8D%E7%BD%AE%E6%A8%A1%E5%BC%8F

## GET /api/v1/knowledge/engines/{plugin_id}/retrieval-schema

获取指定知识引擎的检索参数 JSON Schema。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/engines/{plugin_id}/retrieval-schema": {
      "get": {
        "tags": [
          "知识引擎"
        ],
        "summary": "获取知识引擎检索配置模式",
        "description": "获取指定知识引擎的检索参数 JSON Schema。",
        "parameters": [
          {
            "name": "plugin_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "插件 ID（author/name 格式）"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "schema": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# 获取系统信息

Source: https://langbot.app/docs/zh/api-reference/%E7%B3%BB%E7%BB%9F/%E8%8E%B7%E5%8F%96%E7%B3%BB%E7%BB%9F%E4%BF%A1%E6%81%AF

## GET /api/v1/system/info

获取 LangBot 实例的版本、版本类型等基本信息。此接口无需认证。

No authentication required.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/system/info": {
      "get": {
        "tags": [
          "系统"
        ],
        "summary": "获取系统信息",
        "description": "获取 LangBot 实例的版本、版本类型等基本信息。此接口无需认证。",
        "security": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string",
                          "example": "v4.9.5"
                        },
                        "debug": {
                          "type": "boolean"
                        },
                        "edition": {
                          "type": "string",
                          "example": "community"
                        },
                        "enable_marketplace": {
                          "type": "boolean"
                        },
                        "cloud_service_url": {
                          "type": "string"
                        },
                        "allow_modify_login_info": {
                          "type": "boolean"
                        },
                        "disable_models_service": {
                          "type": "boolean"
                        },
                        "limitation": {
                          "type": "object"
                        },
                        "wizard_status": {
                          "type": "string",
                          "enum": [
                            "none",
                            "skipped",
                            "completed"
                          ]
                        },
                        "wizard_progress": {
                          "type": "object",
                          "nullable": true
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {}
}
```

---

# 获取可用解析器列表

Source: https://langbot.app/docs/zh/api-reference/%E8%A7%A3%E6%9E%90%E5%99%A8/%E8%8E%B7%E5%8F%96%E5%8F%AF%E7%94%A8%E8%A7%A3%E6%9E%90%E5%99%A8%E5%88%97%E8%A1%A8

## GET /api/v1/knowledge/parsers

列出所有由插件提供的文件解析器。可通过 mime_type 过滤。

Authentication (OpenAPI security alternatives; OR between entries, AND within each entry): [{"ApiKeyAuth":[]},{"BearerAuth":[]}]. See components.securitySchemes below for header names, schemes and scopes.

Servers: http://localhost:5300. Use your own LangBot instance, not the documentation host.

[Complete zh OpenAPI specification](https://langbot.app/docs/openapi/service-api-zh.json)

## Operation contract

The OpenAPI subset below preserves path/operation parameters, request bodies, response codes, media types, examples and schemas. All referenced components are included transitively; resolve local JSON pointers against this document. The operation is preserved verbatim, including security overrides.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "LangBot Service API",
    "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer <token>`）\n- API 密钥（通过 `X-API-Key: <key>` 或 `Authorization: Bearer <key>`）\n\n本文档中的所有接口都同时支持这两种认证方式（除特别说明外）。\n",
    "version": "4.9.5",
    "contact": {
      "name": "LangBot",
      "url": "https://langbot.app"
    },
    "license": {
      "name": "AGPL-3.0",
      "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE"
    }
  },
  "servers": [
    {
      "url": "http://localhost:5300",
      "description": "本地开发服务器"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/knowledge/parsers": {
      "get": {
        "tags": [
          "解析器"
        ],
        "summary": "获取可用解析器列表",
        "description": "列出所有由插件提供的文件解析器。可通过 mime_type 过滤。",
        "parameters": [
          {
            "name": "mime_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "按 MIME 类型过滤解析器"
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "integer",
                      "example": 0
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "parsers": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```

---

# LangBot 文章

Source: https://langbot.app/docs/zh/articles

同步自 LangBot Blog 的产品动态、技术解析、教程、集成实践与公告。

同步自 LangBot Blog 的产品动态、技术解析、教程、集成实践与公告。

## 产品动态

- [LangBot Cloud 新版上线：多用户 Workspace 也来到开源版](https://langbot.app/docs/zh/articles/langbot-cloud-multi-user-workspaces.md) — 2026-08-25

## 技术解析

- [LangBot v4.10.0：Agent 沙箱与技能——让 Agent 真正像开发者一样工作](https://langbot.app/docs/zh/articles/langbot-v4100-sandbox-skills.md) — 2026-06-04
- [LangBot v4.9.0：知识库全面插件化——RAG 引擎、解析器与无边界知识架构](https://langbot.app/docs/zh/articles/langbot-v490-rag-plugin-architecture.md) — 2026-03-10
- [深入 LangBot 插件系统：进程隔离、事件驱动与组件化架构](https://langbot.app/docs/zh/articles/langbot-plugin-system-deep-dive.md) — 2026-02-23

## 教程与集成

- [LangTARS：开源 AI Agent 远程控制电脑 — 支持接入 Dify 和 n8n 工作流](https://langbot.app/docs/zh/articles/langtars-remote-pc-control-dify-n8n.md) — 2026-03-23
- [5分钟将 DeepSeek R1 接入微信、企业微信与 Discord (免费教程)](https://langbot.app/docs/zh/articles/connect-deepseek-to-wechat.md) — 2026-02-21
- [5 分钟部署你的 AI 机器人到 Discord、Telegram 和微信](https://langbot.app/docs/zh/articles/deploy-ai-bot-in-5-minutes.md) — 2026-02-17
- [终于让 Dify Agent 在 Discord、Telegram 和 Slack 上跑起来了](https://langbot.app/docs/zh/articles/dify-agent-discord-telegram-slack.md) — 2025-12-11
- [用 Langflow 拖拽式工作流构建多平台 AI 机器人](https://langbot.app/docs/zh/articles/langflow-drag-and-drop-ai-bot.md) — 2025-12-05
- [用 n8n 和 LangBot 构建多平台 AI 聊天机器人](https://langbot.app/docs/zh/articles/n8n-multi-platform-ai-chatbot.md) — 2025-12-03
- [LangBot 4.6.0 外部知识库教程：集成 Dify 实现 RAG 对话](https://langbot.app/docs/zh/articles/dify-langbot-rag-knowledge-base.md) — 2025-12-02

## 公告

- [LangBot 博客正式上线](https://langbot.app/docs/zh/articles/welcome.md) — 2026-02-17

---

# 5分钟将 DeepSeek R1 接入微信、企业微信与 Discord (免费教程)

Source: https://langbot.app/docs/zh/articles/connect-deepseek-to-wechat

手把手教你使用 LangBot 将 DeepSeek R1/V3 (官方/硅基流动 API) 接入个人微信、企业微信、钉钉和飞书。无需写代码，支持联网搜索与知识库。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/connect-deepseek-to-wechat).

发布于 2026-02-21 · 作者：LangBot Team

![DeepSeek x WeChat Integration](https://langbot.app/docs/images/articles/source/images/covers/deepseek-wechat.png)

DeepSeek 已经引爆了 AI 圈。其 R1 推理模型在逻辑能力上媲美 OpenAI o1，但它是开源的，而且 API 价格极低（甚至免费）。

然而，DeepSeek 官方目前仅宣布与微信搜索整合，我们在微信群聊、私聊中依然无法直接使用 DeepSeek R1 进行即时问答或协作。

**想在你的微信群、企业微信、钉钉或 Discord 频道里直接拥有一个满血版的 DeepSeek R1 机器人吗？**

使用 **LangBot**，你只需要 5 分钟就能搞定。

## 为什么选择 LangBot？

LangBot 是一个开源的、生产级的即时通信机器人平台。与 GitHub 上零散的 Python 脚本不同，LangBot 提供：

- **统一平台：** 一次配置，同时部署到微信、QQ、Discord、Telegram、钉钉、飞书等 10+ 个平台。
- **模型聚合：** 支持 DeepSeek (R1/V3), Claude, GPT-4, Gemini, 以及本地 Ollama 模型。
- **零代码：** 全图形化 WebUI 配置，无需懂编程。
- **企业级功能：** 内置知识库 (RAG)、插件系统（联网搜索、绘图）和多用户管理。

## 准备工作

1. **一台服务器或电脑：** 安装好 Docker (VPS, 本地电脑, 或群晖 NAS 均可)。
2. **DeepSeek API Key：**
   - **官方平台：** [platform.deepseek.com](https://platform.deepseek.com)
   - **硅基流动 (推荐):** [cloud.siliconflow.cn](https://cloud.siliconflow.cn) (国内访问更快，并发更高)。

## 第一步：部署 LangBot

如果你还没有部署 LangBot，只需一行命令：

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose up -d
```

部署完成后，浏览器访问 `http://localhost:5300` (或服务器 IP:5300)。

## 第二步：配置 DeepSeek 模型

1. 进入 **模型 (Models)** -> **提供商列表 (Provider List)**。
2. 找到 **DeepSeek** (或 **SiliconFlow** / **OpenAI Compatible**)。
3. 填入你的 API Key。
4. 点击 **保存**。

接着创建一个 **模型实例 (Model Instance)**:

- **名称：** `DeepSeek-R1-Bot`
- **模型 ID：** `deepseek-reasoner` (R1 推理版) 或 `deepseek-chat` (V3 通用版)。

## 第三步：创建对话流 (Pipeline)

LangBot 使用 "Pipeline" 来管理机器人的逻辑。

1. 进入 **业务流 (Pipelines)** -> **新建 Pipeline**。
2. 选择 **对话流 (Chat Pipeline)**。
3. 选择刚才创建的 `DeepSeek-R1-Bot` 模型。
4. (可选) 添加系统提示词：
   > "你是由 DeepSeek R1 驱动的智能助手。在回答问题前，请先进行深度思考。"

## 第四步：接入微信 (或任意平台)

### 接入微信 (个人号 / Wechaty)

*注意：个人号接入存在风险，企业用户建议使用企业微信 (WeCom)。*

1. 进入 **机器人 (Bots)** -> **新建机器人**。
2. 选择 **WeChat**。
3. 选择 **GeweChat** 或 **Wechaty** 适配器。
4. 点击 **保存**。
5. 查看日志或界面上的二维码，使用微信扫码登录。

### 接入企业微信 / 钉钉 / 飞书

- 直接在对应平台后台获取 `AppID` 和 `Secret`，填入 LangBot 即可。

## 第五步：测试效果！

打开微信，给机器人发一条消息。你应该能看到 DeepSeek R1 正在“思考”（如果开启了思维链输出），并给出高质量的回答。

## 进阶玩法：联网搜索与工具调用

DeepSeek 很强，但**带联网搜索的 DeepSeek** 更强。

在 LangBot 中：

1. 进入 **插件市场 (Plugins)**。
2. 安装 **Tavily Search** 或 **Google Search**。
3. 将插件添加到你的 DeepSeek Pipeline 中。

现在，你的机器人可以在回答问题前，先去 Google 搜索最新的实时信息，再结合 DeepSeek R1 的推理能力给出答案！

***

**立即开始构建？**
[GitHub 点个 Star](https://github.com/langbot-app/LangBot) 或 [阅读官方文档](https://langbot.app/docs/zh/insight/guide.md)。

---

# 5 分钟部署你的 AI 机器人到 Discord、Telegram 和微信

Source: https://langbot.app/docs/zh/articles/deploy-ai-bot-in-5-minutes

手把手教你部署 LangBot —— 开源平台，一条 Docker 命令即可将 20+ 大模型接入 13+ 即时通讯平台。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/deploy-ai-bot-in-5-minutes).

发布于 2026-02-17 · 作者：LangBot Team

![LangBot 控制面板](https://langbot.app/docs/images/articles/source/images/covers/deploy-ai-bot.png)

如果你能让 GPT-5、Claude、DeepSeek 和 Gemini 同时在你的 Discord 服务器、Telegram 群组和微信中回答问题呢？

不需要折腾 API。不需要开发好几周。只需要一条 Docker 命令。

这就是 **LangBot** —— GitHub 上已经突破 **15,000 Stars** 的开源项目。

## 每个人都会遇到的问题

你想在团队的聊天工具里加个 AI 助手。也许是 Telegram 上的客服机器人，也许是 Discord 里的编程助手，也许是企业微信或飞书群里的知识库问答机器人。

然后现实来了：

- 每个平台都有自己的 Bot API、Webhook 格式和认证流程
- 你需要处理消息队列、会话管理、错误恢复
- 切换大模型供应商意味着重写整个集成层
- 加上 RAG 或工具调用又是一个独立项目

LangBot 用一个统一的平台解决了所有这些问题。

## LangBot 的独特之处

### 13+ 即时通讯平台，一套代码

部署一个 LangBot 实例，即可连接：

**海外平台：** Discord、Telegram、Slack、LINE、WhatsApp
**国内平台：** 微信公众号、企业微信、QQ、飞书、钉钉、KOOK

每个平台都有独立的适配器 —— 你只需要在 WebUI 中填入 Bot Token 即可上线。

![LangBot 机器人管理页面](https://langbot.app/docs/images/articles/source/images/article-mcp/13-bot-page.png)

### 20+ 大模型，零锁定

通过 **LangBot Space**，开箱即用 20 个云端模型 —— 无需管理 API Key：

- **Claude**（Opus 4.6、Sonnet 4.5、Haiku 4.5）
- **GPT**（GPT-5.2、GPT-5-mini、GPT-4.1-mini）
- **Gemini**（3 Pro、2.5 Pro、2.5 Flash）
- **DeepSeek**（R1、V3）
- **Grok**（4、4.1）
- **Qwen**（通义千问 3 Max）

也可以添加自己的模型供应商 —— OpenAI 兼容接口、Ollama 本地模型，随心选择。

![模型选择](https://langbot.app/docs/images/articles/source/images/article-mcp/08-model-select.png)

### 内置 Agent 与工具调用

LangBot 的本地 Agent 不仅仅是聊天封装 —— 它是一个完整的智能体运行时：

- **多轮对话** —— 可配置的上下文记忆
- **函数调用 / 工具使用** —— LLM 驱动的动作执行
- **MCP（模型上下文协议）** —— 连接 100+ 预置工具
- **知识库（RAG）** —— 内置向量检索

![流水线 AI 配置](https://langbot.app/docs/images/articles/source/images/article-mcp/06-pipeline-ai.png)

### 插件市场

37+ 社区插件，持续增长 —— 一键安装：

- **WebSearch** —— 让机器人搜索网页
- **AI Image Generator** —— 文字生成图片
- **LinkAnaly** —— 自动预览聊天中的链接
- **ScheNotify** —— 用自然语言设置定时提醒
- **Google Search**、**Tavily Search**、**RAGFlow Retriever** 等

![LangBot Space 插件市场](https://langbot.app/docs/images/articles/source/images/article-mcp/14-space-market.png)

## 5 分钟部署 —— 真的只要 5 分钟

### 第 1 步：运行 Docker Compose

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose up -d
```

就这样。LangBot 已经运行在 `http://localhost:5300`。

### 第 2 步：用 LangBot Space 初始化

打开 WebUI，点击 **「Initialize with Space」**。这会将你的实例连接到 LangBot Space，获得：

- 20 个开箱即用的云端模型（附赠免费额度）
- 一键安装插件
- 托管式 API Key 管理

![用 Space 初始化](https://langbot.app/docs/images/articles/source/images/article-mcp/01-init-page.png)

### 第 3 步：配置流水线

进入 **流水线** 页面，编辑默认的 `ChatPipeline`：

1. 选择模型（如 `deepseek-v3`、`gpt-5-mini`、`claude-sonnet-4-5`）
2. 自定义系统提示词
3. 可选：关联知识库或启用工具调用

![流水线页面](https://langbot.app/docs/images/articles/source/images/article-mcp/05-pipelines.png)

### 第 4 步：接入平台

进入 **机器人** → 点击 **+** → 选择平台（Discord、Telegram 等） → 填入 Bot Token。

搞定。你的机器人已经上线了。

### 第 5 步：测试

使用内置的 **Debug Chat** 在上线前测试流水线：

![调试聊天](https://langbot.app/docs/images/articles/source/images/article-mcp/07-debug-chat.png)

## 真实对话，真实价值

下面是 LangBot 在 QQ 群中运行的实际效果 —— 用户提出技术问题，即刻获得准确回答：

![群聊演示](https://langbot.app/docs/images/articles/source/images/article-mcp/10-group-chat.png)

私聊场景：

![私聊演示](https://langbot.app/docs/images/articles/source/images/article-mcp/11-private-chat.png)

## 为生产环境打造的架构

LangBot 为生产环境而生：

- **流水线架构** —— 每个机器人绑定一条流水线，流水线处理 AI 逻辑、触发条件、安全控制和输出格式
- **跨进程插件隔离** —— 一个有问题的插件不会崩溃你的机器人
- **多运行器后端** —— 使用 LangBot 内置 Agent，或接入 Dify、n8n、Langflow、Coze 构建复杂工作流
- **灵活的数据库** —— 开发用 SQLite，生产用 PostgreSQL
- **多种向量数据库** —— Chroma、Qdrant、Milvus、pgvector、SeekDB

## 为什么 15,000+ 开发者选择 LangBot

| 功能        | LangBot             | 从零开发   |
| --------- | ------------------- | ------ |
| 平台支持      | 13+ 即开即用            | 每个平台数周 |
| 模型供应商     | 20+ 模型              | 手动对接   |
| Agent 运行时 | 内置                  | 自己搭建   |
| RAG       | 原生 + 外部集成           | 独立项目   |
| 插件系统      | 有市场                 | DIY    |
| 部署        | `docker compose up` | 数天搭建   |
| WebUI     | 自带                  | 自己开发   |

## 立即开始

- **GitHub：** [github.com/langbot-app/LangBot](https://github.com/langbot-app/LangBot) —— 来点个 Star 吧！
- **文档：** [langbot.app/docs](https://langbot.app/docs/zh/insight/guide.md)
- **插件市场：** [space.langbot.app](https://space.langbot.app)

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
docker compose up -d
```

一条命令，开启你的 AI 机器人帝国。

---

# 终于让 Dify Agent 在 Discord、Telegram 和 Slack 上跑起来了

Source: https://langbot.app/docs/zh/articles/dify-agent-discord-telegram-slack

终于让 Dify Agent 在 Discord、Telegram 和 Slack 上跑起来了

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/dify-agent-discord-telegram-slack).

发布于 2025-12-11 · 作者：LangBot Team

![终于让 Dify Agent 在 Discord、Telegram 和 Slack 上跑起来了](https://langbot.app/docs/images/articles/source/images/covers/dify-agent.png)

想让你的 Dify Agent 突破浏览器限制，直接在 QQ、微信、Telegram 里对话？LangBot 配合 Dify，十分钟就能搞定。

## 为什么要这么搭？

[**LangBot**](https://github.com/langbot-app/LangBot) 是目前最强大的开源多平台聊天机器人框架，支持国内主流 IM（QQ、微信、飞书、钉钉）以及国际平台（Telegram、Discord、Slack、LINE）。它的核心能力就是把各种 AI 后端接入到聊天软件里。

**Dify** 是当下最火的 AI 应用开发平台，提供可视化 Agent 编排、50 多个内置工具、RAG 知识库等功能。两者结合，可以快速打造跨平台 AI 助手。

## 部署 LangBot

用 uvx 三行命令搞定：

```bash
mkdir langbot-instance
cd langbot-instance
uvx langbot@latest
```

访问 `http://127.0.0.1:5300`，注册管理员账号：

![LangBot Dashboard](https://langbot.app/docs/images/articles/external/c6d52212ba91-02-langbot-dashboard.png)

## 创建 Dify Agent

登录 [cloud.dify.ai](https://cloud.dify.ai) 创建新应用。选择 **Agent** 类型——与普通聊天应用不同，Agent 可以自主推理并调用工具完成复杂任务。

![Select Agent Type](https://langbot.app/docs/images/articles/external/3e5b1d8ec6ec-07-dify-create-app-types.png)

### 配置 Agent

在编排界面配置：

**System Instructions** - 定义 Agent 角色：

```
You are an intelligent assistant that helps users complete various tasks. You have the following capabilities:
1. Answer various user questions
2. Query weather information
3. Retrieve webpage content

Please always maintain a friendly and professional attitude. If you need to use tools to get information, proactively call the relevant tools.
```

**添加工具** - 从 Dify 的 50+ 内置工具中选择，比如天气查询和网页抓取：

![Add Tools](https://langbot.app/docs/images/articles/external/9066d99b172c-11-dify-tools-panel.png)

**选择模型** - 支持 GPT、Claude、Gemini、DeepSeek 等主流 LLM。

配置完成效果：

![Configuration Complete](https://langbot.app/docs/images/articles/external/be278ca435e8-12-dify-agent-configured.png)

### 获取 API Key

点击"发布"，然后进入"访问 API"创建密钥：

![Create API Key](https://langbot.app/docs/images/articles/external/471b316018e5-13-dify-api-key-created.png)

保存好 API key 和服务器地址 `https://api.dify.ai/v1`。

## 连接 Dify 到 LangBot

回到 LangBot，进入 Pipelines > ChatPipeline > AI 能力：

![AI Capability Config](https://langbot.app/docs/images/articles/external/8f4b3820ed5b-14-langbot-pipeline-ai-capability.png)

选择 **Dify Service API** 作为运行器：

![选择 Dify 运行器](https://langbot.app/docs/images/articles/external/efa6fcae9c58-15-langbot-runner-dropdown.png)

填写配置：

- **Base URL**: `https://api.dify.ai/v1`
- **API Key**: 刚才创建的密钥
- **App Type**: Chat（包括 Chatflow）

![Enter Configuration](https://langbot.app/docs/images/articles/external/74f71a8bf1dc-17-langbot-dify-api-key-entered.png)

保存后点击"调试对话"测试：

![Test Conversation](https://langbot.app/docs/images/articles/external/9999c12907eb-20-langbot-chat-test.png)

如果 Agent 能正确回复并调用工具，说明集成成功。

## 这种架构的优势

- **解耦设计**：Agent 能力在 Dify 中维护，LangBot 负责消息路由，各司其职
- **一份配置，多端生效**：同一个 Agent 可以同时服务 QQ、微信、Telegram 等多个平台
- **易于扩展**：后续可以在 Dify 中添加 RAG 知识库、工作流编排、更多工具等

## 下一步

- 在 LangBot 中配置消息平台（QQ 机器人、微信个人号等）
- 在 Dify 中添加更多工具（数据库查询、API 调用等）
- 尝试 Dify Chatflow 实现更复杂的对话流程

如果你在用 n8n、FastGPT、Coze 或 Langflow，LangBot 也都支持。

***

**相关资源**

- [LangBot 文档](https://langbot.app/docs/zh/insight/guide.md) | [GitHub](https://github.com/langbot-app/LangBot)
- [Dify 文档](https://docs.dify.ai) | [云端平台](https://cloud.dify.ai)

---

# LangBot 4.6.0 外部知识库教程：集成 Dify 实现 RAG 对话

Source: https://langbot.app/docs/zh/articles/dify-langbot-rag-knowledge-base

LangBot 4.6.0 外部知识库教程：集成 Dify 实现 RAG 对话

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/dify-langbot-rag-knowledge-base).

发布于 2025-12-02 · 作者：LangBot Team

![LangBot 4.6.0 外部知识库教程：集成 Dify 实现 RAG 对话](https://langbot.app/docs/images/articles/source/images/covers/dify-rag.png)

LangBot 4.6.0 引入了外部知识库功能，允许用户将 Dify、RAGFlow 等外部知识检索服务集成到对话流水线中。本教程演示如何将 Dify 知识库与 LangBot 结合，实现基于领域知识的智能对话。

## 功能概述

外部知识库功能使 LangBot 能够：

- 连接各种外部知识检索服务（Dify、RAGFlow 等）
- 基于领域专业知识提供专业回答
- 通过插件系统灵活扩展知识检索能力
- 通过 WebUI 便捷配置，无需手动编辑配置文件

## 准备工作

开始之前，你需要：

1. 部署 LangBot 4.6.0 或更高版本
2. 拥有 Dify 账号（在 <https://cloud.dify.ai> 注册）
3. 配置一个对话模型（本教程使用 claude-opus-4-1-20250805）

## 第一步：部署 LangBot

### 1.1 查看 LangBot 仓库

首先访问 [LangBot GitHub 仓库](https://github.com/langbot-app/LangBot) 了解项目。LangBot 是一个生产级的即时通讯机器人开发平台，支持多种消息平台和 LLM 服务。

### 1.2 了解外部知识库功能

访问 [LangBot 官方文档](https://langbot.app/docs/zh/insight/guide.md) 查看外部知识库使用说明。文档详细介绍了如何构建内置知识库和连接外部知识库。

### 1.3 启动 LangBot

使用 `uvx langbot` 命令快速启动 LangBot，然后访问 <http://127.0.0.1:5300> 进行初始化。填写邮箱和密码完成注册，然后登录。

### 1.4 登录后的控制台

成功登录后，你将看到 LangBot WebUI 控制台。

## 第二步：配置对话模型

使用知识库之前，需要先配置一个对话模型。

### 2.1 进入模型配置页面

点击左侧导航栏的 "Models" 进入模型配置页面。

### 2.2 添加新模型

点击 "+" 按钮打开模型配置对话框。

### 2.3 填写模型信息

填写以下信息：

- **Model Name**：claude-opus-4-1-20250805
- **Model Provider**：New API
- **Request URL**：你的 API 端点
- **API Key**：你的 API Key
- **Abilities**：勾选 Vision Ability 和 Function Call

点击 "Submit" 保存配置。

## 第三步：在 Dify 中创建知识库

### 3.1 登录 Dify 平台

访问 <https://cloud.dify.ai> 并登录你的账号。

### 3.2 进入知识库页面

点击顶部导航栏的 "Knowledge" 进入知识库管理页面。

### 3.3 创建新知识库

点击 "Create Knowledge" 开始创建知识库。

### 3.4 选择数据源

你可以选择以下方式导入数据：

- **Import from file**：上传文档文件
- **Sync from Notion**：从 Notion 同步
- **Sync from website**：爬取网站内容

本教程选择 "Import from file" 并上传准备好的 LangBot 文档。

### 3.5 上传文档

上传文档后，系统会显示文件信息。点击 "Next" 继续。

### 3.6 配置文档处理参数

在文档处理页面，你可以配置分块设置、索引方式和检索设置：

- **Chunk Settings**：General 模式，最大块长度 1024 字符
- **Index Method**：High Quality（使用 embedding 模型）
- **Retrieval Setting**：Vector Search

点击 "Save & Process" 开始处理文档。

### 3.7 知识库处理中

系统开始处理文档并生成向量嵌入。

### 3.8 嵌入完成

处理完成后，知识库即可使用。

## 第四步：获取 Dify API 信息

### 4.1 打开 Service API 面板

点击右下角的 "Service API" 按钮。记录以下信息：

- **Service API Endpoint**：<https://api.dify.ai/v1>
- **Dataset ID**：从 URL 中获取

### 4.2 获取 API Key

点击 "API Key" 按钮查看 API key。记录你的 API Key，用于后续配置。

## 第五步：在 LangBot 中配置外部知识库

### 5.1 进入知识库页面

在 LangBot WebUI 中，点击左侧导航栏的 "Knowledge"。

### 5.2 切换到外部知识库标签页

点击 "External" 标签页。

### 5.3 添加外部知识库

点击 "+" 按钮打开添加外部知识库对话框。在此对话框中，你需要：

1. **Knowledge Base Name**：给知识库起个名字
2. **Knowledge Base Description**：添加描述（可选）
3. **Retriever**：选择知识检索插件

**注意**：使用外部知识库需要先安装对应的知识检索插件。你可以在[插件市场](https://space.langbot.app/market?category=KnowledgeRetriever)中搜索并安装 Dify 知识检索插件。

安装插件后，从 Retriever 下拉菜单中选择对应插件，然后填写从 Dify 获取的配置信息（API Endpoint、API Key、Dataset ID）。

## 第六步：配置 Pipeline

配置好外部知识库后，需要在流水线中启用：

1. 进入 "Pipelines" 页面
2. 编辑或创建新流水线
3. 在 "AI Capabilities" 页面，选择 "Built-in Agent" 作为 runner
4. 在知识库选择中，勾选刚才配置的外部知识库
5. 保存流水线配置

## 第七步：测试效果

在流水线的 "Conversation Testing" 页面测试，或将流水线绑定到机器人进行实际对话测试。当用户提问时，LangBot 会自动从 Dify 知识库检索相关内容，并结合检索到的知识生成回答。

## 常见问题

### 1. 如何安装知识检索插件？

访问 [LangBot 插件市场](https://space.langbot.app/market)，搜索 "Knowledge Retriever" 或 "Dify"，找到对应插件并点击安装。

### 2. 支持哪些外部知识检索服务？

LangBot 目前通过插件系统支持多种外部知识检索服务，包括：

- Dify
- RAGFlow
- 其他自定义知识检索服务

具体支持的服务可在插件市场查看。

### 3. 外部知识库和内置知识库有什么区别？

- **内置知识库**：数据存储在 LangBot 本地，由 LangBot 处理向量化和检索
- **外部知识库**：数据存储在外部服务（如 Dify），通过 API 调用进行检索

外部知识库的优势是可以利用专业 LLMOps 平台的能力，如 Dify 的高级文档处理和多种检索策略。

### 4. 可以同时使用多个知识库吗？

可以。在流水线配置中，你可以同时勾选多个知识库（内置或外部），LangBot 会综合利用这些知识库的内容生成回答。

## 总结

通过本教程，你学会了如何：

1. 在 Dify 平台上创建知识库并上传文档
2. 获取 Dify API key 和相关配置信息
3. 在 LangBot 中配置对话模型
4. 在 LangBot 中添加外部知识库
5. 配置流水线使用外部知识库

外部知识库功能为 LangBot 提供了更强大、更灵活的知识管理能力。结合 Dify 等专业 LLMOps 平台，可以构建更智能、更专业的对话机器人。

## 相关资源

- [LangBot 官网](https://langbot.app)
- [LangBot 文档](https://langbot.app/docs/zh/insight/guide.md)
- [LangBot GitHub](https://github.com/langbot-app/LangBot)
- [Dify 官网](https://dify.ai)
- [LangBot 插件市场](https://space.langbot.app/market)

---

# LangBot Cloud 新版上线：多用户 Workspace 也来到开源版

Source: https://langbot.app/docs/zh/articles/langbot-cloud-multi-user-workspaces

LangBot 是连接大模型与聊天平台的开源 AI 机器人平台。新版 Cloud 与开源版现已支持 Workspace 多用户、成员邀请和角色权限。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/langbot-cloud-multi-user-workspaces).

发布于 2026-08-25 · 作者：LangBot Team

![LangBot 多用户 Workspace 控制台](https://langbot.app/docs/images/articles/source/images/cloud-multi-user/oss-dashboard.png)

新版 [LangBot Cloud](https://cloud.langbot.app) 已经上线。这次先解决一个很具体的问题：多人一起用 LangBot 时，账户、资源和权限怎么分。

同一套多用户能力也进入了开源版。Cloud 和自部署版的运维方式不同，但成员、邀请和权限的基本逻辑现在是一致的。

## LangBot 是什么？

LangBot 是一个开源的多平台 AI 机器人开发与部署平台。你可以在同一套控制台里配置机器人、消息流水线、知识库、模型和扩展，再将 AI 能力接入 QQ、微信、企业微信、飞书、钉钉、KOOK、Discord、Telegram、Slack 和 LINE。它也支持 Satori 与 Matrix；通过 Matrix 桥接，还可以覆盖 WhatsApp、Signal、Messenger、Mattermost、Google Chat、IRC、XMPP、Zulip 等网络。

模型侧不绑定一家厂商。LangBot 可以连接 OpenAI、Anthropic Claude、DeepSeek、Google Gemini、xAI Grok、Moonshot Kimi、智谱 GLM，也支持通过 Ollama 和 LM Studio 运行本地模型。阿里云百炼、火山方舟、SiliconFlow、ModelScope、GiteeAI 等聚合平台同样可以接入；需要组合现有工作流时，还能连接 Dify 和 MCP。

这意味着，同一个团队可以用 LangBot 管理不同聊天平台上的 AI 助手，同时按场景选择云端大模型、本地模型或已有 Agent 工作流。

![新版 LangBot Cloud 登录页](https://langbot.app/docs/images/articles/source/images/cloud-multi-user/cloud-login.png)

## Cloud：登录后进入自己的 Workspace

Cloud 统一使用 LangBot Account 登录。首次使用会进入个人 Workspace，也可以接受邀请加入团队 Workspace；加入多个 Workspace 后，可以在界面中切换当前工作区。

机器人、流水线、模型、知识库和扩展都归属于当前 Workspace。切换 Workspace，不会把不同团队的配置和数据混在一起。

Cloud 仍然负责托管、更新和运行环境。适合不想自己维护服务器，或者希望团队直接开始配置机器人的用户。

## 邀请成员，不再共用一个管理员账号

Owner 或有成员管理权限的角色可以发出一次性邀请。被邀请人使用自己的账户接受邀请，随后以分配到的角色进入 Workspace。

![LangBot Cloud 成员邀请页（Workspace 名称已脱敏）](https://langbot.app/docs/images/articles/source/images/cloud-multi-user/cloud-invitation.png)

这比共享管理员密码更适合长期使用：每个人有独立身份，权限也能按工作需要分开。

当前提供五个固定角色：

- **Owner**：Workspace 所有者，负责最高权限和成员管理。
- **Admin**：管理成员和大部分 Workspace 设置。
- **Developer**：配置机器人、流水线、模型和扩展。
- **Operator**：负责日常运行与操作。
- **Viewer**：只读查看。

## 开源版：一个实例，一个 Workspace，支持多人

自部署版不会变成多 Workspace SaaS。一个 LangBot 实例仍然对应一个 Workspace，但这个 Workspace 可以有多个用户。

初始化时创建的账户是 Owner。之后可以邀请其他人加入；配置了 SMTP 时可直接发送邀请邮件，没有配置邮件服务时也可以复制一次性邀请链接，通过可信渠道发给成员。

成员进入后，看到的仍是熟悉的 LangBot 控制台。区别在于资源访问会结合 Workspace 和角色校验，而不是默认所有登录用户都拥有完整管理员权限。

## 该选哪一个？

|           | LangBot Cloud | 开源自部署版      |
| --------- | ------------- | ----------- |
| 部署维护      | 由 LangBot 托管  | 自己维护服务器和数据  |
| Workspace | 可拥有或加入多个      | 每个实例固定一个    |
| 多用户与邀请    | 支持            | 支持          |
| 固定角色权限    | 支持            | 支持          |
| 适合        | 快速启用、团队直接协作   | 私有部署、掌握运行环境 |

想直接使用，可以访问 [cloud.langbot.app](https://cloud.langbot.app)。想把数据和运行环境留在自己的服务器上，可以从 [GitHub](https://github.com/langbot-app/LangBot) 部署开源版。

---

# 深入 LangBot 插件系统：进程隔离、事件驱动与组件化架构

Source: https://langbot.app/docs/zh/articles/langbot-plugin-system-deep-dive

从源码层面深入剖析 LangBot 4.0 插件系统的架构设计——进程隔离通信、事件驱动钩子、组件化扩展模型，以及与 Dify/MCP 等系统的对比思考。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/langbot-plugin-system-deep-dive).

发布于 2026-02-23 · 作者：LangBot Team

![LangBot Plugin System](https://langbot.app/docs/images/articles/source/images/covers/plugin-system.png)

大多数聊天机器人框架的"插件系统"不过是一个 Python 模块的动态导入。LangBot 4.0 选择了一条更难但更正确的路——**每个插件运行在独立进程中**，通过结构化的 JSON-RPC 风格协议与宿主通信。

这篇文章将从源码出发，完整拆解这套系统的设计。

## 整体架构：三层进程模型

LangBot 的插件系统由三层进程协作：

![LangBot 插件系统三层架构](https://langbot.app/docs/images/articles/source/images/plugin-system/architecture.png)

**三个层次各司其职：**

1. **LangBot 主进程**：运行业务逻辑（消息处理流水线、平台适配、模型调用），通过 `PluginRuntimeConnector` 连接 Runtime。
2. **Plugin Runtime**：插件的"编排层"，负责发现、启动、管理所有插件子进程，接收主进程的指令并分发到对应插件。
3. **插件子进程**：每个插件独立运行在自己的 Python 进程中，通过 stdio 管道与 Runtime 通信。

### 为什么要三层而不是两层？

直觉的设计是主进程直接管理插件进程。LangBot 选择中间加一层 Runtime 的原因是**部署灵活性**：

- **本地开发**：主进程通过 stdio 直接启动 Runtime 子进程（零配置）
- **Docker 生产环境**：Runtime 作为独立容器运行，主进程通过 WebSocket 连接
- **Windows 兼容**：由于 Windows 的 asyncio 不完整支持 stdio 子进程，Windows 上自动降级为 WebSocket 通信

这意味着同一套代码，不改配置，就能适配从开发到生产的全部场景。

## 通信协议：JSON-RPC 风格的请求/响应

所有跨进程通信基于一个统一的协议层。核心数据结构非常简洁：

```python
# 请求
class ActionRequest(pydantic.BaseModel):
    seq_id: int    # 序列号，用于匹配请求和响应
    action: str    # 动作名称
    data: dict     # 载荷

# 响应
class ActionResponse(pydantic.BaseModel):
    seq_id: int
    code: int           # 0 = 成功
    message: str
    data: dict
    chunk_status: str   # "continue" | "end"（支持流式响应）
```

通信层 `Handler` 是整个系统的核心抽象。它同时扮演 RPC 客户端和服务端：

```python
class Handler:
    async def call_action(self, action, data, timeout=15.0) -> dict:
        """主动调用对端提供的 action，等待响应"""
        self.seq_id_index += 1
        request = ActionRequest.make_request(self.seq_id_index, action.value, data)
        future = asyncio.Future()
        self.resp_waiters[self.seq_id_index] = future
        await self.conn.send(json.dumps(request.model_dump()))
        response = await asyncio.wait_for(future, timeout)
        return response.data

    @action(SomeAction.DO_SOMETHING)
    async def handle_something(data: dict) -> ActionResponse:
        """注册一个 action 供对端调用"""
        return ActionResponse.success({"result": "ok"})
```

**关键设计点：**

- 基于 `seq_id` 的请求/响应匹配，支持全双工并发调用
- 支持流式响应（`chunk_status`），用于命令执行等长时间操作
- 大消息自动分块传输（stdio 16KB / WebSocket 64KB 分块）
- 文件传输通过 base64 分块机制实现，不走消息通道

### Action 枚举：清晰的 API 契约

系统通过四组枚举严格定义了所有跨进程调用：

```python
# 插件 → Runtime（插件进程主动请求）
class PluginToRuntimeAction:
    REGISTER_PLUGIN = "register_plugin"
    SEND_MESSAGE = "send_message"        # 发送消息到平台
    INVOKE_LLM = "invoke_llm"           # 调用大模型
    SET_PLUGIN_STORAGE = "set_plugin_storage"  # 持久化存储
    # ...

# Runtime → 插件（Runtime 下发指令）
class RuntimeToPluginAction:
    INITIALIZE_PLUGIN = "initialize_plugin"
    EMIT_EVENT = "emit_event"            # 触发事件
    CALL_TOOL = "call_tool"             # 调用工具
    EXECUTE_COMMAND = "execute_command"   # 执行命令
    SHUTDOWN = "shutdown"
    # ...

# LangBot 主进程 → Runtime
class LangBotToRuntimeAction:
    INSTALL_PLUGIN = "install_plugin"
    EMIT_EVENT = "emit_event"
    LIST_TOOLS = "list_tools"
    # ...

# Runtime → LangBot 主进程
class RuntimeToLangBotAction:
    GET_PLUGIN_SETTINGS = "get_plugin_settings"
    SET_BINARY_STORAGE = "set_binary_storage"
    # ...
```

这种设计让 API 边界一目了然：插件能做什么、不能做什么，全部由枚举定义。

## 插件生命周期

一个插件从安装到运行，经历以下阶段：

### 1. 发现（Discovery）

Runtime 启动时扫描 `data/plugins/` 目录：

```python
async def launch_all_plugins(self):
    for plugin_path in glob.glob("data/plugins/*"):
        if not os.path.isdir(plugin_path):
            continue
        task = self.launch_plugin(plugin_path)
        self.plugin_run_tasks.append(task)
```

目录名约定为 `{author}__{name}`，每个目录包含 `manifest.yaml` 和插件代码。

### 2. 启动（Launch）

Runtime 为每个插件启动独立子进程：

```python
async def launch_plugin(self, plugin_path: str):
    python_path = sys.executable
    args = ["-m", "langbot_plugin.cli.__init__", "run", "-s", "--prod"]

    ctrl = StdioClientController(
        command=python_path,
        args=args,
        working_dir=plugin_path,  # 每个插件在自己的目录下运行
    )
    await ctrl.run(new_plugin_connection_callback)
```

**关键细节**：插件进程的工作目录设置为插件自身目录，这实现了天然的文件系统隔离。

### 3. 注册（Register）

插件进程启动后，主动向 Runtime 注册自己：

```python
# 插件侧
action = PluginToRuntimeAction.REGISTER_PLUGIN
# 携带：manifest、组件列表、配置 schema 等

# Runtime 侧处理注册
async def register_plugin(self, handler, container_data, debug_plugin=False):
    plugin_container = PluginContainer.from_dict(container_data)
    # 从主进程获取插件配置
    plugin_settings = await self.context.control_handler.call_action(
        RuntimeToLangBotAction.GET_PLUGIN_SETTINGS, {...}
    )
    # 初始化插件（下发配置）
    await handler.initialize_plugin(plugin_settings)
    # 存储插件容器
    self.plugins.append(plugin_container)
```

### 4. 运行（Running）

插件进入 `INITIALIZED` 状态后，即可接收事件、工具调用、命令执行等请求。

### 5. 卸载（Shutdown）

```python
async def shutdown_plugin(self, plugin_container):
    # 1. 通知插件进程关闭
    await plugin_container._runtime_plugin_handler.shutdown_plugin()
    # 2. 关闭通信连接
    await plugin_container._runtime_plugin_handler.conn.close()
    # 3. 终止子进程
    if handler.stdio_process is not None:
        handler.stdio_process.kill()
        await asyncio.wait_for(handler.stdio_process.wait(), timeout=2)
```

## 组件系统：四种扩展类型

LangBot 的插件不是一个单一的 hook 函数，而是一个**组件容器**。一个插件可以同时提供多种类型的组件：

### EventListener（事件监听器）

最基础的扩展方式——监听流水线中的事件：

```python
from langbot_plugin.api.definition.components.common.event_listener import EventListener
from langbot_plugin.api.entities.events import PersonNormalMessageReceived
from langbot_plugin.api.entities.context import EventContext

class MyListener(EventListener):
    @EventListener.handler(PersonNormalMessageReceived)
    async def on_person_message(self, ctx: EventContext):
        event = ctx.event
        # 修改用户消息（在发送给 LLM 之前）
        event.user_message_alter = "请用诗歌形式回答：" + event.text_message

        # 或者阻止后续处理
        # ctx.prevent_default()
        # ctx.prevent_postorder()
```

支持的事件类型覆盖消息处理的完整生命周期：

| 事件                            | 触发时机         |
| ----------------------------- | ------------ |
| `PersonMessageReceived`       | 收到私聊消息       |
| `GroupMessageReceived`        | 收到群聊消息       |
| `PersonNormalMessageReceived` | 判定为需处理的私聊消息  |
| `GroupNormalMessageReceived`  | 判定为需处理的群聊消息  |
| `NormalMessageResponded`      | LLM 回复完成     |
| `PromptPreProcessing`         | Prompt 预处理阶段 |

事件传播支持两种中断：

- `prevent_default()`：阻止默认行为（如跳过 LLM 调用）
- `prevent_postorder()`：阻止后续插件执行

### Tool（工具）

供 LLM 的 Function Calling 调用的工具：

```python
from langbot_plugin.api.definition.components.tool.tool import Tool

class WeatherTool(Tool):
    async def call(self, params: dict, session, query_id: int) -> str:
        city = params.get("city", "Beijing")
        # 调用天气 API ...
        return f"{city} 今天晴，25°C"
```

工具的元数据（名称、描述、参数 schema）定义在配套的 YAML manifest 文件中，LangBot 会自动将其转换为 LLM 能理解的 Function 定义。

### Command（命令）

用户通过 `!command` 触发的命令，支持子命令注册：

```python
from langbot_plugin.api.definition.components.command.command import Command

class MyCommand(Command):
    def __init__(self):
        super().__init__()

        @self.subcommand("hello", help="Say hello")
        async def hello(self, ctx):
            yield CommandReturn(text="Hello from plugin!")

        @self.subcommand("status", help="Show status")
        async def status(self, ctx):
            yield CommandReturn(text="All systems operational.")
```

命令的执行结果通过 `AsyncGenerator` 返回，天然支持流式输出。

### KnowledgeRetriever（知识检索器）

多实例组件，用于接入外部知识库：

```python
from langbot_plugin.api.definition.components.knowledge_retriever.retriever import KnowledgeRetriever

class MyRetriever(KnowledgeRetriever):
    async def retrieve(self, context) -> list:
        # 从外部向量数据库检索
        results = await self.search_external_db(context.query)
        return [RetrievalResultEntry(content=r) for r in results]
```

KnowledgeRetriever 是**多态组件（PolymorphicComponent）**——同一个检索器类可以创建多个实例，每个实例有独立的配置。这允许用户连接多个不同的外部知识库。

## SDK API：插件能做什么

插件通过 `BasePlugin` 基类继承的 `LangBotAPIProxy` 获得丰富的能力：

```python
class LangBotAPIProxy:
    # 消息操作
    async def send_message(self, bot_uuid, target_type, target_id, message_chain)

    # 模型调用
    async def get_llm_models(self) -> list[str]
    async def invoke_llm(self, model_uuid, messages, funcs=[], extra_args={})

    # 持久化存储（插件级别隔离）
    async def set_plugin_storage(self, key, value: bytes)
    async def get_plugin_storage(self, key) -> bytes

    # 工作区存储（跨插件共享）
    async def set_workspace_storage(self, key, value: bytes)
    async def get_workspace_storage(self, key) -> bytes

    # 系统信息
    async def get_langbot_version(self) -> str
    async def get_bots(self) -> list[str]
    async def list_plugins_manifest(self) -> list
```

**存储 API 的设计值得注意**：提供了两个级别的 KV 存储——`plugin_storage`（插件私有）和 `workspace_storage`（全局共享），数据以 bytes 形式存储（base64 序列化传输），简单但足够灵活。

## 事件分发机制

事件从主进程到插件的完整路径：

![事件分发流程](https://langbot.app/docs/images/articles/source/images/plugin-system/event-dispatch.png)

关键源码：

```python
async def emit_event(self, event_context, include_plugins=None):
    for plugin in self.plugins:
        if plugin.status != RuntimeContainerStatus.INITIALIZED:
            continue
        if not plugin.enabled:
            continue

        # 流水线级别的插件过滤
        if include_plugins is not None:
            plugin_id = f"{plugin.manifest.metadata.author}/{plugin.manifest.metadata.name}"
            if plugin_id not in include_plugins:
                continue

        resp = await plugin._runtime_plugin_handler.emit_event(
            event_context.model_dump()
        )

        event_context = EventContext.model_validate(resp["event_context"])

        # 插件请求中断后续传播
        if event_context.is_prevented_postorder():
            break

    return emitted_plugins, event_context
```

`include_plugins` 参数实现了**流水线级别的插件绑定**——不同的消息处理流水线可以使用不同的插件子集。

## 安装与分发

插件支持三种安装来源：

1. **本地上传**：`.lbpkg` 文件（实际上是 zip 包，包含 manifest.yaml 和代码）
2. **插件市场**：从 LangBot Space 在线安装
3. **GitHub Release**：从 GitHub 仓库的 Release 资产下载

安装流程：

```python
async def install_plugin(self, source, install_info):
    yield {"current_action": "downloading plugin package"}
    # 1. 获取插件包（解压 zip）
    plugin_path, author, name, version = await self.install_plugin_from_file(plugin_file)

    yield {"current_action": "installing dependencies"}
    # 2. 安装依赖（pip install -r requirements.txt）
    pkgmgr_helper.install_requirements(requirements_file)

    yield {"current_action": "initializing plugin settings"}
    # 3. 初始化配置
    await self.context.control_handler.call_action(
        RuntimeToLangBotAction.INITIALIZE_PLUGIN_SETTINGS, {...}
    )

    yield {"current_action": "launching plugin"}
    # 4. 启动插件进程
    task = self.launch_plugin(plugin_path)
```

整个过程通过 `AsyncGenerator` 流式报告进度，前端可以实时显示安装状态。

## 调试体验

SDK 提供了完善的开发者工具链：

```bash
# 初始化新插件
lbp init

# 添加组件
lbp component add

# 本地调试运行
lbp run

# 打包发布
lbp publish
```

**调试模式**的设计特别巧妙：开发者的插件通过 WebSocket 连接到已运行的 Runtime（而非 stdio），这意味着可以在不重启 LangBot 的情况下热重载插件代码。调试插件在 UI 中有特殊标记，不会被误操作删除。

## 与其他系统的对比

### vs Dify 插件

Dify 的插件系统（`dify-plugin-daemon`）与 LangBot 有相似的进程隔离理念，但侧重点不同：

- **Dify**：插件扩展的是工作流节点类型（Tool、Model、Extension），面向 AI 应用编排
- **LangBot**：插件扩展的是消息处理流水线（Event、Tool、Command、KnowledgeRetriever），面向即时通讯场景

LangBot 的 `EventListener` 组件提供了 Dify 没有的能力——在消息处理的任意阶段插入逻辑。

### vs MCP（Model Context Protocol）

MCP 是一个标准化的 AI 工具调用协议。LangBot 的 Tool 组件和 MCP 服务功能上有重叠，但定位不同：

- **MCP**：通用的"AI 调用外部能力"协议，任何 LLM 应用都能用
- **LangBot Tool**：深度集成在消息处理上下文中，能访问会话信息、用户身份等

实际上，LangBot 已经原生支持 MCP——用户可以在 LangBot 中直接配置 MCP 服务器，无需编写插件。而 LangBot 的 Tool 组件适用于需要访问 LangBot 内部上下文的场景。

## 设计决策背后的思考

**为什么选择进程隔离而非线程/协程？**

- 插件代码质量不可控，一个 segfault 不应该崩掉整个服务
- 依赖隔离：不同插件可能依赖同一个库的不同版本
- 资源可控：可以对单个插件进程设置资源限制

**为什么用 JSON 而非 Protobuf/MessagePack？**

- 调试友好：开发者可以直接阅读通信日志
- Python 生态原生支持，无需额外依赖
- 性能瓶颈不在序列化（插件调用频率远低于数据库查询）

**为什么 stdio 优先于 WebSocket？**

- stdio 无需网络栈，延迟更低
- 进程生命周期管理更简单（父进程退出时子进程自动清理）
- WebSocket 只在不支持 stdio 的场景（Docker、Windows）使用

## 总结

LangBot 的插件系统是一个**为生产环境设计的、进程隔离的、事件驱动的组件化扩展框架**。

它的核心设计原则：

1. **安全第一**：进程隔离确保插件不会影响主服务稳定性
2. **部署灵活**：stdio/WebSocket 双模式适配所有环境
3. **开发者友好**：完善的 SDK、CLI 和调试支持
4. **组件化**：四种组件类型覆盖主要扩展需求

如果你有兴趣开发 LangBot 插件，可以从 [插件开发文档](https://langbot.app/docs/zh/plugin/dev/tutor.md) 开始，或者直接浏览 [插件市场](https://space.langbot.app/market) 中的现有插件获取灵感。

---

# LangBot v4.10.0：Agent 沙箱与技能——让 Agent 真正像开发者一样工作

Source: https://langbot.app/docs/zh/articles/langbot-v4100-sandbox-skills

LangBot v4.10.0 为内置 Agent 引入真正的沙箱（Box Runtime）和按需加载的技能（Skills）系统。Agent 现在能在隔离环境中执行命令、读写文件，并在任务需要时即时调用专业知识。本文深度解读这次更新的设计与用法。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/langbot-v4100-sandbox-skills).

发布于 2026-06-04 · 作者：LangBot Team

![LangBot v4.10.0 Agentic Sandbox & Skills](https://langbot.app/docs/images/articles/source/images/covers/sandbox-skills.png)

LangBot v4.10.0 是迄今为止幅度最大的一次 Agent 更新。它做了两件事，都指向同一个方向——**让内置 Agent 真正像一个开发者那样工作**：

1. **沙箱（Sandbox）**：Agent 现在运行在真正隔离的环境里，能执行命令、读写文件。
2. **技能（Skills）**：Agent 可以在任务需要时按需加载专业知识，而不必把所有东西都塞进上下文。

这两项能力均由社区贡献者 [@huanghuoguoguo](https://github.com/huanghuoguoguo) 主导开发。下面分别展开。

> **第一次了解 LangBot？** [LangBot](https://github.com/langbot-app/LangBot) 是一个开源的大模型机器人平台（GitHub 15k+ stars），让你用一个实例就能把 AI 聊天机器人部署到 **QQ、微信（个人微信 / 企业微信）、飞书、钉钉、Discord、Telegram、Slack** 等十几个平台。它把 20+ 大语言模型（OpenAI GPT、Anthropic Claude、Google Gemini、DeepSeek 等）接入 13+ 即时通讯平台，内置 Agent、RAG 知识库、MCP 支持和插件生态。你可以用一条 Docker 命令自部署，也可以在 [LangBot 云](https://space.langbot.app/cloud)上使用托管版本。

## 📦 沙箱：给 Agent 一个真正的工作空间

在此之前，LangBot 的内置 Agent 只能调用预先定义好的工具。它无法"打开终端跑一条命令"，也无法"把中间结果写到文件里再读回来"——而这恰恰是人类开发者每天都在做的事。

v4.10.0 引入了全新的 **Box Runtime**。它给 Agent 提供一个隔离的沙箱环境，内置六件套原生工具：

| 工具      | 作用          |
| ------- | ----------- |
| `exec`  | 执行 shell 命令 |
| `read`  | 读取文件内容      |
| `write` | 写入文件        |
| `edit`  | 对文件做局部修改    |
| `glob`  | 按通配符查找文件    |
| `grep`  | 在文件内容中检索    |

有了这套工具，Agent 就能像开发者一样：跑一段脚本、把输出存到文件、再读回来分析、对结果做二次处理。整个过程都发生在隔离环境内，不会污染宿主。

![LangBot 沙箱运行界面](https://langbot.app/docs/images/articles/source/images/sandbox-skills/sandbox.png)

### 可插拔的后端

沙箱的执行后端是**可插拔**的，LangBot 会根据部署环境自动选择：

- **Docker**：启动一个独立的 `langbot_box` 容器，通过 WebSocket 与主进程通信。适合容器化部署。
- **nsjail**：基于 Linux namespace 的轻量级隔离，无需额外容器。适合裸机或单容器部署。
- **E2B**：云端沙箱，把执行放到远端隔离环境。

你不需要手动指定——`box.enabled` 是总开关，开启后 LangBot 会自动探测并选用最合适的后端，探测失败时优雅降级。

![沙箱原生工具](https://langbot.app/docs/images/articles/source/images/sandbox-skills/sandbox-tools.png)

### 它还托管 MCP Server

除了原生工具，Box Runtime 还承担一个重要职责：**托管 stdio 模式的 MCP Server**。

过去 stdio 模式的 MCP Server 需要在主进程里直接拉起子进程，既不安全也不好管理。现在它们统一跑在沙箱内，与 Agent 的执行环境共享同一套隔离边界。`http` / `sse` 模式的 MCP 不受影响，照常工作。

## 🎯 技能：按需加载的专业能力

第二个大更新是**技能（Skills）**。

随着 Agent 能做的事越来越多，一个老问题浮现出来：**上下文窗口是有限的**。如果把所有可能用到的指令、流程、参考资料都塞进系统提示词，上下文很快就会被撑爆，而且大部分内容在当前任务里根本用不上。

技能的设计思路很直接——**平时只看目录，用时才翻书**。

一个技能（Skill）是一个**按需激活的指令包**，包含：

- **提示词**：告诉 Agent 这个技能是做什么的、什么时候用
- **流程**：完成某类任务的步骤
- **脚本**：可直接执行的辅助脚本
- **参考文件**：API 文档、模板、示例等

Agent 平时只能看到**可用技能的列表**（名称 + 简介），这只占用极少的上下文。当它判断某个任务需要某个技能时，再通过 `activate` 动作即时拉取该技能的完整内容。

![LangBot 技能系统](https://langbot.app/docs/images/articles/source/images/sandbox-skills/skills.png)

这样做的好处显而易见：

1. **上下文精简**：不相关的技能内容不会占用窗口。
2. **能力可扩展**：想给 Agent 加一项新本领？写一个技能包即可，不用改核心代码。
3. **即时生效**：技能在任务执行中动态加载，无需重启。

如果你用过 Claude 的 Skills 或类似机制，会对这个模式很熟悉——它把"Agent 知道什么"和"Agent 此刻需要什么"解耦开来。

## 🧩 4.9.x 期间已提前到位的能力

以下几项原计划随 v4.10.0 发布，但已在 4.9.x 系列中提前上线：

- **插件扩展页面**：插件可以通过 iframe + Page SDK 渲染自定义 UI（[@TyperBody](https://github.com/TyperBody)，#2107）
- **监控**：反馈与消息 ID 关联，并支持反馈数据导出（[@6mvp6](https://github.com/6mvp6)，#2120）
- **安全加固**：修复路径穿越问题，移除了一个需要鉴权的 RCE 端点（[@sebastiondev](https://github.com/sebastiondev)，#2087 / #2178）

## 🚀 如何启用

沙箱需要一个执行后端，按部署方式不同：

- **Docker**：运行 `docker compose --profile all up`，会一并启动 `langbot_box` 容器。
- **手动 / `uvx`**：自动以 stdio 子进程方式运行，无需额外操作。
- **LangBot 云**：开箱即用，沙箱已经为你配置好，无需安装。

如果你想关闭沙箱，设置 `box.enabled: false` 即可——此时内置工具、技能的创建/编辑，以及 stdio 模式的 MCP 都会停用；`http` / `sse` 模式的 MCP 不受影响。详见[沙箱文档](https://langbot.app/docs/zh/usage/sandbox/readme.md)。

此外，本次更新将插件 SDK 升级至 **`langbot-plugin 0.4.1`**。

## 写在最后

沙箱和技能这两项能力，本质上是在回答同一个问题：**怎样让 Agent 处理真正复杂、开放的任务？**

沙箱解决的是"**手**"——让 Agent 有能力执行、有空间试错；技能解决的是"**脑**"——让 Agent 在合适的时机调用合适的知识，而不被无关信息淹没。

最快的体验方式是在 [LangBot 云](https://space.langbot.app/cloud)上一键部署一个托管实例，沙箱已经就绪。也可以查看[完整发布说明](https://github.com/langbot-app/LangBot/releases/tag/v4.10.0)了解全部变更。

感谢每一位与 LangBot 一起构建的开发者。我们会继续把云端 Agent 的体验做得更稳、更强。

---

# LangBot v4.9.0：知识库全面插件化——RAG 引擎、解析器与无边界知识架构

Source: https://langbot.app/docs/zh/articles/langbot-v490-rag-plugin-architecture

LangBot v4.9.0 将知识库能力从内置实现重构为插件化架构，引入 RAG 引擎和解析器两大组件类型，实现知识库的无边界扩展。本文深度解读这次架构升级的设计思路、核心变更与开发指南。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/langbot-v490-rag-plugin-architecture).

发布于 2026-03-10 · 作者：LangBot Team

![LangBot v4.9.0 RAG Plugin Architecture](https://langbot.app/docs/images/articles/source/images/covers/rag-plugin.png)

LangBot v4.9.0 代号 **"Knowledge Without Borders"**（知识无边界），这个命名精准地概括了本次版本的核心变化：**知识库能力从内置实现全面重构为插件化架构**。

这不是一次小修小补——它重新定义了 LangBot 中"知识"的边界。

## 为什么要做这件事？

在 v4.9.0 之前，LangBot 的知识库分为两套体系：

- **内置知识库**：使用 Chroma 作为向量数据库，嵌入模型由 LangBot 直接调用，文档解析、分块、索引全部内置。
- **外部知识库**：通过 `KnowledgeRetriever` 插件组件桥接 Dify、RAGFlow、FastGPT 等外部服务，只做检索，不管文档摄取。

这两套体系在 UI 上以 Tab 切换的方式呈现，数据模型和管理逻辑完全割裂。

**问题在于：**

1. **扩展性差**：想换一个向量数据库？想用自己的分块策略？对不起，内置实现写死了。
2. **维护成本高**：每次 RAG 能力迭代，都需要改 LangBot 核心代码，发版才能生效。
3. **体验割裂**：内置和外部两种知识库的管理方式完全不同，用户学习成本高。

v4.9.0 的解决方案很直接：**把 RAG 能力从 LangBot 核心中抽出来，交给插件**。

## 核心变更一览

### 1. 统一知识库模型

移除 `internal` / `external` 的区分。所有知识库统一管理，通过 `rag_engine_plugin_id` 区分背后使用的 RAG 引擎。UI 上不再有两个 Tab，只有一个知识库列表，创建时选择引擎即可。

### 2. 新增 KnowledgeEngine 组件

这是本次最核心的新增。`KnowledgeEngine`（知识引擎）替代了旧的 `KnowledgeRetriever`，承担完整的知识库生命周期管理：

- **文档摄取（Ingest）**：从文件解析到向量索引的完整流程
- **知识检索（Retrieve）**：查询时返回相关知识块
- **文档删除（Delete）**：清理文档及关联的向量数据
- **生命周期钩子**：知识库创建/删除时的回调

换句话说，一个 KnowledgeEngine 插件可以完全控制知识库的索引和检索策略，而不仅仅是做检索。

![插件市场中的知识引擎插件](https://langbot.app/docs/images/articles/external/b9a33a8551a7-8dd37939-4f10-4046-bd84-cce798005cd4.png)

### 3. 新增 Parser 组件

文档解析也被独立为插件组件。Parser 负责将 PDF、Word、Markdown 等二进制文件转换为结构化文本，然后交给 RAG 引擎做分块和索引。

**Parser 和 KnowledgeEngine 的关系：**

![数据流：Parser → KnowledgeEngine](https://langbot.app/docs/images/articles/source/images/rag-plugin/data-flow.png)

如果 RAG 引擎自身声明了 `DOC_PARSING` 能力，也可以跳过外部 Parser，自行处理文档解析。

### 4. 宿主 RAG API

LangBot 核心不再直接执行 RAG 操作，但仍然提供了关键的基础设施，封装在 `RAGRuntimeService` 中供插件通过 RPC 调用：

- **嵌入模型调用**：`invoke_embedding()` —— 插件无需自己管理模型连接
- **向量数据库操作**：`vector_upsert()` / `vector_search()` / `vector_delete()` —— 写入、搜索、删除
- **文件读取**：`get_knowledge_file_stream()` —— 从存储中获取原始文件

这意味着插件可以专注于 RAG 策略（分块方式、检索算法、重排序逻辑），而把向量存储和嵌入模型这些"重"操作交给宿主。

### 5. 废弃 KnowledgeRetriever

旧的 `KnowledgeRetriever` 组件已被移除。如果你之前开发过外部知识库插件，需要迁移到 `KnowledgeEngine`。好消息是 KnowledgeEngine 的 API 更清晰，迁移并不复杂。

## 开发一个 RAG 引擎插件

以下是开发自定义 RAG 引擎的完整流程。

### 创建组件

```bash
lbp comp KnowledgeEngine
```

按提示输入引擎名称和描述，SDK 会自动生成目录结构：

![插件目录结构](https://langbot.app/docs/images/articles/source/images/rag-plugin/dir-structure.png)

### 定义配置 Schema

在 `.yaml` 清单文件中定义两类配置：

- **`creation_schema`**：用户创建知识库时填写的参数（如分块大小、嵌入模型）
- **`retrieval_schema`**：检索时可调整的参数（如分数阈值、Top-K）

```yaml
spec:
  creation_schema:
    - name: chunk_size
      label:
        zh_Hans: 分块大小
      type: integer
      default: 500
    - name: chunk_overlap
      label:
        zh_Hans: 分块重叠
      type: integer
      default: 50
  retrieval_schema:
    - name: score_threshold
      label:
        zh_Hans: 分数阈值
      type: float
      default: 0.5
```

LangBot 会根据这些 Schema **动态渲染**创建和检索的配置表单，不同的 RAG 引擎展示不同的配置项。

### 声明能力

```python
class SimpleRag(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return [
            KnowledgeEngineCapability.DOC_INGESTION,   # 支持文档上传
            # KnowledgeEngineCapability.DOC_PARSING,   # 可选：支持内置文档解析
        ]
```

| 能力              | 说明                            |
| --------------- | ----------------------------- |
| `DOC_INGESTION` | 支持文档上传和处理。声明后 UI 显示"文档"标签页    |
| `DOC_PARSING`   | 支持内置文档解析。未声明则必须安装外部 Parser 插件 |

### 实现核心方法

最关键的三个方法：

**文档摄取：**

```python
async def ingest(self, context: IngestionContext) -> IngestionResult:
    # 1. 获取文件内容（或使用 Parser 的预解析结果）
    if context.parsed_content:
        text = context.parsed_content.text
    else:
        file_bytes = await self.plugin.get_knowledge_file_stream(
            context.file_object.storage_path
        )
        text = file_bytes.decode('utf-8')

    # 2. 分块
    chunks = self._split_text(text, chunk_size=500)

    # 3. 调用宿主嵌入模型
    vectors = await self.plugin.invoke_embedding(
        embedding_model_uuid, chunks
    )

    # 4. 写入宿主向量数据库
    await self.plugin.vector_upsert(
        collection_id, vectors, ids, metadata
    )

    return IngestionResult(
        document_id=context.file_object.metadata.document_id,
        status=DocumentStatus.COMPLETED,
        chunks_created=len(chunks),
    )
```

**知识检索：**

```python
async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
    # 1. 生成查询向量
    query_vectors = await self.plugin.invoke_embedding(
        embedding_model_uuid, [context.query]
    )

    # 2. 向量搜索
    results = await self.plugin.vector_search(
        collection_id, query_vectors[0], top_k=5
    )

    # 3. 转换并返回
    return RetrievalResponse(results=entries, total_found=len(entries))
```

**文档删除：**

```python
async def delete_document(self, kb_id: str, document_id: str) -> bool:
    deleted = await self.plugin.vector_delete(
        collection_id=kb_id, file_ids=[document_id]
    )
    return deleted > 0
```

### 桥接外部知识库服务

如果你的目标不是自建 RAG 流程，而是桥接 Dify、RAGFlow、FastGPT 等外部服务，实现方式更简单——**不需要声明 `DOC_INGESTION` 能力**，只实现 `retrieve` 方法即可：

```python
class DifyRAGEngine(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return []  # 不支持文档上传，由外部服务管理

    async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
        # 调用 Dify/RAGFlow/FastGPT 的检索 API
        ...
```

这样在 LangBot 中创建知识库时选择该引擎，不会显示"文档"标签页，知识的管理完全在外部服务中进行。

## 开发 Parser 插件

Parser 的开发更加简洁：

```bash
lbp comp Parser
```

在清单文件中声明支持的 MIME 类型：

```yaml
spec:
  supported_mime_types:
    - application/pdf
    - application/vnd.openxmlformats-officedocument.wordprocessingml.document
```

实现 `parse` 方法：

```python
class PdfParser(Parser):

    async def parse(self, context: ParseContext) -> ParseResult:
        # context.file_content: 原始文件字节
        # context.mime_type: 文件 MIME 类型
        # context.filename: 原始文件名

        text = extract_text_from_pdf(context.file_content)

        return ParseResult(
            text=text,
            sections=[
                TextSection(content=page_text, heading=f"Page {i}", page=i)
                for i, page_text in enumerate(pages)
            ],
        )
```

Parser 和 KnowledgeEngine 之间还支持**跨插件调用**——一个 RAG 引擎插件可以主动调用另一个插件提供的 Parser：

```python
result = await self.plugin.invoke_parser(
    plugin_author="author_name",
    plugin_name="plugin_name",
    storage_path=context.file_object.storage_path,
    mime_type=context.file_object.metadata.mime_type,
    filename=context.file_object.metadata.filename,
)
```

## 升级须知

- 旧版本中创建的内置知识库和外部知识库会由迁移工具**自动迁移**，更新后到知识库页面确认即可。
- `KnowledgeRetriever` 组件已废弃，旧插件需要迁移到 `KnowledgeEngine`。
- 在[插件市场](https://space.langbot.app/market?category=KnowledgeEngine)可以找到已有的 RAG 引擎插件。

## 写在最后

v4.9.0 的知识库插件化是 LangBot 插件系统的又一次扩展。从 v4.0 的事件处理器和工具，到知识检索器，再到现在的 RAG 引擎和解析器——LangBot 的核心能力正在逐步从"内置"走向"可插拔"。

这个方向的终局是：**LangBot 核心只提供流水线编排和基础设施，所有业务能力都由插件驱动**。

想要自定义分块策略？写个 KnowledgeEngine 插件。想支持 PDF 解析？写个 Parser 插件。想桥接企业内部的知识库服务？同样是一个插件。

知识，不再有边界。

***

**相关链接：**

- [v4.9.0 Release Notes](https://github.com/langbot-app/LangBot/releases/tag/v4.9.0)
- [知识引擎开发文档](https://langbot.app/docs/zh/plugin/dev/components/knowledge-engine.md)
- [解析器开发文档](https://langbot.app/docs/zh/plugin/dev/components/parser.md)
- [插件市场](https://space.langbot.app/market)
- [LangBot Cloud](https://space.langbot.app/cloud)

---

# 用 Langflow 拖拽式工作流构建多平台 AI 机器人

Source: https://langbot.app/docs/zh/articles/langflow-drag-and-drop-ai-bot

用 Langflow 拖拽式工作流构建多平台 AI 机器人

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/langflow-drag-and-drop-ai-bot).

发布于 2025-12-05 · 作者：LangBot Team

![用 Langflow 拖拽式工作流构建多平台 AI 机器人](https://langbot.app/docs/images/articles/source/images/covers/langflow.png)

用可视化工作流驱动 QQ、微信、Telegram、Discord 等平台的聊天机器人，无需编写代码。

***

[LangBot](https://github.com/langbot-app/LangBot) 是一个开源即时通讯机器人平台，可以连接 Langflow、n8n、Dify、FastGPT、Coze 等 AI 工作流引擎，以及微信、QQ、飞书、钉钉、Telegram、Discord、Slack、LINE 等消息平台。本教程演示如何将 Langflow 的可视化工作流作为 LangBot 的对话引擎。

## 为什么选择这套方案

- **真正的多平台**：一个工作流同时驱动 8+ 个消息平台
- **可视化编排**：拖拽式对话设计，支持条件分支、多轮对话、外部 API 调用
- **灵活的 AI 模型**：支持 OpenAI、Claude、Gemini、DeepSeek 以及本地模型
- **完全开源**：LangBot 和 Langflow 都是开源项目，可免费部署和二次开发

## 准备工作

- Python 3.10+
- Docker（推荐用于快速部署）
- OpenAI API Key 或其他 LLM 服务的 API Key

## 第一步：部署 LangBot

用 uvx 一行命令启动：

```bash
uvx langbot
```

首次运行会自动初始化并打开浏览器访问 <http://127.0.0.1:5300。>

![LangBot Initial Page](https://langbot.app/docs/images/articles/external/0c8aa2c940ab-01-langbot-initial-page.png)

注册后登录进入控制台：

![LangBot Dashboard](https://langbot.app/docs/images/articles/external/b93d97b5b830-04-langbot-dashboard.png)

## 第二步：部署 Langflow

用 Docker 快速部署：

```bash
docker run -d --name langflow -p 7860:7860 langflowai/langflow:latest
```

访问 <http://localhost:7860> 进入 Langflow：

![Langflow Welcome Page](https://langbot.app/docs/images/articles/external/7e7ebfc3ba58-01-langflow-welcome.png)

## 第三步：创建 Langflow 工作流

在 Langflow 中选择 "Basic Prompting" 模板快速开始：

![Langflow Template Selection](https://langbot.app/docs/images/articles/external/b304cebf8ce9-02-langflow-template-selection.png)

这个模板包含四个基础组件：

- **Chat Input**：接收用户消息
- **Prompt**：设置系统提示词
- **Language Model**：调用 LLM 生成回复
- **Chat Output**：返回结果

![Langflow Workflow Editor](https://langbot.app/docs/images/articles/external/6e24402fd4a8-03-langflow-workflow-editor.png)

### 配置语言模型

点击 Language Model 组件进行配置：

1. **Model Provider**：选择 OpenAI（或其他兼容的提供商如 SiliconFlow、New API）
2. **Model Name**：选择 gpt-4o-mini 或 deepseek-chat
3. **OpenAI API Key**：填入你的 API Key

![Langflow OpenAI API Key Configured](https://langbot.app/docs/images/articles/external/bcd91ef5e4b3-14-langflow-openai-api-key-configured.png)

> 提示：你可以使用 OpenAI 兼容的 API 服务，比如 SiliconFlow 或 New API，只需修改 Base URL 即可。

配置完成后保存工作流。

## 第四步：获取 Langflow API 信息

### 生成 API Key

在 Langflow 右上角：Settings → API Keys，进入 API Keys 页面：

![Langflow API Keys Page](https://langbot.app/docs/images/articles/external/21fc47358066-05-langflow-api-keys-page.png)

点击 Create New Key：

![Langflow Create API Key Dialog](https://langbot.app/docs/images/articles/external/8f04c7b00759-06-langflow-create-api-key-dialog.png)

生成并保存 API Key：

![Langflow API Key Generated](https://langbot.app/docs/images/articles/external/e5a019491ef8-07-langflow-api-key-generated.png)

格式：`sk-xxxxxxxxxxxxxxxxxxxxxxxx`

### 获取 Flow ID

从工作流编辑器的 URL 中提取：

```
http://localhost:7860/flow/{flow-id}
```

记录这个 `flow-id`。

## 第五步：在 LangBot 中配置 Langflow

回到 LangBot 控制台，进入 **Pipelines** 页面。

点击 ChatPipeline 进行编辑，在 AI 标签页：

![LangBot Pipeline AI Tab](https://langbot.app/docs/images/articles/external/3c7d6bc96738-08-langbot-pipeline-ai-tab.png)

配置**运行器**，选择 **Langflow API**：

![LangBot 运行器下拉菜单](https://langbot.app/docs/images/articles/external/ef9bbef78165-09-langbot-runner-dropdown.png)

填写 Langflow 配置：

![LangBot Langflow Config Form](https://langbot.app/docs/images/articles/external/82d5e2ffb9a0-10-langbot-langflow-config-form.png)

配置项：

- **Base URL**：`http://localhost:7860`（本地）或 `http://langflow:7860`（Docker 网络）
- **API Key**：在 Langflow 中生成的 API Key
- **Flow ID**：之前记录的 Flow ID

![LangBot Langflow Config Filled](https://langbot.app/docs/images/articles/external/2fb54ce0f7a2-11-langbot-langflow-config-filled.png)

> Docker 提示：如果两个服务都在容器中运行，确保它们在同一个网络，并使用容器名作为 Base URL。

点击 **Save** 保存配置。

## 第六步：测试对话

在 Pipelines 页面点击 **Debug Chat** 打开调试对话界面：

![LangBot Debug Chat Interface](https://langbot.app/docs/images/articles/external/b36d6dea3702-12-langbot-debug-chat-interface.png)

输入测试消息如 "Hello"，查看 AI 回复：

![LangBot Chat Test Success](https://langbot.app/docs/images/articles/external/3d7fa393f210-13-langbot-chat-with-response.png)

## 工作原理

1. 用户在消息平台发送消息
2. LangBot 接收并传递给 Pipeline
3. Pipeline 调用 Langflow API
4. Langflow 执行工作流：接收输入 → 添加提示词 → 调用 LLM → 返回结果
5. LangBot 将回复发送给用户

## 常见问题

**无法连接 Langflow？**

检查 Base URL。如果是 Docker 部署，确保容器在同一个网络：

```bash
docker network create langbot_network
docker network connect langbot_network langflow
docker network connect langbot_network langbot
```

使用容器名：`http://langflow:7860`

**API 调用失败？**

- 确认 API Key 和 Flow ID 正确
- 验证 Langflow 中的 Language Model 已配置有效的 LLM API Key

## 高级应用场景

Langflow 的强大之处在于可以可视化编排复杂的 AI 工作流：

- **多轮记忆**：添加 Memory 组件实现上下文理解
- **条件分支**：根据用户输入执行不同逻辑
- **外部 API 集成**：连接数据库、搜索引擎、第三方服务
- **多 Agent 协作**：多个 LLM 模型协同工作
- **RAG 应用**：集成向量数据库实现知识库问答

所有这些都可以通过拖拽完成，无需编写代码。

## 总结

通过 LangBot + Langflow，你可以快速构建强大的多平台 AI 聊天机器人。Langflow 提供可视化工作流编排，LangBot 负责消息平台接入，两者结合形成了从工作流设计到多平台部署的完整闭环。

这套方案特别适合：

- 需要在多个平台提供相同 AI 能力的场景
- 团队希望快速迭代和测试不同对话流程
- 开发者希望在不深入编码的情况下构建复杂 AI 应用

## 相关资源

- [LangBot 官网](https://langbot.app) | [文档](https://langbot.app/docs/zh/insight/guide.md) | [GitHub](https://github.com/langbot-app/LangBot)
- [Langflow 官网](https://www.langflow.org) | [文档](https://docs.langflow.org) | [GitHub](https://github.com/langflow-ai/langflow)

***

*本文基于 LangBot 最新版本编写。LangBot 还支持集成 Dify、n8n、FastGPT、Coze 等 AI 平台，可根据需求选择合适的工作流引擎。*

---

# LangTARS：开源 AI Agent 远程控制电脑 — 支持接入 Dify 和 n8n 工作流

Source: https://langbot.app/docs/zh/articles/langtars-remote-pc-control-dify-n8n

LangTARS 是 LangBot 原生插件，让你通过 Telegram、Discord、微信等聊天软件远程控制电脑，并支持接入 Dify、n8n 等 AI 工作流平台。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/langtars-remote-pc-control-dify-n8n).

发布于 2026-03-23 · 作者：LangBot Team

![LangTARS Logo](https://langbot.app/docs/images/articles/external/3fe5bdc18716-icon.svg)

**LangBot 原生插件 | 类 OpenClaw 体验 | 一键部署即可使用**

***

## ✨ 什么是 LangTARS？

**LangTARS** 是 **LangBot 原生的类 OpenClaw 插件**，灵感来自《星际穿越》中忠诚可靠的机器人 TARS。

它能让你通过 **Telegram、钉钉、微信** 等聊天软件，远程控制你的 **Mac / Windows / Linux** 电脑！

> 💡 **部署 LangBot，即可体验 LangTARS！** 无需额外安装，插件市场一键获取。

![LangTARS 演示](https://langbot.app/docs/images/articles/external/70b26e660a60-tars.gif)

***

## 🎯 能做什么？

只需发一条消息，AI 就能帮你完成各种任务：

| 你说                                                      | AI 做            |
| ------------------------------------------------------- | --------------- |
| `!tars 给我打开chrome里的小红书，给我发一篇帖子，标题为来自LangTARS的一封信，内容是你好` | 🌐 自动打开小红书并发布帖子 |
| `!tars 帮我整理桌面文件`                                        | 📁 自动分类整理文件     |
| `!tars 打开浏览器搜索今天的新闻`                                    | 🌐 打开浏览器并搜索     |
| `!tars 创建一个会议笔记`                                        | 📝 自动创建笔记文件     |
| `!tars 查看系统信息`                                          | 💻 获取电脑状态       |

![使用示例](https://langbot.app/docs/images/articles/external/6613b3025b8b-usage-example.png)
![plan模式](https://langbot.app/docs/images/articles/external/ff42857251ab-planner-mode.png)

***

## 🚀 为什么选择 LangTARS？

### 1️⃣ LangBot 原生插件，开箱即用

```bash
# 一行命令部署 LangBot
uvx langbot@latest

# 插件市场安装 LangTARS，配置模型，开始使用！
```

**无需复杂配置，无需额外部署，LangBot 用户直接体验！**

![安装流程](https://langbot.app/docs/images/articles/external/2a3a0d5f4ae9-install-flow.png)

***

### 2️⃣ 智能任务规划，自主执行

基于 **ReAct 循环**的 AI 规划引擎：

```
你的指令 → 理解需求 → 制定计划 → 逐步执行 → 反馈结果
```

AI 会像人一样思考，自动拆解复杂任务！

***

### 3️⃣ 多浏览器支持

| 浏览器            | macOS | Windows | Linux |
| -------------- | ----- | ------- | ----- |
| Playwright（无头） | ✅     | ✅       | ✅     |
| Safari         | ✅     | -       | -     |
| Chrome         | ✅     | ✅       | ✅     |
| Edge           | -     | ✅       | -     |
| Firefox        | -     | -       | ✅     |

***

### 4️⃣ 安全优先设计

- 🚫 **危险命令拦截** — `rm -rf /` 等命令自动阻止
- 📂 **工作区隔离** — 文件操作限制在安全目录
- 📋 **命令白名单** — 可配置允许的命令
- 👤 **用户访问控制** — 限制特定用户使用

![安全特性](https://langbot.app/docs/images/articles/external/a618d3d41416-security.png)

***

## 📱 快速开始

### Step 1: 部署 LangBot

```bash
uvx langbot@latest
```

### Step 2: 配置聊天平台

按照文档配置 Telegram / 钉钉 / 微信机器人

### Step 3: 安装 LangTARS

在 LangBot 插件市场搜索 **LangTARS** 并安装

### Step 4: 开始对话

```
!tars 你好，告诉我你能做什么
```

> 📱 **推荐**：在 **Telegram** 或 **钉钉** 上使用，体验最佳！

***

## 🎮 常用命令

| 命令             | 功能     |
| -------------- | ------ |
| `!tars <任务描述>` | 执行任务   |
| `!tars stop`   | 停止当前任务 |
| `!tars what`   | 查看执行状态 |
| `!tars reset`  | 重置对话   |
| `!tars help`   | 显示帮助   |

***

## 🌟 项目信息

| 项目         | 信息                                                                         |
| ---------- | -------------------------------------------------------------------------- |
| **GitHub** | [github.com/langbot-app/LangTARS](https://github.com/langbot-app/LangTARS) |
| **语言**     | Python 100%                                                                |
| **许可证**    | CC BY-NC-ND 4.0                                                            |
| **平台**     | macOS / Windows / Linux                                                    |

***

## 🔗 相关链接

- 📖 **LangBot 文档**: [langbot.app/docs](https://langbot.app/docs/zh/insight/guide.md)
- 💬 **问题反馈**: [GitHub Issues](https://github.com/langbot-app/LangTARS/issues)
- ⭐ **Star 支持**: [GitHub](https://github.com/langbot-app/LangTARS)

***

## 🎉 部署 LangBot，体验 LangTARS！

**让 AI 成为你忠诚的数字助手，就像 TARS 一样。**

```bash
uvx langbot@latest
```

**#LangTARS #LangBot #AI助手 #效率工具 #开源**

***

## 🔗 搭配 Dify & n8n，释放更强大能力

LangTARS 搭配 AI 工作流平台使用效果更佳：

- **Dify 集成**：将 LangBot 作为 [Dify](https://dify.ai) 的消息前端，在 Dify 可视化编辑器中构建复杂 AI 工作流，然后通过 Telegram/Discord 触发。例如：自动生成报告 → 创建文件 → 发送邮件通知，全部通过一条聊天消息完成。
- **n8n 集成**：结合 [n8n](https://n8n.io) 工作流与 LangBot，将 LangTARS 的电脑控制能力与 n8n 的 400+ 集成组合，实现无限可能。
- **同时支持**：Langflow、Coze 以及任何 OpenAI 兼容 API。

> 💡 **示例**："TARS，运行我的 Dify 工作流分析今天的销售数据，把报告保存到桌面" — LangTARS 处理整个链路。

---

# 用 n8n 和 LangBot 构建多平台 AI 聊天机器人

Source: https://langbot.app/docs/zh/articles/n8n-multi-platform-ai-chatbot

用 n8n 和 LangBot 构建多平台 AI 聊天机器人

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/n8n-multi-platform-ai-chatbot).

发布于 2025-12-03 · 作者：LangBot Team

![用 n8n 和 LangBot 构建多平台 AI 聊天机器人](https://langbot.app/docs/images/articles/source/images/covers/n8n.png)

将 n8n 的可视化工作流自动化与 LangBot 的多平台机器人框架相结合，可以在 QQ、微信、Discord、Telegram、Slack 等平台上以无代码方式部署 AI 聊天机器人。本教程演示如何在几分钟内完成集成。

## 你需要准备

- 已安装 Python 3.8+
- 已安装 Node.js 18+
- 可用的 npm 或 npx
- 15 分钟时间

## 三行命令部署 LangBot

LangBot 是一个生产级的机器人框架，支持连接多种消息平台和 AI 服务，包括 Dify、FastGPT、Coze、OpenAI、Claude 和 Gemini。一键部署：

```bash
cd your-workspace
mkdir -p langbot-instance && cd langbot-instance
uvx langbot@latest
```

首次启动时 LangBot 会自动初始化。在浏览器打开 `http://127.0.0.1:5300`。

![LangBot initialization screen](https://langbot.app/docs/images/articles/external/70ee40a6d232-01-langbot-initialization.png)

按提示注册管理员账号。注册成功后进入控制台，可以管理机器人、模型、流水线和集成。

![LangBot dashboard](https://langbot.app/docs/images/articles/external/4f1f5c28fbfc-03-langbot-dashboard.png)

## 搭建 n8n 工作流自动化

n8n 是一个开源自动化平台，拥有 400+ 集成和强大的 AI 能力。本地启动：

```bash
cd your-workspace
mkdir -p n8n-data
export N8N_USER_FOLDER=$(pwd)/n8n-data
npx n8n
```

访问 `http://127.0.0.1:5678` 创建你的主账号。

![n8n initial setup](https://langbot.app/docs/images/articles/external/12d0e04600c5-05-n8n-setup.png)

## 构建 AI 工作流

在 n8n 中创建新工作流。你需要两个核心节点：

![n8n workflow editor](https://langbot.app/docs/images/articles/external/e36d04ca4a5b-07-n8n-workflow-editor.png)

### 添加 Webhook 触发器

点击画布上的 "+" 添加 **Webhook** 节点。配置如下：

- **HTTP Method**：POST
- **Response Mode**：Streaming（启用实时聊天响应）
- **Authentication**：None（生产环境请调整）

![Webhook node configuration](https://langbot.app/docs/images/articles/external/03443176ae5c-08-n8n-webhook-node.png)

### 添加 AI Agent

按 Tab 键，导航到 "AI" 分类，选择 **AI Agent**。

**配置对话模型**：点击 "Chat Model" 选择 "OpenAI Chat Model"。添加凭据：

- **API Key**：你的 OpenAI API key（或兼容服务的 key）
- **Base URL**：如果使用 Claude、Gemini 或本地模型等其他提供商，更新为对应的 endpoint

**关键步骤 - 修复 Prompt 来源**：默认情况下 AI Agent 期望 Chat Trigger 节点，这与 webhook 不兼容。修复方法：

1. 在 AI Agent 设置中找到 "Source for Prompt (User Message)"
2. 从 "Connected Chat Trigger Node" 改为 "Define below"
3. 切换到 "Expression" 模式
4. 输入：`{{ $json.body }}`

这个表达式从 webhook 请求体中提取用户消息。

![Configured webhook with AI Agent](https://langbot.app/docs/images/articles/external/621f3d526678-09-n8n-webhook-configured.png)

### 激活并获取 Webhook URL

保存工作流并切换右上角的激活开关。切换到 "Production URL" 标签页，复制 webhook URL：

```
http://localhost:5678/webhook/{your-webhook-id}
```

## 连接 LangBot 到 n8n

回到 LangBot 控制台，进入 **Pipelines** 页面，点击默认的 "ChatPipeline"。

![LangBot pipelines page](https://langbot.app/docs/images/articles/external/ef2b2f83bd16-04-langbot-pipelines.png)

切换到 **AI** 标签页，在运行器下拉菜单中选择 "n8n Workflow API"。配置：

- **Webhook URL**：粘贴你的 n8n 生产环境 webhook URL
- **Authentication Type**：None（与 n8n webhook 设置保持一致）
- **Timeout**：120 秒
- **Output Key**：response

点击 **Save** 保存。

## 测试一下

在 Pipeline 编辑器中点击左侧边栏的 "Debug Chat"。发送测试消息如 "What is LangBot?"

如果一切正常，你会看到 LangBot 将消息发送到 n8n，AI Agent 处理后将响应流式返回。

## 故障排查

**错误："Expected to find the prompt in an input field called 'chatInput'"**

这意味着 AI Agent 仍配置为 Chat Trigger 节点。修复：

1. 打开 AI Agent 配置
2. 将 "Source for Prompt (User Message)" 设为 "Define below"
3. 切换到 Expression 模式
4. 输入：`{{ $json.body }}`

**直接测试 Webhook**

用 curl 验证 webhook 是否工作：

```bash
curl -X POST http://localhost:5678/webhook/your-webhook-id \
  -H "Content-Type: application/json" \
  -d '{"body": "Hello, can you introduce yourself?"}'
```

你应该收到包含 AI 响应的流式 JSON。

## 集成工作原理

完整流程如下：

1. 用户通过 QQ、微信、Discord、Telegram、Slack、LINE 或任何 LangBot 支持的平台发送消息
2. LangBot 的 Pipeline 接收消息并调用 n8n Workflow API
3. n8n 的 Webhook 节点捕获请求并传递给 AI Agent
4. AI Agent 使用 OpenAI、Claude、Gemini 或你配置的 LLM 生成回复
5. n8n 将响应流式返回给 LangBot
6. LangBot 将回复送达用户原来的平台

## 为什么这套组合很强大

**LangBot + n8n** 解锁了强大的能力：

1. **无代码 AI 逻辑**：在 n8n 中以可视化方式设计对话流程，无需触碰代码
2. **多平台覆盖**：同时在 QQ、微信、Discord、Telegram、Slack、LINE、钉钉、飞书部署相同的 AI
3. **灵活的 AI 模型**：在 OpenAI GPT、Anthropic Claude、Google Gemini、Coze、Dify、本地模型等之间自由切换
4. **丰富的集成**：连接 n8n 的 400+ 集成——数据库、API、Notion、Airtable、Google Sheets、Slack 等
5. **工具调用 Agent**：AI Agent 可以触发 n8n 工具，如数据库查询、API 调用或自定义函数
6. **工作流扩展**：添加预处理、内容审核、日志记录或自定义业务逻辑

**适合场景**：

- 企业客服机器人
- 知识库问答系统
- 多平台社群管理
- 任务自动化助手
- 团队统一聊天界面

## 下一步

进一步扩展你的机器人：

- 集成 Dify 或 FastGPT 实现高级 RAG（检索增强生成）
- 添加向量数据库节点（Pinecone、Qdrant、Weaviate）实现知识检索
- 连接业务 API 获取实时数据
- 实现对话记忆和上下文追踪
- 添加内容过滤和审核工作流
- 使用 Langflow 或 Coze 进行额外的 AI 编排

这套集成为你提供了基于代码的 AI 框架（如 LangChain）的灵活性，以及可视化工作流构建器的简洁性——同时覆盖所有主流消息平台。

准备好部署你的多平台 AI 助手了吗？立即开始使用 LangBot 和 n8n。

---

# LangBot 博客正式上线

Source: https://langbot.app/docs/zh/articles/welcome

欢迎来到 LangBot 官方博客。在这里获取产品更新、新功能和里程碑信息。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/welcome).

发布于 2026-02-17 · 作者：LangBot Team

![LangBot Blog](https://langbot.app/docs/images/articles/source/images/covers/welcome.png)

我们很高兴推出 LangBot 官方博客！在这里，我们将分享产品更新、新功能、里程碑和来自 LangBot 团队的见解。

## 什么是 LangBot？

LangBot 是一个开源的大语言模型（LLM）原生即时通信机器人平台。它支持多种消息平台和模型供应商，并集成了 Dify、阿里云百炼等 LLMOps 平台。LangBot 还提供了 WebUI，方便用户快速部署和管理。

## 博客内容

在这个博客上，你将看到：

- **版本更新** - 每个新版本的详细说明
- **功能亮点** - 深入介绍新功能
- **里程碑** - 项目成长和社区成就
- **教程与技巧** - 充分利用 LangBot 的最佳实践

## 保持联系

- [GitHub](https://github.com/langbot-app/LangBot) - 给我们点个 Star，关注开发动态
- [文档](https://langbot.app/docs/zh/insight/guide.md) - 完整的使用指南和 API 参考
- [LangBot 主页](https://langbot.app) - 官方网站
- [插件市场](https://space.langbot.app) - 发现更多插件和扩展

敬请期待更多更新！

---

# 命令

Source: https://langbot.app/docs/zh/deploy/command

LangBot 命令行参考：通过终端管理 AI 机器人实例、配置与运行时。

LangBot 将以 `!` 开头的消息视为命令。官方提供了 [`EssentialCommands` 插件](https://space.langbot.app/market?author=langbot-team\&plugin=EssentialCommands)，包含了常用的命令。

您也可以开发自己的命令插件，请参考 [命令插件开发](https://langbot.app/docs/zh/plugin/dev/components/command.md)。

---

# Docker部署

Source: https://langbot.app/docs/zh/deploy/langbot/docker

在 Windows、Linux 或 macOS 上使用 Docker Compose 部署 LangBot。

## 1. 准备环境

- 安装 Git。
- **Windows / macOS**：安装并启动 Docker Desktop。
- **Linux**：安装 Docker 和 Docker Compose。

## 2. 下载项目

请选择有写入权限的普通目录。Linux 用户请避开 `/root`、`/etc` 等系统目录，建议放在 `/opt` 下，以免沙箱功能被安全规则拦截。

在准备存放项目的目录打开终端（Windows 可用 PowerShell），逐行执行：

```bash
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker
```

### 中国大陆用户：启动前更换镜像源（可选）

如果 Docker Hub 下载较慢，先编辑 `LangBot/docker/docker-compose.yaml`，将文件中的所有 `rockchin/langbot:latest` 替换为：

```text
docker.langbot.app/langbot-public/rockchin/langbot:latest
```

保存后再启动，无需更改其他配置。

## 3. 启动 LangBot

> info:
>
> 如果部署在服务器上，请通过防火墙限制管理页面和运行时端口的访问，仅允许可信来源连接。

在刚才的终端中执行：

```bash
docker compose --profile all up -d
```

首次启动需要下载镜像。Windows / macOS 用户请保持 Docker Desktop 运行。

## 4. 打开管理页面

- **本机部署**：打开 `http://localhost:5300`。
- **服务器部署**：打开 `http://你的服务器IP:5300`，确保防火墙允许你的设备访问该端口。

按照页面提示完成初始化，再添加[模型](https://langbot.app/docs/zh/usage/models/readme.md)和[机器人](https://langbot.app/docs/zh/usage/platforms/readme.md)。

## Beta 版本（可选）

如需试用 Beta 而非上述稳定版，请将 [dev/4.11.x 的 Compose 文件](https://raw.githubusercontent.com/langbot-app/LangBot/dev/4.11.x/docker/docker-compose.yaml)下载为 `compose.yaml`，保存到单独的可写目录。手动将**所有** `rockchin/langbot` 镜像改为 `rockchin/langbot:beta`：包括 Core（`langbot`）、插件运行时（`langbot_plugin_runtime`）和 Box（`langbot_box`，若存在）。每次发布 Beta 都会更新 `beta` 标签。在该目录执行以下命令启动或更新：

```bash
docker compose --profile all pull
docker compose --profile all up -d
```

---

# Kubernetes 部署

Source: https://langbot.app/docs/zh/deploy/langbot/kubernetes

在 Kubernetes 上部署 LangBot，实现可扩展、生产级的多平台 AI 机器人托管。

> warning:
>
> 您需要提前了解：
>
> - Kubernetes 集群的基本使用（`kubectl`、Namespace、Deployment、Service、PVC）
> - 容器间网络通信与持久化存储的配置方式

LangBot 仓库在 `docker/` 目录下提供了开箱即用的 Kubernetes 部署清单 [`kubernetes.yaml`](https://github.com/langbot-app/LangBot/blob/master/docker/kubernetes.yaml)。本页是该清单的部署说明，重点放在 **Box 沙箱运行时** 在 Kubernetes 下的部署方式——这是与 Docker Compose 部署差异最大的部分。

## 组件构成

清单会在 `langbot` 命名空间下创建以下组件：

| 组件                       | 说明                   | 端口               |
| ------------------------ | -------------------- | ---------------- |
| `langbot`                | 主应用（WebUI + webhook） | 5300 / 2280-2290 |
| `langbot-plugin-runtime` | 插件运行时                | 5400             |
| `langbot-box`            | Box 沙箱运行时（可选）        | 5410             |

持久化存储：`langbot-data`、`langbot-plugins`、`langbot-plugin-runtime-data` 三个 PVC；Box 工作区根目录使用节点上的 `hostPath`（`/app/data/box`），而非 PVC。

## 快速开始

```bash
# 克隆仓库
git clone https://github.com/langbot-app/LangBot
cd LangBot/docker

# 部署全部组件
kubectl apply -f kubernetes.yaml

# 查看状态
kubectl get all -n langbot
```

部署完成后，可通过端口转发访问 WebUI：

```bash
kubectl port-forward -n langbot svc/langbot 5300:5300
# 浏览器访问 http://localhost:5300
```

生产环境推荐使用 Ingress + TLS 对外暴露（清单中已附带被注释的 Ingress / LoadBalancer / NodePort 示例，按需取消注释）。

### 使用 SeekDB

官方镜像已经包含可选的 SeekDB 依赖，无需构建专用镜像或添加额外构建参数。将 `vdb.use` 配置为 `seekdb` 即可启用；不使用时保持默认的 `chroma`。

## Box 沙箱运行时

`langbot-box` 为 LangBot 提供代码沙箱能力，支撑沙箱工具（`exec` / `read` / `write` / `edit` / `glob` / `grep`）、技能的 `activate` 工具与新增/编辑、以及 stdio 模式的 MCP 服务器。它是**可选组件**：不部署时 LangBot 仍可运行，仪表盘与技能列表只读可见，但上述能力会被禁用，此时请在 `langbot` 上设置 `BOX__ENABLED=false`。

### 工作原理与关键约束

LangBot 官方镜像**只内置了 Docker CLI**（不含 dockerd，也不含 nsjail）。因此 Box 运行时通过挂载到节点的 Docker socket（`/var/run/docker.sock`）来创建沙箱容器——它本身不在 Pod 内运行 dockerd。

由此带来一个**关键约束**：真正创建沙箱容器的是**节点上的 Docker 守护进程**，它解析 bind-mount 路径时使用的是**节点文件系统**视角。所以 Box 工作区根目录必须在以下三处是**同一个绝对路径**：

1. 节点上的实际路径
2. `langbot-box` 容器内的挂载路径
3. 它创建的每个沙箱容器内的挂载路径

这正是清单使用 `hostPath`（固定在 `/app/data/box`）而非普通 PVC 的原因：PVC 路径只存在于 Pod 的 mount namespace 中，节点的 dockerd 看不到。同时 `langbot` 与 `langbot-box` 通过 `podAffinity` 被强制调度到**同一节点**以共享这个 hostPath。

> warning:
>
> 因为依赖 hostPath + 同节点亲和，`langbot` 不支持多副本横向扩容（与使用 `ReadWriteOnce` PVC 的限制一致）。如需高可用，需另行设计架构。

### 连接与配置

- `langbot` 通过 WebSocket 连接 Box 运行时，端点由 ConfigMap 中的 `BOX__RUNTIME__ENDPOINT: ws://langbot-box:5410` 指定。

> info:
>
> 容器内默认主机名是 `langbot_box`（带下划线），而下划线不是合法的 Kubernetes DNS 名称，因此清单中**必须显式**用合法的 Service 名 `langbot-box` 指定端点，不能依赖容器内默认值。

- Box 运行时**不读取**自身的 `box.local.*` / `BOX__*` 环境变量；其配置由 `langbot` 读取 `BOX__LOCAL__*` 后通过 INIT RPC 下发。因此 `BOX__LOCAL__HOST_ROOT` / `DEFAULT_WORKSPACE` / `SKILLS_ROOT` / `ALLOWED_MOUNT_ROOTS` 都配置在 `langbot` Deployment 上，其中 `HOST_ROOT` 必须与两侧的 `box-root` 挂载路径一致（`/app/data/box`）。

### 安全提示

挂载节点的 Docker socket 会让 Box 运行时（以及在沙箱中执行的任意代码）获得对节点的**实质 root 权限**。请仅在你信任该工作负载的节点上部署 Box，最好使用专用节点池并配合污点/容忍（taint/toleration）隔离。若需要更强的隔离边界，可将 `box.backend` 切换为 `e2b`（设置 `E2B_API_KEY`），并移除 `docker.sock` 挂载与 hostPath。详见[沙箱配置](https://langbot.app/docs/zh/usage/sandbox/config.md)。

### 验证 Box 是否就绪

```bash
# 查看 Box 运行时日志（应能看到选用的 backend，例如 "using backend: docker"）
kubectl logs -n langbot -l app=langbot-box -f

# 在 langbot 日志中确认已连上 Box 运行时
kubectl logs -n langbot -l app=langbot | grep -i "box runtime"
```

## 不需要沙箱时

如果你不需要沙箱能力，可以删除清单中的 `langbot-box` Deployment / Service，并在 `langbot` Deployment 上设置 `BOX__ENABLED=false`，以避免连接失败的告警日志。

## 后续阅读

- [Docker 部署](https://langbot.app/docs/zh/deploy/langbot/docker.md)
- [沙箱文档](https://langbot.app/docs/zh/usage/sandbox/readme.md) 与 [沙箱配置](https://langbot.app/docs/zh/usage/sandbox/config.md)
- [技能系统文档](https://langbot.app/docs/zh/usage/skills/readme.md)
- 部署清单源文件：仓库内 [`docker/kubernetes.yaml`](https://github.com/langbot-app/LangBot/blob/master/docker/kubernetes.yaml)

---

# 手动部署

Source: https://langbot.app/docs/zh/deploy/langbot/manual

从源码手动部署 LangBot：在 Linux、Windows、macOS 上搭建开源 AI 机器人平台的详细步骤。

> warning:
>
> Unix-like 系统上请优先考虑使用 Docker 部署。

## 安装主程序

1. 前往[Release](https://github.com/langbot-app/LangBot/releases)页面下载最新版本的压缩包（推荐）`langbot-xxx-all.zip`（请勿下载 Source Code，因为其中不包含 WebUI）。解压，在解压目录打开命令行（终端）

![下载Release](https://langbot.app/docs/images/zh/deploy/langbot/manual/dl_release.png)

2. 安装依赖

我们使用 [uv](https://docs.astral.sh/uv/) 管理依赖。

```bash
pip install uv
uv sync
```

默认安装不包含可选的 SeekDB 支持。如果需要使用 SeekDB 向量数据库或内置嵌入模型，请改用：

```bash
uv sync --extra seekdb
```

SeekDB 嵌入式模式的平台支持取决于 `pylibseekdb` wheel；Apple Silicon 当前要求 macOS 15 或更高版本。其他功能仍可使用默认的 `uv sync` 安装。

或者使用清华源

```bash
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
uv sync
```

3. 运行一次主程序，生成配置文件

```bash
uv run main.py
```

提示如下信息

```
 _                   ___      _   
| |   __ _ _ _  __ _| _ ) ___| |_ 
| |__/ _` | ' \/ _` | _ \/ _ \  _|
|____\__,_|_||_\__, |___/\___/\__|
               |___/              

⭐️开源地址: https://github.com/langbot-app/LangBot
📖文档地址: https://langbot.app/docs

以下文件不存在，已自动生成，请按需修改配置文件后重启：
- data/config.yaml
...
```

接下来可以使用 Ctrl+C 退出程序，继续查看[配置机器人](https://langbot.app/docs/zh/usage/platforms/readme.md)页。

---

# 1Panel部署

Source: https://langbot.app/docs/zh/deploy/langbot/one-click/1panel

使用 1Panel 一键部署 LangBot，无需命令行即可安装开源 AI 聊天机器人平台。

使用[1Panel](https://www.bt.cn/new/download.html?r=dk_LangBot)一键部署 LangBot。

> info:
>
> 使用[阿里云，服务器价格低至 38 元一年，更可以享受8折优惠](https://www.aliyun.com/minisite/goods?userCode=ys4ad8gs)，一键安装1Panel更方便

## 安装1Panel

> 服务器系统推荐(来自1Panel)：Debian 12，Ubuntu 22等
>
> 本文默认所述的是拥有公网IPv4地址的服务器，如果是家用机器没有公网 IP，可以通过下文中的内网来访问相关页面

打开[1Panel](https://www.bt.cn/new/download.html?r=dk_LangBot)，使用1Panel官方提供的Linux面板安装脚本，根据自己使用的系统选择对应的脚本

![安装1Panel](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_install_01.png)

复制对应脚本，粘贴到服务器执行。

等待一段时间后，1Panel安装完成

然后将`外部地址`复制到浏览器打开。

## 安装LangBot

打开`应用商店`，选择`AI`类别，点击安装 LangBot

![安装 LangBot ](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_langbot_01.png)

勾选`端口外部访问`，点击确认即可

![安装 LangBot ](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_langbot_02.png)

稍等片刻，安装完成

点击左侧`容器`，选择`容器`类目，即可看到 LangBot 容器栏

![查看 LangBot 容器信息](https://langbot.app/docs/images/zh/deploy/langbot/one-click/1p_langbot_03.png)

复制服务器公网地址，例如`http://xxx.xxx.xxx.xxx:5300`（xxx.xxx.xxx.xxx为1Panel 明白所在服务器的 IP，5300为端口号）

打开后输入管理员邮箱和密码，然后点击初始化。

然后就可以在可视化界面进行配置了。

接下来请继续阅读[配置消息平台](https://langbot.app/docs/zh/usage/platforms/readme.md)页。

---

# 宝塔面板部署

Source: https://langbot.app/docs/zh/deploy/langbot/one-click/bt

使用宝塔面板（aaPanel）一键部署 LangBot，通过 Web 控制面板安装开源 AI 机器人平台。

使用[宝塔面板](https://www.bt.cn/new/download.html?r=dk_LangBot)一键部署 LangBot。

> warning:
>
> 如果你已经安装了宝塔，请更新到 **9.2.0** 及以上

> info:
>
> 使用[阿里云，服务器价格低至 38 元一年，更可以享受8折优惠](https://www.aliyun.com/minisite/goods?userCode=ys4ad8gs)，一键安装宝塔更方便

## 安装宝塔

> 服务器系统推荐(来自宝塔)：Debian 12，Ubuntu 22等
>
> 本文默认所述的是拥有公网IPv4地址的服务器，如果是家用机器没有公网 IP，可以通过下文中的内网来访问相关页面

打开[宝塔面板](https://www.bt.cn/new/download.html?r=dk_LangBot)，使用宝塔官方提供的Linux面板安装脚本，根据自己使用的系统选择对应的脚本

![安装宝塔](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_install_01.png)

复制对应脚本，粘贴到服务器执行。

## 安装LangBot

等待一段时间后，宝塔安装完成

可以看到提示信息中类似这样的一段，将外网面板地址复制到浏览器打开。

![宝塔访问地址](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_install_02.png)

首次打开应该会弹出`推荐安装套件`，无需安装，关闭跳过即可。

然后点击侧边栏的`docker`，首次会提示安装Docker和Docker Compose服务，点击立即安装，若已安装请忽略。

然后在`Docker -> 应用商店`，搜索`LangBot`（注意大小写），点击`安装`，使用默认配置。

稍等一段时间，可以看到提示名为`langbot_XXXX`的容器显示`运行中`

![创建LangBot容器](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_langbot_01.png)

点击上图中红色圆圈查看运行日志

![查看LangBot容器运行日志](https://langbot.app/docs/images/zh/deploy/langbot/one-click/bt_langbot_02.png)

可以看到WebUI的配置页面（可视化配置页面）的外网和内网访问路径，复制公网地址，例如`http://xxx.xxx.xxx.xxx:5300`（xxx.xxx.xxx.xxx为宝塔面板IP，5300为端口号，可能变化，具体如图）

打开后输入管理员邮箱和密码，然后点击初始化。

然后就可以在可视化界面进行配置了。

接下来请继续阅读[配置消息平台](https://langbot.app/docs/zh/usage/platforms/readme.md)页。

---

# 使用包管理器部署

Source: https://langbot.app/docs/zh/deploy/langbot/package

使用包管理器（uv/uvx）部署 LangBot，快速安装开源大模型聊天机器人平台。

> info:
>
> 支持 Windows、Linux、Mac OS 等系统，推荐在测试环境、个人用途场景使用；生产级环境请使用[Docker部署](https://langbot.app/docs/zh/deploy/langbot/docker.md)。

LangBot 已打包发布至 PyPI。请安装[uv](https://docs.astral.sh/uv/getting-started/installation/)，然后在空目录下运行以下命令：

```bash
uvx langbot@latest
```

这将把该目录作为工作目录，访问 `http://localhost:5300` 即可开始使用。

## Beta 版本（可选）

如需试用 Beta 3，改用以下命令。`--prerelease=allow` 同时允许依赖包的预发布版本，`--refresh` 刷新缓存的包数据。

```bash
uvx --prerelease=allow --refresh langbot==4.11.0b3
```

## 可选的 SeekDB 支持

默认安装使用 Chroma，不包含 SeekDB 的 Python SDK 和原生组件。只有在需要将
SeekDB 用作向量数据库或使用其内置嵌入模型时，才用 `seekdb` extra 启动：

```bash
uvx --from 'langbot[seekdb]@latest' langbot
```

SeekDB 嵌入式模式还要求当前平台存在兼容的 `pylibseekdb` wheel。Apple Silicon
目前要求 macOS 15 或更高版本；macOS 14 ARM64 的支持计划见
[oceanbase/seekdb#1324](https://github.com/oceanbase/seekdb/issues/1324)。受当前
`pyseekdb` 包元数据影响，macOS 14 ARM64 即使只连接远程 SeekDB，也无法解析该
extra。不使用 SeekDB 时，这些平台限制不影响 LangBot。

---

# 系统环境设置

Source: https://langbot.app/docs/zh/deploy/settings

完整说明 LangBot config.yaml 的 API、并发、数据库、向量库、存储、插件、MCP、监控与 Box 配置。

LangBot 的运行配置位于 `data/config.yaml`。首次启动会从默认模板生成该文件；下面的示例与 LangBot 仓库中的 [`src/langbot/templates/config.yaml`](https://github.com/langbot-app/LangBot/blob/master/src/langbot/templates/config.yaml) 保持一致。

> info:
>
> 大多数自部署用户只需要关注公网地址、数据库/向量库、对象存储与 Box Runtime。未理解用途的容量和 Cloud 安全上限建议保持默认值。

## 完整默认配置

```yaml
# HTTP API 与 WebUI 配置。
api:
    port: 5300
    webhook_prefix: 'http://127.0.0.1:5300'
    extra_webhook_prefix: ''
    # WebUI 与 API 分开部署时填写浏览器访问来源；OAuth 只信任此值和 webhook_prefix。
    webui_url: ''
    # 全局 API 密钥；留空表示禁用。生产环境请通过环境变量注入并妥善保密。
    global_api_key: ''
# Workspace 相关配置。
workspace:
    # 成员邀请链接与可选邮件发送设置。
    invitations:
        # 邀请链接使用的 WebUI 公网地址；留空时回退到 api.webui_url 和 api.webhook_prefix。
        public_web_url: ''
        # provider 留空时只生成链接；可选 resend 或 smtp。
        email:
            provider: ''
            from: ''
            timeout_seconds: 10
            resend:
                api_url: 'https://api.resend.com/emails'
                api_key: ''
            smtp:
                host: ''
                port: 587
                username: ''
                password: ''
                starttls: true
                ssl: false
# 命令系统、命令前缀与权限映射。
command:
    enable: true
    prefix:
    - '!'
    - ！
    privilege: {}
# 流水线、会话以及排队请求的并发准入上限。
concurrency:
    pipeline: 20
    session: 1
    pending_queries: 1000
    pending_queries_per_workspace: 100
# Webhook 数量与实例级并发请求上限，防止无界排队。
webhooks:
    max_per_workspace: 16
    max_inflight_requests: 16
# Cloud 单个逻辑实例的运行安全上限，不代表套餐权益。
cloud:
    # 超过目录上限的权威更新会整体拒绝，不会静默截断。
    directory:
        max_active_workspaces: 1000
        max_snapshot_workspaces: 1000
        max_snapshot_memberships: 20000
        max_response_bytes: 33554432
# 出站 HTTP/HTTPS 代理。
proxy:
    http: ''
    https: ''
# 实例身份、全局资源限制与运行时保留策略。
system:
    instance_id: ''
    edition: community
    recovery_key: ''
    allow_modify_login_info: true
    disabled_adapters: []
    # 所有 asyncio.to_thread 任务共享的有界线程池。
    blocking_executor:
        max_workers: 8
        max_pending: 128
        max_inflight_per_scope: 4
    # 对外访问 IP；部分机器人平台要求将其加入可信 IP 白名单。
    outbound_ips: []
    # 实例级数量限制；-1 表示不限制。
    limitation:
        max_bots: -1
        max_pipelines: -1
        max_extensions: -1
        max_knowledge_bases: -1
        # SaaS 可强制统一沙箱作用域；普通自部署保持空字符串。
        force_box_session_id_template: ''
    # 异步任务记录、日志与用户主动任务并发限制。
    task_retention:
        completed_limit: 200
        max_log_chars: 200000
        max_active_user_tasks: 256
        max_active_user_tasks_per_workspace: 8
    # 进程内会话缓存限制；这不是持久聊天记录。
    session_retention:
        max_entries: 2000
        max_entries_per_workspace: 200
        idle_ttl_seconds: 86400
        max_conversations_per_session: 20
        max_messages_per_conversation: 100
    # 浏览器连接、Workspace 代理缓存与发送队列上限。
    websocket_retention:
        max_connections: 1024
        max_connections_per_workspace: 32
        max_workspace_proxies: 1024
        max_conversations_per_workspace: 200
        max_messages_per_conversation: 100
        conversation_idle_ttl_seconds: 86400
        send_queue_size: 100
    # 单次上游响应的字符数与流式分块上限。
    response_limits:
        max_generated_chars: 1048576
        max_stream_chunks: 100000
    # JWT 有效期和签名密钥；生产环境必须设置随机密钥。
    jwt:
        expire: 604800
        secret: ''
# 业务数据库配置；可选 sqlite 或 postgresql。
database:
    use: sqlite
    sqlite:
        path: 'data/langbot.db'
    # PostgreSQL 连接池及超时设置。
    postgresql:
        # 非空时优先于拆分字段，并保留 TLS 与查询参数。
        url: ''
        host: '127.0.0.1'
        port: 5432
        user: 'postgres'
        password: 'postgres'
        database: 'postgres'
        pool_size: 10
        max_overflow: 10
        pool_timeout_seconds: 30
        pool_recycle_seconds: 1800
        statement_timeout_ms: 60000
        lock_timeout_ms: 5000
        idle_in_transaction_session_timeout_ms: 60000
    # Cloud 发布迁移的运维级连接配置。
    cloud_migration:
        # 仅填写环境变量名；运维角色必须与运行时角色分离。
        operator_dsn_env: 'LANGBOT_CLOUD_MIGRATION_DSN'
# 向量数据库配置；只需配置 use 选中的后端。
vdb:
    use: chroma
    # 限制进程内集合或索引句柄数量。
    runtime_cache_limit: 1024
    # Qdrant 连接参数。
    qdrant:
        url: ''
        host: localhost
        port: 6333
        api_key: ''
    # SeekDB 是可选功能；源码/包管理器部署需安装 langbot[seekdb] extra。
    # 官方 Docker/Kubernetes 镜像已包含该依赖。
    # 嵌入式模式的平台支持取决于 pylibseekdb wheel。
    seekdb:
        mode: embedded
        path: './data/seekdb'
        database: 'langbot'
        host: 'localhost'
        port: 2881
        user: 'root'
        password: ''
        tenant: ''
    # Milvus 连接参数。
    milvus:
        uri: 'http://127.0.0.1:19530'
        token: ''
        db_name: ''
    # pgvector 可复用业务 PostgreSQL，也可连接独立数据库。
    pgvector:
        use_business_database: false
        # 发布迁移只为这些向量维度创建 ANN 索引。
        allowed_dimensions: [384, 512, 768, 1024, 1536]
        host: '127.0.0.1'
        port: 5433
        database: 'langbot'
        user: 'postgres'
        password: 'postgres'
    # 需要启用 Search 模块的 Valkey 服务。
    valkey_search:
        host: 'localhost'
        port: 6379
        db: 0
        password: ''
        username: ''
        tls: false
        index_algorithm: 'HNSW'
        distance_metric: 'COSINE'
        request_timeout: 5000
# 对象存储、读取上限与定期清理策略。
storage:
    use: local
    # 单次读入 Core 内存的对象大小上限；内置实现硬上限为 64 MiB。
    max_object_read_bytes: 10485760
    # 本地或 S3 上传文件及旧日志的周期清理。
    cleanup:
        enabled: true
        check_interval_hours: 1
        uploaded_file_retention_days: 7
        log_retention_days: 3
        max_files_per_run: 1000
    # S3 连接与同步操作并发限制。
    s3:
        endpoint_url: ''
        access_key_id: ''
        secret_access_key: ''
        region: 'us-east-1'
        bucket: 'langbot-storage'
        max_concurrency: 16
# 插件 Worker 的实例级硬资源上限与准入预算。
plugin:
    enable: true
    runtime_ws_url: 'ws://langbot_plugin_runtime:5400/control/ws'
    enable_marketplace: true
    display_plugin_debug_url: 'ws://localhost:5401/plugin/debug/ws'
    # 插件清单不能提高或覆盖这些限制。
    worker:
        max_cpus: 1.0
        max_memory_mb: 512
        max_pids: 128
        max_open_files: 256
        max_file_size_mb: 512
        max_workers: 16
        max_total_cpus: 8.0
        max_total_memory_mb: 8192
        max_installations: 10000
        max_concurrent_restarts: 1
        restart_failure_threshold: 8
        restart_failure_window_seconds: 30.0
        restart_circuit_open_seconds: 60.0
        require_hard_limits: false
    # 插件二进制存储单值大小限制。
    binary_storage:
        max_value_bytes: 10485760
# MCP 生命周期并发和本地 stdio 传输开关。
mcp:
    # 实例级 MCP 启停并发，硬上限为 128。
    lifecycle_concurrency: 16
    # 关闭后仅禁用本地 stdio MCP，不影响 HTTP/SSE MCP。
    stdio:
        enabled: true
# 监控查询工作量与历史数据清理策略。
monitoring:
    # 限制分页、导出、详情、时序桶和高 offset 查询。
    query_limits:
        page_rows: 1000
        export_rows: 10000
        detail_rows: 2000
        timeseries_buckets: 1000
        max_offset: 1000000
    # 过期监控记录的分批自动清理。
    auto_cleanup:
        enabled: true
        retention_days: 30
        check_interval_hours: 1
        delete_batch_size: 1000
        max_batches_per_table_per_run: 4
# Box 沙箱 Runtime 总配置。
box:
    # 关闭后不连接或启动 Box，并禁用依赖沙箱的工具和 stdio MCP。
    enabled: true
    # 可选 local、docker、nsjail 或 e2b。
    backend: 'local'
    # 外部 WebSocket Runtime 地址；留空时自动管理本地 Runtime。
    runtime:
        endpoint: ''
    # 会话、进程、Workspace 扫描、准入记录和 RPC 文件上限。
    limits:
        max_sessions: 64
        max_managed_processes: 64
        max_completed_processes: 256
        max_workspace_entries: 100000
        max_admission_records: 100000
        max_rpc_file_bytes: 20971520
    # Cloud v2 强制准入与硬配额；普通 OSS 默认关闭。
    admission:
        required: false
        logical_session_id: 'global'
        required_backend: 'nsjail'
        max_sessions: 1
        max_managed_processes: 0
        max_grant_ttl_sec: 300
        max_timeout_sec: 120
        cpus: 1.0
        memory_mb: 512
        pids_limit: 128
        read_only_rootfs: true
        workspace_quota_mb: 0
        readiness_cache_sec: 15
    # 本地工作目录、Skill 目录、挂载根目录与可选磁盘配额。
    local:
        profile: 'default'
        image: ''
        # Docker 部署应改为容器可挂载的绝对宿主机路径。
        host_root: './data/box'
        default_workspace: ''
        skills_root: 'skills'
        allowed_mount_roots:
            - './data/box'
            - '/tmp'
        workspace_quota_mb: null
    # 每个 MCP stdio 进程的默认 nsjail cgroup 内存上限（MiB）。
    default_memory_mb: 1536
    # Docker 沙箱额外设置。
    docker:
        cpu_limit_enabled: true
    # E2B 或自托管兼容服务设置。
    e2b:
        api_key: ''
        api_url: ''
        template: ''
# LangBot Space OAuth、模型网关和遥测设置。
space:
    url: 'https://space.langbot.app'
    models_gateway_api_url: 'https://api.langbot.cloud/v1'
    oauth_authorize_url: 'https://space.langbot.app/auth/authorize'
    disable_models_service: false
    disable_telemetry: false
```

## 配置分组说明

### API、WebUI 与成员邀请

- `api.port`：LangBot HTTP API 与 WebUI 的监听端口，默认 `5300`。
- `api.webhook_prefix`：对外可访问的服务地址，用于生成机器人平台的 Webhook 回调地址；生产环境通常应设置为反向代理后的 HTTPS 域名。
- `api.extra_webhook_prefix`：需要同时展示第二个回调入口时使用，留空即不启用。
- `api.webui_url`：WebUI 与 API 跨域部署时的浏览器端规范来源，例如开发环境的 `http://localhost:3000`。OAuth 回调只信任该配置与 `webhook_prefix`，不会信任请求中的 `Host` 或 `Origin` 请求头。
- `api.global_api_key`：供自动化程序、HTTP Service API 和内置 MCP 服务使用的全局密钥。设置后可通过 `X-API-Key` 或 `Authorization: Bearer` 鉴权，无需登录会话或数据库中的 `lbk_` 密钥；留空表示关闭。
- `workspace.invitations.public_web_url`：邀请链接使用的 WebUI 公网地址；留空时依次回退到 `api.webui_url`、`api.webhook_prefix`。
- `workspace.invitations.email`：可选的邀请邮件发送配置。`provider` 支持 `resend`、`smtp`，留空时只生成邀请链接、不发送邮件。

> warning:
>
> `global_api_key`、JWT 密钥、数据库密码、S3 密钥、Resend/SMTP 密钥和 E2B API Key 都属于敏感信息。生产环境优先使用环境变量注入，不要提交到 Git，也不要通过明文 HTTP 暴露服务。

### 命令、并发与 Webhook 限制

- `command`：控制命令系统是否启用、命令前缀以及权限映射。
- `concurrency.pipeline`：实例同时处理的流水线请求数量；`concurrency.session`：同一会话允许的并发数量。
- `concurrency.pending_queries` 与 `pending_queries_per_workspace`：限制“排队中 + 执行中”的请求总量，防止突发流量形成无限队列。
- `webhooks.max_per_workspace`：每个 Workspace 最多调度的启用 Webhook 数量，硬上限为 `64`。
- `webhooks.max_inflight_requests`：全实例同时发送的 Webhook 请求数，硬上限为 `128`；槽位占满时会快速失败，不会无限积压任务。

### Cloud 目录安全上限

`cloud.directory` 是单个 LangBot Cloud 逻辑实例的**运行安全上限**，不是套餐权益：

- `max_active_workspaces`：允许加载的活跃 Workspace 数量，Core 绝对上限为 `5000`。
- `max_snapshot_workspaces` / `max_snapshot_memberships`：一次签名目录快照允许携带的 Workspace 与成员关系数量。
- `max_response_bytes`：签名控制面响应在验证前允许缓冲的最大字节数，默认 `32 MiB`、绝对上限 `64 MiB`。

超过这些上限的权威目录更新会被整体拒绝，而不是静默截断。普通自部署用户通常不需要修改这一组。

### 系统限制与内存保留

- `system.instance_id`、`edition`、`recovery_key`：实例身份、发行版与恢复信息；除非部署流程明确要求，否则保持默认。
- `system.disabled_adapters`：禁用的消息平台适配器列表。
- `system.blocking_executor`：限制所有 `asyncio.to_thread` 工作共享的线程池、排队任务和单 Workspace 占用，防止阻塞调用拖垮进程。
- `system.limitation`：实例级机器人、流水线、扩展、知识库数量限制；`-1` 表示不限制。`force_box_session_id_template` 用于 SaaS 强制统一沙箱作用域，普通自部署应保持空字符串。
- `task_retention`：异步任务记录、日志字符数和用户主动任务并发上限。
- `session_retention`：进程内会话缓存上限与空闲 TTL；它不是持久聊天记录。
- `websocket_retention`：浏览器连接数、Workspace 代理缓存、对话缓存与发送队列上限。
- `response_limits`：限制单次上游模型响应的字符数和流式分块数。
- `system.jwt.expire` 以秒为单位；生产环境应显式设置不可预测的 `system.jwt.secret`。

### 数据库与向量数据库

- `database.use` 支持 `sqlite` 与 `postgresql`。SQLite 适合单机轻量部署；多实例或较高并发建议使用 PostgreSQL。
- `database.postgresql.url` 非空时优先于拆分的 `host`、`port`、`user`、`password`、`database` 字段，并可保留 TLS 与查询参数。
- PostgreSQL 的 `pool_size`、`max_overflow`、连接池超时与回收参数共同限制连接资源；三个数据库超时字段只应用于 Cloud 运行时连接。
- `database.cloud_migration.operator_dsn_env` 指定 Cloud 发布迁移读取的运维级 DSN 环境变量。运维角色必须与运行时角色分离，密码不要写入配置文件或命令行参数。
- `vdb.use` 选择向量后端。页面列出了 Qdrant、SeekDB、Milvus、pgvector 与 Valkey Search 的连接参数；只需要配置实际选中的后端。
- `vdb.use: seekdb` 在源码部署中要求执行 `uv sync --extra seekdb`，包管理器部署使用 `uvx --from 'langbot[seekdb]@latest' langbot`。官方 Docker/Kubernetes 镜像已包含该依赖，无需额外构建参数。
- `vdb.runtime_cache_limit` 限制进程内集合/索引句柄数量。
- `vdb.pgvector.use_business_database: true` 表示复用 `database.postgresql`；`allowed_dimensions` 限定发布迁移创建 ANN 索引的向量维度。
- `vdb.valkey_search` 需要带 Search 模块的 Valkey 服务，例如 `valkey/valkey-bundle:9.1.0`。连接按需建立，支持 HNSW/FLAT 与 COSINE/L2/IP。

### 存储、插件、MCP 与监控

- `storage.use` 选择本地或 S3 存储；`max_object_read_bytes` 限制一次读入 Core 内存的对象大小，内置 Local/S3 实现的硬上限为 `64 MiB`。
- `storage.cleanup` 控制上传文件与日志的周期清理。`max_files_per_run` 限制一次扫描的文件数，硬上限 `10000`。
- `storage.s3.max_concurrency` 限制委托给工作线程的同步 boto3 操作数量。
- `plugin.worker` 定义所有插件安装都不能突破的 CPU、内存、PID、打开文件、文件大小与全局 Worker 预算；插件清单不能抬高这些上限。重启参数用于抑制 Runtime 重启风暴。
- `plugin.binary_storage.max_value_bytes` 限制单个插件二进制存储值，默认 `10 MiB`。
- `mcp.lifecycle_concurrency` 限制 MCP 启停并发，硬上限 `128`；`mcp.stdio.enabled` 可独立禁用本地 stdio MCP，而不影响 HTTP/SSE MCP。
- `monitoring.query_limits` 限制分页、CSV 导出、详情、时序桶和高 offset 查询在内存/数据库中的工作量。
- `monitoring.auto_cleanup` 控制监控数据保留与分批删除；`max_batches_per_table_per_run` 防止单个 Workspace 的积压长期占用 PostgreSQL。

### Box 沙箱

- `box.enabled` 是总开关。关闭后不会连接或启动 Box Runtime，并禁用原生沙箱工具、Skill 添加/编辑和 stdio MCP；只读 Skill 列表以及 HTTP/SSE MCP 仍可使用。
- `box.backend` 可选 `local`、`docker`、`nsjail`、`e2b`；`box.runtime.endpoint` 用于连接外部 WebSocket Runtime，留空时使用本地自动管理 Runtime。
- `box.limits` 限制会话、托管进程、已完成进程、Workspace 扫描条目、准入记录和 RPC 文件大小。
- `box.admission` 是 Cloud v2 的强制准入与硬资源配额。普通 OSS 默认 `required: false`；流水线、Workspace 权益或工具调用都不能放宽 Runtime 拥有的限制。
- `box.local` 配置本地工作目录、Skill 根目录、允许挂载根目录和可选磁盘配额。Docker 部署时，`host_root` 应使用 Box 容器可挂载的绝对宿主机路径。
- `box.default_memory_mb` 是每个 MCP stdio 进程的默认 nsjail cgroup 内存上限。Node.js MCP 通常比 Python MCP 占用更多内存；过低时常见 `return_code=137`。
- `box.docker.cpu_limit_enabled: false` 只取消 Docker 的 CPU 参数，内存与 PID 限制仍然生效。
- `box.e2b` 用于 E2B 或自托管兼容服务。

### LangBot Space

- `space.url`：Space OAuth 与 API 服务地址。
- `space.models_gateway_api_url`：LangBot MaaS 的 OpenAI 兼容模型网关地址。
- `space.oauth_authorize_url`：OAuth 授权页地址。
- `space.disable_models_service` / `disable_telemetry`：分别关闭 Space 模型服务与遥测上报。

## 通过环境变量设置

任何嵌套配置都可以转换为“大写 + 双下划线”环境变量：

- `API__PORT` → `api.port`
- `WORKSPACE__INVITATIONS__PUBLIC_WEB_URL` → `workspace.invitations.public_web_url`
- `CONCURRENCY__PENDING_QUERIES_PER_WORKSPACE` → `concurrency.pending_queries_per_workspace`
- `DATABASE__POSTGRESQL__POOL_SIZE` → `database.postgresql.pool_size`
- `STORAGE__CLEANUP__MAX_FILES_PER_RUN` → `storage.cleanup.max_files_per_run`
- `PLUGIN__WORKER__MAX_TOTAL_MEMORY_MB` → `plugin.worker.max_total_memory_mb`
- `MCP__STDIO__ENABLED` → `mcp.stdio.enabled`
- `BOX__DEFAULT_MEMORY_MB` → `box.default_memory_mb`

启动时，LangBot 会读取环境变量、应用对应配置，并写入 `data/config.yaml`。

> info:
>
> Docker 部署中，统一把 `BOX__*` 环境变量设置在 `langbot` 服务上。LangBot 会通过 INIT RPC 将 Box 配置传给 `langbot_box`；直接在 `langbot_box` 服务上设置 `LANGBOT_BOX_*` 或 `BOX__*` 不会被读取。

## 可选遥测

遥测默认开启，可以关闭。

在 `data/config.yaml` 的现有 `space` 节点中设置以下值，保留其他配置，然后重启 LangBot：

```yaml
space:
  disable_telemetry: true
```

此开关统一关闭查询统计、心跳和功能执行遥测，也会关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。

如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。

### 单事件执行链路

执行遥测还会计抽样上报单事件链路（一个入站平台事件从来源平台、路由、处理到由此触发的平台 API 调用的全过程）。可在同一 `space` 节点调整抽样：

```yaml
space:
  execution_trace: sampled    # off | failures | sampled | all
  execution_trace_sample: 20  # sampled 模式下：每 N 条成功链路保留一条
```

`failures` 只保留包含失败、取消或超时阶段的链路。`off` 关闭链路上报，窗口计数不受影响。WebUI 调试执行始终保留，并继续标记为模拟执行。链路的保留期限与功能执行记录一致，为 30 天。

参见[数据收集政策](https://langbot.app/docs/zh/insight/data-collection-policy.md)。

---

# 更新 LangBot

Source: https://langbot.app/docs/zh/deploy/update

将 LangBot 更新到最新版本，按步骤安全升级自托管的 AI 聊天机器人平台。

## 使用包管理器部署

请在之前使用包管理器部署的目录下重新执行：

```bash
uvx langbot@latest
```

这将重新下载并启动最新版本的 LangBot。

## 使用 Docker（或基于 Docker 的一键部署）

请在之前 Clone 的 LangBot 目录下执行：

```bash
git pull
```

并在 `docker/` 目录下执行：

```bash
docker compose up --force-recreate --pull always -d
```

此命令将拉取最新的 LangBot 镜像并重建容器。

> info:
>
> 4.3.0 版本更改了 `docker/docker-compose.yaml` 文件的内容和位置，若您由之前版本更新而来，请[根据文档重新部署](https://langbot.app/docs/zh/deploy/langbot/docker.md)。

## 手动部署

从 [Releases](https://github.com/langbot-app/LangBot/releases) 页面下载最新发行版的 Assets 下的 `langbot-<version>-all.zip`，解压到原来部署到目录重启即可。

---

# Discord 适配器 API 参考

Source: https://langbot.app/docs/zh/develop/adapter/discord/api_reference

## 概述

Discord 适配器提供完整的 Discord 平台集成功能，包括消息处理、图像管理、语音连接等。所有功能基于 discord.py 库的原生 API 实现。

## 核心 API

### DiscordAdapter 类

Discord 平台适配器主类，提供与 Discord 平台交互的完整接口。

#### 消息相关方法

##### `send_message(target_type, target_id, message)`

发送消息到指定频道。

**参数:**

- `target_type` (str): 目标类型，通常为 "channel"
- `target_id` (str): 目标频道 ID
- `message` (MessageChain): 要发送的消息链

**功能:**

- 支持文本消息发送
- 支持图像文件批量发送
- 自动处理消息格式转换

**示例:**

```python
# 发送纯文本消息
await adapter.send_message("channel", "123456789", MessageChain([Plain("Hello!")]))

# 发送带图像的消息
message_chain = MessageChain([
    Plain("看看这张图片："),
    Image(path="path/to/image.jpg"),
    Image(url="https://example.com/image.png")
])
await adapter.send_message("channel", "123456789", message_chain)
```

***

##### `reply_message(message_source, message, quote_origin=False)`

回复指定消息。

**参数:**

- `message_source` (MessageEvent): 要回复的原始消息事件
- `message` (MessageChain): 回复内容
- `quote_origin` (bool): 是否引用原消息

**示例:**

```python
# 简单回复
await adapter.reply_message(
    message_event, 
    MessageChain([Plain("收到你的消息了！")])
)

# 引用回复
await adapter.reply_message(
    message_event,
    MessageChain([Plain("这是对你消息的回复")]),
    quote_origin=True
)
```

#### 语音相关方法

##### `join_voice_channel(guild_id, channel_id, user_id=None)`

加入指定的语音频道。

**参数:**

- `guild_id` (int): Discord 服务器 ID
- `channel_id` (int): 语音频道 ID
- `user_id` (int, optional): 请求用户 ID，用于权限验证

**返回值:**

- `discord.VoiceClient`: 语音客户端对象

**异常:**

- `VoicePermissionError`: 权限不足
- `VoiceNetworkError`: 网络连接问题
- `VoiceConnectionError`: 其他连接错误

**示例:**

```python
try:
    voice_client = await adapter.join_voice_channel(
        guild_id=123456789,
        channel_id=987654321,
        user_id=555666777
    )
    print(f"成功连接，延迟: {voice_client.latency*1000:.2f}ms")
except VoicePermissionError as e:
    print(f"权限错误: {e.missing_permissions}")
```

***

##### `leave_voice_channel(guild_id)`

离开指定服务器的语音频道。

**参数:**

- `guild_id` (int): Discord 服务器 ID

**返回值:**

- `bool`: 成功断开返回 `True`

**示例:**

```python
success = await adapter.leave_voice_channel(guild_id=123456789)
if success:
    print("成功离开语音频道")
```

***

##### `get_voice_client(guild_id)`

获取指定服务器的语音客户端对象。

**参数:**

- `guild_id` (int): Discord 服务器 ID

**返回值:**

- `discord.VoiceClient`: 语音客户端对象，如果存在连接
- `None`: 如果没有活跃连接

**示例:**

```python
voice_client = await adapter.get_voice_client(guild_id=123456789)
if voice_client:
    # 播放音频
    import discord
    audio = discord.FFmpegPCMAudio("path/to/audio.mp3")
    voice_client.play(audio)
```

***

##### `is_connected_to_voice(guild_id)`

检查是否连接到指定服务器的语音频道。

**参数:**

- `guild_id` (int): Discord 服务器 ID

**返回值:**

- `bool`: 已连接返回 `True`

**示例:**

```python
if await adapter.is_connected_to_voice(guild_id=123456789):
    print("已连接到语音频道")
```

***

##### `get_voice_connection_status(guild_id)`

获取语音连接的详细状态信息。

**参数:**

- `guild_id` (int): Discord 服务器 ID

**返回值:**

- `dict`: 连接状态信息字典，如果存在连接
- `None`: 如果没有连接

**状态信息结构:**

```python
{
    'guild_id': int,
    'channel_id': int,
    'channel_name': str,
    'connected': bool,
    'connection_time': datetime,
    'last_activity': datetime,
    'status': str,  # VoiceConnectionStatus 枚举值
    'user_count': int,
    'latency': float,
    'connection_health': str
}
```

***

##### `list_active_voice_connections()`

获取所有活跃的语音连接列表。

**返回值:**

- `List[dict]`: 活跃连接状态列表

**示例:**

```python
connections = await adapter.list_active_voice_connections()
for conn in connections:
    print(f"服务器: {conn['guild_id']}, 频道: {conn['channel_name']}")
```

***

##### `get_voice_channel_info(guild_id, channel_id)`

获取指定语音频道的详细信息。

**参数:**

- `guild_id` (int): 服务器 ID
- `channel_id` (int): 频道 ID

**返回值:**

- `dict`: 频道信息字典
- `None`: 如果频道不存在

**频道信息结构:**

```python
{
    'channel_id': int,
    'channel_name': str,
    'guild_id': int,
    'guild_name': str,
    'user_limit': int,
    'current_users': List[dict],
    'user_count': int,
    'bitrate': int,
    'permissions': dict
}
```

#### 管理方法

##### `is_muted(group_id)`

检查群组是否被静音（Discord 适配器始终返回 False）。

**参数:**

- `group_id` (int): 群组 ID

**返回值:**

- `bool`: 是否静音

***

##### `register_listener(event_type, callback)`

注册事件监听器。

**参数:**

- `event_type` (Type\[Event]): 事件类型
- `callback` (Callable): 回调函数

***

##### `unregister_listener(event_type, callback)`

注销事件监听器。

**参数:**

- `event_type` (Type\[Event]): 事件类型
- `callback` (Callable): 回调函数

***

##### `run_async()`

启动 Discord 适配器，建立与 Discord 的连接。

**功能:**

- 初始化语音管理器
- 启动连接监控
- 建立 WebSocket 连接

***

##### `kill()`

关闭 Discord 适配器。

**返回值:**

- `bool`: 是否成功关闭

**功能:**

- 断开所有语音连接
- 关闭 Discord 客户端
- 清理资源

## 消息转换器 API

### DiscordMessageConverter 类

负责在 LangBot 和 Discord 消息格式之间进行转换。

#### `yiri2target(message_chain)`

将 LangBot MessageChain 转换为 Discord 格式。

**参数:**

- `message_chain` (MessageChain): LangBot 消息链

**返回值:**

- `Tuple[str, List[discord.File]]`: (文本内容, 文件列表)

**支持的消息元素:**

- `Plain`: 纯文本内容
- `Image`: 图像内容（支持 base64、URL、文件路径）
- `At`: @ 提及（会被移除）
- `Forward`: 转发消息

**图像处理特性:**

- **Base64 图像**: 自动检测格式并解码
- **URL 图像**: 异步下载并转换
- **文件路径**: 读取本地文件
- **格式检测**: 支持 PNG、JPG、GIF、WebP
- **错误处理**: 跳过无效图像

**示例:**

```python
message_chain = MessageChain([
    Plain("文本内容"),
    Image(base64="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg=="),
    Image(url="https://example.com/image.jpg"),
    Image(path="/path/to/local/image.png")
])

text, files = await DiscordMessageConverter.yiri2target(message_chain)
# text: "文本内容"
# files: [discord.File, discord.File, discord.File]
```

***

#### `target2yiri(message)`

将 Discord 消息转换为 LangBot MessageChain。

**参数:**

- `message` (discord.Message): Discord 消息对象

**返回值:**

- `MessageChain`: LangBot 消息链

**转换规则:**

- 文本内容 → `Plain` 元素
- 附件图像 → `Image` 元素
- 嵌入内容 → `Plain` 元素（描述文本）

## 事件转换器 API

### DiscordEventConverter 类

负责将 Discord 事件转换为 LangBot 平台事件。

#### `target2yiri(message)`

将 Discord 消息转换为 LangBot MessageEvent。

**参数:**

- `message` (discord.Message): Discord 消息对象

**返回值:**

- `MessageEvent`: LangBot 消息事件

**事件字段:**

- `message_chain`: 转换后的消息链
- `sender`: 发送者信息
- `query`: 查询上下文信息

## 异常类

### VoiceConnectionError

基础语音连接异常类。

**属性:**

- `error_code` (str): 错误代码
- `guild_id` (int): 相关服务器 ID
- `timestamp` (datetime): 错误发生时间

**常见错误代码:**

- `"GUILD_NOT_FOUND"`: 服务器不存在
- `"CHANNEL_NOT_FOUND"`: 频道不存在
- `"MANAGER_NOT_READY"`: 语音管理器未初始化
- `"OPUS_NOT_LOADED"`: Opus编码器未加载
- `"UNKNOWN_ERROR"`: 未知错误

### VoicePermissionError

语音权限异常，继承自 `VoiceConnectionError`。

**属性:**

- `missing_permissions` (List\[str]): 缺失的权限列表
- `user_id` (int): 相关用户 ID
- `channel_id` (int): 相关频道 ID

**常见权限错误:**

- `"user_not_in_channel"`: 用户不在语音频道中
- `"member_not_found"`: 找不到用户
- `"connect"`: Bot缺少连接权限
- `"speak"`: Bot缺少发言权限

### VoiceNetworkError

语音网络异常，继承自 `VoiceConnectionError`。

**属性:**

- `retry_count` (int): 重试次数
- `last_attempt` (datetime): 最后尝试时间

## 使用示例

### 综合消息处理

```python
async def handle_complex_message(adapter, channel_id):
    """处理包含多种元素的复杂消息"""
    
    # 构建包含文本和图像的消息
    message_chain = MessageChain([
        Plain("这是一个包含多种内容的消息：\\n"),
        Plain("1. 文本内容\\n"),
        Plain("2. 网络图像\\n"),
        Image(url="https://example.com/image1.jpg"),
        Plain("3. 本地图像\\n"),
        Image(path="/path/to/local/image.png"),
        Plain("4. Base64 图像\\n"),
        Image(base64="data:image/png;base64,iVBORw0KGgo...")
    ])
    
    # 发送消息
    await adapter.send_message("channel", channel_id, message_chain)
```

### 语音播放控制

```python
async def voice_player_example(adapter, guild_id, channel_id, audio_files):
    """语音播放器示例"""
    
    # 连接到语音频道
    try:
        voice_client = await adapter.join_voice_channel(guild_id, channel_id)
    except VoicePermissionError as e:
        print(f"权限不足: {e.missing_permissions}")
        return
    
    # 播放音频队列
    for audio_file in audio_files:
        if voice_client.is_connected():
            # 等待当前播放完成
            while voice_client.is_playing():
                await asyncio.sleep(1)
            
            # 播放下一个音频
            audio_source = discord.FFmpegPCMAudio(audio_file)
            voice_client.play(audio_source)
            print(f"正在播放: {audio_file}")
    
    # 播放完成后离开频道
    await adapter.leave_voice_channel(guild_id)
```

### 状态监控

```python
async def monitor_connections(adapter):
    """监控所有语音连接状态"""
    
    connections = await adapter.list_active_voice_connections()
    
    for conn in connections:
        print(f"服务器: {conn['guild_id']}")
        print(f"频道: {conn['channel_name']}")
        print(f"延迟: {conn['latency']:.2f}ms")
        print(f"用户数: {conn['user_count']}")
        print(f"健康度: {conn['connection_health']}")
        print("---")
```

## 最佳实践

### 错误处理

```python
async def safe_discord_operation():
    try:
        # Discord 操作
        pass
    except VoicePermissionError as e:
        if "user_not_in_channel" in e.missing_permissions:
            await send_error("请先加入语音频道")
        elif "connect" in e.missing_permissions:
            await send_error("机器人没有连接权限")
    except discord.HTTPException as e:
        if e.status == 403:
            await send_error("权限不足")
        elif e.status == 404:
            await send_error("频道不存在")
    except Exception as e:
        await send_error(f"未知错误: {e}")
```

### 资源管理

```python
async def with_voice_connection(adapter, guild_id, channel_id, operation):
    """安全的语音连接管理"""
    voice_client = None
    try:
        voice_client = await adapter.join_voice_channel(guild_id, channel_id)
        await operation(voice_client)
    finally:
        if voice_client:
            await adapter.leave_voice_channel(guild_id)
```

### 图像处理优化

```python
async def batch_image_processing(image_list):
    """批量图像处理"""
    processed_images = []
    
    for image_element in image_list:
        try:
            if image_element.url:
                # 异步下载
                async with aiohttp.ClientSession() as session:
                    async with session.get(image_element.url) as response:
                        image_data = await response.read()
                        processed_images.append(process_image_data(image_data))
            elif image_element.path:
                # 本地文件处理
                with open(image_element.path, 'rb') as f:
                    image_data = f.read()
                    processed_images.append(process_image_data(image_data))
        except Exception as e:
            print(f"图像处理失败: {e}")
            continue
    
    return processed_images
```

***

> **注意**: 本 API 文档基于实际的 discord.py 实现，涵盖了 Discord 适配器的完整功能集。图像处理功能无需额外依赖，语音功能需要安装可选依赖。

---

# Discord 适配器架构设计

Source: https://langbot.app/docs/zh/develop/adapter/discord/design

## 概述

本文档详细描述 LangBot Discord 适配器的架构设计，包括消息处理、图像管理、语音功能等完整系统的设计理念和实现架构。

## 整体架构

### 系统组件图

```mermaid
graph TB
    subgraph "LangBot 框架层"
        A[EventContext] --> B[DiscordAdapter]
        A --> C[MessageEvent]
        A --> D[Plugin System]
    end
    
    subgraph "Discord 适配器层"
        B --> E[DiscordMessageConverter]
        B --> F[DiscordEventConverter]
        B --> G[VoiceConnectionManager]
        B --> H[MyClient]
    end
    
    subgraph "Discord.py 库层"
        H --> I[discord.Client]
        G --> J[discord.VoiceClient]
        E --> K[discord.File]
        I --> L[Discord WebSocket]
        J --> L
    end
    
    subgraph "外部服务"
        L --> M[Discord API]
        N[HTTP Requests] --> O[Image URLs]
        P[Local Files] --> E
        Q[Audio Files] --> J
    end
    
    subgraph "依赖库"
        R[aiohttp] --> N
        S[PyNaCl] --> J
        T[FFmpeg] --> J
    end
```

### 数据流架构

```mermaid
sequenceDiagram
    participant U as User
    participant D as Discord
    participant A as DiscordAdapter
    participant E as EventConverter
    participant M as MessageConverter
    participant P as Plugin
    
    U->>D: 发送消息
    D->>A: Discord Message
    A->>E: target2yiri()
    E->>A: MessageEvent
    A->>P: 事件分发
    P->>A: 回复消息
    A->>M: yiri2target()
    M->>A: Discord格式
    A->>D: 发送回复
    D->>U: 显示回复
```

## 核心组件设计

### 1. DiscordAdapter 主适配器

#### 职责

- **连接管理**: 维护与 Discord 的 WebSocket 连接
- **事件路由**: 将 Discord 事件转换并分发到插件系统
- **消息发送**: 处理外发消息的格式转换和发送
- **语音管理**: 协调语音连接的生命周期
- **资源清理**: 管理连接池和内存资源

#### 核心接口

```python
class DiscordAdapter(MessagePlatformAdapter):
    # 消息相关
    async def send_message(target_type: str, target_id: str, message: MessageChain)
    async def reply_message(message_source: MessageEvent, message: MessageChain, quote_origin: bool)
    
    # 语音相关
    async def join_voice_channel(guild_id: int, channel_id: int, user_id: int) -> VoiceClient
    async def leave_voice_channel(guild_id: int) -> bool
    async def get_voice_client(guild_id: int) -> Optional[VoiceClient]
    
    # 管理相关
    async def run_async()
    async def kill() -> bool
```

#### 设计模式

- **适配器模式**: 将 Discord API 适配到 LangBot 接口
- **单例模式**: 每个 Discord 配置对应一个适配器实例
- **观察者模式**: 事件监听和分发机制

### 2. 消息转换器 (DiscordMessageConverter)

#### 设计目标

- **格式无关**: 屏蔽 Discord 和 LangBot 格式差异
- **类型安全**: 保证消息元素类型转换的正确性
- **性能优化**: 减少不必要的数据复制和转换
- **错误恢复**: 优雅处理格式错误和网络异常

#### 转换策略

##### LangBot → Discord (yiri2target)

```python
转换流程:
MessageChain → 解析元素 → 分类处理 → (text: str, files: List[discord.File])

元素处理策略:
- Plain → 文本累加
- Image → 文件对象创建
- At → 移除处理
- Forward → 递归展开
```

##### Discord → LangBot (target2yiri)

```python
转换流程:
discord.Message → 提取内容 → 构建元素 → MessageChain

内容映射:
- message.content → Plain
- message.attachments → Image
- message.embeds → Plain (description)
```

#### 图像处理架构

```mermaid
graph TD
    A[Image Element] --> B{来源类型}
    B -->|base64| C[Base64 解码]
    B -->|url| D[HTTP 下载]
    B -->|path| E[文件读取]
    
    C --> F[格式检测]
    D --> F
    E --> F
    
    F --> G[文件名生成]
    G --> H[discord.File 创建]
    
    I[错误处理] --> J[跳过无效图像]
    F --> I
    D --> I
    E --> I
```

#### 图像处理特性

- **多源支持**: Base64、URL、本地文件
- **格式智能检测**: 基于内容和元数据
- **异步下载**: 并发处理多个网络图像
- **内存优化**: 使用 BytesIO 避免临时文件
- **错误隔离**: 单个图像失败不影响其他处理

### 3. 语音连接管理器 (VoiceConnectionManager)

#### 设计原则

- **连接复用**: 避免重复连接开销
- **状态一致性**: 维护准确的连接状态
- **权限验证**: 多层次权限检查
- **故障恢复**: 自动重连和清理机制
- **性能监控**: 连接质量实时监控

#### 连接生命周期

```mermaid
stateDiagram-v2
    [*] --> IDLE
    IDLE --> CONNECTING: join_voice_channel()
    CONNECTING --> CONNECTED: 连接成功
    CONNECTING --> FAILED: 连接失败
    CONNECTED --> PLAYING: 播放音频
    PLAYING --> CONNECTED: 播放完成/停止
    CONNECTED --> RECONNECTING: 网络中断
    RECONNECTING --> CONNECTED: 重连成功
    RECONNECTING --> FAILED: 重连失败
    FAILED --> IDLE: 清理资源
    CONNECTED --> IDLE: leave_voice_channel()
    PLAYING --> IDLE: leave_voice_channel()
```

#### 连接池设计

```python
class VoiceConnectionManager:
    connections: Dict[int, VoiceConnectionInfo]  # guild_id -> 连接信息
    
    # 连接管理
    async def join_voice_channel() -> VoiceClient
    async def leave_voice_channel() -> bool
    async def get_connection_status() -> Optional[dict]
    
    # 监控和清理
    async def start_monitoring()
    async def cleanup_inactive_connections()
    async def disconnect_all()
```

#### 权限验证架构

```mermaid
graph TD
    A[连接请求] --> B[用户权限检查]
    B --> C{用户在频道?}
    C -->|否| D[VoicePermissionError]
    C -->|是| E[Bot权限检查]
    E --> F{Connect权限?}
    F -->|否| G[VoicePermissionError]
    F -->|是| H{Speak权限?}
    H -->|否| I[VoicePermissionError]
    H -->|是| J[建立连接]
```

### 4. 事件转换器 (DiscordEventConverter)

#### 转换策略

- **事件映射**: Discord 事件到 LangBot 事件的标准化
- **上下文构建**: 构建完整的事件上下文信息
- **用户信息**: 提取和标准化用户身份信息
- **频道信息**: 处理频道和服务器相关信息

#### 事件转换流程

```python
discord.Message 
└── 提取基础信息 (作者、频道、时间)
└── 转换消息内容 (DiscordMessageConverter)
└── 构建查询对象 (Query)
└── 创建发送者对象 (Sender)
└── 生成 MessageEvent
```

## 异常处理设计

### 异常体系架构

```mermaid
classDiagram
    Exception <|-- VoiceConnectionError
    VoiceConnectionError <|-- VoicePermissionError
    VoiceConnectionError <|-- VoiceNetworkError
    
    class VoiceConnectionError {
        +error_code: str
        +guild_id: int
        +timestamp: datetime
    }
    
    class VoicePermissionError {
        +missing_permissions: List[str]
        +user_id: int
        +channel_id: int
    }
    
    class VoiceNetworkError {
        +retry_count: int
        +last_attempt: datetime
    }
```

### 错误处理策略

- **分层处理**: 不同层次处理不同类型的错误
- **优雅降级**: 单个功能失败不影响整体系统
- **用户友好**: 提供清晰的错误信息和解决建议
- **日志记录**: 完整的错误追踪和调试信息

## 性能设计

### 内存管理

- **连接池**: 复用语音连接减少开销
- **图像缓存**: 临时图像数据及时清理
- **异步处理**: 避免阻塞主事件循环
- **资源限制**: 控制并发连接和文件大小

### 并发设计

- **异步架构**: 全面采用 async/await
- **连接锁**: 防止语音连接竞态条件
- **批量处理**: 图像和消息的批量操作
- **错误隔离**: 单个操作失败不影响其他操作

### 缓存策略

```python
# 连接状态缓存
connections: Dict[int, VoiceConnectionInfo]

# 临时数据缓存
image_cache: Dict[str, bytes]  # URL -> 图像数据
channel_cache: Dict[int, discord.Channel]  # 频道对象缓存
```

## 扩展性设计

### 插件接口

- **标准化事件**: 提供统一的事件接口
- **类型安全**: 强类型的消息元素系统
- **回调机制**: 灵活的事件监听和处理
- **生命周期**: 完整的插件生命周期管理

### 配置管理

```python
# 适配器配置
class DiscordConfig:
    client_id: str
    token: str
    proxy: Optional[str]
    voice_enabled: bool = True
    image_max_size: int = 25 * 1024 * 1024  # 25MB
    max_concurrent_downloads: int = 5
```

### 监控接口

- **连接状态**: 实时语音连接状态
- **性能指标**: 延迟、吞吐量等指标
- **错误统计**: 各类错误的统计和趋势
- **资源使用**: 内存、连接数等资源监控

## 测试设计

### 单元测试架构

```python
# 消息转换测试
class TestDiscordMessageConverter:
    async def test_yiri2target_text()
    async def test_yiri2target_images()
    async def test_target2yiri()

# 语音功能测试
class TestVoiceConnectionManager:
    async def test_join_voice_channel()
    async def test_permission_validation()
    async def test_connection_cleanup()

# 适配器集成测试
class TestDiscordAdapter:
    async def test_message_sending()
    async def test_event_handling()
    async def test_voice_integration()
```

### 模拟测试

- **Mock Discord API**: 模拟 Discord 服务器响应
- **虚拟语音频道**: 测试语音功能无需真实连接
- **错误注入**: 测试各种异常情况的处理
- **性能测试**: 并发和高负载测试

## 部署架构

### 环境要求

- 与LangBot相同

## 监控和维护

### 日志设计

```python
# 分级日志
logger.debug("详细调试信息")
logger.info("一般操作信息")
logger.warning("警告信息")
logger.error("错误信息")
logger.critical("严重错误")

# 结构化日志
{
    "timestamp": "2025-07-04T10:30:00Z",
    "level": "INFO",
    "component": "VoiceConnectionManager",
    "action": "join_voice_channel",
    "guild_id": 123456789,
    "channel_id": 987654321,
    "latency": 45.2,
    "status": "success"
}
```

### 健康检查

- **连接状态**: Discord WebSocket 连接健康度
- **语音质量**: 语音连接延迟和稳定性
- **资源使用**: 内存和连接池状态
- **错误率**: 各类操作的成功率统计

### 故障恢复

- **自动重连**: WebSocket 连接断开后自动重连
- **连接清理**: 定期清理无效的语音连接
- **错误重试**: 网络错误的智能重试机制
- **降级服务**: 语音功能异常时的降级策略

***

> **设计原则**: 本架构设计遵循模块化、可扩展、高性能的原则，确保 Discord 适配器能够稳定、高效地处理各种类型的消息和连接需求。

---

# Discord 适配器快速入门

Source: https://langbot.app/docs/zh/develop/adapter/discord/quick_start

## 概述

本指南将引导您快速上手 LangBot Discord 适配器的完整功能，包括消息处理、图像功能和语音连接等。

## 前置条件

### 环境要求

- Python 3.8+
- LangBot 框架环境
- discord.py、aiohttp（自动安装）
- discord.py\[voice]、PyNaCl、FFmpeg（语音功能可选）

### Discord 设置

本指南假设您已经创建好了 Discord 应用和 Bot。如需创建，请访问 [Discord Developer Portal](https://discord.com/developers/applications)。

## 基本使用

### 1. 文本消息处理

```python
from pkg.platform.types import message as platform_message
from pkg.platform.types import events as platform_events

@handler(platform_events.MessageEvent)
async def text_message_handler(ctx: EventContext):
    """处理文本消息的基本示例"""
    
    # 获取适配器实例
    adapter = ctx.event.query.adapter
    
    # 提取消息文本
    text_content = ""
    for element in ctx.event.message_chain:
        if isinstance(element, platform_message.Plain):
            text_content += element.text
    
    # 发送回复
    reply_chain = platform_message.MessageChain([
        platform_message.Plain(f"您说了: {text_content}")
    ])
    
    await adapter.reply_message(ctx.event, reply_chain, quote_origin=True)
```

### 2. 图像消息处理

```python
@handler(platform_events.MessageEvent)
async def image_message_handler(ctx: EventContext):
    """处理图像消息的示例"""
    
    adapter = ctx.event.query.adapter
    
    # 检测消息中的图像
    image_count = 0
    for element in ctx.event.message_chain:
        if isinstance(element, platform_message.Image):
            image_count += 1
    
    if image_count > 0:
        # 回复图像信息
        reply_chain = platform_message.MessageChain([
            platform_message.Plain(f"收到 {image_count} 张图片！"),
            platform_message.Plain("\\n正在处理...")
        ])
        await adapter.reply_message(ctx.event, reply_chain)
        
        # 可以添加图像处理逻辑
        # processed_image = process_images(images)
        
        # 发送处理结果
        result_chain = platform_message.MessageChain([
            platform_message.Plain("处理完成！"),
            # platform_message.Image(path="path/to/processed/image.jpg")
        ])
        await adapter.send_message("channel", ctx.event.query.channel_id, result_chain)
```

### 3. 发送不同类型的图像

```python
async def send_various_images(adapter, channel_id):
    """发送不同来源的图像示例"""
    
    message_chain = platform_message.MessageChain([
        platform_message.Plain("以下是不同类型的图像：\\n"),
        
        # 本地文件图像
        platform_message.Plain("1. 本地文件：\\n"),
        platform_message.Image(path="/path/to/local/image.jpg"),
        
        # 网络图像
        platform_message.Plain("\\n2. 网络图像：\\n"),
        platform_message.Image(url="https://example.com/image.png"),
        
        # Base64 图像
        platform_message.Plain("\\n3. Base64 图像：\\n"),
        platform_message.Image(base64="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==")
    ])
    
    await adapter.send_message("channel", channel_id, message_chain)
```

## 语音功能使用

### 语音连接管理

```python
@handler(platform_events.MessageEvent)
async def voice_connect_handler(ctx: EventContext):
    """语音连接示例"""
    
    adapter = ctx.event.query.adapter
    
    # 解析指令
    text = ""
    for element in ctx.event.message_chain:
        if isinstance(element, platform_message.Plain):
            text += element.text
    
    if "加入语音" in text:
        try:
            # 这里需要根据实际情况获取 guild_id 和 channel_id
            guild_id = get_guild_id_from_context(ctx)
            channel_id = get_voice_channel_id_from_user(ctx.event.sender.id, guild_id)
            
            voice_client = await adapter.join_voice_channel(
                guild_id=guild_id,
                channel_id=channel_id,
                user_id=ctx.event.sender.id
            )
            
            await ctx.reply("成功加入语音频道！")
            
        except VoicePermissionError as e:
            if "user_not_in_channel" in e.missing_permissions:
                await ctx.reply("请先加入语音频道")
            elif "connect" in e.missing_permissions:
                await ctx.reply("机器人没有连接权限")
            else:
                await ctx.reply(f"权限错误: {', '.join(e.missing_permissions)}")
                
        except Exception as e:
            await ctx.reply(f"连接失败: {e}")
    
    elif "离开语音" in text:
        guild_id = get_guild_id_from_context(ctx)
        success = await adapter.leave_voice_channel(guild_id)
        
        if success:
            await ctx.reply("已离开语音频道")
        else:
            await ctx.reply("未连接到语音频道")
```

### 音频播放

```python
@handler(platform_events.MessageEvent)
async def audio_play_handler(ctx: EventContext):
    """音频播放示例"""
    
    adapter = ctx.event.query.adapter
    
    # 检查是否有播放音频的指令
    text = extract_text_from_message(ctx.event.message_chain)
    
    if "播放音频" in text:
        guild_id = get_guild_id_from_context(ctx)
        
        # 获取语音客户端
        voice_client = await adapter.get_voice_client(guild_id)
        
        if not voice_client:
            await ctx.reply("请先连接到语音频道")
            return
        
        if voice_client.is_playing():
            await ctx.reply("正在播放其他音频，请稍候")
            return
        
        try:
            # 播放音频文件
            import discord
            
            # 配置 FFmpeg 选项
            ffmpeg_options = {
                'before_options': '-loglevel quiet',
                'options': '-vn -filter:a "volume=0.5"'
            }
            
            # 创建音频源
            audio_source = discord.FFmpegPCMAudio(
                "path/to/your/audio.mp3",
                **ffmpeg_options
            )
            
            # 开始播放
            voice_client.play(audio_source)
            await ctx.reply("开始播放音频")
            
        except Exception as e:
            await ctx.reply(f"播放失败: {e}")
    
    elif "停止播放" in text:
        guild_id = get_guild_id_from_context(ctx)
        voice_client = await adapter.get_voice_client(guild_id)
        
        if voice_client and voice_client.is_playing():
            voice_client.stop()
            await ctx.reply("已停止播放")
        else:
            await ctx.reply("当前没有播放音频")
```

### 语音状态查询

```python
@handler(platform_events.MessageEvent)
async def voice_status_handler(ctx: EventContext):
    """语音状态查询示例"""
    
    adapter = ctx.event.query.adapter
    text = extract_text_from_message(ctx.event.message_chain)
    
    if "语音状态" in text:
        guild_id = get_guild_id_from_context(ctx)
        
        # 获取详细状态
        status = await adapter.get_voice_connection_status(guild_id)
        
        if status:
            status_text = f"""语音连接状态:
                频道: {status['channel_name']}
                连接时间: {status['connection_time'].strftime('%H:%M:%S')}
                延迟: {status['latency']:.2f}ms
                用户数: {status['user_count']}
                健康度: {status['connection_health']}
                状态: {status['status']}"""
            
            await ctx.reply(status_text)
        else:
            await ctx.reply("当前未连接到语音频道")
    
    elif "连接列表" in text:
        # 获取所有活跃连接
        connections = await adapter.list_active_voice_connections()
        
        if connections:
            conn_list = "活跃语音连接:\\n"
            for i, conn in enumerate(connections, 1):
                conn_list += f"{i}. {conn['channel_name']} ({conn['user_count']} 用户)\\n"
            await ctx.reply(conn_list)
        else:
            await ctx.reply("当前没有活跃的语音连接")
```

## 完整插件示例

以下是一个完整的 Discord 插件示例，包含所有主要功能：

```python
import asyncio
import os
from pkg.platform.types import message as platform_message
from pkg.platform.types import events as platform_events
from pkg.core.entities.classes import EventContext
from pkg.plugin import handler

# 辅助函数
def extract_text_from_message(message_chain):
    """从消息链中提取文本"""
    text = ""
    for element in message_chain:
        if isinstance(element, platform_message.Plain):
            text += element.text
    return text.strip()

def extract_images_from_message(message_chain):
    """从消息链中提取图像"""
    images = []
    for element in message_chain:
        if isinstance(element, platform_message.Image):
            images.append(element)
    return images

# 消息处理器
@handler(platform_events.MessageEvent)
async def discord_message_handler(ctx: EventContext):
    """Discord 消息处理主函数"""
    
    adapter = ctx.event.query.adapter
    text = extract_text_from_message(ctx.event.message_chain)
    images = extract_images_from_message(ctx.event.message_chain)
    
    # 文本处理
    if text.startswith("!echo"):
        echo_text = text[5:].strip()
        await ctx.reply(f"回声: {echo_text}")
    
    # 图像处理
    elif text.startswith("!image"):
        if images:
            reply_chain = platform_message.MessageChain([
                platform_message.Plain(f"检测到 {len(images)} 张图像"),
                platform_message.Plain("\\n图像信息:\\n")
            ])
            
            for i, img in enumerate(images, 1):
                if img.url:
                    reply_chain.append(platform_message.Plain(f"{i}. 网络图像: {img.url}\\n"))
                elif img.path:
                    reply_chain.append(platform_message.Plain(f"{i}. 本地图像: {os.path.basename(img.path)}\\n"))
                elif img.base64:
                    reply_chain.append(platform_message.Plain(f"{i}. Base64 图像\\n"))
            
            await ctx.reply(reply_chain)
        else:
            await ctx.reply("请发送图像")
    
    # 语音功能
    elif text.startswith("!voice"):
        await handle_voice_command(ctx, text[6:].strip())
    
    # 帮助信息
    elif text.startswith("!help"):
        help_text = """Discord 插件命令:
            !echo <文本> - 回声功能
            !image - 分析图像信息
            !voice join - 加入语音频道
            !voice leave - 离开语音频道
            !voice play <文件> - 播放音频
            !voice stop - 停止播放
            !voice status - 查看状态
            !help - 显示此帮助"""
        await ctx.reply(help_text)

async def handle_voice_command(ctx: EventContext, command: str):
    """处理语音相关命令"""
    
    adapter = ctx.event.query.adapter
    guild_id = get_guild_id_from_context(ctx)
    
    if command == "join":
        try:
            channel_id = get_user_voice_channel_id(ctx.event.sender.id, guild_id)
            if not channel_id:
                await ctx.reply("请先加入语音频道")
                return
            
            voice_client = await adapter.join_voice_channel(
                guild_id=guild_id,
                channel_id=channel_id,
                user_id=ctx.event.sender.id
            )
            
            await ctx.reply("成功加入语音频道！")
            
        except Exception as e:
            await ctx.reply(f"加入失败: {e}")
    
    elif command == "leave":
        success = await adapter.leave_voice_channel(guild_id)
        if success:
            await ctx.reply("已离开语音频道")
        else:
            await ctx.reply("未连接到语音频道")
    
    elif command.startswith("play"):
        audio_file = command[4:].strip()
        if not audio_file:
            audio_file = "path/to/default/audio.mp3"
        
        voice_client = await adapter.get_voice_client(guild_id)
        if not voice_client:
            await ctx.reply("请先加入语音频道")
            return
        
        if voice_client.is_playing():
            await ctx.reply("正在播放其他音频")
            return
        
        try:
            import discord
            audio_source = discord.FFmpegPCMAudio(audio_file)
            voice_client.play(audio_source)
            await ctx.reply(f"开始播放: {os.path.basename(audio_file)}")
        except Exception as e:
            await ctx.reply(f"播放失败: {e}")
    
    elif command == "stop":
        voice_client = await adapter.get_voice_client(guild_id)
        if voice_client and voice_client.is_playing():
            voice_client.stop()
            await ctx.reply("已停止播放")
        else:
            await ctx.reply("当前没有播放音频")
    
    elif command == "status":
        status = await adapter.get_voice_connection_status(guild_id)
        if status:
            status_text = f"""语音状态:
                频道: {status['channel_name']}
                延迟: {status['latency']:.2f}ms
                用户数: {status['user_count']}
                状态: {status['status']}"""
            await ctx.reply(status_text)
        else:
            await ctx.reply("未连接到语音频道")
    
    else:
        await ctx.reply("未知的语音命令，使用 !help 查看帮助")

# 辅助函数实现（需要根据实际情况调整）
def get_guild_id_from_context(ctx):
    """从上下文获取 guild_id"""
    # 这里需要根据实际的 LangBot 实现来获取 guild_id
    # 可能需要从 ctx.event.query 或其他地方获取
    return ctx.event.query.channel_id  # 示例实现

def get_user_voice_channel_id(user_id, guild_id):
    """获取用户当前所在的语音频道 ID"""
    # 这里需要实现获取用户语音频道的逻辑
    # 可能需要通过 Discord API 查询
    return None  # 示例实现，实际需要实现具体逻辑
```

## 错误处理最佳实践

### 语音错误处理

```python
async def safe_voice_operation(adapter, operation, *args, **kwargs):
    """安全的语音操作包装器"""
    try:
        return await operation(*args, **kwargs)
    except VoicePermissionError as e:
        if "user_not_in_channel" in e.missing_permissions:
            return "错误: 用户不在语音频道中"
        elif "connect" in e.missing_permissions:
            return "错误: 机器人没有连接权限"
        elif "speak" in e.missing_permissions:
            return "错误: 机器人没有发言权限"
        else:
            return f"权限错误: {', '.join(e.missing_permissions)}"
    except VoiceNetworkError as e:
        return f"网络错误: {e}"
    except Exception as e:
        return f"未知错误: {e}"
```

### 图像错误处理

```python
async def safe_image_processing(message_chain):
    """安全的图像处理"""
    processed_images = []
    errors = []
    
    for element in message_chain:
        if isinstance(element, platform_message.Image):
            try:
                # 处理图像
                if element.url:
                    # 处理网络图像
                    pass
                elif element.path:
                    # 处理本地图像
                    if not os.path.exists(element.path):
                        errors.append(f"文件不存在: {element.path}")
                        continue
                elif element.base64:
                    # 处理 Base64 图像
                    pass
                
                processed_images.append(element)
                
            except Exception as e:
                errors.append(f"图像处理失败: {e}")
    
    return processed_images, errors
```

## 性能优化建议

### 异步图像下载

```python
import aiohttp
import asyncio

async def download_images_concurrently(image_urls, max_concurrent=5):
    """并发下载多张图像"""
    semaphore = asyncio.Semaphore(max_concurrent)
    
    async def download_single(session, url):
        async with semaphore:
            try:
                async with session.get(url) as response:
                    return await response.read()
            except Exception as e:
                print(f"下载失败 {url}: {e}")
                return None
    
    async with aiohttp.ClientSession() as session:
        tasks = [download_single(session, url) for url in image_urls]
        return await asyncio.gather(*tasks)
```

### 语音连接复用

```python
class VoiceConnectionPool:
    """语音连接池管理"""
    
    def __init__(self, adapter):
        self.adapter = adapter
        self.connections = {}
    
    async def get_connection(self, guild_id, channel_id, user_id=None):
        """获取或创建语音连接"""
        if guild_id in self.connections:
            # 检查现有连接是否有效
            if await self.adapter.is_connected_to_voice(guild_id):
                return self.connections[guild_id]
        
        # 创建新连接
        voice_client = await self.adapter.join_voice_channel(
            guild_id, channel_id, user_id
        )
        self.connections[guild_id] = voice_client
        return voice_client
    
    async def cleanup_invalid_connections(self):
        """清理无效连接"""
        invalid_guilds = []
        for guild_id in self.connections:
            if not await self.adapter.is_connected_to_voice(guild_id):
                invalid_guilds.append(guild_id)
        
        for guild_id in invalid_guilds:
            del self.connections[guild_id]
```

***

> **提示**: 此快速入门基于实际的 discord.py 实现。建议在开发过程中参考 [Discord Developer Documentation](https://discord.com/developers/docs) 了解更多 Discord API 详情。

---

# Discord 适配器文档

Source: https://langbot.app/docs/zh/develop/adapter/discord/README

## 概述

这是 LangBot 平台的 Discord 适配器完整文档，基于 discord.py 库实现了与 Discord 平台的全面集成，包括文本消息、图像处理、语音功能等完整功能集。

## 文档导航

### 核心文档

- **[API 参考](https://langbot.app/docs/zh/develop/adapter/discord/api_reference.md)** - Discord 适配器完整 API 文档
- **[快速开始](https://langbot.app/docs/zh/develop/adapter/discord/quick_start.md)** - 基本使用指南
- **[架构设计](https://langbot.app/docs/zh/develop/adapter/discord/design.md)** - 适配器架构设计
- **[故障排除](https://langbot.app/docs/zh/develop/adapter/discord/troubleshooting.md)** - 常见问题解决方案

## 完整功能集

### 消息处理

- 文本消息发送和接收
- 图像消息处理（支持多种格式）
- 消息引用和回复
- At 功能支持
- 转发消息处理

### 图像功能

- 多格式图像支持（PNG、JPG、GIF、WebP）
- Base64 编码图像处理
- URL 图像下载和转换
- 本地文件图像读取
- 自动文件类型检测
- 批量图像发送

### 语音功能

- 语音频道连接管理
- 音频播放控制
- 连接状态监控
- 权限验证系统
- 自动连接清理

### 事件系统

- 消息事件处理
- 用户状态监控
- 频道状态变化
- Bot 生命周期管理

## 快速开始

### 环境要求

- **LangBot**: 框架环境

## 系统架构

### 核心组件

```mermaid
graph TD
    A[Discord Adapter] --> B[DiscordAdapter]
    A --> C[DiscordMessageConverter]
    A --> D[DiscordEventConverter]
    A --> E[VoiceConnectionManager]
    A --> F[MyClient]
    
    B --> G[消息发送/接收]
    C --> H[格式转换]
    D --> I[事件处理]
    E --> J[语音连接]
    F --> K[Discord API]
```

### 消息处理流程

```mermaid
sequenceDiagram
    participant U as Discord User
    participant D as Discord API
    participant A as DiscordAdapter
    participant E as EventConverter
    participant P as Plugin
    participant M as MessageConverter
    
    U->>D: 发送消息
    D->>A: Discord Message
    A->>E: target2yiri()
    E->>P: MessageEvent
    P->>A: 回复请求
    A->>M: yiri2target()
    M->>D: Discord 格式
    D->>U: 显示回复
```

### 图像处理流程

```mermaid
graph TD
    A[Image Element] --> B{图像来源}
    B -->|base64| C[Base64 解码]
    B -->|url| D[HTTP 下载]
    B -->|path| E[文件读取]
    
    C --> F[格式检测]
    D --> F
    E --> F
    
    F --> G[文件名生成]
    G --> H[discord.File 创建]
    H --> I[上传到 Discord]
```

### 语音处理流程

```mermaid
graph TD
    A[语音指令] --> B[权限检查]
    B --> C{用户在频道?}
    C -->|否| D[权限错误]
    C -->|是| E[Bot权限检查]
    E --> F{有连接权限?}
    F -->|否| D
    F -->|是| G[建立连接]
    G --> H[音频处理]
    H --> I[Discord Voice API]
```

## 核心特性详解

### 消息转换器 (DiscordMessageConverter)

负责在 LangBot 内部消息格式和 Discord API 格式之间进行转换：

- **yiri2target**: 将 LangBot MessageChain 转换为 Discord 格式
- **target2yiri**: 将 Discord 消息转换为 LangBot 格式
- 支持文本、图像、转发消息等多种类型

### 图像处理特性

- **多源支持**: Base64、URL、本地文件路径
- **格式检测**: 自动检测 PNG、JPG、GIF、WebP 格式
- **智能命名**: 基于内容和来源的文件命名
- **错误处理**: 优雅处理无效图像和网络错误
- **批量处理**: 单次消息支持多张图像

### 语音连接管理器 (VoiceConnectionManager)

提供完整的语音功能管理：

- **连接池管理**: 多服务器连接状态跟踪
- **权限验证**: 用户和机器人权限检查
- **状态监控**: 连接健康度和延迟监控
- **异常处理**: 分类的异常体系
- **自动清理**: 定期清理无效连接

### 事件系统

- **消息事件**: 处理用户消息和机器人响应
- **状态监控**: 跟踪连接状态变化
- **生命周期**: 管理适配器启动和关闭

## 权限配置

Bot 需要以下 Discord 权限：

- **基础权限**:
  - Read Messages
  - Send Messages
  - Embed Links
  - Attach Files
  - Read Message History

- **语音权限**:
  - Connect
  - Speak
  - Use Voice Activity

***

> **注意**: 本文档基于实际的 discord.py 实现，涵盖了 Discord 适配器的完整功能集。语音功能需要额外的依赖安装，图像功能支持多种来源和格式。详细的使用方法和故障排除请参考其他专门文档。

---

# Discord 适配器故障排除

Source: https://langbot.app/docs/zh/develop/adapter/discord/troubleshooting

## 概述

本文档提供 Discord 适配器常见问题的诊断和解决方案，涵盖连接问题、消息处理、图像功能、语音连接等各个方面。

## 连接相关问题

### 1. 无法启动 Discord 适配器

#### 症状

- 适配器启动失败
- 连接超时错误
- 认证失败

#### 可能原因和解决方案

##### 1.1 Token 配置错误

```python
# 错误信息示例
discord.errors.LoginFailure: Improper token has been passed.

# 解决方案
1. 检查配置文件中的 token 是否正确
2. 确认 token 没有包含额外的空格或特殊字符
3. 验证 token 是否仍然有效

# 验证 token 的方法
import aiohttp
import asyncio

async def verify_token(token):
    headers = {'Authorization': f'Bot {token}'}
    async with aiohttp.ClientSession() as session:
        async with session.get('https://discord.com/api/v10/users/@me', headers=headers) as response:
            if response.status == 200:
                print("Token 有效")
                data = await response.json()
                print(f"Bot 用户名: {data['username']}")
            else:
                print(f"Token 无效: {response.status}")
```

##### 1.2 网络连接问题

```python
# 错误信息示例
aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host discord.com

# 解决方案
1. 检查网络连接
2. 配置代理（如果需要）
3. 检查防火墙设置

# 代理配置示例
export http_proxy="http://proxy.example.com:8080"
export https_proxy="http://proxy.example.com:8080"

# 或在代码中设置
import os
os.environ['http_proxy'] = 'http://proxy.example.com:8080'
```

##### 1.3 权限配置问题

```python
# 确保 Bot 具有必要权限
required_permissions = [
    'Read Messages',
    'Send Messages', 
    'Embed Links',
    'Attach Files',
    'Read Message History'
]

# 语音功能额外权限
voice_permissions = [
    'Connect',
    'Speak',
    'Use Voice Activity'
]
```

### 2. 连接频繁断开

#### 症状

- WebSocket 连接频繁中断
- 消息发送失败
- 事件接收延迟

#### 解决方案

```python
# 启用详细日志查看连接状态
import logging
logging.basicConfig(level=logging.DEBUG)

# 检查网络稳定性
async def network_stability_test():
    import aiohttp
    import asyncio
    
    for i in range(10):
        try:
            async with aiohttp.ClientSession() as session:
                start_time = asyncio.get_event_loop().time()
                async with session.get('https://discord.com/api/v10/gateway') as response:
                    end_time = asyncio.get_event_loop().time()
                    latency = (end_time - start_time) * 1000
                    print(f"测试 {i+1}: {response.status}, 延迟: {latency:.2f}ms")
        except Exception as e:
            print(f"测试 {i+1} 失败: {e}")
        
        await asyncio.sleep(1)
```

## 消息处理问题

### 1. 消息发送失败

#### 症状

- 发送消息时抛出异常
- 消息内容被截断
- 消息格式错误

#### 常见问题和解决方案

##### 1.1 消息长度超限

```python
# Discord 消息长度限制: 2000 字符
def check_message_length(text):
    if len(text) > 2000:
        print(f"消息过长: {len(text)} 字符，需要分割")
        return False
    return True

# 自动分割长消息
def split_long_message(text, max_length=2000):
    chunks = []
    while len(text) > max_length:
        # 找到合适的分割点
        split_pos = text.rfind('\n', 0, max_length)
        if split_pos == -1:
            split_pos = text.rfind(' ', 0, max_length)
        if split_pos == -1:
            split_pos = max_length
        
        chunks.append(text[:split_pos])
        text = text[split_pos:].lstrip()
    
    if text:
        chunks.append(text)
    
    return chunks

# 使用示例
async def send_long_message(adapter, channel_id, long_text):
    chunks = split_long_message(long_text)
    for chunk in chunks:
        await adapter.send_message("channel", channel_id, MessageChain([Plain(chunk)]))
        await asyncio.sleep(0.5)  # 避免速率限制
```

##### 1.2 频道权限不足

```python
# 检查 Bot 在频道中的权限
async def check_channel_permissions(bot, channel_id):
    try:
        channel = bot.get_channel(channel_id)
        if not channel:
            channel = await bot.fetch_channel(channel_id)
        
        permissions = channel.permissions_for(channel.guild.me)
        
        required_perms = {
            'send_messages': permissions.send_messages,
            'embed_links': permissions.embed_links,
            'attach_files': permissions.attach_files,
            'read_messages': permissions.read_messages
        }
        
        print("频道权限检查:")
        for perm, has_perm in required_perms.items():
            status = "✓" if has_perm else "✗"
            print(f"  {status} {perm}: {has_perm}")
        
        return all(required_perms.values())
        
    except Exception as e:
        print(f"权限检查失败: {e}")
        return False
```

### 2. 消息接收问题

#### 症状

- 收不到用户消息
- 事件处理延迟
- 消息内容缺失

#### 解决方案

```python
# 检查 Intents 配置
import discord

# 确保启用了必要的 intents
intents = discord.Intents.default()
intents.message_content = True  # 必须启用才能读取消息内容
intents.guild_messages = True
intents.dm_messages = True

# 在 Discord Developer Portal 中也需要启用对应的 Privileged Gateway Intents

# 调试消息接收
class DebugClient(discord.Client):
    async def on_message(self, message):
        print(f"收到消息: {message.author} -> {message.content}")
        if message.author.bot:
            print("跳过 Bot 消息")
            return
        
        # 处理消息...
```

## 图像处理问题

### 1. 图像发送失败

#### 症状

- 图像无法上传
- 图像格式错误
- 文件大小超限

#### 解决方案

##### 1.1 文件大小检查

```python
import os

def check_image_size(image_path, max_size=25*1024*1024):  # 25MB 限制
    """检查图像文件大小"""
    if not os.path.exists(image_path):
        return False, "文件不存在"
    
    size = os.path.getsize(image_path)
    if size > max_size:
        return False, f"文件过大: {size/1024/1024:.2f}MB, 限制: {max_size/1024/1024}MB"
    
    return True, "文件大小正常"

# 图像压缩示例
from PIL import Image
import io

def compress_image(image_path, max_size=1024, quality=85):
    """压缩图像以减小文件大小"""
    try:
        with Image.open(image_path) as img:
            # 调整尺寸
            if max(img.size) > max_size:
                ratio = max_size / max(img.size)
                new_size = tuple(int(dim * ratio) for dim in img.size)
                img = img.resize(new_size, Image.Resampling.LANCZOS)
            
            # 保存为 JPEG 以减小文件大小
            output = io.BytesIO()
            img.convert('RGB').save(output, format='JPEG', quality=quality, optimize=True)
            return output.getvalue()
    
    except Exception as e:
        print(f"图像压缩失败: {e}")
        return None
```

##### 1.2 格式检测和转换

```python
def detect_image_format(image_data):
    """检测图像格式"""
    if image_data.startswith(b'\xff\xd8\xff'):
        return 'jpeg'
    elif image_data.startswith(b'\x89PNG\r\n\x1a\n'):
        return 'png'
    elif image_data.startswith(b'GIF87a') or image_data.startswith(b'GIF89a'):
        return 'gif'
    elif image_data.startswith(b'RIFF') and b'WEBP' in image_data[:20]:
        return 'webp'
    else:
        return 'unknown'

# 安全的图像读取
async def safe_image_processing(image_element):
    """安全地处理图像元素"""
    try:
        image_data = None
        filename = f'{uuid.uuid4()}.png'
        
        if image_element.base64:
            # 处理 Base64 图像
            if image_element.base64.startswith('data:'):
                base64_data = image_element.base64.split(',')[1]
            else:
                base64_data = image_element.base64
            
            image_data = base64.b64decode(base64_data)
            
        elif image_element.url:
            # 下载网络图像
            async with aiohttp.ClientSession() as session:
                async with session.get(image_element.url, timeout=30) as response:
                    if response.status == 200:
                        image_data = await response.read()
                    else:
                        raise Exception(f"下载失败: HTTP {response.status}")
                        
        elif image_element.path:
            # 读取本地文件
            clean_path = os.path.abspath(image_element.path.replace('\x00', ''))
            if os.path.exists(clean_path):
                with open(clean_path, 'rb') as f:
                    image_data = f.read()
            else:
                raise Exception(f"文件不存在: {clean_path}")
        
        if image_data:
            # 检测格式并设置文件名
            format_name = detect_image_format(image_data)
            if format_name != 'unknown':
                filename = f'{uuid.uuid4()}.{format_name}'
            
            # 检查文件大小
            if len(image_data) > 25*1024*1024:  # 25MB
                raise Exception(f"图像过大: {len(image_data)/1024/1024:.2f}MB")
            
            return discord.File(fp=io.BytesIO(image_data), filename=filename)
        
    except Exception as e:
        print(f"图像处理失败: {e}")
        return None
```

### 2. 网络图像下载问题

#### 症状

- 图像下载超时
- 网络连接错误
- 图像内容损坏

#### 解决方案

```python
async def robust_image_download(url, max_retries=3, timeout=30):
    """健壮的图像下载"""
    
    for attempt in range(max_retries):
        try:
            async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=timeout)) as session:
                async with session.get(url, headers={'User-Agent': 'LangBot/1.0'}) as response:
                    if response.status == 200:
                        content_length = response.headers.get('Content-Length')
                        if content_length and int(content_length) > 25*1024*1024:
                            raise Exception("图像文件过大")
                        
                        image_data = await response.read()
                        
                        # 验证图像数据
                        if len(image_data) < 100:  # 太小可能不是有效图像
                            raise Exception("图像数据太小")
                        
                        # 检查格式
                        if detect_image_format(image_data) == 'unknown':
                            raise Exception("不支持的图像格式")
                        
                        return image_data
                    else:
                        raise Exception(f"HTTP错误: {response.status}")
                        
        except asyncio.TimeoutError:
            print(f"下载超时 (尝试 {attempt + 1}/{max_retries}): {url}")
        except Exception as e:
            print(f"下载失败 (尝试 {attempt + 1}/{max_retries}): {e}")
        
        if attempt < max_retries - 1:
            await asyncio.sleep(2 ** attempt)  # 指数退避
    
    raise Exception(f"下载失败，已重试 {max_retries} 次")
```

## 语音功能问题

### 1. 语音连接失败

#### 症状

- 无法加入语音频道
- 连接超时
- 权限错误

#### 解决方案

##### 1.1 依赖检查

```python
def check_voice_dependencies():
    """检查语音功能依赖"""
    try:
        import discord.voice_client
        print("✓ discord.py 语音支持正常")
    except ImportError:
        print("✗ discord.py 语音支持未安装，请运行: pip install discord.py[voice]")
        return False
    
    try:
        import nacl
        print("✓ PyNaCl 已安装")
    except ImportError:
        print("✗ PyNaCl 未安装，请运行: pip install PyNaCl")
        return False
    
    # 检查 FFmpeg
    import shutil
    if shutil.which('ffmpeg'):
        print("✓ FFmpeg 已安装")
    else:
        print("✗ FFmpeg 未安装，请安装 FFmpeg")
        return False
    
    try:
        import discord
        if not discord.opus.is_loaded():
            discord.opus.load_opus()
        print("✓ Opus 编码器已加载")
    except Exception as e:
        print(f"✗ Opus 编码器加载失败: {e}")
        return False
    
    return True
```

##### 1.2 权限诊断

```python
async def diagnose_voice_permissions(bot, guild_id, channel_id, user_id):
    """诊断语音权限问题"""
    try:
        guild = bot.get_guild(guild_id)
        if not guild:
            return "错误: 找不到服务器"
        
        channel = guild.get_channel(channel_id)
        if not channel or not isinstance(channel, discord.VoiceChannel):
            return "错误: 找不到语音频道"
        
        # 检查用户是否在频道中
        member = guild.get_member(user_id)
        if not member:
            return "错误: 找不到用户"
        
        if not member.voice or member.voice.channel != channel:
            return "错误: 用户不在指定语音频道中"
        
        # 检查 Bot 权限
        bot_member = guild.me
        permissions = channel.permissions_for(bot_member)
        
        missing_perms = []
        if not permissions.connect:
            missing_perms.append("Connect")
        if not permissions.speak:
            missing_perms.append("Speak")
        if not permissions.use_voice_activation:
            missing_perms.append("Use Voice Activity")
        
        if missing_perms:
            return f"权限不足: {', '.join(missing_perms)}"
        
        return "权限检查通过"
        
    except Exception as e:
        return f"权限检查失败: {e}"
```

### 2. 音频播放问题

#### 症状

- 音频无法播放
- 播放中断
- 音质问题

#### 解决方案

##### 2.1 音频文件检查

```python
def check_audio_file(file_path):
    """检查音频文件有效性"""
    import os
    import subprocess
    
    if not os.path.exists(file_path):
        return False, "文件不存在"
    
    # 使用 FFmpeg 检查文件
    try:
        result = subprocess.run([
            'ffprobe', '-v', 'quiet', '-print_format', 'json', 
            '-show_format', '-show_streams', file_path
        ], capture_output=True, text=True, timeout=10)
        
        if result.returncode != 0:
            return False, "不是有效的音频文件"
        
        import json
        info = json.loads(result.stdout)
        
        # 检查是否有音频流
        audio_streams = [s for s in info['streams'] if s['codec_type'] == 'audio']
        if not audio_streams:
            return False, "文件中没有音频流"
        
        return True, f"音频文件正常 ({info['format']['format_name']})"
        
    except subprocess.TimeoutExpired:
        return False, "文件检查超时"
    except Exception as e:
        return False, f"文件检查失败: {e}"
```

##### 2.2 音频播放优化

```python
async def play_audio_with_error_handling(voice_client, audio_path):
    """带错误处理的音频播放"""
    
    if not voice_client or not voice_client.is_connected():
        raise Exception("语音客户端未连接")
    
    if voice_client.is_playing():
        voice_client.stop()
        await asyncio.sleep(0.5)  # 等待停止完成
    
    # 检查音频文件
    is_valid, message = check_audio_file(audio_path)
    if not is_valid:
        raise Exception(f"音频文件无效: {message}")
    
    try:
        # 优化的 FFmpeg 选项
        ffmpeg_options = {
            'before_options': (
                '-loglevel quiet '
                '-reconnect 1 '
                '-reconnect_streamed 1 '
                '-reconnect_delay_max 5'
            ),
            'options': (
                '-vn '  # 禁用视频
                '-filter:a "volume=0.5" '  # 音量控制
                '-ac 2 '  # 立体声
                '-ar 48000 '  # 采样率
                '-f s16le'  # 输出格式
            )
        }
        
        audio_source = discord.FFmpegPCMAudio(audio_path, **ffmpeg_options)
        
        # 播放音频
        voice_client.play(audio_source)
        
        # 监控播放状态
        while voice_client.is_playing():
            await asyncio.sleep(1)
        
        print("音频播放完成")
        
    except Exception as e:
        print(f"音频播放失败: {e}")
        raise
```

### 3. 连接稳定性问题

#### 症状

- 连接频繁断开
- 延迟过高
- 音频卡顿

#### 解决方案

```python
async def monitor_voice_connection(adapter, guild_id, monitoring_duration=60):
    """监控语音连接质量"""
    
    start_time = asyncio.get_event_loop().time()
    latencies = []
    disconnection_count = 0
    
    while asyncio.get_event_loop().time() - start_time < monitoring_duration:
        try:
            status = await adapter.get_voice_connection_status(guild_id)
            
            if status:
                latencies.append(status['latency'])
                print(f"延迟: {status['latency']:.2f}ms, 健康度: {status['connection_health']}")
            else:
                disconnection_count += 1
                print("连接已断开")
                
                # 尝试重连
                if disconnection_count < 3:
                    print("尝试重连...")
                    # 这里需要实现重连逻辑
            
        except Exception as e:
            print(f"监控错误: {e}")
        
        await asyncio.sleep(5)
    
    if latencies:
        avg_latency = sum(latencies) / len(latencies)
        max_latency = max(latencies)
        print(f"平均延迟: {avg_latency:.2f}ms, 最大延迟: {max_latency:.2f}ms")
        print(f"断开次数: {disconnection_count}")
```

## 性能问题

### 1. 内存使用过高

#### 症状

- 内存占用持续增长
- 程序响应变慢
- 内存溢出错误

#### 解决方案

```python
import gc
import psutil
import os

def monitor_memory_usage():
    """监控内存使用情况"""
    process = psutil.Process(os.getpid())
    memory_info = process.memory_info()
    memory_mb = memory_info.rss / 1024 / 1024
    
    print(f"内存使用: {memory_mb:.2f} MB")
    return memory_mb

async def cleanup_resources(adapter):
    """清理资源"""
    # 清理语音连接
    if hasattr(adapter, 'voice_manager') and adapter.voice_manager:
        await adapter.voice_manager.cleanup_inactive_connections()
    
    # 强制垃圾回收
    gc.collect()
    
    print(f"清理后内存使用: {monitor_memory_usage():.2f} MB")

# 定期内存监控
async def memory_monitor_task(adapter, interval=300):  # 5分钟检查一次
    """内存监控任务"""
    while True:
        memory_usage = monitor_memory_usage()
        
        if memory_usage > 500:  # 500MB 阈值
            print("内存使用过高，执行清理...")
            await cleanup_resources(adapter)
        
        await asyncio.sleep(interval)
```

### 2. 连接数过多

#### 症状

- 达到连接限制
- 新连接失败
- 性能下降

#### 解决方案

```python
class ConnectionLimiter:
    """连接数限制器"""
    
    def __init__(self, max_connections=10):
        self.max_connections = max_connections
        self.active_connections = {}
        
    async def acquire_connection(self, guild_id, adapter):
        """获取连接"""
        if len(self.active_connections) >= self.max_connections:
            # 断开最旧的连接
            oldest_guild = min(self.active_connections.keys(), 
                             key=lambda g: self.active_connections[g]['created_at'])
            
            await adapter.leave_voice_channel(oldest_guild)
            del self.active_connections[oldest_guild]
            print(f"断开最旧连接: {oldest_guild}")
        
        self.active_connections[guild_id] = {
            'created_at': asyncio.get_event_loop().time(),
            'last_activity': asyncio.get_event_loop().time()
        }
    
    def release_connection(self, guild_id):
        """释放连接"""
        if guild_id in self.active_connections:
            del self.active_connections[guild_id]
    
    def update_activity(self, guild_id):
        """更新活动时间"""
        if guild_id in self.active_connections:
            self.active_connections[guild_id]['last_activity'] = asyncio.get_event_loop().time()
```

## 调试工具

### 1. 详细日志配置

```python
import logging
import sys

def setup_detailed_logging():
    """设置详细日志"""
    
    # 创建格式化器
    formatter = logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(funcName)s:%(lineno)d - %(message)s'
    )
    
    # 控制台处理器
    console_handler = logging.StreamHandler(sys.stdout)
    console_handler.setFormatter(formatter)
    console_handler.setLevel(logging.INFO)
    
    # 文件处理器
    file_handler = logging.FileHandler('discord_debug.log', encoding='utf-8')
    file_handler.setFormatter(formatter)
    file_handler.setLevel(logging.DEBUG)
    
    # Discord.py 日志
    discord_logger = logging.getLogger('discord')
    discord_logger.setLevel(logging.DEBUG)
    discord_logger.addHandler(console_handler)
    discord_logger.addHandler(file_handler)
    
    # 适配器日志
    adapter_logger = logging.getLogger('discord_adapter')
    adapter_logger.setLevel(logging.DEBUG)
    adapter_logger.addHandler(console_handler)
    adapter_logger.addHandler(file_handler)
    
    return discord_logger, adapter_logger
```

### 2. 连接诊断工具

```python
async def comprehensive_diagnostic(adapter):
    """综合诊断工具"""
    
    print("=== Discord 适配器诊断 ===")
    
    # 1. 基础连接检查
    print("1. 基础连接状态:")
    if hasattr(adapter, 'bot') and adapter.bot.is_ready():
        print("  ✓ Discord 连接正常")
        print(f"  ✓ Bot 用户: {adapter.bot.user}")
        print(f"  ✓ 延迟: {adapter.bot.latency*1000:.2f}ms")
    else:
        print("  ✗ Discord 连接异常")
    
    # 2. 语音功能检查
    print("\\n2. 语音功能状态:")
    voice_deps_ok = check_voice_dependencies()
    if voice_deps_ok:
        print("  ✓ 语音依赖正常")
    else:
        print("  ✗ 语音依赖异常")
    
    if hasattr(adapter, 'voice_manager') and adapter.voice_manager:
        connections = await adapter.list_active_voice_connections()
        print(f"  ✓ 语音管理器正常，活跃连接: {len(connections)}")
        for conn in connections:
            print(f"    - {conn['guild_id']}: {conn['channel_name']} ({conn['latency']:.2f}ms)")
    else:
        print("  ✗ 语音管理器未初始化")
    
    # 3. 内存使用检查
    print("\\n3. 资源使用状态:")
    memory_usage = monitor_memory_usage()
    print(f"  内存使用: {memory_usage:.2f} MB")
    
    # 4. 网络连接测试
    print("\\n4. 网络连接测试:")
    await network_stability_test()
    
    print("\\n=== 诊断完成 ===")
```

### 3. 实时监控面板

```python
import asyncio
import time

class DiscordMonitor:
    """Discord 适配器实时监控"""
    
    def __init__(self, adapter):
        self.adapter = adapter
        self.stats = {
            'messages_sent': 0,
            'messages_received': 0,
            'voice_connections': 0,
            'errors': 0,
            'start_time': time.time()
        }
    
    async def start_monitoring(self):
        """启动监控"""
        while True:
            await self.display_status()
            await asyncio.sleep(10)
    
    async def display_status(self):
        """显示状态信息"""
        uptime = time.time() - self.stats['start_time']
        uptime_str = f"{int(uptime//3600)}h {int((uptime%3600)//60)}m {int(uptime%60)}s"
        
        print("\\n" + "="*50)
        print(f"Discord 适配器监控 - 运行时间: {uptime_str}")
        print("="*50)
        
        # 基础状态
        if hasattr(self.adapter, 'bot') and self.adapter.bot.is_ready():
            print(f"连接状态: ✓ 正常 (延迟: {self.adapter.bot.latency*1000:.2f}ms)")
        else:
            print("连接状态: ✗ 异常")
        
        # 统计信息
        print(f"消息发送: {self.stats['messages_sent']}")
        print(f"消息接收: {self.stats['messages_received']}")
        print(f"语音连接: {self.stats['voice_connections']}")
        print(f"错误次数: {self.stats['errors']}")
        
        # 内存使用
        memory = monitor_memory_usage()
        print(f"内存使用: {memory:.2f} MB")
        
        # 语音连接详情
        if hasattr(self.adapter, 'voice_manager') and self.adapter.voice_manager:
            connections = await self.adapter.list_active_voice_connections()
            if connections:
                print("\\n语音连接:")
                for conn in connections:
                    print(f"  {conn['guild_id']}: {conn['channel_name']} "
                          f"({conn['user_count']} 用户, {conn['latency']:.2f}ms)")
        
        print("="*50)
    
    def record_message_sent(self):
        self.stats['messages_sent'] += 1
    
    def record_message_received(self):
        self.stats['messages_received'] += 1
    
    def record_voice_connection(self):
        self.stats['voice_connections'] += 1
    
    def record_error(self):
        self.stats['errors'] += 1

# 使用示例
async def run_with_monitoring(adapter):
    monitor = DiscordMonitor(adapter)
    
    # 启动监控任务
    monitor_task = asyncio.create_task(monitor.start_monitoring())
    
    try:
        # 运行适配器
        await adapter.run_async()
    finally:
        monitor_task.cancel()
```

## 常见问题速查表

| 问题类型   | 症状                   | 快速检查          | 解决方案             |
| ------ | -------------------- | ------------- | ---------------- |
| 连接失败   | LoginFailure         | 检查 token      | 验证并更新 token      |
| 网络超时   | ClientConnectorError | 检查网络          | 配置代理或检查防火墙       |
| 权限不足   | Forbidden 403        | 检查 Bot 权限     | 在 Discord 中添加权限  |
| 消息过长   | 消息被截断                | 检查字符数         | 分割长消息            |
| 图像失败   | 文件上传错误               | 检查文件大小/格式     | 压缩或转换格式          |
| 语音连接失败 | VoiceConnectionError | 检查依赖和权限       | 安装依赖，检查频道权限      |
| 音频播放失败 | FFmpeg 错误            | 检查 FFmpeg 和文件 | 安装 FFmpeg，验证音频文件 |
| 内存泄漏   | 内存持续增长               | 监控内存使用        | 清理连接，执行 GC       |
| 高延迟    | 响应慢                  | 检查网络延迟        | 优化网络，减少并发        |

***

> **提示**: 遇到问题时，首先启用详细日志记录，然后使用诊断工具进行系统性排查。大多数问题都与配置、权限或网络环境相关。

---

# AI 助手开发上下文

Source: https://langbot.app/docs/zh/develop/agent-context

可直接整页复制、粘贴给 AI 编程助手的 LangBot 项目上下文：目录结构、组件组织方式、运行期连接关系与开发环境配置。

> 本页面是为 AI 编程助手（Claude Code / Cursor / Copilot / Codex 等）准备的。:
>
> 直接把本页**全部内容**复制粘贴给你的 AI 助手，它即可快速了解 LangBot 的整体架构、各组件如何组织、运行期如何连接，以及如何配置开发环境，无需你再逐条解释。

本页内容与各仓库根目录的 `AGENTS.md`（`CLAUDE.md` 为其软链接）保持一致，是 LangBot 项目面向开发者与 AI 助手的"一页上手"说明。

## 项目概览

LangBot 是一个开源的、LLM 原生的即时通信机器人开发平台，提供开箱即用的 IM 机器人开发体验，内置 Agent、RAG、MCP 等 LLM 应用能力，支持全球主流 IM 平台，并提供丰富的 API 以供二次开发。

LangBot 拥有完整的 Web 前端，几乎所有操作都可以通过前端完成。

- **后端**：Python（`>=3.11,<4.0`），使用 `uv` 管理依赖；Web 框架为 Quart（Flask 的异步版本）。HTTP API 与预编译好的前端都由后端在 `http://127.0.0.1:5300` 上提供服务。
- **前端**：`web/` 是 **Vite + React Router 7 + shadcn/ui + Tailwind CSS** 的 SPA，使用 `pnpm` 管理依赖（注意：**不是** Next.js，`dev` 脚本就是 `vite`）。
- **插件系统**：插件 SDK、CLI（`lbp`）、插件运行时、Box 沙箱运行时以及 LangBot 与插件共享的实体/API 定义，全部位于独立仓库 [`langbot-plugin-sdk`](https://github.com/langbot-app/langbot-plugin-sdk)。LangBot 通过 `pyproject.toml` 中固定版本的 `langbot-plugin` 包依赖它。

## 仓库目录结构

```
LangBot/
├── main.py                     # 入口垫片 -> langbot.__main__.main()
├── pyproject.toml              # Python 项目与依赖（uv），固定 langbot-plugin==<x.y.z>
├── src/langbot/
│   ├── __main__.py             # 真正的入口，定义 CLI 参数（--standalone-runtime / --standalone-box / --debug）
│   ├── pkg/                    # 核心后端包
│   │   ├── api/                # HTTP API 控制器 + 服务（Quart）
│   │   ├── core/               # 应用引导、启动阶段（stages）、任务管理器
│   │   ├── platform/           # IM 平台适配器、机器人管理、会话管理
│   │   ├── provider/           # LLM 提供商、请求器、工具提供者
│   │   ├── pipeline/           # 流水线、阶段、查询池
│   │   ├── plugin/             # 连接插件运行时的桥接层（connector.py / handler.py）
│   │   ├── box/                # 代码沙箱子系统（Docker / nsjail / E2B 后端）
│   │   ├── skill/              # 技能子系统
│   │   ├── rag/ , vector/      # RAG 与向量存储
│   │   ├── command/            # 内置命令
│   │   ├── persistence/        # ORM 模型 + Alembic 迁移（SQLite 与 PostgreSQL）
│   │   ├── storage/            # 对象/文件存储抽象
│   │   ├── config/, entity/, discover/, utils/, telemetry/, survey/
│   ├── libs/                   # 内置 SDK（qq_official_api、wecom_api 等）
│   └── templates/              # 配置/组件模板（如 templates/config.yaml）
├── web/                        # 前端 SPA（Vite + React Router 7 + shadcn + Tailwind）
└── docker/                     # docker-compose 部署文件
```

## 组件如何组织

LangBot 后端的核心包 `src/langbot/pkg/` 按职责拆分为若干子模块，彼此低耦合：

| 模块                         | 职责                                                         |
| -------------------------- | ---------------------------------------------------------- |
| `core`                     | 应用生命周期：启动阶段（stages）按序加载配置、连接数据库、拉起各子系统，并管理后台任务。            |
| `platform`                 | 各 IM 平台的适配器（Discord、Telegram、QQ、企业微信、飞书等），负责收发消息、管理机器人与会话。 |
| `provider`                 | LLM 提供商与请求器（OpenAI 兼容、各家原生 API），以及供 Agent 调用的工具提供者。        |
| `pipeline`                 | 消息处理流水线：把一条消息经过触发、AI 处理、输出、安全等阶段串联起来。                      |
| `plugin`                   | LangBot 主程序与插件运行时之间的桥接层，负责连接、收发动作、转发事件。                    |
| `box`                      | 代码沙箱子系统，为技能/工具提供隔离的代码执行环境，按可用性选择 Docker / nsjail / E2B 后端。 |
| `skill` / `rag` / `vector` | 技能、检索增强生成与向量存储能力。                                          |
| `persistence`              | ORM 实体定义与 Alembic 数据库迁移，单套脚本同时兼容 SQLite 与 PostgreSQL。      |

插件侧的组件（在 `langbot-plugin-sdk` 中定义，由 `lbp comp` 生成）则围绕一个 `BasePlugin` 组织，目前支持六种组件类型：

- **Command（命令）**：用户主动触发的指令（如 `!weather tokyo`）。
- **Tool（工具）**：供 LLM 在 Agent 执行过程中调用的函数（如查天气、查数据库）。
- **EventListener（事件监听器）**：监听消息流水线中的事件（如自动回复、内容过滤）。
- **KnowledgeEngine（知识引擎）**：自定义知识库的检索/接入实现，供 RAG 使用。
- **Parser（解析器）**：自定义消息/内容的解析处理。
- **Page（页面）**：插件提供的自定义 Web 页面，可嵌入 LangBot 管理面板。

每个插件运行在独立进程中，由插件运行时统一管理生命周期（发现 → 安装依赖 → 加载 → 初始化 → 注册组件 → 就绪 → 终止）。

## 运行期如何连接

```
┌──────────────┐  HTTP/API   ┌──────────────┐
│   浏览器/前端  │ ──────────► │              │
│ (Vite SPA)   │ :3000/同域   │   LangBot    │
└──────────────┘             │   后端       │
                             │  (Quart)     │
   ┌─────────────────────────┤  :5300       ├─────────────────────────┐
   │ stdio 或 WebSocket        └──────────────┘   stdio 或 WebSocket    │
   ▼                                              ▼
┌──────────────┐                          ┌──────────────┐
│ 插件运行时     │  独立进程，逐个拉起插件      │ Box 运行时    │  代码沙箱
│ :5400 / :5401│                          │ :5410        │  Docker/nsjail/E2B
└──────────────┘                          └──────────────┘
```

- **前端 ↔ 后端**：开发时前端独立跑在 `:3000`，通过 `web/.env` 的 `VITE_API_BASE_URL` 访问后端 `:5300`；生产环境前端被预编译为静态文件由后端同域提供。
- **后端 ↔ 插件运行时**：
  - 用户**直接启动** LangBot（非容器）时，后端自己**拉起**运行时并通过 **stdio** 通信（轻量/个人场景）。stdio **不能自动重连**——断开后需重启 LangBot；常见故障是上一个后端遗留的**孤儿运行时进程**仍占用 `5400`/`5401`，杀掉后重启即可。
  - LangBot 运行在**容器**中时，通过 **WebSocket** 连接到独立的运行时（生产场景）。控制端口默认 `5400`，调试端口默认 `5401`。相关配置：`data/config.yaml` 的 `plugin.runtime_ws_url`（如 `ws://langbot_plugin_runtime:5400/control/ws`）。
- **后端 ↔ Box 运行时**：Box 子系统通过控制通道连接到 Box 运行时（默认端口 `5410`），运行时在 Docker / nsjail / E2B 中执行沙箱代码。相关配置（`data/config.yaml` 的 `box:` 段）：`box.enabled`（总开关）、`box.backend`（`'local'`/`'docker'`/`'nsjail'`/`'e2b'`）、`box.runtime.endpoint`（外部 Box 运行时地址，如 `ws://127.0.0.1:5410`，留空则本地自动托管）。与插件运行时类似，配置该地址并以 `--standalone-box` 启动即可连接外部 Box 运行时。
- 调试运行时、CLI 与 SDK 的完整方法见[《调试插件运行时、CLI、SDK》](https://langbot.app/docs/zh/develop/plugin-runtime.md)，详细参数与架构在 `langbot-plugin-sdk` 仓库的 `AGENTS.md` 中。

## 开发环境配置

完整说明见[《开发配置》](https://langbot.app/docs/zh/develop/dev-config.md)。要点如下：

### 后端

```bash
pip install uv
uv sync --dev          # uv 会自动创建 .venv/；请把编辑器解释器指向它
uv run main.py         # 在 http://127.0.0.1:5300 提供 API + 前端
```

首次启动会在 `data/config.yaml` 生成配置文件。默认使用 SQLite（零配置），同时支持 PostgreSQL；迁移在启动时自动执行。

### 前端

需要 Node.js 与 [pnpm](https://pnpm.io/zh/installation)。

```bash
cd web
cp .env.example .env   # Windows: copy .env.example .env
pnpm install
pnpm dev               # http://127.0.0.1:3000（也可用 npm install / npm run dev）
```

`pnpm dev` 会读取 `web/.env` 中的 `VITE_API_BASE_URL`，使开发态前端能访问后端 `:5300`。

### 代码格式化

仓库 CI 会跑 lint + format 检查。安装 pre-commit 钩子，让同样的检查在每次提交前于本地运行：

```bash
uv run pre-commit install
```

### 数据库迁移

修改 ORM 模型后生成迁移：

```bash
# 在项目根目录运行（需已有 data/config.yaml）
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "描述你的变更"
```

`autogenerate` 能检测 schema 变更（增删列/表、类型变更），但**数据迁移**（如修改 JSON 字段内容）需手写进生成的脚本。`env.py` 设置了 `render_as_batch=True`，会自动处理 SQLite 的 ALTER TABLE 限制，无需按数据库类型分支。迁移在 LangBot 启动时自动执行。

## 开发规范

- LangBot 是全球化项目：**所有代码注释与文档字符串必须为英文**，所有面向用户的文案必须支持 **i18n**（至少 `en_US` + `zh_Hans`，仓库已有日文处则补 `ja_JP`）。
- LangBot 同时被 toC 与 toB 场景采用，请始终考虑兼容性与安全性。
- **提交信息格式**：`<type>(<scope>): <subject>`
  - `type`：`feat`、`fix`、`docs`、`style`、`refactor`、`perf`、`test`、`chore` 等。
  - `scope`：受影响的包/模块/文件/类。
  - `subject`：简洁的变更描述。

## 面向 Agent 的能力（MCP + 技能）

LangBot 从设计上就**对 AI Agent 友好**，提供三类面向 Agent 的能力，并与 HTTP API 严格对齐：

1. **MCP 服务**：`src/langbot/pkg/api/mcp/` 在 `/mcp` 上以 MCP 工具形式开放了 API 的精选子集（使用 API Key 鉴权，含 config.yaml 中的 `api.global_api_key`）。`server.py` 定义工具（直接调用 service 层），`mount.py` 是 ASGI 分发器。
2. **仓库内技能**：`skills/` 目录是 LangBot 全部 Agent 技能（插件开发、核心开发、部署、e2e、MCP 操作等）的**唯一事实来源**。文档与落地页都链接到此处，而非各自复制。
3. **API Key 鉴权**：`api.global_api_key`（config.yaml）可在无登录态下鉴权 API 与 MCP，详见 `docs/API_KEY_AUTH.md`。

> **维护规则（重要）**：当你新增、删除或修改某个应对 Agent 开放的 HTTP API 端点时，必须**同时**更新 `src/langbot/pkg/api/mcp/server.py` 中对应的 MCP 工具**以及** `skills/` 下相关技能（尤其是 `skills/skills/langbot-mcp-ops`）。API、MCP 工具集与技能是同一套系统，三者漂移即为 bug。

## 一些原则

- Keep it simple, stupid.
- 如无必要，勿增实体。
- 八荣八耻：

  以瞎猜接口为耻，以认真查询为荣。
  以模糊执行为耻，以寻求确认为荣。
  以臆想业务为耻，以人类确认为荣。
  以创造接口为耻，以复用现有为荣。
  以跳过验证为耻，以主动测试为荣。
  以破坏架构为耻，以遵循规范为荣。
  以假装理解为耻，以诚实无知为荣。
  以盲目修改为耻，以谨慎重构为荣。

---

# 组件架构

Source: https://langbot.app/docs/zh/develop/comp-arch

![组件架构图](https://langbot.app/docs/images/zh/develop/comp_arch/develop_comp_arch_1.png)

---

# 开发配置

Source: https://langbot.app/docs/zh/develop/dev-config

LangBot 分为前端和后端，前端使用 Vite + React Router + shadcn 开发，后端通过 Quart（Flask 的异步版本）开发。

## 后端

代码位于 `pkg` 目录下，由根目录的 `main.py` 文件引导启动。

安装依赖，我们使用 uv 管理依赖。

```bash
pip install uv
uv sync --dev
```

启动后端

```bash
uv run main.py
```

此时配置文件会自动生成到 `data/config.yaml` 文件中。

## 前端

代码位于 `web` 目录下，需要安装 Node.js，[pnpm](https://pnpm.io/zh/installation)。

复制 `.env.example` 到 `.env`。

- linux环境使用

```bash
cp .env.example .env
```

- windows环境使用

```bash
copy .env.example .env
```

安装依赖并启动前端

```bash
pnpm install
pnpm dev

# 若未安装pnpm，也可以使用npm来解决依赖并启动
npm install
npm run dev
```

然后根据输出信息，访问`http://127.0.0.1:3000`查看独立启动的前端页面。

> 本地使用\`pnpm dev\`启动时，会携带\`.env\`中的环境变量\`VITE\_API\_BASE\_URL\`，该变量会自动被前端使用，以确保前端可以访问到本地启动的后端的\`5300\`端口。:
>
> 生产环境中，前端会被预编译成静态文件，由后端提供服务，前端会自动访问同域的后端地址。

## 代码格式化

仓库中包含 lint 和 format 检查工作流，您推送代码后将被自动检查。请配置 pre-commit 来在提交时在本地提前检查代码。

```bash
uv run pre-commit install
```

## API 文档

我们在开发每个接口之前都会先在 APIFox 中编写接口文档，请查看 [API 文档](https://ok52vhsenr.apifox.cn/)。

## 数据库迁移

LangBot 使用 [Alembic](https://alembic.sqlalchemy.org/) 管理数据库迁移，同时支持 SQLite 和 PostgreSQL，无需针对不同数据库编写不同的迁移代码。

### 迁移文件位置

```
src/langbot/pkg/persistence/alembic/versions/
```

### 创建新迁移

推荐使用 **autogenerate** 自动生成迁移脚本，它会对比 ORM 模型和数据库 schema 的差异：

```bash
# 在项目根目录下运行（需要已有 data/config.yaml）
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "描述你的变更"
```

生成的文件会出现在 `src/langbot/pkg/persistence/alembic/versions/` 目录下，请检查并编辑生成的脚本，确认变更无误后提交。

> info:
>
> autogenerate 能自动检测列的增删、表的增删、类型变更等。但对于**数据迁移**（如修改 JSON 字段的内容），需要手动在生成的脚本中添加代码。

也可以手动创建迁移文件，遵循命名规范 `NNNN_description.py`：

```python
"""描述你的迁移

Revision ID: 0003_add_bot_description
Revises: 0002_sample
Create Date: 2026-04-08
"""
from alembic import op
import sqlalchemy as sa

revision = '0003_add_bot_description'
down_revision = '0002_sample'  # 指向前一个迁移的 revision
branch_labels = None
depends_on = None


def upgrade() -> None:
    # Schema 变更（SQLite 和 PostgreSQL 通用）
    op.add_column('bots', sa.Column('description', sa.String(512), server_default=''))


def downgrade() -> None:
    op.drop_column('bots', 'description')
```

### 迁移模式

**Schema 变更（增/删列、建表）**

```python
def upgrade() -> None:
    # 添加列
    op.add_column('table_name', sa.Column('new_col', sa.String(255), server_default=''))
    
    # 新建表
    op.create_table(
        'new_table',
        sa.Column('id', sa.Integer, primary_key=True, autoincrement=True),
        sa.Column('name', sa.String(255), nullable=False),
    )
```

> info:
>
> `env.py` 中设置了 `render_as_batch=True`，Alembic 会自动处理 SQLite 的 ALTER TABLE 限制（通过临时表重建），无需手动区分数据库类型。

**数据迁移（读取并修改数据）**

```python
import json

def upgrade() -> None:
    conn = op.get_bind()
    rows = conn.execute(sa.text("SELECT uuid, config FROM pipelines")).fetchall()
    for row in rows:
        config = json.loads(row[1]) if isinstance(row[1], str) else row[1]
        config.setdefault('ai', {})['new_key'] = 'default_value'
        conn.execute(
            sa.text("UPDATE pipelines SET config = :cfg WHERE uuid = :uuid"),
            {"cfg": json.dumps(config), "uuid": row[0]}
        )
```

### 运行机制

迁移在 LangBot 启动时自动执行，无需手动运行命令：

1. 首次启动时，自动 stamp 基线版本（标记现有数据库）
2. 之后每次启动，自动执行所有未应用的迁移（`alembic upgrade head`）

### CI 测试

仓库中包含 `test-migrations.yml` 工作流，当 `persistence/` 相关文件变更时会自动在 SQLite 和 PostgreSQL 上测试迁移脚本。

### CLI 工具

```bash
# 自动生成迁移脚本（对比 ORM 模型和数据库）
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "描述"

# 升级数据库
uv run python -m langbot.pkg.persistence.alembic_runner upgrade

# 查看当前版本
uv run python -m langbot.pkg.persistence.alembic_runner current

# 标记版本（不执行迁移）
uv run python -m langbot.pkg.persistence.alembic_runner stamp head
```

---

# 调试插件运行时、CLI、SDK

Source: https://langbot.app/docs/zh/develop/plugin-runtime

> info:
>
> 插件运行时、CLI、SDK 开源在: <https://github.com/langbot-app/langbot-plugin-sdk>

由于 LangBot 需要依赖 langbot-plugin-sdk 中定义的实体，我们推荐您在一个新建目录下打开 VS Code，将 LangBot 和 langbot-plugin-sdk（git clone <https://github.com/langbot-app/langbot-plugin-sdk）> 作为子目录放入其中，目录结构如下：

```bash
langbot-projects
├── LangBot
├── langbot-plugin-sdk
```

进入 LangBot 目录，安装依赖：

```bash
cd LangBot
uv sync --dev
```

此时，uv 将自动为您创建虚拟环境(.venv)，若您的编辑器询问您是否使用此虚拟环境，请选择`是`。

![](https://langbot.app/docs/images/zh/develop/confirm_venv.png)

若未弹出，请手动在右下角设置 Python 解释器路径为该 venv 中的解释器。

然后打开 VS Code 底部的终端，这将自动激活 venv。

或者请您手动激活此虚拟环境：

```bash
# 请自行根据.venv路径来修改命令
source .venv/bin/activate
```

## 启动插件运行时

```bash
python -m langbot_plugin.cli.__init__ rt
```

Plugin Runtime 接受以下参数：

- `--debug-only`: 不启动`data/plugins`目录下的插件，仅允许通过调试连接加载插件。
- `--ws-debug-port`: 监听的调试端口，默认是`5401`。
- `--ws-control-port`: 监听的控制端口（供 LangBot 主程序连接），默认是`5400`。
- `-s`: 使用`stdio`接受控制连接。**仅在生产环境使用**。
- `--skip-deps-check`: 为了确保插件依赖均已安装，Runtime 会在每次启动时检查并安装所有已安装插件的依赖。携带此参数可禁用此检查。

### 使 LangBot 使用您本地修改过的 langbot-plugin-sdk

若您修改了诸如消息实体、插件数据定义等内容，需要将其更新到 LangBot 环境，以确保运行期间数据格式兼容。

请在**确保已激活 LangBot 目录下的虚拟环境（.venv）的终端**中，切换目录到 langbot-plugin-sdk 目录下，执行：

```bash
uv pip install .
```

这将把您修改后的 langbot-plugin-sdk 安装到 LangBot 的环境。

### 使 LangBot 连接到此运行时

在 LangBot 的`data/config.yaml`中配置`plugin.runtime_ws_url`为`ws://localhost:5400/control/ws`。

```yaml
plugin:
  runtime_ws_url: ws://localhost:5400/control/ws
```

并在已激活 LangBot 虚拟环境的终端中，直接使用 Python 启动主程序并携带参数`--standalone-runtime`（如：`python main.py --standalone-runtime`）。直接调用当前虚拟环境的 Python 不会再次同步依赖，因此不会把刚刚安装的本地 langbot-plugin-sdk 覆盖为远程版本。\
重启 LangBot，将会使用 WebSocket 连接到此运行时。

默认情况下无需配置 `LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN`：当 LangBot 与 Runtime 两端都未设置时，OSS 的本地控制连接直接建立。若部署环境需要为 5400 控制端口增加共享密钥，则应在两端配置同一个至少 32 位的高熵值。Runtime 端配置后，未携带相同密钥的 LangBot 会被拒绝；只在 LangBot 端配置并不会启用 Runtime 端的认证。

### 使用 `lbp run` 调试插件

多 Workspace 版本不再允许调试插件仅凭 `5401` 端口接入 Runtime。每个 Workspace 都有独立且会过期的调试密钥：

1. 确认 LangBot 与 Plugin Runtime 已按上文启动并连接成功。
2. 在 LangBot WebUI 的“插件”页面点击“调试信息”，复制调试 URL 和调试密钥。该操作需要当前 Workspace 的资源管理权限。
3. 在插件项目的 `.env` 中配置：

```bash
DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws
PLUGIN_DEBUG_KEY=<从 WebUI 复制的调试密钥>
```

4. 在插件项目目录中启动：

```bash
python -m langbot_plugin.cli.__init__ run
```

也可以不写入 `.env`，改用 `python -m langbot_plugin.cli.__init__ run --plugin-debug-key '<调试密钥>'`。调试密钥按 Workspace 隔离且有效期为两小时；密钥过期、Runtime 重启或切换 Workspace 后，请回到 WebUI 重新获取。只配置 `DEBUG_RUNTIME_WS_URL` 会被 Runtime 拒绝。

## 以 standalone 模式启动 Box Runtime

Box Runtime 与 Plugin Runtime 的控制连接规则一致：OSS standalone 开发环境默认不强制配置 token，两端都未设置 `LANGBOT_BOX_CONTROL_TOKEN` 时可以直接连接：

```bash
# 终端 1：langbot-plugin-sdk 目录
python -m langbot_plugin.cli.__init__ box
```

LangBot 的 `data/config.yaml` 使用本地 Box 地址：

```yaml
box:
  enabled: true
  backend: local
  runtime:
    endpoint: ws://127.0.0.1:5410
```

```bash
# 终端 2：LangBot 目录
python main.py --standalone-runtime --standalone-box
```

若需要保护暴露的 5410 端口，请在启动两个进程前分别设置完全相同、至少 32 位且不含空白的高熵值：

```bash
export LANGBOT_BOX_CONTROL_TOKEN='<两端完全相同的高熵密钥>'
```

Box Runtime 端一旦配置 token，就会拒绝未携带相同 token 的 LangBot。只在 LangBot 端设置不会启用 Box Runtime 端认证；显式配置但不足 32 位的值仍会被两端拒绝。不要把真实密钥提交到配置文件或 Git。

## langbot-plugin-sdk 架构

本代码库中包含以下内容：

- `langbot_plugin.api`：插件相关实体和 API 定义。
- `langbot_plugin.assets`：插件模板。
- `langbot_plugin.cli`：插件开发 CLI 工具。
- `langbot_plugin.entities`：插件系统中非 API 定义的相关实体。
- `langbot_plugin.runtime`：插件运行时和底层通信（stdio 和 websocket）实现。

## `lbp` CLI 工具

CLI 工具提供 Runtime 启动、插件初始化、插件组件管理、Marketplace 交互等功能。

详细的程序入口请查看[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)。

---

# 社区资源

Source: https://langbot.app/docs/zh/insight/community

LangBot 社区资源：开源 AI 机器人平台的 GitHub、Discord、文档与支持渠道。

## 项目官方微信群

> 商业合作、定制需求，请加企业微信群

![企业微信群](https://langbot.app/docs/images/zh/insight/wecom_qr.png)

## 本项目交流 QQ 群

> 遇到问题请先认真阅读文档，如无法解决再加群提问

### 🥰 社区总群

解答各种问题

- LangBot 社区（一）：619154800 ([链接](https://qm.qq.com/q/1K9GjQuza))
- LangBot 社区（二）：1030838208 ([链接](https://qm.qq.com/q/PF9OuQCCcM))
- LangBot 社区（三）：966235608 ([链接](https://qm.qq.com/q/JLi38whHum))

### 🧩 插件开发群

插件和 LangBot 开发、发布、交流

> 注意:
>
> 此群群友只对开发插件感兴趣，不会解答您的任何其他问题。

- LangBot 插件&开发：1032327138 ([链接](https://qm.qq.com/q/G7ENGTjeou))

### ❤ 非官方社区群

插件和 LangBot 聊天、对话、交流

> 注意:
>
> 此群群友只对闲聊兴趣，不会解答您的任何其他问题。

- LangBot 非官方社区：472263434 ([链接](https://qm.qq.com/q/c5mH8rHlgQ))

---

# 数据收集政策

Source: https://langbot.app/docs/zh/insight/data-collection-policy

可选遥测、功能执行记录与关闭方法

LangBot 向配置的 LangBot Space 服务（默认为 `https://space.langbot.app`）发送遥测，用于了解使用情况和改进可靠性。**遥测默认开启，可以关闭。** 功能执行记录复用现有遥测，不再使用独立 Beta 诊断上报。

## 现有产品遥测

启用后，现有查询链路可能发送：

| 数据       | 内容                                                                      |
| -------- | ----------------------------------------------------------------------- |
| 标识与环境    | `instance_id`、`workspace_uuid`、随机 `query_id`、版本、适配器及运行器类型               |
| 查询统计     | 模型名称、耗时、时间戳、管道插件名称                                                      |
| 功能使用     | 按来源分类的工具调用次数、工具调用轮数、知识库与检索条目数、知识引擎插件 ID、沙箱执行/错误次数、已激活技能名称、已配置 MCP 服务器名称 |
| 错误       | 旧 `error` 字段可能包含原始 traceback，包括异常文本                                     |
| 托管运行实例活动 | 托管 SaaS 查询中的 `runtime_instance_id` 用于刷新空闲超时活动，不写入分析事件记录                 |

功能计数不会主动包含工具参数/结果、检索文本或沙箱代码/输出。**但旧异常文本以及用户自定义的模型、技能、MCP 名称可能含有敏感信息。功能执行记录的内容限制不会为这条旧数据流脱敏。** 不应将现有遥测视为保证不含用户内容。

活跃工作区会在启动后不久、此后每天发送工作区心跳，包含部署平台、数据库/向量数据库类型、沙箱配置与可用性、已启用适配器类型和资源数量，而非资源内容或连接信息。

自愿参与的应用内问卷会发送问卷 ID、提交的回答、实例 ID、版本及完成/关闭状态。问卷回答是用户主动提供的内容，不属于 Beta 诊断。

## 功能执行遥测

功能执行遥测记录平台事件、路由、Pipeline / Agent / 插件事件处理器和平台 API 的执行事实，包括固定的操作标识、适配器和运行器类型、处理模式、结果、次数、首次及末次观测时间、实例与工作区标识、版本及模拟执行标记。Core 在内存中有界合并，再由后台发送；Space 负责路径覆盖分析。

这些执行记录不包含消息、提示词、模型回复、平台用户或群组 ID、工具/API 参数或结果、凭据及原始异常堆栈。实例与工作区标识可能关联到部署或账户，不应视为不可识别。此内容限制仅针对功能执行记录，不改变上述既有查询遥测的数据范围。

### 单事件执行链路

抽样上报的执行记录还可以还原单个事件的处理全过程：一个不可反推的随机链路标识、按顺序记录的阶段（平台事件 → 路由决策 → Pipeline / Agent / 插件事件处理器 → 平台 API 调用）、每个阶段的结果、路由目标标识、执行该事件的 Runner 运行标识，以及链路关闭原因。各字段与其他执行记录一样只使用代码定义的标识；路由目标以 `type:uuid` 形式上报，不使用用户自定义规则名。Core 对单条链路的阶段数和同时在途的链路数都设置了上限，超出的部分会被丢弃。

链路抽样由 `space.execution_trace` 控制：`off`、`failures`（保留含失败、取消或超时阶段的链路）、`sampled`（默认，在上述基础上保留每 N 条成功链路中的一条，N = `space.execution_trace_sample`）与 `all`。WebUI 调试执行始终保留，并继续标记为模拟执行，不计入真实执行统计。

网络不可达、超时或服务端错误不会阻断正常操作，失败详情仅记录在 DEBUG 日志中。队列有上限，故障时记录可能丢失。执行记录用于辅助分析，平台 API 返回成功不代表用户已阅读消息。

## 存储与保留

数据存储在所配置的 Space 服务。功能执行原始记录按 30 天保留窗口定期分批清理；服务中断或积压可能延迟删除。该期限不改变既有查询遥测、问卷、账户或服务日志的保留规则。覆盖分析仅供获授权的遥测管理用户或服务客户端访问。

关闭遥测会停止后续上报，但不会删除服务端已有记录。如需处理历史数据，请联系 <hello@langbot.app> 或所用 Space 的管理员。

## 关闭遥测

在 `data/config.yaml` 的现有 `space` 节点中设置以下值，保留其他配置，然后重启 LangBot：

```yaml
space:
  disable_telemetry: true
```

此开关统一关闭查询统计、心跳和功能执行遥测，也会关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。

如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。

参见[系统环境设置](https://langbot.app/docs/zh/deploy/settings.md)。

---

# 特性规格

Source: https://langbot.app/docs/zh/insight/features

LangBot 是开源、生产级的 LLM 原生即时通信机器人开发平台，支持 QQ、微信、企业微信、飞书、钉钉、Discord、Telegram、Slack 等全球主流平台，内置 Agent、RAG 知识库、MCP、技能（Skills）与代码沙箱，深度集成 Dify、Coze、n8n、Langflow 等 Agent 平台。

LangBot 是一个**开源、生产级**的大语言模型（LLM）原生即时通信机器人开发平台。一套代码即可把 AI Agent 接入 QQ、微信、企业微信、飞书、钉钉、Discord、Telegram、Slack 等全球主流平台，内置 **Agent、RAG 知识库、MCP、技能（Skills）、代码沙箱**，深度集成 Dify、Coze、n8n、Langflow 等 Agent 平台，并通过浏览器中的 Web 管理面板完成全部配置与监控——无需手写配置文件。

> idea:
>
> **不想自己部署？** 试试 [LangBot Cloud](https://space.langbot.app/cloud) —— 无需服务器，注册即可立即开始使用。

## 核心能力一览

- **AI 对话与 Agent** —— 多轮对话、工具调用（Function Calling）、多模态（图片/语音/文件）、流式输出，开箱即用。
- **RAG 知识库** —— 内置知识库引擎（向量检索 + Rerank 重排序），让机器人基于你的私有知识作答；并支持通过插件扩展，可无缝接入 RAGFlow、Dify、FastGPT 等外部知识库服务。
- **全平台覆盖** —— 一套代码同时接入 QQ、微信、企业微信、飞书、钉钉、Discord、Telegram、Slack、LINE、KOOK、Matrix 等平台。
- **深度集成 Agent 平台** —— 原生对接 Dify、Coze、n8n、Langflow、Deerflow、阿里云百炼、蚂蚁百宝箱等编排与工作流平台。
- **技能（Skills）与代码沙箱** —— 按需激活的指令包，配合安全隔离的代码执行沙箱，让 Agent 真正"动手做事"。
- **MCP 协议** —— 作为客户端接入 Model Context Protocol 工具生态，支持 Stdio 与 HTTP 两种传输方式。
- **Web 管理面板** —— 在浏览器里可视化配置、管理、监控机器人，无需手动编辑配置文件。
- **生产级插件系统** —— 数百个社区插件，基于跨进程、事件驱动架构，安全且可热插拔。
- **多流水线架构** —— 一个实例运行多条流水线，不同机器人服务不同场景，具备访问控制、限速、敏感词过滤与全面监控。

## 即时通信平台支持性

LangBot 用统一的适配层覆盖全球主流即时通信平台，一次开发，多端触达。

| 平台        | 状态 | 备注                                                                                       |
| --------- | -- | ---------------------------------------------------------------------------------------- |
| QQ 个人号    | ✅  | 由支持 OneBot v11 协议的第三方应用端支持，覆盖私聊、群聊                                                       |
| QQ 官方机器人  | ✅  | 支持频道、私聊、群聊                                                                               |
| 微信        | ✅  | 个人微信                                                                                     |
| 微信公众号     | ✅  |                                                                                          |
| 企业微信      | ✅  | 内部应用消息                                                                                   |
| 企微智能机器人   | ✅  | 支持流式输出                                                                                   |
| 企微对外客服    | ✅  |                                                                                          |
| 飞书        | ✅  | 支持流式输出                                                                                   |
| 钉钉        | ✅  | 支持流式输出                                                                                   |
| Discord   | ✅  |                                                                                          |
| Telegram  | ✅  | 支持流式输出                                                                                   |
| Slack     | ✅  |                                                                                          |
| LINE      | ✅  |                                                                                          |
| KOOK      | ✅  |                                                                                          |
| Satori    | ✅  | [Satori](https://satori.chat/zh-CN/introduction.html) 是通用聊天协议，理论上支持 QQ、Zulip、米游社等 15+ 平台 |
| Matrix    | ✅  | 通过桥接可触达 Signal、WhatsApp、Messenger、iMessage、Mattermost、Google Chat、IRC、XMPP、Zulip 等       |
| Email（邮件） | ✅  | 以邮件作为对话通道                                                                                |
| 网页机器人     | ✅  | 可嵌入网页的对话窗口                                                                               |
| WhatsApp  | 🚧 | 开发中（也可经 Matrix 桥接使用）                                                                     |

🚧：正在开发中

各即时通信平台的细粒度功能支持性（收发图片、语音、文件、富文本、流式响应等）请查看[平台特性文档](https://langbot.app/docs/zh/insight/platform-features.md)。

## 模型与 Agent 平台支持性

LangBot 以 **LiteLLM 作为统一的模型请求后端**，因此除下表内置的供应商外，还可接入任意 OpenAI / Anthropic 接口格式或 LiteLLM 支持的模型。

### 大模型与聚合 / GPU 平台

| 供应商/服务                                                                              | 状态 | 备注                  |
| ----------------------------------------------------------------------------------- | -- | ------------------- |
| [OpenAI](https://platform.openai.com/)                                              | ✅  | 可接入任何 OpenAI 接口格式模型 |
| [Anthropic](https://www.anthropic.com/)                                             | ✅  |                     |
| [DeepSeek](https://www.deepseek.com/)                                               | ✅  |                     |
| [Google Gemini](https://aistudio.google.com/prompts/new_chat)                       | ✅  |                     |
| [xAI](https://x.ai/)                                                                | ✅  |                     |
| [Moonshot](https://www.moonshot.cn/)                                                | ✅  |                     |
| [智谱AI](https://open.bigmodel.cn/)                                                   | ✅  |                     |
| [Mistral](https://mistral.ai/)                                                      | ✅  |                     |
| [Groq](https://groq.com/)                                                           | ✅  |                     |
| [OpenRouter](https://openrouter.ai/)                                                | ✅  | 全球大模型聚合             |
| [Ollama](https://ollama.com/)                                                       | ✅  | 本地大模型运行平台           |
| [LMStudio](https://lmstudio.ai/)                                                    | ✅  | 本地大模型运行平台           |
| [SiliconFlow](https://siliconflow.cn/)                                              | ✅  | 大模型聚合平台             |
| [阿里云百炼](https://bailian.console.aliyun.com/)                                        | ✅  | 大模型聚合平台 / Agent 平台  |
| [火山方舟](https://console.volcengine.com/ark)                                          | ✅  | 大模型聚合平台 / Agent 平台  |
| [ModelScope](https://modelscope.cn/docs/model-service/API-Inference/intro)          | ✅  | 大模型聚合平台             |
| [GiteeAI](https://ai.gitee.com/)                                                    | ✅  | 大模型接口聚合平台           |
| [胜算云](https://www.shengsuanyun.com/?from=CH_KYIPP758)                               | ✅  | 全球大模型都可调用（友情推荐）     |
| [优云智算](https://www.compshare.cn/?ytag=GPU_YY-gh_langbot)                            | ✅  | 大模型和 GPU 资源平台       |
| [PPIO](https://ppio.com/user/register?invited_by=QJKFYD\&utm_source=github_langbot) | ✅  | 大模型和 GPU 资源平台       |
| [302.AI](https://share.302ai.cn/SuTG99)                                             | ✅  | 大模型聚合平台             |
| [接口 AI](https://jiekou.ai/)                                                         | ✅  | 大模型聚合平台             |
| [小马算力](https://www.tokenpony.cn/453z1)                                              | ✅  | 大模型聚合平台             |
| [七牛云](https://www.qiniu.com/ai/agent)                                               | ✅  | 大模型聚合平台             |

### Agent 平台

将已有的工作流或智能体直接接入即时通信平台，无需重写业务逻辑。

| 平台                                       | 状态 | 备注       |
| ---------------------------------------- | -- | -------- |
| [Dify](https://dify.ai)                  | ✅  | Agent 平台 |
| [Coze](https://coze.cn)                  | ✅  | 智能体编排平台  |
| [n8n](https://n8n.io/)                   | ✅  | 工作流自动化平台 |
| [Langflow](https://langflow.org/)        | ✅  | 可视化编排平台  |
| [Deerflow](https://deerflow.tech)        | ✅  | 深度研究框架   |
| [Weknora](https://weknora.weixin.qq.com) | ✅  | 微信知识库问答  |
| [蚂蚁百宝箱 TBox](https://tbox.cn/)           | ✅  | 智能体平台    |

### Rerank 重排序模型

| 供应商                                | 状态 | 备注        |
| ---------------------------------- | -- | --------- |
| [Cohere](https://cohere.com/)      | ✅  | Rerank 模型 |
| [Jina](https://jina.ai/)           | ✅  | Rerank 模型 |
| [Voyage AI](https://voyageai.com/) | ✅  | Rerank 模型 |

## LLM 应用范式实现

LangBot 把主流的 LLM 应用范式做成了开箱即用的能力，覆盖从"能聊天"到"能干活"的完整链路。

| 应用范式          | 状态 | 说明                                                                      |
| ------------- | -- | ----------------------------------------------------------------------- |
| Agent         | ✅  | 内置 Agent，支持工具调用、多轮推理、多模态与流式输出                                           |
| RAG（知识库）      | ✅  | 内置知识库引擎（默认 Chroma 向量库 + Rerank 重排序），并可经插件接入 RAGFlow、Dify、FastGPT 等外部知识库 |
| MCP           | ✅  | 作为 MCP 客户端接入工具生态，支持 Stdio 与 HTTP                                        |
| 技能（Skills）    | ✅  | 按需激活的指令包，匹配时才拉入上下文，零额外开销                                                |
| 代码沙箱（Sandbox） | ✅  | 安全隔离的代码执行环境，支持 Docker / nsjail / E2B 后端                                 |

- **技能（Skills）**：把一段专业流程、模板或脚本封装为按需激活的指令包，用户描述匹配时 Agent 才把它拉进上下文，不污染 System Prompt。详见[技能文档](https://langbot.app/docs/zh/usage/skills/readme.md)。
- **代码沙箱（Sandbox）**：为 Agent 提供安全隔离的代码执行能力，自动在 Docker / nsjail / E2B 后端中择优运行，是技能与原生工具的运行底座。详见[沙箱文档](https://langbot.app/docs/zh/usage/sandbox/readme.md)。

## 系统扩展性

LangBot 为二次开发与企业集成提供了完整的扩展面。

- **HTTP Service API**：通过基于 API Key 鉴权的 HTTP 接口访问 LangBot 的各类实体，便于与现有系统集成。
- **Outgoing Webhook**：将 LangBot 内部事件实时推送到外部系统，构建事件驱动的自动化。
- **生产级插件系统**：基于跨进程通信与异步技术实现，支持多种组件扩展，安全、稳定、可热插拔；数百个社区插件可在[扩展市场](https://space.langbot.app)一键安装。
- **Web 管理面板**：可视化完成机器人、模型、流水线、知识库、插件的全部配置与监控。

## 部署方式

LangBot 支持从一行命令到 Kubernetes 集群的多种部署方式：

- **LangBot Cloud（推荐）**：[免部署、开箱即用的托管版本](https://space.langbot.app/cloud)。
- **一键启动**：`uvx langbot`，随后访问 `http://localhost:5300`。
- **Docker Compose**、**宝塔面板**、**Kubernetes**、**Zeabur / Railway 一键云部署**等。

详见[部署文档](https://langbot.app/docs/zh/deploy/langbot/kubernetes.md)与[快速开始](https://langbot.app/docs/zh/insight/guide.md)。

## 案例截图

![LangBot 机器人配置页：在 Web 管理面板中将网页机器人绑定到流水线](https://langbot.app/docs/images/zh/insight/features/bot-page.png)

![LangBot 模型配置：接入 OpenAI、Anthropic 等任意 OpenAI / Anthropic 接口格式的大模型](https://langbot.app/docs/images/zh/insight/features/create-model.png)

![LangBot 流水线 AI 配置：选择内置 Agent 运行器与主模型](https://langbot.app/docs/images/zh/insight/features/edit-pipeline.png)

![LangBot 扩展市场：一键安装数百个社区插件与 MCP 工具](https://langbot.app/docs/images/zh/insight/features/plugin-market.png)

![LangBot 内置 Agent 调用代码沙箱：实时执行 Python 完成精确计算](https://langbot.app/docs/images/zh/insight/features/agent-sandbox.png)

![LangBot Skill 技能驱动 Agent：按预设技能输出结构化结果](https://langbot.app/docs/images/zh/insight/features/agent-skill.png)

---

# 欢迎访问 LangBot 文档

Source: https://langbot.app/docs/zh/insight/guide

LangBot 是开源的大模型机器人平台，将 Discord、Telegram、微信、Slack 等连接到 GPT、Claude、Gemini、DeepSeek 与 Dify。从这里开始。

LangBot 是一个**开源、生产级**的大语言模型（LLM）原生即时通信机器人平台。它把 OpenAI、Anthropic、Gemini、DeepSeek 等大模型，以及 Dify、Coze、n8n 等 Agent 平台，一站式接入 QQ、微信、企业微信、飞书、钉钉、Discord、Telegram、Slack 等全球主流即时通信平台。内置 Agent、RAG 知识库、MCP、技能（Skills）与代码沙箱，并提供开箱即用的 Web 管理面板——无需手写配置文件，几分钟即可让你的 AI 机器人上线。

![LangBot Web 管理面板仪表盘：实时监控消息量、模型调用、成功率、活跃会话与流量趋势](https://langbot.app/docs/images/zh/insight/dashboard-overview.png)

## 能用它做什么

- **智能客服 / 企业助手**：把基于知识库的 AI Agent 部署到微信、企微、飞书、钉钉，自动回答用户与员工的问题。
- **社群运营**：在 QQ、Discord、Telegram 群里提供 AI 驱动的问答、内容审核与互动。
- **工作流接入**：把已有的 Dify / n8n / Coze 工作流直接接到聊天平台，无需重写业务逻辑。
- **多平台触达**：一个机器人，覆盖所有平台，通过统一面板集中管理。

## 从这里开始

按下面的顺序了解 LangBot，再根据需要深入对应文档。

1. **了解功能与平台**：阅读[功能概览](https://langbot.app/docs/zh/insight/features.md)与[平台支持](https://langbot.app/docs/zh/insight/platform-features.md)，确认 LangBot 是否适合你的场景。
2. **选择部署方式**：使用 [LangBot Cloud](https://space.langbot.app/cloud) 免去自建服务，或通过 [Docker](https://langbot.app/docs/zh/deploy/langbot/docker.md)、[包管理器](https://langbot.app/docs/zh/deploy/langbot/package.md)自行部署。
3. **连接机器人与模型**：查看[配置机器人](https://langbot.app/docs/zh/usage/platforms/readme.md)、[配置对话模型](https://langbot.app/docs/zh/usage/models/readme.md)和[流水线](https://langbot.app/docs/zh/usage/pipelines/readme.md)，了解如何把聊天平台与 AI 能力连接起来。
4. **丰富机器人的能力**：通过[知识库](https://langbot.app/docs/zh/usage/knowledge/readme.md)、[插件](https://langbot.app/docs/zh/plugin/plugin-intro.md)、[MCP](https://langbot.app/docs/zh/usage/mcp/readme.md)与[技能](https://langbot.app/docs/zh/usage/skills/readme.md)扩展机器人。
5. **参考实践或参与开发**：从[实践文章](https://langbot.app/docs/zh/articles.md)寻找思路，或阅读[插件开发](https://langbot.app/docs/zh/plugin/dev/tutor.md)与[核心开发环境](https://langbot.app/docs/zh/develop/dev-config.md)。

遇到问题时，可以查阅[故障排除](https://langbot.app/docs/zh/insight/troubleshooting.md)，或到[社区](https://langbot.app/docs/zh/insight/community.md)交流。

> 让 AI Agent 帮你部署和使用:
>
> 将下面的提示词复制给你的 AI 助手。它会从官方文档开始，结合你的环境与目标协助操作。
>
> ```text
> 请帮助我部署和使用 LangBot，先阅读官方文档，再根据我的环境制定方案。
>
> 先读取中文文档索引 https://langbot.app/docs/zh/llms.txt ，并阅读以下关键文档：
> - 功能概览：https://langbot.app/docs/zh/insight/features.md
> - 平台支持：https://langbot.app/docs/zh/insight/platform-features.md
> - 机器人配置：https://langbot.app/docs/zh/usage/platforms/readme.md
> - 模型配置：https://langbot.app/docs/zh/usage/models/readme.md
> - 流水线：https://langbot.app/docs/zh/usage/pipelines/readme.md
>
> 先了解我想接入的聊天平台、使用的模型，以及是否已有 LangBot 实例。若需要部署，确认我的系统、服务器或本机环境，以及偏好云服务还是自部署；再从索引中读取对应的部署文档和平台接入文档，不要猜测命令或配置项。
>
> 根据文档帮助我完成部署、机器人连接、模型与流水线配置。若你有执行工具，在我授权的环境内执行并验证；否则给我适合当前环境的操作指导。已有实例请优先复用，涉及覆盖配置、删除数据或付费操作时先征求确认，不要让我在聊天中粘贴密钥。
>
> 最后帮助我发送一条真实测试消息，确认机器人能够回复。基础功能跑通后，再按需要引导我使用知识库、插件、MCP 或技能。文档无法读取或操作失败时请明确说明，不要把未验证的步骤说成已经完成。
> ```

> info:
>
> 这是 LangBot 4.0 的文档，3.0 文档请[访问](https://v3.langbot.app/docs)。

---

# 各消息平台特性支持性

Source: https://langbot.app/docs/zh/insight/platform-features

对比 LangBot 在各消息平台的功能支持：Discord、Telegram、微信、Slack、QQ、飞书、钉钉等。

以下是各平台我们已实现并测试的功能列表，如有预期之外的现象，欢迎即使反馈到[GitHub Issues](https://github.com/langbot-app/LangBot/issues) 或直接提出 Pull Request 帮助修复。

## OneBot v11

### 接收

| 功能点           | 状态 | 备注      |
| ------------- | -- | ------- |
| 接收私聊消息        | ✅  |         |
| 接收群聊提及消息      | ✅  |         |
| 接收群聊普通消息      | ✅  |         |
| 接收图片消息        | ✅  |         |
| 接收语音消息        | ✅  |         |
| 接收文件消息        | ✅  |         |
| 接收富文本消息       | ✅  | 文本和图片结合 |
| 获取私聊消息事件用户名称  | ✅  |         |
| 获取群聊消息事件群聊名称  | ✅  |         |
| 获取群聊消息事件发送者名称 | ✅  |         |

### 发送

| 功能点     | 状态 | 备注      |
| ------- | -- | ------- |
| 回复私聊消息  | ✅  |         |
| 回复群聊消息  | ✅  |         |
| 回复图片消息  | ✅  |         |
| 回复语音消息  | ✅  |         |
| 回复文件消息  | ✅  |         |
| 回复富文本消息 | ✅  | 文本和图片结合 |
| 发送主动消息  | ✅  |         |
| 发送流式响应  | ❌  |         |

## QQ 官方机器人

## 企业微信（内部应用）

### 接收

| 功能点           | 状态 | 备注          |
| ------------- | -- | ----------- |
| 接收私聊消息        | ✅  |             |
| 接收群聊提及消息      | ❌  | 企微内部应用不支持拉群 |
| 接收群聊普通消息      | ❌  |             |
| 接收图片消息        | ✅  |             |
| 接收语音消息        | ✅  |             |
| 接收文件消息        | ✅  |             |
| 接收富文本消息       | ❌  |             |
| 获取私聊消息事件用户名称  | ✅  |             |
| 获取群聊消息事件群聊名称  | ❌  |             |
| 获取群聊消息事件发送者名称 | ❌  |             |

### 发送

| 功能点     | 状态 | 备注 |
| ------- | -- | -- |
| 回复私聊消息  | ✅  |    |
| 回复群聊消息  | ❌  |    |
| 回复图片消息  | ✅  |    |
| 回复语音消息  | ✅  |    |
| 回复文件消息  | ✅  |    |
| 回复富文本消息 | ❌  |    |
| 发送主动消息  | ✅  |    |
| 发送流式响应  | ❌  |    |

## Satori

### 接收

| 功能点           | 状态 | 备注      |
| ------------- | -- | ------- |
| 接收私聊消息        | ✅  |         |
| 接收群聊提及消息      | ✅  |         |
| 接收群聊普通消息      | ✅  |         |
| 接收图片消息        | ✅  |         |
| 接收语音消息        | ✅  |         |
| 接收文件消息        | ✅  |         |
| 接收富文本消息       | ✅  | 文本和图片结合 |
| 获取私聊消息事件用户名称  | ✅  |         |
| 获取群聊消息事件群聊名称  | ✅  |         |
| 获取群聊消息事件发送者名称 | ✅  |         |

### 发送

| 功能点     | 状态 | 备注      |
| ------- | -- | ------- |
| 回复私聊消息  | ✅  |         |
| 回复群聊消息  | ✅  |         |
| 回复图片消息  | ✅  |         |
| 回复语音消息  | ✅  |         |
| 回复文件消息  | ✅  |         |
| 回复富文本消息 | ✅  | 文本和图片结合 |
| 发送主动消息  | ✅  |         |
| 发送流式响应  | ❌  |         |

## 企业微信（对外客服）

## 企业微信智能机器人

## 微信公众号

## 飞书

### 接收

| 功能点           | 状态 | 备注              |
| ------------- | -- | --------------- |
| 接收私聊消息        | ✅  |                 |
| 接收群聊提及消息      | ✅  |                 |
| 接收群聊普通消息      | ❌  | 飞书仅支持接收提及机器人的消息 |
| 接收图片消息        | ✅  |                 |
| 接收语音消息        | ❌  | 飞书无语音消息         |
| 接收文件消息        | ✅  |                 |
| 接收富文本消息       | ✅  | 文本和图片结合         |
| 获取私聊消息事件用户名称  | ❌  | 飞书不支持获取用户名称     |
| 获取群聊消息事件群聊名称  | ❌  | 飞书不支持获取群聊名称     |
| 获取群聊消息事件发送者名称 | ❌  | 飞书不支持获取发送者名称    |

### 发送

| 功能点     | 状态 | 备注 |
| ------- | -- | -- |
| 回复私聊消息  | ✅  |    |
| 回复群聊消息  | ✅  |    |
| 回复图片消息  | ✅  |    |
| 回复语音消息  | ❌  |    |
| 回复文件消息  | ❌  |    |
| 回复富文本消息 | ❌  |    |
| 发送主动消息  | ✅  |    |
| 发送流式响应  | ✅  |    |

## 钉钉

### 接收

| 功能点           | 状态 | 备注              |
| ------------- | -- | --------------- |
| 接收私聊消息        | ✅  |                 |
| 接收群聊提及消息      | ✅  |                 |
| 接收群聊普通消息      | ❌  | 钉钉仅支持接收提及机器人的消息 |
| 接收图片消息        | ✅  |                 |
| 接收语音消息        | ✅  |                 |
| 接收文件消息        | ✅  |                 |
| 接收富文本消息       | ✅  | 文本和图片结合         |
| 获取私聊消息事件用户名称  | ✅  |                 |
| 获取群聊消息事件群聊名称  | ✅  |                 |
| 获取群聊消息事件发送者名称 | ✅  |                 |

### 发送

| 功能点     | 状态 | 备注      |
| ------- | -- | ------- |
| 回复私聊消息  | ✅  |         |
| 回复群聊消息  | ✅  |         |
| 回复图片消息  | ✅  |         |
| 回复语音消息  | ❌  |         |
| 回复文件消息  | ❌  |         |
| 回复富文本消息 | ✅  | 文本和图片结合 |
| 发送主动消息  | ✅  |         |
| 发送流式响应  | ✅  |         |

## KOOK

P.S. 发送语音和文件报错未修

### 接收

| 功能点           | 状态 | 备注      |
| ------------- | -- | ------- |
| 接收私聊消息        | ✅  |         |
| 接收群聊提及消息      | ✅  |         |
| 接收群聊普通消息      | ✅  |         |
| 接收图片消息        | ✅  |         |
| 接收语音消息        | ✅  |         |
| 接收文件消息        | ✅  |         |
| 接收富文本消息       | ✅  | 文本和图片结合 |
| 获取私聊消息事件用户名称  | ✅  |         |
| 获取群聊消息事件群聊名称  | ✅  |         |
| 获取群聊消息事件发送者名称 | ✅  |         |

### 发送

| 功能点     | 状态 | 备注            |
| ------- | -- | ------------- |
| 回复私聊消息  | ✅  |               |
| 回复群聊消息  | ✅  |               |
| 回复图片消息  | ✅  |               |
| 回复语音消息  | ❌  | KOOK不支持回复语音消息 |
| 回复文件消息  | ❌  |               |
| 回复富文本消息 | ✅  | 文本和图片结合       |
| 发送主动消息  | ✅  |               |
| 发送流式响应  | ❌  |               |

## Discord

### 接收

| 功能点           | 状态 | 备注      |
| ------------- | -- | ------- |
| 接收私聊消息        | ✅  |         |
| 接收群聊提及消息      | ✅  |         |
| 接收群聊普通消息      | ✅  |         |
| 接收图片消息        | ✅  |         |
| 接收语音消息        | ❌  |         |
| 接收文件消息        | ✅  |         |
| 接收富文本消息       | ✅  | 文本和图片结合 |
| 获取私聊消息事件用户名称  | ✅  |         |
| 获取群聊消息事件群聊名称  | ✅  |         |
| 获取群聊消息事件发送者名称 | ✅  |         |

### 发送

| 功能点     | 状态 | 备注      |
| ------- | -- | ------- |
| 回复私聊消息  | ✅  |         |
| 回复群聊消息  | ✅  |         |
| 回复图片消息  | ✅  | 作为文件携带  |
| 回复语音消息  | ✅  | 作为文件携带  |
| 回复文件消息  | ✅  |         |
| 回复富文本消息 | ✅  | 文本和文件结合 |
| 发送主动消息  | ✅  |         |
| 发送流式响应  | ❌  |         |

## Telegram

P.S. 未测试

### 接收

| 功能点           | 状态 | 备注 |
| ------------- | -- | -- |
| 接收私聊消息        | ✅  |    |
| 接收群聊提及消息      | ✅  |    |
| 接收群聊普通消息      | ✅  |    |
| 接收图片消息        | ✅  |    |
| 接收语音消息        | ❌  |    |
| 接收文件消息        | ✅  |    |
| 接收富文本消息       | ✅  |    |
| 获取私聊消息事件用户名称  | ✅  |    |
| 获取群聊消息事件群聊名称  | ✅  |    |
| 获取群聊消息事件发送者名称 | ✅  |    |

### 发送

| 功能点     | 状态 | 备注 |
| ------- | -- | -- |
| 回复私聊消息  | ✅  |    |
| 回复群聊消息  | ✅  |    |
| 回复图片消息  | ✅  |    |
| 回复语音消息  | ✅  |    |
| 回复文件消息  | ✅  |    |
| 回复富文本消息 | ✅  |    |
| 发送主动消息  | ✅  |    |
| 发送流式响应  | ❌  |    |

## Slack

## LINE

---

# 故障排查

Source: https://langbot.app/docs/zh/insight/troubleshooting

收集 LangBot 本地部署和使用过程中的常见故障、症状、原因与解决办法；当前包含 Docker 部署问题。

本文用于集中记录常见故障的排查路径。当前先覆盖 Docker 部署时容易遇到的问题，后续可以继续补充模型、机器人适配器、MCP、Skill 等章节。

以下命令默认在 `LangBot/docker` 目录执行。

## Docker 部署

### 启动前快速确认

需要使用沙箱、stdio MCP 托管、Skill 添加/编辑等能力时，请使用 `all` profile 启动：

```bash
docker compose --profile all up -d
```

确认服务状态：

```bash
docker compose --profile all ps
```

正常情况下应看到：

- `langbot`：WebUI 和后端服务，默认映射 `5300` 和 `2280-2285`。
- `langbot_plugin_runtime`：插件运行时，默认映射 `5401`。
- `langbot_box`：Box Runtime 控制面，用于创建沙箱容器。

如果只运行 `docker compose up`，不会启动 `langbot_box`，stdio MCP、Skill 添加/编辑和部分沙箱能力将不可用。

### 端口被占用

#### 症状

- `docker compose up` 报端口绑定失败。
- WebUI 无法访问 `http://127.0.0.1:5300`。
- 日志中出现 `port is already allocated`、`bind: address already in use` 等信息。

#### 处理方式

先确认占用端口的进程。Linux/macOS：

```bash
lsof -i :5300
lsof -i :5401
```

Windows PowerShell：

```powershell
Get-NetTCPConnection -LocalPort 5300,5401 | Select-Object LocalPort,OwningProcess
Get-Process -Id <PID>
```

如果确认是旧的 LangBot、插件运行时或测试进程，可以停止该进程后重新启动：

```bash
docker compose --profile all up -d
```

如果不能停止占用进程，请修改 `docker-compose.yaml` 中对应端口映射，避免与现有服务冲突。

### Box Runtime 未启动或不可用

#### 症状

- 页面或日志提示 `No sandbox backend (Docker/nsjail/E2B) is ready`。
- stdio 模式 MCP 一直不可用。
- Skill 无法安装、激活或编辑。

#### 常见原因

- 没有使用 `--profile all` 或 `--profile box` 启动。
- `langbot_box` 没有运行。
- 当前用户或 Docker Desktop 无法访问 Docker。
- Linux 主机上当前用户没有 Docker socket 权限。

#### 处理方式

确认 `langbot_box` 已启动：

```bash
docker compose --profile all ps
docker logs langbot_box --tail 100
```

确认 Docker 可用：

```bash
docker info
```

Linux 上如果当前用户不能访问 Docker，可加入 `docker` 用户组后重新登录：

```bash
sudo usermod -aG docker $USER
newgrp docker
docker info
```

之后重新创建容器：

```bash
docker compose --profile all up -d --force-recreate
```

### Box 根目录挂载失败

#### 症状

- 日志中出现 `host_path is outside allowed_mount_roots`。
- 日志中出现 `host_path must point to an existing directory on the host`。
- Docker Desktop 环境中，Box 根目录被解析为 `/run/desktop/...` 后被拒绝。
- stdio MCP 或 Skill 相关沙箱容器无法创建。

#### 原因

`langbot_box` 会通过宿主机 Docker socket 创建沙箱容器。沙箱容器看到的是宿主机路径，因此 Box 根目录的“宿主机路径”和“容器内路径”必须保持一致，并且该路径必须位于 `allowed_mount_roots` 内。

#### 处理方式

在 `LangBot/docker/.env` 中设置一个 Docker 能挂载、且不会被 Box 安全规则拒绝的绝对路径：

```dotenv
LANGBOT_BOX_ROOT=/var/lib/langbot/box
```

Windows Docker Desktop 可以使用 Docker VM 可识别的路径，例如：

```dotenv
LANGBOT_BOX_ROOT=/host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
```

确保目录存在后重建容器：

```bash
docker compose --profile all up -d --force-recreate
```

如果之前已经手动修改过 `docker/data/config.yaml`，请同步检查：

```yaml
box:
  local:
    host_root: /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
    allowed_mount_roots:
      - /host_mnt/c/Users/<user>/code/projects/langbot/LangBot/docker/data/box
```

### 大量 stdio MCP 启动失败或长时间 connecting

#### 症状

- MCP 状态停留在 `connecting` 或变为 `error`。
- `docker logs langbot_box` 中出现 `Cannot fork`。
- 同时安装较多 stdio 模式 MCP 后，原本可用的 MCP 也开始启动失败。

#### 原因

stdio MCP 会运行在 Box 沙箱中。默认 Box profile 的 PID 限制较低，同时启动多个 `npx`、`uvx` MCP 时可能达到沙箱进程数限制。

#### 处理方式

在 `docker/data/config.yaml` 中把 Box profile 调整为资源更高的内置 profile：

```yaml
box:
  local:
    profile: network_extended
```

然后停止 LangBot 和 Box，删除旧共享沙箱，让新配置生效。

Linux/macOS：

```bash
docker compose --profile all stop langbot langbot_box
docker rm -f $(docker ps -aq --filter "name=langbot-box-mcp-shared")
docker compose --profile all up -d --force-recreate
```

Windows PowerShell：

```powershell
docker compose --profile all stop langbot langbot_box
docker ps -a --filter "name=langbot-box-mcp-shared" --format "{{.Names}}" | ForEach-Object { docker rm -f $_ }
docker compose --profile all up -d --force-recreate
```

等待 MCP 冷启动完成后，在 MCP 管理页面确认状态为 `connected`，并检查工具数量是否大于 `0`。

### MCP 已安装但没有工具或无法连接

#### 症状

- MCP 已出现在列表中，但状态是 `error` 或长期 `connecting`。
- 工具数量为 `0`。
- 远程 MCP 日志中出现 `401 Unauthorized`、连接超时或握手失败。

#### 常见原因

- 远程 MCP 需要 API Key 或 OAuth 授权，但未配置。
- MCP 包首次通过 `npx` 或 `uvx` 冷启动，依赖下载时间较长。
- 当前 Docker 网络无法访问对应 MCP 服务或包仓库。
- stdio MCP 沙箱资源不足。

#### 处理方式

优先在 LangBot Space 中选择无需密钥或已正确配置密钥的 MCP。对于需要密钥的 MCP，请在安装配置中补齐环境变量、请求头或 URL 参数。

查看运行时日志：

```bash
docker logs langbot --tail 200
docker logs langbot_box --tail 200
```

如果确认某个 MCP 无法在当前环境连接，请在 MCP 管理页面禁用或删除它，避免影响排查结果。

### 镜像标签或镜像源不一致

#### 症状

- `docker compose ps` 显示服务仍在使用旧镜像。
- 修改了镜像源或标签后，重启仍未生效。
- `langbot`、`langbot_plugin_runtime`、`langbot_box` 使用了不同镜像标签。

#### 处理方式

保持三个 LangBot 服务的镜像标签一致，然后重新拉取并重建：

```bash
docker pull rockchin/langbot:latest
docker compose --profile all up -d --force-recreate
```

如果你明确需要部署其他标签，请确保 `docker-compose.yaml` 中 `langbot`、`langbot_plugin_runtime`、`langbot_box` 三处镜像同时修改。

### 部署后验证

完成修复后建议做一次完整检查：

```bash
docker compose --profile all ps
docker inspect langbot langbot_plugin_runtime langbot_box --format '{{.Name}} {{.Config.Image}} {{.State.Status}}'
```

确认 WebUI 可访问：

```bash
curl -I http://127.0.0.1:5300/
```

在页面中继续确认：

- 可以正常登录。
- Box / 沙箱能力可用。
- MCP 列表中的目标 MCP 状态为 `connected`。
- stdio MCP 的工具数量正常显示。

---

# 认证插件与共享运行

Source: https://langbot.app/docs/zh/plugin/certified-plugins

认证是什么、为什么存在、什么时候需要，以及 shared-runtime-v1 / stateless-v1 的适配规范。

## 认证是什么

认证是 LangBot 对**一份精确、不可变的插件制品**授予的资格：该制品被批准在 LangBot Cloud 中**跨租户共享运行**。

- 认证绑定到制品本身（已发布的具体版本，按 digest 区分），不是绑定到插件名或作者。同一个插件发布新版本后，上一版的认证不会自动延续。
- 认证不是质量评分，也不是安全审计背书。

## 为什么需要认证

平台默认**不**让插件共享运行。这是因为共享的粒度是制品：

- **专属模式**：插件不参与共享，独立运行。
- **共享模式**：同一个 artifact digest 的所有安装共用一个 Worker。

共享的好处是进程数量和启动开销不随安装数线性增长。代价是**一个进程里会同时处理多个工作区的调用**——如果插件把租户数据放在实例上，就会在租户之间串数据。

所以平台需要先对这份制品做代码审查、确认它满足无状态约束，再用签名把"对这份制品的信任"固定下来，才敢让它进入共享放置。这就是认证存在的原因。

## 什么情况下需要认证

**大多数插件不需要认证。** 不认证不影响你把插件发布到插件市场，也不影响用户安装使用——插件会以专属模式正常运行。

| 你的情况                          | 是否需要认证        |
| ----------------------------- | ------------- |
| 只想把插件发布到插件市场供用户使用             | 不需要           |
| 插件需要在进程内保留跨调用状态（例如常驻的外部会话进程）  | 不需要，也应该保持专属运行 |
| 插件里有后台任务、定时器，或长期缓存租户数据        | 不需要，保持专属模式更安全 |
| 希望获得认证插件标识                    | 需要            |
| 希望同一制品的多个安装共用一个进程，降低资源与启动开销   | 需要            |
| 插件面向 Cloud 多租户场景，希望被平台以共享方式放置 | 需要            |

判断标准只有一条：**只有当你的代码确实能做到"实例上不保存任何租户或安装相关数据"时，认证才有意义。**

## 认证之后的效果

通过审核后：

- 制品被签入证书，安装时以**共享模式**运行；同一 digest 的多个安装共用一个 Worker。
- 该 Worker 中只有一个 `BasePlugin` 实例，以及每个已声明组件 manifest 各一个实例（EventListener、Tool、Command、KnowledgeEngine、Parser、Page、Runner）。
- 每个安装只额外保留一份轻量的配置、权限与生命周期上下文，调用时由当前请求决定使用哪一份。
- 你会获得认证插件标识。
- 自托管 OSS 默认不配置认证签发方公钥，因此即使是带认证的制品，在自托管实例上仍以专属模式运行。

同时你也承担一项长期义务：**后续每个版本都必须继续满足无状态约束**。修改代码后需要提交新版本重新审核，认证不会自动延续。

## 需要做的适配与规范

### 声明

在 `manifest.yaml` 的 `execution` 下同时声明两个字段：

```yaml
apiVersion: v1
kind: Plugin
metadata:
  author: your-name
  name: YourPlugin
  version: 0.1.1
spec:
  config: []
  components: {}
execution:
  python:
    path: main.py
    attr: YourPlugin
  sharedRuntime: shared-runtime-v1
  componentModel: stateless-v1
```

| 字段                         | 合法值                 | 说明                     |
| -------------------------- | ------------------- | ---------------------- |
| `execution.sharedRuntime`  | `shared-runtime-v1` | 只接受这一个值，填写其他值会导致清单校验失败 |
| `execution.componentModel` | `stateless-v1`      | 只接受这一个值                |

- 两个字段**必须同时声明**。只写 `sharedRuntime` 不写 `componentModel` 的包会在认证校验阶段被拒绝。
- 这两个字段自 **SDK 0.7.0** 起被识别；更早的 SDK 会忽略它们，因此不要用旧版本验证声明是否生效。

> warning:
>
> 声明只是申请，不等于通过认证。它本身不会授予认证标识，也不会改变运行模式。

### 无状态组件规范

- `BasePlugin.initialize()` 和组件 `initialize()` 是**进程级**初始化，每个 Worker 只执行一次。此时不存在"当前安装"，也不存在"当前工作区"。
- 组件实例会被不同工作区并发调用，因此所有方法都必须可重入。
- 读取当前安装的配置：`BasePlugin` 用 `self.get_config()`，组件用 `self.get_plugin_config()` 或 `self.plugin.get_config()`，Runner 可以直接用 `ctx.config`。
- 不得把配置、凭据、工作区或安装标识、请求数据保存在实例字段或模块级全局变量中。
- 不得在 `initialize()` 中读取并缓存安装配置。
- 存储、文件、凭据、日志、模型等平台能力必须通过 SDK 的 Host API 访问；权限由当前调用自动解析，不需要也不应该自己缓存。
- 需要跨调用保留的租户数据必须存放在 Host 服务中。Runner 使用 `ctx.state_get()` / `ctx.state_set()` 等接口（需要 `ctx.context.available_apis.state` 为 `true`）。进程内缓存只允许存放制品级公共数据；如果确实要缓存租户数据，键必须包含完整安装标识，并能在安装被移除时清理。
- 不要发起携带租户数据的后台任务或线程：SDK **不跟踪**你自己创建的任务的所有权。如果确实要脱离处理函数运行，请以安装绑定为键维护一份登记表，并在 `on_installation_revoked()` 中停止它们。处理函数返回后，本次调用的上下文和运行关联调用即失效。

### 一个安装，多份用法

一个 workspace 内每个插件只安装一次，但同一份安装会被**多个产品对象**复用：

| 组件类型                                  | 复用它的是         | 隔离靠什么                                                          |
| ------------------------------------- | ------------- | -------------------------------------------------------------- |
| Agent / 流水线中的 Runner                  | 每个处理器         | `ctx.state.*` 已按处理器隔离（作用域含 `binding_identity`，由 Agent UUID 派生） |
| 知识库用的 KnowledgeEngine / Parser        | 每个知识库         | **需要插件自己按知识库 ID 隔离**                                           |
| Tool / Command / EventListener / Page | 多个处理器、会话或页面请求 | 依赖调用时读取，不能在实例上累积                                               |

平台的插件存储键是 `(实例, 工作区, 组件类型, 插件名, key)`，**不包含处理器或知识库维度**。所以只要你的插件要持久化或缓存，就必须自己把产品对象的身份拼进键里：

- **配置**：每次调用读取（`ctx.config`，或 task-local 的 `self.get_plugin_config()`），不要缓存到实例。
- **持久化**：键必须包含产品对象身份（处理器身份 / 知识库 ID / 会话身份）。
- **进程内缓存**：键必须同时包含完整安装绑定**和**产品对象身份，并在安装被撤销时释放（见下）。
- **锁与栅栏**：必须按 `(安装, 产品对象)` 记。**一个处理器或知识库的失败，不得阻断同一安装下的其他对象。**
- **失败分级**：只有"已经派发、结果未知"的变更才应进入需要人工对账的状态；确定性的校验错误和调用前的取消不应影响后续调用。
- **日志与遥测**：诊断数据的失败不得影响业务，也不要把租户数据写进进程级单例。

### 安装被撤销时

共享模式下，一个进程内只有一个对象图，服务同一制品的所有安装。所以**某个安装被撤销时对象图不会销毁**，插件必须自己释放按安装绑定记的进程内状态：

```python
class MyPlugin(BasePlugin):
    def __init__(self) -> None:
        super().__init__()
        self._caches: dict[str, Cache] = {}

    async def on_installation_revoked(self, binding) -> None:
        self._caches.pop(binding.installation_uuid, None)
```

- **触发时机**：卸载、停用、移除工作区，以及**升级**（旧绑定被撤销）。只有共享模式会调用；专属模式下进程会被关停，进程内状态随进程消失。
- **调用时没有调用上下文**，Host API（存储、配置、绑定查询）不可用——只能释放进程内状态，安装身份由参数给出。
- 抛出异常会被记录，**不影响撤销流程**。
- 需要带 `BasePlugin.on_installation_revoked` 的 SDK 版本；旧版本上这个钩子只是永远不会被调用。

### 允许 / 禁止对照

| 场景             | 允许                                               | 禁止                              |
| -------------- | ------------------------------------------------ | ------------------------------- |
| 读取配置           | 每次调用时读取（`self.get_plugin_config()`、`ctx.config`） | 在 `initialize()` 中读取后保存到 `self` |
| 连接池 / HTTP 客户端 | 不含租户凭据的共享连接池                                     | 把安装的 endpoint、api key 固化到实例上    |
| 缓存             | 制品级公共数据；或键为完整安装标识且支持清理                           | 模块级 `dict` 以工作区或用户为键长期驻留        |
| 跨调用状态          | Host 服务（Runner 用 `ctx.state_*`）                  | 实例字段、模块级全局变量                    |
| 后台工作           | 无                                                | 处理函数返回后继续持有本次上下文或其关联调用          |
| 日志             | `ctx.log()` 或 SDK 日志 API                         | 模块级后台线程直接输出租户配置或凭据              |

### 常见反例

**1. 在初始化时读取安装配置**

```python
async def initialize(self):
    self.endpoint = self.plugin.config["endpoint"]  # 进程级初始化，没有当前安装
    self.api_key = self.plugin.config["api_key"]
```

共享初始化阶段没有安装配置，这段代码只会读到空值或上一次的值。

**2. 把租户数据放进模块级缓存**

```python
_CACHE = {}  # 以工作区或用户为键，会跨安装、跨租户长期驻留

async def call(self, params, **kwargs):
    if params["user"] not in _CACHE:
        _CACHE[params["user"]] = await fetch(params["user"])
```

**3. 处理函数返回后继续使用本次调用**

```python
async def call(self, params, **kwargs):
    config = self.get_plugin_config()
    asyncio.create_task(self._upload_later(config))  # 处理函数已返回，上下文与授权均已失效
    return ok()
```

**4. 把实例字段当作配置容器**

```python
async def initialize(self):
    self.default_endpoint = "https://api.example.com"  # 公共常量没有问题
    self.last_config = {}  # 一旦写入安装配置就违规
```

正确写法：

```python
class LookupTool(Tool):
    async def initialize(self):
        # 只放置制品级、不含租户信息的对象
        self.transport = StatelessHTTPTransport()

    async def call(self, params, **kwargs):
        config = self.get_plugin_config()  # 每次调用按当前安装读取
        return await self.transport.lookup(config["endpoint"], params)
```

### Runner 组件特别注意

Runner 与无状态约束的张力最大，因为运行器天然倾向于在进程内保存会话与上下文。

- `RunnerContext` **只在本次运行期间有效**，不要把它或它的字段保存到实例上跨调用复用。
- Runner 需要跨调用保留的会话状态，走 `ctx.state_get()` / `ctx.state_set()`（作用域支持 `conversation`、`actor`、`subject`、`runner`）或 Host 提供的其他存储，不要使用实例字段。
- 处理函数返回后，不要继续在后台任务中使用 `ctx`，也不要继续使用通过 `self.plugin` 发起的运行关联调用。
- 如果 Runner 的设计必须依赖进程内持有的跨调用状态（例如需要长期驻留的外部会话进程），**不要声明 `stateless-v1`**，继续以专属 Worker 运行即可。

运行上下文的完整接口见[运行上下文（RunnerContext）](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md)。

## 自检与提交

提交审核前逐条核对：

- [ ] `manifest.yaml` 中两个字段都已声明，取值正确。
- [ ] 全文搜索，确认没有模块级可变全局变量。
- [ ] 确认 `initialize()` 只做进程级初始化，不读取安装配置。
- [ ] 确认所有安装配置都在调用时读取。
- [ ] 确认没有在处理函数返回后继续运行的任务或线程。
- [ ] 确认跨调用状态通过 Host API 保存（Runner 使用 `ctx.state_*`）。

### 提交方式

认证与发布走同一条链路，不需要额外流程：在 `manifest.yaml` 中声明上面两个字段，然后照常用 `lbp publish` 提交一个**新版本**（已发布的版本无法追加声明）。LangBot Space 会检查本次提交的精确插件包，进行辅助代码审查，并在人工批准后签发认证插件标识；认证绑定到已审核的版本与校验和。

如果审核发现该版本无法满足要求，请先把它作为未签名的普通插件发布，并在后续不可变版本中修复问题。

如果核对下来发现插件并不适合共享运行，直接以普通插件提交即可，不需要认证。发布流程见[发布到插件市场](https://langbot.app/docs/zh/plugin/dev/publish/market.md)。

---

# 系统兼容处理

Source: https://langbot.app/docs/zh/plugin/compatibility

LangBot 插件系统运用了`Asyncio`和`Subprocess`等机制，这在unix-like系统（如Linux、MacOS）上运行良好，但在Windows上存在一些问题，导致插件无法正常运行。

Windows 上的 Python 异步事件循环默认使用 `ProactorEventLoop`，但该事件循环对 Stdio 的支持性缺失，而非 Docker 环境下 LangBot 依赖 Stdio 与 Plugin Runtime 通信、Plugin Runtime 也依赖 Stdio 与插件通信。

若改为使用`SelectorEventLoop`，则会导致无法正常启动 Plugin Runtime 和插件，因为`SelectorEventLoop`不支持`Subprocess`。

详细问题参阅：[Python官方文档](https://docs.python.org/zh-cn/3.13/library/asyncio-platforms.html)

## 解决方案

与 Unix-like 系统上的子进程管理与 Stdio 通信绑定的形式不同，LangBot 和 Plugin Runtime 在 Windows 上会自动采用 子进程 + WebSocket 结合的跨进程通信技术，LangBot 通过子进程启动 Plugin Runtime 但通过 WebSocket 与其通信；Plugin Runtime 也通过子进程启动各个已安装插件但通过 WebSocket 通信。

这是 LangBot 根据系统标识自动适应的，您无需手动配置。

---

# 上下文 API

Source: https://langbot.app/docs/zh/plugin/dev/apis/agent-run

上下文保存当前一次组件调用的数据。不同组件接收的上下文不同，请先按组件找到对应入口。

| 组件                 | 处理函数入口                                | 上下文类型                                 |
| ------------------ | ------------------------------------- | ------------------------------------- |
| EventListener      | `handler(event_context)`              | `EventContext`                        |
| Command            | `subcommand(context)`                 | `ExecuteContext`                      |
| Tool               | `call(params, session, query_id)`     | 无独立上下文对象                              |
| 运行器                | `run(ctx)` 或 `handler(ctx)`           | `RunnerContext`                       |
| KnowledgeEngine    | `ingest(context)`、`retrieve(context)` | `IngestionContext`、`RetrievalContext` |
| KnowledgeRetriever | `retrieve(context)`                   | `RetrievalContext`                    |
| Parser             | `parse(context)`                      | `ParseContext`                        |
| Page               | `handle_api(request)`                 | `PageRequest`                         |

本页只介绍上下文中的数据和方法。模型、知识库、存储等 LangBot 能力统一通过 `self.plugin` 调用，见 [LangBot API](https://langbot.app/docs/zh/plugin/dev/apis/common.md)；平台操作见[平台 API](https://langbot.app/docs/zh/plugin/dev/apis/platform.md)。

`EventContext`、`ExecuteContext` 和 `Session` 还会携带 `instance_uuid`、`workspace_uuid` 和 `placement_generation`。这些字段用于标识当前执行所在的实例和工作区，不应作为插件自行鉴权的依据。

## EventListener

EventListener 处理流水线事件。事件处理函数接收 `EventContext`：

```python
event = event_context.event
sender_id = event.sender_id
```

### 上下文数据

| 属性                     | 类型               | 说明                                    |
| ---------------------- | ---------------- | ------------------------------------- |
| `event`                | `BaseEventModel` | 当前事件对象，实际类型与注册的事件类型一致                 |
| `event_name`           | `str`            | 当前事件类名                                |
| `query_id`             | `int`            | 当前流水线请求 ID                            |
| `query_uuid`           | `str \| None`    | 当前流水线请求的稳定标识                          |
| `eid`                  | `int`            | Plugin Runtime 内的临时事件编号，不应持久化         |
| `is_prevent_default`   | `bool`           | 是否已阻止默认处理；通过 `prevent_default()` 修改   |
| `is_prevent_postorder` | `bool`           | 是否已阻止后续插件；通过 `prevent_postorder()` 修改 |

事件对象的字段和所有可监听事件见[流水线事件](https://langbot.app/docs/zh/plugin/dev/apis/pipeline-events.md)。

### 上下文方法

| 方法                                                                                 | 返回值                    | 说明                         |
| ---------------------------------------------------------------------------------- | ---------------------- | -------------------------- |
| `await event_context.reply(message_chain, quote_origin=False)`                     | -                      | 回复当前请求所在会话                 |
| `await event_context.get_bot_uuid()`                                               | `str`                  | 获取当前请求来源机器人 UUID           |
| `await event_context.set_query_var(key, value)`                                    | -                      | 设置当前请求变量                   |
| `await event_context.get_query_var(key)`                                           | `Any`                  | 获取一个请求变量                   |
| `await event_context.get_query_vars()`                                             | `dict[str, Any]`       | 获取全部请求变量                   |
| `await event_context.create_new_conversation()`                                    | `dict[str, Any]`       | 清除流水线当前使用的对话，后续请求会创建新对话    |
| `await event_context.list_pipeline_knowledge_bases()`                              | `list[dict[str, Any]]` | 列出当前流水线 Local Agent 绑定的知识库 |
| `await event_context.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)` | `list[dict[str, Any]]` | 检索当前流水线已绑定的知识库             |
| `event_context.prevent_default()`                                                  | -                      | 阻止当前事件的默认处理                |
| `event_context.prevent_postorder()`                                                | -                      | 阻止后续插件继续处理当前事件             |

`reply()` 使用 [MessageChain](https://langbot.app/docs/zh/plugin/dev/apis/messages.md)。请求变量、回复和流水线知识库方法依赖当前请求；没有关联请求的事件不能调用这些方法。`retrieve_knowledge()` 的 `kb_id` 必须来自 `list_pipeline_knowledge_bases()`。

`prevent_default()` 只对支持中止默认流程的流水线事件生效，具体事件见[流水线事件](https://langbot.app/docs/zh/plugin/dev/apis/pipeline-events.md#阻止默认行为)。

## Command

Command 的子命令处理函数接收 `ExecuteContext`：

```python
query = " ".join(context.crt_params)
session = context.session
```

### 上下文数据

| 属性                  | 类型            | 说明           |
| ------------------- | ------------- | ------------ |
| `session`           | `Session`     | 当前消息所属会话     |
| `command_text`      | `str`         | 去掉命令前缀后的完整文本 |
| `full_command_text` | `str`         | 包含命令前缀的完整文本  |
| `command`           | `str`         | 根命令名称        |
| `crt_command`       | `str`         | 当前正在执行的子命令名称 |
| `params`            | `list[str]`   | 根命令后的全部参数    |
| `crt_params`        | `list[str]`   | 当前子命令尚未消费的参数 |
| `privilege`         | `int`         | 当前用户的命令权限级别  |
| `query_id`          | `int`         | 当前流水线请求 ID   |
| `query_uuid`        | `str \| None` | 当前流水线请求的稳定标识 |

`context.shift()` 由 SDK 在进入当前子命令前调用，组件不需要手动调用。

### 上下文方法

| 方法                                                                           | 返回值                    | 说明                         |
| ---------------------------------------------------------------------------- | ---------------------- | -------------------------- |
| `await context.reply(message_chain, quote_origin=False)`                     | -                      | 回复当前请求所在会话                 |
| `await context.get_bot_uuid()`                                               | `str`                  | 获取当前请求来源机器人 UUID           |
| `await context.set_query_var(key, value)`                                    | -                      | 设置当前请求变量                   |
| `await context.get_query_var(key)`                                           | `Any`                  | 获取一个请求变量                   |
| `await context.get_query_vars()`                                             | `dict[str, Any]`       | 获取全部请求变量                   |
| `await context.create_new_conversation()`                                    | `dict[str, Any]`       | 清除流水线当前使用的对话，后续请求会创建新对话    |
| `await context.list_pipeline_knowledge_bases()`                              | `list[dict[str, Any]]` | 列出当前流水线 Local Agent 绑定的知识库 |
| `await context.retrieve_knowledge(kb_id, query_text, top_k=5, filters=None)` | `list[dict[str, Any]]` | 检索当前流水线已绑定的知识库             |

这些请求方法的行为与 EventListener 相同。命令的注册和返回值见 [Command 组件](https://langbot.app/docs/zh/plugin/dev/components/command.md)。

## Tool

Tool 没有独立的上下文对象。调用信息直接传入 `call()`：

```python
conversation_type = session.launcher_type.value
conversation_id = session.launcher_id
sender_id = session.sender_id
```

| 参数         | 说明                                      |
| ---------- | --------------------------------------- |
| `params`   | 模型或调用方根据工具 JSON Schema 生成的参数            |
| `session`  | 当前会话数据                                  |
| `query_id` | 当前流水线请求 ID；调用需要请求上下文的 LangBot API 时原样传入 |

`Session` 的常用字段如下：

| 属性                          | 说明                      |
| --------------------------- | ----------------------- |
| `launcher_type`             | 会话类型：`person` 或 `group` |
| `launcher_id`               | 私聊用户或群组 ID              |
| `sender_id`                 | 当前消息发送者 ID              |
| `bot_uuid`                  | 当前机器人 UUID              |
| `using_conversation`        | 当前流水线会话                 |
| `conversations`             | 该 Session 保存的流水线会话列表    |
| `use_prompt_name`           | 当前使用的提示词名称              |
| `create_time`、`update_time` | Session 的创建时间和更新时间      |

`session` 只保存数据，不提供 `reply()` 等上下文方法。工具的返回值交给调用方，不会自动发送到聊天平台。需要调用 LangBot 或平台能力时使用 `self.plugin`；相关接口要求 `session` 和 `query_id` 时，传入本次调用收到的值。

## 运行器

SDK `Runner` 类型的自定义 `run(ctx)` 和事件处理函数都接收 `RunnerContext`。该上下文只在本次运行期间有效。

```python
text = ctx.input.to_text()
event_type = ctx.event.event_type
```

### 上下文数据

| 属性               | 类型                            | 说明                           |
| ---------------- | ----------------------------- | ---------------------------- |
| `run_id`         | `str`                         | 本次运行 ID                      |
| `trigger`        | `AgentTrigger`                | 触发类型、来源和时间                   |
| `event`          | `AgentEventContext`           | 标准事件信封，包含事件 ID、类型、来源、时间和原始数据 |
| `platform_event` | 平台事件类型                        | 按事件类型解析后的平台事件对象              |
| `conversation`   | `ConversationContext \| None` | 当前会话、线程、机器人和工作区标识            |
| `actor`          | `ActorContext \| None`        | 事件发起者                        |
| `subject`        | `SubjectContext \| None`      | 事件所作用的消息、群组等对象               |
| `input`          | `AgentInput`                  | 当前输入的文本、结构化内容和附件             |
| `delivery`       | `DeliveryContext`             | 当前输出目标及流式、编辑、回应等能力           |
| `resources`      | `AgentResources`              | 本次运行已授权的模型、工具、知识库、技能和存储      |
| `context`        | `ContextAccess`               | 会话游标、内联范围和可用上下文 API          |
| `state`          | `AgentRunState`               | 本次运行开始时读取到的各作用域状态快照          |
| `runtime`        | `AgentRuntimeContext`         | LangBot 版本、追踪 ID 和截止时间       |
| `config`         | `dict[str, Any]`              | 当前 Agent 或插件处理器配置            |
| `adapter`        | `AdapterContext \| None`      | 入口适配器附加数据                    |
| `variables`      | `dict[str, Any]`              | 公开的请求变量，可用于运行器插值模板           |
| `metadata`       | `dict[str, Any]`              | 宿主提供的其他元数据                   |

优先使用上表中的稳定字段。`event.data` 和 `adapter.extra` 用于承载尚未进入稳定字段的附加信息。

### 回复与日志

| 方法                                                   | 返回值      | 说明                                             |
| ---------------------------------------------------- | -------- | ---------------------------------------------- |
| `await ctx.get_bot_uuid()`                           | `str`    | 获取来源机器人 UUID；无关联机器人时抛出异常                       |
| `await ctx.reply(message_chain, quote_origin=False)` | `Any`    | 回复当前事件，支持字符串或 `MessageChain`                   |
| `ctx.reply_stream()`                                 | 异步上下文管理器 | 流式更新同一条回复                                      |
| `await ctx.log(text, level="info")`                  | -        | 写入本次运行日志；级别支持 `debug`、`info`、`warning`、`error` |

`reply_stream()` 的 `update(text)` 接收当前完整文本。平台不支持流式时，LangBot 会在结束时发送一条完整消息；调试模式只模拟发送。

### 可用工具

| 方法                                                | 返回值                    | 说明                                   |
| ------------------------------------------------- | ---------------------- | ------------------------------------ |
| `await ctx.get_available_tools()`                 | `list[dict[str, Any]]` | 获取本次实际允许调用的上下文动作、平台 API、插件工具和 MCP 工具 |
| `await ctx.call_tool(tool_name, parameters=None)` | `dict[str, Any]`       | 调用上述列表中的工具                           |

`get_available_tools()` 的每一项包含 `name`、`description`、`parameters`、`type` 和 `operations`。返回结果已经按当前 Agent 或插件处理器的配置和事件能力过滤；不在列表中的工具不能通过 `ctx.call_tool()` 调用。

### Box 与附件

Box 是否启用、何时创建以及如何复用，由运行器决定。获取状态和申请 Box 使用 [LangBot API](https://langbot.app/docs/zh/plugin/dev/apis/common.md#box-沙箱)；当前运行的绑定和附件操作使用下列方法。

| 方法                                                      | 返回值             | 说明                                                           |
| ------------------------------------------------------- | --------------- | ------------------------------------------------------------ |
| `await ctx.bind_box(box_id)`                            | `BoxBinding`    | 绑定当前工作区中的 Box，返回 `box_id`、`outbox`；同次运行不能切换 Box              |
| `await ctx.import_box_attachments(attachment_ids=None)` | `list[BoxFile]` | 导入 `ctx.input.attachments` 的 `ref`，省略参数则导入全部；返回各文件的沙箱 `path` |
| `await ctx.export_box_files()`                          | `list[BoxFile]` | 导出本次运行 outbox 中的文件，返回文件句柄，不发送消息                              |
| `await ctx.reply_files(file_ids)`                       | `Any`           | 使用导出的 `id` 回复当前事件，受回复工具权限约束                                  |

`BoxFile` 包含 `id`、`name`、`type`、`size` 和可选的 `path`。输入的 `url`、`content` 等原始信息仍保留，只有显式导入才产生沙箱文件路径。文件句柄仅在本次运行有效，不能重复发送。

先绑定 Box，再使用原生执行、文件工具和附件方法。复用同一 Box 时，各次运行的附件目录仍独立。`ctx.variables` 提供公开的请求变量，运行器可据此计算复用键。

通过流水线运行时，`ctx.delivery.automatic_reply` 为 `True`，可以在 `RunnerResult.message_completed(ctx.run_id, message, file_ids=[...])` 返回附件；Agent 和插件处理器使用 `ctx.reply_files()` 显式发送。

外部运行器通过 `AgentRunExternalTools` 工具网关使用相同流程：`langbot_get_box_status`、`langbot_list_boxes`、`langbot_acquire_box`、`langbot_bind_box`、`langbot_import_box_attachments`、`langbot_export_box_files`。具有当前事件回复权限时还可使用 `langbot_reply_files`；这些调用均携带当前运行的授权。

### 提示词、历史与事件

| 方法                                                                                                                                               | 返回值                    | 可用性字段            |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ---------------- |
| `await ctx.get_prompt()`                                                                                                                         | `list[dict[str, Any]]` | `prompt_get`     |
| `await ctx.history_page(conversation_id=None, before_cursor=None, after_cursor=None, limit=50, direction="backward", include_attachments=False)` | `HistoryPage`          | `history_page`   |
| `await ctx.history_search(query, filters=None, top_k=10)`                                                                                        | `HistorySearchResult`  | `history_search` |
| `await ctx.event_get(event_id)`                                                                                                                  | `AgentEventRecord`     | `event_get`      |
| `await ctx.event_page(conversation_id=None, event_types=None, before_cursor=None, limit=50)`                                                     | `EventPage`            | `event_page`     |
| `await ctx.steering_pull(mode="all", limit=None)`                                                                                                | `SteeringPullResult`   | `steering_pull`  |

### 状态

| 方法                                                    | 返回值              | 说明               |
| ----------------------------------------------------- | ---------------- | ---------------- |
| `await ctx.state_get(scope, key)`                     | `dict[str, Any]` | 读取状态值            |
| `await ctx.state_set(scope, key, value)`              | `dict[str, Any]` | 写入可 JSON 序列化的状态值 |
| `await ctx.state_delete(scope, key)`                  | `dict[str, Any]` | 删除状态值            |
| `await ctx.state_list(scope, prefix=None, limit=100)` | `dict[str, Any]` | 列出指定作用域的状态键      |

`scope` 支持 `conversation`、`actor`、`subject` 和 `runner`。这些方法要求 `ctx.context.available_apis.state` 为 `true`。

### 运行记录

| 方法                                                                                                             | 返回值             | 可用性字段               |
| -------------------------------------------------------------------------------------------------------------- | --------------- | ------------------- |
| `await ctx.run_get(run_id=None)`                                                                               | `AgentRun`      | `run_get`           |
| `await ctx.run_list(conversation_id=None, statuses=None, before_cursor=None, limit=50)`                        | `RunPage`       | `run_list`          |
| `await ctx.run_events_page(run_id=None, before_cursor=None, after_cursor=None, limit=50, direction="forward")` | `RunEventPage`  | `run_events_page`   |
| `await ctx.run_cancel(run_id=None, reason=None)`                                                               | `AgentRun`      | `run_cancel`        |
| `await ctx.run_append_result(result)`                                                                          | `AgentRunEvent` | `run_append_result` |
| `await ctx.run_finalize(run_id=None, status=None, reason=None)`                                                | `AgentRun`      | `run_finalize`      |

`run_id=None` 表示当前运行。普通事件处理函数结束后，SDK 会自动完成本次运行；自定义 `run(ctx)` 通过 `yield RunnerResult` 返回结果时，也不需要再调用 `run_append_result()` 重复登记。

### 可用性与授权

通过 `ctx.context.available_apis` 判断提示词、历史、事件、状态和运行记录接口是否可用。模型、工具和知识库的授权范围分别位于 `ctx.resources.models`、`ctx.resources.tools` 和 `ctx.resources.knowledge_bases`。

运行器执行期间，通过 `self.plugin` 发起的模型、工具、知识库、存储和平台调用会自动关联当前运行，并按 `ctx.resources` 再次校验，无需传入 `run_id`。处理函数结束后，不要继续在后台任务中使用本次上下文或这些运行关联调用。

`ctx.api` 是底层的运行级代理。普通组件代码应优先使用本页列出的 `ctx` 方法，并通过 `self.plugin` 调用 LangBot API。

## 数据型上下文

以下组件收到的是本次任务的输入数据，不提供 EventListener 或运行器的上下文方法。字段、返回值和完整示例放在对应组件教程中。

| 组件入口                                                     | 主要数据                 | 组件教程                                                                                                 |
| -------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
| `KnowledgeEngine.ingest(context: IngestionContext)`      | 文件、目标知识库、创建配置和解析结果   | [KnowledgeEngine](https://langbot.app/docs/zh/plugin/dev/components/knowledge-engine.md#文档摄取)        |
| `KnowledgeEngine.retrieve(context: RetrievalContext)`    | 查询、目标知识库、检索配置和过滤条件   | [KnowledgeEngine](https://langbot.app/docs/zh/plugin/dev/components/knowledge-engine.md#知识检索)        |
| `KnowledgeRetriever.retrieve(context: RetrievalContext)` | 查询和外部知识库配置           | [KnowledgeRetriever](https://langbot.app/docs/zh/plugin/dev/components/knowledge-retriever.md#检索上下文) |
| `Parser.parse(context: ParseContext)`                    | 文件内容、文件名、MIME 类型和元数据 | [Parser](https://langbot.app/docs/zh/plugin/dev/components/parser.md#解析方法)                           |
| `Page.handle_api(request: PageRequest)`                  | 接口路径、HTTP 方法、请求体和请求头 | [Page](https://langbot.app/docs/zh/plugin/dev/components/page.md#pagerequest-字段)                     |

---

# LangBot API

Source: https://langbot.app/docs/zh/plugin/dev/apis/common

模型、工具、知识库和存储等能力通过 `self.plugin` 访问。当前事件、回复和会话状态的访问方式见[上下文 API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md)。

## LangBot API

这些 API 可在所有组件中通过 `self.plugin` 调用。访问方式如下：

- 插件根目录`main.py`中：`self` 对象内部方法，这些 API 均由插件类父类 `BasePlugin` 提供。
- 组件类中：`self.plugin` 对象内部方法。

### 获取插件配置信息

插件配置格式可在`manifest.yaml`中编写，用户需要在 LangBot 的插件管理中按照插件配置格式填写。之后插件代码可以调用此 API 获取插件配置信息。

```python
def get_config(self) -> dict[str, typing.Any]:
    """Get the config of the plugin."""

# 调用示例
config = self.plugin.get_config()
```

### 获取 LangBot 版本

获取 LangBot 版本号，返回格式为字符串`v<major>.<minor>.<patch>`。

```python
async def get_langbot_version(self) -> str:
    """Get the langbot version"""

# 调用示例
langbot_version = await self.plugin.get_langbot_version()
```

### 获取已配置的机器人列表

返回由所有机器人 UUID 组成的列表。

```python
async def get_bots(self) -> list[str]:
    """Get all bots"""

# 调用示例
bots = await self.plugin.get_bots()
```

### 获取机器人信息

获取机器人信息。

```python
async def get_bot_info(self, bot_uuid: str) -> dict[str, Any]:
    """Get a bot info"""

# 调用示例
bot_info = await self.plugin.get_bot_info("de639861-be05-4018-859b-c2e2d3e0d603")

# 返回示例
{
    "uuid": "de639861-be05-4018-859b-c2e2d3e0d603",
    "name": "aiocqhttp",
    "description": "由 LangBot v3 迁移而来",
    "adapter": "aiocqhttp",
    "enable": true,
    "use_pipeline_name": "ChatPipeline",
    "use_pipeline_uuid": "c30a1dca-e91c-452b-83ec-84d635a30028",
    "created_at": "2025-05-10T13:53:08",
    "updated_at": "2025-08-12T11:27:30",
    "adapter_runtime_values": {  # 若该机器人正在运行中，则具有该字段
        "bot_account_id": 960164003  # 机器人账号 ID
    }
}
```

### 发送主动消息

通过机器人 UUID 和目标会话 ID 发送主动消息。

消息链构造方式请参考[消息平台实体](https://langbot.app/docs/zh/plugin/dev/apis/messages.md)。

```python
async def send_message(
    self,
    bot_uuid: str,
    target_type: str,
    target_id: str,
    message_chain: platform_message.MessageChain,
) -> None:
    """Send a message to a session"""

# 调用示例
await self.plugin.send_message(
    bot_uuid="de639861-be05-4018-859b-c2e2d3e0d603",
    target_type="person",
    target_id="1010553892",
    message_chain=platform_message.MessageChain([platform_message.Plain(text="Hello, world!")]),
)
```

### 获取已配置的 LLM 模型列表

返回由所有已配置的 LLM 模型 UUID 组成的列表。

```python
async def get_llm_models(self) -> list[str]:
    """Get all LLM models"""

# 调用示例
llm_models = await self.plugin.get_llm_models()
```

### 调用 LLM 模型

调用 LLM 模型，返回 LLM 消息。非流式。

```python
async def invoke_llm(
    self,
    llm_model_uuid: str,
    messages: list[provider_message.Message],
    funcs: list[resource_tool.LLMTool] = [],
    extra_args: dict[str, Any] = {},
    timeout: float | None = None,
    *,
    reasoning_level: ReasoningLevel | None = None,
) -> provider_message.Message:
    """Invoke an LLM model"""

# 调用示例
llm_message = await self.plugin.invoke_llm(
    llm_model_uuid="llm_model_uuid",
    messages=[provider_message.Message(role="user", content="Hello, world!")],
    funcs=[],
    extra_args={},
)
```

### 思考等级

上述模型调用方法都支持可选的关键字参数 `reasoning_level`：

```python
response = await self.plugin.invoke_llm(
    llm_model_uuid=model_uuid,
    messages=[provider_message.Message(role="user", content="分析这个问题")],
    reasoning_level="medium",
)
```

可选值为 `provider_default`、`disabled`、`enabled`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`，具体取决于模型支持的等级。LangBot 校验能力并转换为供应商参数，不支持的等级会报错。

- 不传或传 `None`：保持原有行为，使用模型配置及 `extra_args`。
- 传 `provider_default`：不额外指定思考等级。
- 传其他等级：仅作用于本次调用；不要再通过 `extra_args` 重复设置供应商的思考参数。

Runner 应读取自己的配置，在每次模型调用时显式传入对应等级，包括备用模型和工具调用后的续答。LangBot 不会自动读取 Runner 配置中的思考等级。旧插件无需修改；显式使用新参数时，如果 Host 不支持，SDK 会在调用模型前提示升级。

### 模型流式输出与用量

| 方法                                                                                                                | 返回值                   |
| ----------------------------------------------------------------------------------------------------------------- | --------------------- |
| `invoke_llm_with_usage(llm_model_uuid, messages, funcs=[], extra_args={}, timeout=None, *, reasoning_level=None)` | `LLMInvokeResult`     |
| `invoke_llm_stream(llm_model_uuid, messages, funcs=[], extra_args={}, *, reasoning_level=None)`                   | 异步迭代 `MessageChunk`   |
| `invoke_llm_stream_events(llm_model_uuid, messages, funcs=[], extra_args={}, *, reasoning_level=None)`            | 异步迭代 `LLMStreamEvent` |

参数与 `invoke_llm` 相同。`timeout` 单位为秒，非流式调用默认 120 秒。需要 token 用量时使用 `invoke_llm_with_usage`：

```python
from langbot_plugin.api.entities.builtin.provider.message import Message

result = await self.plugin.invoke_llm_with_usage(
    llm_model_uuid=model_uuid,
    messages=[Message(role="user", content="Hello!")],
)
print(result.message.content)
if result.usage is not None:
    print(result.usage.total_tokens)
```

`usage` 可为 `None`，其中 `prompt_tokens`、`completion_tokens`、`total_tokens` 也可能缺失，不代表用量为零。供应商附加的缓存等用量字段会保留。

```python
async for event in self.plugin.invoke_llm_stream_events(
    llm_model_uuid=model_uuid,
    messages=[Message(role="user", content="Hello!")],
):
    if event.chunk is not None:
        print(event.chunk.content)
    if event.usage is not None:
        print(event.usage.model_dump())
```

`LLMStreamEvent` 包含可选的 `chunk` 和 `usage`，末尾可能只有用量，没有文本。`invoke_llm_stream` 只返回文本或工具调用分块。`MessageChunk.content` 是当前片段，`all_content` 在提供时是累计文本；累计文本应用替换，增量文本才追加；`is_final` 为真时也可能仍有文本。模型流式调用不会直接发送平台消息，主动流式回复见[运行上下文 API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md)。

### 列出可用解析器

列出宿主当前可用的 Parser 插件，可按 MIME 类型过滤。

```python
async def list_parsers(self, mime_type: str | None = None) -> list[dict[str, Any]]:
    """List available Parser plugins"""

# 调用示例
parsers = await self.plugin.list_parsers(mime_type="application/pdf")
# 返回的每项包含 plugin_id、plugin_author、plugin_name、name、description、supported_mime_types
```

### 获取所有可用工具

列出当前 LangBot 实例中所有可用的工具（包括插件工具和 MCP 工具）。

```python
async def list_tools(self) -> list[dict[str, Any]]:
    """List all available tools

    Returns:
        工具列表，每个元素包含：
        - name: 工具名称
        - label: 工具显示名称（多语言）
        - description: 工具描述（多语言）
        - icon: 工具图标
        - spec: 工具规格（包含 llm_prompt 和 parameters）
    """

# 调用示例
tools = await self.plugin.list_tools()
for tool in tools:
    print(f"Tool: {tool['name']}")
```

### 获取工具详情

获取特定工具的详细信息。

```python
async def get_tool_detail(self, tool_name: str) -> dict[str, Any]:
    """Get detailed information about a specific tool

    Args:
        tool_name: 工具名称（metadata.name，例如 "get_weather_alerts"）

    Returns:
        工具详情 dict，包含 name、label、description、spec（含 parameters 和 llm_prompt）
    """

# 调用示例
detail = await self.plugin.get_tool_detail("get_weather_alerts")
print(detail['spec']['parameters'])
```

### 调用工具

调用指定的工具。

```python
async def call_tool(
    self,
    tool_name: str,
    parameters: dict[str, Any],
    session: dict[str, Any],
    query_id: int,
) -> dict[str, Any]:
    """Call a specific tool

    Args:
        tool_name: 工具名称（metadata.name）
        parameters: 工具参数
        session: 会话信息
        query_id: 查询 ID

    Returns:
        工具返回的结果 dict
    """

# 调用示例
result = await self.plugin.call_tool(
    tool_name="get_weather_alerts",
    parameters={"state": "CA"},
    session={},
    query_id=0,
)
print(result)
```

> idea:
>
> 工具名称使用 `metadata.name`（如 `echo_tool`、`get_weather_alerts`），不需要包含作者或插件名前缀。

### 设置插件持久化数据

持久化存储插件数据。通过这个接口存储的数据，仅可被该插件访问。值需要自行转换为字节。

```python
async def set_plugin_storage(self, key: str, value: bytes) -> None:
    """Set a plugin storage value"""

# 调用示例
await self.plugin.set_plugin_storage("key", b"value")
```

### 获取插件持久化数据

```python
async def get_plugin_storage(self, key: str) -> bytes:
    """Get a plugin storage value"""

# 调用示例
plugin_storage = await self.plugin.get_plugin_storage("key")
```

### 获取插件所有持久化数据键

```python
async def get_plugin_storage_keys(self) -> list[str]:
    """Get all plugin storage keys"""

# 调用示例
plugin_storage_keys = await self.plugin.get_plugin_storage_keys()
```

### 删除插件持久化数据

```python
async def delete_plugin_storage(self, key: str) -> None:
    """Delete a plugin storage value"""

# 调用示例
await self.plugin.delete_plugin_storage("key")
```

### 获取工作空间持久化数据

通过这个接口存储的数据，可被所有插件访问。值需要自行转换为字节。

```python
async def set_workspace_storage(self, key: str, value: bytes) -> None:
    """Set a workspace storage value"""

# 调用示例
await self.plugin.set_workspace_storage("key", b"value")
```

### 获取工作空间持久化数据

```python
async def get_workspace_storage(self, key: str) -> bytes:
    """Get a workspace storage value"""

# 调用示例
workspace_storage = await self.plugin.get_workspace_storage("key")
```

### 获取工作空间所有持久化数据键

```python
async def get_workspace_storage_keys(self) -> list[str]:
    """Get all workspace storage keys"""

# 调用示例
workspace_storage_keys = await self.plugin.get_workspace_storage_keys()
```

### 删除工作空间持久化数据

```python
async def delete_workspace_storage(self, key: str) -> None:
    """Delete a workspace storage value"""

# 调用示例
await self.plugin.delete_workspace_storage("key")
```

### 获取插件配置项文件数据

```python
async def get_config_file(self, file_key: str) -> bytes:
    """Get a config file value"""

# 调用示例
file_bytes = await self.plugin.get_config_file("key")
```

请结合 [`file 或 array[file] 类型配置项`](https://langbot.app/docs/zh/plugin/dev/basic-info.md#type-file)使用。

## 知识库 API

这些 API 可在提供 `self.plugin` 的普通组件中访问，用于列出和检索 LangBot 实例中的所有知识库，不受流水线配置限制。

### 列出所有知识库

列出 LangBot 实例中所有可用的知识库。

```python
async def list_knowledge_bases(self) -> list[dict[str, Any]]:
    """列出所有知识库

    Returns:
        知识库列表，每个元素包含：
        - uuid: 知识库 UUID
        - name: 知识库名称
        - description: 知识库描述
    """

# 调用示例
knowledge_bases = await self.plugin.list_knowledge_bases()
for kb in knowledge_bases:
    print(f"KB: {kb['name']} ({kb['uuid']})")
```

### 检索知识库

从任意知识库中检索相关文档。

```python
async def retrieve_knowledge(
    self,
    kb_id: str,
    query_text: str,
    top_k: int = 5,
    filters: dict[str, Any] | None = None,
) -> list[dict[str, Any]]:
    """从知识库中检索

    Args:
        kb_id: 知识库 UUID（从 list_knowledge_bases 获取）
        query_text: 检索查询文本
        top_k: 返回结果数量（默认：5）
        filters: 可选的元数据过滤条件

    Returns:
        检索结果条目列表
    """

# 调用示例
results = await self.plugin.retrieve_knowledge(
    kb_id="kb-uuid-here",
    query_text="如何配置系统？",
    top_k=3,
)
for entry in results:
    print(entry)
```

> idea:
>
> 这些 API 不需要 `query_id`，可以在普通组件中使用（包括 Tool 组件），且可以访问所有知识库，不受当前流水线配置限制。

## RAG API

这些 API 供 `KnowledgeEngine` 组件调用，用于访问 LangBot 宿主的嵌入模型、向量数据库和文件存储。访问方式：

- 在 `KnowledgeEngine` 组件类中：`self.plugin` 对象内部方法。

### 调用嵌入模型

调用宿主已配置的嵌入模型生成文本向量。

```python
async def invoke_embedding(
    self,
    embedding_model_uuid: str,
    texts: list[str],
) -> list[list[float]]:
    """调用嵌入模型生成向量

    Args:
        embedding_model_uuid: 嵌入模型 UUID
        texts: 待嵌入的文本列表

    Returns:
        向量列表，每个输入文本对应一个向量
    """

# 调用示例
vectors = await self.plugin.invoke_embedding("model_uuid", ["Hello", "World"])
```

### 向量写入

将向量写入宿主的向量数据库。

```python
async def vector_upsert(
    self,
    collection_id: str,
    vectors: list[list[float]],
    ids: list[str],
    metadata: list[dict[str, Any]] | None = None,
    documents: list[str] | None = None,
) -> None:
    """向量写入

    Args:
        collection_id: 目标集合 ID
        vectors: 向量列表
        ids: 向量唯一标识列表
        metadata: 可选的元数据列表
        documents: 可选的原始文本文档列表。在支持全文/混合检索的
            后端中，需要传入此参数以启用全文和混合检索。
    """

# 调用示例
await self.plugin.vector_upsert(
    collection_id="kb_uuid",
    vectors=[[0.1, 0.2, ...], [0.3, 0.4, ...]],
    ids=["chunk_0", "chunk_1"],
    metadata=[{"document_id": "doc1"}, {"document_id": "doc1"}],
    documents=["分块文本 0", "分块文本 1"],
)
```

### 向量搜索

在宿主的向量数据库中搜索相似向量。

```python
async def vector_search(
    self,
    collection_id: str,
    query_vector: list[float],
    top_k: int = 5,
    filters: dict[str, Any] | None = None,
    search_type: str = "vector",
    query_text: str = "",
) -> list[dict[str, Any]]:
    """向量搜索

    Args:
        collection_id: 目标集合 ID
        query_vector: 查询向量
        top_k: 返回结果数量
        filters: 可选的元数据过滤条件
        search_type: 检索方式，可选 'vector'、'full_text'、'hybrid'
        query_text: 原始查询文本，用于全文检索和混合检索

    Returns:
        搜索结果列表（包含 id, score, metadata 等字段）
    """

# 调用示例
results = await self.plugin.vector_search(
    collection_id="kb_uuid",
    query_vector=[0.1, 0.2, ...],
    top_k=5,
    search_type="hybrid",
    query_text="搜索查询",
)
# 返回格式: [{"id": "chunk_0", "score": 0.123, "metadata": {"document_id": "doc1", ...}}, ...]
```

> info:
>
> `vector_search` 返回的每个结果为 dict，包含 `id`（向量 ID）、`score`（距离分数）和 `metadata`（写入时附带的元数据）三个字段。如果需要在检索结果中返回文本内容，请在摄取阶段将文本存入 metadata 中。

### 向量删除

从宿主的向量数据库中删除向量。

```python
async def vector_delete(
    self,
    collection_id: str,
    file_ids: list[str] | None = None,
    filters: dict[str, Any] | None = None,
) -> int:
    """向量删除

    Args:
        collection_id: 目标集合 ID
        file_ids: 要删除的文件 ID 列表
        filters: 可选的元数据过滤条件

    Returns:
        删除的条目数量
    """

# 调用示例
deleted = await self.plugin.vector_delete(
    collection_id="kb_uuid",
    file_ids=["doc_001"],
)
```

> info:
>
> `filters` 参数支持 Chroma 风格的 `where` 语法进行元数据过滤。多个顶层键之间为 AND 关系。支持的运算符：`$eq`、`$ne`、`$gt`、`$gte`、`$lt`、`$lte`、`$in`、`$nin`。
>
> ```python
> # 隐式 $eq
> results = await self.plugin.vector_search(
>     collection_id="kb_uuid",
>     query_vector=[0.1, 0.2, ...],
>     filters={"file_id": "abc"},
> )
>
> # 比较运算符
> results = await self.plugin.vector_search(
>     collection_id="kb_uuid",
>     query_vector=[0.1, 0.2, ...],
>     filters={"created_at": {"$gte": 1700000000}},
> )
>
> # 列表运算符
> results = await self.plugin.vector_search(
>     collection_id="kb_uuid",
>     query_vector=[0.1, 0.2, ...],
>     filters={"file_type": {"$in": ["pdf", "docx"]}},
> )
>
> # 按过滤条件删除
> deleted = await self.plugin.vector_delete(
>     collection_id="kb_uuid",
>     filters={"file_type": {"$eq": "pdf"}},
> )
> ```
>
> **注意：** Chroma、Qdrant 和 SeekDB 存储完整的元数据，可以对任意字段进行过滤。Milvus 和 pgvector 仅存储 `text`、`file_id` 和 `chunk_uuid`，对其他字段的过滤将被静默忽略。

从宿主存储中获取上传文件的内容。

```python
async def get_knowledge_file_stream(self, storage_path: str) -> bytes:
    """获取文件内容

    Args:
        storage_path: 文件的存储路径（来自 FileObject.storage_path）

    Returns:
        文件内容的字节数据
    """

# 调用示例
file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)
```

## 其他资源 API

以下方法同样通过 `self.plugin` 调用。

### 调用重排模型

```python
async def invoke_rerank(
    self, rerank_model_uuid: str, query: str, documents: list[str],
    top_k: int | None = None, extra_args: dict[str, Any] | None = None,
    timeout: float = 60.0,
) -> list[dict[str, Any]]:
    ...

scores = await self.plugin.invoke_rerank(
    rerank_model_uuid=rerank_model_uuid,
    query="How do I configure a bot?",
    documents=["Bot configuration guide", "Plugin publishing guide"],
    top_k=1,
)
```

返回结果通常包含原文档索引 `index` 和相关性分数 `relevance_score`。

### 调用解析器

```python
async def invoke_parser(
    self, plugin_author: str, plugin_name: str, storage_path: str,
    mime_type: str, filename: str, metadata: dict[str, Any] | None = None,
) -> dict[str, Any]:
    ...

parsers = await self.plugin.list_parsers(mime_type="application/pdf")
if parsers:
    parser = parsers[0]
    parsed = await self.plugin.invoke_parser(
        plugin_author=parser["plugin_author"],
        plugin_name=parser["plugin_name"],
        storage_path=storage_path,
        mime_type="application/pdf",
        filename="guide.pdf",
    )
```

`storage_path` 是宿主存储中的文件路径，例如知识库摄取上下文的 `context.file_object.storage_path`，不是插件本地路径。返回字典包含 `text`、`sections`、`metadata`。

### 列出向量记录

```python
async def vector_list(
    self, collection_id: str, filters: dict[str, Any] | None = None,
    limit: int = 20, offset: int = 0,
) -> dict[str, Any]:
    ...

page = await self.plugin.vector_list(
    collection_id=collection_id,
    filters={"file_id": "doc_001"},
    limit=20,
    offset=0,
)
for item in page["items"]:
    print(item["id"], item.get("metadata"))
```

返回 `items` 和 `total`。条目包含 `id`、`document`、`metadata`；`total` 是存储后端尽力提供的匹配数量。过滤条件使用上文的向量 API 格式。

### 列出插件和命令

```python
manifests = await self.plugin.list_plugins_manifest()
commands = await self.plugin.list_commands()
```

两个方法均不需要参数，分别返回宿主提供的插件清单列表和命令列表。

### Box 沙箱

这些方法通过 `self.plugin` 调用，作用于当前工作区。在运行器内调用时会自动携带本次运行的授权。

| 方法                                                       | 返回值                | 说明                                                                                                       |
| -------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------- |
| `await self.plugin.get_box_status()`                     | `BoxStatus`        | `enabled`、`available`、数量上限 `limit`、已用 `used`、剩余 `remaining`、托管环境要求的 `required_reuse_key` 和不可用原因 `reason` |
| `await self.plugin.list_boxes()`                         | `list[BoxSession]` | 可用 Box 的 `id` 和状态快照 `status`（`idle`、`running`、`closing`）                                                 |
| `await self.plugin.acquire_box(reuse_key, options=None)` | `BoxSession`       | 同一键复用已有 Box，否则在数量限制内创建；`options` 支持 `image`                                                              |

数量未知时对应字段为 `None`。`remaining=0` 仍可以复用已有 Box；创建时由 Runtime 原子检查额度。运行器自行计算复用键，Host 不解释聊天模板；托管环境给出 `required_reuse_key` 时须使用该值。不同工作区的相同键不会共用 Box。

获取 Box 后，通过[运行器上下文](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md#runner)绑定到本次运行，再导入附件和执行工具。

---

# 消息平台实体

Source: https://langbot.app/docs/zh/plugin/dev/apis/messages

LangBot 支持多种消息平台，每个消息平台的`消息实体`格式均不相同。为了屏蔽这些差异，我们实现了一套统一的标准。插件开发者只需要掌握并在插件中使用此页所述的消息实体，LangBot 内部的消息处理逻辑能够自动完成消息的解析和转换。

## 消息链

消息平台的`消息`不同于用于 AI 交互的消息，消息平台的消息以`消息链`的形式描述，QQ 上展示的每一个独立的消息就是一条消息链，消息链中可以包含`文字`、`图片`、`@组件`等多种`消息链组件`，例如：

![](https://langbot.app/docs/images/zh/plugin/dev/apis/plugin_dev_messages_01.png)

这就是一个消息链，包含 一个 Plain 组件（Hello World）和 一个 Image 组件（乌萨奇）

消息链和消息链组件的定义位于`langbot_plugin.api.entities.builtin.platform.message`中。

### 构造消息链

请先引入`langbot_plugin.api.entities.builtin.platform.message`包，才能使用其中的消息组件。

```python
from langbot_plugin.api.entities.builtin.platform.message import *

# 构建一个包含文字 Hello LangBot 和图片（从URL获取）的消息
msg_chain = MessageChain([
    Plain(text="Hello LangBot"),
    Image(url='https://qchatgpt.rockchin.top/langbot-logo.png')
])

# 构建一个包含 @全体成员 和文字 Hello LangBot 的消息
msg_chain = MessageChain([
    AtAll(),
    Plain(text="Hello LangBot")
])

# 构建一个包含 @指定成员 和文字 Hello LangBot 的消息
msg_chain = MessageChain([
    At(target=123456),
    Plain(text="Hello LangBot")
])
```

目前支持的消息链组件：

- `Source` 源消息链信息，如果是从消息平台收到的消息，都会在消息链最前端包含此组件，记录消息信息
- `Plain` 纯文本消息
- `Quote` 引用消息
- `Image` 图片消息
- `AtAll` @全体成员消息
- `At` @指定成员消息
- `Voice` 语音消息
  - 需要检查消息平台支持性
- `Forward` 转发消息
  - 在很多平台不受支持，不建议使用
- `File` 文件消息

创建组件时，须使用具名参数传入。具体使用方式可以查看源码`langbot_plugin.api.entities.builtin.platform.message`中的定义。

## 其他实体

除了上述实体之外，还有`好友 Friend`和`群 Group`等实体，这些实体的定义位于`langbot_plugin.api.entities.builtin.platform.entities`中。

## 平台 API

查询用户、管理群组和调用平台专有接口，请使用[平台 API](https://langbot.app/docs/zh/plugin/dev/apis/platform.md)。运行器使用相同的 `self.plugin` 入口，当前会话回复使用 `ctx.reply()`。

---

# 流水线事件和 API

Source: https://langbot.app/docs/zh/plugin/dev/apis/pipeline-events

LangBot 插件可注册并处理流水线事件。使用方法见[组件：事件监听器](https://langbot.app/docs/zh/plugin/dev/components/event-listener.md)。

## 可监听的事件列表

某些事件具有`可设置的属性`，这些属性可以被插件代码修改，并在之后被用在 LangBot 后续的处理中。

### \*MessageReceived

接收到群聊或私聊任何消息时触发。

```python
class PersonMessageReceived(BaseEventModel):
    """收到任何私聊消息时"""

    event_name: str = "PersonMessageReceived"

    launcher_type: str
    """发起对象类型(person)"""

    launcher_id: typing.Union[int, str]
    """发送者ID"""

    sender_id: typing.Union[int, str]
    """发送者ID，私聊情况下与 launcher_id 相同"""

    message_event: platform_events.PersonMessage
    """原消息事件对象。包含发送者的信息。"""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """消息链"""


class GroupMessageReceived(BaseEventModel):
    """收到任何群聊消息时"""

    event_name: str = "GroupMessageReceived"

    launcher_type: str
    """发起对象类型(group)"""

    launcher_id: typing.Union[int, str]
    """群号"""

    sender_id: typing.Union[int, str]
    """发送者ID"""

    message_event: platform_events.GroupMessage
    """原消息事件对象。包含群聊和发送者的信息。"""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """消息链"""
```

### \*NormalMessageReceived

接收到群聊或私聊消息，并判断为需要由 LLM 处理的消息（非命令消息）时触发。

```python
class PersonNormalMessageReceived(BaseEventModel):
    """判断为应该处理的私聊普通消息时触发"""

    event_name: str = "PersonNormalMessageReceived"

    launcher_type: str
    """发起对象类型(person)"""

    launcher_id: typing.Union[int, str]
    """发起对象ID"""

    sender_id: typing.Union[int, str]
    """发送者ID，私聊情况下与 launcher_id 相同"""

    text_message: str
    """消息文本"""

    message_event: platform_events.PersonMessage
    """原消息事件对象。包含发送者的信息。"""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """消息链"""

    # ========== 可设置的属性 ==========

    user_message_alter: typing.Optional[provider_message.ContentElement] = None
    """修改后的消息文本，langbot_plugin.api.entities.builtin.provider.message.ContentElement 类型"""

    reply_message_chain: typing.Optional[platform_message.MessageChain] = None
    """直接回复消息链，仅在阻止默认行为时生效"""


class GroupNormalMessageReceived(BaseEventModel):
    """判断为应该处理的群聊普通消息时触发"""

    event_name: str = "GroupNormalMessageReceived"

    launcher_type: str
    """发起对象类型(group)"""

    launcher_id: typing.Union[int, str]
    """群号"""

    sender_id: typing.Union[int, str]
    """发送者ID"""

    text_message: str
    """消息文本"""

    message_event: platform_events.GroupMessage
    """原消息事件对象。包含群聊和发送者的信息。"""

    message_chain: platform_message.MessageChain = pydantic.Field(
        serialization_alias="message_chain"
    )
    """消息链"""

    # ========== 可设置的属性 ==========

    user_message_alter: typing.Optional[provider_message.ContentElement] = None
    """修改后的消息文本，langbot_plugin.api.entities.builtin.provider.message.ContentElement 类型"""

    reply_message_chain: typing.Optional[platform_message.MessageChain] = None
    """直接回复消息链，仅在阻止默认行为时生效"""
```

### \*CommandSent

> warning:
>
> 不再推荐使用，请改为使用[组件：命令](https://langbot.app/docs/zh/plugin/dev/components/command.md)。

接收到群聊或私聊命令时触发。

```python
class PersonCommandSent(BaseEventModel):
    """判断为应该处理的私聊命令时触发"""

    event_name: str = "PersonCommandSent"

    launcher_type: str
    """发起对象类型(person)"""

    launcher_id: typing.Union[int, str]
    """发起对象ID"""

    sender_id: typing.Union[int, str]
    """发送者ID，私聊情况下与 launcher_id 相同"""

    command: str
    """命令文本"""

    params: list[str]
    """命令参数"""

    text_message: str
    """消息文本"""

    is_admin: bool
    """是否为管理员"""


class GroupCommandSent(BaseEventModel):
    """判断为应该处理的群聊命令时触发"""

    event_name: str = "GroupCommandSent"

    launcher_type: str
    """发起对象类型(group)"""

    launcher_id: typing.Union[int, str]
    """群号"""

    sender_id: typing.Union[int, str]
    """发送者ID"""

    command: str
    """命令文本"""

    params: list[str]
    """命令参数"""

    text_message: str
    """消息文本"""

    is_admin: bool
    """是否为管理员"""
```

### NormalMessageResponded

消息得到 LLM 响应时触发。

```python
class NormalMessageResponded(BaseEventModel):
    """收到对普通消息的响应时触发"""

    event_name: str = "NormalMessageResponded"

    launcher_type: str
    """发起对象类型(person)"""

    launcher_id: typing.Union[int, str]
    """发起对象ID"""

    sender_id: typing.Union[int, str]
    """发送者ID，私聊情况下与 launcher_id 相同"""

    session: provider_session.Session
    """会话对象"""

    prefix: str
    """回复消息的前缀"""

    response_text: str
    """回复消息的文本"""

    finish_reason: str
    """响应结束原因"""

    funcs_called: list[str]
    """调用的函数列表"""

    # ========== 可设置的属性 ==========

    reply_message_chain: typing.Optional[platform_message.MessageChain] = None
    """直接回复消息链，仅在阻止默认行为时生效"""
```

### PromptPreProcessing

在构建 LLM 响应的上下文（prompt）时触发。

```python
class PromptPreProcessing(BaseEventModel):
    """会话中的Prompt预处理时触发"""

    event_name: str = "PromptPreProcessing"

    session_name: str
    """会话名称，格式为 person_1234567890 或 group_1234567890"""

    # ========== 可设置的属性 ==========

    default_prompt: list[
        typing.Union[provider_message.Message, provider_message.MessageChunk]
    ]
    """此对话的情景预设（系统提示词），可修改，langbot_plugin.api.entities.builtin.provider.message.Message 或 langbot_plugin.api.entities.builtin.provider.message.MessageChunk 类型"""

    prompt: list[typing.Union[provider_message.Message, provider_message.MessageChunk]]
    """此对话现有消息记录，可修改，langbot_plugin.api.entities.builtin.provider.message.Message 或 langbot_plugin.api.entities.builtin.provider.message.MessageChunk 类型"""
```

## EventListener 上下文

事件处理函数通过 `event_context.event` 读取当前事件。`EventContext` 的完整属性和方法见[上下文 API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md#eventlistener)。

### 阻止默认行为

调用 `event_context.prevent_default()` 后，当前事件的默认处理将停止。仅以下事件支持此操作：

> info:
>
> 仅以下事件可阻止默认行为：
>
> - PersonMessageReceived
> - GroupMessageReceived
> - PersonNormalMessageReceived
> - GroupNormalMessageReceived
> - PersonCommandSent
> - GroupCommandSent
> - NormalMessageResponded

调用 `event_context.prevent_postorder()` 可阻止后续插件继续处理当前事件。

---

# 平台 API

Source: https://langbot.app/docs/zh/plugin/dev/apis/platform

通过机器人 UUID 调用平台适配器的 API。发送消息链可继续使用 `self.plugin.send_message()`；查询群组、用户及其他平台能力使用下面的接口。

## 调用平台 API

```python
async def call_platform_api(
    self,
    bot_uuid: str,
    action: str,
    params: dict[str, Any] | None = None,
) -> Any:
    ...
```

在 Command、EventListener、Tool 等组件中通过 `self.plugin` 调用。返回值为可序列化的字典、列表、标量或 `None`，具体取决于动作；不是平台 SDK 对象。

```python
group = await self.plugin.call_platform_api(
    bot_uuid=bot_uuid,
    action="get_group_info",
    params={"group_id": "123456"},
)
```

`bot_uuid` 可从 `await self.plugin.get_bots()` 获取，流水线事件中也可使用 `await event_context.get_bot_uuid()`。平台 ID 的值应来自实际事件或平台配置。

### 常用动作

| `action`                         | `params`                             |
| -------------------------------- | ------------------------------------ |
| `get_user_info`                  | `user_id`                            |
| `get_friend_list`                | `{}`                                 |
| `get_group_info`                 | `group_id`                           |
| `get_group_list`                 | `{}`                                 |
| `get_group_member_list`          | `group_id`                           |
| `get_group_member_info`          | `group_id`, `user_id`                |
| `get_message` / `delete_message` | `chat_type`, `chat_id`, `message_id` |
| `set_group_name`                 | `group_id`, `name`                   |
| `mute_member`                    | `group_id`, `user_id`, `duration`    |
| `unmute_member` / `kick_member`  | `group_id`, `user_id`                |
| `leave_group`                    | `group_id`                           |
| `approve_friend_request`         | `request_id`, `approve`, `remark`    |
| `approve_group_invite`           | `request_id`, `approve`              |
| `get_file_url`                   | `file_id`                            |

每个平台支持的动作不同，也可能要求机器人管理员权限。`duration` 单位为秒，`0` 的含义依平台而异，不应作为通用的永久禁言值。查询结果可能依赖平台缓存。机器人未运行、动作不受支持或参数不正确时，调用会抛出异常。

## 平台专有 API

将外层 `action` 设为 `call_platform_api`，在 `params` 中填写平台动作及其参数。例如，使用 OneBot Omni 读取机器人账号信息：

```python
account = await self.plugin.call_platform_api(
    bot_uuid=bot_uuid,
    action="call_platform_api",
    params={"action": "get_login_info", "params": {}},
)
```

只能调用适配器已声明的动作，并非任意平台接口都能透传。插件通过运行时调用宿主，不直接访问 `ctx.query.adapter` 或 `adapter.bot`。

## 运行器

运行器执行期间，`self.plugin` 的模型、工具、知识库、存储和平台调用自动关联当前运行并执行授权检查，无需传入 `run_id`。同一插件的并发运行互相隔离。不要在处理函数返回后继续调用这些运行关联的 API。

通过 `await ctx.get_bot_uuid()` 获取当前机器人。平台调用必须匹配本次工具授权：仅授权当前事件目标时，不能改传其他目标；未授权的动作（包括平台专有动作）会被拒绝。调试中的这些调用同样使用 Mock。

```python
tools = await ctx.get_available_tools()
if any(tool["name"] == "event_get_actor" for tool in tools):
    actor = await ctx.call_tool("event_get_actor")
    await ctx.log(str(actor))
```

---

# 插件技术细节

Source: https://langbot.app/docs/zh/plugin/dev/apis/tech-details

## 架构

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_system_arch.png)

在 4.0 版本中，我们引入了一种高安全性、高灵活性的生产级插件系统，并为插件开发者提供了丰富的 API 和易用的配套工具。

Plugin Runtime （插件运行时），用于管理插件的生命周期，协调 LangBot 与插件之间的交互。有两种运行模式：`stdio` 和 `websocket`。当 LangBot 是由用户直接启动（未运行在容器内时），会使用 `stdio` 模式，这种场景多为个人用户或轻量级环境。当 LangBot 运行在容器内时，会使用 `websocket` 模式，此场景专为生产级环境设计。

Plugin Runtime 会自动启动各个已安装的插件，通过 stdio 交互。在插件开发场景中，开发者可以使用 `lbp` 命令行工具启动插件并通过 WebSocket 连接到已启动的 Runtime 进行调试。

---

# 完善配置信息

Source: https://langbot.app/docs/zh/plugin/dev/basic-info

## 修改清单文件

插件目录下的`manifest.yaml`文件声明了插件的基础信息，这些信息会被展示到 LangBot UI 或插件市场等界面上。

```yaml
apiVersion: v1  # 请勿修改
kind: Plugin  # 请勿修改
metadata:
  author: RockChinQ  # 作者，符合正则表达式 ^[a-zA-Z0-9_-]+$
  name: HelloPlugin  # 插件名称，用于区分插件，符合正则表达式 ^[a-zA-Z0-9-]+$
  repository: 'https://github.com/langbot-app/HelloPlugin'  # 插件仓库地址
  version: 0.1.0  # 插件版本
  description:
    en_US: 'Hello LangBot Plugin'  # 插件描述，多语言
    zh_Hans: 'Hello LangBot Plugin'
  label:
    en_US: HelloPlugin  # 插件标签，用于在界面上展示，多语言
    zh_Hans: HelloPlugin
  icon: assets/icon.svg  # 插件图标，默认使用 assets/icon.svg，可自行替换，支持各种图片格式
spec:
  config: []  # 插件所需配置项格式
  components: {}  # 插件组件列表，无需手动修改
execution:
  python:
    path: main.py  # 请勿修改
    attr: HelloPlugin  # 请勿修改
```

如果需要申请认证并让多个安装共享运行，还需要在 `execution` 下声明 `sharedRuntime` 与 `componentModel`，见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

插件多语言遵循 [RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646) 标准。目前支持的语言有：

- `en_US` 英文 （必填）
- `zh_Hans` 简体中文
- `zh_Hant` 繁体中文
- `ja_JP` 日语
- `vi_VN` 越南语
- `th_TH` 泰语
- `es_ES` 西班牙语

## 插件配置项格式

在 `manifest.yaml` 文件中，`spec.config` 声明的字段将在 LangBot 渲染成配置项表单由用户填写，插件可通过 SDK 提供的 API 获取用户填写的配置项（见后文）。

例如：

```yaml
spec:
  config:
    - name: github_token  # 必填；配置项名称，用于在插件中获取
      type: string  # 必填；配置项类型，支持 string, integer, float, boolean, select, prompt-editor, llm-model-selector, bot-selector, tools-selector 等
      label:  # 必填；配置项显示名称，支持多语言。语言代码采用 RFC 4646 标准。
        en_US: Github Token
        zh_Hans: Github Token
      description:  # 配置项描述，支持多语言。可选。
        en_US: Image downloading requires a Github token
        zh_Hans: 如果不填的话，图片可能会下载失败
      default: ''  # 配置项默认值，可选。
      required: false  # 配置项是否必填，可选。
      show_if:  # 配置项条件渲染（满足条件时才显示），可选。
        field: mode
        operator: eq
        value: mode1
    - name: mode
      type: select
      ...
```

配置项支持的各个类型及字段如下：

### 条件渲染 (`show_if`)

所有类型的配置项都支持通过 `show_if` 字段实现条件渲染。您可以根据同一个表单（或关联表单）中其他字段的值，来决定当前字段是否在界面上渲染显示。

```yaml
- name: advanced_setting
  type: string
  show_if:
    field: mode          # 依赖的字段名称
    operator: eq         # 判断操作符，支持 'eq' (等于), 'neq' (不等于), 'in' (包含于列表)
    value: advanced      # 判断的标准值
```

> **注意：** 跨表单的级联关系（如 RAG 引擎中 `creation_schema` 的配置去读取 `retrieval_schema` 的值，反之亦然）在 LangBot 最新前端中已经受支持。

### type: string

字符串。可选配置 `options` 预选项——配置后会在输入框旁显示一个下拉按钮，用户可快速选择预设值填入输入框，也可以自由输入。

```yaml
- name: api_key
  type: string
  ...
```

带预选项：

```yaml
- name: api_url
  type: string
  options:  # 可选的预设值，以下拉按钮形式显示在输入框旁。
    - name: "https://api.openai.com/v1"  # 选中时填入的值。
      label:  # 显示名称，支持多语言。
        en_US: OpenAI Official
        zh_Hans: OpenAI 官方
    - name: "https://api.deepseek.com/v1"
      label:
        en_US: DeepSeek
        zh_Hans: DeepSeek
  ...
```

### type: array\[string]

字符串数组。

```yaml
- name: tags
  type: array[string]
  ...
```

### type: integer

整数。

```yaml
- name: progress
  type: integer
  ...
```

### type: float

浮点数。

```yaml
- name: temperature
  type: float
  ...
```

### type: boolean

布尔值。

```yaml
- name: is_enabled
  type: boolean
  ...
```

### type: select

下拉框。需要配置 `options` 选项，表示下拉框的选项。每个选项会显示 `label` 作为主要文本，`name`（值）以小字显示在下方。

```yaml
- name: mode
  type: select
  allow_custom: true
  options:  # 下拉框选项，支持多语言。
    - name: mode1  # 值，在下拉框中以小字显示。
      label:  # 显示名称，支持多语言。
        en_US: Mode 1
        zh_Hans: 模式 1
    - name: mode2
      label:  # 显示名称，支持多语言。
        en_US: Mode 2
        zh_Hans: 模式 2
  ...
```

设置 `allow_custom: true` 可在预设之外提供“自定义”选项，仅选择该项时显示输入框。最终保存的是所选 `name` 或自定义字符串，不会保存“自定义”标记。此选项也适用于运行器的 `spec.config`。

### type: prompt-editor

提示词编辑器。会展示一个流水线配置页面的提示词编辑器，最终结果表示为 OpenAI 的 `messages` 格式。

```yaml
- name: prompt
  type: prompt-editor
  ...
```

### type: text

大段文本。前端渲染为 textarea 以供用户输入，最终以 string 类型传递给插件。

```yaml
- name: prompt
  type: text
  ...
```

### type: file

文件上传。支持最大 10MB 的文件上传，最终以 `{"file_key": "xxxxx.xxx", "mimetype": "xxxxx"}` 格式传递给插件。插件可使用 `get_config_file` API 获取文件内容。

```yaml
- name: config_file
  type: file
  accept: 'application/json'  # 可选，指定接受的文件 MIME 类型
  ...
```

在插件中获取文件：

```python
# 从配置中获取文件信息
file_config = self.get_config()['config_file']
file_key = file_config['file_key']
mimetype = file_config['mimetype']

# {'file_input': {'file_key': 'plugin_config_d2234fd802054faf80babe0679a97fa9.json', 'mimetype': 'application/json'}}
print(file_config)

# 获取文件内容
file_bytes = await self.get_config_file(file_key)
```

> info:
>
> 常见 mimetype 与文件扩展名对应参考：[mdn 文档](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Guides/MIME_types/Common_types)

### type: array\[file]

多文件上传。与 file 类型类似，但支持上传多个文件，最终以 `[{"file_key": "xxxxx.xxx", "mimetype": "xxxxx"}]` 格式传递给插件。

```yaml
- name: resource_files
  type: array[file]
  accept: 'image/*'  # 可选，指定接受的文件 MIME 类型
  ...
```

在插件中获取文件：

```python
# 从配置中获取文件列表
files_config = self.get_config()['resource_files']

for file_config in files_config:
    file_key = file_config['file_key']
    mimetype = file_config['mimetype']

    # 获取文件内容
    file_bytes = await self.get_config_file(file_key)
```

### type: llm-model-selector

LLM 模型选择器。会展示一个 LLM 模型选择器，可选择已配置的 LLM 模型，最终结果表示为 LLM 模型 uuid。

```yaml
- name: model
  type: llm-model-selector
  ...
```

### type: bot-selector

Bot 选择器。会展示一个 Bot 选择器，可选择已配置的 Bot，最终结果表示为 Bot uuid。

```yaml
- name: bot
  type: bot-selector
  ...
```

在插件中使用 Bot uuid：

```python
# 从配置中获取 Bot UUID
bot_uuid = self.get_config()['bot']
print(bot_uuid)  # 输出: '550e8400-e29b-41d4-a716-446655440000'
```

### type: tools-selector

工具选择器。会展示一个多选工具选择器，可选择已注册的工具（插件工具和 MCP 工具），最终结果表示为工具名称数组。

```yaml
- name: selected_tools
  type: tools-selector
  ...
```

在插件中使用选中的工具名称：

```python
# 从配置中获取选中的工具名称列表
selected_tools = self.get_config()['selected_tools']
print(selected_tools)  # 输出: ['get_weather_alerts', 'web_search']

# 调用选中的工具
for tool_name in selected_tools:
    result = await self.plugin.call_tool(
        tool_name=tool_name,
        parameters={"query": "hello"},
        session={},
        query_id=0,
    )
```

## 接下来做什么

该教程将指引您逐步完善插件功能。

- 添加组件：插件组件是插件的核心功能单元，您可以根据需求[添加组件](https://langbot.app/docs/zh/plugin/dev/components/add.md)。

---

# 添加组件

Source: https://langbot.app/docs/zh/plugin/dev/components/add

插件由一种或多种组件构成，为 LangBot 提供不同的功能。目前支持的组件类型有：

- 插件处理器（运行器）：处理机器人收到的消息、成员入群等事件。详见[开发教程](https://langbot.app/docs/zh/plugin/dev/components/runner.md)。
- Agent 使用的运行器：为 Agent 提供模型调用、外部 Agent 服务连接等运行方式。
- 事件监听器（EventListener）：监听流水线执行期间的事件，对上下文或流水线进行修改。
- 命令（Command）：由用户通过`!`（或其他已设置的前缀）开头的命令消息触发。
- 工具（Tool）：供 LangBot 内置的 Local Agent 在执行期间由 LLM 调用。
- RAG 引擎（KnowledgeEngine）：为 LangBot 提供知识库的索引和检索能力，管理文档摄取、检索和删除。
- 解析器（Parser）：在文档摄取前将 PDF、Word 等二进制文件解析为结构化文本，供 RAG 引擎使用。
- 页面（Page）：在 LangBot WebUI 侧边栏中注册自定义可视化页面，提供管理面板、数据展示等交互式界面。

## 添加组件

在插件目录下执行命令：

```bash
lbp comp <component_type>
```

例如，添加一个事件监听器：

```bash
lbp comp EventListener
```

请根据提示输入组件的配置（若有）。

```bash
➜  HelloPlugin > lbp comp EventListener
Generating component EventListener...
Component EventListener generated successfully.
组件 EventListener 生成成功。
➜  HelloPlugin >
```

> :
>
> CLI 将在插件目录下生成一个 `components` 目录，并在其中创建组件对应目录
>
> ```
> .
> ├── assets
> │   └── icon.svg
> ├── components
> │   ├── __init__.py
> │   └── event_listener
> │       ├── __init__.py
> │       ├── default.py
> │       └── default.yaml
> ├── main.py
> ├── manifest.yaml
> ├── README.md
> └── requirements.txt
> ```
>
> 同时，会在插件的`manifest.yaml`中添加组件发现配置：
>
> ```yaml
> ...
> components:
>     EventListener:
>       fromDirs:
>       - path: components/event_listener/
> ...
> ```
>
> 如需删除组件，可自行删除对应信息。

## 组件类型

各个组件的详细使用方式请参考：

- [运行器](https://langbot.app/docs/zh/plugin/dev/components/runner.md)
- [EventListener](https://langbot.app/docs/zh/plugin/dev/components/event-listener.md)
- [Command](https://langbot.app/docs/zh/plugin/dev/components/command.md)
- [Tool](https://langbot.app/docs/zh/plugin/dev/components/tool.md)
- [KnowledgeEngine](https://langbot.app/docs/zh/plugin/dev/components/knowledge-engine.md)
- [Parser](https://langbot.app/docs/zh/plugin/dev/components/parser.md)
- [Page](https://langbot.app/docs/zh/plugin/dev/components/page.md)

---

# 组件：命令

Source: https://langbot.app/docs/zh/plugin/dev/components/command

命令组件由用户通过`!`（或其他已设置的前缀）开头的命令消息触发。如下是命令`!help`的触发示例：

![](https://langbot.app/docs/images/zh/plugin/dev/components/command_use.png)

## 添加命令组件

单个插件中能添加任意数量的命令，请在插件目录执行命令`lbp comp Command`，并根据提示输入命令的配置。

```bash
➜  HelloPlugin > lbp comp Command
Generating component Command...
Command name: info
Command description: Show information of the query
Component Command generated successfully.
组件 Command 生成成功。
```

现在即会在`components/commands/`目录下生成`info.yaml`和`info.py`文件，`.yaml`定义了`!info`命令的基础信息，`.py`是该命令的处理程序：

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   ├── commands
│   │   ├── __init__.py
│   │   ├── info.py
│   │   └── info.yaml
...
```

## 清单文件：命令组件

```yaml
apiVersion: v1  # 请勿修改
kind: Command  # 请勿修改
metadata:
  name: info  # 命令名称，在使用时，用户会通过 !info 触发该命令
  label:  # 命令显示名称，用于显示在 LangBot 的 UI 上，支持多语言
    en_US: Info
    zh_Hans: Info
  description:  # 命令描述，用于显示在 LangBot 的 UI 上，支持多语言。可选。
    en_US: 'Show information of the query'
    zh_Hans: '发送此次消息的详细信息'
spec:
execution:
  python:
    path: info.py  # 命令处理程序，请勿修改
    attr: Info  # 命令处理程序的类名，与 info.py 中的类名一致
```

## 插件处理

默认会生成如下代码(`components/command/<命令名称>.py`)，您需要在`Info`类的`initialize`方法中注册并实现子命令的处理逻辑。

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from typing import Any, AsyncGenerator

from langbot_plugin.api.definition.components.command.command import Command, Subcommand
from langbot_plugin.api.entities.builtin.command.context import ExecuteContext, CommandReturn


class Info(Command):
    
    async def initialize(self):
        await super().initialize()
        
        "Fill with your code here"
```

添加子命令：

```python
...
class Info(Command):
    
    async def initialize(self):
        await super().initialize()
        
        @self.subcommand(
            name="",  # 空字符串表示根命令
            help="Show information of the query", # 命令帮助信息
            usage="info", # 命令使用示例，显示在命令帮助信息中
            aliases=["i"], # 命令别名
        )
        async def send(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]:
            print(context)

            reply_text = f"Query ID: {context.query_id}\n"
            reply_text += f"command: {context.command}\n"
            reply_text += f"command_text: {context.command_text}\n"
            reply_text += f"params: {context.params}\n"
            reply_text += f"crt_params: {context.crt_params}\n"
            reply_text += f"privilege: {context.privilege}\n"
            reply_text += f"session: {context.session.launcher_type.value}_{context.session.launcher_id}\n"
            
            yield CommandReturn(
                text=reply_text,
            )

        @self.subcommand(
            name="field",
            help="Show information of the field",
            usage="info field",
            aliases=["f"],
        )
        async def field(self, context: ExecuteContext) -> AsyncGenerator[CommandReturn, None]:
            print(context)

            field_name = context.crt_params[0]
            field_value = getattr(context, field_name)

            yield CommandReturn(
                text=f"{field_name}: {field_value}",
            )
```

该代码中，`send`函数通过装饰器`@self.subcommand`注册为子命令，并在其中打印了命令的上下文（ExecuteContext）信息并拼接成一条回复消息。

### 子命令注册

`name` 为子命令名称，留空表示处理主命令。不为空则匹配第二个参数为命令，例如：

- `!info` 匹配 name="" 的子命令
- `!info field` 匹配 name="field" 的子命令
- `!info field value` 匹配 name="field" 的子命令，`value` 为子命令参数
- 特殊地，`name="*"` 匹配所有未匹配的一级子命令，并将`info`后的每一节作为参数传递传递参数，例如`!info 123`, `!info abc`. 此时可以从`context.crt_params`中获取到`['123']`或`['abc']`，取决于用户输入的参数。

子命令函数中，可通过 `context` 变量读取到命令参数。

上述命令效果如图：

![](https://langbot.app/docs/images/zh/plugin/dev/components/info_command_demo.png)

### 命令上下文

```python

class ExecuteContext(pydantic.BaseModel):
    """单次命令执行上下文"""

    query_id: int
    """请求ID"""

    session: provider_session.Session
    """本次消息所属的会话对象"""

    command_text: str
    """命令完整文本"""

    command: str
    """命令名称"""

    crt_command: str
    """当前命令
    
    多级命令中crt_command为当前命令，command为根命令。
    例如：!plugin on Webwlkr
    处理到plugin时，command为plugin，crt_command为plugin
    处理到on时，command为plugin，crt_command为on
    """

    params: list[str]
    """命令参数
    
    整个命令以空格分割后的参数列表
    """

    crt_params: list[str]
    """当前命令参数

    多级命令中crt_params为当前命令参数，params为根命令参数。
    例如：!plugin on Webwlkr
    处理到plugin时，params为['on', 'Webwlkr']，crt_params为['on', 'Webwlkr']
    处理到on时，params为['on', 'Webwlkr']，crt_params为['Webwlkr']
    """

    privilege: int
    """会话权限级别"""

    ...
```

### 命令返回值

命令返回值(CommandReturn)目前支持返回文本（text）和图片（image\_url，图片链接）、错误（error）。

```python
yield CommandReturn(
    text=reply_text,
)

yield CommandReturn(
    image_url=image_url,
)
```

命令处理支持返回多条消息，故请使用`yield`语句返回消息。

具体的返回值请参考`CommandReturn`的定义：[langbot\_plugin.api.entities.builtin.command.context.CommandReturn](https://github.com/langbot-app/langbot-plugin-sdk/tree/main/src/langbot_plugin/api/entities/builtin/command/context.py)

## 一个安装，多份用法

一个命令会被**多个会话并发触发**：

- 配置每次调用读取，不要在 `initialize()` 中读取后缓存到实例。
- 不要把命令参数、返回值或会话数据留在实例字段或模块级变量上；`ExecuteContext` 只在本次执行内有效。
- 并发触发意味着实例字段会被交织写入，不要用它保存「当前会话」之类的状态；需要跨调用保留的数据放 Host 存储，键包含会话身份。
- 如果按安装维护了进程内缓存，请在 `on_installation_revoked(binding)` 中释放。

以上约束的完整说明见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

## 接下来做什么

您已经了解了命令注册和命令执行的基本信息，接下来可以：

- 查看完整的 [`ExecuteContext` 上下文 API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md#command)
- 查看 [LangBot API](https://langbot.app/docs/zh/plugin/dev/apis/common.md)

---

# 组件：事件监听器

Source: https://langbot.app/docs/zh/plugin/dev/components/event-listener

> info:
>
> 本组件用于扩展流水线的处理流程。如果您需要处理机器人收到的消息、成员入群等事件，请参阅[事件处理器](https://langbot.app/docs/zh/plugin/dev/components/runner.md)。

LangBot 的流水线在运行期间会产生一些事件，供插件 Hook 并处理。每个插件中只允许添加一个事件监听器(components/event\_listener/default.yaml)，但在其中可以注册任意数量的事件。

## 添加事件监听器组件

请在插件目录执行命令`lbp comp EventListener`，创建事件监听器组件不需要填写任何配置。

```bash
➜  HelloPlugin > lbp comp EventListener
Generating component EventListener...
Component EventListener generated successfully.
组件 EventListener 生成成功。
```

现在即会在`components/event_listener/`目录下生成`default.yaml`和`default.py`文件，`.yaml`定义了事件监听器的基础信息，`.py`是该事件监听器的处理程序：

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   └── event_listener
│       ├── __init__.py
│       ├── default.py
│       └── default.yaml
...
```

## 清单文件：事件监听器

由于每个插件仅允许添加一个事件监听器，故清单文件中不需要修改任何内容。

## 插件处理

默认会生成如下代码(components/event\_listener/default.py)，您需要在`DefaultEventListener`类的`initialize`方法中注册并实现事件的处理逻辑。

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from langbot_plugin.api.definition.components.common.event_listener import EventListener
from langbot_plugin.api.entities import events, context


class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()

        "Fill with your code here"
```

添加对特定事件的监听：

```python
...
class DefaultEventListener(EventListener):

    async def initialize(self):
        await super().initialize()
        
        @self.handler(events.PersonMessageReceived)
        async def handler(event_context: context.EventContext):
            print("Hello LangBot Plugin!")
            print(event_context)
            
            await event_context.reply(
                platform_message.MessageChain([
                    platform_message.Plain(text=f"Hello from Nahida Plugin!"),
                ])
            )
```

此代码将注册对`PersonMessageReceived（收到来自私聊的任何消息）`事件的监听，并在事件触发时打印事件的上下文（EventContext）信息，并调用事件上下文 API 回复一条消息。

EventContext 保存了该此事件触发的通用上下文信息，而 EventContext.event 为 PersonMessageReceived （或其他对应的事件类型）的对象，保存了该事件的详细信息。

```python
# EventContext 的定义摘要
class EventContext(pydantic.BaseModel):
    """事件上下文, 保存此次事件运行的信息"""
    ...

    event: pydantic.SerializeAsAny[BaseEventModel]
    """此次事件的对象，具体类型为handler注册时指定监听的类型，可查看events.py中的定义"""
    
    ...
```

## 事件注册

事件注册通过装饰器`@self.handler`实现，装饰器参数为事件类型。可监听的事件均在`langbot_plugin.api.entities.builtin.events`中定义。

## 一个安装，多份用法

同一个事件监听器会被**多个工作区、多个事件并发调用**：

- 不要在实例上按事件累积状态（计数、最近事件、会话映射等），并发回调会互相覆盖。
- 回调只从当前 `EventContext` 取数据，不要跨调用复用上下文或其字段。
- 需要跨调用保留的数据放 Host 存储，键包含安装标识与事件相关的身份（工作区、会话等）。
- 如果按安装维护了进程内状态，请在 `on_installation_revoked(binding)` 中释放。

以上约束的完整说明见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

## 接下来做什么

您已经了解了事件监听器的基本信息，接下来可以：

- 在[流水线事件](https://langbot.app/docs/zh/plugin/dev/apis/pipeline-events.md)中查看可监听的事件及字段
- 查看完整的 [`EventContext` 上下文 API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md#eventlistener)
- 查看 [LangBot API](https://langbot.app/docs/zh/plugin/dev/apis/common.md)

---

# 组件：知识引擎

Source: https://langbot.app/docs/zh/plugin/dev/components/knowledge-engine

RAG 引擎（KnowledgeEngine）组件允许插件为 LangBot 提供完整的知识库索引与检索能力。用户在 LangBot 中创建知识库时，可以选择由插件提供的 RAG 引擎来管理文档的摄取、检索和删除。或通过插件桥接来自 Dify、RAGFlow、FastGPT 等业内先进知识库服务。

## 添加 RAG 引擎组件

单个插件中能添加任意数量的 RAG 引擎，请在插件目录执行命令 `lbp comp KnowledgeEngine`，并根据提示输入 RAG 引擎的配置。

```bash
➜  MyRAGPlugin > lbp comp KnowledgeEngine
Generating component KnowledgeEngine...
Knowledge Engine name: simple_rag
Knowledge Engine description: A simple Knowledge Engine with built-in chunking and retrieval
Component KnowledgeEngine generated successfully.
组件 KnowledgeEngine 生成成功。
```

现在即会在 `components/knowledge_engine/` 目录下生成 `simple_rag.yaml` 和 `simple_rag.py` 文件，`.yaml` 定义了 RAG 引擎的基础信息和配置 Schema，`.py` 是该引擎的处理程序：

```bash
➜  MyRAGPlugin > tree
...
├── components
│   ├── __init__.py
│   └── knowledge_engine
│       ├── __init__.py
│       ├── simple_rag.py
│       └── simple_rag.yaml
...
```

## 清单文件：RAG 引擎

```yaml
apiVersion: v1  # 请勿修改
kind: KnowledgeEngine  # 请勿修改
metadata:
  name: simple_rag  # RAG 引擎名称，用于标识该引擎
  label:
    en_US: Simple Knowledge Engine  # 引擎显示名称，用于显示在 LangBot 的 UI 上，支持多语言
    zh_Hans: 简易 RAG 引擎
    ja_JP: シンプル RAG エンジン
  description:
    en_US: 'A simple Knowledge Engine with built-in chunking and retrieval'
    zh_Hans: '内置分块和检索能力的简易 RAG 引擎'
    ja_JP: 'チャンキングと検索を内蔵したシンプルなRAGエンジン'
spec:
  creation_schema:  # 用户创建知识库时需要填写的配置参数
    - name: chunk_size
      label:
        en_US: Chunk Size
        zh_Hans: 分块大小
      type: integer
      required: false
      default: 500
    - name: chunk_overlap
      label:
        en_US: Chunk Overlap
        zh_Hans: 分块重叠
      type: integer
      required: false
      default: 50
  retrieval_schema:  # 检索时可配置的参数
    - name: score_threshold
      label:
        en_US: Score Threshold
        zh_Hans: 分数阈值
      type: float
      required: false
      default: 0.5
execution:
  python:
    path: simple_rag.py  # 引擎处理程序，请勿修改
    attr: SimpleRag  # 引擎处理程序的类名，与 simple_rag.py 中的类名一致
```

配置项格式可参考：[插件清单配置项格式](https://langbot.app/docs/zh/plugin/dev/basic-info.md)

### creation\_schema 与 retrieval\_schema

与旧版 `KnowledgeRetriever` 组件使用单一 `spec.config` 不同，KnowledgeEngine 使用两个独立的 Schema：

- **creation\_schema**：用户创建知识库时填写的参数，会在摄取和检索时通过 `creation_settings` 传入插件。
- **retrieval\_schema**：用户在检索知识库时可调整的参数，通过 `retrieval_settings` 传入插件。

## 能力声明

KnowledgeEngine 可以声明自身支持的能力，LangBot 会根据能力声明决定 UI 展示和可用操作：

```python
from langbot_plugin.api.definition.components.knowledge_engine.engine import KnowledgeEngine, KnowledgeEngineCapability

class SimpleRag(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return [
            KnowledgeEngineCapability.DOC_INGESTION,    # 支持文档上传和处理
        ]
```

可用的能力常量：

| 能力              | 说明                                                                                                                                                                     |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOC_INGESTION` | 支持文档上传和处理。声明此能力后，LangBot 将在知识库详情中显示"文档"标签页；若该插件是用于桥接其他的知识库服务或不需要用户上传文档，则可不提供该能力声明。                                                                                     |
| `DOC_PARSING`   | 支持原生文档解析（文件到文本的提取）。声明此能力后，用户上传文档时可以选择使用 RAG 引擎内置的解析能力，而不需要外部 [Parser 插件](https://langbot.app/docs/zh/plugin/dev/components/parser.md)。若未声明此能力，则必须安装外部 Parser 插件才能上传文档。 |

> info:
>
> 其他检索行为（如重排序、混合搜索等）由插件的 `retrieval_schema` 控制，不需要能力标志。

## 插件处理

默认会生成如下代码（`components/knowledge_engine/<引擎名称>.py`），您需要实现 `ingest`、`retrieve`、`delete_document` 三个核心方法。完整代码可在 [langbot-plugin-demo](https://github.com/langbot-app/langbot-plugin-demo) 的 `SimpleKnowledgeEngine` 中找到。

```python
from langbot_plugin.api.definition.components.knowledge_engine.engine import KnowledgeEngine, KnowledgeEngineCapability
from langbot_plugin.api.entities.builtin.rag.models import (
    IngestionContext,
    IngestionResult,
)
from langbot_plugin.api.entities.builtin.rag.context import (
    RetrievalContext,
    RetrievalResponse,
    RetrievalResultEntry,
)
from langbot_plugin.api.entities.builtin.rag.enums import DocumentStatus
from langbot_plugin.api.entities.builtin.provider.message import ContentElement


class SimpleRag(KnowledgeEngine):

    @classmethod
    def get_capabilities(cls) -> list[str]:
        return [KnowledgeEngineCapability.DOC_INGESTION]

    async def on_knowledge_base_create(self, kb_id: str, config: dict) -> None:
        """知识库创建时的回调，可用于初始化资源"""
        pass

    async def on_knowledge_base_delete(self, kb_id: str) -> None:
        """知识库删除时的回调，可用于清理资源"""
        pass

    async def ingest(self, context: IngestionContext) -> IngestionResult:
        """将文档摄取到知识库中"""

        # 1. 获取文件内容
        file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)

        # 2. 解析文档并分块
        text = file_bytes.decode('utf-8')
        chunk_size = context.creation_settings.get('chunk_size', 500)
        chunk_overlap = context.creation_settings.get('chunk_overlap', 50)
        chunks = self._split_text(text, chunk_size, chunk_overlap)

        # 3. 调用宿主嵌入模型生成向量
        embedding_model_uuid = context.creation_settings.get('embedding_model_uuid', '')
        vectors = await self.plugin.invoke_embedding(embedding_model_uuid, chunks)

        # 4. 写入宿主向量数据库
        collection_id = context.get_collection_id()
        ids = [f"{context.file_object.metadata.document_id}_{i}" for i in range(len(chunks))]
        metadata = [{"document_id": context.file_object.metadata.document_id, "chunk_index": i, "text": chunks[i]} for i in range(len(chunks))]
        await self.plugin.vector_upsert(collection_id, vectors, ids, metadata)

        return IngestionResult(
            document_id=context.file_object.metadata.document_id,
            status=DocumentStatus.COMPLETED,
            chunks_created=len(chunks),
        )

    async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
        """从知识库中检索相关内容"""

        # 1. 生成查询向量
        embedding_model_uuid = context.creation_settings.get('embedding_model_uuid', '')
        query_vectors = await self.plugin.invoke_embedding(embedding_model_uuid, [context.query])
        query_vector = query_vectors[0]

        # 2. 向量搜索
        collection_id = context.get_collection_id()
        results = await self.plugin.vector_search(collection_id, query_vector, top_k=context.retrieval_settings.get('top_k', 5))

        # 3. 转换为检索结果
        entries = []
        for r in results:
            entry = RetrievalResultEntry(
                id=r.get('id', ''),
                content=[ContentElement.from_text(r.get('metadata', {}).get('text', ''))],
                metadata=r.get('metadata', {}),
                distance=r.get('score', 0.0),
            )
            entries.append(entry)

        return RetrievalResponse(
            results=entries,
            total_found=len(entries),
            metadata={},
        )

    async def delete_document(self, kb_id: str, document_id: str) -> bool:
        """从知识库中删除文档及其关联数据"""
        collection_id = kb_id
        deleted = await self.plugin.vector_delete(collection_id, file_ids=[document_id])
        return deleted > 0
```

### 生命周期钩子

KnowledgeEngine 提供两个生命周期钩子，会在知识库创建和删除时被调用：

```python
async def on_knowledge_base_create(self, kb_id: str, config: dict) -> None:
    """知识库创建时的回调

    Args:
        kb_id: 知识库 UUID
        config: 用户在创建时填写的配置（creation_schema 中的字段）
    """

async def on_knowledge_base_delete(self, kb_id: str) -> None:
    """知识库删除时的回调

    Args:
        kb_id: 知识库 UUID
    """
```

### 文档摄取

`ingest` 方法在用户上传文档到知识库时被调用：

```python
async def ingest(self, context: IngestionContext) -> IngestionResult:
```

**IngestionContext** 包含以下信息：

```python
class IngestionContext(pydantic.BaseModel):
    file_object: FileObject        # 待摄取的文件对象
    knowledge_base_id: str         # 目标知识库 ID
    collection_id: str | None      # 向量集合 ID（默认回退到 knowledge_base_id）
    creation_settings: dict        # 知识库创建时的配置参数
    parsed_content: ParseResult | None  # 外部 Parser 插件的预解析内容（若有）
```

**FileObject** 包含文件元信息：

```python
class FileObject(pydantic.BaseModel):
    metadata: FileMetadata    # 包含 filename, file_size, mime_type, document_id, knowledge_base_id 等
    storage_path: str         # 文件在存储系统中的路径
```

**IngestionResult** 应返回摄取结果：

```python
class IngestionResult(pydantic.BaseModel):
    document_id: str                  # 文档 ID
    status: DocumentStatus            # 处理状态：COMPLETED / FAILED
    chunks_created: int = 0           # 创建的分块数量
    error_message: str | None = None  # 失败时的错误信息
    metadata: dict = {}               # 额外元数据
```

### 知识检索

`retrieve` 方法在知识库被查询时调用：

```python
async def retrieve(self, context: RetrievalContext) -> RetrievalResponse:
```

**RetrievalContext** 包含以下信息：

```python
class RetrievalContext(pydantic.BaseModel):
    query: str                           # 查询文本
    knowledge_base_id: str | None        # 知识库 ID
    collection_id: str | None            # 向量集合 ID
    retrieval_settings: dict             # 检索时的配置参数（retrieval_schema 中的字段）
    creation_settings: dict              # 知识库创建时的配置参数
    filters: dict                        # 元数据过滤条件（Chroma 风格 where 语法）
```

> info:
>
> LangBot 宿主会在传入 `retrieval_settings` 前自动注入 `top_k` 默认值（默认为 5），插件可通过 `context.retrieval_settings.get('top_k', 5)` 获取。
>
> `filters` 字段包含从 `retrieval_settings` 中提取的 Chroma 风格 `where` 过滤条件。当调用方在检索设置中提供 `filters`（例如按时间范围、文件类型或自定义元数据字段过滤文档）时，宿主会填充此字段，插件可据此在检索时进行过滤。如果未提供过滤条件，此字段为空 dict。

**RetrievalResponse** 应返回检索结果：

```python
class RetrievalResponse(pydantic.BaseModel):
    results: list[RetrievalResultEntry]  # 检索结果列表
    total_found: int                     # 匹配的总数
    metadata: dict                       # 额外元数据
```

**RetrievalResultEntry** 表示单个检索结果：

```python
class RetrievalResultEntry(pydantic.BaseModel):
    id: str                       # 结果 ID
    content: list[ContentElement] # 内容，使用 ContentElement.from_text() 创建
    metadata: dict                # 元数据
    distance: float               # 距离分数（越小越相关）
    score: float | None = None    # 相似度分数（越大越相关）
```

### 文档删除

`delete_document` 方法在用户从知识库删除文档时调用：

```python
async def delete_document(self, kb_id: str, document_id: str) -> bool:
    """删除文档及其关联数据

    Args:
        kb_id: 知识库 ID
        document_id: 文档 ID

    Returns:
        是否删除成功
    """
```

## 宿主 RAG API

KnowledgeEngine 组件可以通过 `self.plugin` 调用 LangBot 宿主提供的 RAG 相关 API，包括嵌入模型调用、向量数据库操作和文件读取。

### 调用嵌入模型

```python
async def invoke_embedding(
    self,
    embedding_model_uuid: str,
    texts: list[str],
) -> list[list[float]]:
    """调用宿主的嵌入模型生成向量

    Args:
        embedding_model_uuid: 嵌入模型 UUID
        texts: 待嵌入的文本列表

    Returns:
        向量列表，每个输入文本对应一个向量
    """

# 调用示例
vectors = await self.plugin.invoke_embedding("model_uuid", ["Hello", "World"])
```

### 向量写入

```python
async def vector_upsert(
    self,
    collection_id: str,
    vectors: list[list[float]],
    ids: list[str],
    metadata: list[dict] | None = None,
) -> None:
    """将向量写入宿主的向量数据库

    Args:
        collection_id: 目标集合 ID
        vectors: 向量列表
        ids: 向量唯一标识列表
        metadata: 可选的元数据列表
    """

# 调用示例
await self.plugin.vector_upsert(
    collection_id="kb_uuid",
    vectors=[[0.1, 0.2, ...], [0.3, 0.4, ...]],
    ids=["chunk_0", "chunk_1"],
    metadata=[{"document_id": "doc1"}, {"document_id": "doc1"}],
)
```

### 向量搜索

```python
async def vector_search(
    self,
    collection_id: str,
    query_vector: list[float],
    top_k: int = 5,
    filters: dict | None = None,
) -> list[dict]:
    """在宿主的向量数据库中搜索相似向量

    Args:
        collection_id: 目标集合 ID
        query_vector: 查询向量
        top_k: 返回结果数量
        filters: 可选的元数据过滤条件

    Returns:
        搜索结果列表（包含 id, score, metadata 等字段）
    """

# 调用示例
results = await self.plugin.vector_search(
    collection_id="kb_uuid",
    query_vector=[0.1, 0.2, ...],
    top_k=5,
)
# 返回格式: [{"id": "chunk_0", "score": 0.123, "metadata": {"document_id": "doc1", ...}}, ...]
```

> info:
>
> `vector_search` 返回的每个结果为 dict，包含 `id`（向量 ID）、`score`（距离分数）和 `metadata`（写入时附带的元数据）三个字段。如果需要在检索结果中返回文本内容，请在摄取阶段将文本存入 metadata 中。

### 向量删除

```python
async def vector_delete(
    self,
    collection_id: str,
    file_ids: list[str] | None = None,
    filters: dict | None = None,
) -> int:
    """从宿主的向量数据库中删除向量

    Args:
        collection_id: 目标集合 ID
        file_ids: 要删除的文件 ID 列表
        filters: 可选的元数据过滤条件

    Returns:
        删除的条目数量
    """

# 调用示例
deleted = await self.plugin.vector_delete(
    collection_id="kb_uuid",
    file_ids=["doc_001"],
)
```

> info:
>
> `filters` 参数支持 Chroma 风格的 `where` 语法进行元数据过滤。多个顶层键之间为 AND 关系。支持的运算符：`$eq`、`$ne`、`$gt`、`$gte`、`$lt`、`$lte`、`$in`、`$nin`。示例：`{"file_id": {"$eq": "abc"}}`。
>
> **注意：** Chroma、Qdrant 和 SeekDB 存储完整的元数据，可以对任意字段进行过滤。Milvus 和 pgvector 仅存储 `text`、`file_id` 和 `chunk_uuid`，对其他字段的过滤将被静默忽略。

```python
async def get_knowledge_file_stream(self, storage_path: str) -> bytes:
    """从宿主存储中获取文件内容

    Args:
        storage_path: 文件的存储路径（来自 FileObject.storage_path）

    Returns:
        文件内容的字节数据
    """

# 调用示例
file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)
```

## 一个安装，多份用法

一个 RAG 引擎会被**多个知识库**同时选用，而平台的存储键 `(实例, 工作区, 组件类型, 插件名, key)` 不含知识库维度：

- 持久化与缓存的键必须包含**知识库 ID**，否则不同知识库的向量、文档状态会互相覆盖。
- 锁与「待对账」状态必须按 `(安装, 知识库)` 记；**一个知识库摄取失败不得阻断同一安装下其他知识库的摄取与检索**。
- 只有「已经派发、结果未知」的变更才应进入需要人工对账的状态；确定性的校验错误与派发前的取消不应影响后续调用。
- 遥测与诊断上报失败不得影响业务：日志/上报出错不要中断摄取或检索，也不要把租户数据写进进程级单例。
- 如果按安装维护了进程内缓存或状态，请在 `on_installation_revoked(binding)` 中释放。

以上约束的完整说明见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

## 测试 RAG 引擎

创建完成后，在插件目录执行命令 `lbp run`，启动调试。然后在 LangBot 中：

1. 进入"知识库"页面
2. 点击"创建知识库"
3. 选择您的插件提供的 RAG 引擎，并根据引擎的 `creation_schema` 填写配置
4. 创建成功后，可上传文档测试摄取能力（如引擎声明了 `DOC_INGESTION` 能力）
5. 在流水线中绑定该知识库，测试检索能力

---

# 组件：知识检索器

Source: https://langbot.app/docs/zh/plugin/dev/components/knowledge-retriever

知识检索器（Knowledge Retriever）组件允许插件为 LangBot 提供外部知识库检索能力。当用户在 LangBot 中创建外部知识库时，可以选择由插件提供的知识检索器来检索知识。

![](https://langbot.app/docs/images/zh/plugin/dev/components/knowledge_retriever_use.png)

## 添加知识检索器组件

单个插件中能添加任意数量的知识检索器，请在插件目录执行命令`lbp comp KnowledgeRetriever`，并根据提示输入知识检索器的配置。

```bash
➜  FastGPTRetriever > lbp comp KnowledgeRetriever
Generating component KnowledgeRetriever...
KnowledgeRetriever name: fastgpt
KnowledgeRetriever description: Retrieve knowledge from FastGPT knowledge bases
Component KnowledgeRetriever generated successfully.
组件 KnowledgeRetriever 生成成功。
```

现在即会在`components/knowledge_retriever/`目录下生成`fastgpt.yaml`和`fastgpt.py`文件，`.yaml`定义了知识检索器的基础信息和配置参数，`.py`是该知识检索器的处理程序：

```bash
➜  FastGPTRetriever > tree
...
├── components
│   ├── __init__.py
│   └── knowledge_retriever
│       ├── __init__.py
│       ├── fastgpt.py
│       └── fastgpt.yaml
...
```

## 清单文件：知识检索器

```yaml
apiVersion: v1  # 请勿修改
kind: KnowledgeRetriever  # 请勿修改
metadata:
  name: fastgpt  # 知识检索器名称，用于标识该检索器
  label:
    en_US: FastGPT Knowledge Base  # 检索器显示名称，用于显示在 LangBot 的 UI 上，支持多语言
    zh_Hans: FastGPT 知识库
    ja_JP: FastGPT ナレッジベース
  description:
    en_US: 'Retrieve knowledge from FastGPT knowledge bases'  # 检索器描述，用于显示在 LangBot 的 UI 上，支持多语言。可选
    zh_Hans: '从 FastGPT 知识库中检索知识'
    ja_JP: 'FastGPT ナレッジベースから知識を取得'
  icon: assets/icon.svg  # 检索器图标，会被展示在外部知识库配置页面
spec:
  config:  # 检索器配置参数，用户在创建外部知识库时需要填写这些参数
    - name: api_base_url  # 参数名称
      type: string  # 参数类型：string, number, boolean, select
      label:
        en_US: API Base URL
        zh_Hans: API 基础地址
        ja_JP: API ベース URL
      description:
        en_US: 'Base URL for FastGPT API'
        zh_Hans: 'FastGPT API 基础地址'
        ja_JP: 'FastGPT API ベース URL'
      default: 'http://localhost:3000'  # 参数默认值
      required: true  # 是否必填
    - name: api_key
      type: string
      label:
        en_US: FastGPT API Key
        zh_Hans: FastGPT API Key
        ja_JP: FastGPT API キー
      description:
        en_US: 'API key from your FastGPT instance'
        zh_Hans: '从您的 FastGPT 实例获取的 API Key'
        ja_JP: 'FastGPT インスタンスから取得した API Key'
      default: ''
      required: true
    - name: search_mode  # select 类型参数示例
      type: select
      label:
        en_US: Search Mode
        zh_Hans: 搜索模式
        ja_JP: 検索モード
      description:
        en_US: 'The search method to use'
        zh_Hans: '使用的搜索方法'
        ja_JP: '使用する検索方法'
      default: 'embedding'
      options:  # select 类型参数需要定义选项列表
      - name: 'embedding'
        label:
          en_US: 'Embedding Search'
          zh_Hans: '向量搜索'
          ja_JP: '埋め込み検索'
      - name: 'fullTextRecall'
        label:
          en_US: 'Full-Text Recall'
          zh_Hans: '全文检索'
          ja_JP: '全文検索'
    - name: using_rerank  # boolean 类型参数示例
      type: boolean
      label:
        en_US: Use Re-ranking
        zh_Hans: 使用重排序
        ja_JP: リランキングを使用
      description:
        en_US: 'Whether to use re-ranking'
        zh_Hans: '是否使用重排序'
        ja_JP: 'リランキングを使用するかどうか'
      default: false
      required: false
execution:
  python:
    path: fastgpt.py  # 检索器处理程序，请勿修改
    attr: FastGPT  # 检索器处理程序的类名，与 fastgpt.py 中的类名一致
```

配置项格式可参考：[插件清单配置项格式](https://langbot.app/docs/zh/plugin/dev/basic-info.md)

## 插件处理

默认会生成如下代码(`components/knowledge_retriever/<检索器名称>.py`)，您需要在`FastGPT`类的`retrieve`方法中实现知识检索逻辑。完整代码可在[langbot-plugin-demo](https://github.com/langbot-app/langbot-plugin-demo)中找到。

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
...

class FastGPT(KnowledgeRetriever):

    async def retrieve(self, context: RetrievalContext) -> list[RetrievalResultEntry]:
        """Retrieve knowledge from FastGPT knowledge base"""

        # 1. 获取配置参数
        api_base_url = self.config.get('api_base_url', 'http://localhost:3000')
        api_key = self.config.get('api_key')
        dataset_id = self.config.get('dataset_id')
        search_mode = self.config.get('search_mode', 'embedding')
        using_rerank = self.config.get('using_rerank', False)

        # 2. 参数验证
        if not api_key or not dataset_id:
            logger.error("Missing required configuration: api_key or dataset_id")
            return []

        # 3. 构建 API 请求
        url = f"{api_base_url.rstrip('/')}/api/core/dataset/searchTest"
        headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
        payload = {
            "datasetId": dataset_id,
            "text": context.query,  # 从 RetrievalContext 获取查询文本
            "searchMode": search_mode,
            "usingReRank": using_rerank,
        }

        try:
            # 4. 调用外部 API
            async with httpx.AsyncClient() as client:
                response = await client.post(url, json=payload, headers=headers, timeout=30.0)
                response.raise_for_status()
                result = response.json()

            # 5. 解析响应并转换为 RetrievalResultEntry
            results = []
            for record in result.get('data', []):
                # 合并主要数据和辅助数据作为内容
                content_text = '\n'.join([
                    record.get('q', ''),
                    record.get('a', '')
                ]).strip()

                # 创建检索结果条目
                entry = RetrievalResultEntry(
                    id=record.get('id', ''),
                    content=[ContentElement.from_text(content_text)],
                    metadata={
                        'dataset_id': record.get('datasetId', ''),
                        'source_name': record.get('sourceName', ''),
                        'score': record.get('score', 0.0),
                    },
                    # 将相似度分数转换为距离（分数越高，距离越小）
                    distance=1.0 - float(record.get('score', 0.0)),
                )
                results.append(entry)

            logger.info(f"Retrieved {len(results)} chunks from FastGPT dataset {dataset_id}")
            return results

        except httpx.HTTPStatusError as e:
            logger.error(f"HTTP error from FastGPT API: {e.response.status_code} - {e.response.text}")
            return []
        except httpx.RequestError as e:
            logger.error(f"Request error when calling FastGPT API: {str(e)}")
            return []
        except Exception as e:
            traceback.print_exc()
            logger.error(f"Unexpected error during retrieval: {str(e)}")
            return []
```

### 检索上下文

`RetrievalContext` 包含本次检索的上下文信息：

```python
class RetrievalContext(pydantic.BaseModel):
    """知识检索上下文"""

    query: str
    """查询文本，用户的检索问题"""
```

### 检索结果

检索结果需要转换为 `RetrievalResultEntry` 对象列表，每个对象代表一个检索到的知识块：

```python
class RetrievalResultEntry(pydantic.BaseModel):
    """单个检索结果条目"""

    id: str
    """结果 ID，唯一标识此条目"""

    content: list[ContentElement]
    """结果内容，使用 ContentElement.from_text() 创建文本内容"""

    metadata: dict[str, Any]
    """结果元数据，可以包含任意键值对，如来源、分数等"""

    distance: float
    """距离分数，表示与查询的相关度（越小越相关）
    通常通过 1.0 - similarity_score 计算"""
```

### 获取配置参数

通过 `self.config.get(参数名, 默认值)` 获取用户配置的参数值：

```python
# 获取字符串参数
api_base_url = self.config.get('api_base_url', 'http://localhost:3000')

# 获取数字参数
limit = self.config.get('limit', 5000)
similarity = self.config.get('similarity', 0.0)

# 获取布尔参数
using_rerank = self.config.get('using_rerank', False)

# 获取 select 参数
search_mode = self.config.get('search_mode', 'embedding')
```

## 一个安装，多份用法

一个知识检索器会被**多个知识库**选用，平台的存储键 `(实例, 工作区, 组件类型, 插件名, key)` 不含知识库维度：

- 检索所需的缓存、索引或中间结果必须按**知识库 ID** 隔离，键里要带上知识库 ID，不能放到实例上。
- 检索的锁与「待对账」状态按 `(安装, 知识库)` 记，一个知识库检索失败不得让同一安装下其他知识库的检索不可用。
- `RetrievalContext` 只在单次检索内有效，不要把它或检索结果保存到实例字段跨调用复用。
- 需要跨调用保留的知识库数据存到 Host 存储，键同时包含安装标识与知识库 ID。
- 如果按安装缓存了连接、索引或其他进程内状态，请在 `on_installation_revoked(binding)` 中释放。

以上约束的完整说明见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

## 测试检索器

创建完成后，在插件目录执行命令 `lbp run`，启动调试。然后在 LangBot 中：

1. 进入"知识库"页面
2. 添加外部知识库
3. 选择您的插件提供的知识检索器并填写配置

![](https://langbot.app/docs/images/zh/plugin/dev/components/knowledge_retriever_config.png)

保存后即可在 LangBot 流水线中选用该知识库。

---

# 组件：页面

Source: https://langbot.app/docs/zh/plugin/dev/components/page

Page 组件允许插件在 LangBot 的 WebUI 侧边栏中注册自定义的可视化页面。页面运行在 iframe 沙箱中，通过 Page SDK 与宿主通信，并可调用插件后端 API。

## 适用场景

- **管理面板**：为插件提供可视化的配置和数据管理界面（如 FAQ 管理、数据统计仪表盘）
- **数据展示**：展示插件运行时的统计数据、日志、图表等
- **交互式工具**：提供表单、编辑器等交互式界面

![](https://langbot.app/docs/images/zh/plugin/dev/components/plugin-page-demo.png)

## 添加页面组件

在插件目录执行命令：

```bash
lbp comp Page
```

根据提示输入页面名称后，会在 `components/pages/` 目录下生成页面文件：

```bash
├── components
│   └── pages
│       └── dashboard
│           ├── dashboard.yaml   # 页面清单
│           ├── dashboard.py     # 页面后端处理程序
│           ├── index.html       # 页面入口
│           └── i18n             # 翻译文件（可选）
│               ├── en_US.json
│               └── zh_Hans.json
```

同时，`manifest.yaml` 中会添加组件发现配置：

```yaml
spec:
  components:
    Page:
      fromDirs:
      - path: components/pages/
        maxDepth: 2
```

## 清单文件：页面

```yaml
apiVersion: v1  # 请勿修改
kind: Page  # 请勿修改
metadata:
  name: dashboard  # 页面唯一 ID，同一插件内不可重复
  label:
    en_US: Dashboard  # 页面显示名称，显示在 WebUI 侧边栏，支持多语言
    zh_Hans: 仪表盘
spec:
  path: index.html  # HTML 入口文件，相对于该 YAML 所在目录的路径
execution:
  python:
    path: dashboard.py  # 页面后端处理程序
    attr: DashboardPage  # 处理程序类名
```

## 后端处理

Page 组件的后端处理程序继承 `Page` 基类，实现 `handle_api` 方法来处理来自前端页面的 API 请求。

```python
from langbot_plugin.api.definition.components.page import Page, PageRequest, PageResponse


class DashboardPage(Page):

    async def handle_api(self, request: PageRequest) -> PageResponse:
        # request.endpoint: API 端点路径，如 '/stats'
        # request.method:   HTTP 方法（GET、POST、PUT、DELETE）
        # request.body:     请求体（已解析的 JSON，或 None）

        if request.endpoint == '/stats' and request.method == 'GET':
            # 从 Host 存储读取当前 installation 的数据
            entries = await self.load_entries_for_current_installation()
            return PageResponse.ok({'total': len(entries)})

        return PageResponse.fail(f'Unknown endpoint: {request.endpoint}')
```

### PageRequest 字段

| 字段         | 类型    | 说明                                   |
| ---------- | ----- | ------------------------------------ |
| `endpoint` | `str` | API 端点路径（如 `'/entries'`）             |
| `method`   | `str` | HTTP 方法（`GET`、`POST`、`PUT`、`DELETE`） |
| `body`     | `Any` | 请求体（已解析的 JSON，或 `None`）              |

### PageResponse 构造

| 方法                         | 说明                           |
| -------------------------- | ---------------------------- |
| `PageResponse.ok(data)`    | 成功响应，`data` 为任意可 JSON 序列化的数据 |
| `PageResponse.fail(error)` | 失败响应，`error` 为错误信息字符串        |

## 前端页面开发

在 HTML 文件中引入 Page SDK，即可与插件后端通信：

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <style>
    body {
      background: var(--langbot-bg, #ffffff);
      color: var(--langbot-text, #0a0a0a);
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
      padding: 24px;
    }
  </style>
</head>
<body>
  <h1 data-i18n="title">Dashboard</h1>
  <p id="stats"></p>

  <script src="/api/v1/plugins/_sdk/page-sdk.js"></script>
  <script>
    langbot.onReady(async function(ctx) {
      // 调用后端 API
      var data = await langbot.api('/stats', null, 'GET');
      document.getElementById('stats').textContent = 'Total: ' + data.total;
    });
  </script>
</body>
</html>
```

### Page SDK API

| 方法                                      | 说明                                                          |
| --------------------------------------- | ----------------------------------------------------------- |
| `langbot.onReady(callback)`             | SDK 就绪后触发回调，`callback` 接收 `ctx` 参数（包含 `theme` 和 `language`） |
| `langbot.api(endpoint, body?, method?)` | 调用插件后端 `handle_api`，返回 Promise                              |
| `langbot.t(key, fallback?)`             | 获取翻译字符串                                                     |
| `langbot.onThemeChange(callback)`       | 主题变更回调                                                      |
| `langbot.onLanguageChange(callback)`    | 语言变更回调                                                      |
| `langbot.applyI18n()`                   | 手动重新应用 `data-i18n` 翻译                                       |

### 暗色模式

SDK 会自动在页面上设置 CSS 自定义属性，直接使用即可：

| CSS 变量                 | 用途    |
| ---------------------- | ----- |
| `--langbot-bg`         | 页面背景色 |
| `--langbot-bg-card`    | 卡片背景色 |
| `--langbot-text`       | 主文字色  |
| `--langbot-text-muted` | 次要文字色 |
| `--langbot-border`     | 边框色   |
| `--langbot-accent`     | 强调色   |

### 页面 i18n

在页面目录下创建 `i18n/` 目录，放入 JSON 翻译文件：

```
pages/dashboard/
├── index.html
└── i18n/
    ├── en_US.json
    └── zh_Hans.json
```

翻译文件格式为扁平 JSON 键值对：

```json
{
  "title": "仪表盘",
  "totalEntries": "条目总数"
}
```

在 HTML 元素上添加 `data-i18n` 属性，SDK 会自动替换文本：

```html
<h1 data-i18n="title">Dashboard</h1>
```

## 完整示例：FAQ 管理器

以下是一个完整的 Page 组件示例，实现了 FAQ 条目的增删改查。

**后端处理程序**（`components/pages/manager/manager.py`）：

```python
from langbot_plugin.api.definition.components.page import Page, PageRequest, PageResponse


class ManagerPage(Page):

    async def handle_api(self, request: PageRequest) -> PageResponse:
        if request.endpoint == '/entries' and request.method == 'GET':
            entries = await self.load_entries_for_current_installation()
            return PageResponse.ok({'entries': entries})

        if request.endpoint == '/entries' and request.method == 'POST':
            question = (request.body or {}).get('question', '').strip()
            answer = (request.body or {}).get('answer', '').strip()
            if not question or not answer:
                return PageResponse.fail('question and answer are required')
            entry = {'question': question, 'answer': answer}
            await self.save_entry_for_current_installation(entry)
            return PageResponse.ok({'entry': entry})

        if request.endpoint == '/entries' and request.method == 'DELETE':
            entry_id = (request.body or {}).get('id', '')
            if await self.delete_entry_for_current_installation(entry_id):
                return PageResponse.ok({'deleted': entry_id})
            return PageResponse.fail('entry not found')

        return PageResponse.fail(f'Unknown: {request.method} {request.endpoint}')
```

**前端页面**（`components/pages/manager/index.html`）中通过 `langbot.api()` 调用后端：

```javascript
// 加载条目
var data = await langbot.api('/entries', null, 'GET');

// 添加条目
await langbot.api('/entries', { question: '...', answer: '...' }, 'POST');

// 删除条目
await langbot.api('/entries', { id: '...' }, 'DELETE');
```

完整示例代码请参考 [FAQManager 插件](https://github.com/langbot-app/langbot-plugin-demo/tree/main/FAQManager)。

## 一个安装，多份用法

同一个 Page 会被**多次页面请求**调用（同一安装下的不同请求、不同工作区）：

- 不要把上一次请求的数据留在实例上；端点、方法、body 与当前安装信息一律从当前 `PageRequest` / 绑定取。
- 页面数据一律按安装作用域存放（installation-scoped Host 存储）；`self.plugin` 是进程级共享对象，不能保存租户数据。
- 不同工作区的请求会共享同一个 Page 实例，实例字段会被交织使用；需要跨请求保留的数据放 Host 存储。
- 如果按安装维护了进程内缓存，请在 `on_installation_revoked(binding)` 中释放。

以上约束的完整说明见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

## 注意事项

- 页面运行在 `sandbox="allow-scripts allow-forms"` 的 iframe 中，不能弹窗或导航父页面
- 认证 Page 必须把租户数据放在 installation-scoped Host 存储中；`self.plugin` 是进程级共享对象，不能保存租户条目。上面的存储 helper 名仅为示意，请使用当前组件可用的 SDK Host 存储 API。
- 使用 `PageResponse.ok()` 和 `PageResponse.fail()` 构造响应，确保格式一致
- Page SDK 的 `<script>` 标签必须放在使用 `langbot` 对象的代码之前

---

# 组件：解析器

Source: https://langbot.app/docs/zh/plugin/dev/components/parser

解析器（Parser）组件允许插件为 LangBot 提供文档解析能力。在用户上传文档到知识库时，LangBot 会在 RAG 引擎摄取（`ingest`）之前调用解析器，将 PDF、Word、Markdown 等二进制文件提取为结构化文本。

Parser 与 KnowledgeEngine 的关系：

- **Parser** 负责将文件转换为文本（file → text）
- **KnowledgeEngine** 负责将文本索引和检索（text → chunks → vectors）

如果 RAG 引擎自身已具备文档解析能力（声明了 `DOC_PARSING` 能力），用户可以选择使用 RAG 引擎内置的解析能力，也可以选择使用外部 Parser 插件。

## 添加解析器组件

单个插件中能添加任意数量的解析器，请在插件目录执行命令 `lbp comp Parser`，并根据提示输入解析器的配置。

```bash
➜  MyParserPlugin > lbp comp Parser
Generating component Parser...
Parser name: pdf_parser
Parser description: A PDF document parser
Component Parser generated successfully.
组件 Parser 生成成功。
```

现在即会在 `components/parser/` 目录下生成 `pdf_parser.yaml` 和 `pdf_parser.py` 文件，`.yaml` 定义了解析器的基础信息和支持的 MIME 类型，`.py` 是该解析器的处理程序：

```bash
➜  MyParserPlugin > tree
...
├── components
│   ├── __init__.py
│   └── parser
│       ├── __init__.py
│       ├── pdf_parser.py
│       └── pdf_parser.yaml
...
```

## 清单文件：解析器

```yaml
apiVersion: v1  # 请勿修改
kind: Parser  # 请勿修改
metadata:
  name: pdf_parser  # 解析器名称，用于标识该解析器
  label:
    en_US: PDF Parser  # 解析器显示名称，用于显示在 LangBot 的 UI 上，支持多语言
    zh_Hans: PDF 解析器
  description:
    en_US: 'A PDF document parser'
    zh_Hans: 'PDF 文档解析器'
spec:
  supported_mime_types:  # 声明支持的文件 MIME 类型
    - application/pdf
execution:
  python:
    path: pdf_parser.py  # 解析器处理程序，请勿修改
    attr: PdfParser  # 解析器处理程序的类名，与 pdf_parser.py 中的类名一致
```

### supported\_mime\_types

`supported_mime_types` 声明该解析器支持解析的文件类型。常见 MIME 类型：

| MIME 类型                                                                   | 说明             |
| ------------------------------------------------------------------------- | -------------- |
| `application/pdf`                                                         | PDF 文档         |
| `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | Word 文档（.docx） |
| `text/markdown`                                                           | Markdown 文件    |
| `text/plain`                                                              | 纯文本文件          |
| `text/html`                                                               | HTML 文件        |

## 插件处理

默认会生成如下代码（`components/parser/<解析器名称>.py`），您需要实现 `parse` 方法。

```python
from langbot_plugin.api.definition.components.parser.parser import Parser
from langbot_plugin.api.entities.builtin.rag.models import (
    ParseContext,
    ParseResult,
    TextSection,
)


class PdfParser(Parser):
    """解析器组件，用于从文件中提取文本。"""

    async def parse(self, context: ParseContext) -> ParseResult:
        """解析文件并提取结构化文本。

        Args:
            context: 包含 file_content（bytes）、mime_type、filename 和 metadata。

        Returns:
            ParseResult，包含提取的文本和可选的结构化分节。
        """
        # TODO: 实现解析逻辑
        text = context.file_content.decode("utf-8", errors="replace")

        return ParseResult(
            text=text,
            sections=[
                TextSection(
                    content=text,
                    heading=context.filename,
                    level=0,
                ),
            ],
            metadata={
                "filename": context.filename,
                "mime_type": context.mime_type,
            },
        )
```

### 解析方法

`parse` 方法在文档上传到知识库时被调用（在 RAG 引擎摄取之前）：

```python
async def parse(self, context: ParseContext) -> ParseResult:
```

**ParseContext** 包含以下信息：

```python
class ParseContext(pydantic.BaseModel):
    file_content: bytes          # 原始文件字节（由 LangBot 从存储中读取）
    mime_type: str               # 检测到的文件 MIME 类型
    filename: str                # 原始文件名
    metadata: dict[str, Any]     # FileObject 中的额外元数据
```

**ParseResult** 应返回解析结果：

```python
class ParseResult(pydantic.BaseModel):
    text: str                            # 提取的完整纯文本
    sections: list[TextSection] = []     # 结构化分节（可选）
    metadata: dict[str, Any] = {}        # 解析元数据（如 page_count、language 等）
```

**TextSection** 表示文档中的一个段落/分节：

```python
class TextSection(pydantic.BaseModel):
    content: str                   # 分节文本内容
    heading: str | None = None     # 分节标题
    level: int = 0                 # 嵌套层级
    page: int | None = None        # 来源页码（适用于 PDF 等）
    metadata: dict[str, Any] = {}  # 额外分节元数据
```

## 与 KnowledgeEngine 的协作

当用户上传文档时，LangBot 会根据以下逻辑决定解析流程：

- 若用户选择了外部 Parser 插件，LangBot 会先调用 Parser 的 `parse` 方法，然后将解析结果通过 `IngestionContext.parsed_content` 传递给 RAG 引擎的 `ingest` 方法。
- 若 RAG 引擎声明了 `DOC_PARSING` 能力且用户未选择外部解析器，则由 RAG 引擎自行处理文档解析。

KnowledgeEngine 可通过检查 `IngestionContext.parsed_content` 来判断是否存在预解析内容：

```python
async def ingest(self, context: IngestionContext) -> IngestionResult:
    if context.parsed_content:
        # 使用外部 Parser 的解析结果
        text = context.parsed_content.text
        sections = context.parsed_content.sections
    else:
        # 自行解析文档
        file_bytes = await self.plugin.get_knowledge_file_stream(context.file_object.storage_path)
        text = file_bytes.decode('utf-8')
    ...
```

## 跨插件调用解析器

在调用其他插件提供的解析器之前，可以先通过 `self.plugin.list_parsers` 枚举当前可用的解析器：

```python
parsers = await self.plugin.list_parsers(mime_type="application/pdf")
# 返回的每项包含 plugin_id、plugin_author、plugin_name、name、description、supported_mime_types
```

若返回空列表，说明宿主当前没有已连接且支持该 MIME 类型的 Parser 插件。

拿到 `plugin_author` 和 `plugin_name` 后，即可通过 `self.plugin.invoke_parser` 调用对应解析器：

```python
parser = parsers[0]
result = await self.plugin.invoke_parser(
    plugin_author=parser["plugin_author"],
    plugin_name=parser["plugin_name"],
    storage_path=context.file_object.storage_path,
    mime_type=context.file_object.metadata.mime_type,
    filename=context.file_object.metadata.filename,
    metadata={},
)
# result 为 dict，包含 text、sections、metadata
```

## 一个安装，多份用法

一个 Parser 会被**多个知识库**选用（同一安装下不同知识库会上传不同 MIME 类型的文件），而平台的存储键不含知识库维度：

- 解析缓存与临时文件必须按**知识库 ID** 隔离，键里要带上知识库 ID，不要缓存到实例上。
- `ParseContext` 与解析中间结果只在单次解析内有效，不要保存到实例字段或模块级变量。
- 解析失败只影响当前知识库的这次上传，不要让其他知识库的解析不可用。
- 如果按安装缓存了模型、解析器或临时目录，请在 `on_installation_revoked(binding)` 中释放，并确保临时文件可被清理。

以上约束的完整说明见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

## 测试解析器

创建完成后，在插件目录执行命令 `lbp run`，启动调试。然后在 LangBot 中：

1. 进入"知识库"页面
2. 选择一个知识库并进入文档管理
3. 上传文件时，在解析器选择器中选择您的插件提供的解析器
4. 上传文件后检查文档是否正确摄取

---

# 组件：运行器

Source: https://langbot.app/docs/zh/plugin/dev/components/runner

运行器组件通过 SDK 的 `Runner` 类型实现 Agent 的运行逻辑，也可以按事件注册处理函数，供「插件处理器」使用。两种写法共用 `RunnerContext`，插件安装后由用户选择组件并配置。

环境准备见[插件开发教程](https://langbot.app/docs/zh/plugin/dev/tutor.md)。

`RunnerContext` 的完整字段和方法见[上下文 API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md#runner)。

## 添加运行器组件

单个插件中可以添加多个事件处理器。请在插件目录执行命令 `lbp comp Runner`，名称填写 `welcome`，描述填写 `Welcome new members`。

```bash
lbp comp Runner
```

生成的 `components/runner/welcome.yaml` 定义组件信息，`welcome.py` 是处理程序。

## 自定义运行逻辑

需要接入模型或实现自己的执行循环时，声明 `spec.usages: [agent]`，在 `run(ctx)` 中返回结果：

```python
from langbot_plugin.api.definition.components.runner import Runner, RunnerContext, RunnerResult
from langbot_plugin.api.entities.builtin.provider.message import Message


class Echo(Runner):
    async def run(self, ctx: RunnerContext):
        yield RunnerResult.run_completed(
            ctx.run_id,
            message=Message(role="assistant", content=ctx.input.to_text()),
        )
```

## 清单文件：运行器

将 `welcome.yaml` 修改为：

```yaml
apiVersion: langbot/v1
kind: Runner
metadata:
  name: welcome
  label:
    en_US: Welcome members
    zh_Hans: 欢迎新成员
    ja_JP: 新しいメンバーを歓迎
  description:
    en_US: Welcome new members and respond to /hello.
    zh_Hans: 欢迎新成员，并响应 /hello 消息。
    ja_JP: 新しいメンバーを歓迎し、/hello に返信します。
spec:
  usages: [event]
  events:
    - group.member_joined
    - message.received
  capabilities:
    tool_calling: true
  permissions:
    tools: [detail, call]
  config:
    - name: greeting
      type: string
      label:
        en_US: Greeting
        zh_Hans: 欢迎语
        ja_JP: 歓迎メッセージ
      required: true
      default: Welcome aboard!
    - name: reply_enabled
      type: boolean
      label:
        en_US: Send replies
        zh_Hans: 发送回复
        ja_JP: 返信する
      default: true
execution:
  python:
    path: ./welcome.py
    attr: Welcome
```

`spec.events` 指定支持的事件，`spec.config` 定义用户可在处理器详情页修改的配置。本例支持成员入群和收到消息，并提供欢迎语、回复开关两个配置项。回复消息需要上面的 `tool_calling` 和 `permissions.tools` 配置。

`spec.usages` 必填、无默认值，决定组件可在哪类处理器中选择：`agent` 用于 Agent 和流水线，`event` 用于插件处理器。可同时声明 `[agent, event]`；包含 `event` 时必须填写 `spec.events`。本例使用事件处理函数，也可以在 `run(ctx)` 中按需调用 `await super().run(ctx)`。

## 插件处理

在 `Welcome` 类的 `initialize` 方法中注册事件处理函数。将 `welcome.py` 修改为：

```python
from langbot_plugin.api.definition.components.runner import (
    Runner,
    RunnerContext,
)
from langbot_plugin.api.entities.builtin.platform.events import (
    MemberJoinedEvent,
    MessageReceivedEvent,
)
from langbot_plugin.api.entities.builtin.platform.message import Plain


class Welcome(Runner):
    async def initialize(self):
        await super().initialize()

        @self.handler(MemberJoinedEvent)
        async def on_join(ctx: RunnerContext):
            name = ctx.platform_event.member.nickname or str(ctx.platform_event.member.id)
            await ctx.log(f"Member joined: {name}")
            if not ctx.config.get("reply_enabled", True):
                await ctx.log("Replies are disabled for this processor")
                return
            greeting = ctx.config.get("greeting", "Welcome aboard!")
            await ctx.reply(f"{name}, {greeting}")
            await ctx.log("Welcome action completed")

        @self.handler(MessageReceivedEvent)
        async def on_message(ctx: RunnerContext):
            text = "".join(
                item.text for item in ctx.platform_event.message_chain if isinstance(item, Plain)
            ).strip()
            if text != "/hello":
                await ctx.log("Message ignored: expected /hello")
                return
            if ctx.config.get("reply_enabled", True):
                await ctx.reply(ctx.config.get("greeting", "Welcome aboard!"))
            else:
                await ctx.log("Replies are disabled for this processor")
```

`on_join` 在成员入群时发送欢迎语，`on_message` 回复 `/hello`。关闭「发送回复」后，只记录日志。

处理函数中，`ctx.platform_event` 保存当前事件的数据，`ctx.config` 是当前处理器的配置。调用 `ctx.reply()` 回复消息，`ctx.log()` 记录日志。函数执行完毕，本次处理即结束。

## 流式回复

使用 `ctx.reply_stream()` 更新同一条回复，`update(text)` 接收当前的完整文本：

```python
async with ctx.reply_stream() as reply:
    await reply.update("正在处理…")
    await reply.update("处理完成。")
```

正常退出 `async with` 时完成回复。平台不支持流式、未开启流式回复或当前不是消息事件时，会在结束后发送一条完整消息；发生异常时不发送缓存中的未完成文本。调试模式仅模拟发送。

## 事件注册

通过 `@self.handler(事件类)` 注册处理函数，并将对应事件标识加入清单的 `spec.events`。例如，`MemberJoinedEvent` 对应 `group.member_joined`。

| 事件       | 清单中的标识                    | SDK 事件类                      |
| -------- | ------------------------- | ---------------------------- |
| 收到消息     | `message.received`        | `MessageReceivedEvent`       |
| 消息被编辑    | `message.edited`          | `MessageEditedEvent`         |
| 消息被删除    | `message.deleted`         | `MessageDeletedEvent`        |
| 消息表情回应   | `message.reaction`        | `MessageReactionEvent`       |
| 收到反馈     | `feedback.received`       | `FeedbackReceivedEvent`      |
| 成员加入群组   | `group.member_joined`     | `MemberJoinedEvent`          |
| 成员离开群组   | `group.member_left`       | `MemberLeftEvent`            |
| 成员被禁言    | `group.member_banned`     | `MemberBannedEvent`          |
| 群组信息更新   | `group.info_updated`      | `GroupInfoUpdatedEvent`      |
| 收到好友申请   | `friend.request_received` | `FriendRequestReceivedEvent` |
| 添加好友     | `friend.added`            | `FriendAddedEvent`           |
| 删除好友     | `friend.removed`          | `FriendRemovedEvent`         |
| 机器人被邀请入群 | `bot.invited_to_group`    | `BotInvitedToGroupEvent`     |
| 机器人被移出群组 | `bot.removed_from_group`  | `BotRemovedFromGroupEvent`   |
| 机器人被禁言   | `bot.muted`               | `BotMutedEvent`              |
| 机器人被解除禁言 | `bot.unmuted`             | `BotUnmutedEvent`            |
| 平台自定义事件  | `platform.specific`       | `PlatformSpecificEvent`      |

可用事件及字段见 SDK 的 [events.py](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/api/entities/builtin/platform/events.py)。各平台支持的事件有所不同。

## 测试事件处理器

按[插件开发教程](https://langbot.app/docs/zh/plugin/dev/tutor.md)配置调试连接，在插件目录执行 `lbp run`。然后在 LangBot 中：

1. 创建「插件处理器」，在详情页选择「欢迎新成员」组件，填写配置并保存。
2. 在左侧选择「成员加入群组」，填写成员昵称、ID 和群组 ID，点击「运行测试」。
3. 查看回复和日志。也可以选择「收到消息」，输入 `/hello` 测试回复。

调试中的平台回复使用 Mock，不发送真实消息。修改组件 YAML 后，请重启 `lbp run`。

安装插件后，在机器人详情页的「插件处理器」中添加该配置并保存。也可以直接在这里选择组件、填写配置，创建并绑定新配置。机器人会自动投递组件声明的事件，无需逐条配置事件路由。

插件处理器与 Agent／流水线路由独立执行，同一事件可以触发多个插件处理器，某个处理器失败不会阻止其他处理。使用同一配置的机器人会共享设置和运行状态；需要分别设置时，创建不同的配置。可选功能应通过组件配置提供，例如是否回复消息，避免与其他处理器重复回复。

## 一个安装，多份用法

一个工作区内每个插件只安装一次，但这份安装会被**多个处理器**（Agent / 流水线）复用。Runner 需要自己保证处理器之间不串数据：

- `ctx.state.*` 已经按处理器隔离：其作用域包含 `binding_identity`（由 Agent UUID 派生），同一安装下的不同处理器不会互相覆盖。
- 平台的插件存储键是 `(实例, 工作区, 组件类型, 插件名, key)`，**不含处理器维度**；所以你自己写进 Host 存储或缓存的键，必须额外包含处理器或会话身份。
- `RunnerContext`（`ctx`）只在单次运行内有效，不要把它或它的字段保存到实例上跨调用复用；需要跨调用保留的会话状态用 `ctx.state_get()` / `ctx.state_set()`。
- 多个处理器会共享同一个 Runner 实例，不要在实例字段上累积当前运行的数据；如果运行器必须依赖进程内持有的跨调用状态（例如长期驻留的外部会话进程），就不要声明共享运行，保持专属。
- 如果按安装维护了进程内缓存，请在 `on_installation_revoked(binding)` 中释放。

以上约束的完整说明见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

## 接下来做什么

- 查看 [`RunnerContext` 上下文 API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md#runner)。
- 查看模型、工具、知识库和存储相关的 [LangBot API](https://langbot.app/docs/zh/plugin/dev/apis/common.md)。
- 查看消息发送等[平台 API](https://langbot.app/docs/zh/plugin/dev/apis/platform.md)。
- 查看 [RunnerDemo](https://github.com/langbot-app/langbot-plugin-demo/tree/main/Runner/RunnerDemo) 中的更多示例。
- 如果要扩展流水线的预处理、模型调用完成等步骤，请使用[事件监听器](https://langbot.app/docs/zh/plugin/dev/components/event-listener.md)。

---

# 组件：工具

Source: https://langbot.app/docs/zh/plugin/dev/components/tool

LangBot 内置的 Local Agent 在执行期间会根据场景调用工具以与外界交互，目前支持通过插件和 MCP 两种方式添加工具。

## 添加工具组件

单个插件中能添加任意数量的工具，请在插件目录执行命令`lbp comp Tool`，并根据提示输入工具的配置。

```bash
➜  HelloPlugin > lbp comp Tool
Generating component Tool...
Tool name: get_weather_alerts
Tool description: Get weather alerts for a US state.
Component Tool generated successfully.
组件 Tool 生成成功。
```

现在即会在`components/tools/`目录下生成`get_weather_alerts.yaml`和`get_weather_alerts.py`文件，`.yaml`定义了工具的基础信息，`.py`是该工具的处理程序：

```bash
➜  HelloPlugin > tree
...
├── components
│   ├── __init__.py
│   └── tools
│       ├── __init__.py
│       ├── get_weather_alerts.py
│       └── get_weather_alerts.yaml
...
```

## 清单文件：工具

```yaml
apiVersion: v1  # 请勿修改
kind: Tool  # 请勿修改
metadata:
  name: get_weather_alerts  # 工具名称，供 LLM 识别
  label:
    en_US: GetWeatherAlerts  # 工具显示名称，用于显示在 LangBot 的 UI 上，支持多语言
    zh_Hans: GetWeatherAlerts
  description:
    en_US: 'Get weather alerts for a US state.'  # 工具描述，用于显示在 LangBot 的 UI 上，支持多语言。可选
    zh_Hans: '获取美国某个州的天气预警'
spec:
  parameters: []  # 工具参数，由 LLM 根据对话上下文生成值
  llm_prompt: 'Get weather alerts for a US state.'  # 工具提示词，供 LLM 判断是否调用该工具
execution:
  python:
    path: get_weather_alerts.py  # 工具处理程序，请勿修改
    attr: GetWeatherAlerts  # 工具处理程序的类名，与 get_weather_alerts.py 中的类名一致
```

## 插件处理

默认会生成如下代码(`components/tools/<工具名称>.py`)，您需要在`GetWeatherAlerts`类的`call`方法中实现此工具的调用和返回逻辑。

```python
# Auto generated by LangBot Plugin SDK.
# Please refer to https://langbot.app/docs/en/plugin/dev/tutor.html for more details.
from __future__ import annotations

from typing import Any

from langbot_plugin.api.definition.components.tool.tool import Tool
from langbot_plugin.api.entities.builtin.provider import session as provider_session


class GetWeatherAlerts(Tool):

    async def call(self, params: dict[str, Any], session: provider_session.Session, query_id: int) -> str:
        """Fill your tool code here"""
        return {}
```

在 `call` 方法中，实现该工具：

> info:
>
> 天气获取工具用例来自 MCP 的 [Server 编写示例](https://modelcontextprotocol.io/quickstart/server)。

```python
from __future__ import annotations

from typing import Any

from langbot_plugin.api.definition.components.tool.tool import Tool
from langbot_plugin.api.entities.builtin.provider import session as provider_session

import httpx

# Constants
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"


async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

class GetWeatherAlerts(Tool):

    async def call(self, params: dict[str, Any], session: provider_session.Session, query_id: int) -> str:
        """Fill your tool code here"""
        state = params.get("state", "CA")

        url = f"{NWS_API_BASE}/alerts/active/area/{state}"
        data = await make_nws_request(url)

        if not data or "features" not in data:
            return "Unable to fetch alerts or no alerts found."

        if not data["features"]:
            return "No active alerts for this state."

        alerts = [format_alert(feature) for feature in data["features"]]
        return "\n---\n".join(alerts)
```

在这个工具中，我们要从`params`中获取`state`参数，并调用 NWS API 获取该州的天气预警，故我们需要在清单文件的`parameters`中定义`state`参数。

`parameters` 的格式遵循 [JSON Schema](https://json-schema.org/docs)，受 [OpenAI Function Calling 特性](https://platform.openai.com/docs/guides/function-calling#defining-functions)支持，且其根类型固定为`type: object`，请在`properties`中添加参数，并在`required`中添加必填参数说明。

```yaml
...
spec:
  parameters:
    type: object  # 请勿修改
    properties:  # 请勿修改，在此处添加参数
      state:
        type: string
        description: 'Two-letter US state code (e.g. CA, NY)'
    required:  # 在此添加必填参数说明
      - state
...
```

本工具中还使用了`httpx`库，我们需要在插件目录的`requirements.txt`中添加`httpx`依赖。

```txt
# HelloPlugin/requirements.txt
langbot-plugin  # 默认已存在
httpx
```

现在在插件目录执行命令`lbp run`，启动调试。在 LangBot 中配置支持工具调用的模型，并在对应流水线上选择使用该模型，即可使用该工具。

![](https://langbot.app/docs/images/zh/plugin/dev/components/tool_use_in_chat.png)

## 一个安装，多份用法

一个 Tool 会被**多个处理器与会话**调用（同一事件可以触发多个插件处理器）：

- 配置每次调用读取（`self.get_plugin_config()` 或 `ctx.config`），不要在 `initialize()` 中读取后缓存到实例。
- 不要把调用参数、返回结果或会话数据留在实例字段或模块级变量上；会话身份从当前调用的 `session` / `query_id` 取。
- 并发调用会共享同一个实例，实例字段会被交织写入；需要跨调用保留的数据放 Host 存储，键包含对应处理器或会话身份。
- 如果按安装维护了进程内缓存，请在 `on_installation_revoked(binding)` 中释放。

以上约束的完整说明见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

## 接下来做什么

您已经了解了工具的基本用法，接下来可以：

- 查看 Tool 的 [`session` 和 `query_id` 说明](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md#tool)
- 查看 [LangBot API](https://langbot.app/docs/zh/plugin/dev/apis/common.md)

---

# 插件目录规范

Source: https://langbot.app/docs/zh/plugin/dev/directory-structure

本文介绍 LangBot 插件的标准目录结构和文件组织规范，帮助开发者创建符合规范的插件。

## 基本目录结构

一个标准的 LangBot 插件应遵循以下目录结构：

```
MyPlugin/
├── manifest.yaml          # 插件清单文件（必需）
├── main.py               # 插件主入口文件（必需）
├── README.md             # 英文版插件说明文档（必需）
├── readme/               # 多语言 README 目录（可选）
│   ├── README_zh_Hans.md # 简体中文版说明文档
│   ├── README_ja_JP.md   # 日文版说明文档
│   └── README_zh_Hant.md # 繁体中文版说明文档（可选）
├── assets/               # 资源文件目录
│   ├── icon.svg         # 插件图标（推荐）
│   └── ...              # 其他资源文件
├── components/           # 组件目录
│   ├── event_listener/  # 事件监听器组件
│   ├── commands/        # 命令组件
│   └── tools/           # 工具组件
├── requirements.txt      # Python 依赖（可选）
└── config/              # 配置文件目录（可选）
```

## 多语言 README 规范

### 文件位置规范

LangBot 插件支持多语言 README 文档，以便为不同语言的用户提供本地化的插件说明。

**重要规范：**

1. **`根目录 README.md（必需）`**
   - 必须使用**英文**编写
   - 作为插件的默认说明文档
   - 当请求的语言版本不存在时，将回退到此文档
2. **`readme/ 目录（可选）`**
   - 用于存放**非英文**的 README 文档
   - 文件命名格式：`README_{语言代码}.md`

### 支持的语言代码

根据 [RFC 4646](https://datatracker.ietf.org/doc/html/rfc4646) 标准，LangBot 目前支持以下语言代码：

| 语言   | 语言代码           | 文件名                 | 位置           |
| ---- | -------------- | ------------------- | ------------ |
| 英文   | `en` 或 `en_US` | `README.md`         | **插件根目录**    |
| 简体中文 | `zh_Hans`      | `README_zh_Hans.md` | `readme/` 目录 |
| 繁体中文 | `zh_Hant`      | `README_zh_Hant.md` | `readme/` 目录 |
| 日语   | `ja_JP`        | `README_ja_JP.md`   | `readme/` 目录 |
| 越南语  | `vi_VN`        | `README_vi_VN.md`   | `readme/` 目录 |
| 泰语   | `th_TH`        | `README_th_TH.md`   | `readme/` 目录 |
| 西班牙语 | `es_ES`        | `README_es_ES.md`   | `readme/` 目录 |

### 示例目录结构

```
MyPlugin/
├── README.md                    # ✅ 英文版（必需，放在根目录）
└── readme/                      # ✅ 多语言目录
    ├── README_zh_Hans.md       # ✅ 简体中文版
    ├── README_ja_JP.md         # ✅ 日语版
    └── README_zh_Hant.md       # ✅ 繁体中文版
```

### 错误示例

❌ **错误做法：将英文 README 放在 readme/ 目录**

```
MyPlugin/
├── readme/
│   ├── README_en.md        # ❌ 错误：英文不应该在 readme/ 目录
│   └── README_zh_Hans.md
```

❌ **错误做法：根目录 README.md 包含非英文内容**

```markdown
# MyPlugin

This is a plugin...

这是一个插件...    # ❌ 错误：根目录 README.md 只能包含英文
```

### README 语言回退逻辑

当用户请求特定语言的 README 时，LangBot 将按以下顺序查找：

1. 尝试读取 `readme/README_{语言代码}.md`
2. 如果不存在，回退到根目录的 `README.md`（英文版）

**示例：**

- 用户请求简体中文（`zh_Hans`）
  - → 查找 `readme/README_zh_Hans.md`
  - → 如果不存在，返回 `README.md`（英文版）
- 用户请求日语（`ja_JP`）
  - → 查找 `readme/README_ja_JP.md`
  - → 如果不存在，返回 `README.md`（英文版）

## 资源文件目录

### assets/ 目录

`assets/` 目录用于存放插件的静态资源文件。

**推荐结构：**

```
assets/
├── icon.svg              # 插件图标（推荐使用 SVG 格式）
├── example.png           # 示例图片
├── screenshot1.png       # 截图
└── logo.png             # Logo 图片
```

**图标规范：**

- 推荐使用 `icon.svg` 作为插件图标
- 支持的格式：`.svg`、`.png`、`.jpg`、`.jpeg`、`.gif`
- 推荐尺寸：至少 256x256 像素
- 在 `manifest.yaml` 中引用：`icon: assets/icon.svg`

### 在 README 中引用资源

在 README 文档中，可以使用相对路径引用 assets/ 目录中的图片：

```markdown
# MyPlugin

![Example](./assets/example.png)

![Screenshot](./assets/screenshot1.png)
```

**注意：** 插件上传到 LangBot Space 后，资源文件会被自动处理并托管，用户查看 README 时会正确显示图片。

## 组件目录

插件的功能通过组件实现，组件文件应按类型组织在 `components/` 目录下：

```
components/
├── event_listener/       # 事件监听器
│   ├── on_message.py
│   └── on_message.yaml
├── commands/            # 命令
│   ├── hello.py
│   └── hello.yaml
└── tools/               # 工具
    ├── search.py
    └── search.yaml
```

详细的组件开发规范请参考：[添加组件](https://langbot.app/docs/zh/plugin/dev/components/add.md)

## 配置文件

### manifest.yaml

插件清单文件 `manifest.yaml` 是插件的核心配置文件，包含插件的元数据、配置项、组件列表等信息。

详细说明请参考：[完善配置信息](https://langbot.app/docs/zh/plugin/dev/basic-info.md)

### requirements.txt

如果插件需要额外的 Python 依赖包，应在根目录创建 `requirements.txt` 文件：

```
requests>=2.28.0
beautifulsoup4>=4.11.0
pillow>=9.0.0
```

**注意：** LangBot 在安装插件时会自动安装 `requirements.txt` 中列出的依赖。

## 相关文档

- [基础教程](https://langbot.app/docs/zh/plugin/dev/tutor.md) - 了解如何创建第一个插件
- [完善配置信息](https://langbot.app/docs/zh/plugin/dev/basic-info.md) - 配置 manifest.yaml
- [添加组件](https://langbot.app/docs/zh/plugin/dev/components/add.md) - 开发插件组件
- [发布到插件市场](https://langbot.app/docs/zh/plugin/dev/publish/market.md) - 分发你的插件

---

# 迁移指南

Source: https://langbot.app/docs/zh/plugin/dev/migration

本教程高亮了某些注意事项，请各位插件开发者在已阅读现版本插件教程后，再以此文档作为参考进行插件迁移。

## 从 3.x 支持的异步插件迁移

> 插件特征：:
>
> - 主要时间段：2024.2 \~ 2025.8
> - 注册方式：`main.py` 中的插件类中使用 `@handler` 装饰器注册事件监听器、使用 `@llm_func` 装饰器注册内容函数（工具）；处理函数均为异步函数(async def)

- 插件和组件注册方式：已由以往的单一插件类中的装饰器注册方式，改为了清单文件注册方式，参阅[清单文件](https://langbot.app/docs/zh/plugin/dev/basic-info.md)；并将各个不同类型的组件独立出来，详细请见[添加组件](https://langbot.app/docs/zh/plugin/dev/components/add.md)。
- 消息链实体：现已重构，每个消息链元素的构造方法现在需要显式传入**具名参数**，参阅[消息平台实体](https://langbot.app/docs/zh/plugin/dev/apis/messages.md)。
- 事件监听器：提供向后兼容性，但不再于上下文中提供`query: Query`对象，详细请参阅[流水线事件](https://langbot.app/docs/zh/plugin/dev/apis/pipeline-events.md)。
- 命令组件：现已重构，请参阅[命令组件](https://langbot.app/docs/zh/plugin/dev/components/command.md)。

## 从 2.x 和 3.x 支持的同步插件迁移

> 插件特征：:
>
> - 主要时间段：2023.1 \~ 2024.2
> - 注册方式：`main.py` 中的插件类中使用 `@on` 装饰器注册事件监听器、使用 `@func` 装饰器注册内容函数（工具）；处理函数均为同步函数(def)

- 同步改异步：插件运行时现已改为全异步（基于asyncio），请将插件所有涉及 IO 操作的代码改为异步写法。
- 详细内容请参阅上述 3.x 异步插件迁移指南。

---

# 通过 GitHub 分发插件

Source: https://langbot.app/docs/zh/plugin/dev/publish/github

您可以将您的插件上传至 GitHub ，为仓库创建 Release 并上传 `.lbpkg` 文件，其他用户即可在 LangBot 上安装。

## 打包插件

在插件目录下执行命令：

```bash
lbp build
```

这将生成一个 `.lbpkg` 文件在`dist`目录。

## 创建 Release

请将该插件上传 GitHub，并前往插件仓库的 Release 页面，点击创建 Release，并上传刚刚打包的`.lbpkg`文件。

![](https://langbot.app/docs/images/zh/plugin/dev/dist/github_release.png)

## 自动创建 Release（GitHub Actions）

自 `lbp init` 创建的插件已内置一个 GitHub Actions 工作流（`.github/workflows/release.yml`），无需手动打包和上传。

将插件仓库推送到 GitHub 后，每当您修改 `manifest.yaml` 中的 `version` 字段并推送到 `main` 或 `master` 分支时，该工作流会自动：

1. 安装 `lbp` CLI 并执行 `lbp build` 打包插件；
2. 以 `v<version>` 为标签创建一个 GitHub Release，并上传生成的 `.lbpkg` 文件。

若对应版本号的 Release 已存在，则工作流会跳过，不会重复发布。您也可以在仓库的 Actions 页面手动触发（`workflow_dispatch`）。

> :
>
> 该工作流依赖仓库默认的 `GITHUB_TOKEN`，并需要 `contents: write` 权限（模板已声明）。请确保仓库的 Actions 已启用，且 `manifest.yaml` 中的 `metadata.author`、`metadata.name`、`metadata.version` 字段填写正确——Release 名称与产物文件名均由这些字段拼接而成（`<author>-<name>-<version>.lbpkg`）。

## 安装插件

请在 LangBot 的插件管理页面，点击右上角即可选择 GitHub 安装方式。

---

# 发布插件到插件市场

Source: https://langbot.app/docs/zh/plugin/dev/publish/market

通过 CLI 将插件发布至 [LangBot 插件市场](https://space.langbot.app/market)。

## 在 LangBot Space 创建账号

LangBot Space 是 LangBot 提供中心化服务平台。请访问[LangBot Space](https://space.langbot.app)，点击右上角使用 GitHub 登录并创建账号。

![](https://langbot.app/docs/images/zh/plugin/dev/login_space.png)

这将跳转到 GitHub 授权页面，请根据提示完成授权。

## 使用 CLI 登录 LangBot Space

### 方式一：使用个人访问令牌（推荐）

1. 登录 [LangBot Space](https://space.langbot.app)，点击头像进入 **账户设置**，在 **账户** 标签页中找到 **个人访问令牌**，创建一个新的令牌。
2. 复制生成的令牌（仅显示一次），在终端执行：

```bash
➜  HelloPlugin > lbp login --token lbpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

==================================================
✅ 使用个人访问令牌登录成功！
令牌已保存至：~/.langbot/cli/config.json
==================================================
```

### 方式二：使用设备码验证

在任意目录执行命令`lbp login`：

```bash
➜  HelloPlugin > lbp login
Starting LangBot CLI login process...
Generating device code...

==================================================
Please copy the user code and complete verification in your browser:
User Code: 6CD64D56
Verification URL: https://space.langbot.app/auth/device
Device code expires in: 120 seconds
==================================================

Waiting for verification...
```

请点击`Verification URL`跳转至 LangBot Space，输入`User Code`完成登录。

![](https://langbot.app/docs/images/zh/plugin/dev/space_device_flow.png)

```bash
==================================================
✅ Login successful!
Access token saved to: ~/.langbot/cli/config.json
Token type: Bearer
Expires in: 21600 seconds
==================================================
```

两种方式登录成功后，均可继续使用 CLI 上传插件。

## 上传插件

请在您的插件目录下执行`lbp publish`:

```bash
➜  HelloPlugin > lbp publish
Building plugin to dist/tmp...
  - Skipping ignored directory: dist
  - Skipping ignored directory: __pycache__
  ...
Plugin built successfully: dist/tmp/RockChinQ-HelloPlugin-0.1.0.lbpkg
✅ Plugin published successfully. You can check it on https://https://space.langbot.app/market
```

您现在可以在[LangBot 插件市场](https://space.langbot.app/market)查看您的插件提交任务。请等待审核通过后，您可以在插件市场查看您的插件。

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_submission.png)

发布流程本身不涉及认证：插件默认以专属模式运行。如果这个版本还要申请认证，见[认证插件与共享运行](https://langbot.app/docs/zh/plugin/certified-plugins.md)。

有任何问题，您可以发送邮件到`hello@langbot.app`或通过[社区](https://langbot.app/docs/zh/insight/community.md)联系我们。

---

# 代码规范指南

Source: https://langbot.app/docs/zh/plugin/dev/style

## 日志记录

在插件中请使用`logging`模块记录日志，不要使用`print`语句（这将导致容器环境中无法输出日志）。

```python
import logging

logger = logging.getLogger(__name__)  # 在任何 Python 文件的开头导入 logging 模块，并定义 logger 对象

logger.info('This is an info message')  # 使用 logger.info 记录信息级别日志
logger.warning('This is a warning message')
logger.error('This is an error message')
```

认证插件中，原始进程日志无法安全归属到某个工作区，只用于运维诊断。Runner 可在调用中使用 `RunnerContext.log()` 记录安装作用域、租户可见日志。其他组件目前没有通用租户日志 API，其原始进程日志仅供运维；不要在模块全局后台线程中输出租户配置、凭据或请求数据。

---

# 插件开发教程

Source: https://langbot.app/docs/zh/plugin/dev/tutor

> info:
>
> 要开发处理消息、成员入群等事件的插件，可在完成基础环境准备后，继续阅读[事件处理器教程](https://langbot.app/docs/zh/plugin/dev/components/runner.md)。

## 架构基础

在 4.0 版本中，我们引入了一种高安全性、高灵活性的生产级插件系统，并为插件开发者提供了丰富的 API 和易用的配套工具。

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_system_arch.png)

Plugin Runtime （插件运行时），用于管理插件的生命周期，协调 LangBot 与插件之间的交互。有两种运行模式：`stdio` 和 `websocket`。当 LangBot 是由用户直接启动（未运行在容器内时），会使用 `stdio` 模式，这种场景多为个人用户或轻量级环境。当 LangBot 运行在容器内时，会使用 `websocket` 模式，此场景专为生产级环境设计。

Plugin Runtime 会自动启动各个已安装的插件，通过 stdio 交互。在插件开发场景中，开发者可以使用 `lbp` 命令行工具启动插件并通过 WebSocket 连接到已启动的 Runtime 进行调试。

### 插件结构

一个插件的目录结构与以下类似：

```bash
➜  HelloPlugin > tree
.
├── assets
│   └── icon.svg  # 插件图标，会被展示在插件市场页面
├── components  # 插件组件目录，存放插件的各个组件代码和清单文件
│   ├── __init__.py
│   ├── commands
│   │   ├── __init__.py
│   │   ├── info.py
│   │   └── info.yaml
│   ├── event_listener
│   │   ├── __init__.py
│   │   ├── default.py
│   │   └── default.yaml
│   └── tools
│       ├── __init__.py
│       ├── get_weather_alerts.py
│       └── get_weather_alerts.yaml
├── main.py  # 插件主程序，监听插件的生命周期
├── manifest.yaml  # 插件清单文件，描述插件的元信息
├── README.md  # 插件说明文件，描述插件的功能和使用方法，会被展示在插件市场页面
├── readme
│   └── README_zh_Hans.md  # 中文说明文件，用于多语言文档
├── requirements.txt  # 插件依赖文件
└── .github
    └── workflows
        └── release.yml  # GitHub Actions 工作流，推送版本号变更时自动构建并发布 Release
```

main.py 中的插件类是每个插件通用的代码，在插件被启动时会被初始化，并传入上下文信息（配置信息等）。您可在此实现插件的初始化和关闭时的逻辑。插件类会继承于`langbot_plugin.api.definition.plugin.BasePlugin`，并提供 [LangBot 全局 API](https://langbot.app/docs/zh/plugin/dev/apis/common.md)。

各个组件是您插件的核心功能模块，可以根据需要[添加和删除组件](https://langbot.app/docs/zh/plugin/dev/components/add.md)。不同的组件会在不同的情况下被调用，这种设计方便后续扩展插件功能。各个组件均直接继承于`langbot_plugin.api.definition.components`包下的各个组件基类，并在其中包含`plugin: BasePlugin`对象，您可直接调用插件的 API。

> :
>
> - 详细的 API 说明请参考[API 参考](https://langbot.app/docs/zh/plugin/dev/apis/common.md)。
>
> 请您继续阅读本页教程，了解插件的开发流程。

## AI 辅助开发

- [skills-LangBotplugin](https://github.com/TyperBody/skills-LangBotplugin) - 来自社区成员 [@TyperBody](https://github.com/TyperBody) 贡献的 Skills，使用 AI 快速开发插件，欢迎体验
  - *langbotplugin* 该skill提供自动化生成插件工具
  - *langbotplugindebug* 该skill提供调试插件工具

## 安装 CLI

请确保您已安装 Python 3.10 或更高版本，并已安装 [uv 包管理器](https://docs.astral.sh/uv/)。

在任意空目录执行命令，安装 LangBot CLI 和 SDK

```bash
pip install -U langbot_plugin
```

## 初始化插件目录

假设您的插件名称为 `HelloPlugin`，则在任意目录下创建目录`HelloPlugin`，并进入该目录，执行命令初始化插件：

```bash
lbp init
```

按照提示输入`Author(作者)`、`Description(描述)`等信息

> :
>
> 您也可以使用`lbp init HelloPlugin`命令，在子目录`HelloPlugin`中初始化插件。
>
> ![](https://langbot.app/docs/images/zh/plugin/dev/create_plugin.png)

此操作将生成插件的初始文件。您现在可以在您喜爱的编辑器中打开 `HelloPlugin` 目录，开始编写插件代码。

> :
>
> 若提示找不到 `lbp` 命令，可能是由于您未正确设置 `PATH` 环境变量。
> 可使用`python -m langbot_plugin.cli.__init__`替代`lbp`命令。
>
> 例如：
>
> ```bash
> python -m langbot_plugin.cli.__init__ init HelloPlugin
> cd HelloPlugin
> ```

## 启动调试

您需要先部署并启动 LangBot，确保 Plugin Runtime 正在运行并监听 `5401` 端口。

> Runtime 有两种启动方式：:
>
> - `Stdio` 模式：当您使用源代码启动 LangBot 并未携带启动参数`--standalone-runtime`时，LangBot 会自动以子进程的形式启动 Plugin Runtime，并通过 `stdio`（标准输入输出流）模式与 Plugin Runtime 通信。此时 Runtime 会加载 LangBot 根目录的`data/plugins`目录下的插件。并监听 LangBot 运行主机的`5401`端口作为调试端口。
>
> - `WebSocket` 模式：
>   - 生产环境：当您使用官方提供的`docker-compose.yaml`启动 LangBot 时，会在独立的容器运行 Plugin Runtime，LangBot 也会因为携带启动参数`--standalone-runtime`而以 WebSocket 模式与 Plugin Runtime 通信。默认情况下，Runtime 容器的 5401 端口会被映射到宿主机的 5401 端口。
>   - 开发环境：若您通过源代码启动 LangBot，并携带启动参数`--standalone-runtime`，LangBot 按照`data/config.yaml`中配置的`plugin.runtime_ws_url`地址（端口通常是5400）连接到已启动的 Plugin Runtime。您需要自行启动独立运行的 Plugin Runtime，见[开发 Plugin Runtime](https://langbot.app/docs/zh/develop/plugin-runtime.md)。
>
> 无论是`stdio`或`websocket`模式，Plugin Runtime 都会监听其所在的主机的`5401`端口作为调试端口供插件调试时连接。
>
> 当您在开发插件时，推荐您按照[开发配置](https://langbot.app/docs/zh/develop/dev-config.md)中的方式 LangBot，此方式将以 Stdio 形式启动 Plugin Runtime，便于插件开发。

复制插件目录下的`.env.example`文件为`.env`。在 LangBot WebUI 的“扩展 → 调试信息”中复制当前工作区的调试地址和调试密钥，分别填写为 `DEBUG_RUNTIME_WS_URL` 和 `PLUGIN_DEBUG_KEY`。每个工作区的密钥不同，并每两小时自动轮换；过期后请重新复制。

```bash
cp .env.example .env
```

启动插件调试，您将看到插件的输出：

```bash
lbp run
```

![](https://langbot.app/docs/images/zh/plugin/dev/launch_debug_plugin.png)

并可以在 LangBot 的 WebUI 中看到此插件已被加载。

![](https://langbot.app/docs/images/zh/plugin/dev/debug_plugin_loaded.png)

## 接下来做什么

该教程将指引您逐步完善插件功能。

- 修改插件信息：插件已创建，并填入了最基础的插件信息，请您[完善插件信息](https://langbot.app/docs/zh/plugin/dev/basic-info.md)。
- 添加组件：插件组件是插件的核心功能单元，您可以根据需求[添加组件](https://langbot.app/docs/zh/plugin/dev/components/add.md)。

---

# LangBot 插件

Source: https://langbot.app/docs/zh/plugin/plugin-intro

LangBot 内部由多种组件组成，如大模型工具、命令、消息平台适配器、大模型请求器等。为了满足扩展性和灵活性的需求，我们实现了一套生产级的插件系统。

插件由 Plugin Runtime 统一管理。大多数插件使用专属运行时；精确制品签名通过验证的版本才可能在 LangBot Cloud 获得[跨工作区共享资格](https://langbot.app/docs/zh/plugin/certified-plugins.md)；审核本身不是认证。

![](https://langbot.app/docs/images/zh/plugin/dev/plugin_system_arch.png)

## 插件结构

插件根据具体功能可提供以下组件：

- 事件处理器：监听流水线执行期间的事件，对上下文或流水线进行修改。
- 命令：由用户通过`!`（或其他已设置的前缀）开头的命令消息触发。
- 工具：供 LangBot 内置的 Local Agent 在执行期间由 LLM 调用。
- RAG 引擎：管理知识库的文档索引和检索。

后续还将支持更多组件的插件化。

## 安装插件

目前支持上传插件包安装、从插件市场安装以及从 GitHub Release 安装插件。\
在 LangBot 的插件管理页面，点击右上角即可选择安装方式

![](https://langbot.app/docs/images/zh/plugin/install_method.png)

点击本地安装，选择他人分享的或从 Marketplace 下载的`.lbpkg`文件，即可安装插件。

或点击插件市场 Tab，选择插件后点击安装。

![](https://langbot.app/docs/images/zh/plugin/install_from_marketplace.png)

安装插件后，您需要到流水线配置中，选择所需要使用的插件。

![](https://langbot.app/docs/images/zh/plugin/pipeline_extensions.png)

## 插件管理

### 插件配置项

某些插件可能会要求您填入特定的配置项（请参考插件 README 说明），请点击插件卡片进入插件详情页，按照提示获取并输入。

![](https://langbot.app/docs/images/zh/plugin/plugin_config.png)

### 更新插件

仅支持更新从插件市场安装的插件。

![](https://langbot.app/docs/images/zh/plugin/update_plugin.png)

## 插件市场

插件市场可以从 LangBot 内部的`插件管理`页面进入，也可以访问独立站点[LangBot 插件市场](https://space.langbot.app/market)。

---

# Service API 概述

Source: https://langbot.app/docs/zh/tags/readme

LangBot 提供了一套供外部服务使用的 RESTful API 接口，便于集成和自动化管理。这些接口以 API Key 鉴权，是目前 HTTP API 的子集。

> warning:
>
> Service API 目前处于 Beta 阶段，部分接口可能会频繁变动。

## 获取 API Key

点击 WebUI 侧栏的 `API Keys` 按钮，创建一个 API Key。

![create\_api\_key](https://langbot.app/docs/images/zh/api/create_api_key.png)

创建后，复制 API Key 并保存。

![copy\_api\_key](https://langbot.app/docs/images/zh/api/copy_api_key.png)

## 认证方式

所有 Service API 都支持以下两种认证方式：

- **API Key**：通过请求头 `X-API-Key: <your-key>` 或 `Authorization: Bearer <your-key>` 传递
- **用户令牌**：通过请求头 `Authorization: Bearer <user-token>` 传递（登录后获取）

## 使用 API

左侧列出了所有可用的 API，您可以填入您的实例地址（后端开放的端口地址，默认为 `http://localhost:5300`）和 API Key，然后点击 `Try it out` 按钮即可调用 API。

## 核心概念

### Provider + Model 架构

LangBot 采用 **供应商（Provider）+ 模型（Model）** 的两层架构来管理 AI 模型：

- **供应商（Provider）**：定义 API 地址（base\_url）、请求器类型（requester）和 API 密钥（api\_keys）。一个供应商可以关联多个模型。
- **模型（Model）**：关联到一个供应商（通过 `provider_uuid`），定义具体的模型名称和参数。模型继承供应商的 API 地址和密钥。

```
Provider (OpenAI)
├── base_url: https://api.openai.com/v1
├── api_keys: [sk-xxx]
├── LLM: gpt-4o
├── LLM: gpt-4o-mini
└── Embedding: text-embedding-3-small
```

这种架构允许您在同一供应商下管理多个模型，共享 API 配置，避免重复填写密钥。

### 请求器（Requester）

请求器定义了与 AI 服务通信的协议。可通过 `GET /api/v1/provider/requesters` 获取可用请求器列表。常见的请求器包括：

- `openai-chat-completions` — OpenAI 兼容的聊天补全 API（也适用于国内服务商如硅基流动、DeepSeek 等）
- `anthropic-messages` — Anthropic Claude API
- `openai-embeddings` — OpenAI 兼容的向量嵌入 API

### 异步任务

部分操作（插件安装/删除/升级）为异步执行，接口返回 `task_id`。可通过 WebUI 查看任务进度。

---

# Webhooks

Source: https://langbot.app/docs/zh/tags/webhook

Webhooks 允许您将机器人收到的消息事件发送到外部服务进行处理。

## 配置 Webhook

1. 在 LangBot WebUI 中，点击侧边栏的 "API 集成" 按钮
2. 切换到 "Webhooks" 标签页
3. 点击 "+" 按钮创建新的 Webhook
4. 填写以下信息：
   - **名称**：Webhook 的名称
   - **URL**：接收事件的目标 URL
   - **描述**：可选说明
   - **状态**：启用或禁用

## 事件格式

### 个人消息 (bot.person\_message)

```json
{
  "uuid": "event-unique-id",
  "event_type": "bot.person_message",
  "data": {
    "bot_uuid": "bot-uuid",
    "adapter_name": "AdapterName",
    "sender": {
      "id": "user-id",
      "name": "User Name"
    },
    "message": [
      {
        "type": "Plain",
        "text": "消息内容"
      }
    ],
    "timestamp": 1234567890
  }
}
```

### 群组消息 (bot.group\_message)

```json
{
  "uuid": "event-unique-id",
  "event_type": "bot.group_message",
  "data": {
    "bot_uuid": "bot-uuid",
    "adapter_name": "AdapterName",
    "group": {
      "id": "group-id",
      "name": "Group Name"
    },
    "sender": {
      "id": "user-id",
      "name": "User Name"
    },
    "message": [
      {
        "type": "Plain",
        "text": "消息内容"
      }
    ],
    "timestamp": 1234567890
  }
}
```

## 响应格式

Webhook 服务应返回 JSON 响应：

```json
{
  "status": "ok",
  "skip_pipeline": false
}
```

### 参数说明

- **status**: 处理状态（建议返回 "ok"）
- **skip\_pipeline**: 是否跳过 LangBot 流水线处理
  - `true`: 消息不会继续在流水线中处理
  - `false`: 消息正常进入流水线处理

> idea:
>
> `skip_pipeline` 允许您完全接管消息处理。设置为 `true` 时，消息只由 Webhook 服务处理，不触发 LangBot 的 AI 对话功能。

## 集成示例

### Dify 工作流

使用 [dify-plugin-langbot-trigger](https://github.com/langbot-app/dify-plugin-langbot-trigger) 插件接收 LangBot webhook 事件，在 Dify 中创建工作流处理消息。

## 注意事项

- Webhook URL 必须可访问
- 请求超时时间为 15 秒
- 请求失败不影响消息正常处理
- 支持配置多个 Webhook 并行执行
- 任一 Webhook 返回 `skip_pipeline: true` 时跳过流水线处理

---

# 规模使用和商用指南

Source: https://langbot.app/docs/zh/tob

LangBot 已经具备了一定的生产能力，目前已在多家公司的生产环境运行并承担一定的业务。我们相信您非常重视合规性和稳定性方面的问题，此章节将基于一些已有的案例讲解商用最佳实践。

请点击左侧目录查看具体内容。

---

# 咨询方式

Source: https://langbot.app/docs/zh/tob/contact

作者长期提供定制服务，欢迎咨询：

- 微信：junyan\_qin
- QQ：1010553892

---

# 消息平台稳定性

Source: https://langbot.app/docs/zh/tob/platform

主流的 QQ、微信机器人都是使用`逆向工程`的方式，破解QQ的通信协议，实现程序控制的功能。这种方式具有一定的灰色性质，可能会被腾讯系统风控。

目前的案例来看，现有的逆向工程可以实现多个月的较稳定运行，服务宕机恢复不会超过24小时，有完善的社区支持，可以较好地应对商业用途。

## 降低被风控风险

- 在配置文件中启用`强制消息延迟`、`请求限速功能`，使机器人回复用户消息的速度降低，减少被风控的风险。
- 避免将机器人放到人员复杂的大群里使用。这个一般不会出问题，有过在3000人大群稳定运行近一年的案例。但若是群内人员频繁举报机器人账号，可能会被风控。
- 使用境内主机或家用网络的电脑运行消息平台，尽量不使用境外主机。

## 机器人服务多开

如果机器人的业务与账号本身弱相关，可以考虑开启多个`消息平台`（例如使用两个账号登录两个Lagrange实例），在一个机器人被腾讯封号后，另一个机器人还可以继续服务。

## 使用 QQ 官方机器人 API

腾讯官方在23年下半年开放了Q群机器人API，LangBot 很好地支持这个 API，可以查看部署教程中的配置方式使用。

但 QQ 官方机器人API具有以下已知的局限性：

- 需要企业资质才能申请
- 仅支持群内使用，不支持私聊
- 仅能接收到群内@机器人的消息，无法接收到群内其他消息
- 主动发送消息每天限次
- 腾讯对 AIGC 功能的机器人审核较严格

---

# AI 内容合规性

Source: https://langbot.app/docs/zh/tob/provider

> 国家对AIGC的管理办法参考资料
>
> - [生成式人工智能服务管理暂行办法](https://www.cac.gov.cn/2023-07/13/c_1690898327029107.htm)

在内容管控方面，LangBot 内置了`关键词检测`、`百度智能云审核`等内容过滤器，具体请查看配置文件章节。

在实践中，应该辅以群内管理员禁言之类的方式管控内容，模型方面，以下是推荐的方案（按推荐顺序）：

1. 使用国产模型
2. 使用严格的内容过滤器（可自行实现，详细参考插件功能章节）
3. 在使用境外模型时辅以严格的 Prompt

---

# 知识库 (Knowledge Base)

Source: https://langbot.app/docs/zh/usage/knowledge/readme

在 LangBot 中构建 RAG 知识库，为 AI 机器人提供文档检索与基于知识的回答。

LangBot 原生支持 RAG（Retrieval-Augmented Generation，即检索增强生成），您可以创建知识库，并将其与流水线绑定，流水线将根据知识库中的内容回答问题。

知识库由 RAG 引擎插件驱动，不同的 RAG 引擎提供不同的索引和检索策略。您可以在[插件市场](https://space.langbot.app/market)中查找可用的 RAG 引擎插件。

## 创建知识库

在知识库页面，点击`创建知识库`按钮：

1. 填写知识库名称
2. 选择一个 RAG 引擎（由已安装的插件提供）
3. 根据所选引擎的配置表单填写相关参数（如嵌入模型、分块大小等）
4. 点击`创建`按钮

> info:
>
> 不同的 RAG 引擎有不同的配置参数，具体取决于引擎的 `creation_schema` 定义。某些引擎可能需要先配置嵌入模型，请先阅读[配置模型](https://langbot.app/docs/zh/usage/models/readme.md)。

如果所选 RAG 引擎支持文档上传（声明了 `DOC_INGESTION` 能力），创建后请到知识库的"文档"页面，上传文档，LangBot 将会在后台开始解析和索引。

## 使用知识库

请到流水线配置中，"AI 能力"页，选择`内置 Agent`作为运行器，并在下方选择您刚刚创建的知识库。

![use\_kb](https://langbot.app/docs/images/zh/deploy/knowledge/use_local_agent.png)

![use\_kb](https://langbot.app/docs/images/zh/deploy/knowledge/use_kb.png)

### 配置重排序（可选）

选择知识库后，您可以在下方配置**重排序模型**来提升检索质量：

- **重排序模型**：选择已配置的 Rerank 模型（如未配置，请先到[模型配置](https://langbot.app/docs/zh/usage/models/readme.md)中添加）
- **重排序保留数量（Top-K）**：重排序后保留的最相关结果数量，默认为 5

> idea:
>
> 重排序模型是可选的。配置后，知识库检索返回的候选文档会经过重排序模型重新打分，只保留最相关的 Top-K 条，再交给大模型回答，显著减少无关信息干扰。

> info:
>
> 仅当运行器为`内置 Agent`时，才可以使用 LangBot 原生知识库，若要在使用其他运行器时使用知识库，请参考所使用的运行器对应产品的文档。

现在即可在`对话调试`或流水线所绑定的机器人上使用知识库进行对话：

![use\_kb\_in\_chat](https://langbot.app/docs/images/zh/deploy/knowledge/use_kb_in_chat.png)

## 开发自定义 RAG 引擎

如果现有的知识引擎插件不能满足您的需求，您可以开发自己的知识引擎插件。请参阅[组件：知识引擎](https://langbot.app/docs/zh/plugin/dev/components/knowledge-engine.md)了解开发方式。

---

# MCP 服务器

Source: https://langbot.app/docs/zh/usage/mcp/readme

为 LangBot 接入 MCP（Model Context Protocol）服务器，用外部工具与数据源扩展 AI 机器人能力。

LangBot 支持调用来自 MCP 服务器的工具。添加 MCP 后，启用了工具使用能力的内置 Agent 即可在对话中调用这些工具。

> MCP 支持本地（stdio）和远程两种模式。:
>
> 首选从 [LangBot Space](https://space.langbot.app) 安装：已上架的 MCP 服务器配置好、开箱即用。
>
> 也可以从 [ModelScope](https://modelscope.cn/mcp)、[mcp.so](https://mcp.so)、[composio.dev](https://composio.dev/toolkits) 等渠道获取，再按下文手动添加。

## 两种运行模式

| 模式                           | 适合场景                | 备注                                                             |
| ---------------------------- | ------------------- | -------------------------------------------------------------- |
| 远程 (`mode: "remote"`)        | 远程 MCP 服务，粘贴 URL 即可 | LangBot 直接连接远程 URL，自动探测传输协议（先试 Streamable HTTP，失败回退 SSE），无需手动选 |
| 本地 / stdio (`mode: "stdio"`) | 本地命令启动的 MCP Server  | 仅在 Box Runtime 可用时支持                                           |

> info:
>
> 旧版本曾把远程模式拆成 `http`（Streamable HTTP）和 `sse` 两项；现已合并为单一的 `remote`，传输协议由后端自动探测。数据库里存量的 `http` / `sse` 记录会在升级时自动归一为 `remote`，连接参数（URL、请求头、超时）保持不变。

> info:
>
> MCP 工具需要流水线使用**内置 Agent**，并选择**已开启工具使用能力**的模型——见[模型](https://langbot.app/docs/zh/usage/models/readme.md)。Dify、n8n、Langflow、Coze 等外部运行器使用各自平台的工具机制。

## 安装 MCP 服务器

### 从 LangBot Space（首选）

[LangBot Space](https://space.langbot.app) 是 LangBot 的官方市场，已上架多种 MCP 服务器。在 WebUI 的 `插件管理` → `MCP 管理` 页面浏览并一键安装，URL、命令、运行模式等参数由市场提供，无需手动填写。

适合大多数场景；接入未上架的服务再走下面的方式。

### 手动添加

进入 `插件管理` → `MCP 管理`：

![MCP 管理页面](https://langbot.app/docs/images/zh/deploy/mcp/mcp02.png)

点击右上角 `添加` → `添加 MCP 服务器`，选择**本地（stdio）**或**远程**模式：远程只需粘贴 URL，本地填写启动命令。点 `测试` 验证连通，点 `提交` 保存：

![新建 MCP 服务器](https://langbot.app/docs/images/zh/deploy/mcp/mcp03.png)

保存后点击卡片上的开关连接 MCP，点击卡片可查看详情：

![MCP 服务器详情](https://langbot.app/docs/images/zh/deploy/mcp/mcp05.png)

## 在流水线启用

MCP 服务器添加后，还要在流水线扩展配置里决定 Agent 能看到哪些：

- 开启"启用所有 MCP Server"，或
- 只绑定指定 MCP Server

未绑定的 MCP 工具不会进入该流水线的工具列表。

## stdio MCP 高级配置

stdio MCP 由 Box Runtime 托管，连接前 LangBot 会：

1. 创建或复用共享的 MCP Box session
2. 如果能从命令推断本地项目路径，把项目 staging 到工作区
3. 项目含 `requirements.txt` / `pyproject.toml` / `setup.py` / `setup.cfg` 时先安装依赖
4. 通过 WebSocket relay 接 MCP 进程的 stdin/stdout

需要细化挂载、网络、超时等行为时，可在 MCP 配置的 `extra_args` 里加 `box` 覆盖项：

```json
{
  "mode": "stdio",
  "extra_args": {
    "command": "python",
    "args": ["server.py"],
    "env": {},
    "box": {
      "host_path": "/path/to/mcp-project",
      "network": "on",
      "host_path_mode": "ro",
      "startup_timeout_sec": 120,
      "image": "python:3.11-slim"
    }
  }
}
```

常用字段：

| 字段                    | 说明                                                        |
| --------------------- | --------------------------------------------------------- |
| `host_path`           | MCP 项目在宿主机上的目录。需在 `box.local.allowed_mount_roots` 允许范围内   |
| `network`             | 是否允许网络（依赖安装常用）                                            |
| `host_path_mode`      | 准备 `host_path` 时的访问模式，默认 `ro`；stdio MCP 通常会先 staging 到工作区 |
| `startup_timeout_sec` | Box 准备和依赖安装超时，默认 120 秒；连接等待会额外预留约 30 秒                    |
| `image`               | Docker 后端使用的运行镜像                                          |
| `memory_mb`           | 覆盖该服务的内存上限（MB）；优先级高于全局 `box.default_memory_mb`            |

> warning:
>
> stdio MCP 在 Box 中运行，依赖安装和进程启动受 sandbox profile、网络权限、资源限制和挂载白名单影响。

## 常见问题

| 现象               | 检查项                                          |
| ---------------- | -------------------------------------------- |
| MCP 连接失败         | URL、命令、参数、环境变量是否正确                           |
| stdio MCP 一直连接中  | Box Runtime 是否可用，`startup_timeout_sec` 是否过短  |
| 依赖安装失败           | sandbox 是否允许网络，依赖文件是否正确                      |
| 本地文件无法访问         | `host_path` 是否存在，是否在 `allowed_mount_roots` 内 |
| Agent 看不到 MCP 工具 | 流水线是否使用内置 Agent、模型是否启用工具使用能力、MCP 是否在流水线中绑定   |

---

# 模型 (Models)

Source: https://langbot.app/docs/zh/usage/models/readme

在 LangBot 中配置大模型供应商：OpenAI GPT、Anthropic Claude、Google Gemini、DeepSeek、通义千问、Ollama 及 OpenAI 兼容模型。

## LangBot Models

LangBot Models 是 LangBot 官方提供的模型服务。当您使用 LangBot Space 账户初始化本地实例时，可用模型将被自动添加到您的实例中，无需进行任何配置。您将会获得一定的免费额度用于快速上手。

![langbot\_models](https://langbot.app/docs/images/zh/deploy/models/langbot_models.png)

具体可用模型，请查看[LangBot Space](https://space.langbot.app/models)。

## 自定义模型

您也可以添加其他来源的模型。LangBot 采用 **供应商（Provider）+ 模型（Model）** 的两层架构：

- **供应商**：定义 API 地址（Base URL）和 API 密钥。同一供应商下的所有模型共享这些配置。
- **模型**：关联到一个供应商，指定具体的模型名称和能力。

```
供应商 (OpenAI)
├── Base URL: https://api.openai.com/v1
├── API Keys: [sk-xxx]
├── LLM 模型: gpt-4o
├── LLM 模型: gpt-4o-mini
├── 向量模型: text-embedding-3-small
└── 重排序模型: rerank-v3.5
```

> idea:
>
> 同一供应商下可以添加多个模型，它们会自动继承供应商的 API 地址和密钥，无需重复填写。

### 对话模型 (LLM Model)

对话模型将被流水线用于处理消息，您配置的第一个模型将被设置为默认流水线的模型。

![arch](https://langbot.app/docs/images/zh/deploy/models/arch.png)

可以添加多个模型，然后在流水线中选择具体使用什么模型。

![model\_config](https://langbot.app/docs/images/zh/deploy/models/model_config.png)

填入 `模型名称`、选择 `模型供应商`（或新建供应商并填入 `请求 URL` 和 `API Key`），然后提交即可。

模型能力方面，请根据具体模型特性来选择：

- **视觉能力**：启用后才能识别图片
- **工具使用能力**（function calling / tool use）：启用后 LLM 才能在对话中调用工具

> info:
>
> **只要想使用来自 MCP 服务器、沙箱内置工具（`exec`/`read`/`write`/`edit`/`glob`/`grep`）、Skills 的能力，都必须为模型启用工具使用能力。** 否则即使流水线绑定了这些扩展，Agent 也不会调用任何工具。
>
> 模型本身需要支持 function calling 才能勾选。不确定时请查阅模型供应商的文档。

### 嵌入模型 (Embedding Model)

嵌入模型将被用于计算消息的向量，若您需要使用知识库，请配置此模型。

![embedding\_model](https://langbot.app/docs/images/zh/deploy/models/embedding_model.png)

填入 `模型名称`、选择 `模型供应商`，然后提交即可。之后请在知识库中配置使用此模型。

### 使用 seekdb 内置嵌入模型（需要可选依赖）

该模型无需填写请求参数。源码部署使用 `uv sync --extra seekdb`，包管理器部署使用 `uvx --from 'langbot[seekdb]@latest' langbot`；官方 Docker/Kubernetes 镜像已包含 SeekDB 依赖。原生部署的平台支持取决于 `pylibseekdb` wheel。

- 在”嵌入模型”页面选择「seekdb-内置」；
- 点击「保存」即可立即使用；
- 后续在知识库中选择该模型即可生效。

### 使用 Chroma 内置嵌入模型（零配置）

系统已集成 Chroma 提供的内置嵌入模型（all-MiniLM-L6-v2），无需填写任何参数。

- 在”嵌入模型”页面选择「chroma-内置」；
- 点击「保存」即可立即使用；
- 后续在知识库中选择该模型即可生效。

### 重排序模型 (Rerank Model)

重排序模型用于对 RAG 检索结果进行重新评分排序，显著提升知识库回答的精准度。当知识库返回多个候选文档时，重排序模型会使用 cross-encoder 对每个文档与查询的相关性进行精确打分，筛选出最相关的内容。

填入 `模型名称`、选择 `模型供应商`，然后提交即可。之后请在流水线的”AI 能力”配置中选择此模型。

> idea:
>
> 重排序模型是可选的。不配置时，知识库检索结果将按向量相似度排序直接使用。配置后，检索结果会经过重排序模型重新打分，只保留最相关的 Top-K 条结果。

---

# 接入 Coze API

Source: https://langbot.app/docs/zh/usage/pipelines/coze

将 Coze 与 LangBot 集成，把 Coze 智能体连接到 Discord、Telegram、微信等消息平台。

本文仅说明如何在 Coze 平台获取 Token 与 Bot ID，并将其填写到 LangBot 流水线配置中。

## 1. 获取 Token 与 Bot ID

1. 登录 Coze 平台，进入你的开发控制台。
   ![Coze 应用 API 密钥](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze07.png)
2. 在“API 管理”中创建并复制令牌。
   ![Coze 应用 API 密钥](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze06.png)

> info:
>
> coze.cn 的授权中有可以长期授权的`服务身份及凭证`，但是 coze.com 只有个人访问令牌。

3. 从项目开发中选择你自己的智能体，或者新建智能体，拿到一下id就是bot\_id。
   ![Coze bot\_id](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze05.png)

- 智能体发布一定要选上api的选项
  ![Coze 应用 API 密钥](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze04.png)

请妥善保存以上两项信息：

- token：Coze 平台生成的令牌
- bot\_id：机器人 ID

## 2. 在 LangBot 中填写配置

1. 打开 LangBot WebUI，进入一个流水线的配置页面（或新建流水线后进入配置页面）。
2. 在“AI 能力”中选择运行器为 `Coze API`。
3. 在运行器的配置项中，填写：

   - token：粘贴你在 Coze 平台复制的 API Token
   - bot\_id：粘贴对应机器人的 Bot ID
   - 请根据您使用的 Coze 站点选择 `API 基础 URL`：coze.cn 请填写 `https://api.coze.cn`；coze.com 请填写 `https://api.coze.com`

   ![流水线配置](https://langbot.app/docs/images/zh/deploy/pipelines/coze/coze08.png)
4. 点击“保存”完成配置。

完成后，你即可在该流水线中调用 Coze 机器人完成对话处理。

## 常见问题

- 保存失败或调用报错：请确认 token 与 bot\_id 是否正确且未包含多余空格。
- 无法选择 `Coze API`：请确认当前版本是否已支持该运行器；若尚未支持，请升级到包含 Coze 运行器的版本。

更多流水线通用配置说明，请参考[修改对话流水线配置](https://langbot.app/docs/zh/usage/pipelines/readme.md)。

---

# 在 LangBot 上使用 DeerFlow

Source: https://langbot.app/docs/zh/usage/pipelines/deerflow

在 LangBot 中使用 DeerFlow，为 AI 机器人的对话管线提供支持。

[DeerFlow](https://github.com/bytedance/deer-flow) 是字节跳动开源的基于大语言模型（LLM）的 AI Agent 框架，专注于深度研究、信息检索与多智能体协作编排。\
框架基于 LangGraph 构建，采用可配置的工作流引擎，支持规划模式、子智能体并发、思维链等高级特性，适用于需要深度信息搜集和结构化分析的场景。

当前适配面向 DeerFlow **2.0 `main` 分支**。DeerFlow 官方已将原始 Deep Research 框架迁移到 `main-1.x` 分支持续维护，因此如果你使用的是 2.0 版本，请以 `main` 分支的官方文档和后端 API 为准。

LangBot 目前支持将 DeerFlow 作为 `AI 能力` 运行器接入对话流水线，为你的 Bot 带来深度研究和智能体编排能力。

## 部署 DeerFlow

请根据 [DeerFlow 官方文档](https://github.com/bytedance/deer-flow) 完成服务的安装、配置与启动：

- [DeerFlow GitHub 仓库](https://github.com/bytedance/deer-flow)
- [DeerFlow 官方网站](https://deerflow.tech/)
- [DeerFlow 配置文档](https://github.com/bytedance/deer-flow/blob/main/backend/docs/CONFIGURATION.md)

部署完成后，请确认 DeerFlow 已正常启动，并记下其网关地址。默认情况下，DeerFlow 网关地址为 `http://127.0.0.1:2026`。

> 网络配置提示:
>
> - 若 LangBot 与 DeerFlow 部署在同一台主机且都使用 Docker 部署，可以参考文章：[网络配置详解](https://langbot.app/docs/zh/workshop/network-details.md#langbot-%E5%92%8C%E6%B6%88%E6%81%AF%E5%B9%B3%E5%8F%B0%E5%9D%87%E8%BF%90%E8%A1%8C%E5%9C%A8-docker-%E5%AE%B9%E5%99%A8%E4%B8%AD)。请在启动 DeerFlow 时将其容器加入 `langbot-network`，并在 LangBot 配置中将 `API 基础 URL` 设置为容器互通地址，例如 `http://deerflow-app:2026`。
> - 若部署在不同主机或容器上，请将 `127.0.0.1` 替换为 DeerFlow 实际可访问的内网地址、主机名或域名。

## 配置 LangBot

打开 LangBot WebUI 页面，添加一个新的流水线或在已有流水线中切换到 `AI 能力` 配置页面。

![deerflow](https://langbot.app/docs/images/zh/deploy/pipelines/deerflow/creat_langbot_pipeline.png)

1. 在 `运行器` 中选择 `DeerFlow API`。
2. 在运行器的配置项中，填写：
   - `API 基础 URL`：DeerFlow 服务的 API 网关地址，默认 `http://127.0.0.1:2026`。
   - `API 密钥`：可选。若你的 DeerFlow 网关使用 Bearer Token 鉴权，可在此填写 API Key。
   - `Assistant ID`：对应 DeerFlow 2.0 LangGraph 的 `assistant_id`，默认为 `lead_agent`。
   - `模型名称覆盖`：可选。用于覆盖 DeerFlow 侧配置的默认模型。若 DeerFlow 已配置好模型，可留空。
   - `启用思考模式`：开启后 DeerFlow 将返回思维链内容，可用于展示推理过程。
   - `启用计划模式`：对应 DeerFlow 2.0 运行时参数 `config.configurable.is_plan_mode`，开启后 Agent 会先制定研究计划再执行。
   - `启用子智能体`：对应 DeerFlow 2.0 运行时参数 `config.configurable.subagent_enabled`，开启后允许 Agent 调度子智能体并行完成任务。
   - `子智能体最大并发数`：对应 DeerFlow 2.0 运行时参数 `config.configurable.max_concurrent_subagents`，仅在启用子智能体时生效，默认 `3`。
   - `递归深度上限`：对应 LangGraph 的 `recursion_limit`，控制工作流的最大递归层数，默认 `1000`。
3. 点击 `保存` 完成配置。

> 配置建议:
>
> - 只有在 DeerFlow 侧已启用相应能力时，才建议开启 `计划模式` 或 `子智能体` 相关选项，否则可能不会产生预期效果。
> - LangBot 会同时发送 DeerFlow 2.0 推荐的 `config.configurable` 运行时参数，并保留向后兼容的旧字段，便于对接上游近期版本。

完成后，你即可在该流水线中使用 DeerFlow 完成深度研究和智能问答。

## 常见问题

- **保存失败或调用报错**：请确认 `API 密钥` 与 `API 基础 URL` 是否正确，并确保 DeerFlow 服务已正常启动。
- **未返回预期内容**：请确认 `Assistant ID` 是否与 DeerFlow 中实际可用的 assistant 一致。
- **无法选择 `DeerFlow API`**：请确认当前 LangBot 版本是否已支持该运行器；若尚未支持，请升级到包含 DeerFlow 运行器的版本。
- **DeerFlow 相关配置项含义**：请参考 DeerFlow 官方文档中关于运行时参数和能力的说明，或咨询 DeerFlow 社区获取建议配置。

---

# 在 LangBot 上使用 Dify

Source: https://langbot.app/docs/zh/usage/pipelines/dify

将 Dify 接入 LangBot，把 Dify 应用与智能体部署为 Discord、Telegram、微信、Slack 等平台的 AI 机器人。

[Dify](https://dify.ai) 是一款开源的大语言模型(LLM) 应用开发平台。它融合了后端即服务（Backend as Service）和 LLMOps 的理念，使开发者可以快速搭建生产级的生成式 AI 应用。\
Dify 可以创建聊天助手（含Chatflow）、Agent、文本生成应用、工作流等应用。

LangBot 目前支持`聊天助手`（含Chatflow）、`Agent`、`工作流`三种 Dify 应用类型。

## 在 Dify 上创建应用

请根据 [Dify文档](https://docs.dify.ai) 部署dify并创建你的应用。

发布应用后，在应用的 `访问API` 页面，生成 API 密钥。

![Dify 应用 API 密钥](https://langbot.app/docs/images/zh/deploy/pipelines/dify/dify_sv_api_01.png)

保存 API 服务器和 API 密钥，在 LangBot 的流水线的`AI 能力`配置。

> 以上为 Dify 云服务版本的示例，若您使用本地自部署的社区版本，请使用 LangBot 访问你自己 Dify 服务的地址作为 \`base-url\`，后方需要添加 \`/v1\` 作为路径。:
>
> - 若 LangBot 与 Dify 部署在同一台主机，并且都是使用 Docker 部署的，可以参考文章：[网络配置详解](https://langbot.app/docs/zh/workshop/network-details.md#langbot-%E5%92%8C%E6%B6%88%E6%81%AF%E5%B9%B3%E5%8F%B0%E5%9D%87%E8%BF%90%E8%A1%8C%E5%9C%A8-docker-%E5%AE%B9%E5%99%A8%E4%B8%AD)。其中，请将启动 Dify 的 docker-compose.yaml 中所有容器的`networks`均添加`langbot-network`，并为`nginx`容器添加容器名`dify-nginx`，最后在 LangBot 配置中将`base-url`设置为`http://dify-nginx/v1`。
> - 其他情况请咨询贵司运维人员。

## 配置 LangBot

打开 LangBot WebUI 页面，添加一个新的流水线或在已有流水线中切换到 AI 能力配置页面。

![设置开发项](https://langbot.app/docs/images/zh/deploy/pipelines/dify/dify_sv_api_02.png)

> \### 工作流输出键:
>
> 如果使用的是 Dify 的工作流应用，那么请使用 `summary` 作为键传递输出内容。
>
> ![Dify 工作流应用的输出键](https://langbot.app/docs/images/zh/deploy/pipelines/dify/dify_workflow_output_key.png)
>
> ## 输出处理
>
> 使用 工作流 应用或 Agent 应用时，如果开启了 LangBot 流水线`输出处理`中的`track-function-calls`，将会在 Dify 执行每个工具调用时，输出一个`调用函数xxx`的消息给用户。\
> 但如果是使用`chat`应用下的`ChatFlow`（聊天助手->工作流编排），无论如何只会输出 Answer（直接回复）节点返回的文本。

---

# 在 LangBot 上使用 Langflow

Source: https://langbot.app/docs/zh/usage/pipelines/langflow

在 LangBot 中使用 Langflow，把 Langflow 流程作为 AI 机器人接入 Discord、Telegram、微信等平台。

Langflow 是一个开源的用于构建和部署基于 AI 的 Agent 和工作流的项目。其支持本地和云端部署，并提供 API 供其他应用接入。

LangBot 目前支持使用 Langflow 作为运行器。

## 在 Langflow 上创建工作流

请根据 [Langflow 文档](https://langflow.com/docs/introduction) 部署 Langflow 实例。

以默认模板中的 Simple Agent 为例：

![create\_flow](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/create_flow.png)

您可根据需求修改工作流：

![edit\_flow](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/edit_flow.png)

## 配置 LangBot

打开 LangBot WebUI 页面，添加一个新的流水线或在已有流水线中切换到 AI 能力配置页面，选择`Langflow API` 作为运行器。

![set\_langflow\_runner](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/set_langflow_runner.png)

根据提示填入`Base URL`(根据实际网络情况填写) `API Key` `Flow ID` 等信息，API Key 可在 Langflow 的 Settings 中获取：

![get\_api\_key](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/get_api_key.png)

Flow ID 可点击编辑页右上角的`Share` -> `API access` 并示例代码中获取：

![get\_flow\_id](https://langbot.app/docs/images/zh/deploy/pipelines/langflow/get_flow_id.png)

---

# 在 LangBot 上使用 n8n

Source: https://langbot.app/docs/zh/usage/pipelines/n8n

将 n8n 与 LangBot 集成，驱动跨消息平台的 AI 机器人工作流与自动化。

[n8n](https://n8n.io/) 是一款开源的自动化工作流平台，可以创建、调度、执行各种自动化任务。

LangBot 目前支持通过 n8n 工作流的 `Webhook` 节点，来触发工作流并获取回复。

## 选用 n8n 作为运行器

请打开已有的流水线配置页面，或新建流水线（推荐）并打开配置页面，到 `AI 能力`中选择 `n8n 工作流 API` 作为运行器。

![n8n 作为运行器](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_runner.png)

并根据下方内容设置并填写其他配置。

## 配置 n8n 工作流连接

![n8n 工作流](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/create_wf.png)
or
![n8n 工作流](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/create_wf01.png)

需要选择`Webhook`或者`On chat message`触发，并参考下图配置：

- webhook
  ![n8n webhook 配置](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_webhook.png)
- on chat message
  ![n8n on chat message 配置](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_n8n_onchatmessage.png)

> :
>
> 如果要需要流式，其中的`Response Mode`都需要选择为`Streaming`。
>
> ![n8n 流式配置](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_response_model.png)

> :
>
> Authentication 对应 LangBot 流水线配置中的几种鉴权方式，可自行更改。
>
> ![n8n 工作流配置](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_auth.png)

调用ai模型的节点可配置为`AI Agent`，并参考下图配置：

> 需要流式则将图片中红框内容添加，不需要则不管

![n8n 调用ai模型配置](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_call_ai.png)

n8n 的工作流响应内容请使用`Respond to Webhook`节点，并参考下图配置（如果你选择的是流式响应和`AI Agent`节点，则不需要操作此步骤）：

![n8n 工作流响应配置](https://langbot.app/docs/images/zh/deploy/pipelines/n8n/config_respond.png)

`Response Body`中的响应内容键名需要与 LangBot 流水线配置中的`输出键名`一致。

在完成 n8n 工作流的配置之后，请在其顶部点击`Active`以启用工作流。

---

# 对话流水线 (Pipelines)

Source: https://langbot.app/docs/zh/usage/pipelines/readme

LangBot 管线将 AI 编排平台（Dify、Coze、n8n、Langflow）连接到你的消息机器人，了解其工作原理。

流水线控制了收到消息之后的处理流程，以及与大模型之间的信息交互。每个机器人可以绑定到一条流水线上，同一条流水线能被多个机器人绑定。

LangBot 首次启动时会自动创建一个默认的流水线。创建机器人时，会自动绑定到默认流水线。创建第一个模型时，会自动将其设置为默认流水线的模型。

![arch](https://langbot.app/docs/images/zh/deploy/pipelines/arch.png)

您可以创建多条流水线，用于不同的机器人，适应不同的场景。

当前流水线可以配置以下功能

## AI 能力

可以选择使用：`内置 Agent`、[`Dify`](https://dify.ai/)、[`阿里云百炼`](https://www.aliyun.com/product/bailian?source=5176.29345612\&userCode=ys4ad8gs)、[`n8n`](https://n8n.io/)、[`TBox（蚂蚁百宝箱）`](https://tbox.cn/)

AI 能力主要分为两个部分，选择运行器和配置运行器参数。

运行器定义了如何调度大模型处理消息，默认为`内置 Agent`，这是 LangBot 实现的一个多回合 Agent 策略，当且仅当选择此运行器时，才会使用 LangBot 内部配置的模型和工具。

![edit\_pipeline](https://langbot.app/docs/images/zh/deploy/pipelines/edit_pipeline_ai.png)

您也可以选择使用 `Dify`、 [`n8n`](https://n8n.io/) 等外部 Agent 平台，这种情况下所使用的模型和提示词、工具等资源将由 Agent 平台提供。

![more\_runner](https://langbot.app/docs/images/zh/deploy/pipelines/more_runner.png)

- 接入 Dify 的详细步骤可以[参考教程](https://langbot.app/docs/zh/usage/pipelines/dify.md)。
- 接入 n8n 的详细步骤可以[参考教程](https://langbot.app/docs/zh/usage/pipelines/n8n.md)。

### 请求变量

当使用外部 Agent 平台时，LangBot 会显式传入以下参数，您可以自行在 Agent 平台的开始节点中添加（下图以 Dify 为例）：

- `launcher_type`：发起对象类型，私聊为 `person`，群聊为 `group`
- `launcher_id`：发起对象ID，私聊为用户ID，群聊为群ID
- `sender_id`：发送者ID
- `user_message_text`：用户消息的纯文本
- `session_id`：用户会话id，私聊为 `person_<id>`，群聊为 `group_<id>`
- `conversation_id`：字符串，用户会话id，由 LangBot 生成。用户重置会话后，会重新生成
- `msg_create_time`：数字类型，收到此消息的时间戳（秒）
- `group_name`：群聊名称，仅在群消息事件时设置
- `sender_name`：发送者名称

您可以[通过插件自定义任何变量](https://langbot.app/docs/zh/plugin/dev/apis/common.md#%E8%AE%BE%E7%BD%AE%E8%AF%B7%E6%B1%82%E5%8F%98%E9%87%8F)。

![Dify 工作流开始节点配置](https://langbot.app/docs/images/zh/workshop/dify-service-api/dify_workflow_var.png)

## 其他配置

请参考配置表单中的描述信息。

---

# 在 LangBot 上使用 TBox（蚂蚁百宝箱）

Source: https://langbot.app/docs/zh/usage/pipelines/tbox

在 LangBot 中使用 TBox，为 AI 机器人对话管线提供支持。

[TBox（百宝箱）](https://tbox.cn/)是蚂蚁集团推出的面向 AI 开发者的一站式智能体应用开发平台。在平台上，无论您是否拥有编程基础，都可以通过自然语言，基于各种大模型搭建属于您自己的智能体应用，并将其发布到支付宝小程序、web 服务、浏览器插件等生态渠道。

LangBot 支持接入 TBox 上编排好的智能体，用作流水线运行器。

在 TBox 上搭建好智能体后，请到[`开放平台`](https://www.tbox.cn/open/authorized-management)创建 API Key：

![TBox API Key](https://langbot.app/docs/images/zh/deploy/pipelines/tbox/create_api_key.png)

并在 TBox 的智能体编排页面找到该应用的 AppID：

![TBox AppID](https://langbot.app/docs/images/zh/deploy/pipelines/tbox/find_appid.png)

接着回到 LangBot 流水线设置中，切到`AI 能力`配置页面，选择`蚂蚁百宝箱平台 API` 作为运行器：

![TBox API Key](https://langbot.app/docs/images/zh/deploy/pipelines/tbox/tbox_runner.png)

现在即可使用 TBox 上的智能体了。

---

# 在 LangBot 上使用 WeKnora

Source: https://langbot.app/docs/zh/usage/pipelines/weknora

在 LangBot 中使用 WeKnora，为 AI 消息机器人加入基于知识库的问答能力。

[WeKnora](https://weknora.weixin.qq.com/)（维娜拉）是腾讯开源的基于大语言模型（LLM）的文档理解与语义检索框架，专为结构复杂、内容异构的文档场景而打造。\
框架采用模块化架构，融合多模态预处理、语义向量索引、智能召回与大模型生成推理，构建起高效、可控的文档问答流程。核心检索流程基于 RAG（Retrieval-Augmented Generation）机制，将上下文相关片段与语言模型结合，实现高质量的答案生成。

LangBot 目前支持 WeKnora 的 `知识库问答（chat）` 和 `Agent 智能对话（agent）` 两种应用类型。

## 在 WeKnora 上获取 API Key

请根据 [WeKnora 官方文档](https://github.com/Tencent/WeKnora) 部署 WeKnora 服务并完成知识库的创建与文档上传。

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_api_lead.png)

部署完成后，访问 WeKnora 的 WebUI（默认 `http://localhost:80`），在 `设置` -> `API 密钥` 页面，点击`生成 API Key`并复制保存。

> API Key 与知识库 ID:
>
> - `API Key`：用于鉴权，请妥善保管，不要泄露。
> - `知识库 ID`：在知识库管理页面查看每个知识库对应的 ID（形如 `kb-00000001`），可在 LangBot 中指定调用的知识库。

点击后可以获取到基础的Url与key信息

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_api_information.png)

> 部署提示:
>
> - 若 LangBot 与 WeKnora 部署在同一台主机，并且都是使用 Docker 部署的，可以参考文章：[网络配置详解](https://langbot.app/docs/zh/workshop/network-details.md#langbot-%E5%92%8C%E6%B6%88%E6%81%AF%E5%B9%B3%E5%8F%B0%E5%9D%87%E8%BF%90%E8%A1%8C%E5%9C%A8-docker-%E5%AE%B9%E5%99%A8%E4%B8%AD)。请在启动 WeKnora 时将其容器加入 `langbot-network`，并在 LangBot 配置中将 `API 基础 URL` 设置为容器互通地址，例如 `http://weknora-app:8080/api/v1`。
> - 其他情况请咨询贵司运维人员。

## 获取 Weknora Agent 信息

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_agent_lead.png)

在 '智能体' 页面，点击要选择的 Agent，进入其详情页，在 `Agent 配置` 中可以查看到 `Agent ID`（形如 `builtin-smart-reasoning`），在 `工具列表` 中可以查看到该 Agent 可调用的工具名称（如 `web-search`、`file-search` 等）。在配置 LangBot 时需要用到这些信息。

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/weknora_other_information.png)

此时你已经准备好了接入 WeKnora API 的必要信息，接下来请按照下文步骤在 LangBot 上完成配置。

## 配置 LangBot

打开 LangBot WebUI 页面，添加一个新的流水线或在已有流水线中切换到 `AI 能力` 配置页面。

![weknora](https://langbot.app/docs/images/zh/deploy/pipelines/weknora/creat_langbot_pipeline.png)

1. 在 `运行器` 中选择 `WeKnora API`。
2. 在运行器的配置项中，填写：
   - `API 基础 URL`：WeKnora 服务的 API 地址，默认 `http://localhost:8080/api/v1`。
   - `API 密钥`：粘贴在 WeKnora 上生成的 API Key。
   - `应用类型`：选择 `agent`（Agent 智能对话，支持工具调用、联网搜索、思维链）或 `chat`（知识库 RAG 问答）。
   - `Agent ID`：内置 Agent 标识，常用值：
     - `builtin-smart-reasoning`：智能推理 Agent（推荐用于 `agent` 模式）
     - `builtin-quick-answer`：快速问答 Agent（推荐用于 `chat` 模式）
   - `知识库 ID 列表`：填入需要检索的知识库 ID（形如 `kb-00000001`），可填写多个。
   - `启用联网搜索`：仅在 `agent` 模式下生效，开启后允许 Agent 调用 Web 搜索工具。
   - `超时时间（秒）`：请求超时时间，默认 `120`。
   - `默认提示词`：当用户未发送文本内容时使用的默认问句。
3. 点击 `保存` 完成配置。

完成后，你即可在该流水线中调用 WeKnora 完成基于知识库的智能对话。

## 输出处理

- 使用 `agent` 应用时，如果开启了 LangBot 流水线 `输出处理` 中的 `track-function-calls`，将会在 WeKnora 执行每个工具调用时，输出一个 `调用函数 xxx` 的消息给用户。
- WeKnora 返回的 `thinking`（思维链）内容会以 `<think>` 标签包裹后发送，可在前端进行折叠展示。
- WeKnora 返回的 `references`（知识库引用来源）会作为参考来源消息附在回答之后。

## 常见问题

- **保存失败或调用报错**：请确认 `API 密钥` 与 `API 基础 URL` 是否正确，URL 末尾需包含 `/api/v1`。
- **未返回知识库内容**：请确认填写的 `知识库 ID` 是否正确，且该知识库下已成功上传并解析了文档。
- **无法选择 `WeKnora API`**：请确认当前 LangBot 版本是否已支持该运行器；若尚未支持，请升级到包含 WeKnora 运行器的版本。

更多流水线通用配置说明，请参考[修改对话流水线配置](https://langbot.app/docs/zh/usage/pipelines/readme.md)。

---

# 钉钉

Source: https://langbot.app/docs/zh/usage/platforms/dingtalk

用 LangBot 搭建钉钉 AI 机器人，将 GPT、Claude、Dify 等接入钉钉群聊与会话。

部署 LangBot 到钉钉。

## 一键配置（推荐）

LangBot 支持一键创建钉钉应用并自动填写凭证，无需手动复制粘贴。

1. 打开 LangBot WebUI，进入**机器人 > 创建机器人**
2. 填写机器人名称，平台/适配器选择 `钉钉`
3. 在下方出现的**一键创建应用**区域，点击右侧的 **开始** 按钮

![一键创建应用](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_oneclick_qrcode.png)

4. 使用钉钉扫描弹出的二维码，手机端会提示选择加入的组织

![选择组织](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_select_org.png)

5. 选择组织后，可以**创建新的**机器人或**选择已有的**机器人

![创建或选择机器人](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_create_or_select.png)

6. 授权成功后，手机端会显示「配置成功」，同时 LangBot WebUI 中的 Client ID 和 Client Secret 会**自动填入**

![配置成功](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_config_success.png)

7. **手动填写机器人名称**（名称需与钉钉中创建的机器人一致），以及**机器人代码**（识图、上传文件等功能必填，需前往钉钉开发者后台 > 机器人配置中获取）

![填写机器人名称和代码](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk_fill_name_and_code.png)

8. 点击**提交**，完成创建

> warning:
>
> 一键配置完成后即可正常进行文字收发消息。但有以下限制：
>
> - **图片/文件收发**：需要填写机器人代码（RobotCode）才能支持，如一键配置时未填写，请前往钉钉开发者后台 > 机器人配置中获取并补填
> - **流式回复**：需要手动配置卡片模板ID才能开启，参考下方「配置机器人」中的卡片模板创建步骤

***

## 手动配置

### 创建机器人

进入 [钉钉开发者后台](https://open-dev.dingtalk.com/?spm=ding_open_doc.document.0.0.74f445e5MkawbT#/)，登录并且进入组织。登录成功后进入开放平台，是这样的：
![钉钉开放平台](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk1.png)

点击上方的 `应用开发`,然后点击右面蓝色的按钮 `创建应用`，填写机器人的基本信息，点击保存。

进入机器人的后台，比如我们有机器人 langbot2 ,那么它的管理页面是这样的：
![机器人页面](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk2.png)

### 配置机器人

点击 `添加应用能力`，`其他应用能力`，`机器人`中的 `配置`，点击配置并且填写信息之后，如下图：
![机器人配置](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk3.png)

点击页面下方的`发布`，发布成功之后，点击机器人页面中左侧最下方的`版本管理与发布`，如图：
![版本管理与发布](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk4.png)

如果是第一次创建机器人，那么右边是空的，需要点击`创建新版本`，在其中设置信息，然后设置`应用可见范围`，点击保存。

点击`事件订阅`，将其中的推送方式改为`Stream模式推送`。

如果需要卡片流式，则需要在权限管理中申请卡片权限，如图:
![申请卡片权限前](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk6.png)

![申请卡片权限后](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk7.png)

另外卡片消息主要创建卡片模板，并记录模板id填入配置信息，流程如下：

> 卡片内容模板ID，可通过登录开发者后台 > [卡片平台](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV)获取

新建模板填写信息，如图：
![新建模板填写信息](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk8.png)

选择预设模板（直接选第一个然后进去后更改模板内容），如图：
![选择预设模板](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk9.png)
点击使用
![点击](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk10.png)
创建
![创建](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk11.png)

点击创建后会跳转到编辑模板。如图，这样你就可以尽情的编辑你想要的卡片消息了：
![编辑模板](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk12.png)

主内容这里默认content不要改动即可：
![不改动](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk13.png)

宽屏配置参数，需要在模板变量中添加.参考[钉钉宽屏配置](https://open.dingtalk.com/document/development/configure-widescreen-cards)
![宽屏配置](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk16.png)

编辑好没问题之后保存即可，并复制模板id用以填写配置文件：
![保存](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk14.png)
![复制模板id](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk15.png)

### 填写配置信息

点击`凭证与基础信息`，记录`Client ID` 和 `Client Secret`，
点击`应用能力`，`机器人`，记录下 RobotCode 和 机器人名称。
`markdown_card` 为是否启用 Markdown 形式的回复，当此配置项关闭时，`@发送者` 配置开关不会生效。
将以上配置项 记录下来，填到 LangBot 机器人配置表单中。

点击[卡片平台](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV)模板列表复制绑定的对应的模板id填入卡片模板id

![对接 LangBot](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/connect_to_langbot.png)

流式相关：
![img.png](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk17.png)

**启动 LangBot** 。

### 添加机器人

本文使用钉钉 windows 桌面版举例，点击上方的`搜索`，`功能`，然后输入刚才机器人创建的名称，如图：
![robot\_png](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk5.png)

点击机器人即可和机器人聊天。

如果想要添加到群里，那么点击钉钉群的`群管理`，`机器人`，`添加机器人`，然后搜索机器人名称就可以在群中使用。

---

# Discord

Source: https://langbot.app/docs/zh/usage/platforms/discord

用 LangBot 搭建 Discord AI 机器人，几分钟内将 GPT、Claude、Gemini、DeepSeek 与 Dify 接入 Discord 服务器。

## 创建机器人

前往[Discord 开发者门户](https://discord.com/developers/applications)，登录后，创建应用。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_01.png)

修改基础信息，点击`Save Changes`保存。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_02.png)

点击左侧`Bot`，点击`Reset Token`，复制生成的 Token。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_03.png)

并在此页面的`Privileged Gateway Intents`中勾选所有选项，点击`Save Changes`保存。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_05.png)

**最后，点击左侧`OAuth2`，复制页面上的`Client ID`。**

## 对接 LangBot

点击添加一个新的机器人，将上一步获取的`Client ID`和`Token`填写到配置中。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/connect_to_langbot.png)

> :
>
> 如果你在中国大陆境内使用此适配器，可能需要设置网络代理。

填写完成后启动 LangBot，若成功配置，日志中会出现`[02-02 16:48:15.263] manager.py (68) - [INFO] : 初始化平台适配器 1: discord`的字样，保持 LangBot 运行。

## 邀请机器人到服务器

你需要先创建一个服务器，然后邀请机器人到服务器。

前往`OAuth2`页面，选择`URL Generator`，选择`bot`，按照图中所示勾选权限。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_06.png)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_07.png)

点击`Copy`，将生成的 URL 粘贴到浏览器中打开，邀请机器人到你的服务器。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_08.png)

## 使用机器人

现在在群里或者私聊机器人都可以正常使用了。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/discord/discord_09.png)

---

# HTTP 通用接入

Source: https://langbot.app/docs/zh/usage/platforms/http-bot

通过 HTTP 将任意后端系统接入 LangBot：以签名 Webhook 推入消息，在回调地址接收回复。面向服务间集成，无需长连接。

`HTTP 通用接入`（HTTP Bot）是一个面向**服务间集成**的通用适配器。任意后端系统（工单系统、CRM、内部工具、自研 Web 应用等）都可以通过它驱动 LangBot 流水线：

- **入站**：你的后端将消息以签名方式 `POST` 到 LangBot 的固定地址；
- **出站**：LangBot 把回复 `POST` 到你配置的回调地址。

它**无需维持长连接**，并且完整保留流水线的两项原生能力：

- **消息聚合（多条合一，N→1）**：用户连发多条消息，合并成一轮处理；
- **多段回复（一问多答，1→M）**：一轮对话可产生多条回复（函数调用、插件多条消息、流式分片）。

> info:
>
> 如果你要的是**浏览器内**的实时聊天组件，请使用[页面机器人](https://langbot.app/docs/zh/usage/platforms/webpage.md)。HTTP 通用接入是为后端到后端的集成设计的。

## 工作原理

```
你的后端  ──(1) 推入签名消息──►  LangBot   /bots/<bot_uuid>
                                （流水线运行：聚合 → 推理 → 回复）
你的回调  ◄─(2) 推回签名回复──   LangBot   每段回复一次 POST
```

- **(1) 入站**是「先收下、后处理」：LangBot 立即返回 `202 Accepted`，**不会**在该响应里带流水线结果；
- **(2) 出站**回复随后以独立的签名 POST 发到你的 `回调地址`，一轮对话可能产生多次回调；
- 一切都以**你自定义的 `session_id`**（如工单号）为键，每个 `session_id` 对应一个独立会话。

## 创建机器人

打开 LangBot WebUI，进入**机器人 > 创建机器人**，填写名称，平台/适配器选择 `HTTP 通用接入`。

## 配置项

| 配置项      | 必填 | 说明                                                  |
| -------- | -- | --------------------------------------------------- |
| 入站签名密钥   | 是  | 你的后端用它对入站请求做 HMAC-SHA256 签名，LangBot 据此校验每个入站请求。     |
| 出站回调地址   | 是  | LangBot 将回复 POST 到此地址。**仅取自此配置**，不允许在消息中覆盖（防 SSRF）。 |
| 出站签名密钥   | 否  | LangBot 用它对回调签名，供你的接收端校验。留空则回退使用入站密钥。               |
| 默认会话类型   | 否  | `person`（默认）或 `group`。                              |
| 强制入站签名校验 | 否  | 生产环境请保持开启。                                          |
| 回调超时（秒）  | 否  | 单次回调的 HTTP 超时，默认 15。                                |
| 回调最大重试次数 | 否  | 超时或 5xx 时按指数退避重试，默认 3。                              |

创建并绑定**流水线**、**启用**后，配置页会显示**入站 Webhook 地址**，形如 `https://your-langbot/bots/<bot_uuid>`，复制备用。

## 签名方案

两个方向都使用同一套零依赖的 HMAC-SHA256 方案：

```
signing_string = "{timestamp}." + 原始请求体字节
signature      = "sha256=" + hex(HMAC_SHA256(secret, signing_string))
```

通过请求头传递：

| 请求头                    | 含义                                           |
| ---------------------- | -------------------------------------------- |
| `X-LB-Timestamp`       | Unix 秒级时间戳。与服务端相差超过 **±300 秒**则拒绝。           |
| `X-LB-Signature`       | `sha256=<hex>`，对 `"{timestamp}." + body` 计算。 |
| `X-LB-Idempotency-Key` | （可选，入站）幂等键；相同键重复提交返回 `409`。                  |

校验出站回调时同理，使用**出站密钥**（留空则用入站密钥）。

## 发送第一条消息（curl）

```bash
BOT="https://your-langbot/bots/<bot_uuid>"
SECRET="你的入站密钥"
BODY='{"session_id":"ticket-10293","message":[{"type":"Plain","text":"导出功能在控制台一直失败。"}]}'
TS=$(date +%s)
SIG="sha256=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)"

curl -sS -X POST "$BOT" \
  -H "Content-Type: application/json" \
  -H "X-LB-Timestamp: $TS" \
  -H "X-LB-Signature: $SIG" \
  -d "$BODY"
# -> 202 {"code":0,"msg":"accepted","data":{"session_id":"ticket-10293","accepted_message_id":"in_...","aggregating":true}}
```

回复将稍后 POST 到你配置的回调地址。

## 入站消息格式

`POST /bots/{bot_uuid}`

```json
{
  "session_id": "ticket-10293",
  "session_type": "person",
  "sender": { "id": "user-5567", "name": "Alice" },
  "message": [
    { "type": "Plain", "text": "导出功能在控制台一直失败。" },
    { "type": "Image", "url": "https://example.com/screenshot.png" }
  ]
}
```

- `session_id`（**必填**）：你的稳定标识，1:1 映射到一个 LangBot 会话；
- `message`（**必填**）：LangBot 消息链。文本用 `{"type":"Plain","text":"..."}`，图片用 `{"type":"Image","url":"..."}`（或 `base64`）；其余支持 `Voice`、`File`、`At`、`Quote`。

> warning:
>
> 回调地址**不接受**写在消息体里，只取自机器人配置。这是有意为之：即便入站密钥泄露，攻击者也无法把回复重定向到任意地址。

### 消息聚合（N → 1）

若流水线启用了**消息聚合**，用**相同的 `session_id`**在聚合窗口内连发多条消息，它们会被合并为**一轮**处理。无需任何特殊标记，复用 `session_id` 即可。

## 出站回调格式

LangBot 将每段回复 POST 到你的回调地址：

```json
{
  "session_id": "ticket-10293",
  "reply_to": "in_01H...",
  "sequence": 1,
  "is_final": false,
  "stream": false,
  "message": [ { "type": "Plain", "text": "正在排查……" } ],
  "timestamp": "2026-06-22T09:00:01Z"
}
```

你的接收端应尽快返回 `2xx`。非 2xx 或超时，LangBot 会按指数退避重试。

### 多段回复（1 → M）

一轮对话可能产生多次回调，对同一会话按 `sequence` 顺序送达：

```
seq=1 is_final=false  "正在查看导出日志……"
seq=2 is_final=false  "发现 2 次失败的导出。"
seq=3 is_final=true   "已修复，请重试。"
```

用 `session_id` + `sequence` 拼接；收到 `is_final: true` 表示本轮结束。

## 重置会话

为某个 `session_id` 开启全新会话（清空历史）：

```
POST /bots/{bot_uuid}/reset
{ "session_id": "ticket-10293", "session_type": "person" }
→ 200 { "code":0, "msg":"reset", "data": { "session_id":"ticket-10293", "removed": true } }
```

签名方式与入站消息一致。

## 同步便利模式

若你不需要流式/多段，只想在同一次 HTTP 调用里拿回复，可 POST 到 `/sync`。LangBot 会等待本轮结束，把所有回复段**折叠**成一个数组返回：

```
POST /bots/{bot_uuid}/sync
{ "session_id": "ticket-10293", "message": [ { "type":"Plain", "text":"你好" } ] }
→ 200 { "code":0, "msg":"ok",
        "data": { "session_id":"ticket-10293", "reply_to":"in_...", "message": [ ... ] } }
```

> warning:
>
> 同步模式是**有损的**（丢失 `sequence` 与流式边界），且会阻塞最长 `回调超时 × 4` 秒。实时或多段场景请优先使用回调模式。每个 `session_id` 同一时刻只允许一个进行中的 `/sync`。

## 错误码

```json
{ "code": 40101, "msg": "invalid signature: signature_mismatch", "data": null }
```

| HTTP | code  | 含义                                   |
| ---- | ----- | ------------------------------------ |
| 202  | 0     | 已接受                                  |
| 400  | 40001 | 请求体不合法 / 缺少 `session_id` 或 `message` |
| 401  | 40101 | 签名错误或过期                              |
| 409  | 40901 | 幂等键重复                                |
| 413  | 41301 | 消息过大（>1 MiB）                         |
| 500  | 50001 | 内部错误                                 |

## 参考客户端与 5 分钟体验

LangBot 主仓的 [`examples/http-bot/`](https://github.com/langbot-app/LangBot/tree/master/examples/http-bot) 提供了一个**交互式调试台**和 Python / TypeScript 参考客户端。

### 交互式调试台（推荐先跑这个）

[`playground.py`](https://github.com/langbot-app/LangBot/blob/master/examples/http-bot/playground.py) 是一个单文件网页应用:在浏览器里打字 → 自动签名后真实发往运行中的 `http_bot` 机器人 → 回复经回调实时显示在页面上,右侧调试面板展示签名、`202` 确认、以及每条回调的 `sequence` 与验签结果。

```bash
# 在 LangBot 仓库根目录,后端已在运行的前提下:
PUBLIC_IP=<你的公网IP> ./.venv/bin/python examples/http-bot/playground.py
# 然后打开  http://<你的公网IP>:8920/
```

启动时它会从 `data/langbot.db` 读取 API Key 与 `http_bot` 机器人,并通过 LangBot API 把该机器人的回调地址和密钥指向自身(机器人热加载,无需重启)。前提:有一个已启用、且绑定了可用流水线的 `http_bot` 机器人。

### 命令行参考客户端

[`examples/http-bot/`](https://github.com/langbot-app/LangBot/tree/master/examples/http-bot) 还提供了 Python 与 TypeScript 参考客户端（含回调接收器）：

```bash
cd examples/http-bot
pip install flask requests

# 终端 1：回调接收器（把机器人回调地址指向它，本地可用 cloudflared / ngrok 隧道）
python client.py serve --port 8900 --secret SHARED_SECRET

# 终端 2：推送一条消息
python client.py push \
  --url https://your-langbot/bots/<bot_uuid> \
  --secret SHARED_SECRET \
  --session ticket-1 \
  --text "你好"
```

终端 1 会逐段打印回复（`[part ]` / `[FINAL]`）并带序号——这就是 1→M 多段回复、签名校验通过的实时效果。

机器可读契约见主仓 [`docs/http-bot-openapi.json`](https://github.com/langbot-app/LangBot/blob/master/docs/http-bot-openapi.json)。

## 安全清单

- 生产环境保持**强制入站签名校验**开启；
- 回调地址使用 **HTTPS**，且只能在配置中设置（不可逐条覆盖）；
- 密钥按密码对待，通过控制台轮换；
- 入站路由在框架层是无鉴权的（**有意设计**），安全完全依赖 HMAC 签名——公网部署绝不要关闭它。

---

# KOOK

Source: https://langbot.app/docs/zh/usage/platforms/kook

用 LangBot 搭建 KOOK 开黑啦 AI 机器人，将大模型接入 KOOK 频道。

## 创建机器人

前往 [KOOK 开发者中心](https://developer.kookapp.cn/)，登录后进入控制台。

![KOOK 开发者控制台](https://langbot.app/docs/images/zh/deploy/bots/kook/01-dashboard.png)

点击「新建应用」，填写应用信息。

![创建应用](https://langbot.app/docs/images/zh/deploy/bots/kook/02-create-app.png)

应用创建完成后，进入应用详情页。

![应用已创建](https://langbot.app/docs/images/zh/deploy/bots/kook/03-app-created.png)

在应用概览页面可以查看应用的基本信息。

![应用概览](https://langbot.app/docs/images/zh/deploy/bots/kook/04-app-overview.png)

## 获取 Bot Token

在应用页面中，点击「机器人」标签，复制 Bot Token 并妥善保存，后续需要使用。

![获取 Bot Token](https://langbot.app/docs/images/zh/deploy/bots/kook/05-bot-token.png)

## 配置机器人权限

**重要：** 在「机器人」设置中，找到「消息过滤」选项，点击配置。

![消息过滤设置](https://langbot.app/docs/images/zh/deploy/bots/kook/07-message-filters.png)

开启所有消息相关事件权限，包括频道消息和私聊消息事件，否则机器人将无法接收消息。

![启用权限](https://langbot.app/docs/images/zh/deploy/bots/kook/08-permissions-enabled.png)

## 邀请机器人

在机器人设置页面，可以生成邀请链接，将机器人邀请到你的服务器。

![生成邀请链接](https://langbot.app/docs/images/zh/deploy/bots/kook/06-invite-link.png)

## 对接 LangBot

打开 LangBot Webui 页面，在「机器人」页面点击创建新机器人。

![LangBot 机器人管理](https://langbot.app/docs/images/zh/deploy/bots/kook/09-langbot-bots.png)

选择 KOOK 平台，填写机器人名称和 Bot Token。

![配置 KOOK 机器人](https://langbot.app/docs/images/zh/deploy/bots/kook/10-bot-config.png)

保存后，机器人将出现在列表中。

![机器人已创建](https://langbot.app/docs/images/zh/deploy/bots/kook/11-bot-created.png)

点击启用按钮，启动机器人。若成功配置，机器人状态将显示为运行中。

![机器人已启用](https://langbot.app/docs/images/zh/deploy/bots/kook/12-bot-enabled.png)

## 使用机器人

现在在 KOOK 服务器中，机器人就可以正常接收和回复消息了。机器人支持频道消息和私聊消息。

---

# 飞书

Source: https://langbot.app/docs/zh/usage/platforms/lark

用 LangBot 搭建飞书 AI 机器人，将 GPT、Claude、Dify 等接入飞书群组与消息。

## 选择平台域名

创建机器人时，需要在**适配器配置**中选择**平台域名**：

- **飞书 (open.feishu.cn)**：适用于国内飞书用户（默认选项）
- **Lark (open.larksuite.com)**：适用于海外 Lark 用户
- **自定义 (custom)**：适用于使用私有化部署的用户

![选择平台域名](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_platform_domain.png)

> warning:
>
> 如果选择海外版 Lark，请确保使用 `open.larksuite.com` 域名，否则可能导致连接失败。私有化部署用户请根据实际部署地址选择自定义并填写对应域名。

## 一键配置（推荐）

LangBot 支持一键创建飞书应用并自动填写凭证，无需手动复制粘贴。

1. 打开 LangBot WebUI，进入**机器人 > 创建机器人**
2. 填写机器人名称，平台/适配器选择 `飞书`
3. 在下方出现的**一键创建应用**区域，点击右侧的 **开始** 按钮

![一键创建飞书应用](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_oneclick_qrcode.png)

4. 使用飞书扫描弹出的二维码，手机端会进入飞书开放平台的创建智能体应用页面
5. 可以选择**已有应用**或**立即创建**新应用：

![手机端选择](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_select_or_create_bot.png)

如果选择已有应用，会展示应用列表供你选择：

![选择已有应用](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_select_existing.png)

6. 授权成功后，手机端会显示「配置成功」，同时 LangBot WebUI 中的应用ID、应用密钥等凭证会**自动填入**

![配置成功](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_config_success.png)

7. **手动填写机器人名称**，名称必须与飞书机器人名称一致，否则机器人将无法在群内正常接收消息

![手动填写机器人名称](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_fill_bot_name.png)

8. 点击**提交**，完成创建

***

## 手动配置

### 创建机器人

前往[飞书开放平台](https://open.feishu.cn/app)，登录后，创建企业自建应用/商店应用 [(区别介绍)](https://open.feishu.cn/document/platform-overveiw/overview)。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_01.png)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_02.png)

为应用添加机器人能力：
![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_03.png)

在权限管理中添加图中所示权限：

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_04.png)

如需卡片流式权限则多添加如下图的创建与更新卡片：

![img\_1.png](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_14.png)

> warning:
>
> 默认卡片模板如需更换，需要自己去平台适配器的代码中修改卡片模板

### 对接 LangBot

在`凭证与基础信息`页找到`app_id`和`app_secret`。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_05.png)

打开LangBot 的 Webui 配置页面，创建一个新的机器人

将相关信息填入表单

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/connect_to_langbot.png)

流式相关：
![流式相关](https://langbot.app/docs/images/zh/deploy/bots/lark/connect_to_langbot01.png)

填写完成后启动 LangBot，若成功配置，日志中会出现`[01-29 23:42:56.796] manager.py (68) - [INFO] : 初始化平台适配器 1: lark`的字样，保持 LangBot 运行。

> :
>
> 默认使用的是 WebSocket 长连接模式，对应下方的长连接订阅。但某些情况下（如国际版飞书）不具有长连接模式，此时需要使用 Webhook 模式，对应`将事件发送到开发者服务器`模式，请参考以下配置：
>
> - `enable-webhook`：设置为`true`
> - `encrypt-key`：设置为`事件与回调`页面的`加密策略`中的`Encrypt Key`
>
> 注意，在Webhook模式中，LangBot 需要部署在具有公网 IP 的服务器上，并确保防火墙已开放上方配置的端口。

> idea:
>
> **没有公网服务器？** [LangBot Cloud](https://space.langbot.app/cloud) 自带域名和 HTTPS，无需自行配置，开箱即用飞书机器人。

### 配置事件订阅

前往`事件与回调`页，配置订阅方式为`长连接`：

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_07.png)

并添加事件：`接收消息`

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_08.png)

设置`回调配置`，选择使用长连接的回调(如果是webhook则使用webhook)

![设置回调配置](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_16.png)

添加回调`卡片回传交互`

![添加回调](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_17.png)

> :
>
> Webhook 模式配置方式：
>
> ![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_13.png)
>
> 请先启动 LangBot，在此处填写从 LangBot 获取的 Webhook 地址

### 发布机器人

点击顶部`创建版本`，填写版本号等信息，点击下方`保存`。

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_09.png)

在飞书群中添加机器人，即可使用：

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_10.png)

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_11.png)

私聊也可以直接使用

![alt text](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_12.png)

## 常见问题

- 商店应用机器人创建/保存后无法立刻响应聊天消息，由于[app\_ticket事件](https://open.feishu.cn/document/server-docs/application-v6/event/app_ticket-events)延迟机制，需要等待2分钟左右才可以正常使用。

---

# LINE

Source: https://langbot.app/docs/zh/usage/platforms/line

用 LangBot 搭建 LINE AI 机器人，将大模型接入 LINE 聊天与官方账号。

本文介绍如何将 LangBot 与 LINE 平台进行对接，实现 LINE 机器人功能。

## 创建LINE机器人

### 注册LINE开发者账号

1. 访问 [LINE Developers 官网](https://developers.line.biz/)，使用 LINE 账号登录
2. 登录后，进入开发者控制台

### 创建 Provider 和 Channel

> [开发者控制台](https://developers.line.biz/console)

1. 在开发者控制台中，创建一个新的 Provider（如果没有的话）

![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line01.png)

2. 在 Provider 下，点击 "Create"

![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line02.png)

3. 填入名称，并点击 Create

![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line03.png)

4. 跳转页面后选择 Create a Message API
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line04.png)

- 继续点击 Create a Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line05.png)
- 跳转页面后填入基本信息
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line06.png)
  - Channel Name（频道名称）
  - Channel Description（频道描述）
  - Category（类别）
  - Subcategory（子类别）
  - Email Address（邮箱地址）

5. 全部填好之后点击 "Continue" 创建
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line07.png)
6. 检查填入的信息，无问题点击 Submit 即可
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line08.png)
7. 创建成功去使用
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line09.png)

### 获取配置信息

创建完成后，您将获得以下重要信息，请记录下来：

1. Channel Secret

> [刚刚点击使用跳转页面](https://manager.line.biz/account)

- 选择 Settings
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line09.png)
- 点击 Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line11.png)
- 开启 Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line12.png)
- 选择刚刚新建的 Provider 并点击 Agree
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line13.png)
- 隐私条款直接点击 OK
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line14.png)
- 点击 OK 创建成功
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line15.png)
- Copy 即可
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line16.png)

2. Channel Access Token（需要点击 "Issue" 按钮生成）

- 点击控制台或者直接访问 [控制台](https://developers.line.biz/console/)
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line17.png)
- 选择你创建的 Provider 并点击 Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line18.png)
- 点击 Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line19.png)
- 下滑到最下面，点击 Issue
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line20.png)
- 点击图标复制
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line21.png)

## 对接 LangBot

接下来打开 LangBot 配置页面：

1. 点击 "机器人"，然后点击 "添加"
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line26.png)

2. 在 "平台/适配器选择" 中选择 "LINE"
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line27.png)

3. 填写配置信息：
   - Channel Secret：您之前获取的 Channel Secret
   - Channel Access Token：您之前获取的 Channel Access Token
     ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line28.png)

4. 点击 "保存" 完成配置
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line29.png)

## 配置Webhook

> info:
>
> 推荐您先参照[配置 HTTP 反向代理](https://langbot.app/docs/zh/workshop/production/proxy-and-ssl.md)来配置 LangBot 回调地址。

> idea:
>
> **不想配置公网和域名？** [LangBot Cloud](https://space.langbot.app/cloud) 自带域名和 HTTPS，开箱即用。

- 从 LangBot 配置页面获取 Webhook 回调地址
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line30.png)

- 点击控制台或者直接访问 [控制台](https://developers.line.biz/console/)
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line17.png)

- 选择你创建的 Provider 并点击 Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line18.png)

- 点击 Message API
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line19.png)

- 点击 Edit 填写连接
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line22.png)

- 填入连接（必须要 HTTPS 的连接，也就是要 SSL 证书），点击 Update
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line23.png)

- 选择 Use Webhook
  ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line24.png)

5. 点击 "Verify" 按钮测试连接是否成功
   ![alt text](https://langbot.app/docs/images/zh/deploy/bots/line/line25.png)

## 功能配置

在 LINE 开发者控制台中，您可以进一步配置机器人的功能：

1. 在 "Messaging API" 选项卡中，找到 "LINE Official Account Features" 部分
2. 根据需要开启或关闭以下功能：
   - 自动回复消息
   - 加好友欢迎消息
   - 群组和多人聊天
   - 机器人加入群组时的问候语

## 使用

配置完成后，用户可以通过以下方式与您的 LINE 机器人互动：

1. 扫描 LINE 开发者控制台中提供的 QR 码添加机器人为好友
2. 在聊天中发送消息，机器人将通过 LangBot 处理并回复

## 常见问题

### Webhook 验证失败

- 确保您的服务器可以通过 HTTPS 访问
- 检查 Webhook URL 是否正确
- 确认 LangBot 服务是否正常运行

### 消息无法接收

- 检查 Channel Access Token 是否有效
- 确认 "Use Webhook" 选项已开启
- 查看 LangBot 日志是否有错误信息

### 权限问题

- 确保您已在 LINE 开发者控制台中为机器人开启了必要的权限
- 对于某些高级功能，可能需要 LINE Premium 账号

---

# Mattermost

Source: https://langbot.app/docs/zh/usage/platforms/mattermost

用 LangBot 接入 Mattermost 机器人，几分钟内将 智能体/工作流 接入 Mattermost 服务器。

## 创建机器人账号

登录Mattermost实例（自部署/官方皆可），点击左上角的`Mattermost图标`，在下拉菜单中选择`集成`。

![](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_main_page.png)

进入集成页面后，在左侧菜单中选择`机器人账号`，点击右上角的添加机器人账号。

![](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_account.png)

为机器人起一个用户名。

![](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_add_new.png)

身份选择`成员`即可（暂不支持管理员相关功能），需要私聊选`post:all`，仅需要公共频道就只勾选`post:channels`，然后点击右下角的`创建机器人账号`。

![](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_deploy.png)

点击按钮复制令牌（只显示一次，记得保存），点右下角`完成`。

![](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_bot_token.png)

## 配置LangBot机器人

进入LangBot官网或自部署实例，按下图中红箭头指示的顺序操作：

- 光标移到左侧`机器人`选项卡上，会显示一个加号`+`，点击加号
- 给机器人起一个名字，输进`机器人名称`的文本框
- 点击平台适配器选择的选项框，在下拉菜单中选择`Mattermost`
- 输入`Mattermost`实例的地址和刚才创建的机器人账号的令牌
- （可选）如果你的流水线/AI供应商不支持流式输出，则关闭该选项
- 点击右上角的提交后会进入编辑该机器人的界面

![](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_langbot_add_new.png)

绑定现有的流水线，以及配置路由（如果有需求的话），并点击右上角的保存。

![](https://langbot.app/docs/images/zh/deploy/bots/mattermost/Mattermost_langbot_deploy.png)

---

# Lagrange

Source: https://langbot.app/docs/zh/usage/platforms/qq/aiocqhttp/lagrange

通过 Lagrange（aiocqhttp）将 QQ 接入 LangBot，在 QQ 群聊与私聊中运行 AI 机器人。

## Lagrange介绍

Lagrange 是一个 QQNT 协议逆向工程框架，轻便且相对稳定。通过 OneBot 11 协议接入，需选择使用`OneBot v11`作为适配器。

> warning:
>
> 需要使用 NT QQ 与机器人交互，旧版QQ无法正常使用

## 部署步骤

以下仅提供 Windows 上的大致步骤，详细步骤或其他平台请参考 [Lagrange官方文档](https://lagrangedev.github.io/Lagrange.Doc/v1/Lagrange.OneBot/)

### 环境配置

安装.NET 8运行时，[点击直达微软官网下载](https://dotnet.microsoft.com/zh-cn/download/dotnet/thank-you/runtime-desktop-8.0.4-windows-x64-installer)

### 从Github Actions下载最新的build

需要登录Github后才能下载，如果你不需要部分特性，可以在Release下载，看图片3

[Github Actions](https://github.com/KonataDev/Lagrange.Core/actions)

看图进行下载:

![图片1](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_1.png)

![图片2](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_2.png)

![图片3](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/dl_lgr_3.png)

### 尾声

解压你所下载的zip，打开到有Lagrange.OneBot.exe的目录，在此目录下打开cmd命令提示符，输入

```bash
.\Lagrange.OneBot
```

运行一次，如果输出了一个二维码，即可直接用机器人号扫码登录（若二维码显示不清楚，可以到lagrange的data目录下寻找图片文件）。

若无法登录，请检查是否正常填写了lagrange配置文件appsettings.json中的签名地址 SignServerUrl ，签名地址请到lagrange文档中寻找。

## 修改配置

需要配置 Lagrange 以让其连接上 LangBot，请编辑 Lagrange 的配置文件 appsettings.json，确保 Implementations 中的连接配置符合下图内容：

![配置连接](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/lagrange/config_lgr.png)

其中 Type 必须为 `ReverseWebSocket`;\
Host 为 LangBot 运行的主机 IP，若在同一主机上，可以写 `127.0.0.1`；\
Suffix 必须为 `/ws`；

## Lagrange 对接

接下来打开 LangBot 配置页面

点击机器人，点击添加

`平台/适配器选择`为`OneBot v11`

![napcat\_webui\_03](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png)

> info:
>
> 注意，如果涉及多个 docker 容器的网络连接问题，请参考[网络配置详解](https://langbot.app/docs/zh/workshop/network-details.md)

---

# LiteLoaderQQNT

Source: https://langbot.app/docs/zh/usage/platforms/qq/aiocqhttp/llonebot

通过 LiteLoaderQQNT（LLOneBot）将 QQ 接入 LangBot，为 QQ 群聊与会话搭建 AI 机器人。

通过 OneBot 11 协议接入，需选择使用`OneBot v11`作为适配器。

# LiteLoaderQQNT

- [LiteLoaderQQNT 的 OneBot API 插件](https://github.com/LLOneBot/LLOneBot) 注入 QQ 客户端并将其转换为 OneBot 11 协议

安装LiteLoaderQQNT的教程：<https://llonebot.github.io/zh-CN/guide/getting-started>

![图片1](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/llonebot/llob_cfg.png)

确保地址中 IP地址 是 LangBot 运行的主机的地址（若在同一网络内运行则为 127.0.0.1）

## Lagrange 对接

接下来打开 LangBot 配置页面

点击机器人，点击添加

`平台/适配器选择`为`OneBot v11`

![napcat\_webui\_03](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png)

> info:
>
> 注意，如果涉及多个 docker 容器的网络连接问题，请参考[网络配置详解](https://langbot.app/docs/zh/workshop/network-details.md)

---

# NapCat

Source: https://langbot.app/docs/zh/usage/platforms/qq/aiocqhttp/napcat

通过 NapCat（aiocqhttp）将 QQ 接入 LangBot，在 QQ 群聊与私信中运行 AI 聊天机器人。

通过 OneBot 11 协议接入，需选择使用`OneBot v11`作为适配器。

## NapCat安装教程

按照 [NapCat 官方文档安装](https://napcat.napneko.icu/guide/start-install)

## NapCat配置教程

仅以 webui 操作为例，其他的配置方式请查看 NapCat 文档。

登录后，在控制台或Bash上可以查看日志 , 找到 `[NapCat] [WebUi] WebUi Publish Panel Url: http://x.x.x.x:6099/webui?token=xxxxx `
![napcat\_webui\_01](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_01.png)

复制Url到浏览器或者 Windows11 按照Ctrl点击Url即可 扫码登录后即可进入网络配置一页

点击添加网络配置 WebSocket客户端 点击启用 然后在Url一栏填入 `ws://127.0.0.1:2280/ws`  并保存即可
![napcat\_webui\_02](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_02.png)

## NapCat 对接

接下来打开 LangBot 配置页面

点击机器人，点击添加

`平台/适配器选择`为`OneBot v11`

![napcat\_webui\_03](https://langbot.app/docs/images/zh/deploy/bots/qq/onebot/napcat/napcat_webui_03.png)

> info:
>
> 注意，如果涉及多个 docker 容器的网络连接问题，请参考[网络配置详解](https://langbot.app/docs/zh/workshop/network-details.md)

---

# QQ 官方机器人 API（WebSocket）

Source: https://langbot.app/docs/zh/usage/platforms/qq/official

通过 QQ 官方机器人 API 接入 LangBot，在 QQ 上运行合规的 AI 机器人。

> warning:
>
> QQ 官方已停止维护 WebSocket 方式，请使用 Webhook 方式。

QQ官方机器人所有人均可申请，可以在频道和群聊中使用，私聊也可。

## 注册 QQ 机器人

前往[QQ开放平台](https://q.qq.com/#/)，找到下方的 QQ 机器人文档，按照指引注册 QQ 频道机器人。

## 获取凭证

注册完成后，前往机器人控制台，找到 开发设置，获取 `AppId(机器人ID)` 和 `AppSecret(机器人密钥)`，接下来进入填写配置信息步骤。

---

# QQ 官方机器人 API（Webhook）

Source: https://langbot.app/docs/zh/usage/platforms/qq/official_webhook

通过 QQ 官方机器人 API（Webhook）接入 LangBot，在 QQ 上运行合规的 AI 机器人。

本文章只提供测试版机器人的发布，具体机器人上线请按照 [发布流程](https://q.qq.com/qqbot/#/home) 进行部署。

> warning:
>
> 目前 QQ 官方发布公告，禁止违规接入 AIGC 功能，请慎重使用。

## 注册 QQ 机器人（测试机器人）

### 配置机器人基本信息

前往 [QQ开放平台](https://q.qq.com/#/) ，找到下方的 `应用管理` ，点击创建机器人，填写基本信息之后，进入机器人页面，如图：

![机器人主页面](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial1.png)

`首页` 选项中的 `发布流程` 即为上线机器人的步骤。由于部署的是测试版机器人，所以只需要进行其中的 `资料` 和 `沙箱配置` 。\


先进行资料填写，然后点击沙箱配置。

#### 配置沙箱配置项

点击 `沙箱配置` 。
如果要部署在QQ群中，那么按照 `QQ群ID` 下方的要求进行选择群聊，在消息列表配置中添加有私聊权限的用户。\

如果要部署在QQ频道中，那么按照 `频道ID` 下方的要求选择频道ID，机器人类型为0。

#### 配置开发管理项

点击 `开发管理` 。

![开发管理页面](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial2.png)

记录其中的 `AppID` , `Token` , `AppSecret` ,并将 LangBot 所在服务器的IP地址填写到IP白名单中。

## 对接 LangBot

接下来打开 LangBot 配置页面

点击机器人，点击添加

`平台/适配器选择`为`QQ官方API`

![QQ 官方 Bot 对接 LangBot](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial3.png)

## 配置回调地址

要求 LangBot 部署在具有公网 IP 的服务器上，并已成功启用 HTTPS。请根据文档[配置 HTTP 反向代理和 SSL](https://langbot.app/docs/zh/workshop/production/proxy-and-ssl.md) 操作。

> idea:
>
> **不想折腾公网 IP 和 HTTPS？** [LangBot Cloud](https://space.langbot.app/cloud) 自带域名解析，注册即可直接使用 QQ 官方机器人。

#### 后续配置

若 Caddy 启动不成功，请自行阅读 [Caddy文档](https://caddy2.dengxiaolong.com/docs/quick-starts/caddyfile)，或者加入 LangBot 社区群请求帮助。\


以下是一些可能出现的问题：

- 没有开启443端口
- 没有将域名解析到本机
- 没有成功保存 Caddyfile

### 设置管理端回调地址

首先 **启动 LangBot** 。

点击 机器人管理端网页中的 `回调配置`，勾选下面 `添加事件` 中的所有事件。

进入 LangBot 配置页面，启用并且选择对应的QQ机器人，粘贴对应机器人配置页面中的 Webhook 回调地址，将其中的 IP 地址和端口改成之前 Caddy 配置的域名，在请求地址中填入。

如图：
![Caddy文档](https://langbot.app/docs/images/zh/deploy/bots/qq/official/qqofficial4.png)

比如域名为 `testlb.com`，那么请求地址中填写 `testlb.com/bots/xxxxxx-xxxxxx` ，点击确定配置。如果回调地址保存成功，那么意味着部署成功。若出现 `校验失败` 字样，请认真检查上述配置项是否填写正确。

## 发布方式

进入 `首页` 的发布流程 ，按照流程进行机器人发布，上线。

---

# 机器人 (Bots)

Source: https://langbot.app/docs/zh/usage/platforms/readme

将 LangBot 接入各消息平台：Discord、Telegram、Slack、微信、QQ、飞书、钉钉、LINE 等。

机器人用于从消息平台接收消息事件并调用流水线处理消息。

![arch](https://langbot.app/docs/images/zh/deploy/bots/arch.png)

| 平台         | 状态 | 备注                                       | 教程                                                                                                                                                                                                                                                     |
| ---------- | -- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| OneBot v11 | ✅  | 使用普通的 QQ 号作为机器人，需要使用独立的协议端，支持 OneBot v11 | [NapCat](https://langbot.app/docs/zh/usage/platforms/qq/aiocqhttp/napcat.md)  [Lagrange](https://langbot.app/docs/zh/usage/platforms/qq/aiocqhttp/lagrange.md)  [LiteLoaderQQNT](https://langbot.app/docs/zh/usage/platforms/qq/aiocqhttp/llonebot.md) |
| QQ 官方机器人   | ✅  | 接入 QQ 开放平台的机器人 API                       | [教程](https://langbot.app/docs/zh/usage/platforms/qq/official_webhook.md)                                                                                                                                                                               |
| 个人微信助手     | ✅  | 微信官方个人助手机器人                              | [教程](https://langbot.app/docs/zh/usage/platforms/wechat/weixin.md)                                                                                                                                                                                     |
| 企业微信       | ✅  | 企业内部机器人                                  | [教程](https://langbot.app/docs/zh/usage/platforms/wecom/wecom.md)                                                                                                                                                                                       |
| 企业微信客服     | ✅  | 企业对外机器人                                  | [教程](https://langbot.app/docs/zh/usage/platforms/wecom/wecomcs.md)                                                                                                                                                                                     |
| 企业微信智能机器人  | ✅  | 智能机器人                                    | [教程](https://langbot.app/docs/zh/usage/platforms/wecom/wecombot.md)                                                                                                                                                                                    |
| 微信公众号      | ✅  | 微信公众平台机器人                                | [教程](https://langbot.app/docs/zh/usage/platforms/wxoa.md)                                                                                                                                                                                              |
| 飞书         | ✅  |                                          | [教程](https://langbot.app/docs/zh/usage/platforms/lark.md)                                                                                                                                                                                              |
| 钉钉         | ✅  |                                          | [教程](https://langbot.app/docs/zh/usage/platforms/dingtalk.md)                                                                                                                                                                                          |
| Discord    | ✅  |                                          | [教程](https://langbot.app/docs/zh/usage/platforms/discord.md)                                                                                                                                                                                           |
| Telegram   | ✅  |                                          | [教程](https://langbot.app/docs/zh/usage/platforms/telegram.md)                                                                                                                                                                                          |
| Slack      | ✅  |                                          | [教程](https://langbot.app/docs/zh/usage/platforms/slack.md)                                                                                                                                                                                             |
| Mattermost | ✅  | 适用于开源版、免费版、专业版、企业版                       | [教程](https://langbot.app/docs/zh/usage/platforms/mattermost.md)                                                                                                                                                                                        |
| LINE       | ✅  |                                          | [教程](https://langbot.app/docs/zh/usage/platforms/line.md)                                                                                                                                                                                              |
| KOOK       | ✅  |                                          | [教程](https://langbot.app/docs/zh/usage/platforms/kook.md)                                                                                                                                                                                              |
| 页面机器人      | ✅  | 将聊天组件嵌入网站                                | [教程](https://langbot.app/docs/zh/usage/platforms/webpage.md)                                                                                                                                                                                           |

> idea:
>
> **不想折腾公网 IP 和域名？** 企业微信、微信公众号、QQ 官方机器人、飞书、钉钉、Slack、LINE 等平台需要配置 Webhook 回调地址，这意味着你需要公网服务器、域名和 HTTPS 证书。[LangBot Cloud](https://space.langbot.app/cloud) 自带域名解析和 HTTPS，注册即可直接使用，省去繁琐的网络配置。

---

# Lucky Lilla Desktop

Source: https://langbot.app/docs/zh/usage/platforms/satori/llonebot

通过 Satori 协议（LLOneBot）接入 LangBot，在受支持的消息客户端上运行 AI 机器人。

通过 Satori 协议接入，需选择使用`Satori`作为适配器。

# LuckyLillia

- [LuckyLillia](https://github.com/LLOneBot/LuckyLilliaBot) 安装客户端以使用Satori协议

安装LuckyLillia的教程：<https://luckylillia.com/guide/choice_install>

![图片1](https://langbot.app/docs/images/zh/deploy/bots/satori/llbot_local_setting.png)

确保地址中 IP地址 是 LangBot 运行的主机的地址（若在同一网络内运行则为 `127.0.0.1`） 默认端口 `5600` 可以根据需要更改 推荐设置令牌

> ![图片2](https://langbot.app/docs/images/zh/deploy/bots/satori/llbot_open_setting.png)
>
> 该图为公网配置确保地址中 IP地址 是 LangBot 运行的主机的地址 此时配置需要暴露langbot的该端口

## LangBot 对接

接下来打开 LangBot 配置页面

点击机器人，点击添加

`平台/适配器选择`为`Satori`

![图片3](https://langbot.app/docs/images/zh/deploy/bots/satori/llone_langbot_build.png)

> 如果你使用默认配置(内网)你甚至不用修改任何参数

创建好后你仍然可以调整参数

![图片4](https://langbot.app/docs/images/zh/deploy/bots/satori/llone_langbot_setting.png)

确保你启用了本适配器

![图片5](https://langbot.app/docs/images/zh/deploy/bots/satori/satori_platform_open.png)

> info:
>
> 注意，如果涉及多个 docker 容器的网络连接问题，请参考 [网络配置详解](https://langbot.app/docs/zh/workshop/network-details.md)

---

# Slack

Source: https://langbot.app/docs/zh/usage/platforms/slack

用 LangBot 搭建 Slack AI 机器人，将 GPT、Claude、Dify 等接入你的 Slack 工作区。

## 创建机器人

前往 [Slack的App平台](https://api.slack.com/apps)。

![Slack平台](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_01.jpg)

点击右上角的 `Create New App` ，选择从 `from a manifest` ， 选择要部署机器人的工作区，选择下一步，
选择创建机器人。

进入左侧 `Basic Information` 选项，记录 `signing_secret`。

进入左侧 `OAuth & Permissions` ，往下拉到 `Scopes`，添加如下机器人权限：

![机器人权限1](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_02.jpg)

![机器人权限2](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_03.jpg)

添加上述权限之后，点击 `Install to your workspace`，记录下开头为 `xoxb-xxxxx`的token。\


**注：**
**若没有一次性添加成功权限，后续则需要重新安装App。**\


进入左侧 `App Home` 栏，滑到最下面有 `Message Tab`，打开并且勾选
`Allow users to send Slash commands and messages from the messages tab`。

## 对接 LangBot

进入左侧 `Event Subscriptions` ，打开开关，点击 `Subscribe to bot events`，
将如下权限添加进去:
![事件权限](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_04.jpg)

上述操作都完成之后，打开 LangBot Webui 配置页面，添加一个新的机器人

![事件权限](https://langbot.app/docs/images/zh/deploy/bots/slack/connect_to_langbot.png)

## 启动机器人

> info:
>
> 由于 Slack 官方要求使用 https，请根据文档[配置 HTTP 反向代理和 SSL](https://langbot.app/docs/zh/workshop/production/proxy-and-ssl.md) 先配置好反向代理。

Slack 配置项在填写完成后，**启动 LangBot**。
启用并打开 LangBot 主页中的 Slack 机器人配置页面，复制其中的 WebHook URL，在刚才Event Subscriptions的 `Request URL`中，填写入 WebHook URL。

上述配置项都填写完成后，点击保存链接，若标识为绿色的**Verified**，那么就说明部署成功。
否则查看上述配置项是否填写正确。

## 效果图

![效果图](https://langbot.app/docs/images/zh/deploy/bots/slack/slack_05.jpg)

---

# Telegram

Source: https://langbot.app/docs/zh/usage/platforms/telegram

用 LangBot 搭建 Telegram AI 机器人，将 GPT、Claude、Gemini、DeepSeek 与 Dify 接入 Telegram 聊天与群组。

## 创建机器人

前往 [Telegram 机器人创建页面](https://t.me/botfather)，按照提示操作，创建一个机器人。

![Telegram 机器人创建](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_01.png)

![Telegram 机器人创建](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_02.png)

创建完成后，BotFather 会返回一个 API Token，请妥善保存。接下来关闭`Privacy Mode`，以便在群聊中使用。

![Telegram 机器人 API Token](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_03.png)

## 对接 LangBot

打开 LangBot Webui 页面，创建一个新机器人

![对接 LangBot](https://langbot.app/docs/images/zh/deploy/bots/telegram/connect_to_langbot.png)

填写完成后启动 LangBot，若成功配置，日志中会出现`[02-02 16:48:15.263] manager.py (68) - [INFO] : 初始化平台适配器 1: telegram`的字样，保持 LangBot 运行。

## 使用机器人

现在在群里或者私聊机器人都可以正常使用了。

![Telegram 机器人使用](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_04.png)

![Telegram 机器人使用](https://langbot.app/docs/images/zh/deploy/bots/telegram/telegram_05.png)

---

# 页面机器人

Source: https://langbot.app/docs/zh/usage/platforms/webpage

在网页中嵌入 LangBot AI 聊天机器人，为任意网站添加大模型驱动的聊天组件。

通过一行脚本标签将 LangBot 聊天组件嵌入到任何网站。

## 创建机器人

打开 LangBot WebUI，进入**机器人 > 创建机器人**，填写机器人名称，平台/适配器选择 `页面机器人`。

![创建页面机器人](https://langbot.app/docs/images/zh/deploy/bots/web_page/webpage_01.png)

## 配置项

| 配置项             | 说明                                                               |
| --------------- | ---------------------------------------------------------------- |
| 组件标题            | 显示在聊天组件顶部的标题，默认为 LangBot                                         |
| 气泡图标            | 浮动聊天气泡上显示的图标                                                     |
| 组件语言            | 聊天组件的显示语言，支持简体中文、English 等                                       |
| Turnstile 站点密钥  | Cloudflare Turnstile 站点密钥，用于防止机器人滥用。留空则不启用                       |
| Turnstile 服务端密钥 | Cloudflare Turnstile 服务端密钥，与站点密钥一起在 Cloudflare 控制台中获取。设置了站点密钥时必填 |

## 获取嵌入代码

创建并保存后，在机器人配置页面的**嵌入代码**区域会自动生成一段 `<script>` 标签。

![嵌入代码](https://langbot.app/docs/images/zh/deploy/bots/web_page/webpage_02.png)

复制此代码并粘贴到你的网站 HTML 中（通常放在 `</body>` 前），保存后页面右下角将出现聊天气泡，访客即可与机器人对话。

```html
<script data-title="LangBot" src="http://localhost:5300/api/v1/embed/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"></script>
```

> warning:
>
> 嵌入代码中的 URL 默认为 `localhost`，如果你的 LangBot 部署在服务器上，请将 `localhost:5300` 替换为你的实际访问地址。

## 防滥用（可选）

如果担心接口被滥用，可以在 Cloudflare 控制台中开启 Turnstile：

1. 前往 [Cloudflare Turnstile](https://dash.cloudflare.com/) > 添加站点
2. 获取**站点密钥**和**服务端密钥**
3. 分别填入 LangBot 页面机器人的对应配置项
4. 保存即可生效

## 本地预览 / 演示

如果你想在接入自己网站前先体验一下嵌入组件的效果，LangBot 主仓的
[`examples/web-page-bot/`](https://github.com/langbot-app/LangBot/tree/master/examples/web-page-bot)
提供了一个自包含的单文件演示页 `index.html`：在浏览器中打开它，填上你的 LangBot
地址和页面机器人 UUID，它就会加载真实的嵌入组件，让你像网站访客一样和机器人对话，
并实时生成可直接粘贴到自己网站的 `<script>` 代码片段。

```bash
# 在 LangBot 仓库根目录起一个静态服务，然后在浏览器中打开
python3 -m http.server 8930
# 访问 http://localhost:8930/examples/web-page-bot/
```

## 开始使用

嵌入代码添加到网站后，访客点击页面右下角的聊天气泡即可与机器人进行对话。

---

# 个人微信（WeChatPadPro）

Source: https://langbot.app/docs/zh/usage/platforms/wechat/wechatpad

通过 WeChatPad 将个人微信接入 LangBot，运行大模型驱动的 AI 机器人。

> 异地警告，没有 Socks5 代理或者本地服务器慎用！！！！！！

**本教程仅说明 Docker 部署教程，如果可以尽量将 WeChatPadPro 部署到同一网络**

## 拉取 WeChatPad-Docker

1. 原项目

```bash
git clone https://github.com/WeChatPadPro/WeChatPadPro.git  
cd WeChatPadPro/deploy
```

2. 简化

```bash
git clone https://github.com/fdc310/WeChatPad-Docker.git  
```

### 一、如果不更改 Redis、MySQL、AdminKey 和相关端口及其网络的情况下可以直接运行

```bash
docker compose up -d
```

- 查看日志是否启动成功

```bash
# 简化
docker logs wechatpad
# or 原版
docker logs wechatpadpro
```

启动成功实例如下输出：

查看并记录自己的日志生成的 `adminKey`，后面登录会用到。

```bash
版本号: v20240818.00
======== ADMIN_KEY === adminKey ========
connect MySQL success
auto create MySQL tables success
connect Redis success
GET Connection locfree Failed by ee4c9a06-cf5e-4451-9e81-5290d0217625  abandon the conntection get  !
updateApiVersion success

启动GIN服务成功！ http://0.0.0.0:8849
```

- 然后在本机或者局域网下访问 `http://serveip:9090` 进入 Swagger 即可。（这是简化版 docker-compose 中映射端口号）
- 然后在本机或者局域网下访问 `http://serveip:1239` 进入 Swagger 即可。（这是原版 docker-compose 中映射端口号）

### 二、如果要更改（简化版）docker-compose 网络与 langbot 在同一个 Docker 网络中，以及数据库密码和端口更改

参考修改 YAML 文件，以下是 WeChatPad 的 YAML 文件，容器连接方式可以参考 [文档](https://langbot.app/docs/zh/workshop/network-details.md)。

- 如需修改数据库账号密码等，有能力的自行修改，此版本修改需要同时修改项目目录下 `app/assets/setting.json` 中的用户密码相关

```yaml
version: "3.3"
services:
  mysql_wx:
    container_name: mysql_wxpad
    image: mysql:8.0
    ports:
      - "3306:3306"
    restart: always
    logging:
      driver: "json-file"
      options:
        max-size: "5g"
    environment:
      MYSQL_ROOT_PASSWORD: test_mysql
      MYSQL_ROOT_HOST: '%'
      MYSQL_DATABASE: wechatpadpro
    volumes:
      - "./mysql/data:/var/lib/mysql"
      - "./mysql/config:/etc/mysql/conf.d"
    networks:
      - langbot-network
    healthcheck:
      test: [ "CMD", "mysqladmin", "ping", "-h", "localhost" ]
      interval: 5s
      timeout: 3s
      retries: 5

  redis_wx:
    image: redis:alpine
    container_name: redis_wxpad
    restart: unless-stopped
    command: redis-server --requirepass test_redis
    environment:
      - REDIS_PASSWORD=test_redis
    volumes:
      - ./redis/data:/data
    ports:
      - "6381:6379"
    networks:
      - langbot-network
    healthcheck:
      test: ["CMD", "redis-cli", "-a", "test_redis", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  wechatpad:
    container_name: wechatpad
    image: alpine:latest
    ports:
      - "9090:8849"
    restart: always
    depends_on:
      mysql_wx:
        condition: service_healthy
      redis_wx:
        condition: service_healthy
    links:
      - mysql_wx
      - redis_wx
    volumes:
      - ./app:/app # 映射数据目录，宿主机:容器
    working_dir: /app
    command: [ "/bin/sh", "-c", "chmod +x ./stay && ./stay" ]
    logging:
      driver: "json-file"
      options:
        max-size: "5g"
    environment:
      - TZ=Asia/Shanghai
      - LANG=zh_CN.UTF-8
      - LC_ALL=zh_CN.UTF-8
    networks:
      - langbot-network
networks:
  langbot-network:
    external: true
```

### 三、原版 docker-compose 需要修改与 langbot 同一 Docker 网络中，以及数据库用户密码，都那口映射修改可参考以下：

- 如需修改数据库账号密码等，有能力的自行修改，此版本修改需要同时修改项目目录下 `deploy/.env` 中的用户密码相关

```yaml
version: '3.8'

services:
  wechatpadpro:
    image: registry.cn-hangzhou.aliyuncs.com/wechatpad/wechatpadpro:v0.11
    container_name: wechatpadpro
    restart: always
    ports:
      - "1239:1239"
    volumes:
      - wechatpadpro_data:/app/data
      - wechatpadpro_logs:/app/logs
    environment:
      - TZ=Asia/Shanghai
      - DEBUG=false
      - ADMIN_KEY=12345
      - HOST=0.0.0.0
      - PORT=1239
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_DB=1
      - REDIS_PASS=123456
      - MYSQL_CONNECT_STR=wechatpadpro:123456@tcp(mysql:3306)/wechatpadpro?charset=utf8mb4&parseTime=true&loc=Local
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - langbot-network

  redis:
    image: registry.cn-hangzhou.aliyuncs.com/wechatpad/wechatpadpro-redis:v0.1
    container_name: wechatpadpro_redis
    restart: always
    command: redis-server --requirepass 123456
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 3
    networks:
      - langbot-network

  mysql:
    image: registry.cn-hangzhou.aliyuncs.com/wechatpad/wechatpadpro-mysql:v0.11
    container_name: wechatpadpro_mysql
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=123456
      - MYSQL_DATABASE=wechatpadpro
      - MYSQL_USER=wechatpadpro
      - MYSQL_PASSWORD=123456
      - TZ=Asia/Shanghai
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "wechatpadpro", "-p123456"]
      interval: 5s
      timeout: 3s
      retries: 3
    networks:
      - langbot-network

networks:
  langbot-network:
    driver: bridge

volumes:
  wechatpadpro_data:
  wechatpadpro_logs:
  redis_data:
  mysql_data: 
```

#### `.env` 环境变量说明

| 变量名                 | 说明        | 默认值    | 是否必填 |
| ------------------- | --------- | ------ | ---- |
| DEBUG               | 调试模式      | false  | 否    |
| ADMIN\_KEY          | 管理员密钥     | 12345  | 是    |
| PORT                | 服务端口      | 1239   | 否    |
| REDIS\_PASS         | Redis 密码  | 123456 | 是    |
| MYSQL\_CONNECT\_STR | MySQL 连接串 | 见配置文件  | 是    |

## 如果要手动部署

- 手动部署或者 Win 上使用 Docker 部署参考以下官方文档

请查看 [WeChatPadPro 文档](https://github.com/luolin-ai/WeChatPadPro)

## 登录微信

1. 成功启动 WeChatPadPro 后根据你的 serverip:port 访问 WeChatPadPro 的 Swagger\
   ![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/Snipaste_2025-06-09_22-30-49.png)

2. 填入 adminKey\
   ![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/Snipaste_2025-06-09_22-30-49.png)

3. 获取 token\
   \*\* try it out `/admin/GanAuthKey1` 接口 body 中的 days 改为 365 即可\
   ![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/Snipaste_2025-06-09_22-33-18.png)

等待返回拿到里面的 token 回填入上面的 token\
![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/Snipaste_2025-06-09_22-36-41.png)

5. 登录微信\
   \*\* try it out `/login/GetLoginQrCodeNew` 接口即可（和服务器是同市或者同省）\
   ![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/Snipaste_2025-06-09_22-37-40.png)

\*\* 如果是云服务器，需要填入 Proxy\
![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/login2.png)

\*\* 返回的参数中有登录二维码链接，打开扫码登录即可\
![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/login3.png)

\*\* 手机登录后看是否有 iPad 在线，如果不在线就使用, 查看扫码状态\
![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/ipadlogin.jpg)

> 没有在线的话是因为什么（这是我已经成功登录，扫码状态过期了）

![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/Snipaste_2025-06-09_22-41-05.png)

6. 记录你的 adminkey、token、wx 地址和访问地址（wxid 可以不管）

## 在 langbot 的创建机器人中填写信息

- `wechatpad_key` 填写 adminKey
- `wechatpad_url` 填写 WeChatPadPro 的地址
- `wechatpad_ws` 填写 WeChatPadPro 的 ws 地址
- `wxid` 填写该登录账号的 wxid
- `wechatpad_token` 填写 WeChatPadPro 的 token

![img.png](https://langbot.app/docs/images/zh/deploy/platforms/wechat/langbotset.png)

## 详细的 API 接口文档

如果有想要为该适配器做贡献，或者制作微信相关插件请查看 [WeChatPadPro API 文档](https://doc.apipost.net/docs/460ada21e884000?locale=zh-cn)\
里面有相关接口及其参数说明

## 常见问题

### 1. 服务无法启动

检查步骤：

```bash
# 查看服务日志
docker-compose logs

# 查看具体服务日志
docker-compose logs wechatpadpro
docker-compose logs mysql
docker-compose logs redis
```

### 2. 数据持久化

数据默认保存在以下 Docker volumes 中：

- `wechatpadpro_data`：应用数据
- `wechatpadpro_logs`：应用日志
- `redis_data`：Redis 数据
- `mysql_data`：MySQL 数据

查看数据卷：

```bash
docker volume ls | grep wechatpadpro
```

### 3. 服务重启

```bash
# 重启所有服务
docker-compose restart

# 重启单个服务
docker-compose restart wechatpadpro
```

## 维护指南

### 日常维护

1. 查看服务状态：

```bash
docker-compose ps
```

2. 查看服务日志：

```bash
docker-compose logs -f --tail=100
```

3. 备份数据：

```bash
# 备份 MySQL 数据
docker exec wechatpadpro_mysql mysqldump -u root -p123456 wechatpadpro > backup.sql
```

### 官方版本升级

1. 拉取最新镜像：

```bash
docker-compose pull
```

2. 重新部署服务：

```bash
docker-compose up -d
```

### 简化版升级

- 需要重新拉取 GitHub

```bash
git clone 
cd WeCahtPad_Docker
docker compose down
docker compose up -d
```

## 安全建议

1. 修改默认密码
   - 修改 `ADMIN_KEY`
   - 修改 MySQL 密码
   - 修改 Redis 密码

2. 限制端口访问
   - 只对必要端口开放外部访问
   - 使用防火墙限制 IP 访问

3. 定期备份
   - 备份 MySQL 数据
   - 备份应用数据

---

# 个人微信（OpenClaw）

Source: https://langbot.app/docs/zh/usage/platforms/wechat/weixin

用 LangBot 搭建个人微信 AI 机器人，将大模型接入你的微信账号。

## 简介

[OpenClaw](https://github.com/dingxiang-me/OpenClaw-Wechat) 是一个开源 AI Agent 框架。通过 OpenClaw 微信适配器，您可以将 LangBot 接入个人微信，支持单聊、流式输出、白名单控制等功能。

## 一键扫码登录（推荐）

LangBot 支持扫码一键登录微信，自动填写凭证，无需手动复制令牌。

> warning:
>
> 请确认您的手机微信版本为 最新的**8.0.69** 或以上，否则可能无法正常使用。

1. 打开 LangBot WebUI，进入**机器人 > 创建机器人**
2. 填写机器人名称，平台/适配器选择 `个人微信机器人`
3. 在下方出现的**扫码登录**区域，点击右侧的 **开始** 按钮

![选择扫码登录](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_scan_login.png)

4. 使用微信扫描弹出的二维码，手机端会提示「将新的 OpenClaw 连接到微信」，点击**继续连接**

![扫码后手机点击连接](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_scan_connect.png)

5. 授权成功后，令牌和账号标识会**自动填入**配置表单

![配置自动填入](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_config_auto_fill.png)

6. 点击**提交**，完成创建

> warning:
>
> 如果提示连接失败，请确认微信版本为 8.0.69 或以上。

### 确认登录成功

扫码成功后，手机端会进入与 ClawBot 的聊天页面。

![微信 ClawBot 聊天页面](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_05.jpg)

同时，LangBot 日志中会出现连接成功的信息，配置页面中的令牌和账号也会自动更新，表示登录成功。

![日志信息](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_06.png)
![配置页](https://langbot.app/docs/images/zh/deploy/bots/wexin/wexin_07.png)

## 开始使用

登录成功后，使用扫码账号向刚刚进入的 ClawBot 聊天页面进行对话，LangBot 自动回复。

---

# 企业微信

Source: https://langbot.app/docs/zh/usage/platforms/wecom/wecom

将企业微信接入 LangBot，为企业消息部署大模型 AI 机器人。

部署企业微信机器人接入 LangBot 。

> \- 此种接入方式为企业内部自建应用，是在企业内部使用的，若需要对外接待，请查看\[企业微信客服接入方案]\(wecomcs)。:
>
> - 企业微信回调地址需要公网IP和域名，推荐您先参照[配置 HTTP 反向代理](https://langbot.app/docs/zh/workshop/production/proxy-and-ssl.md)来配置 LangBot 回调地址。

> idea:
>
> **没有公网服务器？** [LangBot Cloud](https://space.langbot.app/cloud) 自带域名和 HTTPS，无需自行配置反向代理，开箱即用企业微信。

## 记录企业ID

打开[企业微信管理后台](https://work.weixin.qq.com/)，点击`我的企业`，记录下最下面的`企业ID`。

![Corp ID](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/03-corp-id.png)

## 创建机器人

点击`应用管理`,`自建`,` 创建应用`

![App Management](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/01-wecom-apps.png)

填写机器人基本信息：

![Create Application](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/02-create-app.png)

查看并记录机器人密钥（Secret）：

![Bot Secret](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/04-bot-secret.png)

从企业微信客户端根据提示获取。

## 开启通讯录同步权限

> \- 此配置项是为了实现 LangBot 的群发消息，具体代码位于libs/wecom\_api/api.py 。:
>
> - 目前 LangBot 仍在开发，所以未实现此配置项的相关功能。
> - 此配置项可以填写入随机字符，**不能为空**。

点击`安全与管理`,`管理工具`,`通讯录同步`；先配置可信IP，添加部署 LangBot 的服务器IP。

点击`查看secret`，记录下来，这是 contacts\_secret（通讯录同步 secret）。

![Contact Sync Secret](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/08-contact-secret.png)

## 在 LangBot 新建机器人

在 LangBot 机器人页面，点击`创建机器人`，填入名称，选择`企业微信`，此步骤只需要填入 企业ID 和 机器人密钥，以及通讯录同步 secret。

![Create WeCom Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/05-fill-in-corpid-secret.png)

点击提交，跳转到机器人编辑页面，点击启用；此时即可看到 Webhook 回调地址，复制下来：

![Webhook Callback Address](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/06-webhook-callback-address.png)

## 设置回调地址

回到企业微信的机器人管理页面，点击`接收消息`，`设置API接收`，将 LangBot 的 Webhook 回调地址填入`URL`中：

![Set API Receiver](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/07-set-api-receiver.png)

点击 Token 和 EncodingAESKey 的`随机获取`，并记录下来，**保持此页开启**。返回到 LangBot 的企微机器人配置页面，将 Token 和 EncodingAESKey 填入，点击保存。

![Save WeCom Bot](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/09-save-wecom-bot.png)

再回到**刚刚填写 Webhook 回调地址的页面**，点击保存即可配置完成；如果出现**请求URL失败**，请再三检查你的配置项填写是否正确。

## 配置应用的企业可信 IP

回到该应用到管理页，在下方找到`企业可信 IP`，添加部署 LangBot 的服务器IP。

![Corp Trusted IP](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecom/10-corp-trusted-ip.png)

点击保存即可。

## 常见问题

Q：企微上找不到机器人对话框？
A：可以到企微管理页面上该应用的详情页，点击`功能`->`发送消息`->`发消息`，选择自己账号，发送消息，即可在自己的对话框中看到机器人。

---

# 企业微信智能机器人

Source: https://langbot.app/docs/zh/usage/platforms/wecom/wecombot

用 LangBot 搭建企业微信智能机器人，将大模型对话引入你的组织。

## 一键配置（推荐）

LangBot 支持一键创建企业微信智能机器人并自动填写 BotId 和 Secret，无需手动复制粘贴。

1. 打开 LangBot WebUI，进入**机器人 > 创建机器人**
2. 填写机器人名称，平台/适配器选择 `企业微信智能机器人`
3. 在下方出现的**一键创建机器人**区域，点击右侧的 **开始** 按钮

![一键创建机器人](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_oneclick.png)

4. 使用企业微信扫描弹出的二维码，手机端会提示「请先创建智能机器人」，点击 **一键创建智能机器人**

![手机端一键创建](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_scan_create.png)

5. 授权成功后，BotId 和 Secret 会**自动填入**配置表单
6. **手动填写机器人名称**，名称需与企业微信中创建的机器人名称一致

![手动填写机器人名称](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_fill_name.png)

7. 点击**提交**，完成创建

> warning:
>
> 企业微信智能机器人**不能选择已有的机器人**进行一键配置，只能新建。如果需要使用已有机器人，请参考下方手动配置。

***

## 手动配置

### 创建机器人

首先登录[企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#/)。

![主页](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_1.png)

点击左边栏的`安全与管理`，点击`管理工具`里面的`智能机器人`。

如图:

![智能机器人](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_2.png)

点击`创建机器人`并选择`手动创建`，拉至页面最底部，点击`API模式创建`，进入页面：

![API模式创建](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_3.png)

### 长连接配置说明

#### 开启长连接 API 模式

在企业微信管理后台，进入智能机器人的配置页面，开启「API 模式」并选择「长连接」方式：

![长连接方式创建](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_9.png)

#### 获取凭证

开启长连接 API 模式后，需要获取以下凭证用于建立连接：

| 凭证     | 说明                   |
| ------ | -------------------- |
| BotID  | 智能机器人的唯一标识，用于标识机器人身份 |
| Secret | 长连接专用密钥，用于身份校验       |

> warning:
>
> 注意：
>
> - Secret 是长连接专用的密钥，与设置接收消息回调地址模式的 Token/EncodingAESKey 不同
> - 请妥善保管 Secret，避免泄露
> - 模式切换影响：API 模式只能选择一种方式（长连接或设置接收消息回调地址），切换到「设置接收消息回调地址」模式会导致现有长连接失效；反之，从「设置接收消息回调地址」切换到「长连接」模式后，原有的回调地址将不再生效

#### 配置机器人

启动 LangBot 主程序，适配器选择 `企业微信智能机器人`，填写配置项，
将长连接中的botid和secret以及机器人名称填入，点击保存并使用

> 其中机器人名称要与新建的机器人名称一样，不然群聊会不回复

![长连接配置](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_10.png)

### 使用url回调配置说明

点击随机获取 Token 和 EncodingAESKey，然后填写上方的机器人基本信息，**注意设置可见范围**。

![参数获取](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_11.png)

点击左边栏的`我的企业`，保存最下方的企业ID。

#### 配置回调地址

启动 LangBot 主程序，适配器选择 `企业微信智能机器人`，填写配置项，
其中，令牌为 Token，消息加解密密钥为 EncodingAESKey，机器人ID填写入xxx（或者随便填写，后续会改），填写之后点击
`保存`，并`启用`机器人。

![企业微信智能机器人适配器](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_4.png)

在 LangBot 主页中，启用并选择对应的机器人，点击进入配置页面，复制其中的 Webhook 回调地址

> info:
>
> 推荐您先参照[配置 HTTP 反向代理](https://langbot.app/docs/zh/workshop/production/proxy-and-ssl.md)来配置 LangBot 回调地址。

![Webhook 回调地址](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_8.png)

返回企业微信机器人配置页面将复制的webhook地址填写到`URL回调`中。若创建成功，则会跳转至详情页面，若出现`请求URL失败`字样，请再三检查上述操作是否一一完成。

创建成功之后的详情页：
![创建成功](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_5.png)

复制企业微信机器人详情页的`Bot ID`和机器人的名称，回到LangBot管理页面，将部署的智能机器人的机器人Id改为复制的ID，并填入机器人名称，重新启动机器人。

### 开启流式

针对部分本地搭建或者不支持流式的模型新增流式开关

![流式开关](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_12.png)

### 开始使用

进入企业微信，点击 `➕`,如图：

![添加机器人](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_6.png)

点击`企业创建的`,选择创建的机器人，进入聊天界面。

同理，若想邀请机器人进入群聊，那么点击群聊的添加人员，在其中添加机器人。

### 效果图

![效果图1](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecombot/wecombot_7.png)

---

# 企业微信客服

Source: https://langbot.app/docs/zh/usage/platforms/wecom/wecomcs

用 LangBot 配置企业微信客服，提供 AI 驱动的客服对话。

> 本文详细讲述 LangBot 部署到企业微信客服号的过程，此功能可以将客服号与普通微信进行对话。若只需要在企业微信内部使用，请参考\[企业微信内部应用实现]\(wecom)。:
>
> **部署企业微信客服号需要企业资质**，具体查看[企业微信客服号接入指南](https://developer.work.weixin.qq.com/document/path/94638)，并且根据此文档提供对应的企业资质证明。

## 效果图

![效果图](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/wecomcs_01.jpg)

## 部署企业微信客服

#### 配置企业微信客服页面

打开[企业微信客服后台](https://kf.weixin.qq.com/kf)，登录之后进入，点击`企业信息`，获取`企业ID`。

![主页](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/wecomcs_03.png)

保存企业ID，然后点击`开发配置`，点击`开始使用`，进入之后随机获取 Token，EncodingAESKey，随后将此三项填写入 LangBot 配置页中，Secret 随便填写,如图：

![connect](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/connect_to_langbot.png)

点击 LangBot 配置页中的提交，启用机器人，复制 WebHook回调地址，填写入企业微信客服后台中的 URl （记得改成自己的 ip 或者域名），点击保存，如果可以保存成功，那么说明可以正常连接。

> idea:
>
> **配置域名太麻烦？** [LangBot Cloud](https://space.langbot.app/cloud) 自带域名和 HTTPS，无需自行配置，开箱即用。

复制页面中的 Secret，然后打开新建好的 LangBot 企业微信客服机器人，填写入新的 Secret，重新启动。

回到企业微信客服配置页面，点击客服账号，创建客服账号，即可使用。

---

# 微信公众号

Source: https://langbot.app/docs/zh/usage/platforms/wxoa

用 LangBot 搭建微信公众号 AI 机器人，将大模型接入你的微信公众号。

部署微信公众号机器人接入 LangBot 。

## LangBot 微信公众号接入模式

目前，LangBot 提供两种方式接入微信公众号：

1. **传统收发消息模式**
   - 公众号要求请求必须在 **15 秒内** 处理完成，超时的 AI 生成内容将无法发送。
   - 当 AI 生成内容超时发生后，LangBot 会在控制台打印请求超时信息。

2. **“发送任意文字回复消息”模式**
   - 该方法可突破 **15 秒** 限制，但 **过长的文本** 可能无法成功发送。
   - 使用此方法时，给公众号发消息，公众号会回复“AI正在思考中，请发送任意内容获取回答”，此时，需要发送任意内容获取回答。

如需更复杂的功能，请联系 **LangBot 团队** 进行定制化支持。

## 创建机器人

进入[微信公众平台](https://mp.weixin.qq.com/)，如果已经有公众号账号，那么直接扫码登录，进入控制台。
如果之前没有注册过公众号，那么点击立即注册，选择 `公众号`，依次填写信息，进入控制台。控制台是这样的：
![控制台页面](https://langbot.app/docs/images/zh/deploy/bots/wxoa/wxoa1.png)

## 设置回调地址

> idea:
>
> **微信公众号需要公网域名和 HTTPS。** 如果你没有服务器，[LangBot Cloud](https://space.langbot.app/cloud) 自带域名解析，注册即可直接使用。

### 获取配置项

点击`设置与开发`，`开发接口管理`，出现这样的页面：
![设置开发项](https://langbot.app/docs/images/zh/deploy/bots/wxoa/wxoa2.png)

记录下来`开发者ID（AppID）`，`开发者密码（AppSecret）`，并将部署 LangBot 的服务器添加入`IP白名单`。

### 为 LangBot 设置反向代理

由于微信公众号的只支持http（80端口），https（443端口），请根据文档[配置 HTTP 反向代理和 SSL](https://langbot.app/docs/zh/workshop/production/proxy-and-ssl.md) 操作。

### 保存回调地址

点击设置服务器配置，输入`Token`，`EncodingAESKey`，并将消息加解密方式改为`安全模式`。

至此，打开 LangBot Webui 页面，创建一个新的机器人，将获取到的四个配置项( AppID , AppSecret , token , EncodingAESKey )填入

![设置开发项](https://langbot.app/docs/images/zh/deploy/bots/wxoa/connect_to_langbot.png)

在配置项中，`Mode`选项为选择的接入模式，其中默认为`drop`，`drop` 为传统收发消息模式，`passive` 为发送任意文字获取回复模式。

`LoadingMessage`选项为加载信息，可以更改为其他内容，仅在模式为`passive`下有效。将 `enable` 设置为 `true` 。

填写成功后，在 LangBot 主页中，启用并选择对应的机器人，点击进入配置页面，复制其中的 Webhook 回调地址，返回微信公众号机器人配置页面，填写到`URL`。比如 URL 填写为`https://your_domain_name/bots/xxxxx`，其中的 `your_domain_name` 就是 Caddy 中填写的域名。点击保存。如果可以保存成功，那么意味着部署成功。如果出现**系统发生错误，请稍后重试**，那么请重新检查以上配置内容是否填写正确。

---

# 沙箱配置

Source: https://langbot.app/docs/zh/usage/sandbox/config

配置 LangBot Box Runtime，选择 Docker、nsjail、E2B，或显式启用不具备隔离能力的 Host 后端。

Box 由 LangBot 主进程配置，Box Runtime 负责实际执行。常规部署只需要选择后端、设置工作目录和安全预设。Docker、nsjail 和 E2B 提供沙箱环境；Host 后端则直接在 Box Runtime 所在机器上执行命令。

> info:
>
> 本页所有 `box.*` 配置都写在 `data/config.yaml` 中。配置文件的位置和加载机制详见[系统环境设置](https://langbot.app/docs/zh/deploy/settings.md)。

## 推荐配置

```yaml
box:
  enabled: true
  backend: 'local'        # 自动从 Docker / Nsjail 里选可用的
  local:
    profile: 'default'
    host_root: './data/box'
    skills_root: 'skills'
  docker:
    cpu_limit_enabled: true
```

- `enabled`：沙箱总开关。设为 `false` 时，沙箱内置工具、Skill 添加/编辑、stdio MCP 托管等依赖 Box 的能力都不可用。
- `backend`：见下文「后端选择」。
- `local.profile`：安全预设，控制网络、挂载和资源限制。
- `local.host_root`：主机上的沙箱工作目录，会映射为沙箱内的 `/workspace`。
- `local.skills_root`：Skill 包目录；相对路径解析到 `host_root` 下，默认 `host_root/skills`。
- `docker.cpu_limit_enabled`：是否为 Docker 沙箱容器启用 CPU 限制；设为 `false` 时不传 `docker run --cpus`，内存和 PID 限制仍然保留。

> info:
>
> Skills 只从 Box Runtime 管理的 skill store 加载。Box Runtime 或后端不可用时 Skill 列表为空，新增 / 编辑 / `register_skill` 都不可用；不会回退扫描 `data/skills/`。

## 后端选择

Box 可以跑在**本机容器**、**云端沙箱**，也可以直接使用 **Box Runtime 主机进程**。`box.backend` 选择走哪一种：

| `backend`   | 跑在哪            | 行为                                              |
| ----------- | -------------- | ----------------------------------------------- |
| `local`（默认） | 本机容器           | 自动从 Docker / Nsjail 里选可用的（Docker 优先）            |
| `docker`    | 本机容器           | 强制使用 Docker，需要 Docker daemon                    |
| `nsjail`    | 本机容器           | 强制使用 Nsjail（仅 Linux），不支持自定义镜像                   |
| `e2b`       | 云端             | 使用 [E2B](https://e2b.dev) 云沙箱，需要 API Key        |
| `host`      | Box Runtime 主机 | 直接以 Box Runtime 用户权限启动本机进程；仅支持 POSIX 系统且需要 `sh` |

`local` 是「自动选择」的简写，不是和 `docker`/`nsjail` 平级的第四种后端。它只会尝试 Docker 和 Nsjail，**永远不会自动选择 `host`**。本机后端使用 `box.local.*` 中的工作区配置；云端后端使用 `box.e2b.*`。

> warning:
>
> `host` **不是沙箱**。命令拥有 Box Runtime 用户的主机权限，没有文件系统、进程、网络、namespace、cgroup、rootfs 或镜像隔离，也不保证只读挂载和硬磁盘配额。它只适合单用户、可信输入的本地开发环境；不要用于公开服务、共享主机或执行不受信任的代码。

> info:
>
> `backend` 是强制值。设为 `docker` 时如果 Docker 不可用，**不会**自动回退到 Nsjail 或 E2B——只有 `local` 会自动 fan-out。
>
> 也可以用环境变量 `BOX__BACKEND` 覆盖配置（优先级高于 `config.yaml`）。

## 安全预设

`box.local.profile` 控制 Docker / Nsjail 本机沙箱后端的网络、挂载和资源限制：

| Profile            | 网络     | 挂载 | 资源   | 建议场景           |
| ------------------ | ------ | -- | ---- | -------------- |
| `default`          | 关闭     | 读写 | 默认限制 | 默认选择           |
| `offline_readonly` | 关闭     | 只读 | 更严格  | 读取不可信文件        |
| `network_basic`    | 开启基础网络 | 读写 | 默认限制 | 需要访问 API 或下载依赖 |
| `network_extended` | 开启完整网络 | 读写 | 更宽松  | 开发、调试、复杂任务     |

优先使用最小权限：不需要网络就用 `default` 或 `offline_readonly`；只把必要目录加入 `allowed_mount_roots`。

> info:
>
> Host 后端不执行这些隔离策略。即使配置了 profile、CPU / 内存 / PID 限制、只读 rootfs 或网络关闭，主机进程也不受这些沙箱边界保护。

## 本机工作区配置（box.local.\*）

Docker、Nsjail 和 Host 共用工作区路径配置；隔离与资源配置仅在对应沙箱后端能够实施时生效：

| 配置项                         | 默认值           | 说明                                              |
| --------------------------- | ------------- | ----------------------------------------------- |
| `local.profile`             | `default`     | Docker / Nsjail 安全预设；Host 不提供对应隔离               |
| `local.image`               | 空             | Docker 后端的自定义镜像；空 = 用 profile 默认                |
| `local.host_root`           | `./data/box`  | 主机工作目录基础路径，映射为沙箱内 `/workspace`                  |
| `local.default_workspace`   | 空             | 默认工作空间名；空 = `<host_root>/default`               |
| `local.skills_root`         | `skills`      | Skill 包目录；相对路径解析到 `host_root` 下                 |
| `local.allowed_mount_roots` | `[host_root]` | Agent 可请求挂载的主机目录白名单                             |
| `local.workspace_quota_mb`  | `null`        | 工作区磁盘配额（MB），`null` = 用 profile 默认；Host 不提供硬配额保证 |
| `default_memory_mb`         | `1536`        | MCP stdio 进程内存上限（MB）；Host 无法用 cgroup 强制执行       |

## Host 后端（可信本地开发）

Host 是依赖最少的本地选项，不需要安装 Docker 或 Nsjail。它必须显式选择：

```yaml
box:
  enabled: true
  backend: 'host'
  local:
    host_root: './data/box'
    skills_root: 'skills'
```

WebUI、Agent 工具和调用方式不变：仍然使用相同的会话作用域、`exec/read/write/edit/glob/grep`、Skills 和 stdio MCP。区别只在执行层：

- `/workspace`、`workdir` 和 Skill 挂载路径会转换为 Box Runtime 主机上的实际路径。
- 子进程只继承最小的 PATH、语言和终端环境，再叠加请求中显式传入的变量；LangBot / Box 控制密钥不会自动进入子进程环境。这能减少意外泄露，但不构成文件系统隔离。
- `exec` 和托管进程在独立进程组中启动；超时、取消、停止、删除会话和 Runtime 关闭都会终止对应进程树。
- 空闲回收、托管进程保活和 `persistent` 规则与其他后端一致。
- 状态接口会返回 `unsafe_direct_execution: true`，便于运维侧识别当前没有沙箱隔离。

> info:
>
> Host 指的是 **Box Runtime 所在的环境**。LangBot 直接启动本地 stdio Box Runtime 时，它是当前机器；如果 Box Runtime 本身运行在容器里，命令会直接运行在那个容器中，而不是自动穿透到物理宿主机。

Host MVP 支持带 `sh` 的 POSIX 系统（Linux / macOS）。Windows 请先使用 WSL；原生 Windows 进程后端尚未支持。

外部 WebSocket Box Runtime 使用 Host 时，必须在 LangBot 与 Box Runtime 两侧设置相同的强随机 `LANGBOT_BOX_CONTROL_TOKEN`。本地自动管理的 stdio Box Runtime 不需要额外配置该令牌。启用了托管沙箱 admission 的 Cloud 环境仍会按隔离能力和指定后端进行校验，Host 不会绕过这些检查。

## Box 沙箱内存配置

`box.default_memory_mb` 控制每个 stdio 模式 MCP 服务进程的 nsjail cgroup 内存上限。

Host 后端不提供 cgroup 内存隔离，因此该值不能限制 Host 上的 MCP 进程。

| 配置项                     | 说明             | 默认值  |
| ----------------------- | -------------- | ---- |
| `box.default_memory_mb` | MCP 进程内存上限（MB） | 1536 |

可通过 config.yaml 或环境变量 `BOX__DEFAULT_MEMORY_MB` 设置。

**为什么需要调整：**

- Node.js 类 MCP（npx/bunx 启动）：V8 引擎 + WebAssembly 模块初始化需要较多内存，建议 ≥ 1536 MB
- Python 类 MCP（uvx 启动）：通常 512 MB 已足够，但用默认值也没问题
- 内存不足时进程会被强制终止（return\_code=137），在日志里表现为「Box managed process exited unexpectedly」

**单个 MCP 服务覆盖：** 在 MCP 配置的 `box.memory_mb` 字段单独设置，优先级高于全局默认值。

## Docker 后端配置（box.docker.\*）

| 配置项                        | 默认值    | 说明                                                                                         |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| `docker.cpu_limit_enabled` | `true` | 仅 Docker 后端生效。设为 `false` 时，Docker 沙箱容器启动时不会附带 `--cpus`；`--memory` 和 `--pids-limit` 仍会照常应用。 |

## 云端后端配置（box.e2b.\*）

设为 `backend: 'e2b'` 后配置：

| 配置项            | 默认值 | 说明                                 |
| -------------- | --- | ---------------------------------- |
| `e2b.api_key`  | 空   | E2B API Key，也可用 `E2B_API_KEY` 环境变量 |
| `e2b.api_url`  | 空   | 自建 E2B 服务地址，也可用 `E2B_API_URL`      |
| `e2b.template` | 空   | 默认 E2B 模板 ID                       |

E2B 不需要本机 Docker 或 Nsjail，每次执行都走远程沙箱。

## Docker Compose 部署

Docker Compose 部署时，沙箱配置写在 `langbot` 服务上。LangBot 启动后会通过 INIT RPC 把配置下发给 `langbot_box`。

```yaml
services:
  langbot_box:
    image: rockchin/langbot:latest
    container_name: langbot_box
    profiles: ["box", "all"]
    volumes:
      - ${LANGBOT_BOX_ROOT:-${PWD}/data/box}:${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - /var/run/docker.sock:/var/run/docker.sock
    command: ["uv", "run", "--no-sync", "-m", "langbot_plugin.cli.__init__", "box"]

  langbot:
    image: rockchin/langbot:latest
    volumes:
      - ./data:/app/data
    environment:
      - BOX__LOCAL__HOST_ROOT=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__LOCAL__SKILLS_ROOT=skills
      - BOX__LOCAL__ALLOWED_MOUNT_ROOTS=${LANGBOT_BOX_ROOT:-${PWD}/data/box}
      - BOX__DOCKER__CPU_LIMIT_ENABLED=${LANGBOT_BOX_DOCKER_CPU_LIMIT_ENABLED:-true}
```

> warning:
>
> `langbot_box` 需要访问 Docker daemon。只在受信任环境中挂载 `docker.sock`；并保持 Box 根目录在主机和 `langbot_box` 容器内路径一致。

如需 LangBot 连接外部 Box Runtime（例如远程主机），用 `box.runtime.endpoint` 指定 URL：

```yaml
box:
  runtime:
    endpoint: 'ws://192.168.1.10:5410'
```

## 环境变量

| 环境变量                              | 写入配置                                 |
| --------------------------------- | ------------------------------------ |
| `BOX__ENABLED`                    | `box.enabled`                        |
| `BOX__BACKEND`                    | `box.backend`                        |
| `BOX__LOCAL__PROFILE`             | `box.local.profile`                  |
| `BOX__LOCAL__IMAGE`               | `box.local.image`                    |
| `BOX__LOCAL__HOST_ROOT`           | `box.local.host_root`                |
| `BOX__LOCAL__DEFAULT_WORKSPACE`   | `box.local.default_workspace`        |
| `BOX__LOCAL__SKILLS_ROOT`         | `box.local.skills_root`              |
| `BOX__LOCAL__ALLOWED_MOUNT_ROOTS` | `box.local.allowed_mount_roots`，逗号分隔 |
| `BOX__LOCAL__WORKSPACE_QUOTA_MB`  | `box.local.workspace_quota_mb`       |
| `BOX__DEFAULT_MEMORY_MB`          | `box.default_memory_mb`              |
| `BOX__DOCKER__CPU_LIMIT_ENABLED`  | `box.docker.cpu_limit_enabled`       |
| `BOX__E2B__API_KEY`               | `box.e2b.api_key`                    |
| `BOX__E2B__API_URL`               | `box.e2b.api_url`                    |
| `BOX__E2B__TEMPLATE`              | `box.e2b.template`                   |

> info:
>
> 不要在 `langbot_box` 服务上设置 `BOX__*` 或 `LANGBOT_BOX_*` 变量；这些变量不会被 Box Runtime 直接读取——它的配置由 LangBot 通过 INIT RPC 下发。

---

# 沙箱 (Sandbox)

Source: https://langbot.app/docs/zh/usage/sandbox/readme

LangBot Box Runtime 为内置 Agent 提供命令执行与文件工具，并可选择沙箱或可信本机后端。

Box Runtime 给内置 Agent 一个统一的执行环境：跑命令、读写文件、运行长驻进程。日常 Agent 应用（数据处理、文件操作、运行用户代码、托管 stdio MCP）都依赖它。Docker、nsjail 和 E2B 后端提供沙箱隔离；显式选择的 Host 后端用于可信本地开发，不提供隔离。

启用 Box 后，内置 Agent 会自动获得六个工具，无需在流水线里逐项开启。

## 内置工具

| 工具      | 用途              |
| ------- | --------------- |
| `exec`  | 在沙箱内执行 Shell 命令 |
| `read`  | 读取工作区文件         |
| `write` | 创建或覆盖文件         |
| `edit`  | 字符串替换式修改文件      |
| `glob`  | 按 glob 模式查找文件   |
| `grep`  | 按正则搜索文件内容       |

`exec` 在所选 Box 后端中运行；其余五个直接读写映射到 `/workspace` 的工作区目录。选择 Host 时，命令也直接运行在 Box Runtime 主机上。

> info:
>
> 这些工具面向内置 Agent。使用 Dify、n8n、Langflow、Coze 等外部运行器时，请使用对应平台自己的工具机制。

## 沙箱作用域

在流水线 AI 配置中可选择沙箱在不同消息间如何共享。默认"每个会话"足够大多数场景使用。

| 作用域      | 模板                                                | 共享范围       |
| -------- | ------------------------------------------------- | ---------- |
| 全局       | `{global}`                                        | 所有用户共用一个沙箱 |
| 每个会话（默认） | `{launcher_type}_{launcher_id}`                   | 同一群/私聊共用   |
| 每个用户     | `{launcher_type}_{launcher_id}_{sender_id}`       | 群里每位成员独立   |
| 每个对话     | `{launcher_type}_{launcher_id}_{conversation_id}` | 按对话隔离      |
| 每条消息     | `{query_id}`                                      | 完全无状态      |

> warning:
>
> 同一作用域内的命令共享文件系统状态。需要独立工作区请选择"每条消息"。作用域是会话复用规则，不是安全边界；Host 后端即使使用不同作用域，也没有主机级隔离。

## 生命周期

| 情况                        | 行为           |
| ------------------------- | ------------ |
| 空闲超过 5 分钟                 | 自动清理         |
| 有 Box 托管进程（如 stdio MCP）在跑 | 不清理，进程结束后才释放 |
| 配置 `persistent: true`     | 永不自动清理       |

这些生命周期行为也适用于 Host。回收时会终止该会话的托管进程树并移除临时会话目录；映射到 `box.local.host_root` 的持久工作区不会被当作临时目录删除。Runtime 关闭或显式删除会话时也会执行清理。

## 快速开始

可信的 Linux / macOS 本地开发可以直接选择 Host，不需要安装 Docker：

1. **写入 `config.yaml`**：
   ```yaml
   box:
     enabled: true
     backend: 'host'
     local:
       host_root: './data/box'
   ```
2. **启动 LangBot**：Box Runtime 自动启用
3. **在流水线里**选择内置 Agent + 支持函数调用的模型

之后 Agent 会自动获得六个工具。详细配置见[沙箱配置](https://langbot.app/docs/zh/usage/sandbox/config.md)。

> warning:
>
> Host 会以 LangBot / Box Runtime 用户的权限直接执行命令，只能处理可信输入。需要执行不受信任的代码时，请将 `backend` 改为 `local`（自动选择 Docker / Nsjail）、`docker`、`nsjail` 或 `e2b`。

## 关闭 Box

设置 `box.enabled: false`。所有依赖沙箱的能力（内置工具、Skill 创建/编辑/激活、stdio MCP）会一并停用；http/sse 模式的 MCP 不受影响。

## 下一步

- [沙箱配置](https://langbot.app/docs/zh/usage/sandbox/config.md) — 后端、安全预设、挂载、环境变量
- [运行时与扩展关系](https://langbot.app/docs/zh/usage/sandbox/runtime-relationships.md) — 沙箱、Skills、MCP、插件如何分工

---

# 运行时与扩展关系

Source: https://langbot.app/docs/zh/usage/sandbox/runtime-relationships

理解 LangBot 运行时与扩展：Box Runtime、沙箱后端与 MCP 服务器如何协同工作。

LangBot 里同时存在**插件、MCP、Skills、沙箱**四种扩展机制，容易混淆。本页帮你区分它们的职责和适用场景。

## 一句话区分

- **Box 执行环境**：让 Agent 跑命令、读写文件；是否隔离取决于所选后端
- **Skills**：按需激活的指令包，给 Agent 临时增加一段专业工作流
- **MCP Server**：接入外部工具服务
- **插件**：长期运行的扩展进程，可带配置页、事件监听、知识库

## 对照表

| 能力         | 提供方                                  | 给 Agent 的形式                               | 何时使用                      |
| ---------- | ------------------------------------ | ----------------------------------------- | ------------------------- |
| Box 执行环境   | Box Runtime                          | 直接挂上 `exec/read/write/edit/glob/grep` 六件套 | Agent 要执行代码、读写文件          |
| Skills     | Box Runtime skill store              | Agent 调 `activate` 后，指令通过 Tool Result 注入  | 想给 Agent 加一段流程/模板/脚本，按需触发 |
| MCP Server | LangBot MCP Loader（stdio 模式由 Box 托管） | 工具直接进入可用工具列表                              | 接入已有的 MCP 服务              |
| 插件         | Plugin Runtime                       | 由插件系统暴露能力                                 | 长期能力、需要配置页/事件监听/知识库组件     |

## 流水线绑定

Skills、MCP Server、插件都属于**流水线扩展**。在 WebUI 安装/创建后，还要在流水线扩展配置里决定启用范围：

- 启用全部扩展，或
- 只绑定指定的扩展

Skills 的绑定决定 Agent **能看到哪些技能**（影响 `<available_skills>` 列表）。具体技能内容只有 Agent 调用 `activate` 后才会注入。

## 后端与隔离边界

Box API、Agent 工具、会话作用域、生命周期、Skills 和 stdio MCP 托管在各后端上的使用方式一致，但安全属性不同：Docker、nsjail 和 E2B 提供各自的沙箱边界；Host 直接使用 Box Runtime 主机进程，只用于可信本地开发。选择 Host 不会改变 WebUI，也不会让不同会话获得主机级隔离。

## 排障入口

| 现象                            | 优先检查                                                      |
| ----------------------------- | --------------------------------------------------------- |
| Agent 没有 `exec/read/write` 工具 | `box.enabled`、后端是否可用、流水线是否用内置 Agent                       |
| Skill 列表为空                    | Box Runtime 状态、`box.local.skills_root`、流水线绑定              |
| stdio MCP 启动失败                | Box Runtime 状态、MCP 命令和环境变量、启动超时                           |
| Docker 部署沙箱启不来                | `langbot_box` 是否挂载 `docker.sock`、Box 根目录路径是否一致            |
| 文件读写失败                        | `box.local.host_root`、`box.local.allowed_mount_roots`     |
| 后端选择不生效                       | 确认 `BOX__BACKEND` 设在 `langbot` 服务上，不是 `langbot_box`       |
| Host 后端不可用                    | 确认系统为 POSIX 且 `PATH` 中存在 `sh`；Windows 使用 WSL              |
| 外部 Host Box 连接被拒绝             | LangBot 与 Box Runtime 两侧设置相同的 `LANGBOT_BOX_CONTROL_TOKEN` |

> info:
>
> 沙箱内置工具和 Skills 当前面向内置 Agent。外部运行器（Dify、n8n、Langflow、Coze 等）应使用各自平台的工具和执行机制。

---

# 技能 (Skills)

Source: https://langbot.app/docs/zh/usage/skills/readme

在 LangBot 中使用技能（Skills），按需加载专业知识，扩展 AI Agent 而不撑爆上下文。

Skill 是一个**按需激活**的指令包：用户描述匹配时，Agent 调用 `activate` 工具把这个技能的指令拉进上下文，然后按指令完成任务。未激活的技能不占用上下文。

适合给 Agent 加一段**专业流程、模板或脚本**——比如"分析 Python 项目"、"PDF 表单填充"、"代码评审"——而不必每个对话都把指令塞进 System Prompt。

## 与插件、MCP 的区别

| 你想做的事               | 用这个        |
| ------------------- | ---------- |
| 按需触发的一段工作流（可带脚本、模板） | Skill      |
| 接入已有的 MCP 工具服务      | MCP Server |
| 长期能力，需要配置页、事件、知识库   | 插件         |

详见[运行时与扩展关系](https://langbot.app/docs/zh/usage/sandbox/runtime-relationships.md)。

## 安装技能

> info:
>
> 技能依赖沙箱：`box.enabled` 为 `true` 且 Docker / Nsjail / E2B 至少一个可用时，才能安装、激活和编辑技能。详见[沙箱配置](https://langbot.app/docs/zh/usage/sandbox/config.md)。

### 从 LangBot Space（首选）

[LangBot Space](https://space.langbot.app) 是 LangBot 的官方市场，已上架多种技能。在 WebUI 的 Skills 页面浏览并一键安装，无需自己编写 `SKILL.md` 或准备资源文件。

适合大多数场景。需要自定义流程再走下面的方式。

### 自己创建技能

**WebUI** — Skills 页面新建、上传 zip 包、从 GitHub 导入。

**沙箱 + `register_skill`**：

1. 在沙箱 `/workspace` 下准备好目录和 `SKILL.md`
2. 让 Agent 调用 `register_skill(path="/workspace/my-skill")`

两种方式都会写入 Box Runtime 管理的 skill store。

## 在流水线启用

技能装好之后，还要在流水线扩展配置里决定 Agent 能看到哪些：

- 开启"启用所有技能"，或
- 只绑定指定技能

绑定只影响 `<available_skills>` 列表（即 Agent 能从哪些技能里挑），完整指令永远等 `activate` 被调用后才注入。

## 编写 SKILL.md

技能就是一个目录加一个 `SKILL.md`。frontmatter 写元数据，正文是 Agent 激活后会收到的指令：

```markdown
---
name: code-reviewer
display_name: 代码评审助手
description: 审查代码并给出改进建议；用户提到 review、评审、代码改进时触发
---

## 执行步骤

1. 用 `read` 浏览相关文件
2. 检查可读性、潜在 bug、安全问题
3. 给出按优先级排序的改进建议
```

LangBot 当前读取以下三个字段：

| 字段             | 必需     | 说明                      |
| -------------- | ------ | ----------------------- |
| `name`         | 创建/注册时 | 唯一标识，1–64 字符            |
| `description`  | 强烈建议   | Agent 用它判断何时激活——越具体越能选中 |
| `display_name` | 否      | UI 显示名                  |

`description` 是 Agent 挑技能的唯一依据，要写清楚**功能、适用场景、可能的触发关键词**。

完整规范见 [agentskills.io](https://agentskills.io/home)。其它字段（`license`、`metadata` 等）可保留供未来兼容，当前不会被读取。

**带资源的技能**在 `SKILL.md` 同级放 `scripts/`、`templates/` 等目录，激活后 Agent 通过 `/workspace/.skills/{skill-name}/` 访问。

### Agent 可用的工具

| 工具               | 用途                               |
| ---------------- | -------------------------------- |
| `activate`       | Agent 判断匹配时自动调用，把 SKILL.md 拉进上下文 |
| `register_skill` | 把沙箱里准备好的目录注册为新技能                 |

## 常见问题

| 现象                  | 检查项                                                  |
| ------------------- | ---------------------------------------------------- |
| 技能列表为空              | `box.enabled`、Box Runtime 状态、`box.local.skills_root` |
| Agent 不激活技能         | `description` 是否具体、流水线是否绑定、模型是否支持函数调用                |
| 激活后找不到文件            | 文件需在 Skill 包内，路径是 `/workspace/.skills/{skill-name}/` |
| `register_skill` 报错 | 路径必须在 `/workspace` 下，目录或两层内子目录需含 `SKILL.md`          |

> info:
>
> Skills 当前面向内置 Agent，依赖函数调用和沙箱后端。外部运行器（Dify、n8n、Langflow、Coze 等）请使用各自平台的等价机制。

---

# 接入 302.AI 的模型

Source: https://langbot.app/docs/zh/workshop/302ai-integration

打开 WebUI 页面，添加模型时选择[302.AI](https://share.302ai.cn/SuTG99)即可

![model](https://langbot.app/docs/images/zh/workshop/302ai-integration/model.png)

---

# 实现一个消息平台适配器

Source: https://langbot.app/docs/zh/workshop/impl-platform-adapter

本文章将以`aiocqhttp`适配器为例，讲解如何为 LangBot 实现一个新的消息平台适配器，以便接入 WhatsApp、Discord 等新的消息平台协议。

## 注册

```text
新增一个消息平台适配器，例如：接入 WhatsApp、Discord 等。

- 基类：`pkg.platform.adapter.MessageSourceAdapter`
- 装饰器：`pkg.platform.adapter.adapter_class(name: str)`
- 参考实现：`pkg.platform.sources/`
```

我们实现一个消息平台适配器，本质上就是实现一个继承于`基类`的类，并使用`装饰器`进行注册。最后在运行阶段供用户选择并使用。

### 贡献到主仓库

在 `pkg/platform/sources/` 目录下新建一个 `aiocqhttp.py` 文件：

```python
from .. import adapter

@adapter.adapter_class("aiocqhttp")
class AiocqhttpAdapter(adapter.MessageSourceAdapter):
    pass
```

同时在 `pkg/platform/manager.py` 的第40行导入此模块：

```python
        from .sources import nakuru, aiocqhttp, qqbotpy
```

最后参考其他适配器的清单文件，编写自己的清单文件。

## 事件、消息转换器

消息平台适配器，主要的工作就是`接收消息平台协议的事件，将其转换成LangBot的格式`，传递给核心组件，LangBot 核心组件处理完后，将需要回复的内容传递给消息平台适配器，消息平台适配器再`将内容转换成平台协议的格式，发送给消息平台`。

下图展示了两种情况的处理模式：消息平台协议无 SDK、有成熟 SDK。第一种情况我们需要根据消息平台协议的文档，自行实现连接管理、网络格式数据转换成 LB 消息 Python 对象。第二种情况，消息平台有成熟的 SDK，我们只需要根据 SDK 的文档，调用 SDK 的 API 创建连接，注册事件监听器，并实现消息转换器。

![alt text](https://langbot.app/docs/images/zh/workshop/impl-platform-adapter/workshop_impl_platform_adapter_01.png)

在`pkg.platform.sources.aiocqhttp`文件里，我们可以看到不只有`AiocqhttpAdapter`，还有`class AiocqhttpMessageConverter(adapter.MessageConverter):` 和 `class AiocqhttpEventConverter(adapter.EventConverter):`。

- `MessageConverter` 用于进行 LangBot 消息和平台消息的互相转换。
- `EventConverter` 用于进行 LangBot 事件和平台事件的互相转换。

TBC...

---

# MCP 生态详解

Source: https://langbot.app/docs/zh/workshop/mcp-details

[MCP协议](https://modelcontextprotocol.io/) 是一种描述应用程序与 LLM 交互的协议，目前已经被多种产品采用。LangBot 可以作为 MCP Client 接入 MCP Server，大量扩展工具供 LLM 在与用户对话时使用。

## 寻找 MCP Server

要在 LangBot 使用 MCP 工具，需要找到已有的 MCP Server 并接入。\
市面上有两种类型的 MCP Server：

- 基于 node 或 python 实现的可执行文件，通过 `stdio`（标准输入输出）与 LangBot 通信
- 基于 http 协议的 web 服务，通过 http 协议与 LangBot 通信

> \- 可以到 \[MCP Server 列表]\(https\://github.com/punkpeye/awesome-mcp-servers) 查看已有的 MCP Server。:
>
> - 在线托管的 MCP Server 可以到 [Composio MCP](https://mcp.composio.dev/) 查找。
> - 自行编写 MCP Server 可以参考 [MCP 协议文档](https://modelcontextprotocol.io/quickstart/server) 和 [MCP Server 示例](https://modelcontextprotocol.io/examples)。

## 配置 MCP Server

查看 [系统设置文档](https://langbot.app/docs/zh/deploy/settings.md)

配置完成后即可在聊天中通过`!func`命令查看已经注册的 MCP 工具，在与支持 Function Calling 的模型对话时，LangBot 会自动调用 MCP 工具。

---

# 网络配置详解

Source: https://langbot.app/docs/zh/workshop/network-details

> info:
>
> 若您的 LangBot 实例需要连接其他在容器中运行的服务（如 Ollama），也可以参考以下配置，自行替换`消息平台`为`您要连接的服务`。

LangBot 和部分消息平台均可采用 Docker 部署，以下是四种情况下的网络配置详解。

## LangBot 和消息平台均运行在 Docker 容器中

如果消息平台（NapCat/Lagrange）和 LangBot 均使用 Docker 启动，那么你需要配置 Docker 的网络连接。

新建一个网络：

```bash
docker network create langbot-network
```

在 LangBot 目录的 `docker-compose.yaml` 文件中添加网络配置(添加到 `services.langbot` 字段下，并在 `networks` 字段下添加 `langbot-network` 网络配置)：

```yaml
services:
  langbot:
    ...
    networks:
      - langbot-network
    ...

networks:
  langbot-network:
    external: true
```

然后在消息平台的 `docker-compose.yaml` 文件中添加同样的网络配置（如果是直接 docker run 命令启动的，请在启动命令中添加 `--network langbot-network`）。接着在消息平台配置文件中，把 WS 反向连接地址中的 IP 地址修改为 `langbot`（例如：`ws://langbot:2280/ws`）。

重启两个容器。

## 仅 LangBot 运行在 Docker 容器中

当只有 LangBot 采用 Docker 部署时，默认已经映射 2280 到 2290 端口到容器外。此时 LangBot 只能作为 WebSocket 服务器，接受消息平台作为客户端连接。

请把消息平台设置为 ReverseWebSocket（称为 `反向 ws` 或 `WebSocket 客户端`），端口对应 LangBot 的 aiocqhttp 适配器启用的端口，连接本地 127.0.0.1 即可。

## LangBot 和消息平台都不使用 Docker 部署

根据文档配置消息平台和 LangBot 设置，两者端口设置为统一的不被占用的即可，都连接本地 127.0.0.1。

## 仅消息平台运行在 Docker 容器中（不建议）

> warning:
>
> 仅支持 Linux ，或其他支持 host 模式 docker 网络的系统。

目前 LangBot 的 aiocqhttp 适配器仅支持 反向 WebSocket 连接，当消息平台运行在 Docker 容器中而 LangBot 直接运行在宿主机时，必须由 消息平台作为客户端连接 LangBot。此时只能将 消息平台的 network 设置为 `host` 模式，再设置其 WS 连接地址为 127.0.0.1，端口对应 LangBot 的 aiocqhttp 适配器启用的端口。

---

# LangBot 接入 New API

Source: https://langbot.app/docs/zh/workshop/newapi-integration

New API 是新一代大模型网关与 AI 资产管理系统，旨在解决多 AI 服务商接入分散、成本难管控、服务稳定性不足等问题，核心优势集中在三点：

1. **多服务商兼容**：已整合 **30+ AI 服务商**，且实现 **100% OpenAI 兼容**（即支持按 OpenAI 接口格式调用其他服务商模型，降低开发成本）；
2. **高可用性**：承诺 **99.9% 服务可用性**，满足企业级稳定需求；
3. **易用与可控**：支持 “一键部署” 快速接入，同时提供 “灵活计费” 功能，帮助用户管控 AI 使用成本，兼顾 “安全稳定” 特性。

## 一、本地部署 New API（Docker 容器方式）

> 更多部署方式，参考 [New API 部署指南](https://docs.newapi.pro/installation/)

本部署方式使用 SQLite 数据库（轻量无需额外部署）

命令行中输入

```bash
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./new-api/data:/data \
  calciumion/new-api:latest
```

> ⚠️ 注意：
>
> - 把 `./new-api/data` 替换成你要使用的实际文件夹

部署完成后，打开`http://服务器IP:3000`进行配置 New API

## 二、LangBot 连接本地 New API

1. **添加 New API 模型**
   - 模型名称：输入 New API 中配置的模型名称
   - 模型供应商：选择 New API
   - 请求 URL：输入`http://服务器IP:3000/v1`
   - API Key：输入 New API 中创建的令牌

![](https://langbot.app/docs/images/zh/workshop/newapi-integration/model.png)

2. **流水线选择使用刚才配置的模型**

![](https://langbot.app/docs/images/zh/workshop/newapi-integration/model2.png)

3. 接下来就可以使用 New API 中的模型了

---

# 接入 PPIO 派欧云 API 的模型

Source: https://langbot.app/docs/zh/workshop/ppio-integration

打开 WebUI 页面，添加模型时选择[派欧云](https://ppio.cn/user/register?from=ppinfra\&invited_by=QJKFYD\&utm_source=github_langbot)即可

![model](https://langbot.app/docs/images/zh/workshop/ppio-integration/model.png)

---

# 配置 HTTP 反向代理或通过网关访问 LangBot

Source: https://langbot.app/docs/zh/workshop/production/proxy-and-ssl

LangBot 内部未支持内置 SSL 提供 HTTPS 服务，若您需要解析域名到 LangBot 实例，或需要使用 HTTPS 访问 LangBot WebUI 和各个机器人的 Webhook 地址，请参考此文档部署 NGINX 或 Caddy 实现 HTTP 反向代理。

您需要将 LangBot 部署在具有公网 IP 的主机上，并购买域名，将域名解析到主机公网 IP 上。

> idea:
>
> **觉得配置麻烦？** [LangBot Cloud](https://space.langbot.app/cloud) 已自带域名和 HTTPS，无需自行购买服务器、域名或配置反向代理，注册即可使用企业微信、微信公众号等 Webhook 类平台。

> warning:
>
> 若您需要使用 QQ官方机器人、微信公众号、企业微信、Slack、LINE 等需要 Webhook 回调地址的机器人，请务必按照本文档配置 HTTP 反向代理。

## Caddy

Caddy 是一个现代的 HTTP 服务器，支持自动 HTTPS 证书申请和续期，支持反向代理，支持自动配置 DNS 解析。

[Caddy 安装文档](https://caddy2.dengxiaolong.com/docs/install)。选择对应自己操作系统的安装步骤，进行安装。

### 填写 Caddyfile

本文假设使用 ubuntu 系统部署 LangBot ，那么在系统中，Caddyfile 的默认位置为 `/etc/caddy/Caddyfile`。
使用 vim 或 nano 编辑 Caddyfile ，Caddyfile文件填写为：

```json
your.domain.com {
        reverse_proxy 127.0.0.1:5300
}
```

> info:
>
> 若您的 Caddy 和 LangBot 使用容器部署，请查看[容器网络配置详解](https://langbot.app/docs/zh/workshop/network-details.md)

现在，您即可通过浏览器访问 `https://your.domain.com` 访问 LangBot WebUI。

### 设置机器人回调地址前缀

若您需要使用 QQ官方机器人、微信公众号、企业微信、Slack、LINE 等需要 Webhook 回调地址的机器人，请在 data/config.yaml 文件中设置`api.webhook_prefix`为您的域名。例如：`https://your.domain.com`。

之后，在机器人管理页面，您将看到正确显示的回调地址。

## NGINX

NGINX 也是常用的 HTTP 服务器和反向代理工具，可以用来实现 LangBot 的 HTTPS 接入。

### 安装 NGINX

在 Ubuntu 上可以通过以下命令安装 NGINX：

```bash
sudo apt update
sudo apt install nginx
```

### 准备 SSL 证书

您可以使用 [Let’s Encrypt](https://letsencrypt.org/) 免费申请 SSL 证书。推荐使用 [Certbot](https://certbot.eff.org/) 工具来获取证书：

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx
```

按照提示输入域名，证书申请与 NGINX 配置会自动完成。请参考如下内容完成 NGINX 配置。

### 配置 NGINX 反向代理

LangBot 的流水线调试功能需要使用 WebSocket 连接，因此需要配置 NGINX 支持 WebSocket。

编辑 NGINX 配置文件 `/etc/nginx/sites-available/langbot`（可以使用 vim 或 nano 编辑器）：

```nginx
# WebSocket 连接升级映射（放在 server 块之外）
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name your.domain.com;
    # 将 HTTP 流量重定向到 HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your.domain.com;

    ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 反向代理到 LangBot 实例
    location / {
        proxy_pass http://127.0.0.1:5300;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 86400;
    }
}
```

将 `your.domain.com` 替换为您实际的域名。

启用此配置并重启 NGINX：

```bash
sudo ln -s /etc/nginx/sites-available/langbot /etc/nginx/sites-enabled/langbot
sudo nginx -t
sudo systemctl reload nginx
```

### 设置机器人回调地址前缀

同样，在 `data/config.yaml` 配置文件中将 `api.webhook_prefix` 设置为 `https://your.domain.com`，这样机器人 Webhook 回调地址才会正确。

完成上述配置后，即可通过 `https://your.domain.com` 安全访问 LangBot WebUI 和机器人 Webhook 服务。

---

# 接入来自胜算云的模型

Source: https://langbot.app/docs/zh/workshop/shengsuanyun-integration

胜算云是一家提供大模型和 GPU 资源的平台，支持将国内外各种大模型接入 LangBot，包括 Claude、GPT、DeepSeek、Gemini 等。

## 注册胜算云

点击[链接](https://www.shengsuanyun.com/?from=CH_KYIPP758)注册胜算云账号，完成后前往`控制台`，`API 密钥`页面，生成并复制 API Key。

## 使用聊天模型

在胜算云顶部进入`大厂模型Router`，即可查看可用的模型列表，并复制模型名称。

![胜算云模型列表](https://langbot.app/docs/images/zh/workshop/shengsuanyun-integration/llm-models.png)

前往 LangBot 模型管理页，添加模型（选择胜算云提供商，填入模型名称和 API Key）：

![添加模型](https://langbot.app/docs/images/zh/workshop/shengsuanyun-integration/add-llm-model.png)

现在即可在流水线中选择使用该模型。

---

# 接入来自小马算力的模型

Source: https://langbot.app/docs/zh/workshop/tokenpony-integration

![model](https://langbot.app/docs/images/zh/workshop/tokenpony-integration/tokenpony-mainpage.png)

TokenPony（小马算力）提供统一的API，可以通过单一端点访问数百个AI模型，同时自动处理回退并选择最具成本效益的选项。在 LangBot 中已完美适配，可按照以下步骤添加来自小马算力的模型。

## 注册小马算力

点击[链接](https://www.tokenpony.cn/453z1)注册小马算力账号，完成后点击右上角账户按钮，点击`API Keys`

![api-keys](https://langbot.app/docs/images/zh/workshop/tokenpony-integration/access-api-key-page.png)

生成并复制 API Key。

![api-keys](https://langbot.app/docs/images/zh/workshop/tokenpony-integration/get-api-key.png)

## 使用聊天模型

在小马算力顶部进入[`模型`](https://www.tokenpony.cn/#/model)，即可查看可用的模型列表，并复制模型名称。

前往 LangBot 模型管理页，添加模型（选择小马算力提供商，填入模型名称和 API Key）：

![model](https://langbot.app/docs/images/zh/workshop/tokenpony-integration/add-model.png)

现在即可在流水线中选择使用该模型。