## Canonical agent entry

Read https://langbot.app/llms.txt first for deployment choices, optional managed hosting, CLI installation and operation, and end-to-end verification. This documentation index supplies the detailed guides referenced by that workflow.

# 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

- [LangBot 4.11: Event-Driven Agents, Plugin Runners, and a Workspace Assistant](https://langbot.app/docs/en/articles/langbot-v411-event-driven-agents.md) — 2026-10-15
- [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

- [Turn GitHub Releases into Telegram Briefings with Dify and LangBot](https://langbot.app/docs/en/articles/dify-langbot-github-release-briefing.md) — 2026-09-16
- [Route Support Questions in Discord and LINE with Dify and LangBot](https://langbot.app/docs/en/articles/dify-langbot-support-triage.md) — 2026-09-16
- [A Dify Writing Assistant for Discord and Telegram with GPT-6 Astra and LangBot](https://langbot.app/docs/en/articles/dify-langbot-writing-assistant.md) — 2026-09-16
- [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)

---

# Turn GitHub Releases into Telegram Briefings with Dify and LangBot

Source: https://langbot.app/docs/en/articles/dify-langbot-github-release-briefing

Fetch a real GitHub release with Dify, extract the useful fields and let GPT-6 Astra write a sourced briefing. Connect the Workflow to LangBot with the correct input and output contract.

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

Published 2026-09-16 · Author: LangBot Team

“What changed in the latest release?” sounds like a simple chatbot question. It becomes a data problem as soon as a repository ships something newer than the model knows.

We built an on-demand release briefing that reads GitHub first. Dify fetches the public release JSON, a code node keeps the useful fields, GPT-6 Astra writes a short summary, and LangBot returns it to the conversation. The example uses the public LangBot repository, and the same pattern works for other release feeds.

![The briefing comes from a live GitHub API request, with a source link.](https://langbot.app/docs/images/articles/source/images/dify-langbot/056-release-english-live-briefing.png)

*The briefing comes from a live GitHub API request, with a source link.*

## Start with a working Dify and LangBot installation

Start Docker Compose and Git, then follow the [Dify Docker Compose guide](https://docs.dify.ai/en/self-host/deploy/quick-start/docker-compose) and the [LangBot Docker guide](https://langbot.app/docs/en/deploy/langbot/docker.md) to bring up both services. For Dify, clone the repository, enter `docker`, copy `.env.example` to `.env`, and start Compose. The LangBot guide includes the application image and plugin runtime configuration.

The screenshots come from a local installation of **Dify 1.17.1 and LangBot v4.10.11**. We mapped the browser ports to `8088` and `5368`. Those are custom demo ports; the default installations normally use `80` and `5300`. With the defaults, open `http://localhost` and `http://localhost:5300`. You do not need to change ports just to match a screenshot. Create your own administrator accounts and select **English** in both interfaces.

![The first-run screen of the local Dify deployment.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-dify-install.png)

*The first-run screen of the local Dify deployment.*

![The local LangBot installation before administrator setup.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-langbot-install.png)

*The local LangBot installation before administrator setup.*

The important requirement is that **the LangBot container can reach Dify**. Our two services share a Docker network, so the Runner uses `http://nginx/v1`, where `nginx` is Dify's service name. You can attach Dify's `nginx` service and LangBot to the same external network in their Compose configurations. For separate hosts, use a Dify HTTPS address reachable from LangBot and append `/v1`. Every `http://nginx/v1` example below refers to our shared network; replace it for your own deployment. Inside a container, `localhost` points back to that container.

## Connect GPT-6 Astra to Dify

Open **Integrations → Model Provider**, install the official **OpenAI-API-compatible** provider, and choose **Add Model**. We tested provider version 0.0.66 with an OpenAI-compatible gateway.

| Field                                | Tutorial setting                                             |
| ------------------------------------ | ------------------------------------------------------------ |
| Model Name / endpoint model name     | `gpt-6-astra`                                                |
| Model Type / Completion mode         | LLM / Chat                                                   |
| Model display name                   | GPT-6 Astra                                                  |
| API Base URL                         | Your provider's compatible endpoint, usually ending in `/v1` |
| API Key                              | Your own provider key                                        |
| API Type                             | Chat Completions API                                         |
| Context size / maximum-token ceiling | 32768 / 4096 for this example                                |

Those limits are conservative settings for this tutorial, not a statement of Astra's full specifications. Save the model and let Dify validate the connection. Replace the gateway shown in the screenshot with your own authorized endpoint. Model names and capabilities depend on your provider. This walkthrough retains the `gpt-6-astra` identifier used in the tested deployment.

![The custom model form, captured before entering the API key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/014-dify-astra-model-settings.png)

*The custom model form, captured before entering the API key.*

## Create a Workflow with a clear input and output

Create a Dify **Workflow** named `Astra Release Briefing`. Each request is an independent read of the current release, so a Workflow fits naturally.

Connect these nodes:

`User Request → HTTP Request → Code → LLM → End`

![The complete five-node release workflow.](https://langbot.app/docs/images/articles/source/images/dify-langbot/045-release-workflow-overview.png)

*The complete five-node release workflow.*

### 1. Name the input for LangBot

In the Start node, add a required paragraph input named:

```text
langbot_user_message_text
```

LangBot's Dify Workflow Runner places the incoming message text in that field. If you call it `question` instead, the workflow may pass a manual Dify test and still fail when LangBot calls it with different input names.

![The required input is named to match the runner contract.](https://langbot.app/docs/images/articles/source/images/dify-langbot/049-release-workflow-input.png)

*The required input is named to match the runner contract.*

### 2. Read the latest public release

Use an HTTP Request node with GET:

```text
https://api.github.com/repos/langbot-app/LangBot/releases/latest
```

Add `Accept: application/vnd.github+json` and `User-Agent: LangBot-Dify-Tutorial`. This example reads public data without a GitHub token. Leave SSL verification enabled and choose sensible connection and read timeouts for your environment.

![The HTTP node fetches the latest release directly from GitHub.](https://langbot.app/docs/images/articles/source/images/dify-langbot/046-release-http-request-settings.png)

*The HTTP node fetches the latest release directly from GitHub.*

### 3. Extract the useful fields

Pass the HTTP node's `body` and `status_code` to a Code node. Keep only the information needed for a briefing:

```python
import json

def main(body: str, status_code: int) -> dict:
    if status_code != 200:
        return {"release": json.dumps({"error": f"GitHub HTTP {status_code}"})}
    data = json.loads(body)
    return {"release": json.dumps({
        "repository": "langbot-app/LangBot",
        "tag": data.get("tag_name"),
        "published_at": data.get("published_at"),
        "url": data.get("html_url"),
        "notes": (data.get("body") or "")[:14000],
    }, ensure_ascii=False)}
```

This removes avatars and unrelated API URLs from the model input. It also makes a non-200 response explicit. A transport failure can still stop the HTTP node before this code runs, which is why you should inspect failed workflow runs as well as successful ones.

![The Code node turns the raw response into a small release record.](https://langbot.app/docs/images/articles/source/images/dify-langbot/047-release-code-extraction-node.png)

*The Code node turns the raw response into a small release record.*

### 4. Write the briefing and return summary

Choose GPT-6 Astra in the LLM node. Ask it to answer in the user's language and include the repository, release tag, publication time, three useful highlights, and the source URL. Tell it to use only the supplied API data and to report missing data or an error instead of guessing.

Pass both `langbot_user_message_text` and the extracted `release` record into the user prompt. In End, map the LLM's `text` to an output named **`summary`**. This is the field LangBot expects from the workflow response.

![The final output maps the generated text to summary.](https://langbot.app/docs/images/articles/source/images/dify-langbot/054-release-summary-output-verified.png)

*The final output maps the generated text to summary.*

## Verify against GitHub, not against the screenshot

Our English and Chinese runs both retrieved `v4.10.11`, published on September 12, 2026 at 04:55:58 UTC. The briefing linked to that exact release and summarized changes in knowledge ingestion, monitoring, and platform compatibility.

![The English run includes a release tag, date, highlights, and source.](https://langbot.app/docs/images/articles/source/images/dify-langbot/056-release-english-live-briefing.png)

*The English run includes a release tag, date, highlights, and source.*

Your run may show a newer version. Compare the answer with the current API fields—`tag_name`, `published_at`, and `html_url`—rather than expecting the version in this article forever.

## Put LangBot in front of the app

Publish the saved version in Dify. Open **Access Point → Backend Service API → API Key** and create a key for this app.

In LangBot, choose **Create Pipelines**, name the pipeline `Astra Release Briefing`, and open **Configuration → AI**:

| Field    | Value                             |
| -------- | --------------------------------- |
| Runner   | Dify Service API                  |
| Base URL | `http://nginx/v1`                 |
| App Type | Workflow                          |
| API Key  | The Dify app key you just created |

The Dify app key belongs here. The Astra provider key stays in Dify. Save the pipeline, then use **Debug Chat** to check the complete request and response path before adding a messaging platform.

![The LangBot pipeline settings, captured before entering the app key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/078-langbot-release-workflow-settings.png)

*The LangBot pipeline settings, captured before entering the app key.*

## Ask for the briefing through LangBot

The English request through LangBot returned the same kind of source-linked briefing. I also tested Chinese output. One request hit a temporary upstream SSL interruption; a later retry succeeded. The failed run remains separate from the successful evidence.

![The workflow summary returned through LangBot.](https://langbot.app/docs/images/articles/source/images/dify-langbot/079-langbot-release-english-roundtrip.png)

*The workflow summary returned through LangBot.*

For Telegram or a Discord project channel, start with an on-demand command or mention trigger. This workflow reads the release when someone asks; scheduled delivery requires an additional scheduler and sending step.

To cover another repository, first duplicate the app and change the fixed API URL. Add a validated repository parameter only when you actually need it. A short, predictable integration is much easier to operate than an unrestricted URL-fetching bot.

## Connect it to Telegram and Discord

Choose **Create Bots** in LangBot, select your adapter, and enter credentials from that platform. After creating the bot, select the pipeline you just built. Check the pipeline's trigger rules for direct messages, group messages, and mentions before inviting it into a channel.

The measured path in this walkthrough is **LangBot → Dify → GPT-6 Astra → LangBot**. We inspected the real adapter forms below; we did not authorize a live Slack workspace, Discord server, Telegram bot, or LINE account for this demo.

| Platform   | Setup path                                                                                                                                                                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Slack      | Create a Slack app, grant the required bot scopes, install it to the workspace, and enter the Bot Token and Signing Secret in LangBot. Configure event subscriptions with the public HTTPS callback from the bot setup, verify it, and invite the bot to the intended channel. |
| Discord    | Create an application and bot in the Developer Portal. Enter Client ID and bot Token, enable the required message intents, then invite the bot with the appropriate channel permissions.                                                                                       |
| Telegram   | Create a bot with BotFather and enter its token. Start with a direct message; for groups, invite the bot and configure privacy mode and LangBot's trigger rules for the messages it should receive.                                                                            |
| LINE       | Create a Messaging API channel. Enter the Channel access token and Channel secret, configure the public HTTPS webhook, enable webhook delivery, and avoid conflicting automatic replies.                                                                                       |
| Mattermost | Enter the server URL and a Bot Account access token, then add that account to the relevant teams and channels. The adapter uses REST and WebSocket APIs.                                                                                                                       |

![The Discord adapter uses the application Client ID and bot token.](https://langbot.app/docs/images/articles/source/images/dify-langbot/059-platform-discord-fields.png)

*The Discord adapter uses the application Client ID and bot token.*

![The Telegram adapter uses a BotFather token and exposes reply options.](https://langbot.app/docs/images/articles/source/images/dify-langbot/060-platform-telegram-fields.png)

*The Telegram adapter uses a BotFather token and exposes reply options.*

The catalog also includes Matrix, Lark, DingTalk, WeCom, WeChat-related adapters, QQ, KOOK, OneBot v11, Satori, HTTP Bot, and Page Bot. See the [platform-specific LangBot guides](https://langbot.app/docs/en/usage/platforms/readme.md) for the permissions and networking required by each adapter. In particular, the local-only deployment above needs a suitable public HTTPS endpoint for webhook-based integrations such as Slack and LINE.

## Troubleshooting

When something fails, check the path in order: Dify preview, the published app version, LangBot's `/v1` base URL and app type, then the platform's event delivery. If you change Dify service passwords, keep Redis and Celery credentials aligned, and do the same for Sandbox and its code-execution client.

Our local proxy initially returned fake DNS addresses that Dify's SSRF proxy rejected. Correcting DNS fixed the plugin download without disabling network protections. For external API calls, inspect the run record after a retry rather than assuming that a transport error means the app configuration is wrong.

Project sources: [LangBot](https://github.com/langbot-app/LangBot) and [Dify](https://github.com/langgenius/dify). The deployment and screenshots are from September 16, 2026; later versions may move some controls.

## Further reading

- [A Dify Writing Assistant for Discord and Telegram with GPT-6 Astra and LangBot](https://langbot.app/en/blog/dify-langbot-writing-assistant)
- [Route Support Questions in Discord and LINE with Dify and LangBot](https://langbot.app/en/blog/dify-langbot-support-triage)

---

# 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)

---

# Route Support Questions in Discord and LINE with Dify and LangBot

Source: https://langbot.app/docs/en/articles/dify-langbot-support-triage

Use GPT-6 Astra and a Dify Question Classifier to separate account help, product questions and requests for human review. Test each route through LangBot before connecting Discord or LINE.

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

Published 2026-09-16 · Author: LangBot Team

A single support prompt can work surprisingly well—until the same bot receives an expired invitation, an export question, and an angry refund request. Those messages need different responses and different limits.

We built a three-route support assistant in Dify, then connected it through LangBot. GPT-6 Astra classifies the request and writes a reply for the selected route. The result is small enough to inspect: one classifier, three response nodes, and three outputs.

![The actual support Chatflow, with separate account, product, and human-review routes.](https://langbot.app/docs/images/articles/source/images/dify-langbot/039-triage-three-branch-overview.png)

*The actual support Chatflow, with separate account, product, and human-review routes.*

## Start with a working Dify and LangBot installation

Start Docker Compose and Git, then follow the [Dify Docker Compose guide](https://docs.dify.ai/en/self-host/deploy/quick-start/docker-compose) and the [LangBot Docker guide](https://langbot.app/docs/en/deploy/langbot/docker.md) to bring up both services. For Dify, clone the repository, enter `docker`, copy `.env.example` to `.env`, and start Compose. The LangBot guide includes the application image and plugin runtime configuration.

The screenshots come from a local installation of **Dify 1.17.1 and LangBot v4.10.11**. We mapped the browser ports to `8088` and `5368`. Those are custom demo ports; the default installations normally use `80` and `5300`. With the defaults, open `http://localhost` and `http://localhost:5300`. You do not need to change ports just to match a screenshot. Create your own administrator accounts and select **English** in both interfaces.

![The first-run screen of the local Dify deployment.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-dify-install.png)

*The first-run screen of the local Dify deployment.*

![The local LangBot installation before administrator setup.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-langbot-install.png)

*The local LangBot installation before administrator setup.*

The important requirement is that **the LangBot container can reach Dify**. Our two services share a Docker network, so the Runner uses `http://nginx/v1`, where `nginx` is Dify's service name. You can attach Dify's `nginx` service and LangBot to the same external network in their Compose configurations. For separate hosts, use a Dify HTTPS address reachable from LangBot and append `/v1`. Every `http://nginx/v1` example below refers to our shared network; replace it for your own deployment. Inside a container, `localhost` points back to that container.

## Connect GPT-6 Astra to Dify

Open **Integrations → Model Provider**, install the official **OpenAI-API-compatible** provider, and choose **Add Model**. We tested provider version 0.0.66 with an OpenAI-compatible gateway.

| Field                                | Tutorial setting                                             |
| ------------------------------------ | ------------------------------------------------------------ |
| Model Name / endpoint model name     | `gpt-6-astra`                                                |
| Model Type / Completion mode         | LLM / Chat                                                   |
| Model display name                   | GPT-6 Astra                                                  |
| API Base URL                         | Your provider's compatible endpoint, usually ending in `/v1` |
| API Key                              | Your own provider key                                        |
| API Type                             | Chat Completions API                                         |
| Context size / maximum-token ceiling | 32768 / 4096 for this example                                |

Those limits are conservative settings for this tutorial, not a statement of Astra's full specifications. Save the model and let Dify validate the connection. Replace the gateway shown in the screenshot with your own authorized endpoint. Model names and capabilities depend on your provider. This walkthrough retains the `gpt-6-astra` identifier used in the tested deployment.

![The custom model form, captured before entering the API key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/014-dify-astra-model-settings.png)

*The custom model form, captured before entering the API key.*

## Define what each route is allowed to do

This example uses a fictional help-desk product called Northstar Desk. Its few product rules are included directly in the branch prompts, so you do not need a pre-existing knowledge base or another tutorial.

| Route   | Requests                                                                 | Job                                                                                 |
| ------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Account | Login, invitations, workspace access                                     | Explain the invitation recovery steps                                               |
| Product | CSV export, trial limits, basic setup                                    | Answer from the small set of supplied product rules                                 |
| Human   | Billing, refunds, enterprise pricing, complaints, unclear mixed requests | Explain that a human decision is needed and help the user prepare a concise request |

The Human branch produces handoff guidance. It does not create a ticket, notify an employee, or approve a refund. That distinction belongs in the prompt: otherwise the assistant may casually imply it has performed an action that the workflow never implemented.

## Build the classifier and three branches

Create a **Chatflow** named `Astra Support Router`. Connect User Input to a **Question Classifier**, choose GPT-6 Astra, and set its query variable to `sys.query`.

Add these categories:

```text
Account: login, invitation, password or workspace access
Product: usage, ticket export, setup and trial limits
Human: billing, refunds, enterprise pricing, angry complaints
or unclear mixed questions
```

![The category descriptions define the routing boundary.](https://langbot.app/docs/images/articles/source/images/dify-langbot/040-triage-classifier-settings.png)

*The category descriptions define the routing boundary.*

In the classifier's advanced instructions, tell it to choose Human when essential context is missing or the request needs authorization. Connect each branch to its own LLM node and Answer node.

Use GPT-6 Astra in each LLM node and pass the user query through `sys.query`. Give the branches different system instructions:

- **Account Reply:** invitations expire after 48 hours. Ask the workspace owner to resend from `Settings > Members`. Never request passwords. Ask one clarifying question if the problem is different.
- **Product Reply:** owners export CSV tickets from `Settings > Data > Export`; export links last 7 days. The trial lasts 14 days and supports 5 teammates and 2 inboxes. Say when the supplied notes do not cover a question.
- **Human Reply:** acknowledge the request and explain that a human must decide. Ask for a brief issue summary and a non-sensitive reference. Tell the user to contact their support team, without inventing an address, response-time promise, or completed action.

All three prompts ask for concise replies in the user's language. Keeping the branch instructions separate makes a later change easier to review: adjusting billing guidance does not also change the login instructions.

## Test the path, not only the wording

We ran an expired-invitation question, a CSV-export question, and a refund complaint. The preview identified the selected output for each run:

| Test                  | Observed output | Response                                                   |
| --------------------- | --------------- | ---------------------------------------------------------- |
| Expired invitation    | Account Output  | Owner resend instructions and the 48-hour limit            |
| Export tickets as CSV | Product Output  | Correct menu path and 7-day availability                   |
| Refund complaint      | Human Output    | Human-review guidance without claiming a refund was issued |

![The account test follows the Account branch.](https://langbot.app/docs/images/articles/source/images/dify-langbot/041-triage-account-path-result.png)

*The account test follows the Account branch.*

![The export question follows the Product branch.](https://langbot.app/docs/images/articles/source/images/dify-langbot/043-triage-product-path-result.png)

*The export question follows the Product branch.*

Expand the workflow process in Preview when a result looks odd. A plausible sentence can hide an incorrect route. That is why the output name is part of the test, rather than treating every fluent answer as a pass.

## Put LangBot in front of the app

Publish the saved version in Dify. Open **Access Point → Backend Service API → API Key** and create a key for this app.

In LangBot, choose **Create Pipelines**, name the pipeline `Astra Support Router`, and open **Configuration → AI**:

| Field    | Value                             |
| -------- | --------------------------------- |
| Runner   | Dify Service API                  |
| Base URL | `http://nginx/v1`                 |
| App Type | Chat                              |
| API Key  | The Dify app key you just created |

The Dify app key belongs here. The Astra provider key stays in Dify. Save the pipeline, then use **Debug Chat** to check the complete request and response path before adding a messaging platform.

![The LangBot pipeline settings, captured before entering the app key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/053-langbot-triage-dify-settings.png)

*The LangBot pipeline settings, captured before entering the app key.*

## Run it through LangBot

The same expired-invitation question in LangBot returned the workspace-owner recovery steps. A later refund request in Chinese reached the human-review guidance. LangBot did not need its own copy of the classification rules.

![An account-support response returned through LangBot.](https://langbot.app/docs/images/articles/source/images/dify-langbot/055-langbot-triage-account-english.png)

*An account-support response returned through LangBot.*

Before putting this in a busy Discord server or a LINE support account, add ambiguous examples such as “I cannot log in and want a refund.” If those repeatedly land in Product, refine the category descriptions and classifier instructions.

When you are ready for a real handoff, add your existing ticketing or notification API to the Human branch and handle its success and failure explicitly. The example gives you a visible place to add that action later.

## Connect it to Discord and LINE

Choose **Create Bots** in LangBot, select your adapter, and enter credentials from that platform. After creating the bot, select the pipeline you just built. Check the pipeline's trigger rules for direct messages, group messages, and mentions before inviting it into a channel.

The measured path in this walkthrough is **LangBot → Dify → GPT-6 Astra → LangBot**. We inspected the real adapter forms below; we did not authorize a live Slack workspace, Discord server, Telegram bot, or LINE account for this demo.

| Platform   | Setup path                                                                                                                                                                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Slack      | Create a Slack app, grant the required bot scopes, install it to the workspace, and enter the Bot Token and Signing Secret in LangBot. Configure event subscriptions with the public HTTPS callback from the bot setup, verify it, and invite the bot to the intended channel. |
| Discord    | Create an application and bot in the Developer Portal. Enter Client ID and bot Token, enable the required message intents, then invite the bot with the appropriate channel permissions.                                                                                       |
| Telegram   | Create a bot with BotFather and enter its token. Start with a direct message; for groups, invite the bot and configure privacy mode and LangBot's trigger rules for the messages it should receive.                                                                            |
| LINE       | Create a Messaging API channel. Enter the Channel access token and Channel secret, configure the public HTTPS webhook, enable webhook delivery, and avoid conflicting automatic replies.                                                                                       |
| Mattermost | Enter the server URL and a Bot Account access token, then add that account to the relevant teams and channels. The adapter uses REST and WebSocket APIs.                                                                                                                       |

![The Discord adapter uses the application Client ID and bot token.](https://langbot.app/docs/images/articles/source/images/dify-langbot/059-platform-discord-fields.png)

*The Discord adapter uses the application Client ID and bot token.*

![LINE requires its channel access token and channel secret.](https://langbot.app/docs/images/articles/source/images/dify-langbot/061-platform-line-fields.png)

*LINE requires its channel access token and channel secret.*

The catalog also includes Matrix, Lark, DingTalk, WeCom, WeChat-related adapters, QQ, KOOK, OneBot v11, Satori, HTTP Bot, and Page Bot. See the [platform-specific LangBot guides](https://langbot.app/docs/en/usage/platforms/readme.md) for the permissions and networking required by each adapter. In particular, the local-only deployment above needs a suitable public HTTPS endpoint for webhook-based integrations such as Slack and LINE.

## Troubleshooting

When something fails, check the path in order: Dify preview, the published app version, LangBot's `/v1` base URL and app type, then the platform's event delivery. If you change Dify service passwords, keep Redis and Celery credentials aligned, and do the same for Sandbox and its code-execution client.

Our local proxy initially returned fake DNS addresses that Dify's SSRF proxy rejected. Correcting DNS fixed the plugin download without disabling network protections. For external API calls, inspect the run record after a retry rather than assuming that a transport error means the app configuration is wrong.

Project sources: [LangBot](https://github.com/langbot-app/LangBot) and [Dify](https://github.com/langgenius/dify). The deployment and screenshots are from September 16, 2026; later versions may move some controls.

## Further reading

- [A Dify Writing Assistant for Discord and Telegram with GPT-6 Astra and LangBot](https://langbot.app/en/blog/dify-langbot-writing-assistant)
- [Turn GitHub Releases into Telegram Briefings with Dify and LangBot](https://langbot.app/en/blog/dify-langbot-github-release-briefing)

---

# A Dify Writing Assistant for Discord and Telegram with GPT-6 Astra and LangBot

Source: https://langbot.app/docs/en/articles/dify-langbot-writing-assistant

Build a basic Dify Chatbot for announcements, revisions and translations, then connect it to LangBot. Includes tested prompts, screenshots and Discord and Telegram setup guidance.

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

Published 2026-09-16 · Author: LangBot Team

A community announcement usually starts as a few rough notes: a date, a channel, and something people need to bring. The first draft is easy. The annoying part is reopening another app for every “make it shorter” or “turn that into a Telegram reminder.”

We built a small writing assistant that keeps those revisions in the conversation. Dify owns the prompt and chat history, GPT-6 Astra writes the response, and LangBot provides the messaging-platform entry point. Here is the complete setup, including the local deployment and the replies We tested.

![A real response from Dify and Astra, shown in LangBot Debug Chat.](https://langbot.app/docs/images/articles/source/images/dify-langbot/025-langbot-writing-english-roundtrip.png)

*A real response from Dify and Astra, shown in LangBot Debug Chat.*

## Start with a working Dify and LangBot installation

Start Docker Compose and Git, then follow the [Dify Docker Compose guide](https://docs.dify.ai/en/self-host/deploy/quick-start/docker-compose) and the [LangBot Docker guide](https://langbot.app/docs/en/deploy/langbot/docker.md) to bring up both services. For Dify, clone the repository, enter `docker`, copy `.env.example` to `.env`, and start Compose. The LangBot guide includes the application image and plugin runtime configuration.

The screenshots come from a local installation of **Dify 1.17.1 and LangBot v4.10.11**. We mapped the browser ports to `8088` and `5368`. Those are custom demo ports; the default installations normally use `80` and `5300`. With the defaults, open `http://localhost` and `http://localhost:5300`. You do not need to change ports just to match a screenshot. Create your own administrator accounts and select **English** in both interfaces.

![The first-run screen of the local Dify deployment.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-dify-install.png)

*The first-run screen of the local Dify deployment.*

![The local LangBot installation before administrator setup.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-langbot-install.png)

*The local LangBot installation before administrator setup.*

The important requirement is that **the LangBot container can reach Dify**. Our two services share a Docker network, so the Runner uses `http://nginx/v1`, where `nginx` is Dify's service name. You can attach Dify's `nginx` service and LangBot to the same external network in their Compose configurations. For separate hosts, use a Dify HTTPS address reachable from LangBot and append `/v1`. Every `http://nginx/v1` example below refers to our shared network; replace it for your own deployment. Inside a container, `localhost` points back to that container.

## Connect GPT-6 Astra to Dify

Open **Integrations → Model Provider**, install the official **OpenAI-API-compatible** provider, and choose **Add Model**. We tested provider version 0.0.66 with an OpenAI-compatible gateway.

| Field                                | Tutorial setting                                             |
| ------------------------------------ | ------------------------------------------------------------ |
| Model Name / endpoint model name     | `gpt-6-astra`                                                |
| Model Type / Completion mode         | LLM / Chat                                                   |
| Model display name                   | GPT-6 Astra                                                  |
| API Base URL                         | Your provider's compatible endpoint, usually ending in `/v1` |
| API Key                              | Your own provider key                                        |
| API Type                             | Chat Completions API                                         |
| Context size / maximum-token ceiling | 32768 / 4096 for this example                                |

Those limits are conservative settings for this tutorial, not a statement of Astra's full specifications. Save the model and let Dify validate the connection. Replace the gateway shown in the screenshot with your own authorized endpoint. Model names and capabilities depend on your provider. This walkthrough retains the `gpt-6-astra` identifier used in the tested deployment.

![The custom model form, captured before entering the API key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/014-dify-astra-model-settings.png)

*The custom model form, captured before entering the API key.*

## Build a basic Chatbot

In Dify Studio, choose **Create → Create from Blank → More basic app types → Chatbot**. Name it `Astra Writing Assistant`. A basic Chatbot is enough here: we need a clear prompt and conversation history, without a branching workflow.

![Dify keeps its basic Chatbot option under More basic app types.](https://langbot.app/docs/images/articles/source/images/dify-langbot/010-dify-create-basic-app.png)

*Dify keeps its basic Chatbot option under More basic app types.*

![Give the assistant a name and a specific job.](https://langbot.app/docs/images/articles/source/images/dify-langbot/011-dify-writing-app-create.png)

*Give the assistant a name and a specific job.*

Select GPT-6 Astra under **Configure model**, then add these instructions:

```text
You help a community manager turn rough notes into messages people can use.
Reply in the language of the user's request.
For an announcement, give: one clear headline, a short ready-to-send message,
and one optional reminder.
Preserve supplied dates, times, links, and requirements exactly.
Never invent missing event details, discounts, results, or promises.
If an essential detail is missing, ask one concise question.
Use a natural, direct tone. Avoid hype and excessive emojis.
Keep a typical reply under 180 words. When revising, use conversation context.
```

The most useful line is the one about preserving details. An announcement can survive plain wording. It cannot survive an invented RSVP link or the wrong time zone. We also kept the output short enough to be useful in a channel.

![The prompt gives the assistant a narrow job and clear boundaries.](https://langbot.app/docs/images/articles/source/images/dify-langbot/012-dify-writing-instructions.png)

*The prompt gives the assistant a narrow job and clear boundaries.*

For the first test, we entered:

> Write a Discord announcement: community demo day is September 22 at 18:00 UTC. Bring one bot demo. RSVP in #demo-day. Keep it friendly and under 100 words.

The response preserved the date, time, and channel. We then asked, “Make it shorter, and remove the optional reminder.” The second reply kept the details from the first turn without asking us to paste them again.

![The first English announcement generated in Dify.](https://langbot.app/docs/images/articles/source/images/dify-langbot/016-writing-english-first-reply.png)

*The first English announcement generated in Dify.*

![A follow-up instruction revises the existing announcement.](https://langbot.app/docs/images/articles/source/images/dify-langbot/019-writing-english-context-revision.png)

*A follow-up instruction revises the existing announcement.*

Publish the updated configuration with **Publish Update**. This step matters: an external caller should receive the version you just tested, rather than an older prompt still attached to the published app.

![The published app exposes a backend API for LangBot.](https://langbot.app/docs/images/articles/source/images/dify-langbot/023-writing-access-point-api.png)

*The published app exposes a backend API for LangBot.*

## Put LangBot in front of the app

Publish the saved version in Dify. Open **Access Point → Backend Service API → API Key** and create a key for this app.

In LangBot, choose **Create Pipelines**, name the pipeline `Astra Writing Assistant`, and open **Configuration → AI**:

| Field    | Value                             |
| -------- | --------------------------------- |
| Runner   | Dify Service API                  |
| Base URL | `http://nginx/v1`                 |
| App Type | Chat                              |
| API Key  | The Dify app key you just created |

The Dify app key belongs here. The Astra provider key stays in Dify. Save the pipeline, then use **Debug Chat** to check the complete request and response path before adding a messaging platform.

![The LangBot pipeline settings, captured before entering the app key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/007-langbot-dify-runner-config.png)

*The LangBot pipeline settings, captured before entering the app key.*

## Test the same task through LangBot

We asked LangBot for a two-sentence Telegram reminder. The reply came back through Dify with the supplied date and time intact. A later request switched the same conversation to Chinese, which also worked.

For a community server, we would start with mention-based triggers in a single channel. Let members ask for a draft, shorten it, and adjust the tone before they decide to post it. That small loop is already useful for release announcements, event reminders, and repeated support replies.

![The writing assistant answering through the LangBot pipeline.](https://langbot.app/docs/images/articles/source/images/dify-langbot/025-langbot-writing-english-roundtrip.png)

*The writing assistant answering through the LangBot pipeline.*

## Connect it to Discord and Telegram

Choose **Create Bots** in LangBot, select your adapter, and enter credentials from that platform. After creating the bot, select the pipeline you just built. Check the pipeline's trigger rules for direct messages, group messages, and mentions before inviting it into a channel.

The measured path in this walkthrough is **LangBot → Dify → GPT-6 Astra → LangBot**. We inspected the real adapter forms below; we did not authorize a live Slack workspace, Discord server, Telegram bot, or LINE account for this demo.

| Platform   | Setup path                                                                                                                                                                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Slack      | Create a Slack app, grant the required bot scopes, install it to the workspace, and enter the Bot Token and Signing Secret in LangBot. Configure event subscriptions with the public HTTPS callback from the bot setup, verify it, and invite the bot to the intended channel. |
| Discord    | Create an application and bot in the Developer Portal. Enter Client ID and bot Token, enable the required message intents, then invite the bot with the appropriate channel permissions.                                                                                       |
| Telegram   | Create a bot with BotFather and enter its token. Start with a direct message; for groups, invite the bot and configure privacy mode and LangBot's trigger rules for the messages it should receive.                                                                            |
| LINE       | Create a Messaging API channel. Enter the Channel access token and Channel secret, configure the public HTTPS webhook, enable webhook delivery, and avoid conflicting automatic replies.                                                                                       |
| Mattermost | Enter the server URL and a Bot Account access token, then add that account to the relevant teams and channels. The adapter uses REST and WebSocket APIs.                                                                                                                       |

![The Discord adapter uses the application Client ID and bot token.](https://langbot.app/docs/images/articles/source/images/dify-langbot/059-platform-discord-fields.png)

*The Discord adapter uses the application Client ID and bot token.*

![The Telegram adapter uses a BotFather token and exposes reply options.](https://langbot.app/docs/images/articles/source/images/dify-langbot/060-platform-telegram-fields.png)

*The Telegram adapter uses a BotFather token and exposes reply options.*

The catalog also includes Matrix, Lark, DingTalk, WeCom, WeChat-related adapters, QQ, KOOK, OneBot v11, Satori, HTTP Bot, and Page Bot. See the [platform-specific LangBot guides](https://langbot.app/docs/en/usage/platforms/readme.md) for the permissions and networking required by each adapter. In particular, the local-only deployment above needs a suitable public HTTPS endpoint for webhook-based integrations such as Slack and LINE.

## Troubleshooting

When something fails, check the path in order: Dify preview, the published app version, LangBot's `/v1` base URL and app type, then the platform's event delivery. If you change Dify service passwords, keep Redis and Celery credentials aligned, and do the same for Sandbox and its code-execution client.

Our local proxy initially returned fake DNS addresses that Dify's SSRF proxy rejected. Correcting DNS fixed the plugin download without disabling network protections. For external API calls, inspect the run record after a retry rather than assuming that a transport error means the app configuration is wrong.

Project sources: [LangBot](https://github.com/langbot-app/LangBot) and [Dify](https://github.com/langgenius/dify). The deployment and screenshots are from September 16, 2026; later versions may move some controls.

## Further reading

- [Route Support Questions in Discord and LINE with Dify and LangBot](https://langbot.app/en/blog/dify-langbot-support-triage)
- [Turn GitHub Releases into Telegram Briefings with Dify and LangBot](https://langbot.app/en/blog/dify-langbot-github-release-briefing)

---

# 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 4.11: Event-Driven Agents, Plugin Runners, and a Workspace Assistant

Source: https://langbot.app/docs/en/articles/langbot-v411-event-driven-agents

Explore LangBot 4.11 with real screenshots: route platform events to agents, install independent AgentRunner plugins, manage resources through the Workspace Assistant, and upgrade existing pipelines.

This article is synchronized from the LangBot Blog. [Read the canonical version](https://langbot.app/en/blog/langbot-v411-event-driven-agents).

Published 2026-10-15 · Author: LangBot Team

LangBot is an open-source AI chatbot and agent platform that connects messaging platforms, large language models, knowledge bases, and plugins to help you build, deploy, and manage AI assistants.

Most chatbots start with a simple loop: receive a message, generate a reply. Real collaboration involves more than messages, though. A new member joins a community, someone reacts to an answer, or a colleague clicks a card button. Each can be the beginning of a task.

**LangBot 4.11 makes these events configurable entry points for agents, with routing and execution tracking.** Together with plugin-based AgentRunners and the new Workspace Assistant, the release separates three practical questions: what triggers the work, what executes it, and how you manage it.

## 1. Event-driven agents: more than the next message

Event-Based Agents, or EBA, extend processing beyond ordinary messages to platform events such as member joins and departures, message recalls, reactions, and card clicks. In this release, 13 platform adapters have been rebuilt on the EBA architecture.

That does not mean every platform offers identical event coverage. Available events still depend on the platform, adapter, and bot permissions. The shared foundation is what happens after an event reaches LangBot: it can be routed to a suitable processor.

![Routing platform events to processors](https://langbot.app/docs/images/articles/source/images/langbot-411/eba-event-routing.png)

*Event Routing example from the official 4.11 release notes.*

### Start with the scenario

Event Routing provides common scenarios, such as welcoming new members or handling departures, as starting points for rules. You then choose the processor responsible for the work.

For example, a community could send ordinary questions to a knowledge-base Pipeline, route joins to an Agent that welcomes members and explains community rules, and use a plugin processor for events requiring fixed business logic. This is a configuration pattern, not a preconfigured integration: check platform support and permissions, then test each route before enabling it.

The benefit is a cleaner separation between platform connectivity and business behavior. You can revise the welcome flow without rewriting the chatbot integration, or change the question-answering strategy without combining every behavior into one prompt.

### Pipeline, Agent, or plugin processor?

![Three processor types in a running LangBot 4.11 instance](https://langbot.app/docs/images/articles/source/images/langbot-411/processor-types.png)

*The processor creation screen in the fresh LangBot 4.11.0 instance used for this article.*

- **Pipeline:** handles message events through a fixed sequence. A good fit for direct AI replies, knowledge-base questions, and established message-processing flows.
- **Agent:** follows natural-language instructions to handle different events, or delegates processing to an external agent platform. Useful when a task requires contextual decisions.
- **Plugin processor:** runs plugin code for explicitly declared event types. A good fit for deterministic rules and specialized integrations.

Not everything needs to become an agent. Keep clear rules in code, predictable question-answering in a Pipeline, and use an Agent where judgment adds value.

### Debug the event, not just the reply

The event debugger lets you edit an event payload through a form and inspect execution logs and details. It helps validate fields and processing behavior before testing on the real messaging platform. A successful debug run does not replace verification of platform connectivity, permissions, and actual callbacks.

Platform improvements accompany the new architecture, including Slack Socket Mode, DingTalk card interactions, WeChat typing indicators, and OneBot WebSocket support. Check the relevant platform documentation for the exact capabilities and setup requirements.

## 2. Plugin-based AgentRunners: update execution independently

LocalAgent, Dify, Coze, and n8n runners have moved from the core application into official Marketplace plugins. New runners include Codex, Claude Code, and ACP.

![Official runners in the live extension marketplace](https://langbot.app/docs/images/articles/source/images/langbot-411/marketplace-live.png)

*The Official Runner section loaded from the Marketplace in our running instance. Marketplace listings evolve independently of the Core release.*

For users, the practical change is straightforward: **install the runners you need and update them independently**. Use LocalAgent for models, tools, and knowledge retrieval, or connect an existing Dify application or n8n workflow without building a separate messaging integration for each execution backend.

For developers, AgentRunner Protocol v1 provides an extension boundary for implementing a runner without adding platform-specific execution logic directly to Core.

![AgentRunner plugins featured in the release notes](https://langbot.app/docs/images/articles/source/images/langbot-411/runner-plugins-marketplace.png)

*Runner examples from the official release notes. Each runner still has its own account, API, and execution-environment requirements.*

Plugin-based execution is not unrestricted execution. Runners can access only the tools and platform APIs authorized in the current context. The Marketplace displays certification badges, and Core verifies certified plugin signatures. These mechanisms address provenance and authorization; still read the plugin documentation and check its compatibility with your deployment.

### What happens to existing Pipelines?

The migration flow installs required plugins and backs up the original configuration. After upgrading, complete migration on the Pipelines page, then review the selected runner, model, knowledge bases, and tools.

**Migrated Pipelines start fresh sessions.** Legacy custom runners must be rewritten as plugin runners. Offline deployments can choose **Data only** migration and install the runner plugins manually. The [4.11 configuration migration map](https://github.com/langbot-app/LangBot/blob/v4.11.0/docs/pipeline-migration-config-map.zh-CN.md) provides the detailed mappings in Chinese.

## 3. Workspace Assistant: configuration through confirmed actions

The new Workspace Assistant is for the people managing LangBot, rather than end users chatting with a bot. It can inspect resources in the current Workspace and help create or configure resources such as Pipelines and knowledge bases through conversation.

![Workspace Assistant alongside the execution dashboard](https://langbot.app/docs/images/articles/source/images/langbot-411/workspace-assistant.png)

*The assistant's initial screen in our fresh instance. A LangBot Account or a configured model is required before use. The zero-value monitoring data is the genuine empty state of this new Workspace.*

Start with a read-only question such as “What models, knowledge bases and Pipelines are available?” Then ask for a task such as creating a knowledge-base question-answering application. The useful distinction is not merely replacing a form with a chat box: the assistant can inspect existing resources before proposing a configuration.

**Every write requires confirmation before execution.** Review the proposed resource, parameters, and scope before approving a change. This makes configuration easier to find while keeping the administrator in control of modifications.

## 4. Operations that match the new execution model

### Follow executions, not only message counts

With events going to Pipelines, Agents, or plugins, debugging requires a view of the whole execution. LangBot 4.11 adds unified execution views, tool-call tracing, and a live in-flight panel.

A useful troubleshooting sequence is to check whether the event arrived, which processor received it, and whether model and tool calls completed. This separates connectivity problems from routing mistakes and execution failures instead of treating every missing reply as the same issue.

### Account security and an operation trail

![Passkey and two-factor authentication settings](https://langbot.app/docs/images/articles/source/images/langbot-411/account-security.png)

*The account settings in our running instance. Passkeys and two-factor authentication are not enabled on this demonstration account.*

The release adds WebAuthn passkey sign-in and TOTP two-factor authentication, alongside operation logs that record changes and support integrity checks. In a shared Workspace, these features help strengthen sign-in and establish who changed what. Passkeys also depend on browser secure-context requirements; configure them on an appropriate HTTPS deployment.

Media handling now uses content-addressed, deduplicated storage to reduce growth of `langbot.db` caused by repeated media. For command-line operations, `lbctl` and API keys provide management and diagnostic entry points that can fit into existing operational workflows.

## 5. A clearer first run—and an upgrade checklist

![Selecting a platform in the first-run wizard](https://langbot.app/docs/images/articles/source/images/langbot-411/onboarding.png)

*The live onboarding wizard starts with a platform, then moves through bot setup and AI engine configuration.*

New users can follow the sidebar tour and scenario-based bot wizard. Validate a simple question-and-answer flow first, then add knowledge retrieval, tools, and event routes. Introducing one capability at a time makes failures easier to understand.

For an existing deployment:

1. **Back up first.** Preserve `data/` or your PostgreSQL database and deployment configuration. Upgrading from the latest v4.10.x is recommended.
2. **Upgrade Core and its matching Runtime.** Check service connectivity. The 4.11.0 release pins SDK `0.7.11`; do not leave an older Runtime in place.
3. **Migrate Pipelines and update plugins.** Review the resulting runner configuration and remember the fresh-session boundary.
4. **Verify a real business flow.** Test an existing message conversation before expanding to event routes and authorized tools.
5. **Review telemetry and configuration changes.** New execution telemetry is enabled by default and excludes message content; disable that telemetry with `space.disable_telemetry: true`. Configuration adds `media_cache`, `api.host`, and `runner.admin_plugins`, and removes `force_box_session_id_template`. See the [data collection policy](https://langbot.app/docs/en/insight/data-collection-policy.md) and release notes.

## Get started with LangBot 4.11

The release connects three decisions: **which event starts a task, which runner or processor handles it, and how to manage and observe the result**. Keep familiar chat-based flows where they work, then introduce community interactions and event-driven tasks incrementally.

- [Download v4.11.0 and read the full release notes](https://github.com/langbot-app/LangBot/releases/tag/v4.11.0)
- [Read the deployment and usage documentation](https://langbot.app/docs/en/insight/guide.md)
- [Try LangBot Cloud](https://cloud.langbot.app)

Thanks to everyone who contributed code, testing, documentation, and feedback. This article focuses on the main product changes; the complete contributor list is in the release notes.

*Image sources: the event-routing and runner-overview images come from the v4.11.0 GitHub Release. The other five screenshots were captured from an independently launched official `rockchin/langbot:v4.11.0` instance. Screenshots use English for consistent cross-language reference. No production bots were connected, and the demo screens are not presented as evidence of production task execution.*

---

# 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.

> info:
>
> The official Docker images come pre-equipped with minimal `ffmpeg` and `pilk` audio tools. Native voice transcoding (including SILK for WeChat) is supported out-of-the-box without extra host configuration.

## 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.

### Optional Voice Transcoding Support (SILK / WeChat Native Voice)

If you need native voice bubbles on platforms like WeChat (SILK encoding) or audio transcoding support, install system `ffmpeg` and the `audio` extra:

- **System Dependency**: `ffmpeg` (macOS: `brew install ffmpeg`, Ubuntu/Debian: `sudo apt-get install -y ffmpeg`, Windows: `winget install Gyan.FFmpeg`)
- **Python Extra**:
  ```bash
  uv sync --extra audio
  # or combine with seekdb
  uv sync --extra seekdb --extra audio
  ```

If transcoding dependencies are not installed, LangBot performs **graceful degradation** by delivering the audio as a playable audio file attachment rather than dropping the message.

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.

## Optional Voice Transcoding Support (SILK / WeChat Native Voice)

If you need native voice bubbles on platforms like WeChat (SILK encoding) or audio transcoding support, make sure `ffmpeg` is installed on your system and launch LangBot with the `audio` extra:

```bash
uvx --from 'langbot[audio]@latest' langbot
# or combine with seekdb
uvx --from 'langbot[seekdb,audio]@latest' langbot
```

If transcoding dependencies (`ffmpeg` / `pilk`) are not installed, LangBot automatically performs **graceful degradation** by delivering the audio as an audio file attachment.

---

# 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 product telemetry (including heartbeats and execution records) and survey fetching. Use an unquoted YAML boolean. To restore the default, set it to `false` and restart. Cloud Plugin Runtime operational health reporting is controlled separately by `plugin.runtime_ops.enabled`.

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

Current 4.11 execution telemetry defaults to full reporting of eligible executions, covering platform events, routing, Pipeline / Agent / plugin event processors, and the platform API and tool calls they cause. Each completed node generates a record, followed by a closure record when the execution ends; Space reconstructs the chain. These are the defaults in the same `space` section; restart after changing them:

Platform events without a matching business route, or ignored by a `discard` rule with no matching plugin subscription, upload no execution records. Local logs and monitoring keep their existing behavior. Matching subscriptions, valid interaction resumptions and independent WebUI/API/Pipeline calls remain eligible, as do unavailable targets, execution failures or Pipeline filtering after a route matches. Eligibility is checked before sampling; neither Cloud's `all` nor failure fallback bypasses it. A Core upgrade is required.

```yaml
space:
  execution_trace: all        # off | failures | sampled | all
  execution_trace_sample: 20  # sampled: retain about 1/N successful executions by event hash
  telemetry_flush_seconds: 180  # Execution record buffer flush interval, in seconds
```

The community edition supports these modes:

| Mode       | Reporting behavior                                                                                                                                                               |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `all`      | Default; records nodes and closure records for every eligible execution                                                                                                          |
| `sampled`  | Makes one stable hash decision from the event identity for all records of that execution; excluded executions that fail still report a closure, without recovering skipped nodes |
| `failures` | Omits nodes for ordinary executions; reports closures only for failure, cancellation, timeout or a recorded chain failure reason                                                 |
| `off`      | Reports neither nodes nor closures; no independent window counters continue, while heartbeats remain controlled by `disable_telemetry`                                           |

WebUI debug runs are retained with a debug flag in `all`, `sampled` and `failures`; `off` or `disable_telemetry: true` stops their upload. **Cloud always uses `all` while product telemetry is enabled and does not apply the sampling mode configured above**; the instance operator can still disable product telemetry with the main switch.

`execution_trace_sample` accepts integers from 1 to 100000; `telemetry_flush_seconds` accepts integers from 1 to 86400. Invalid values fall back to 20 and 180 respectively, and an invalid mode falls back to `all`. Sampling does not select exactly every N-th execution in sequence.

Each flush sends at most 128 records and the buffer holds at most 512. Failed sends remain buffered for retries; a full buffer drops the oldest records, so full reporting does not guarantee complete delivery. Active Workspaces first send a heartbeat about 30 seconds after startup, then daily in ordinary deployments or every 5 minutes in Cloud runtime. Raw execution records are cleaned up in batches using a 30-day window; backlogs can delay deletion.

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).

---

# Enterprise Support

Source: https://langbot.app/docs/en/enterprise/overview

Official issue triage, security updates, and procurement-ready contracts and invoices for open-source LangBot.

LangBot Enterprise Support is for organizations that need an **official support relationship** and **formal procurement documents**. Your subscription also directly funds continued LangBot development.

> info:
>
> LangBot remains free under Apache License 2.0. Enterprise Support is **not a commercial-use license**: it unlocks no features and does not restrict organizations that don't subscribe.

## Plans

|                                                                        | Enterprise Support                                     | Enterprise Assurance          |
| ---------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------- |
| Annual fee (USD)                                                       | US$599                                                 | US$1,199                      |
| Best for                                                               | Funding the project with a formal support relationship | Running LangBot in production |
| Contract, invoice and annual certificate                               | ✓                                                      | ✓                             |
| Enterprise tickets, first response within 2 business days              | ✓                                                      | ✓                             |
| Critical security notices, quarterly release & security digest         | ✓                                                      | ✓                             |
| Annual 60-minute usage review                                          | 1                                                      | 1                             |
| Priority review of public roadmap proposals                            | ✓                                                      | ✓                             |
| Listing as an enterprise supporter (with consent; anonymity available) | ✓                                                      | ✓                             |
| Registered production instance                                         | —                                                      | 1                             |
| Remote technical consultations (60 min each)                           | —                                                      | 4 per year                    |
| Pre-upgrade compatibility advice, priority incident triage             | —                                                      | ✓                             |
| Confirmed Core defects enter the priority fix queue                    | —                                                      | ✓                             |
| Annual version, dependency and security status summary                 | —                                                      | ✓                             |

Fees are charged per contracting organization per year, not per seat or deployment. Taxes, invoice type and service dates follow the formal quote and contract.

## Next steps

- [Service scope and response](https://langbot.app/docs/en/enterprise/service-scope.md): what's included, what isn't, and how response time is counted
- [Submit a ticket](https://langbot.app/docs/en/enterprise/submit-ticket.md): how subscribers request support
- [Procurement and activation](https://langbot.app/docs/en/enterprise/procurement.md): contracts, invoices and deliverables

To subscribe, fill in the [inquiry form](https://langbot.app/en/enterprise#enterprise-contact) with your use case, industry, role and contact details. We reply within 1–2 business days.

---

# Procurement and activation

Source: https://langbot.app/docs/en/enterprise/procurement

Contracts, invoices and deliverables for Enterprise Support.

## How to subscribe

1. **Send an inquiry**: fill in the [inquiry form](https://langbot.app/en/enterprise#enterprise-contact) with your use case, industry, role and contact details. We reply within 1–2 business days.
2. **Confirm the quote**: agree on scope, taxes and invoicing, and sign an annual service contract.
3. **Pay and register**: pay as agreed and register contacts, Space accounts and service dates.
4. **Get started**: once you receive the certificate and service guide, [submit tickets](https://langbot.app/docs/en/enterprise/submit-ticket.md).

> info:
>
> For the first contact, your use case, industry, role and contact details are enough. Invoicing details come before signing. Never send bank or tax details through public tickets or GitHub.

## Contract and invoice

| Item                | Details                                                                                          |
| ------------------- | ------------------------------------------------------------------------------------------------ |
| Contracting entity  | The operating company behind LangBot; details are in the quote and contract                      |
| Subject             | Annual maintenance, release information and technical support for open-source LangBot            |
| Billing             | Annual fee per contracting organization, not per seat                                            |
| Invoice description | Confirmed by finance within the permitted scope, e.g. software service or technical support fees |

The fee is not invoiced as a donation or as a commercial software license fee.

## Deliverables

- Service order and contract with service dates and named contacts
- Annual subscription certificate (evidences the support relationship; grants no additional software license)
- Versioned service scope document, Space ticket access and account registration
- Assurance: production instance registration and consultation allowance
- During the term: quarterly maintenance digests, ticket and consultation records; Assurance also receives an annual version, dependency and security status summary

Listing as an enterprise supporter requires separate consent and can be anonymous. Later changes to the service documents don't alter signed contracts.

## Renewal

Renewal is confirmed separately; there is no automatic charge. Start, end, cancellation and refund terms follow the contract.

The subscription doesn't include LangBot Cloud compute, model credits or hosting. After expiry you can keep using LangBot under Apache 2.0.

---

# Service scope and response

Source: https://langbot.app/docs/en/enterprise/service-scope

What Enterprise Support covers, what it doesn't, and how first response time is calculated.

Enterprise Support focuses on **LangBot Core itself**. It provides triage and guidance through a single ticket channel, not managed operations or custom development.

## Included and not included

| Included                                           | Not included                                                             |
| -------------------------------------------------- | ------------------------------------------------------------------------ |
| LangBot Core defect assessment and triage          | Deployment, operations, 24/7 coverage, on-site service                   |
| Official documentation guidance                    | Troubleshooting your network, database, Kubernetes or model providers    |
| Upgrade compatibility advice                       | Maintenance of plugins, third-party adapters or private-protocol clients |
| Public release information and security advisories | Custom development, historical data migration                            |
| Ticket intake and triage                           | Recovery SLAs, fixed resolution deadlines, compliance certification      |

Custom work is outside the subscription and generally not accepted. Requests with broad value can be proposed on the public roadmap.

## First response

Both plans commit to a **first human response within 2 business days**. A first response means a person has confirmed the scope, requested more information, or given an initial classification. Automated emails don't count.

> warning:
>
> A first response is not a fix or recovery. Resolution depends on severity, reproducibility, and whether the issue belongs to LangBot Core.

- **Hours**: 09:00–18:00 Beijing time on mainland China business days, including make-up working days; public holidays are skipped.
- **Counting**: requests submitted during hours are counted from submission; requests outside hours start at 09:00 on the next business day.
- **Example**: submitted Friday 14:00 → response by Tuesday 14:00. Submitted Friday 20:00 → response by Wednesday 09:00.

## Supported versions

- Support covers the **current stable release** of LangBot Core. For older versions we first recommend upgrading, and confirming a defect may require reproducing it on the current release.
- No backports, LTS branches or private patches.
- Plugins and third-party components are outside Core maintenance.

## Consultations and allowances

|                                                        | Enterprise Support | Enterprise Assurance |
| ------------------------------------------------------ | ------------------ | -------------------- |
| Annual usage review (60 min)                           | 1                  | 1                    |
| Remote technical consultation (60 min, by appointment) | —                  | 4                    |

Unused sessions don't roll over. Enterprise Support covers ticket triage, documentation guidance and defect confirmation, not ongoing remote troubleshooting of your environment.

## Instance registration (Assurance)

- Assurance covers **1 registered production instance**. Registration only defines support scope; it doesn't limit deployments permitted by Apache 2.0 and requires no license key or telemetry.
- We record version, deployment overview, purpose and contacts. Update the registration through a ticket when you replace the instance.

## Security information

- Quarterly digests are based on public release and security information.
- Critical security notices are based on advisories confirmed by the maintainers; we don't determine whether your environment is affected.
- The annual status summary (Assurance) is based on your registered version and public information. It is not a security audit, penetration test or compliance certification.

## Working principles

- One ticket per issue; duplicates may be merged.
- The priority fix queue has no fixed deadline, and priority roadmap review is not a development or scheduling commitment.
- Support runs through tickets only, not one-to-one group chats.

## Service term

Language, contacts, service dates and the applicable version of this document are set in the contract. After expiry no new requests are accepted; open tickets are triaged or handed over as agreed. You can keep using open-source LangBot after expiry.

---

# Submit a ticket

Source: https://langbot.app/docs/en/enterprise/submit-ticket

How subscribers report issues or book consultations in LangBot Space.

> idea:
>
> [Open LangBot Space tickets →](https://space.langbot.app/profile?tab=tickets\&language=en)

## Steps

1. Sign in with the Space account registered in your contract.
2. Go to **Profile → Tickets** and pick a template:
   - **Enterprise Support: issue intake**: report a suspected LangBot Core defect
   - **Enterprise Support: upgrade and consultation**: upgrade compatibility, consultation booking (Assurance), documentation and procurement materials
3. Enter your subscription/contract ID and organization name, then complete the form.

We verify the contract, registered account and service term before confirming entitlements. A subscription ID alone doesn't prove identity.

## What to include

**Issue intake**

- LangBot version and deployment method
- Expected vs. actual behavior
- Reproduction steps
- Redacted logs (explain if unavailable)
- Business impact

**Upgrade and consultation**

- Registered instance and current version, target version if relevant
- Goals and context
- Preferred times, if a meeting is needed

> warning:
>
> Don't submit access tokens, passwords, full chat histories, personal data or raw configuration files. Redact screenshots. Never post vulnerability details in a public GitHub issue.

## After you submit

Once your subscription is verified, we triage the request and may:

- Point you to documentation or ask for more information
- Book a consultation (Assurance)
- Confirm a LangBot Core defect and move it into public maintenance
- Explain that the request is out of scope

For confirmed general defects, only the minimum redacted reproduction details go into public maintenance. Contracts, logs and business information are never synced to public GitHub. Please reply in the same ticket rather than opening duplicates elsewhere.

---

# 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://discord.gg/wdNEHETs87)

---

# Data Collection Policy

Source: https://langbot.app/docs/en/insight/data-collection-policy

Optional telemetry, execution chains, collected data and opt-out controls

LangBot sends product telemetry to the LangBot Space service configured by `space.url` (by default `https://space.langbot.app`) to understand usage and improve reliability. **Telemetry is enabled by default and can be disabled.** This page describes the current 4.11 execution telemetry protocol (`schema: 2`); older-version data is described separately below.

## Execution telemetry

An eligible execution consists of independent records sharing an `event_id`: one `execution_node` is generated when each workflow node completes, and one `execution_chain` when the execution closes. Core buffers records within a fixed limit and uploads them in background batches; Space reconstructs the execution chain. The current sender no longer uses legacy feature window counters or assembles a complete chain locally.

**Platform events without a matching business route, or whose selected route is `discard` with no matching plugin subscription, report neither nodes nor a closure.** Disabled routes and event-type/filter mismatches are included; local logs and monitoring keep their existing behavior. A matching plugin event processor still makes an execution eligible when the primary route misses. Unmatched and discarded branches do not contribute telemetry.

After a business route matches, unavailable targets, execution failures, timeouts and filtering inside a Pipeline remain reportable. Valid interaction callbacks resuming an original processor, WebUI/API debug runs and independent calls explicitly targeting a Pipeline also remain eligible; invalid callbacks do not independently qualify. Eligibility takes precedence over sampling and failure fallback, including in Cloud. This requires a Core upgrade and does not retroactively change older clients or historical records.

| Data                     | Contents                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identity and environment | `instance_id`, `workspace_uuid`, `event_id`, version, edition, timestamp, debug flag and sampling information                                                                                                                                                                                                                                                                                |
| Execution nodes          | Operation identifiers, processing mode, outcome, start/end times, parent/child relationships and sequence, routing target and Runner run identity for platform events, routing, Pipeline, Runner, platform API and tool calls                                                                                                                                                                |
| Chain closure            | Overall outcome, closure reason (`completed` when the inbound event and all downstream work queued for it finished; `merged` when message aggregation folded it into another chain, with `merged_into`; `timeout` when handed-off work did not report back within 30 minutes), duration, node count, nodes omitted by sampling, origin, model name, adapter, Runner and pipeline plugins     |
| Feature usage            | Per-execution integer counters in `features`: tool calls by source, sandbox executions and errors, knowledge-base retrieval attempts, skill activations and LLM attempts (including retries). Zero counters are omitted; each counter is capped at 65,535. No tool arguments, outputs or skill names are added by these counters                                                             |
| Bound resources          | Identifiers or names of plugins, MCP servers, knowledge bases, tools and their sources, skills, models and platform APIs granted to a Pipeline or Agent, plus selector fields, capabilities and permission flags; fields depend on the execution path                                                                                                                                        |
| Errors                   | A complete diagnostic description: exception class, message, the `Caused by` chain and the file, line and function of the last traceback frames (no source lines), capped at about 4,000 characters while keeping both ends. Common credential shapes (`sk-` keys, Bearer tokens, `api_key=`/`token=`/`password=` pairs, secret URL parameters) and email addresses are masked before upload |

Bound resources describe what an execution was configured or authorized to use. **They do not establish that those resources were actually called, searched or consumed.** Routing targets use `type:uuid`, not user-defined rule names.

`model_name` identifies the first LLM invoked in an execution, across Pipeline, Agent and event-processor paths, truncated to 128 UTF-8 bytes. Feature counters are included only in the existing chain closure; disabling telemetry or leaving `space.url` empty disables counting as well as upload.

Execution records do not intentionally collect message bodies, prompts, model replies, platform user/group IDs, or tool/API arguments or results. **Credential masking matches common formats and is not reliable redaction: exception messages (such as raw provider error text) and user-defined model, skill or resource names may still contain sensitive information or user content.** Instance and Workspace identifiers may be associated with deployments or accounts; these records are neither anonymous nor guaranteed to contain no user content.

### Sampling and debug runs

The community edition controls execution reporting with `space.execution_trace`:

| Mode            | Behavior                                                                                                                                                                                                                       |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `all` (default) | Records nodes and closure records for every eligible execution                                                                                                                                                                 |
| `sampled`       | Makes one stable hash decision from the event identity at ingress; retains approximately `1/N` successful executions, where N is `space.execution_trace_sample` (default 20); every record of an execution shares the decision |
| `failures`      | Omits nodes for ordinary executions and reports a closure only for failure, cancellation, timeout or a recorded chain failure reason                                                                                           |
| `off`           | Disables node and closure records; no independent window counters continue, while Workspace heartbeats remain controlled by the main telemetry switch                                                                          |

If an execution excluded by `sampled` fails, its closure is still reported. Previously skipped nodes are not recovered, so a failure may have a summary without a complete chain. WebUI debug runs are retained in `all`, `sampled` and `failures` with a debug flag; neither `off` nor the main opt-out permits their upload.

**Cloud always uses `all` while product telemetry is enabled**, so sampling successful executions does not distort activity counts. The instance operator can still disable the product telemetry described here with `space.disable_telemetry`.

### Delivery and completeness

Records are sent to `POST /api/v1/telemetry`. The default flush interval is 180 seconds, configurable through `space.telemetry_flush_seconds`. Each flush sends at most 128 records and the memory buffer holds at most 512. Records are removed only after an accepted send; failed sends are retried, and a full buffer drops the oldest records. Shutdown attempts to flush remaining records within a limited time.

Network failures, timeouts and server errors do not fail business execution because telemetry failed; upload failure details are logged at DEBUG level. Sampling, buffer overflow, process exit or expired cross-task associations can leave incomplete chains. **Full reporting does not guarantee complete delivery.** A successful platform API response does not prove that a user read a message.

## Heartbeats, surveys and older-version data

Active Workspaces first send an `instance_heartbeat` about 30 seconds after startup. Ordinary deployments send daily thereafter; Cloud runtime refreshes every 5 minutes. Heartbeats include deployment platform, database/vector-database kinds, sandbox configuration and availability, adapter types and counts of resources such as bots, Pipelines, plugins, Agents, event processors, event bindings, MCP servers, knowledge bases and skills. They do not intentionally include resource contents or connection credentials.

Optional in-app surveys send the survey ID, submitted answers, instance ID, version and completion/dismissal status. Survey answers are content voluntarily provided by users.

Space remains compatible with older `query` and `feature_execution` data. Legacy query records may contain model names, feature counters, user-defined skill/MCP names and raw traceback text. The current execution-record restrictions neither sanitize historical data nor change uploads from older clients still running.

## Storage and retention

Data is stored by the configured Space service. Execution lists, chain details and summaries are restricted to authorized telemetry management users or service clients. Raw `execution_node`, `execution_chain` and legacy `feature_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, heartbeats, surveys, accounts or service logs.

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 the product telemetry described on this page and 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.

Cloud Plugin Runtime operational health reporting is separate from product telemetry. It is controlled by `plugin.runtime_ops.enabled` and is not disabled by `space.disable_telemetry`.

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
> Read https://langbot.app/llms.txt first and follow its official guidance to help me deploy and use LangBot, install the LangBot CLI, and configure and manage my instance with the CLI. Adapt to my goals and environment, reuse an existing instance when possible, and verify a real message and reply on my target messaging platform. Respond in English.
> ```

---

# 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.

See [LLM request configuration](https://langbot.app/docs/en/plugin/dev/apis/llm-requests.md) for retries, timeouts, numeric reasoning budgets, prompt caching, headers and stream cancellation.

## 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).

See [LLM request configuration](https://langbot.app/docs/en/plugin/dev/apis/llm-requests.md) for retries, timeouts, numeric reasoning budgets, prompt caching, headers and stream cancellation.

> info:
>
> Most methods on this page need a capability that your plugin declares in `manifest.yaml` and a Workspace member grants after installation, for example `models.invoke` for `invoke_llm` or `bot.message.send` for `send_message`. Calls without the grant fail with `permission_denied`. See [Plugin permissions](https://langbot.app/docs/en/plugin/dev/permissions.md#capabilities) for which capability each method needs. To manage Agents, Pipelines, bots and other Workspace resources, use the [Workspace API](https://langbot.app/docs/en/plugin/dev/apis/workspace.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.

---

# LLM request configuration

Source: https://langbot.app/docs/en/plugin/dev/apis/llm-requests

Retries, deadlines, reasoning budgets, caching and stream cancellation for plugins and Runners

These options require a Core build containing [Core #2661](https://github.com/langbot-app/LangBot/pull/2661). A merged PR does not imply a published release. Pass them through the existing `extra_args`; plugin and Runner signatures, message types and authorization remain unchanged. See [LangBot API](https://langbot.app/docs/en/plugin/dev/apis/common.md) and [Context APIs](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md).

## Retries and timeouts

The following non-streaming example configures the request and reads complete 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!")],
    timeout=110,
    extra_args={
        "request_policy": {
            "retries": 1,
            "total_timeout": 90,
            "first_event_timeout": 30,
            "stream_idle_timeout": 30,
            "connect_timeout": 10,
            "read_timeout": 60,
        },
    },
)
print(result.message.content)
if result.usage is not None:
    print(result.usage.model_dump())
```

Runner `ctx.api.invoke_llm*` accepts the same `extra_args`, subject to run authorization and remaining time. Calls through `self.plugin` also inherit these restrictions inside a run context.

`timeout=` is the SDK/RPC waiting limit (120 seconds by default for non-streaming calls). Core's `request_policy` controls the inner request. Keep its total budget within the enclosing RPC/Runner deadline; raising it cannot extend that deadline. Streaming methods have no `timeout=` argument and remain bounded by SDK/Runner waiting limits.

| `request_policy` field         | Default     | Meaning                                                       |
| ------------------------------ | ----------- | ------------------------------------------------------------- |
| `retries`                      | `0`         | Additional attempts after the first, integer 0–5              |
| `total_timeout`                | `300`       | Whole invocation budget, including backoff                    |
| `first_event_timeout`          | `120`       | Wait for the first upstream event, not the first visible text |
| `stream_idle_timeout`          | `120`       | Idle time between stream events                               |
| `connect_timeout`              | `10`        | Connection timeout                                            |
| `read_timeout`                 | `120`       | Transport read timeout                                        |
| `write_timeout`                | `30`        | Transport write timeout                                       |
| `pool_timeout`                 | `10`        | Connection pool acquisition timeout                           |
| `backoff_base` / `backoff_max` | `0.5` / `8` | Exponential backoff base and cap, with full jitter            |
| `attribution`                  | `True`      | Automatic application attribution headers                     |
| `conversation_header`          | `None`      | Generated session header name, described below                |

Times are seconds; timeouts must be finite and positive. Unknown policy fields are rejected. Precedence: instance `llm_request_policy`, model `extra_args`, then call `extra_args`. Within one layer, `request_policy.retries` wins over legacy `num_retries` / `max_retries`. A call-level legacy value still overrides model policy; `0` disables retries. Legacy numeric `extra_args["timeout"]` sets read, first-event and stream-idle limits without extending the total budget.

Authentication, invalid-request and exhausted-quota failures are not retried. Retries stop after any upstream event, including reasoning or usage. `Retry-After` is bounded by the remaining budget. Core disables LiteLLM and provider SDK retries for managed calls; gateways may independently retry. This adds no tool replay, model fallback or embedding/rerank retries. Legacy third-party requesters still own their transport configuration.

## Reasoning budgets

Existing `reasoning_level` behavior is unchanged. For a numeric budget, pass this object as `extra_args` or save it in model advanced parameters. Omitting `level` means `enabled`:

```json
{
  "reasoning_config": {"budget_tokens": 2048},
  "max_tokens": 4096
}
```

Do not combine a budget with an effort level such as `medium`, `disabled`, or native reasoning parameters. Direct Anthropic calls require explicit `max_tokens` greater than the budget; Core never raises that limit automatically.

Precedence: persisted model `reasoning_config`, model `extra_args.reasoning_config`, call `extra_args.reasoning_config`, then an explicit Runner level override. Each object replaces the previous one; an effort override clears a lower-priority budget.

Numeric budgets map to native Anthropic, Gemini 2.5, supported Qwen models and OpenRouter routes. Direct OpenAI/Codex and adaptive-only Claude models retain effort control. Check the model's `reasoning_capabilities.budget_tokens` for support and bounds. Unsupported budgets fail before HTTP. Providers/gateways may impose stricter limits; OpenRouter may translate a numeric budget into effort.

## Prompt caching

`extra_args.prompt_caching` is consumed by Core, not forwarded unchanged. Call configuration replaces model configuration. The default `{"mode": "provider_default"}` adds no fields. This is not a local response cache.

| Configuration                                  | Behavior                                                                                                                                                          |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{"mode": "openai", "retention": "in_memory"}` | Generates a model-and-conversation-scoped `prompt_cache_key` when conversation context exists; optional `retention` also accepts `24h` if supported by the target |
| `{"mode": "anthropic", "ttl": "5m"}`           | Adds an ephemeral breakpoint to the last text block of the leading system/developer prefix; `ttl` accepts `5m` or `1h`                                            |

OpenAI mode applies to compatible routes and OpenRouter OpenAI models supporting these options. Explicit native `prompt_cache_key`, `prompt_cache_retention` and `prompt_cache_options` win. Anthropic mode supports native Claude and OpenRouter Claude. Existing native cache markers are preserved without adding duplicates. Core does not reorder tools/history or mark user messages, and inserts nothing without an eligible prefix.

Hints do not guarantee hits. Inspect `usage.model_dump()` for provider fields such as `prompt_tokens_details.cached_tokens` or `cache_read_input_tokens`; missing counts are not zero. Minimum prefix lengths, retention eligibility and pricing are provider-controlled. Codex's restricted Responses body does not accept this configuration object; existing server caching remains. General Responses migration and Gemini explicit cache-resource management are outside this change.

## Application and session headers

Direct OpenRouter calls receive `HTTP-Referer: https://langbot.app`, `X-OpenRouter-Title: LangBot`, and, with conversation context, `x-session-id: lb-<opaque scoped hash>`. Custom gateway addresses do not automatically inherit these headers. `request_policy.attribution=False` disables only automatic application attribution. Explicit `extra_headers` remain and take precedence case-insensitively.

A gateway can use an explicitly configured session header:

```json
{
  "request_policy": {"conversation_header": "x-litellm-session-id"},
  "extra_headers": {
    "HTTP-Referer": "https://langbot.app",
    "X-OpenRouter-Title": "LangBot"
  }
}
```

Supported names: `x-session-id`, `x-litellm-session-id`, `x-langbot-conversation-id`. The last is a custom convention, not a universal provider standard, and provides no automatic routing or caching benefit. Generated identifiers are scoped by workspace/bot/pipeline/session and contain no raw session ID or prompt. They are pseudonymous, not a guarantee of anonymization, and are omitted without context. New API and other gateways may filter or rewrite headers; verify forwarding rules and actual outbound requests.

## Stream cancellation and compatibility

Use `aclosing` when leaving a stream early. Allow task cancellation exceptions to propagate:

```python
from contextlib import aclosing
from langbot_plugin.api.entities.builtin.provider.message import Message

async with aclosing(self.plugin.invoke_llm_stream_events(
    llm_model_uuid=model_uuid,
    messages=[Message(role="user", content="Hello!")],
    extra_args={"request_policy": {"retries": 0, "total_timeout": 90}},
)) as events:
    async for event in events:
        if event.usage is not None:
            print(event.usage.model_dump())
        if event.chunk is not None and event.chunk.content:
            print(event.chunk.content)
            break
```

This example intentionally stops after the first nonempty content chunk and may miss final usage. For a complete response, remove `break`; a final event can have usage without a chunk. `invoke_llm` still returns `Message`, and `invoke_llm_stream` still yields `MessageChunk`. Choose `invoke_llm_with_usage` or `invoke_llm_stream_events` for accounting. Usage may be `None`; nested cache/reasoning counts and provider-specific fields are preserved.

SDK ≤0.7.11 has a proxy-layer defect that delays upstream cancellation on early close. Deterministic close requires **langbot-plugin ≥0.7.12**, which publishes the fix from [SDK #177](https://github.com/langbot-app/langbot-plugin-sdk/pull/177). A Core dependency pin does not automatically upgrade a separately deployed Runtime or plugin development environment; upgrade those executing environments too. Ordinary signatures, payloads and return types remain compatible. Total deadlines include consumer time, but cannot interrupt a consumer while the generator is suspended at `yield`; expiration is enforced on the next pull.

## Diagnostics

Core monitoring records expose `details.timing`, complete `usage` and structured `error`; legacy SDK exception transport is unchanged. Structured errors include `code`, `status_code`, `retryable`, `retry_after`, `request_id` and `phase`. Do not assume these fields exist on legacy exceptions received by plugins.

Millisecond timings include `preparation_ms`, `transport_setup_ms`, `first_event_ms`, `first_reasoning_ms`, `first_content_ms`, `first_visible_chunk_ms`, `total_ms`, plus `attempts` and `retry_wait_ms`. The first event may be reasoning/control, and the first visible chunk may include reasoning. `request_started_ms` marks the SDK call, not a packet leaving the socket. Missing fields mean unobserved, not zero. Monitoring retains partial usage received before cancellation but cannot reconstruct missing upstream accounting.

---

# 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.

#### How it shows up in monitoring

When a plugin calls `prevent_default()` on a message event to take the message over, LangBot's monitoring marks the message as "Handled by plugin author/name", and the pipeline's Runner is no longer shown as its handler. What the plugin sends while handling the event is recorded too:

- Replies sent with `event_context.reply()` are recorded as replies to the message. A failed send records a `PluginReplyError` error.
- Messages sent with `self.plugin.send_message()` are recorded as plugin-sent messages. A failed send records a `PluginSendError` error.
- Calls to `self.plugin.invoke_llm()` / `invoke_llm_stream()` are recorded as LLM calls.

Linking the plugin's messages and LLM calls to the triggering message needs a Plugin Runtime (`langbot-plugin`) that supports event origin attribution. Older Runtimes still get these records, without the link. Background work that runs after the handler returns is not linked to the message.

---

# 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.

## Send messages, replies, and threads

The standard `send_message` API returns a `MessageResult`, whose `message_id` identifies the sent message when the platform provides one. `self.plugin.send_message()` returns its serialized dictionary, so read `result["message_id"]` rather than an object attribute. The ID may be `None` or empty when the platform does not return one.

Use the standard `Quote` component to express a reply or thread reference in a message chain. `Quote.id` is the referenced message or thread root ID; `origin` is the quoted message chain and may be empty. Support and reply/thread behavior depend on the adapter. For example, Slack returns the message `ts` as `message_id`, sends a chain with `Quote(id=ts)` into that thread, and appends `Quote(id=thread_ts)` to inbound channel thread replies. This uses standard message APIs, not a Slack-specific action.

```python
from langbot_plugin.api.entities.builtin.platform.message import MessageChain, Plain, Quote

result = await self.plugin.send_message(
    bot_uuid=bot_uuid,
    target_type="group",
    target_id=group_id,
    message_chain=MessageChain([Plain(text="Support request")]),
)
message_id = result.get("message_id") if result else None
if message_id is not None and message_id != "":
    await self.plugin.send_message(
        bot_uuid=bot_uuid,
        target_type="group",
        target_id=group_id,
        message_chain=MessageChain([
            Plain(text="Follow-up"),
            Quote(id=message_id, origin=MessageChain([])),
        ]),
    )
```

Use IDs from the same bot and conversation. `Quote` preserves reference metadata in serialization but adds no text to `str(message_chain)`, so it does not change command or keyword matching.

## 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.

---

# Workspace API

Source: https://langbot.app/docs/en/plugin/dev/apis/workspace

Read and manage Agents, Pipelines, bots, models, knowledge bases and more from a plugin.

The Workspace API lets a plugin work with the Workspace it is installed in: list and edit Agents and Pipelines, look up bots, manage models and knowledge bases, read monitoring data, and so on. It exposes the same operations as LangBot's HTTP API, MCP server and Workspace assistant, so a plugin can automate anything a member could do through those interfaces, within the limits the member grants.

Every operation has a stable ID, such as `pipeline.list` or `knowledge.base.retrieve`. A plugin can only call operations it [declares in its manifest](https://langbot.app/docs/en/plugin/dev/permissions.md#declare-permissions) and a member has granted to its installation.

## Calling an operation

From any component, use `self.plugin.workspace`. Each operation has a typed method named after its ID:

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


class WorkspaceSummary(Tool):
    async def call(self, params, session, query_id):
        result = await self.plugin.workspace.pipeline.list()
        if not result["ok"]:
            return f"Could not list pipelines: {result['error']['message']}"

        names = [pipeline["name"] for pipeline in result["result"]]
        return "Pipelines: " + ", ".join(names)
```

Methods take keyword arguments that match the operation's input schema, and editors show their types and documentation. A few names are adjusted to be valid Python: a segment that is a Python keyword gets a trailing underscore (for example `import_`), and other invalid characters become underscores. The arguments are still sent under their original names.

If you prefer to choose the operation at runtime, call it by ID. Both forms behave identically:

```python
result = await self.plugin.workspace.call("knowledge.base.retrieve", kb_uuid=kb_uuid, query="refund policy")
```

`await self.plugin.workspace.list()` returns the operations granted to the installation, with their input schemas, grouped into `domains`. It is useful for building a dynamic tool list or checking a grant before offering a feature.

### Inside a Runner

A Runner receives a run-bound proxy as `ctx.api.workspace`. It offers the same methods and is authorized by the same installation grants; the difference is that LangBot records each call against the current run.

The Agent or Pipeline that started the run may restrict which workspace operations the model should see. That selection is delivered in `ctx.resources.workspace_operations`. A Runner that exposes workspace operations to a model as tools should offer only those, and offer none when the list is empty. LangBot's built-in LocalAgent does exactly this.

## Results and errors

Workspace calls never raise for business errors. They always return a dictionary:

```python
# Success
{"ok": True, "result": ..., "operation": {"id": "pipeline.list", ...}}

# Failure
{"ok": False, "error": {"code": "permission_denied", "message": "...", "details": {...}}}
```

Check `ok` before reading `result`. Common error codes:

| Code                | Meaning                                                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `permission_denied` | The operation is not granted to this installation, or the installation is disabled. `details.denied_operations` lists the missing IDs. |
| `invalid_input`     | The arguments do not match the operation's input schema.                                                                               |
| `not_found`         | The referenced resource does not exist in this Workspace.                                                                              |
| `application_error` | The operation ran and failed; `message` explains why.                                                                                  |

A denied operation is an expected outcome, because members may grant only part of what a plugin declares. Handle it by explaining what is missing rather than failing the whole command or run.

## Choosing operations to declare

Operations carry a risk level that the member sees when confirming:

- **Read** operations only return data, such as `pipeline.list` or `stats.basic`.
- **Write** operations change Workspace configuration, such as `pipeline.update` or `knowledge.file.store`.
- **High-risk** operations delete resources, reach outside LangBot, or consume significant resources, such as `bot.delete` or `pipeline.chat.broadcast`. The confirmation dialog highlights them.

The member who grants an operation must hold its permission themselves (the last column below). Ask only for what your plugin needs; a request for many high-risk operations is likely to be declined or trimmed.

Wildcards such as `knowledge.*` request every operation under a prefix. Not every prefix can be used this way; see [Wildcards](https://langbot.app/docs/en/plugin/dev/permissions.md#wildcards).

## Operation reference

This reference covers every operation a plugin can request in the current LangBot version, grouped by domain. Methods are shown on `workspace`, which is `self.plugin.workspace` in components and `ctx.api.workspace` in a Runner. The SDK's typed methods are generated from this catalog, so every operation listed here is available as a method.

### Adapter (`adapter`)

| Operation                                                             | ID and method                             | Risk | Granting member needs |
| --------------------------------------------------------------------- | ----------------------------------------- | ---- | --------------------- |
| Get Adapter Get configuration schema and requirements for an adapter. | `adapter.get` `workspace.adapter.get()`   | Read | `resource.view`       |
| List Adapters List available chat platform adapters in the workspace. | `adapter.list` `workspace.adapter.list()` | Read | `resource.view`       |

### Agent (`agent`)

| Operation                                                                  | ID and method                                       | Risk      | Granting member needs |
| -------------------------------------------------------------------------- | --------------------------------------------------- | --------- | --------------------- |
| Create Agent Create a new autonomous AI agent in the workspace.            | `agent.create` `workspace.agent.create()`           | Write     | `resource.manage`     |
| Debug Agent Execute a test turn on an agent for debugging purposes.        | `agent.debug` `workspace.agent.debug()`             | Write     | `runtime.operate`     |
| Delete Agent Delete an autonomous AI agent from the workspace.             | `agent.delete` `workspace.agent.delete()`           | High risk | `resource.manage`     |
| Get Agent Get full configuration and parameters for an AI agent.           | `agent.get` `workspace.agent.get()`                 | Read      | `resource.view`       |
| List Agents List all autonomous AI agents configured in the workspace.     | `agent.list` `workspace.agent.list()`               | Read      | `resource.view`       |
| Agent Metadata Get supported agent capabilities, model types, and schemas. | `agent.metadata` `workspace.agent.metadata()`       | Read      | `resource.view`       |
| Get Run Events Fetch step-by-step trace events for an agent execution run. | `agent.runs.events` `workspace.agent.runs.events()` | Read      | `resource.view`       |
| List Agent Runs List historical execution runs for an agent or processor.  | `agent.runs.list` `workspace.agent.runs.list()`     | Read      | `resource.view`       |
| Update Agent Update configuration, model, or prompts of an agent.          | `agent.update` `workspace.agent.update()`           | Write     | `resource.manage`     |

### Bot (`bot`)

| Operation                                                                      | ID and method                                                     | Risk      | Granting member needs |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- | --------- | --------------------- |
| List Bot Admins List platform users configured as administrators for a bot.    | `bot.admins.list` `workspace.bot.admins.list()`                   | Read      | `resource.view`       |
| Create Bot Create a new chat bot connected to an IM adapter.                   | `bot.create` `workspace.bot.create()`                             | Write     | `resource.manage`     |
| Delete Bot Delete a chat bot and remove its adapter connection.                | `bot.delete` `workspace.bot.delete()`                             | High risk | `resource.manage`     |
| Get Bot Get detailed configuration and status for a specific bot.              | `bot.get` `workspace.bot.get()`                                   | Read      | `resource.view`       |
| Apply Group Filter Apply group filtering rules to enable or disable pipelines. | `bot.group_filter.apply` `workspace.bot.group_filter.apply()`     | Write     | `resource.manage`     |
| Preview Group Filter Preview chat group filtering rules for a bot.             | `bot.group_filter.preview` `workspace.bot.group_filter.preview()` | Read      | `resource.manage`     |
| List Bots List all configured chat bots in the workspace.                      | `bot.list` `workspace.bot.list()`                                 | Read      | `resource.view`       |
| Bot Logs Fetch runtime connection logs and events for a bot.                   | `bot.logs` `workspace.bot.logs()`                                 | Read      | `resource.view`       |
| Send Bot Message Send an outbound message to a chat user or group via a bot.   | `bot.message.send` `workspace.bot.message.send()`                 | High risk | `runtime.operate`     |
| Test Bot Message Test bot messaging capability by sending a test message.      | `bot.message.test` `workspace.bot.message.test()`                 | Write     | `resource.manage`     |
| Preview Routes Preview message routing decisions for a simulated event.        | `bot.routes.preview` `workspace.bot.routes.preview()`             | Read      | `resource.manage`     |
| Routing Status Get active message routing bindings and rules for a bot.        | `bot.routes.status` `workspace.bot.routes.status()`               | Read      | `resource.view`       |
| Bot Runtime Status Inspect live connection state and health of a bot.          | `bot.runtime.get` `workspace.bot.runtime.get()`                   | Read      | `resource.view`       |
| Update Bot Update settings or pipeline bindings for an existing bot.           | `bot.update` `workspace.bot.update()`                             | Write     | `resource.manage`     |

### Extension (`extension`)

| Operation                                                                         | ID and method                                 | Risk | Granting member needs |
| --------------------------------------------------------------------------------- | --------------------------------------------- | ---- | --------------------- |
| List All Extensions List all available plugins, MCP servers, and skills combined. | `extension.list` `workspace.extension.list()` | Read | `resource.view`       |

### Knowledge Base (`knowledge`)

| Operation                                                                               | ID and method                                                                       | Risk      | Granting member needs |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------- | --------------------- |
| Create Knowledge Base Create a new knowledge base with storage and vector engine.       | `knowledge.base.create` `workspace.knowledge.base.create()`                         | Write     | `resource.manage`     |
| Delete Knowledge Base Permanently delete a knowledge base and indexed documents.        | `knowledge.base.delete` `workspace.knowledge.base.delete()`                         | High risk | `resource.manage`     |
| Get Knowledge Base Get configuration and indexing status of a knowledge base.           | `knowledge.base.get` `workspace.knowledge.base.get()`                               | Read      | `resource.view`       |
| List Knowledge Bases List all knowledge bases configured in the workspace.              | `knowledge.base.list` `workspace.knowledge.base.list()`                             | Read      | `resource.view`       |
| Retrieve Knowledge Chunks Search and retrieve relevant text chunks from knowledge base. | `knowledge.base.retrieve` `workspace.knowledge.base.retrieve()`                     | Read      | `resource.view`       |
| Update Knowledge Base Update configuration or description of a knowledge base.          | `knowledge.base.update` `workspace.knowledge.base.update()`                         | Write     | `resource.manage`     |
| Engine Creation Schema Get configuration schema required to create an engine.           | `knowledge.engine.creation_schema` `workspace.knowledge.engine.creation_schema()`   | Read      | `resource.view`       |
| List Knowledge Engines List available storage and vector retrieval engine types.        | `knowledge.engine.list` `workspace.knowledge.engine.list()`                         | Read      | `resource.view`       |
| Engine Retrieval Schema Get parameter schema for retrieving from an engine.             | `knowledge.engine.retrieval_schema` `workspace.knowledge.engine.retrieval_schema()` | Read      | `resource.view`       |
| Delete Knowledge File Delete an indexed document from a knowledge base.                 | `knowledge.file.delete` `workspace.knowledge.file.delete()`                         | High risk | `resource.manage`     |
| List Knowledge Files List all documents indexed within a knowledge base.                | `knowledge.file.list` `workspace.knowledge.file.list()`                             | Read      | `resource.view`       |
| Store Knowledge File Index and store a document into a knowledge base.                  | `knowledge.file.store` `workspace.knowledge.file.store()`                           | Write     | `resource.manage`     |
| List Document Parsers List supported document parser formats and capabilities.          | `knowledge.parser.list` `workspace.knowledge.parser.list()`                         | Read      | `resource.view`       |

### MCP (`mcp`)

| Operation                                                                               | ID and method                                                 | Risk      | Granting member needs |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --------- | --------------------- |
| List MCP Resources List all resources exposed by connected MCP servers.                 | `mcp.resource.list` `workspace.mcp.resource.list()`           | Read      | `resource.view`       |
| Read MCP Resource Read contents of a specific resource from an MCP server.              | `mcp.resource.read` `workspace.mcp.resource.read()`           | Read      | `resource.view`       |
| List MCP Resource Templates List parameterized resource URI templates from MCP servers. | `mcp.resource.templates` `workspace.mcp.resource.templates()` | Read      | `resource.view`       |
| Delete MCP Server Disconnect and delete an MCP server from the workspace.               | `mcp.server.delete` `workspace.mcp.server.delete()`           | High risk | `resource.manage`     |
| Get MCP Server Get configuration and parameters of a specific MCP server.               | `mcp.server.get` `workspace.mcp.server.get()`                 | Read      | `resource.view`       |
| List MCP Servers List configured Model Context Protocol (MCP) servers.                  | `mcp.server.list` `workspace.mcp.server.list()`               | Read      | `resource.view`       |
| MCP Server Logs Retrieve communication and error logs for an MCP server.                | `mcp.server.logs` `workspace.mcp.server.logs()`               | Read      | `audit.view`          |
| MCP Server Runtime Inspect live health and session state of an MCP server.              | `mcp.server.runtime` `workspace.mcp.server.runtime()`         | Read      | `resource.view`       |
| Test MCP Server Connection Test connectivity and ping an MCP server configuration.      | `mcp.server.test` `workspace.mcp.server.test()`               | Write     | `resource.manage`     |

### Model (`model`)

| Operation                                                                               | ID and method                                                                     | Risk      | Granting member needs    |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | --------- | ------------------------ |
| Create Embedding Model Configure and add a new embedding model to the workspace.        | `model.embedding.create` `workspace.model.embedding.create()`                     | Write     | `provider_secret.manage` |
| Delete Embedding Model Delete an embedding model configuration from the workspace.      | `model.embedding.delete` `workspace.model.embedding.delete()`                     | High risk | `resource.manage`        |
| Get Embedding Model Get configuration and parameters of an embedding model.             | `model.embedding.get` `workspace.model.embedding.get()`                           | Read      | `resource.view`          |
| List Embedding Models List all text embedding models configured in the workspace.       | `model.embedding.list` `workspace.model.embedding.list()`                         | Read      | `resource.view`          |
| List Embeddings by Provider List embedding models configured under a specific provider. | `model.embedding.list_by_provider` `workspace.model.embedding.list_by_provider()` | Read      | `resource.view`          |
| Test Embedding Model Test vector generation and connectivity for embedding model.       | `model.embedding.test` `workspace.model.embedding.test()`                         | Write     | `provider_secret.manage` |
| Update Embedding Model Update configuration and parameters of an embedding model.       | `model.embedding.update` `workspace.model.embedding.update()`                     | Write     | `provider_secret.manage` |
| Create LLM Model Configure and add a new LLM model to the workspace.                    | `model.llm.create` `workspace.model.llm.create()`                                 | Write     | `provider_secret.manage` |
| Get Default LLM Model Get workspace default large language model configuration.         | `model.llm.default.get` `workspace.model.llm.default.get()`                       | Read      | `resource.manage`        |
| Delete LLM Model Delete an LLM model configuration from the workspace.                  | `model.llm.delete` `workspace.model.llm.delete()`                                 | High risk | `resource.manage`        |
| Get LLM Model Get configuration and parameters of a specific LLM model.                 | `model.llm.get` `workspace.model.llm.get()`                                       | Read      | `resource.view`          |
| List LLM Models List all configured large language models in the workspace.             | `model.llm.list` `workspace.model.llm.list()`                                     | Read      | `resource.view`          |
| List LLMs by Provider List LLM models configured under a specific model provider.       | `model.llm.list_by_provider` `workspace.model.llm.list_by_provider()`             | Read      | `resource.view`          |
| Get Starred LLM Model Get the starred favorite LLM model of the workspace.              | `model.llm.starred.get` `workspace.model.llm.starred.get()`                       | Read      | `resource.view`          |
| Set Starred LLM Model Designate a specific LLM model as the starred favorite.           | `model.llm.starred.set` `workspace.model.llm.starred.set()`                       | Write     | `provider_secret.manage` |
| Test LLM Model Test connectivity and response generation for an LLM model.              | `model.llm.test` `workspace.model.llm.test()`                                     | Write     | `provider_secret.manage` |
| Update LLM Model Update configuration and parameters of an LLM model.                   | `model.llm.update` `workspace.model.llm.update()`                                 | Write     | `provider_secret.manage` |
| Create Rerank Model Configure and add a new rerank model to the workspace.              | `model.rerank.create` `workspace.model.rerank.create()`                           | Write     | `provider_secret.manage` |
| Delete Rerank Model Delete a rerank model configuration from the workspace.             | `model.rerank.delete` `workspace.model.rerank.delete()`                           | High risk | `resource.manage`        |
| Get Rerank Model Get configuration and parameters of a rerank model.                    | `model.rerank.get` `workspace.model.rerank.get()`                                 | Read      | `resource.view`          |
| List Rerank Models List all document reranking models in the workspace.                 | `model.rerank.list` `workspace.model.rerank.list()`                               | Read      | `resource.view`          |
| List Reranks by Provider List rerank models configured under a specific provider.       | `model.rerank.list_by_provider` `workspace.model.rerank.list_by_provider()`       | Read      | `resource.view`          |
| Test Rerank Model Test connectivity and scoring capability of a rerank model.           | `model.rerank.test` `workspace.model.rerank.test()`                               | Write     | `provider_secret.manage` |
| Update Rerank Model Update configuration and parameters of a rerank model.              | `model.rerank.update` `workspace.model.rerank.update()`                           | Write     | `provider_secret.manage` |

### Monitoring (`monitoring`)

| Operation                                                                                 | ID and method                                                           | Risk      | Granting member needs |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------- | --------------------- |
| Embedding Call Metrics Query embedding generation metrics and latency statistics.         | `monitoring.embedding_calls` `workspace.monitoring.embedding_calls()`   | Read      | `resource.view`       |
| Error Logs Query runtime errors and failures across bots and pipelines.                   | `monitoring.errors` `workspace.monitoring.errors()`                     | Read      | `resource.view`       |
| Execution Details Get detailed traces and step execution events for a specific execution. | `monitoring.execution.detail` `workspace.monitoring.execution.detail()` | Read      | `resource.view`       |
| List Executions Query execution history records across bots, pipelines, and agents.       | `monitoring.executions` `workspace.monitoring.executions()`             | Read      | `resource.view`       |
| List User Feedback List user ratings and feedback records on bot responses.               | `monitoring.feedback.list` `workspace.monitoring.feedback.list()`       | Read      | `resource.view`       |
| Feedback Statistics Get aggregated positive and negative user feedback metrics.           | `monitoring.feedback.stats` `workspace.monitoring.feedback.stats()`     | Read      | `resource.view`       |
| In-Flight Executions Inspect currently active in-flight requests and pipeline runs.       | `monitoring.inflight` `workspace.monitoring.inflight()`                 | Read      | `resource.view`       |
| LLM Call Metrics Query model invocation counts, latencies, and token stats.               | `monitoring.llm_calls` `workspace.monitoring.llm_calls()`               | Read      | `resource.view`       |
| Message Details Retrieve full metadata and trace details for a single message.            | `monitoring.message.detail` `workspace.monitoring.message.detail()`     | Read      | `resource.view`       |
| Query Messages Query processed chat messages across bot sessions.                         | `monitoring.messages` `workspace.monitoring.messages()`                 | Read      | `resource.view`       |
| Monitoring Overview Get aggregated monitoring overview statistics for bots and pipelines. | `monitoring.overview` `workspace.monitoring.overview()`                 | Read      | `resource.view`       |
| Session Analysis Analyze session metrics, duration, and token usage for a session.        | `monitoring.session.analysis` `workspace.monitoring.session.analysis()` | Read      | `resource.view`       |
| Reset Session Reset a chat session and clear its context window.                          | `monitoring.session.reset` `workspace.monitoring.session.reset()`       | High risk | `resource.manage`     |
| List Sessions List active and historical chat sessions across bots.                       | `monitoring.sessions` `workspace.monitoring.sessions()`                 | Read      | `resource.view`       |
| Token Usage Statistics Query token consumption metrics aggregated by time buckets.        | `monitoring.tokens` `workspace.monitoring.tokens()`                     | Read      | `resource.view`       |
| Tool Call Metrics Query tool invocation history and execution performance.                | `monitoring.tool_calls` `workspace.monitoring.tool_calls()`             | Read      | `resource.view`       |

### Pipeline (`pipeline`)

| Operation                                                                              | ID and method                                                         | Risk      | Granting member needs |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | --------- | --------------------- |
| Broadcast Chat Message Broadcast a message to all active pipeline chat clients.        | `pipeline.chat.broadcast` `workspace.pipeline.chat.broadcast()`       | High risk | `runtime.operate`     |
| Pipeline Connections Inspect live websocket connection status for pipeline chat.       | `pipeline.chat.connections` `workspace.pipeline.chat.connections()`   | Read      | `runtime.operate`     |
| Pipeline Chat History Retrieve debug chat message history for a pipeline session.      | `pipeline.chat.history` `workspace.pipeline.chat.history()`           | Read      | `runtime.operate`     |
| Reset Chat Session Clear memory and chat history for a pipeline debug session.         | `pipeline.chat.reset` `workspace.pipeline.chat.reset()`               | High risk | `runtime.operate`     |
| Copy Pipeline Duplicate an existing pipeline to create a new copy.                     | `pipeline.copy` `workspace.pipeline.copy()`                           | Write     | `resource.manage`     |
| Create Pipeline Create a new processing pipeline in the workspace.                     | `pipeline.create` `workspace.pipeline.create()`                       | Write     | `resource.manage`     |
| Pipeline Defaults Get template defaults and initial values for new pipelines.          | `pipeline.defaults` `workspace.pipeline.defaults()`                   | Read      | `resource.view`       |
| Delete Pipeline Permanently delete a pipeline from the workspace.                      | `pipeline.delete` `workspace.pipeline.delete()`                       | High risk | `resource.manage`     |
| Get Pipeline Extensions Get bound plugins, MCP servers, and tools for a pipeline.      | `pipeline.extensions.get` `workspace.pipeline.extensions.get()`       | Read      | `resource.view`       |
| Update Pipeline Extensions Update bound plugins, MCP servers, and tools on a pipeline. | `pipeline.extensions.update` `workspace.pipeline.extensions.update()` | Write     | `resource.manage`     |
| Get Pipeline Get complete definition and node graph of a pipeline.                     | `pipeline.get` `workspace.pipeline.get()`                             | Read      | `resource.view`       |
| List Pipelines List all message processing pipelines in the workspace.                 | `pipeline.list` `workspace.pipeline.list()`                           | Read      | `resource.view`       |
| Pipeline Metadata Get available component types and node specifications.               | `pipeline.metadata` `workspace.pipeline.metadata()`                   | Read      | `resource.view`       |
| Run Pipeline Execute a pipeline run with custom input data.                            | `pipeline.run` `workspace.pipeline.run()`                             | Write     | `runtime.operate`     |
| Update Pipeline Update topology, nodes, or settings of a pipeline.                     | `pipeline.update` `workspace.pipeline.update()`                       | Write     | `resource.manage`     |

### Plugin (`plugin`)

| Operation                                                                                 | ID and method                                                         | Risk      | Granting member needs |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | --------- | --------------------- |
| Get Plugin Config Get configured parameters and settings for a plugin.                    | `plugin.config.get` `workspace.plugin.config.get()`                   | Read      | `resource.view`       |
| Plugin Debug Info Inspect internal plugin runtime process state and memory.               | `plugin.debug_info` `workspace.plugin.debug_info()`                   | Read      | `resource.manage`     |
| Get Plugin Get detailed metadata and manifest for an installed plugin.                    | `plugin.get` `workspace.plugin.get()`                                 | Read      | `resource.view`       |
| Plugin GitHub Assets List downloadable asset files for a GitHub release.                  | `plugin.github.assets` `workspace.plugin.github.assets()`             | Read      | `resource.view`       |
| Plugin GitHub Releases List releases of a plugin repository hosted on GitHub.             | `plugin.github.releases` `workspace.plugin.github.releases()`         | Read      | `resource.view`       |
| Install Plugin from Marketplace Install a certified plugin from the official marketplace. | `plugin.install.marketplace` `workspace.plugin.install.marketplace()` | High risk | `resource.manage`     |
| List Plugins List all installed plugins and their running status.                         | `plugin.list` `workspace.plugin.list()`                               | Read      | `resource.view`       |
| Plugin Logs Fetch runtime logs and error messages from a plugin.                          | `plugin.logs` `workspace.plugin.logs()`                               | Read      | `audit.view`          |
| Search Plugin Marketplace Search the LangBot Plugin Marketplace for installable plugins.  | `plugin.marketplace.search` `workspace.plugin.marketplace.search()`   | Read      | `resource.view`       |
| Plugin Readme Get documentation and usage instructions for a plugin.                      | `plugin.readme` `workspace.plugin.readme()`                           | Read      | `resource.view`       |

### Model Provider (`provider`)

| Operation                                                                      | ID and method                                               | Risk      | Granting member needs    |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------- | --------- | ------------------------ |
| Create Provider Add a new model provider and credentials to the workspace.     | `provider.create` `workspace.provider.create()`             | Write     | `provider_secret.manage` |
| Delete Provider Delete a model provider and its associated models.             | `provider.delete` `workspace.provider.delete()`             | High risk | `resource.manage`        |
| Get Provider Get configuration and credentials of a model provider.            | `provider.get` `workspace.provider.get()`                   | Read      | `resource.view`          |
| List Providers List all configured model providers in the workspace.           | `provider.list` `workspace.provider.list()`                 | Read      | `resource.view`          |
| Provider Models Count Count models configured under a specific model provider. | `provider.models.count` `workspace.provider.models.count()` | Read      | `resource.view`          |
| Scan Provider Models Scan remote provider endpoint for available models.       | `provider.models.scan` `workspace.provider.models.scan()`   | Write     | `provider_secret.manage` |
| Update Provider Update credentials or base URL of a model provider.            | `provider.update` `workspace.provider.update()`             | Write     | `provider_secret.manage` |

### Requester (`requester`)

| Operation                                                               | ID and method                                 | Risk | Granting member needs |
| ----------------------------------------------------------------------- | --------------------------------------------- | ---- | --------------------- |
| Get Requester Get configuration and capabilities of an HTTP requester.  | `requester.get` `workspace.requester.get()`   | Read | `resource.view`       |
| List Requesters List HTTP request client adapters used for model calls. | `requester.list` `workspace.requester.list()` | Read | `resource.view`       |

### Skill (`skill`)

| Operation                                                               | ID and method                                             | Risk      | Granting member needs |
| ----------------------------------------------------------------------- | --------------------------------------------------------- | --------- | --------------------- |
| Create Skill Create and register a new custom skill package.            | `skill.create` `workspace.skill.create()`                 | Write     | `resource.manage`     |
| Delete Skill Delete a custom skill and remove its code files.           | `skill.delete` `workspace.skill.delete()`                 | High risk | `resource.manage`     |
| List Skill Files List files and directories within a skill package.     | `skill.file.list` `workspace.skill.file.list()`           | Read      | `resource.view`       |
| Read Skill File Read the source code or content of a file in a skill.   | `skill.file.read` `workspace.skill.file.read()`           | Read      | `resource.view`       |
| Write Skill File Write or update a code file inside a skill package.    | `skill.file.write` `workspace.skill.file.write()`         | Write     | `resource.manage`     |
| Get Skill Get full manifest and metadata for a specific skill.          | `skill.get` `workspace.skill.get()`                       | Read      | `resource.view`       |
| Preview GitHub Skill Preview a skill package from a GitHub repository.  | `skill.github.preview` `workspace.skill.github.preview()` | Read      | `resource.manage`     |
| List Skills List all custom skills installed in the workspace.          | `skill.list` `workspace.skill.list()`                     | Read      | `resource.view`       |
| Reload Skills Reload all skill packages and refresh runtime registries. | `skill.reload` `workspace.skill.reload()`                 | Write     | `resource.manage`     |
| Update Skill Update metadata or configuration of an existing skill.     | `skill.update` `workspace.skill.update()`                 | Write     | `resource.manage`     |

### Statistics (`stats`)

| Operation                                                                         | ID and method                           | Risk | Granting member needs |
| --------------------------------------------------------------------------------- | --------------------------------------- | ---- | --------------------- |
| Basic Statistics Get workspace overview counters for bots, models, and pipelines. | `stats.basic` `workspace.stats.basic()` | Read | `resource.view`       |

### Task (`task`)

| Operation                                                                   | ID and method                     | Risk | Granting member needs |
| --------------------------------------------------------------------------- | --------------------------------- | ---- | --------------------- |
| Get Task Get the status of a background task such as a plugin installation. | `task.get` `workspace.task.get()` | Read | `resource.view`       |

### Tool (`tool`)

| Operation                                                              | ID and method                       | Risk | Granting member needs |
| ---------------------------------------------------------------------- | ----------------------------------- | ---- | --------------------- |
| Get Tool Get parameter schema and description for a specific tool.     | `tool.get` `workspace.tool.get()`   | Read | `resource.view`       |
| List Tools List all registered function tools available for execution. | `tool.list` `workspace.tool.list()` | Read | `resource.view`       |

### Workspace (`workspace`)

| Operation                                                                                            | ID and method                                                 | Risk | Granting member needs |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---- | --------------------- |
| Get Workspace Language Get the Workspace language used for backend messages and default bot replies. | `workspace.language.get` `workspace.workspace.language.get()` | Read | `workspace.view`      |

`workspace.language.get` returns `{"language": "zh_Hans", "supported_languages": [...]}`. `language` is the Workspace message language set under Workspace settings (default `en_US`), not a member's WebUI language. Plugins and Agents can use it to localize replies and generated content. Changing the language stays with members.

---

# 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.

The plugin-level `spec.permissions` lists the capabilities and Workspace operations the plugin needs. A Workspace member confirms them after installation; see [Plugin permissions](https://langbot.app/docs/en/plugin/dev/permissions.md).

```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:
  permissions:  # Capabilities and Workspace operations the plugin needs; see Plugin permissions
    capabilities: []
    workspace_operations: []
  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`. See the official [LangRAG knowledge engine](https://github.com/langbot-app/LangBot/tree/master/plugins/KnowledgeEngine/LangRAG) for a complete implementation.

```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 [official plugins](https://github.com/langbot-app/LangBot/tree/master/plugins).

```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/tree/master/plugins/misc/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/tree/master/plugins/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.

---

# Plugin permissions

Source: https://langbot.app/docs/en/plugin/dev/permissions

Declare what your plugin needs, and understand how Workspace members confirm and revoke that access.

A plugin can do far more than reply to messages: it can call models, read knowledge bases, send messages through any bot, or manage Agents and Pipelines through the [Workspace API](https://langbot.app/docs/en/plugin/dev/apis/workspace.md). Because every installation runs inside one Workspace, LangBot asks plugins to say up front which of these abilities they need, and asks a Workspace member to approve them.

The flow has three steps:

1. **Declare.** The plugin lists the permissions it needs in `manifest.yaml`.
2. **Confirm.** After installation, a member reviews the list on the plugin's detail page and grants all or part of it. Until then the installation stays disabled.
3. **Enforce.** LangBot checks the installation's grants on every call the plugin makes. A call outside the grants fails with `permission_denied`.

Declaring a permission does not grant it. Only a member's confirmation does.

## Declare permissions

Permissions belong to the plugin as a whole, so they live under the plugin-level `spec` in `manifest.yaml`, not inside a component. The same grants apply to every component of the plugin: commands, event listeners, tools, knowledge engines, parsers and Runners.

```yaml
apiVersion: v1
kind: Plugin
metadata:
  author: acme
  name: WeeklyReport
  version: 1.0.0
spec:
  permissions:
    capabilities:
      - models.invoke      # call LLMs
      - bot.message.send   # post the report to a group
      - storage.plugin     # remember when the last report was sent
    workspace_operations:
      - stats.basic        # read Workspace statistics
      - knowledge.*        # every knowledge base operation
  config: []
  components: {}
```

The two lists cover different kinds of access:

- **`capabilities`** unlock the classic SDK methods on `self.plugin`, such as `invoke_llm`, `send_message` or `set_plugin_storage`. The [table below](#capabilities) lists all 16.
- **`workspace_operations`** unlock operations of the [Workspace API](https://langbot.app/docs/en/plugin/dev/apis/workspace.md), the same operations the LangBot HTTP API, MCP server and Workspace assistant use. Each entry is an operation ID such as `pipeline.list`.

Declare only what the plugin actually uses. Members are far more willing to approve a short, sensible list, and a smaller grant limits the damage if the plugin is ever misused.

### Strict mode and compatibility mode

How you declare permissions decides which mode the installation runs in:

| Manifest                              | Mode          | Behaviour                                                                                |
| ------------------------------------- | ------------- | ---------------------------------------------------------------------------------------- |
| `permissions:` with one or both lists | Strict        | Members may grant the whole list or only part of it.                                     |
| `permissions: {}`                     | Strict        | The plugin needs no global access at all.                                                |
| No `permissions` field                | Compatibility | The plugin is treated as a legacy plugin; see [Compatibility mode](#compatibility-mode). |

New plugins should always declare permissions, even an empty set.

### Wildcards

A workspace operation entry may end in `.*` to request every operation under a prefix, for example `knowledge.*` or `model.llm.*`. LangBot expands the wildcard into concrete operation IDs when a member confirms the installation, and stores those IDs. If a later LangBot version adds operations under that prefix, they are not granted automatically; the installation asks for confirmation again.

Some operations can never be granted to plugins: streaming operations, operations reserved for other callers (for example ones only a signed-in member may call), and operations not exposed through the API at all. Declaring one of them, or an unknown ID, makes the declaration invalid. The same applies to a wildcard whose prefix contains such an operation, so `bot.*`, `agent.*`, `pipeline.*`, `plugin.*` and `monitoring.*` are rejected; list those operations individually or use a narrower prefix.

These wildcards are valid today:

- Whole domains: `adapter.*`, `extension.*`, `knowledge.*`, `model.*`, `requester.*`, `stats.*`, `tool.*`
- Narrower prefixes: `agent.runs.*`, `bot.group_filter.*`, `bot.message.*`, `bot.routes.*`, `bot.runtime.*`, `mcp.resource.*`, `monitoring.execution.*`, `monitoring.feedback.*`, `monitoring.message.*`, `monitoring.session.*`, `pipeline.chat.*`, `pipeline.extensions.*`, `plugin.github.*`, `plugin.marketplace.*`, `provider.models.*`, `skill.file.*`, and every prefix under `knowledge.` and `model.`

The [Workspace API reference](https://langbot.app/docs/en/plugin/dev/apis/workspace.md#operation-reference) lists every operation a plugin can request.

## Capabilities

Each capability unlocks a group of SDK methods. The member confirming it needs the Workspace permissions in the third column; the last column tells them what they are approving.

| Capability          | SDK methods it unlocks                                                                                                      | Member needs                         | What it means                                |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------- |
| `langbot.info`      | `get_langbot_version`                                                                                                       | `resource.view`                      | Read-only                                    |
| `bot.read`          | `get_bots`, `get_bot_info`                                                                                                  | `resource.view`                      | Read-only                                    |
| `bot.message.send`  | `send_message`                                                                                                              | `runtime.operate`                    | Sends messages to users and groups           |
| `bot.platform_api`  | `call_platform_api`                                                                                                         | `runtime.operate`, `resource.manage` | **Dangerous**: raw access to the IM platform |
| `models.read`       | `get_llm_models`                                                                                                            | `resource.view`                      | Read-only                                    |
| `models.invoke`     | `invoke_llm`, `invoke_llm_with_usage`, `invoke_llm_stream`, `invoke_llm_stream_events`, `invoke_embedding`, `invoke_rerank` | `runtime.operate`                    | Consumes model provider quota                |
| `storage.plugin`    | `get/set/delete_plugin_storage`, `get_plugin_storage_keys`                                                                  | `resource.manage`                    | Writes the plugin's own storage              |
| `storage.workspace` | `get/set/delete_workspace_storage`, `get_workspace_storage_keys`                                                            | `resource.manage`                    | Writes storage shared by all plugins         |
| `knowledge.read`    | `list_knowledge_bases`, `retrieve_knowledge`, `get_knowledge_file_stream`                                                   | `resource.view`                      | Reads knowledge bases                        |
| `knowledge.vector`  | `vector_upsert`, `vector_search`, `vector_delete`, `vector_list`                                                            | `resource.manage`                    | Writes vector stores                         |
| `knowledge.parser`  | `list_parsers`, `invoke_parser`                                                                                             | `runtime.operate`                    | Runs document parsers                        |
| `config.read`       | `get_config_file`                                                                                                           | `resource.view`                      | Reads uploaded config files                  |
| `plugin_tools`      | `list_tools`, `get_tool_detail`, `call_tool` on plugin tools                                                                | `runtime.operate`                    | Runs other plugins' tools                    |
| `mcp`               | `call_tool` on MCP tools                                                                                                    | `runtime.operate`                    | **Dangerous**: runs MCP tools                |
| `sandbox`           | `get_box_status`, `list_boxes`, `acquire_box`, and `call_tool` on sandbox tools                                             | `runtime.operate`                    | **Dangerous**: runs code in the sandbox      |
| `plugin.read`       | `list_plugins_manifest`, `list_commands`                                                                                    | `resource.view`                      | Lists installed plugins                      |

Two notes on tools. When your plugin calls another plugin's tool, that tool runs with **its own** installation's grants, not yours. And a capability is checked per tool source: `plugin_tools` alone does not let you call an MCP or sandbox tool.

Calls that act only on the event or run your plugin is currently handling need no capability. Replying to the triggering conversation, reading the current query's variables, or using the tools LangBot provides to a Runner are all authorized by that event or run, not by the installation. See [Agent run API](https://langbot.app/docs/en/plugin/dev/apis/agent-run.md) and [Pipeline event API](https://langbot.app/docs/en/plugin/dev/apis/pipeline-events.md).

## Confirming an installation

A newly installed or upgraded plugin that needs confirmation shows **Needs approval** in the plugin list and on its detail page, and stays disabled. A member opens **Plugin permissions** on the detail page, reviews the requested permissions, unchecks anything they do not want to grant, and selects **Grant**. Dangerous capabilities and the ability to send messages are highlighted in the confirmation dialog.

Who may confirm:

- Only members signed in to the WebUI (and support administrators) can add grants. API keys, `lbctl`, processors, plugins and public bots cannot. An installation made through an API key or `lbctl` waits for a member to confirm it in the WebUI.
- The member needs `resource.manage`, plus the permissions each grant requires: the capability ceilings in the table above, and each operation's own `permission` for workspace operations. Members with the developer role hold `resource.view`, `resource.manage` and `runtime.operate`, so they can grant every capability. That still does not let them grant operations above their role, such as member or API-key management.
- If even one requested item is above the member's ceiling, the whole request fails with `permission_denied`, and the response lists the offending items in `denied_operations` and `denied_capabilities`. LangBot never silently drops part of a request.

In strict mode the member may grant any subset of what the plugin declared, so make your plugin degrade gracefully when an optional permission is missing.

Grants belong to the installation, not to the member. They stay in place if the member who approved them later changes role or leaves the Workspace.

### Installing with automatic confirmation

The setup wizard and Pipeline migration install official plugins and confirm their declared permissions in one step. They go through the same checks as a manual confirmation: the caller must be a member and must hold every required permission. If any check fails, the plugin is still installed but stays pending. Over HTTP this corresponds to `auto_confirm_permissions: true` on `POST /api/v1/plugins/install/marketplace`; the default is `false`, and API keys cannot use it to bypass member confirmation.

### Installs requested by plugins and Agents

A plugin, or an Agent or Pipeline through its workspace tools, can find plugins with `plugin.marketplace.search` and install them with `plugin.install.marketplace` once a member has granted those operations. Installing is marked **High risk**, so selecting it for an Agent or Pipeline shows the sensitive-tool warning. These callers can only add new installations from the marketplace:

- `auto_confirm_permissions: true` is rejected with `permission_denied`. The new plugin stays disabled until a member confirms its permissions on the plugin's detail page.
- Installing a plugin that is already installed fails with `plugin_already_installed`; upgrading or reinstalling stays with members.
- When the instance disables the marketplace, both operations fail with `marketplace_disabled`.
- Installing from GitHub or a local file is not available to them.

The install call returns a `task_id`. Poll `task.get` until `status` is `succeeded` or `failed`; `pending_permission_confirmation: true` means the plugin is waiting for a member.

## Revoking and upgrading

Any member with `resource.manage` can revoke a grant at any time by unchecking it and saving. Revoking needs no confirmation and no permission ceiling. API keys may revoke but never add.

When a plugin is upgraded:

- Grants that the new version still declares are kept.
- Permissions the new version adds stay ungranted until a member confirms them, and the installation shows **Needs approval** again.
- Permissions the new version no longer declares stop being effective immediately.

## How grants combine with Agent and Pipeline settings

Choosing tools for an Agent or a Pipeline does not grant anything. It only narrows what the model sees. A Runner such as LocalAgent offers the model the intersection of the tools selected in the Agent (or the Pipeline's **Extensions** page) and the operations granted to the Runner's installation. If nothing is selected, the model gets no workspace tools.

This is why a member who can edit an Agent may select a workspace operation they could not grant themselves: the selection has no effect unless a member with enough permissions has already granted that operation to the Runner plugin.

## Compatibility mode

Plugins written before installation permissions existed have no `spec.permissions`. LangBot runs them in compatibility mode:

- They receive a fixed set of **all 16 legacy capabilities** and **no workspace operations**.
- A member must confirm the whole set at once; partial confirmation is not possible, because nothing in the manifest tells LangBot which subset would be safe. After confirming, the member may revoke individual capabilities.
- Confirming requires `resource.view`, `resource.manage` and `runtime.operate`.
- Capabilities added in future LangBot versions are not added to an already confirmed set.

Installations that existed before you upgraded LangBot are migrated with this set already confirmed and keep their enabled state. Installing a compatibility-mode plugin afresh, or upgrading one (including to a version that drops its previous declaration), disables it until a member confirms again.

## Handling a denied call

Classic SDK methods raise an error whose data carries `code: permission_denied` and, where relevant, `denied_capabilities`. Workspace API calls do not raise; they return `{"ok": false, "error": {...}}` with the same code. Either way, treat a denial as a normal outcome: log it, tell the user which permission is missing, and continue without that feature.

## Managing permissions programmatically

The WebUI uses these endpoints, which you can also call with a member token:

- `GET /api/v1/plugins/{author}/{plugin_name}/permissions` returns every declared item with `granted` and `grantable`, whether the installation is in compatibility mode or pending confirmation, and whether the caller `can_manage` and `can_confirm`. Workspace operations include their `domain`, and the response lists domain names in `domains`.
- `PUT /api/v1/plugins/{author}/{plugin_name}/permissions` takes `workspace_operations`, `capabilities` and `confirm`. With `confirm: false` the lists must be a subset of the current grants, so this form can only revoke. With `confirm: true` the full confirmation rules above apply.
- Plugin list and detail responses include `permission_status` with `compatibility_mode` and `pending_confirmation`.

The matching Application API operations are `plugin.permissions.get` and `plugin.permissions.update`. LangBot's MCP server exposes `get_plugin_permissions` and `revoke_plugin_permissions`; MCP clients authenticated with an API key cannot confirm new grants.

---

# 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 the LangBot host debug port (default `5401`, overridable via the port in `plugin.display_plugin_debug_url`).
>
> - `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. Click **Submit** to complete. LangBot automatically identifies the bot.

> warning:
>
> One-click setup fills in app credentials but does not create card templates. For streaming replies, import the LangBot streaming reply template, enable Use Card Replies and set Card Template ID to automatically enable streaming replies. Turn off the switch for plain text without deleting the template ID. For human input interactions, import the separate human input template and set Human Input Card Template ID. Enable the required card permissions in your DingTalk app.

## Configure card templates (use the LangBot templates)

For card replies, import the templates supplied by LangBot instead of building components and binding variables manually. Enable the required card permissions for your DingTalk app, then choose the template for your use case:

| Purpose                                                      | Download                         | LangBot field                |
| ------------------------------------------------------------ | -------------------------------- | ---------------------------- |
| Streaming replies with separate reasoning and answer regions | `dingtalk_stream_card.json`      | Card Template ID             |
| Pause for user input, a choice, or confirmation              | `dingtalk_human_input_card.json` | Human Input Card Template ID |

### Create and import the streaming reply template

1. In the DingTalk adapter configuration, click **Download Streaming Reply Card Template** below **Card Template ID**.
2. Open [DingTalk Card Platform](https://open-dev.dingtalk.com/fe/card), select the same organization as your bot app, and click **New Template**.
3. Enter a name. Set **Card Type** to **Message Card**, **Template Scenario** to **AI Card**, associate your bot app, and select **Build from Blank**. Click **Create Blank Template**. The screenshot shows these options in the Chinese interface.

![Create a message card with the AI Card scenario, associated bot app, and blank creation mode](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/create_ai_card_template.png)

4. In the card editor, choose **More → Import Card Template** and select `dingtalk_stream_card.json`.

![Import Card Template in the card editor's More menu](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/import_card_template.png)

> info:
>
> The import option is inside the editor, not on the template list page. Importing replaces the current template contents, so use a new blank template. Keep the imported components, variables, and event bindings.

5. Review the preview, **save and publish** the template, and copy its ID. Saving a draft is insufficient: `param.templateUnpublished` means the template has not been published.
6. Enable **Use Card Replies**, paste the ID into **Card Template ID** in LangBot, and save to enable streaming replies. Turning off the switch uses plain text and hides but preserves the template settings for later use.

The template includes LangBot branding and separate reasoning and answer regions. Reasoning is expanded during generation and collapsed by default when finished; users can expand it again. The footer offers answer copying, thumbs-up/down controls, and an AI-generated content label. The pipeline still controls whether reasoning is removed. If removed, the reasoning region is hidden. Ordinary messages with reasoning retained show literal `<think>` and `</think>` markers separated from the answer by blank lines.

Card Auto Layout is enabled by default; the supplied streaming reply template includes the required variables. For an existing bot saved with this option off, enable it and save the configuration. You can keep it off for a narrower card.

To update, download and import the latest template, then save and publish again. If you create a different template, also replace its ID in LangBot. Existing templates bound only to `content` remain compatible but do not offer the new separate reasoning region.

## Import the human input card template

Human input is used when a workflow or plugin waits for information, a choice, or confirmation before continuing, such as a Dify Human Input node. Ordinary chat and streaming replies alone do not require this template.

1. Next to **Human Input Card Template ID**, click **Download Human Input Card Template** to save `dingtalk_human_input_card.json`.
2. Follow the creation steps above to create a separate **Message Card → AI Card → Build from Blank** template associated with your bot app.
3. Choose **More → Import Card Template** in the editor and import the human input JSON. Keep its input fields, buttons, variables, and event bindings.
4. **Save and publish**, enter this template's ID into **Human Input Card Template ID** in LangBot, and save the bot configuration.

Import the two templates separately and use their corresponding fields. The human input template does not replace the streaming reply template or automatically enable streaming replies.

***

## 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)

For card templates, follow the steps above to import and publish the templates supplied by LangBot.

### Fill in Configuration Information

Click `Credentials and Basic Information`, record `Client ID` and `Client Secret`, and enter these credentials in the LangBot adapter configuration.
`markdown_card` (Use Card Replies) controls both Markdown and streaming card replies. When enabled, a configured template enables streaming; otherwise ordinary Markdown is used. Disable it for plain text without clearing template settings. Human input cards are configured separately for workflow interactions.
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.

**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.

## Event subscriptions

Select Stream mode under Event Subscriptions in the DingTalk app console and enable the required events. This is separate from the robot message callback setting.

- `chat_add_member` maps to `group.member_joined`, once per affected member.
- `chat_remove_member` / `chat_quit` map to `group.member_left`, distinguishing removal from voluntary departure.
- `chat_update_title` / `chat_update_owner` map to `group.info_updated`.
- Ordinary card interactions emit `dingtalk.card_action`. Recognized feedback uses `feedback.received`; managed input forms retain their existing interaction flow without duplicate triggers.
- Group disbanding and other subscribed events use `platform.specific`, preserving the native event name in `action` and the original headers and payload in `data`.

Group events depend on application permissions and supported group types. Member notifications containing only unionId remain platform-specific; unionId is not treated as a messaging user ID. Message editing, recall, reactions, friend requests and bot mute events are not advertised without a confirmed corresponding push capability.

---

# 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 the application and bot

Open the [Discord Developer Portal](https://discord.com/developers/applications) and choose **New Application**. Do not include `Discord` in the application name: the portal rejects it. Complete the terms confirmation and verification shown by Discord.

1. Copy the **Application ID** from **General Information**. This is the **Client ID** required by LangBot, not a server or channel ID.
2. Open **Bot**, choose **Reset Token**, and complete verification. The token is shown only once. Enter it in LangBot; never include it in screenshots, source code, or public messages. Resetting invalidates the old token, so update LangBot as well.
3. Under **Privileged Gateway Intents**, enable **Server Members Intent** and **Message Content Intent**, then **Save Changes**. The new adapter requests both. **Presence Intent is not required**.

## Connect LangBot

Create a bot using the new **Discord** adapter (`discord-omni`). Enter the Client ID and token and save.

Configure event processing next:

- **Pipeline**: add a received-message rule and bind `message.received` to a pipeline with a configured model. Configure **Trigger conditions** on the bot's event route to limit messages by text, session type, or message elements. Explicit event routes bypass the Pipeline's own group response rules; an unconditional route processes every received message. The mention-element condition matches an @ mention, not necessarily the bot.
- **Agent**: bind events to an Agent. Instruct it to use the event reply tool to deliver messages; generated text alone is not delivery. Select only the tools the task needs.
- **Plugin processor**: add an existing plugin processor configuration separately on the bot page. It subscribes independently to the events declared by the plugin and can run alongside a Pipeline or Agent.

Enable an available Box sandbox when the runner needs code execution or file generation. Unrelated MCP servers are unnecessary for attachments; external tools with missing credentials introduce additional failures.

Enable the bot and look for `Discord adapter running as ...` in its logs. This confirms Gateway login. Send a real Discord message to verify routing and delivery.

## Install in a test server

In **OAuth2 → URL Generator**, select `bot` and **Guild Install**. For ordinary messages, images, and files, select:

- View Channels
- Send Messages
- Embed Links
- Attach Files
- Read Message History
- Add Reactions

Open the generated link, select your test server, and authorize installation. Administrator is unnecessary. Add permissions for moderation or threads only when needed. Channel permission overrides must also allow access and replies.

## Verify delivery

Send a message matching the trigger rules in a server channel, then open a DM from the bot's profile. Check ordinary replies, progressive streaming, image and text-file input, and actual returned attachments in both places. A filename or output path in a text reply is not proof that a file was delivered.

Discord limits each message's length, so long streaming replies must be delivered in multiple messages. Verify the final segment and end marker; a successful LangBot run alone does not prove complete delivery. Image understanding requires a vision model; file processing requires suitable runner tools and sandbox support.

The adapter also exposes edits, deletions, reaction additions/removals, member joins/leaves, bot joins/leaves, and platform-specific events. Pipelines process messages; route other events to an Agent or plugin. Interaction submissions come from interactive components sent by LangBot, not every possible Discord event.

For message events, `chat_id` is the channel ID and `group.id` is the server ID. Use the channel ID for channel delivery and the server ID for server/member queries and management. They are not interchangeable.

For member join/leave events, there is no originating channel. Replies use the server's configured **System Messages Channel**. Configure it in Discord's server settings and grant the bot View Channels and Send Messages there; without a system channel, the reply fails explicitly. The member-leave callback does not distinguish voluntary departure from a kick, so do not use `is_kicked` as an authoritative moderation signal.

![Real Discord delivery: the plugin returns the uploaded image and text file, followed by a successful Pipeline DM reply.](https://langbot.app/docs/images/zh/deploy/bots/discord/attachment-roundtrip.jpg)

## Troubleshooting

- **Gateway login fails**: check the current token and both required intents, including Save Changes. A browser login does not validate the bot token.

- **Online without replies**: check enablement, event routes, processor model, group triggers, and channel permissions. Independent plugin subscriptions are configured separately.

- **Attachments fail**: check attachment permissions, runner logs, Box readiness, and attachment download connectivity. CDN access is separate from Gateway connectivity.

- **Restricted network**: the LangBot environment needs access to Discord Gateway, API, and attachment CDN. Configure a proxy appropriate to your deployment if required.

- **Screenshots**: exclude tokens and real users' private conversations.

- **Attachment 404 errors in an old conversation**: Discord attachment URLs expire, and an old image can also break later text-only requests. Upload the attachment again and reset the conversation context. With EssentialCommands installed, send `!reset` (use your configured command prefix). Resetting context preserves monitoring records.

---

# 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. The new adapter identifies the bot automatically; no bot name is needed to recognize group mentions. If the legacy adapter still shows this field, enter the same name as the Feishu bot.

![Fill Bot Name](https://langbot.app/docs/images/zh/deploy/bots/lark/lark_fill_bot_name.png)

8. Click **Submit** to complete

### Additional permissions and event subscriptions

> info:
>
> An app created or authorized by QR code may not have all the permissions and event subscriptions your use case requires. Sending and receiving messages does not mean member join/leave events are subscribed. You can update the existing app in the developer console without creating another bot.

1. Open the [Feishu developer console](https://open.feishu.cn/app) or [Lark developer console](https://open.larksuite.com/app). Select the app you created or authorized, using its App ID to confirm.
2. Under **Permissions**, add the permissions required for your features. Permissions control which data and operations the bot can access.
3. Under **Events & Callbacks > Event Configuration**, subscribe to the events you need. Subscriptions control which notifications are sent to LangBot; granting permissions does not automatically subscribe to events.
4. Save the changes and complete any release or administrator approval requested by the platform. Once effective, trigger a new event to verify delivery; earlier actions are not replayed by adding a subscription.

> warning:
>
> **Remember to publish a new app version after adding events.** Complete the release under **Version Management & Release**, and wait for administrator approval if required. Adding and saving an event does not activate changes that are still pending release. LangBot may show a healthy connection while these events are not delivered.

If member join/leave events still do not arrive after subscribing, first check for changes pending release or approval. Once the new version is effective, have a member join or leave a group containing the bot again, then check the event records in LangBot.

To receive group membership changes, the bot must be in the group and the app must subscribe to:

| Feature                                | Feishu event                     |
| -------------------------------------- | -------------------------------- |
| User joins a group                     | `im.chat.member.user.added_v1`   |
| User leaves or is removed from a group | `im.chat.member.user.deleted_v1` |

The bot joining a group (`im.chat.member.bot.added_v1`) is a separate event and does not cover other members. Also configure **Event Routing** in LangBot to send these events to an Agent or plugin processor; pipelines only process message events.

***

## 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.

## Group replies and At components

QQ Official Omni disables `Enable Markdown Rendering` by default. Plain-text group replies omit At components rather than exposing literal markup, while preserving the original reply `msg_id`. This does not guarantee a mention notification in QQ.

For explicit group mentions, obtain Markdown permission for your QQ bot and enable this option. Markdown uses the member's original OpenID, not their display name or QQ number. Verify rendering in the actual QQ client; LangBot does not automatically switch to a potentially unauthorized Markdown mode. Although the official text-interaction documentation lists plain-text support, [adapter testing](https://github.com/nonebot/adapter-qq/issues/220) and user acceptance have shown literal tags in plain-text group replies.

## 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.

## Quick setup (recommended)

Use **Quick Slack setup** to create your app. LangBot configures bot scopes, message events, the messages tab and the OAuth return URL. You provide configuration tokens, approve installation in Slack, and add an App-Level Token when using Socket Mode.

### 1. Create a bot and choose a connection mode

In LangBot, open **Bots → Create bot**, enter a name, select **Slack**, and submit. On the configuration page, choose a connection mode and select **Quick Slack setup → Start**:

![Create a bot and select the Slack adapter](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-create-bot.jpg)

- **Socket Mode (recommended)**: LangBot connects to Slack. No public event webhook is required, making this suitable for local or private-network deployments.
- **Webhook**: Slack sends events to LangBot through a publicly reachable HTTPS endpoint.

![Select Socket Mode and open Quick Slack setup](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-connection-mode.jpg)

### 2. Get App Configuration Tokens

Open the [Slack apps page](https://api.slack.com/apps). Under **Your App Configuration Tokens**, select **Generate Token** and choose the target workspace. Copy both the **Access Token** and **Refresh Token**. If tokens already exist, use their copy buttons.

![Slack configuration token section and copy buttons](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-configuration-tokens.jpg)

These tokens create and configure apps. **They are not the runtime Bot Token or App-Level Token.** Paste each into its matching field in the assistant and confirm the app name.

### 3. Confirm the URL and create the app

For Socket Mode, check the **OAuth return URL**. It returns your browser to LangBot after authorization, accepts HTTPS or `http://localhost`, and ends in `/api/v1/platform/adapters/slack/setup/callback`. Only your browser needs to reach it; this is not an event webhook. For remote deployments, do not use a server-internal address that your browser cannot reach.

![Socket Mode quick setup form](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-socket-mode.jpg)

For Webhook, the assistant shows a **Webhook URL** instead. Verify the public domain, HTTPS and reverse proxy, and preserve the `/bots/<bot UUID>` suffix. LangBot derives the OAuth return URL from it and completes Slack's event URL verification automatically.

Select **Create and configure**, then wait for **Authorize in Slack**.

### 4. Authorize installation in Slack

Select **Authorize in Slack**, review the app name, workspace and permissions, and select **Allow**. Workspace policy may require administrator approval. Return to the original LangBot assistant afterward.

![Slack installation authorization page](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-slack-permissions.jpg)

### 5. Socket Mode: add an App-Level Token

Skip this step for Webhook. For Socket Mode, use **Open app settings** in the assistant and navigate to **Basic Information → App-Level Tokens → Generate Token and Scopes**:

1. Enter a Token Name, such as `langbot-socket`.
2. Select **Add Scope**, then **connections:write**.
3. Select **Generate**, copy the resulting `xapp-` token, and paste it into **App-Level Token** in the assistant.

![Add connections:write to the App-Level Token](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-app-token-scope.jpg)

Leave **Token rotation** disabled. The token must belong to the same Slack app you just created. Do not use the Access Token or Refresh Token from step 2 here.

### 6. Fill configuration, set routing and enable the bot

When the assistant reports successful authorization, select **Fill adapter configuration**. In Socket Mode, this button becomes available after you enter the App-Level Token. The assistant fills the Bot Token and other adapter credentials automatically.

![Authorization completed and adapter configuration ready to fill](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-authorized.jpg)

Under **Event routing → Add action → Reply to received messages**, select a configured pipeline or Agent for `message.received` and keep the route enabled. Finally, select **Save and enable** at the top right.

![Configure the message route and save the bot](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-routing.jpg)

### 7. Test a conversation

Open the app's **Messages** tab in Slack and send a direct message. You can also invite the bot to a channel and mention it. A reply confirms the integration works.

![A successful Slack bot conversation](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-conversation.png)

> info:
>
> Configuration tokens are used only during the temporary setup session, not saved as runtime credentials. Sessions last 15 minutes. Cancelling does not delete an app already created in Slack, and starting again may create another app. If the return page shows an error, check whether the original assistant already reports successful authorization before restarting.

If no reply arrives, check that both the bot and message route are enabled, the handler works, and the bot logs show no errors. For Socket Mode, verify that the App-Level Token belongs to the same app and includes `connections:write`. For Webhook, check the public endpoint and Slack's **Verified** status.

## Events, interactions and upgrading existing apps

Quick setup configures the subscriptions and interaction endpoint below. Installation requests message, channel, user, file and reaction permissions; `reactions:read` enables reaction events. Replies in threads started by this bot are delivered without an @mention; other channel messages still require one. Subscribe to `message.channels` with `channels:history` (and `message.groups` with `groups:history` for private channels) to receive these thread replies. Reinstall the Slack app after adding scopes.

Thread delivery does not imply a bot mention. Unmentioned replies remain available to plugins but do not satisfy the default pipeline's mention-based group response rule.

| Slack event                                                                     | LangBot event                                                                            |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Direct messages, `app_mention`, replies in this bot's threads                   | `message.received`                                                                       |
| `message_changed` / `message_deleted` message subtypes                          | `message.edited` / `message.deleted`                                                     |
| `reaction_added` / `reaction_removed`                                           | `message.reaction`, distinguished by `is_add`                                            |
| `member_joined_channel` / `member_left_channel`                                 | `group.member_joined` / `group.member_left`                                              |
| Membership events for the bot itself                                            | `bot.invited_to_group` when an inviter is present; `bot.removed_from_group` on departure |
| Channel rename, archive/unarchive, topic/purpose changes                        | `group.info_updated`                                                                     |
| `block_actions`, `view_submission`, `view_closed`, `shortcut`, `message_action` | `platform.specific`, with `action` set to `slack.` plus the callback type                |
| `app_home_opened`, `app_uninstalled`, `tokens_revoked`                          | `platform.specific`, with `action` set to `slack.` plus the event type                   |

Configure handlers in the bot's event routing; distinguish platform callbacks by `action`. Uninstallation and token revocation also produce bot warning logs and do not automatically send chat replies. Emoji reactions are not automatically treated as model feedback. Message IDs use Slack message timestamps (`ts`) together with the channel; replies preserve `thread_ts`.

Interactions are acknowledged first and processed asynchronously. Synchronous field validation errors in modal submission acknowledgements and external select-option loading are not supported. Set `notify_on_close: true` when opening a modal to receive `view_closed`. Receiving callbacks does not create buttons, shortcuts or modals. Both Socket Mode and Webhook support these handlers; actual delivery depends on Slack permissions, channel membership and connection availability.

**Upgrading LangBot does not automatically update an existing Slack app's permissions.** Keep the existing app and:

1. In **OAuth & Permissions → Bot Token Scopes**, retain existing scopes and add `reactions:read`. Verify `app_mentions:read`, `chat:write`, `channels:history`, `channels:read`, `groups:history`, `groups:read`, `im:history`, `im:read`, `im:write`, `mpim:history`, `mpim:read`, `users:read`, `files:read`, `files:write`, then **Reinstall to Workspace** to authorize the permissions.
2. In **Event Subscriptions → Subscribe to bot events**, configure: `app_mention`, `message.im`, `message.channels`, `message.groups`, `message.mpim`, `reaction_added`, `reaction_removed`, `member_joined_channel`, `member_left_channel`, `channel_rename`, `group_rename`, `channel_archive`, `channel_unarchive`, `group_archive`, `group_unarchive`, `app_home_opened`, `app_uninstalled`, `tokens_revoked`. Edits/deletions and topic/purpose changes are message subtypes, not separate subscriptions.
3. Enable **Interactivity & Shortcuts**. For Webhook, use the same LangBot `/bots/<bot UUID>` **Request URL** as event subscriptions. Socket Mode needs no public interaction URL.
4. Save Slack settings and configure the corresponding LangBot routes. If reinstallation changes the Bot Token, update it and save the bot.

See the [Slack App Manifest reference](https://docs.slack.dev/reference/app-manifest/) for field definitions.

## Threads with standard message APIs

Use `send_message` and `reply_message` with standard message components:

- `send_message` returns a `MessageResult` whose `message_id` is the first sent message's Slack `ts`, including when text is followed by a file. Save this ID to start a thread beneath that message.
- Include `Quote(id=message_id, origin=MessageChain([]))` in the outgoing chain to send text and files into that thread. The first Quote with a nonempty ID takes precedence, including over `reply_message`'s source thread or `quote_origin` selection. Its origin content is not sent. Without an explicit Quote ID, existing send/reply behavior is unchanged.
- Incoming channel thread replies include `Quote(id=thread_ts, group_id=channel, target_id=channel, origin=MessageChain([]))`. The current message's ID remains in `Source.id`. Root messages and messages outside threads have no thread Quote. Plugins can read the parent ID directly from the chain without a separate context lookup.

## Manual setup (Webhook)

The screenshots below show basic messaging setup. Use the current lists in “Events, interactions and upgrading existing apps” above for complete permissions, subscriptions and interactivity settings.

The manual Webhook instructions follow. For manual Socket Mode setup, enable Socket Mode in Slack, supply Bot Token and App-Level Token, and subscribe to `app_mention` and `message.im`. No event Request URL is needed.

### 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:
>
> Webhook mode requires public 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 a bot

Open the official [BotFather](https://t.me/BotFather) in Telegram, send `/newbot`, and choose a name and a username ending in `bot`. Keep the returned Token private; do not include it in group messages or screenshots.

This guide covers the new Telegram adapter in LangBot 4.11 (internal name `telegram-omni`). Do not select the deprecated legacy adapter.

## Configure and enable

1. Configure a working model provider and model in LangBot, then create a Pipeline, Agent, or plugin processor.
2. Create a bot under **Bots**, select Telegram, and enter the Token.
3. Bind a message processor to `message.received`. A Pipeline runs a conversation flow; an Agent handles events with tools. Plugin processors can also subscribe independently.
4. Enable Markdown and streaming as needed, enable the bot, and save. Save again after changing processor bindings.
5. Open the bot's private chat in Telegram, click **Start**, and send a test message. Check the processor's run status and reply tool result in LangBot as well.

The adapter uses long polling and requires outbound access to `api.telegram.org`. An inbound Webhook is not required to receive messages. Only one polling instance should use a Token; do not enable the same bot in another LangBot instance simultaneously.

### Choose a processor

| Type             | Configuration and checks                                                                                                                                                                     |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pipeline         | Set the model and trigger rules. Group mentions or prefixes must still match the rules. With streaming enabled, a streaming-capable processor can progressively update the Telegram message. |
| Agent            | Configure the model, instructions, and event tools. Instruct it to use `event_reply` or another sending tool; model text alone does not prove delivery to Telegram.                          |
| Plugin processor | Install and configure the plugin processor, bind it to the bot, and save. Independent subscriptions can run alongside the main processor, so one message can produce two replies.            |

For attachment tasks, enable Box for the processor and use its sandbox tools and attachment delivery capabilities. Box must be ready. An external filesystem MCP server does not share Box's filesystem. Image understanding also requires a vision-capable model.

The bot's streaming toggle does not make every tool call stream tokens. An Agent's `event_reply` sends a complete message; plugin streaming depends on its implementation. Verify actual Telegram updates and processor logs separately.

## Private chats and groups

Click **Start** in a private chat first. For groups, add the bot to a test group and follow the processor's trigger rules, for example with a command addressed to the bot or a reply to its message.

Disabling **Privacy Mode** is not mandatory for every group scenario. Telegram delivers different messages for directed commands, replies, administrator bots, and ordinary group traffic. To receive ordinary group messages, adjust privacy mode in BotFather and re-add the bot when Telegram requires it, or grant administrator status where appropriate. See [Telegram's privacy mode documentation](https://core.telegram.org/bots/features#privacy-mode).

Member-status and reaction updates must satisfy Telegram's administrator requirements for those update types. Grant only the permissions the feature needs; do not enable deletion, bans, or adding administrators merely to receive events. Telegram delivery rules and LangBot trigger rules both apply.

Upgrading a basic group to a supergroup changes its ID. The Bot API group ID in event logs can also differ from the Telegram Web URL; do not construct a group ID from that URL.

## Images, files, and streaming

Images and files arrive as message attachments. Test with a clearly captioned image and a text file whose content can be checked. Verify the actual returned image or file rather than a textual claim that it was sent.

Streaming text progressively updates a Telegram message; attachments are sent separately at completion. Generated files must use the processor's attachment output mechanism, not just return a sandbox path. Images Telegram cannot process as photos are retried as documents to preserve their original bytes.

![Real group acceptance: the Agent identifies an image, reads a file, and returns a file and a generated image.](https://langbot.app/docs/images/telegram/agent-group-media.jpg)

## Other events

Bind an Agent or plugin processor to the required events. Pipelines primarily handle message flows; do not treat every non-message event as ordinary chat.

| Event                    | Trigger and meaning                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
| `message.received`       | A private or group message, including supported attachments.                                                |
| `message.edited`         | An existing message is edited.                                                                              |
| `message.reaction`       | A user adds or removes a reaction. `is_add` identifies the direction; `reaction` retains the removed emoji. |
| `group.member_joined`    | A member joins.                                                                                             |
| `group.member_left`      | A member leaves or is removed; inspect `is_kicked`.                                                         |
| `group.member_banned`    | A member is restricted, such as being muted; this does not mean they were removed.                          |
| `bot.invited_to_group`   | The bot is added to a group.                                                                                |
| `bot.removed_from_group` | The bot is removed, including when previously restricted.                                                   |
| `bot.muted`              | The bot loses permission to send messages. An indefinite restriction has `duration: null`.                  |
| `bot.unmuted`            | Sending permission is restored, even if other restrictions remain.                                          |
| `platform.specific`      | Other platform events, such as permission changes or callbacks. Inspect `action` and `data`.                |

Start with a logging-only plugin processor to confirm delivery before adding replies or moderation actions. A muted or removed bot may receive the event while no longer being able to reply in that group. Evaluate reception and sending permission separately.

## Troubleshooting

- **No reply:** check enabled state, saved bindings, private-chat Start, group privacy mode, and trigger rules, then inspect the processor run.
- **Delivered message but failed run:** expand the run and inspect tool results. A visible Telegram message alone does not prove the entire task succeeded.
- **Model errors or timeouts:** check the provider and model separately from Telegram delivery.
- **Only a file path is returned:** check Box, tool permissions, and whether the attachment sending tool actually ran.
- **Duplicate replies:** check overlapping main/independent subscriptions and multiple polling instances.
- **Missing reactions or member events:** check administrator status and event bindings. Test in a dedicated group without affecting real members.

---

# 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.

### Orchestration events

The new WeCom AI Bot adapter exposes these business events in both WebSocket and Webhook modes. Choose a processor for each event in the bot's event routing settings.

| Event                          | Use case and data                                                                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message.received`             | Handle incoming user messages for conversations or tasks.                                                                                         |
| `wecombot.enter_chat`          | Start a welcome or onboarding workflow when a user enters the bot chat. Includes the user, chat ID, and raw event data.                           |
| `wecombot.template_card_event` | Handle card clicks and submissions, branching on `task_id`, `event_key`, or `selected_items`. Includes card type, user, chat, and raw event data. |
| `feedback.received`            | Collect feedback on bot replies.                                                                                                                  |

WeCom sends the chat-entry event; it does not mean that a friend was added. Welcome replies must complete within the platform's 5-second window. Prefer a fast, fixed text response. LangBot uses the dedicated welcome API for text event replies and reports an expired window explicitly. Avoid slow model calls to generate welcome messages.

LangBot interaction forms and Dify forms continue through their existing callback flows, without also triggering a card business event. Connection, authentication, and reconnection states are not orchestration events.

### 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.

## Get the customer service link and QR code

After configuring the callback, obtain an entry point that WeChat users can use to start a conversation.

1. Return to the [WeChat Customer Service console](https://kf.weixin.qq.com/kf), open **Customer Service Accounts** (`客服帐号`), and create or select the account you want to connect to LangBot.
2. Open its integration page, scroll to **Integrate into apps or websites outside WeChat** (`在微信外App/网页中接入`), and click **Integrate** (`去接入`).

![Find the integration entry for apps and websites outside WeChat](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/customer-service-entry.png)

3. Find the account at the top of the integration page. Click **Copy Link** (`复制链接`) to obtain its customer service link, or **Generate QR Code** (`生成二维码`) to display its QR code.

![Copy the customer service link or generate a QR code](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/customer-service-link.png)

> info:
>
> The link in the screenshot is an example. Use the link or QR code generated for your own account. The Webhook callback URL delivers events to LangBot; the customer service link and QR code let users start a conversation.

## Test with WeChat

1. Enable the bot in LangBot and configure **Event Routing** to send **Message Received** events to the processor you want to use.
2. Scan the generated QR code with regular WeChat, enter the customer service conversation, and send a message.
3. Check the bot logs, session monitor, and the processor's execution logs in LangBot to confirm receipt and processing, then check for a reply in WeChat.

For a QR-code test, you do not need to configure the app association shown further down the integration page.

## Routable events

Select a processor for each event in the bot's **Event Routing** settings. Regular messages can use a Pipeline or Agent; other events require an Agent or plugin processor that supports them.

| Event                                                  | Event type                                  |
| ------------------------------------------------------ | ------------------------------------------- |
| Message received                                       | `message.received`                          |
| Customer or representative recalled a message          | `message.deleted`                           |
| Customer entered through a service link                | `wecomcs.enter_session`                     |
| Outgoing message failed                                | `wecomcs.msg_send_fail`                     |
| Representative availability changed                    | `wecomcs.servicer_status_change`            |
| Conversation accepted, transferred, closed or reopened | `wecomcs.session_status_change`             |
| Customer message rejection changed                     | `wecomcs.reject_customer_msg_switch_change` |

Recall events include the original message ID, operator and chat ID. Customer-service events retain account, customer and event-specific fields such as `welcome_code`, `fail_type` and `change_type`. Unknown events preserve their payload through `platform.specific`.

Entering through a service link triggers the entry event; reopening an existing chat from the chat list does not. Configure the processor's handling logic to send a welcome message; receiving the event alone does not send one.

### Reply windows and welcome messages

- Ordinary replies require the customer to send a message first and must be sent within 48 hours. Entering a session alone does not open this window. Error `95002` indicates that the sending time restriction was not met.
- For entry events, the Agent's `event_reply` uses the dedicated event response API with `welcome_code`. WeChat only supplies this credential when welcome-message conditions are met. It permits one message and expires after 20 seconds. Prefer a fast, fixed welcome message instead of waiting for a long model response.
- For session-status changes, `event_reply` uses `msg_code`, subject to its expiration and the current session state. Event replies currently support text. Missing, expired or used credentials cannot be reused; rerunning an old event does not extend their validity.

See the official [send message](https://developer.work.weixin.qq.com/document/path/94677) and [send event response](https://developer.work.weixin.qq.com/document/path/95122) documentation.

---

# 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

The current Official Account adapter supports three modes. Save the bot configuration after changing the mode. Existing bots keep their selected mode; the default remains `drop`. The legacy adapter does not offer `auto`.

| Mode             | How replies are delivered                                                                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auto`           | Returns a loading message, processes the request in the background, then tries the customer service API. If restricted, queues the answer for retrieval with the next message. |
| `passive`        | Returns a loading message and queues the answer. The user sends another message to retrieve it. Does not call the customer service API.                                        |
| `drop` (default) | Replies within the current callback. Suitable for replies completed within 5 seconds. Does not use the customer service API or fall back to retrieval.                         |

### How auto works

`auto` does not query the account's verification status in advance. When the processor sends its reply, LangBot calls the customer service API and uses the actual result:

- Success: the user receives the answer without sending another message.
- Permission denied (`48001`), expired reply window (`45015`), exhausted quota (`45047`), or recipient not following the account (`43004`): the answer is queued for retrieval with the next message.
- Other failures, including credentials, IP whitelist and network errors: an error is recorded instead of treating the failure as a permission restriction.

This decision is made for each reply. An initial loading message does not mean the answer has been generated; check processor execution logs if no answer arrives.

### Verification and reply windows

Callbacks require a response within **5 seconds**, regardless of verification. `drop` uses this callback; WeChat retries do not provide a reliable 15-second generation window. See the [official passive reply documentation](https://developers.weixin.qq.com/doc/service/guide/product/message/Passive_user_reply_message.html).

Customer service messages can be sent after the callback ends. WeChat currently requires enterprise verification for Official Accounts and Service Accounts to use this API. Identity verification alone does not grant this permission; actual account permissions and API responses determine availability.

| User action                                                             | Customer service message quota | Validity |
| ----------------------------------------------------------------------- | ------------------------------ | -------- |
| Sends a message                                                         | 5 messages                     | 48 hours |
| Clicks an eligible custom menu, follows the account, or scans a QR code | 3 messages                     | 1 minute |

These are platform limits, not AI generation timeouts. Consult the [official customer service API documentation](https://developers.weixin.qq.com/doc/service/api/customer/message/api_sendcustommessage) for current rules.

### Retrieving replies

In `passive`, or after `auto` falls back, the next message retrieves the previous answer and is **not also processed as a new question**. If the answer is still being generated, the loading message is returned again. Retrieve the answer before sending a new question.

`LoadingMessage` applies to both `auto` and `passive`, not `drop`. For `auto`, use wording such as “Processing your request. If no answer arrives, send any message later to retrieve it.” If empty, LangBot acknowledges the callback without a visible loading message.

Queued replies are stored in memory and cleared when LangBot restarts or the bot configuration is reloaded. All modes remain subject to WeChat content and message-length limits.

Route incoming messages to a processor. Reply modes do not automatically send every Agent text output: approve the reply-to-current-conversation tool and instruct the Agent to use it. Plugin processors must call the reply API.

## 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)

Select `auto`, `passive`, or `drop` in `Mode` using the comparison above. The default is `drop`.

The `LoadingMessage` option controls the loading message for `auto` and `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`          | On            | Read-write | Default limits | Default choice, including API access or dependency downloads |
| `offline`          | Off           | Read-write | Default limits | Offline tasks; preserves the previous default configuration  |
| `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                        |

`network_basic` is retained for compatibility and has the same settings as `default`.

Prefer least privilege: skip the network unless you need it (`offline` / `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 4.11：イベント駆動エージェントとプラグイン化された Runner](https://langbot.app/docs/ja/articles/langbot-v411-event-driven-agents.md) — 2026-10-15
- [新しい 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

## チュートリアルと連携

- [Turn GitHub Releases into Telegram Briefings with Dify and LangBot](https://langbot.app/docs/ja/articles/dify-langbot-github-release-briefing.md) — 2026-09-16
- [Route Support Questions in Discord and LINE with Dify and LangBot](https://langbot.app/docs/ja/articles/dify-langbot-support-triage.md) — 2026-09-16
- [A Dify Writing Assistant for Discord and Telegram with GPT-6 Astra and LangBot](https://langbot.app/docs/ja/articles/dify-langbot-writing-assistant.md) — 2026-09-16
- [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)

---

# Turn GitHub Releases into Telegram Briefings with Dify and LangBot

Source: https://langbot.app/docs/ja/articles/dify-langbot-github-release-briefing

Fetch a real GitHub release with Dify, extract the useful fields and let GPT-6 Astra write a sourced briefing. Connect the Workflow to LangBot with the correct input and output contract.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/dify-langbot-github-release-briefing).

公開日：2026-09-16 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

“What changed in the latest release?” sounds like a simple chatbot question. It becomes a data problem as soon as a repository ships something newer than the model knows.

We built an on-demand release briefing that reads GitHub first. Dify fetches the public release JSON, a code node keeps the useful fields, GPT-6 Astra writes a short summary, and LangBot returns it to the conversation. The example uses the public LangBot repository, and the same pattern works for other release feeds.

![The briefing comes from a live GitHub API request, with a source link.](https://langbot.app/docs/images/articles/source/images/dify-langbot/056-release-english-live-briefing.png)

*The briefing comes from a live GitHub API request, with a source link.*

## Start with a working Dify and LangBot installation

Start Docker Compose and Git, then follow the [Dify Docker Compose guide](https://docs.dify.ai/en/self-host/deploy/quick-start/docker-compose) and the [LangBot Docker guide](https://langbot.app/docs/en/deploy/langbot/docker.md) to bring up both services. For Dify, clone the repository, enter `docker`, copy `.env.example` to `.env`, and start Compose. The LangBot guide includes the application image and plugin runtime configuration.

The screenshots come from a local installation of **Dify 1.17.1 and LangBot v4.10.11**. We mapped the browser ports to `8088` and `5368`. Those are custom demo ports; the default installations normally use `80` and `5300`. With the defaults, open `http://localhost` and `http://localhost:5300`. You do not need to change ports just to match a screenshot. Create your own administrator accounts and select **English** in both interfaces.

![The first-run screen of the local Dify deployment.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-dify-install.png)

*The first-run screen of the local Dify deployment.*

![The local LangBot installation before administrator setup.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-langbot-install.png)

*The local LangBot installation before administrator setup.*

The important requirement is that **the LangBot container can reach Dify**. Our two services share a Docker network, so the Runner uses `http://nginx/v1`, where `nginx` is Dify's service name. You can attach Dify's `nginx` service and LangBot to the same external network in their Compose configurations. For separate hosts, use a Dify HTTPS address reachable from LangBot and append `/v1`. Every `http://nginx/v1` example below refers to our shared network; replace it for your own deployment. Inside a container, `localhost` points back to that container.

## Connect GPT-6 Astra to Dify

Open **Integrations → Model Provider**, install the official **OpenAI-API-compatible** provider, and choose **Add Model**. We tested provider version 0.0.66 with an OpenAI-compatible gateway.

| Field                                | Tutorial setting                                             |
| ------------------------------------ | ------------------------------------------------------------ |
| Model Name / endpoint model name     | `gpt-6-astra`                                                |
| Model Type / Completion mode         | LLM / Chat                                                   |
| Model display name                   | GPT-6 Astra                                                  |
| API Base URL                         | Your provider's compatible endpoint, usually ending in `/v1` |
| API Key                              | Your own provider key                                        |
| API Type                             | Chat Completions API                                         |
| Context size / maximum-token ceiling | 32768 / 4096 for this example                                |

Those limits are conservative settings for this tutorial, not a statement of Astra's full specifications. Save the model and let Dify validate the connection. Replace the gateway shown in the screenshot with your own authorized endpoint. Model names and capabilities depend on your provider. This walkthrough retains the `gpt-6-astra` identifier used in the tested deployment.

![The custom model form, captured before entering the API key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/014-dify-astra-model-settings.png)

*The custom model form, captured before entering the API key.*

## Create a Workflow with a clear input and output

Create a Dify **Workflow** named `Astra Release Briefing`. Each request is an independent read of the current release, so a Workflow fits naturally.

Connect these nodes:

`User Request → HTTP Request → Code → LLM → End`

![The complete five-node release workflow.](https://langbot.app/docs/images/articles/source/images/dify-langbot/045-release-workflow-overview.png)

*The complete five-node release workflow.*

### 1. Name the input for LangBot

In the Start node, add a required paragraph input named:

```text
langbot_user_message_text
```

LangBot's Dify Workflow Runner places the incoming message text in that field. If you call it `question` instead, the workflow may pass a manual Dify test and still fail when LangBot calls it with different input names.

![The required input is named to match the runner contract.](https://langbot.app/docs/images/articles/source/images/dify-langbot/049-release-workflow-input.png)

*The required input is named to match the runner contract.*

### 2. Read the latest public release

Use an HTTP Request node with GET:

```text
https://api.github.com/repos/langbot-app/LangBot/releases/latest
```

Add `Accept: application/vnd.github+json` and `User-Agent: LangBot-Dify-Tutorial`. This example reads public data without a GitHub token. Leave SSL verification enabled and choose sensible connection and read timeouts for your environment.

![The HTTP node fetches the latest release directly from GitHub.](https://langbot.app/docs/images/articles/source/images/dify-langbot/046-release-http-request-settings.png)

*The HTTP node fetches the latest release directly from GitHub.*

### 3. Extract the useful fields

Pass the HTTP node's `body` and `status_code` to a Code node. Keep only the information needed for a briefing:

```python
import json

def main(body: str, status_code: int) -> dict:
    if status_code != 200:
        return {"release": json.dumps({"error": f"GitHub HTTP {status_code}"})}
    data = json.loads(body)
    return {"release": json.dumps({
        "repository": "langbot-app/LangBot",
        "tag": data.get("tag_name"),
        "published_at": data.get("published_at"),
        "url": data.get("html_url"),
        "notes": (data.get("body") or "")[:14000],
    }, ensure_ascii=False)}
```

This removes avatars and unrelated API URLs from the model input. It also makes a non-200 response explicit. A transport failure can still stop the HTTP node before this code runs, which is why you should inspect failed workflow runs as well as successful ones.

![The Code node turns the raw response into a small release record.](https://langbot.app/docs/images/articles/source/images/dify-langbot/047-release-code-extraction-node.png)

*The Code node turns the raw response into a small release record.*

### 4. Write the briefing and return summary

Choose GPT-6 Astra in the LLM node. Ask it to answer in the user's language and include the repository, release tag, publication time, three useful highlights, and the source URL. Tell it to use only the supplied API data and to report missing data or an error instead of guessing.

Pass both `langbot_user_message_text` and the extracted `release` record into the user prompt. In End, map the LLM's `text` to an output named **`summary`**. This is the field LangBot expects from the workflow response.

![The final output maps the generated text to summary.](https://langbot.app/docs/images/articles/source/images/dify-langbot/054-release-summary-output-verified.png)

*The final output maps the generated text to summary.*

## Verify against GitHub, not against the screenshot

Our English and Chinese runs both retrieved `v4.10.11`, published on September 12, 2026 at 04:55:58 UTC. The briefing linked to that exact release and summarized changes in knowledge ingestion, monitoring, and platform compatibility.

![The English run includes a release tag, date, highlights, and source.](https://langbot.app/docs/images/articles/source/images/dify-langbot/056-release-english-live-briefing.png)

*The English run includes a release tag, date, highlights, and source.*

Your run may show a newer version. Compare the answer with the current API fields—`tag_name`, `published_at`, and `html_url`—rather than expecting the version in this article forever.

## Put LangBot in front of the app

Publish the saved version in Dify. Open **Access Point → Backend Service API → API Key** and create a key for this app.

In LangBot, choose **Create Pipelines**, name the pipeline `Astra Release Briefing`, and open **Configuration → AI**:

| Field    | Value                             |
| -------- | --------------------------------- |
| Runner   | Dify Service API                  |
| Base URL | `http://nginx/v1`                 |
| App Type | Workflow                          |
| API Key  | The Dify app key you just created |

The Dify app key belongs here. The Astra provider key stays in Dify. Save the pipeline, then use **Debug Chat** to check the complete request and response path before adding a messaging platform.

![The LangBot pipeline settings, captured before entering the app key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/078-langbot-release-workflow-settings.png)

*The LangBot pipeline settings, captured before entering the app key.*

## Ask for the briefing through LangBot

The English request through LangBot returned the same kind of source-linked briefing. I also tested Chinese output. One request hit a temporary upstream SSL interruption; a later retry succeeded. The failed run remains separate from the successful evidence.

![The workflow summary returned through LangBot.](https://langbot.app/docs/images/articles/source/images/dify-langbot/079-langbot-release-english-roundtrip.png)

*The workflow summary returned through LangBot.*

For Telegram or a Discord project channel, start with an on-demand command or mention trigger. This workflow reads the release when someone asks; scheduled delivery requires an additional scheduler and sending step.

To cover another repository, first duplicate the app and change the fixed API URL. Add a validated repository parameter only when you actually need it. A short, predictable integration is much easier to operate than an unrestricted URL-fetching bot.

## Connect it to Telegram and Discord

Choose **Create Bots** in LangBot, select your adapter, and enter credentials from that platform. After creating the bot, select the pipeline you just built. Check the pipeline's trigger rules for direct messages, group messages, and mentions before inviting it into a channel.

The measured path in this walkthrough is **LangBot → Dify → GPT-6 Astra → LangBot**. We inspected the real adapter forms below; we did not authorize a live Slack workspace, Discord server, Telegram bot, or LINE account for this demo.

| Platform   | Setup path                                                                                                                                                                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Slack      | Create a Slack app, grant the required bot scopes, install it to the workspace, and enter the Bot Token and Signing Secret in LangBot. Configure event subscriptions with the public HTTPS callback from the bot setup, verify it, and invite the bot to the intended channel. |
| Discord    | Create an application and bot in the Developer Portal. Enter Client ID and bot Token, enable the required message intents, then invite the bot with the appropriate channel permissions.                                                                                       |
| Telegram   | Create a bot with BotFather and enter its token. Start with a direct message; for groups, invite the bot and configure privacy mode and LangBot's trigger rules for the messages it should receive.                                                                            |
| LINE       | Create a Messaging API channel. Enter the Channel access token and Channel secret, configure the public HTTPS webhook, enable webhook delivery, and avoid conflicting automatic replies.                                                                                       |
| Mattermost | Enter the server URL and a Bot Account access token, then add that account to the relevant teams and channels. The adapter uses REST and WebSocket APIs.                                                                                                                       |

![The Discord adapter uses the application Client ID and bot token.](https://langbot.app/docs/images/articles/source/images/dify-langbot/059-platform-discord-fields.png)

*The Discord adapter uses the application Client ID and bot token.*

![The Telegram adapter uses a BotFather token and exposes reply options.](https://langbot.app/docs/images/articles/source/images/dify-langbot/060-platform-telegram-fields.png)

*The Telegram adapter uses a BotFather token and exposes reply options.*

The catalog also includes Matrix, Lark, DingTalk, WeCom, WeChat-related adapters, QQ, KOOK, OneBot v11, Satori, HTTP Bot, and Page Bot. See the [platform-specific LangBot guides](https://langbot.app/docs/en/usage/platforms/readme.md) for the permissions and networking required by each adapter. In particular, the local-only deployment above needs a suitable public HTTPS endpoint for webhook-based integrations such as Slack and LINE.

## Troubleshooting

When something fails, check the path in order: Dify preview, the published app version, LangBot's `/v1` base URL and app type, then the platform's event delivery. If you change Dify service passwords, keep Redis and Celery credentials aligned, and do the same for Sandbox and its code-execution client.

Our local proxy initially returned fake DNS addresses that Dify's SSRF proxy rejected. Correcting DNS fixed the plugin download without disabling network protections. For external API calls, inspect the run record after a retry rather than assuming that a transport error means the app configuration is wrong.

Project sources: [LangBot](https://github.com/langbot-app/LangBot) and [Dify](https://github.com/langgenius/dify). The deployment and screenshots are from September 16, 2026; later versions may move some controls.

## Further reading

- [A Dify Writing Assistant for Discord and Telegram with GPT-6 Astra and LangBot](https://langbot.app/en/blog/dify-langbot-writing-assistant)
- [Route Support Questions in Discord and LINE with Dify and LangBot](https://langbot.app/en/blog/dify-langbot-support-triage)

---

# 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)

---

# Route Support Questions in Discord and LINE with Dify and LangBot

Source: https://langbot.app/docs/ja/articles/dify-langbot-support-triage

Use GPT-6 Astra and a Dify Question Classifier to separate account help, product questions and requests for human review. Test each route through LangBot before connecting Discord or LINE.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/dify-langbot-support-triage).

公開日：2026-09-16 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

A single support prompt can work surprisingly well—until the same bot receives an expired invitation, an export question, and an angry refund request. Those messages need different responses and different limits.

We built a three-route support assistant in Dify, then connected it through LangBot. GPT-6 Astra classifies the request and writes a reply for the selected route. The result is small enough to inspect: one classifier, three response nodes, and three outputs.

![The actual support Chatflow, with separate account, product, and human-review routes.](https://langbot.app/docs/images/articles/source/images/dify-langbot/039-triage-three-branch-overview.png)

*The actual support Chatflow, with separate account, product, and human-review routes.*

## Start with a working Dify and LangBot installation

Start Docker Compose and Git, then follow the [Dify Docker Compose guide](https://docs.dify.ai/en/self-host/deploy/quick-start/docker-compose) and the [LangBot Docker guide](https://langbot.app/docs/en/deploy/langbot/docker.md) to bring up both services. For Dify, clone the repository, enter `docker`, copy `.env.example` to `.env`, and start Compose. The LangBot guide includes the application image and plugin runtime configuration.

The screenshots come from a local installation of **Dify 1.17.1 and LangBot v4.10.11**. We mapped the browser ports to `8088` and `5368`. Those are custom demo ports; the default installations normally use `80` and `5300`. With the defaults, open `http://localhost` and `http://localhost:5300`. You do not need to change ports just to match a screenshot. Create your own administrator accounts and select **English** in both interfaces.

![The first-run screen of the local Dify deployment.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-dify-install.png)

*The first-run screen of the local Dify deployment.*

![The local LangBot installation before administrator setup.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-langbot-install.png)

*The local LangBot installation before administrator setup.*

The important requirement is that **the LangBot container can reach Dify**. Our two services share a Docker network, so the Runner uses `http://nginx/v1`, where `nginx` is Dify's service name. You can attach Dify's `nginx` service and LangBot to the same external network in their Compose configurations. For separate hosts, use a Dify HTTPS address reachable from LangBot and append `/v1`. Every `http://nginx/v1` example below refers to our shared network; replace it for your own deployment. Inside a container, `localhost` points back to that container.

## Connect GPT-6 Astra to Dify

Open **Integrations → Model Provider**, install the official **OpenAI-API-compatible** provider, and choose **Add Model**. We tested provider version 0.0.66 with an OpenAI-compatible gateway.

| Field                                | Tutorial setting                                             |
| ------------------------------------ | ------------------------------------------------------------ |
| Model Name / endpoint model name     | `gpt-6-astra`                                                |
| Model Type / Completion mode         | LLM / Chat                                                   |
| Model display name                   | GPT-6 Astra                                                  |
| API Base URL                         | Your provider's compatible endpoint, usually ending in `/v1` |
| API Key                              | Your own provider key                                        |
| API Type                             | Chat Completions API                                         |
| Context size / maximum-token ceiling | 32768 / 4096 for this example                                |

Those limits are conservative settings for this tutorial, not a statement of Astra's full specifications. Save the model and let Dify validate the connection. Replace the gateway shown in the screenshot with your own authorized endpoint. Model names and capabilities depend on your provider. This walkthrough retains the `gpt-6-astra` identifier used in the tested deployment.

![The custom model form, captured before entering the API key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/014-dify-astra-model-settings.png)

*The custom model form, captured before entering the API key.*

## Define what each route is allowed to do

This example uses a fictional help-desk product called Northstar Desk. Its few product rules are included directly in the branch prompts, so you do not need a pre-existing knowledge base or another tutorial.

| Route   | Requests                                                                 | Job                                                                                 |
| ------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| Account | Login, invitations, workspace access                                     | Explain the invitation recovery steps                                               |
| Product | CSV export, trial limits, basic setup                                    | Answer from the small set of supplied product rules                                 |
| Human   | Billing, refunds, enterprise pricing, complaints, unclear mixed requests | Explain that a human decision is needed and help the user prepare a concise request |

The Human branch produces handoff guidance. It does not create a ticket, notify an employee, or approve a refund. That distinction belongs in the prompt: otherwise the assistant may casually imply it has performed an action that the workflow never implemented.

## Build the classifier and three branches

Create a **Chatflow** named `Astra Support Router`. Connect User Input to a **Question Classifier**, choose GPT-6 Astra, and set its query variable to `sys.query`.

Add these categories:

```text
Account: login, invitation, password or workspace access
Product: usage, ticket export, setup and trial limits
Human: billing, refunds, enterprise pricing, angry complaints
or unclear mixed questions
```

![The category descriptions define the routing boundary.](https://langbot.app/docs/images/articles/source/images/dify-langbot/040-triage-classifier-settings.png)

*The category descriptions define the routing boundary.*

In the classifier's advanced instructions, tell it to choose Human when essential context is missing or the request needs authorization. Connect each branch to its own LLM node and Answer node.

Use GPT-6 Astra in each LLM node and pass the user query through `sys.query`. Give the branches different system instructions:

- **Account Reply:** invitations expire after 48 hours. Ask the workspace owner to resend from `Settings > Members`. Never request passwords. Ask one clarifying question if the problem is different.
- **Product Reply:** owners export CSV tickets from `Settings > Data > Export`; export links last 7 days. The trial lasts 14 days and supports 5 teammates and 2 inboxes. Say when the supplied notes do not cover a question.
- **Human Reply:** acknowledge the request and explain that a human must decide. Ask for a brief issue summary and a non-sensitive reference. Tell the user to contact their support team, without inventing an address, response-time promise, or completed action.

All three prompts ask for concise replies in the user's language. Keeping the branch instructions separate makes a later change easier to review: adjusting billing guidance does not also change the login instructions.

## Test the path, not only the wording

We ran an expired-invitation question, a CSV-export question, and a refund complaint. The preview identified the selected output for each run:

| Test                  | Observed output | Response                                                   |
| --------------------- | --------------- | ---------------------------------------------------------- |
| Expired invitation    | Account Output  | Owner resend instructions and the 48-hour limit            |
| Export tickets as CSV | Product Output  | Correct menu path and 7-day availability                   |
| Refund complaint      | Human Output    | Human-review guidance without claiming a refund was issued |

![The account test follows the Account branch.](https://langbot.app/docs/images/articles/source/images/dify-langbot/041-triage-account-path-result.png)

*The account test follows the Account branch.*

![The export question follows the Product branch.](https://langbot.app/docs/images/articles/source/images/dify-langbot/043-triage-product-path-result.png)

*The export question follows the Product branch.*

Expand the workflow process in Preview when a result looks odd. A plausible sentence can hide an incorrect route. That is why the output name is part of the test, rather than treating every fluent answer as a pass.

## Put LangBot in front of the app

Publish the saved version in Dify. Open **Access Point → Backend Service API → API Key** and create a key for this app.

In LangBot, choose **Create Pipelines**, name the pipeline `Astra Support Router`, and open **Configuration → AI**:

| Field    | Value                             |
| -------- | --------------------------------- |
| Runner   | Dify Service API                  |
| Base URL | `http://nginx/v1`                 |
| App Type | Chat                              |
| API Key  | The Dify app key you just created |

The Dify app key belongs here. The Astra provider key stays in Dify. Save the pipeline, then use **Debug Chat** to check the complete request and response path before adding a messaging platform.

![The LangBot pipeline settings, captured before entering the app key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/053-langbot-triage-dify-settings.png)

*The LangBot pipeline settings, captured before entering the app key.*

## Run it through LangBot

The same expired-invitation question in LangBot returned the workspace-owner recovery steps. A later refund request in Chinese reached the human-review guidance. LangBot did not need its own copy of the classification rules.

![An account-support response returned through LangBot.](https://langbot.app/docs/images/articles/source/images/dify-langbot/055-langbot-triage-account-english.png)

*An account-support response returned through LangBot.*

Before putting this in a busy Discord server or a LINE support account, add ambiguous examples such as “I cannot log in and want a refund.” If those repeatedly land in Product, refine the category descriptions and classifier instructions.

When you are ready for a real handoff, add your existing ticketing or notification API to the Human branch and handle its success and failure explicitly. The example gives you a visible place to add that action later.

## Connect it to Discord and LINE

Choose **Create Bots** in LangBot, select your adapter, and enter credentials from that platform. After creating the bot, select the pipeline you just built. Check the pipeline's trigger rules for direct messages, group messages, and mentions before inviting it into a channel.

The measured path in this walkthrough is **LangBot → Dify → GPT-6 Astra → LangBot**. We inspected the real adapter forms below; we did not authorize a live Slack workspace, Discord server, Telegram bot, or LINE account for this demo.

| Platform   | Setup path                                                                                                                                                                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Slack      | Create a Slack app, grant the required bot scopes, install it to the workspace, and enter the Bot Token and Signing Secret in LangBot. Configure event subscriptions with the public HTTPS callback from the bot setup, verify it, and invite the bot to the intended channel. |
| Discord    | Create an application and bot in the Developer Portal. Enter Client ID and bot Token, enable the required message intents, then invite the bot with the appropriate channel permissions.                                                                                       |
| Telegram   | Create a bot with BotFather and enter its token. Start with a direct message; for groups, invite the bot and configure privacy mode and LangBot's trigger rules for the messages it should receive.                                                                            |
| LINE       | Create a Messaging API channel. Enter the Channel access token and Channel secret, configure the public HTTPS webhook, enable webhook delivery, and avoid conflicting automatic replies.                                                                                       |
| Mattermost | Enter the server URL and a Bot Account access token, then add that account to the relevant teams and channels. The adapter uses REST and WebSocket APIs.                                                                                                                       |

![The Discord adapter uses the application Client ID and bot token.](https://langbot.app/docs/images/articles/source/images/dify-langbot/059-platform-discord-fields.png)

*The Discord adapter uses the application Client ID and bot token.*

![LINE requires its channel access token and channel secret.](https://langbot.app/docs/images/articles/source/images/dify-langbot/061-platform-line-fields.png)

*LINE requires its channel access token and channel secret.*

The catalog also includes Matrix, Lark, DingTalk, WeCom, WeChat-related adapters, QQ, KOOK, OneBot v11, Satori, HTTP Bot, and Page Bot. See the [platform-specific LangBot guides](https://langbot.app/docs/en/usage/platforms/readme.md) for the permissions and networking required by each adapter. In particular, the local-only deployment above needs a suitable public HTTPS endpoint for webhook-based integrations such as Slack and LINE.

## Troubleshooting

When something fails, check the path in order: Dify preview, the published app version, LangBot's `/v1` base URL and app type, then the platform's event delivery. If you change Dify service passwords, keep Redis and Celery credentials aligned, and do the same for Sandbox and its code-execution client.

Our local proxy initially returned fake DNS addresses that Dify's SSRF proxy rejected. Correcting DNS fixed the plugin download without disabling network protections. For external API calls, inspect the run record after a retry rather than assuming that a transport error means the app configuration is wrong.

Project sources: [LangBot](https://github.com/langbot-app/LangBot) and [Dify](https://github.com/langgenius/dify). The deployment and screenshots are from September 16, 2026; later versions may move some controls.

## Further reading

- [A Dify Writing Assistant for Discord and Telegram with GPT-6 Astra and LangBot](https://langbot.app/en/blog/dify-langbot-writing-assistant)
- [Turn GitHub Releases into Telegram Briefings with Dify and LangBot](https://langbot.app/en/blog/dify-langbot-github-release-briefing)

---

# A Dify Writing Assistant for Discord and Telegram with GPT-6 Astra and LangBot

Source: https://langbot.app/docs/ja/articles/dify-langbot-writing-assistant

Build a basic Dify Chatbot for announcements, revisions and translations, then connect it to LangBot. Includes tested prompts, screenshots and Discord and Telegram setup guidance.

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/en/blog/dify-langbot-writing-assistant).

公開日：2026-09-16 · 著者：LangBot Team

> この記事の日本語版はまだ公開されていないため、英語版を掲載しています。

A community announcement usually starts as a few rough notes: a date, a channel, and something people need to bring. The first draft is easy. The annoying part is reopening another app for every “make it shorter” or “turn that into a Telegram reminder.”

We built a small writing assistant that keeps those revisions in the conversation. Dify owns the prompt and chat history, GPT-6 Astra writes the response, and LangBot provides the messaging-platform entry point. Here is the complete setup, including the local deployment and the replies We tested.

![A real response from Dify and Astra, shown in LangBot Debug Chat.](https://langbot.app/docs/images/articles/source/images/dify-langbot/025-langbot-writing-english-roundtrip.png)

*A real response from Dify and Astra, shown in LangBot Debug Chat.*

## Start with a working Dify and LangBot installation

Start Docker Compose and Git, then follow the [Dify Docker Compose guide](https://docs.dify.ai/en/self-host/deploy/quick-start/docker-compose) and the [LangBot Docker guide](https://langbot.app/docs/en/deploy/langbot/docker.md) to bring up both services. For Dify, clone the repository, enter `docker`, copy `.env.example` to `.env`, and start Compose. The LangBot guide includes the application image and plugin runtime configuration.

The screenshots come from a local installation of **Dify 1.17.1 and LangBot v4.10.11**. We mapped the browser ports to `8088` and `5368`. Those are custom demo ports; the default installations normally use `80` and `5300`. With the defaults, open `http://localhost` and `http://localhost:5300`. You do not need to change ports just to match a screenshot. Create your own administrator accounts and select **English** in both interfaces.

![The first-run screen of the local Dify deployment.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-dify-install.png)

*The first-run screen of the local Dify deployment.*

![The local LangBot installation before administrator setup.](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-langbot-install.png)

*The local LangBot installation before administrator setup.*

The important requirement is that **the LangBot container can reach Dify**. Our two services share a Docker network, so the Runner uses `http://nginx/v1`, where `nginx` is Dify's service name. You can attach Dify's `nginx` service and LangBot to the same external network in their Compose configurations. For separate hosts, use a Dify HTTPS address reachable from LangBot and append `/v1`. Every `http://nginx/v1` example below refers to our shared network; replace it for your own deployment. Inside a container, `localhost` points back to that container.

## Connect GPT-6 Astra to Dify

Open **Integrations → Model Provider**, install the official **OpenAI-API-compatible** provider, and choose **Add Model**. We tested provider version 0.0.66 with an OpenAI-compatible gateway.

| Field                                | Tutorial setting                                             |
| ------------------------------------ | ------------------------------------------------------------ |
| Model Name / endpoint model name     | `gpt-6-astra`                                                |
| Model Type / Completion mode         | LLM / Chat                                                   |
| Model display name                   | GPT-6 Astra                                                  |
| API Base URL                         | Your provider's compatible endpoint, usually ending in `/v1` |
| API Key                              | Your own provider key                                        |
| API Type                             | Chat Completions API                                         |
| Context size / maximum-token ceiling | 32768 / 4096 for this example                                |

Those limits are conservative settings for this tutorial, not a statement of Astra's full specifications. Save the model and let Dify validate the connection. Replace the gateway shown in the screenshot with your own authorized endpoint. Model names and capabilities depend on your provider. This walkthrough retains the `gpt-6-astra` identifier used in the tested deployment.

![The custom model form, captured before entering the API key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/014-dify-astra-model-settings.png)

*The custom model form, captured before entering the API key.*

## Build a basic Chatbot

In Dify Studio, choose **Create → Create from Blank → More basic app types → Chatbot**. Name it `Astra Writing Assistant`. A basic Chatbot is enough here: we need a clear prompt and conversation history, without a branching workflow.

![Dify keeps its basic Chatbot option under More basic app types.](https://langbot.app/docs/images/articles/source/images/dify-langbot/010-dify-create-basic-app.png)

*Dify keeps its basic Chatbot option under More basic app types.*

![Give the assistant a name and a specific job.](https://langbot.app/docs/images/articles/source/images/dify-langbot/011-dify-writing-app-create.png)

*Give the assistant a name and a specific job.*

Select GPT-6 Astra under **Configure model**, then add these instructions:

```text
You help a community manager turn rough notes into messages people can use.
Reply in the language of the user's request.
For an announcement, give: one clear headline, a short ready-to-send message,
and one optional reminder.
Preserve supplied dates, times, links, and requirements exactly.
Never invent missing event details, discounts, results, or promises.
If an essential detail is missing, ask one concise question.
Use a natural, direct tone. Avoid hype and excessive emojis.
Keep a typical reply under 180 words. When revising, use conversation context.
```

The most useful line is the one about preserving details. An announcement can survive plain wording. It cannot survive an invented RSVP link or the wrong time zone. We also kept the output short enough to be useful in a channel.

![The prompt gives the assistant a narrow job and clear boundaries.](https://langbot.app/docs/images/articles/source/images/dify-langbot/012-dify-writing-instructions.png)

*The prompt gives the assistant a narrow job and clear boundaries.*

For the first test, we entered:

> Write a Discord announcement: community demo day is September 22 at 18:00 UTC. Bring one bot demo. RSVP in #demo-day. Keep it friendly and under 100 words.

The response preserved the date, time, and channel. We then asked, “Make it shorter, and remove the optional reminder.” The second reply kept the details from the first turn without asking us to paste them again.

![The first English announcement generated in Dify.](https://langbot.app/docs/images/articles/source/images/dify-langbot/016-writing-english-first-reply.png)

*The first English announcement generated in Dify.*

![A follow-up instruction revises the existing announcement.](https://langbot.app/docs/images/articles/source/images/dify-langbot/019-writing-english-context-revision.png)

*A follow-up instruction revises the existing announcement.*

Publish the updated configuration with **Publish Update**. This step matters: an external caller should receive the version you just tested, rather than an older prompt still attached to the published app.

![The published app exposes a backend API for LangBot.](https://langbot.app/docs/images/articles/source/images/dify-langbot/023-writing-access-point-api.png)

*The published app exposes a backend API for LangBot.*

## Put LangBot in front of the app

Publish the saved version in Dify. Open **Access Point → Backend Service API → API Key** and create a key for this app.

In LangBot, choose **Create Pipelines**, name the pipeline `Astra Writing Assistant`, and open **Configuration → AI**:

| Field    | Value                             |
| -------- | --------------------------------- |
| Runner   | Dify Service API                  |
| Base URL | `http://nginx/v1`                 |
| App Type | Chat                              |
| API Key  | The Dify app key you just created |

The Dify app key belongs here. The Astra provider key stays in Dify. Save the pipeline, then use **Debug Chat** to check the complete request and response path before adding a messaging platform.

![The LangBot pipeline settings, captured before entering the app key.](https://langbot.app/docs/images/articles/source/images/dify-langbot/007-langbot-dify-runner-config.png)

*The LangBot pipeline settings, captured before entering the app key.*

## Test the same task through LangBot

We asked LangBot for a two-sentence Telegram reminder. The reply came back through Dify with the supplied date and time intact. A later request switched the same conversation to Chinese, which also worked.

For a community server, we would start with mention-based triggers in a single channel. Let members ask for a draft, shorten it, and adjust the tone before they decide to post it. That small loop is already useful for release announcements, event reminders, and repeated support replies.

![The writing assistant answering through the LangBot pipeline.](https://langbot.app/docs/images/articles/source/images/dify-langbot/025-langbot-writing-english-roundtrip.png)

*The writing assistant answering through the LangBot pipeline.*

## Connect it to Discord and Telegram

Choose **Create Bots** in LangBot, select your adapter, and enter credentials from that platform. After creating the bot, select the pipeline you just built. Check the pipeline's trigger rules for direct messages, group messages, and mentions before inviting it into a channel.

The measured path in this walkthrough is **LangBot → Dify → GPT-6 Astra → LangBot**. We inspected the real adapter forms below; we did not authorize a live Slack workspace, Discord server, Telegram bot, or LINE account for this demo.

| Platform   | Setup path                                                                                                                                                                                                                                                                     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Slack      | Create a Slack app, grant the required bot scopes, install it to the workspace, and enter the Bot Token and Signing Secret in LangBot. Configure event subscriptions with the public HTTPS callback from the bot setup, verify it, and invite the bot to the intended channel. |
| Discord    | Create an application and bot in the Developer Portal. Enter Client ID and bot Token, enable the required message intents, then invite the bot with the appropriate channel permissions.                                                                                       |
| Telegram   | Create a bot with BotFather and enter its token. Start with a direct message; for groups, invite the bot and configure privacy mode and LangBot's trigger rules for the messages it should receive.                                                                            |
| LINE       | Create a Messaging API channel. Enter the Channel access token and Channel secret, configure the public HTTPS webhook, enable webhook delivery, and avoid conflicting automatic replies.                                                                                       |
| Mattermost | Enter the server URL and a Bot Account access token, then add that account to the relevant teams and channels. The adapter uses REST and WebSocket APIs.                                                                                                                       |

![The Discord adapter uses the application Client ID and bot token.](https://langbot.app/docs/images/articles/source/images/dify-langbot/059-platform-discord-fields.png)

*The Discord adapter uses the application Client ID and bot token.*

![The Telegram adapter uses a BotFather token and exposes reply options.](https://langbot.app/docs/images/articles/source/images/dify-langbot/060-platform-telegram-fields.png)

*The Telegram adapter uses a BotFather token and exposes reply options.*

The catalog also includes Matrix, Lark, DingTalk, WeCom, WeChat-related adapters, QQ, KOOK, OneBot v11, Satori, HTTP Bot, and Page Bot. See the [platform-specific LangBot guides](https://langbot.app/docs/en/usage/platforms/readme.md) for the permissions and networking required by each adapter. In particular, the local-only deployment above needs a suitable public HTTPS endpoint for webhook-based integrations such as Slack and LINE.

## Troubleshooting

When something fails, check the path in order: Dify preview, the published app version, LangBot's `/v1` base URL and app type, then the platform's event delivery. If you change Dify service passwords, keep Redis and Celery credentials aligned, and do the same for Sandbox and its code-execution client.

Our local proxy initially returned fake DNS addresses that Dify's SSRF proxy rejected. Correcting DNS fixed the plugin download without disabling network protections. For external API calls, inspect the run record after a retry rather than assuming that a transport error means the app configuration is wrong.

Project sources: [LangBot](https://github.com/langbot-app/LangBot) and [Dify](https://github.com/langgenius/dify). The deployment and screenshots are from September 16, 2026; later versions may move some controls.

## Further reading

- [Route Support Questions in Discord and LINE with Dify and LangBot](https://langbot.app/en/blog/dify-langbot-support-triage)
- [Turn GitHub Releases into Telegram Briefings with Dify and LangBot](https://langbot.app/en/blog/dify-langbot-github-release-briefing)

---

# 新しい 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 4.11：イベント駆動エージェントとプラグイン化された Runner

Source: https://langbot.app/docs/ja/articles/langbot-v411-event-driven-agents

LangBot 4.11 の主要機能を実機スクリーンショットで紹介。イベントルーティング、AgentRunner のプラグイン化、Workspace Assistant、運用機能と移行手順を解説します。

この記事は LangBot Blog から同期されています。 [Blog の原文を読む](https://langbot.app/ja/blog/langbot-v411-event-driven-agents).

公開日：2026-10-15 · 著者：LangBot Team

LangBot は、複数のメッセージングサービス、大規模言語モデル、ナレッジベース、プラグインを接続し、AI アシスタントの構築・デプロイ・管理を支援するオープンソースの AI チャットボット・エージェントプラットフォームです。

チャットボットの基本は「メッセージを受け取り、返信する」ことです。ただ、実際のチームやコミュニティでは、会話以外にも作業のきっかけがあります。新しいメンバーの参加、回答へのリアクション、カードのボタンクリック。こうした操作も、次の処理につなげたい場面があります。

**LangBot 4.11 では、これらのイベントを設定可能な入り口として扱い、エージェントに渡し、実行状況を追跡できるようになりました。** AgentRunner のプラグイン化と Workspace Assistant により、「何をきっかけに、どの実行方式で処理し、どう管理するか」を整理しやすくなっています。

## 1. イベント駆動：次のメッセージを待つだけではない Bot へ

Event-Based Agents（EBA）は、通常のメッセージに加え、参加・退出、メッセージの撤回、リアクション、カード操作などのプラットフォームイベントを処理対象にします。今回のリリースでは、13 のプラットフォームアダプターが EBA アーキテクチャに基づいて書き直されました。

すべてのプラットフォームで同じイベントが使えるわけではありません。受信できるイベントは、プラットフォーム、アダプター、Bot に付与した権限によって異なります。共通化されたのは、受信したイベントを適切なプロセッサーへ渡す仕組みです。

![イベントの種類に応じてプロセッサーへ振り分ける設定](https://langbot.app/docs/images/articles/source/images/langbot-411/eba-event-routing.png)

*4.11 正式版リリースノートに掲載されたイベントルーティングの例。*

### まずは実現したいシナリオから

イベントルーティングでは、新規メンバーへの歓迎や退出時の処理といった、よく使うシナリオからルールを作成し、担当するプロセッサーを選べます。

たとえば、通常の質問はナレッジベースを使う Pipeline、新規参加者への案内は Agent、固定の業務ルールが必要なイベントはプラグインプロセッサーへ、と分担できます。これは構成例であり、そのまま動く設定ではありません。利用するイベントと権限を確認し、各ルートをテストしてから有効にしてください。

プラットフォームとの接続と業務処理を分けられるため、歓迎の手順が変わっても Bot の接続部分まで作り直す必要がありません。質問への回答方針も、ほかの振る舞いと一つのプロンプトに詰め込まずに管理できます。

### Pipeline・Agent・プラグインプロセッサーの使い分け

![実機で表示した三種類のプロセッサー作成画面](https://langbot.app/docs/images/articles/source/images/langbot-411/processor-types.png)

*この記事用に起動した LangBot 4.11.0 のプロセッサー作成画面。*

- **Pipeline**：メッセージイベントを決まった順序で処理します。AI による直接返信、ナレッジベースへの質問、既存のメッセージ処理に向いています。
- **Agent**：イベントへの対応を自然言語で指示し、AI に判断と実行を任せるか、外部の Agent プラットフォームへ接続します。状況に応じた判断が必要な処理に適しています。
- **プラグインプロセッサー**：プラグインが対応を宣言したイベントをコードで処理します。決定的なルールや専用の連携処理に向いています。

すべてを Agent に置き換える必要はありません。明確なルールはコードへ、定型的な質疑応答は Pipeline へ、判断が必要な部分は Agent へ。役割を分けるほうが、運用時にも理解しやすくなります。

### デバッグもイベントを中心に

イベントデバッガーでは、フォームでイベントデータを編集し、実行ログと詳細を確認できます。実際のチャットサービスで試す前に、入力フィールドや処理結果を確認する用途に便利です。ただし、デバッグ実行だけで接続・権限・実際のコールバックまで確認できるわけではありません。

関連するプラットフォーム改善には、Slack Socket Mode、DingTalk のカード操作、WeChat の入力中表示、OneBot WebSocket などがあります。対応範囲と設定方法は各プラットフォームのドキュメントを参照してください。

## 2. AgentRunner のプラグイン化：実行方式を独立して更新

これまで Core に組み込まれていた LocalAgent、Dify、Coze、n8n などの Runner は、拡張マーケットの公式プラグインへ移行しました。Codex、Claude Code、ACP などの Runner も追加されています。

![稼働中のインスタンスから開いた公式 Runner の一覧](https://langbot.app/docs/images/articles/source/images/langbot-411/marketplace-live.png)

*実機から読み込んだ拡張マーケットの Official Runner セクション。掲載内容は Core と独立して更新されます。*

利用者にとっての主な変化は、**必要な Runner を選んでインストールし、個別に更新できること**です。LocalAgent でモデル・ツール・知識検索を使う構成も、既存の Dify アプリや n8n ワークフローをチャットにつなぐ構成も、共通の Bot 接続基盤で扱えます。

開発者は AgentRunner Protocol v1 に基づいて独自の Runner を実装できます。特定の実行基盤向けの処理を Core に直接組み込む必要がなくなり、拡張の境界が明確になります。

![リリースノートに掲載された AgentRunner プラグイン](https://langbot.app/docs/images/articles/source/images/langbot-411/runner-plugins-marketplace.png)

*正式版リリースノートの Runner 一覧例。必要なアカウント、API、実行環境は Runner ごとに設定します。*

プラグイン化は、すべての権限を無条件に渡すことではありません。Runner が呼び出せるのは、現在のコンテキストで許可されたツールとプラットフォーム API です。マーケットには認証バッジが表示され、Core は認証プラグインの署名を検証します。出所の確認と権限管理に加え、導入前に説明を読み、自分の環境での動作条件も確認してください。

### 既存の Pipeline はどう移行する？

移行機能は必要なプラグインをインストールし、元の設定をバックアップします。アップグレード後に Pipelines 画面で移行を実行し、Runner、モデル、ナレッジベース、ツールの設定を見直してください。

**移行後の Pipeline は新しいセッションから開始します。** 旧式のカスタム Runner はプラグイン Runner として書き直す必要があります。オフライン環境では「データのみ移行」を選び、Runner プラグインを手動でインストールできます。詳しい対応関係は[設定移行マップ（中国語）](https://github.com/langbot-app/LangBot/blob/v4.11.0/docs/pipeline-migration-config-map.zh-CN.md)を参照してください。

## 3. Workspace Assistant：確認してから反映する対話型の設定

新しい Workspace Assistant は、Bot と会話するエンドユーザーではなく、LangBot を管理する人のための機能です。現在の Workspace にあるリソースを調べ、対話を通じて Pipeline やナレッジベースなどの作成・設定を支援します。

![実機の Workspace Assistant と実行状況ダッシュボード](https://langbot.app/docs/images/articles/source/images/langbot-411/workspace-assistant.png)

*新しいインスタンスでの初期画面。利用には LangBot Account へのログイン、またはモデル設定が必要です。監視データのゼロ表示は、この新規 Workspace の実際の空状態です。*

まずは「使えるモデル、ナレッジベース、Pipeline は？」といった読み取り専用の質問から始められます。そのうえで、ナレッジベースを使う質問応答アプリの作成を依頼します。単にフォームをチャットに置き換えるのではなく、現在あるリソースを確認したうえで設定案を出せる点が重要です。

**書き込み操作は、確認を受けてから実行されます。** 対象リソース、パラメーター、変更範囲を見てから承認してください。設定項目を探す手間を減らしつつ、変更の判断は管理者に残す仕組みです。

## 4. 新しい実行方式を支える運用機能

### メッセージ数だけでなく、実行の流れを見る

一つのイベントが Pipeline、Agent、プラグインのいずれかへ渡るようになると、問題の切り分けには処理全体の見通しが必要です。4.11 では統一実行ビュー、ツール呼び出しの追跡、処理中のタスクを示すリアルタイムパネルが追加・更新されました。

調査するときは、イベントを受信したか、どのプロセッサーへ渡ったか、モデルやツールの呼び出しが完了したか、の順に確認すると整理しやすくなります。「返信がない」という現象だけで、接続とルーティングと実行の問題を一緒に扱わずに済みます。

### アカウント保護と操作の追跡

![Passkey と二要素認証の設定画面](https://langbot.app/docs/images/articles/source/images/langbot-411/account-security.png)

*実機のアカウント設定。撮影用アカウントでは Passkey と二要素認証をまだ有効にしていません。*

WebAuthn による Passkey ログイン、TOTP による二要素認証に対応しました。また、変更内容を記録し、完全性を検証できる操作ログが追加されています。複数人で管理する Workspace では、ログイン保護と「誰が何を変えたか」の確認に役立ちます。Passkey はブラウザーのセキュアコンテキスト要件なども満たす必要があるため、適切な HTTPS 環境で設定してください。

メディアは内容に基づいて重複を排除して保存され、同じメディアによる `langbot.db` の肥大化を抑えます。さらに、`lbctl` と API Key による管理・診断が使えるため、コマンドラインを既存の運用手順に組み込むこともできます。

## 5. はじめての設定と、既存環境のアップグレード

![初回セットアップでプラットフォームを選択する画面](https://langbot.app/docs/images/articles/source/images/langbot-411/onboarding.png)

*実機の導入ウィザード。プラットフォームの選択から、Bot 設定、AI エンジンの設定へ進みます。*

新規ユーザーはサイドバーのガイドとシナリオ別の Bot 作成ウィザードを使えます。最初にシンプルな質疑応答を確認し、その後にナレッジベース、ツール、イベントルートを足していくと、問題が起きたときに原因を追いやすくなります。

既存環境では、次の順序で進めることをおすすめします。

1. **バックアップを取得する。** `data/` または PostgreSQL データベースと、現在のデプロイ設定を保存します。最新の v4.10.x からの更新を推奨します。
2. **Core と対応する Runtime を更新する。** 接続状態を確認してください。4.11.0 は SDK `0.7.11` に固定されているため、古い Runtime を混在させないようにします。
3. **Pipeline を移行し、プラグインを更新する。** 移行後の Runner 設定と、新しいセッションになる点を確認します。
4. **実際の利用経路をテストする。** 既存のメッセージ応答を先に確認し、その後でイベントルートや許可したツールを試します。
5. **テレメトリーと設定変更を確認する。** 新しい実行テレメトリーは既定で有効ですが、メッセージ内容は含みません。このテレメトリーは `space.disable_telemetry: true` で無効化できます。設定には `media_cache`、`api.host`、`runner.admin_plugins` が追加され、`force_box_session_id_template` は削除されました。[データ収集ポリシー（英語）](https://langbot.app/docs/en/insight/data-collection-policy.md)とリリースノートを参照してください。

## LangBot 4.11 を使い始める

4.11 がつなぐのは、**タスクのきっかけ、処理する実行方式、そして管理・観察の方法**です。従来のメッセージ応答はそのまま活かしながら、コミュニティでのやり取りやイベント起点の処理を少しずつ追加できます。

- [v4.11.0 と正式版リリースノート](https://github.com/langbot-app/LangBot/releases/tag/v4.11.0)
- [デプロイ・利用ドキュメント](https://langbot.app/docs/ja/insight/guide.md)
- [LangBot Cloud を利用する](https://cloud.langbot.app)

開発、テスト、ドキュメント、フィードバックに協力してくださった皆さんに感謝します。本記事は主要な製品更新に絞って紹介しました。貢献者の一覧は正式版リリースノートをご覧ください。

*画像について：イベントルーティングと Runner 一覧の二枚は v4.11.0 GitHub Release から引用しています。残る五枚は、この記事用に公式イメージ `rockchin/langbot:v4.11.0` を独立して起動し、実際の画面から撮影しました。各言語版で見比べやすいように UI は英語で統一しています。本番 Bot への接続は行っていません。*

---

# 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` に変更し、再起動します。Cloud の Plugin Runtime 運用状態の送信は、別の設定 `plugin.runtime_ops.enabled` で制御します。

環境変数 `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時にファイルの設定を上書きするため、併せて変更または削除してください。コンテナの環境変数を変更する場合はコンテナを再作成します。Cloud ではインスタンスの運用者が設定し、そのインスタンスの全ワークスペースに適用されます。Bot の動作や、メッセージングプラットフォーム、モデル提供者、プラグイン自体のプライバシー設定は変更しません。

### イベント単位の実行チェーン

現在の 4.11 は、送信条件を満たす実行について、プラットフォームイベント、ルーティング、Pipeline / Agent / プラグインのイベントプロセッサー、およびそこから生じるプラットフォーム API とツール呼び出しを、既定で全件記録します。ノード完了ごとに記録を生成し、実行終了時に終了記録を生成します。Space がチェーンを再構成します。同じ `space` セクションでの既定値は以下のとおりです。変更後は再起動してください。

業務ルートに一致しない、または `discard` ルールで無視され、一致するプラグイン購読もないプラットフォームイベントは、実行記録を送信しません。ローカルのログと監視は従来どおりです。一致する購読、有効な対話の再開、独立した WebUI/API/Pipeline 呼び出しは送信対象です。ルート一致後の対象利用不可、実行失敗、Pipeline 内部のフィルタリングも対象です。この判定はサンプリングより優先し、Cloud の `all` や失敗時の送信でも迂回できません。Core の更新が必要です。

```yaml
space:
  execution_trace: all        # off | failures | sampled | all
  execution_trace_sample: 20  # sampled：イベントのハッシュで成功した実行の約 1/N を保持
  telemetry_flush_seconds: 180  # 実行記録バッファの送信間隔（秒）
```

コミュニティ版のモードは以下のとおりです。

| モード        | 送信動作                                                                                |
| ---------- | ----------------------------------------------------------------------------------- |
| `all`      | 既定値。送信条件を満たすすべての実行のノードと終了記録を記録します                                                   |
| `sampled`  | イベント識別子の安定したハッシュで一度だけ判定し、同じ実行の全記録が判定を共有します。対象外の実行が失敗した場合も終了記録は送信しますが、省略したノードは復元しません |
| `failures` | 通常の実行ではノードを保持せず、失敗・キャンセル・タイムアウト、またはチェーンの失敗理由がある場合の終了記録のみを送信します                      |
| `off`      | ノードと終了記録を送信せず、独立した集計カウンターの送信も継続しません。ハートビートは `disable_telemetry` に従います               |

WebUI のデバッグ実行は `all`、`sampled`、`failures` ではデバッグフラグ付きで保持します。`off` または `disable_telemetry: true` では送信しません。**Cloud は製品テレメトリが有効な場合、常に `all` を使用し、上記のサンプリングモード設定を適用しません。** インスタンス運用者は全体のスイッチで製品テレメトリを無効にできます。

`execution_trace_sample` は 1–100000、`telemetry_flush_seconds` は 1–86400 の整数を受け付けます。無効な値はそれぞれ 20 と 180 に、無効なモードは `all` に戻ります。サンプリングは実行順に正確に N 件ごとに選ぶ方式ではありません。

1 回の送信は最大 128 件、バッファは最大 512 件です。送信失敗時は記録を保持して再試行し、満杯になると最も古い記録を破棄するため、全件記録でも完全な到達は保証されません。アクティブなワークスペースは起動約 30 秒後に最初のハートビートを送信し、その後、通常のデプロイでは毎日、Cloud runtime では 5 分ごとに送信します。実行の生データは 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/enterprise/overview

オープンソース版 LangBot に、公式の問題受付、セキュリティ情報、調達用の契約書と請求書を。

LangBot エンタープライズサポート（LangBot Enterprise Support）は、**公式のサポート関係**と**正式な調達書類**を必要とする企業向けのサービスです。購読料は LangBot の継続的な開発にも直接充てられます。

> info:
>
> LangBot は引き続き Apache License 2.0 で無料提供されます。本サービスは**商用利用ライセンスではありません**。機能の解除はなく、未契約企業の利用も制限しません。

## プラン

|                                | 企業サポートプラン                   | 企業保障プラン                |
| ------------------------------ | --------------------------- | ---------------------- |
| 年額（米ドル）                        | US$599                      | US$1,199               |
| 対象                             | 正式なサポート関係を結び、プロジェクトを支援したい企業 | LangBot を本番環境で利用している企業 |
| 契約書・請求書・年次証明書                  | ✓                           | ✓                      |
| 企業チケット、2 営業日以内の初回応答            | ✓                           | ✓                      |
| 重大なセキュリティ通知、四半期のリリース・セキュリティまとめ | ✓                           | ✓                      |
| 年次利用状況レビュー（60 分）               | 1 回                         | 1 回                    |
| 公開ロードマップ提案の優先審査                | ✓                           | ✓                      |
| 支援企業一覧への掲載（同意制、匿名可）            | ✓                           | ✓                      |
| 本番インスタンスの登録                    | —                           | 1 件                    |
| リモート技術相談（各 60 分）               | —                           | 年 4 回                  |
| 更新前の互換性相談、障害の優先切り分け            | —                           | ✓                      |
| 確認済み Core 不具合の優先修正キュー登録        | —                           | ✓                      |
| 年次のバージョン・依存関係・セキュリティ状態の説明      | —                           | ✓                      |

料金は契約企業単位の年額で、人数やデプロイ数による課金はありません。税金、請求書の種類、サービス期間は正式な見積・契約によります。

## 次のステップ

- [サービス範囲と応答](https://langbot.app/docs/ja/enterprise/service-scope.md)：対象・対象外、応答時間の数え方
- [チケットの送信](https://langbot.app/docs/ja/enterprise/submit-ticket.md)：契約企業のサポート依頼方法
- [調達と利用開始](https://langbot.app/docs/ja/enterprise/procurement.md)：契約、請求書、提供物

お問い合わせは[お問い合わせフォーム](https://langbot.app/ja/enterprise#enterprise-contact)から、利用シーン・業種・お立場・連絡先をご入力ください。1〜2 営業日以内にご連絡します。

---

# 調達と利用開始

Source: https://langbot.app/docs/ja/enterprise/procurement

エンタープライズサポートの契約、請求書、提供物。

## 利用開始までの流れ

1. **お問い合わせ**：[お問い合わせフォーム](https://langbot.app/ja/enterprise#enterprise-contact)に利用シーン・業種・お立場・連絡先をご入力ください。1〜2 営業日以内にご連絡します。
2. **見積の確認**：範囲、税金、請求書について確認し、年間サービス契約を締結します。
3. **支払いと登録**：契約に従って支払い、担当者、Space アカウント、サービス期間を登録します。
4. **利用開始**：証明書とサービス説明を受け取ったら、[チケットを送信](https://langbot.app/docs/ja/enterprise/submit-ticket.md)できます。

> info:
>
> 最初のご連絡は利用シーン・業種・お立場・連絡先だけで十分です。請求書用の情報は契約前にご提供ください。銀行・税務情報を公開チケットや GitHub で送らないでください。

## 契約と請求書

| 項目     | 内容                                           |
| ------ | -------------------------------------------- |
| 契約主体   | LangBot プロジェクトの運営法人（詳細は見積書・契約書でご案内）          |
| 契約対象   | LangBot オープンソースソフトウェアの年間保守、リリース情報、技術サポートサービス |
| 料金     | 契約企業単位の年額、人数課金なし                             |
| 請求書の品目 | 発行可能な範囲で経理が確認（ソフトウェアサービス費、技術サポート費など）         |

寄付や商用ソフトウェアライセンス料としての請求書は発行しません。

## 提供物

- サービス期間と担当者を記載したサービス注文書・契約書
- 年次サポート証明書（サポート関係を証明するもので、追加のソフトウェアライセンスではありません）
- 版管理されたサービス範囲の説明、Space チケット窓口とアカウント登録
- 保障プラン：本番インスタンス登録と技術相談枠
- 期間中：四半期の保守まとめ、チケット・相談記録。保障プランは年次のバージョン・依存関係・セキュリティ状態の説明も含みます

支援企業一覧への掲載は別途同意が必要で、匿名も選べます。サービス説明の後日の変更は、締結済み契約の内容を変えません。

## 更新

更新は別途確認し、自動課金はありません。開始、終了、解約、返金は契約によります。

本サービスには LangBot Cloud の計算資源、モデル利用枠、ホスティングは含まれません。期間終了後も Apache 2.0 に基づき LangBot を利用できます。

---

# サービス範囲と応答

Source: https://langbot.app/docs/ja/enterprise/service-scope

エンタープライズサポートの対象・対象外と、初回応答時間の計算方法。

エンタープライズサポートの対象は **LangBot Core そのもの**です。統一チケット窓口での切り分けと案内を提供し、運用代行やカスタム開発は行いません。

## 対象と対象外

| 対象                       | 対象外                                     |
| ------------------------ | --------------------------------------- |
| LangBot Core の不具合確認と切り分け | 導入代行、運用代行、24 時間対応、常駐                    |
| 公式ドキュメントの案内              | 顧客のネットワーク、データベース、Kubernetes、モデル提供者の障害調査 |
| 更新時の互換性に関する助言            | プラグイン、第三者アダプター、非公開プロトコルクライアントの保守        |
| 公開リリース情報とセキュリティ告知        | カスタム開発、過去データの移行                         |
| チケットの受付と切り分け             | 復旧 SLA、修正期限の保証、適合性認証                    |

カスタム開発は対象外で、原則としてお受けしていません。汎用的な要望は公開ロードマップに提案できます。

## 初回応答

両プランとも **2 営業日以内の初回有人応答**をお約束します。初回応答とは、担当者が範囲を確認する、追加情報を依頼する、または初期分類を行うことを指し、自動通知メールは含みません。

> warning:
>
> 初回応答は修正や復旧の保証ではありません。修正は重大度、再現性、LangBot Core の問題かどうかによります。

- **受付時間**：中国本土の営業日 09:00–18:00（北京時間）。振替出勤日を含み、法定休日は除きます。
- **計算方法**：受付時間内の依頼は送信時刻から、時間外の依頼は翌営業日 09:00 から数えます。
- **例**：金曜 14:00 に送信 → 火曜 14:00 までに応答。金曜 20:00 に送信 → 水曜 09:00 までに応答。

## 対象バージョン

- 対象は LangBot Core の**最新安定版**です。旧バージョンではまず更新をご提案し、不具合の確認には最新安定版での再現をお願いする場合があります。
- 過去バージョンへのバックポート、LTS ブランチ、個別パッチは提供しません。
- プラグインや第三者コンポーネントは Core の保守対象外です。

## 相談と回数

|                    | 企業サポートプラン | 企業保障プラン |
| ------------------ | --------- | ------- |
| 年次利用状況レビュー（60 分）   | 1 回       | 1 回     |
| リモート技術相談（60 分、要予約） | —         | 4 回     |

未使用分は翌年に繰り越せません。企業サポートプランはチケットの切り分け、ドキュメント案内、不具合確認を提供し、顧客環境の継続的なリモート調査は含みません。

## インスタンス登録（保障プラン）

- 保障プランは**登録済みの本番インスタンス 1 件**が対象です。登録はサポート範囲を定めるためのもので、Apache 2.0 で認められるデプロイ数を制限せず、ライセンスキーやテレメトリーも不要です。
- 登録内容はバージョン、デプロイ概要、用途、担当者です。インスタンスを入れ替える場合はチケットで登録を更新してください。

## セキュリティ情報

- 四半期まとめは公開されたリリース・セキュリティ情報に基づきます。
- 重大なセキュリティ通知はメンテナーが確認した告知に基づきます。お客様の環境が影響を受けるかどうかの判定は行いません。
- 年次の状態説明（保障プラン）は登録バージョンと公開情報に基づくもので、セキュリティ監査、ペネトレーションテスト、適合性認証ではありません。

## 対応の原則

- 1 チケットにつき 1 件の問題とし、重複は統合する場合があります。
- 優先修正キューへの登録は修正期限を保証せず、ロードマップの優先審査も開発やスケジュールを約束するものではありません。
- サポートはチケットで行い、グループチャットでの個別対応は行いません。

## サービス期間

言語、担当者、サービス期間、適用されるサービス説明の版は契約で定めます。期間終了後は新しい依頼を受け付けず、受付済みのチケットは契約に従って切り分けまたは引き継ぎを行います。終了後もオープンソース版 LangBot は引き続き利用できます。

---

# チケットの送信

Source: https://langbot.app/docs/ja/enterprise/submit-ticket

契約企業が LangBot Space で問題報告や相談予約を行う方法。

> idea:
>
> [LangBot Space でチケットを送信 →](https://space.langbot.app/profile?tab=tickets\&language=ja)

## 手順

1. 契約で登録した Space アカウントでログインします。
2. **プロフィール → チケット**でテンプレートを選びます。
   - **Enterprise Support: issue intake**：LangBot Core の不具合と思われる問題の報告
   - **Enterprise Support: upgrade and consultation**：更新時の互換性、技術相談の予約（保障プラン）、ドキュメント・調達資料
3. 契約番号と企業名を入力し、フォームに記入します。

権利を確認する前に、契約、登録アカウント、サービス期間を照合します。契約番号だけでは本人確認になりません。

## 用意する情報

**問題の報告**

- LangBot のバージョンとデプロイ方法
- 期待する動作と実際の動作
- 再現手順
- マスキング済みのログ（ない場合は理由）
- 業務への影響

**更新・相談**

- 登録インスタンスと現在のバージョン、目標バージョン（該当する場合）
- 相談の目的と背景
- 希望日時（打ち合わせが必要な場合）

> warning:
>
> アクセストークン、パスワード、チャット履歴全体、個人情報、設定ファイルそのものは送信しないでください。スクリーンショットはマスキングしてください。脆弱性の詳細を公開 GitHub issue に投稿しないでください。

## 送信後

契約を確認したうえで切り分けを行い、次のいずれかで対応します。

- ドキュメントの案内、または追加情報の依頼
- 技術相談の予約（保障プラン）
- LangBot Core の不具合として確認し、公開の保守プロセスへ
- 対象外であることのご説明

確認された一般的な不具合は、必要最小限のマスキング済み再現情報のみを公開保守に回します。契約、ログ、業務情報が公開 GitHub に同期されることはありません。追加情報は同じチケットに返信してください。

---

# コミュニティリソース

Source: https://langbot.app/docs/ja/insight/community

LangBot コミュニティリソース：オープンソース AI ボットの GitHub・Discord・ドキュメント・サポート。

## 簡易チュートリアル

> 簡易チュートリアル:ビデオチュートリアル、より簡単なテキストチュートリアルなど、初心者に適しています

こちらで収集されています: <https://blog.thelazy.top/tags/langbot>

## 🥰 コミュニティ

Discordコミュニティに参加してください: [Discord](https://discord.gg/wdNEHETs87)

---

# データ収集ポリシー

Source: https://langbot.app/docs/ja/insight/data-collection-policy

任意のテレメトリ、実行チェーン、収集範囲と無効化の方法

LangBot は利用状況の把握と信頼性の改善のため、`space.url` で設定された LangBot Space サービス（既定は `https://space.langbot.app`）に製品テレメトリを送信します。**既定で有効ですが、無効にできます。** このページは 4.11 の現在の実行テレメトリプロトコル（`schema: 2`）を説明します。旧バージョンのデータについては後述します。

## 実行テレメトリ

送信条件を満たす 1 回の実行は、同じ `event_id` を持つ独立した記録で構成されます。各ワークフローノードの完了時に `execution_node`、実行の終了時に `execution_chain` を 1 件生成します。Core は上限付きバッファに記録を格納し、バックグラウンドでまとめて送信します。Space がノードから実行チェーンを再構成します。現在の送信側は、旧方式の集計カウンターやローカルでの完全なチェーン組み立てを使用しません。

**業務ルートに一致しない、または選択されたルートが `discard`（無視・破棄）で、一致するプラグイン購読もないプラットフォームイベントは、ノードも終了記録も送信しません。** 無効なルートやイベント種類・フィルターの不一致も対象です。ローカルのログと監視は従来どおりです。主ルートが一致しなくてもプラグインのイベントプロセッサーが一致すれば、その実行は送信対象になります。不一致・破棄の分岐はテレメトリに含めません。

業務ルートに一致した後の対象利用不可、実行失敗、タイムアウト、Pipeline 内部のフィルタリングは引き続き送信対象です。元の処理を再開する有効な対話コールバック、WebUI/API デバッグ、Pipeline を明示的に指定した独立呼び出しも対象です。無効なコールバックだけでは送信対象になりません。この判定はサンプリングや失敗時の送信より優先し、Cloud にも適用します。Core の更新後に有効となり、旧クライアントや過去の記録は遡って変更しません。

| データ         | 内容                                                                                                                                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 識別子と環境      | `instance_id`、`workspace_uuid`、`event_id`、バージョン、エディション、タイムスタンプ、デバッグフラグ、サンプリング情報                                                                                                                                                 |
| 実行ノード       | プラットフォームイベント、ルーティング、Pipeline、Runner、プラットフォーム API、ツール呼び出しの操作識別子、処理モード、結果、開始/終了時刻、親子関係と順序、ルーティング先、Runner の実行識別子                                                                                                                   |
| チェーン終了      | 全体の結果、終了理由（`completed` は受信イベントとキューに渡した下流処理がすべて終了、`merged` はメッセージ集約で別のチェーンに統合され `merged_into` を付与、`timeout` は引き渡した下流処理が 30 分以内に戻らなかった場合）、所要時間、ノード数、サンプリングで送信しなかったノード数、実行元、モデル名、アダプター、Runner、パイプラインプラグイン                          |
| 機能の使用       | `features` に実行ごとの整数カウンターを記録します。提供元別ツール呼び出し、サンドボックス実行とエラー、ナレッジベース検索試行、スキル有効化、LLM 呼び出し試行（再試行を含む）。ゼロは省略し、各値の上限は 65,535 です。これらのカウンターにツール引数、出力、スキル名は含みません                                                                            |
| バインドされたリソース | Pipeline や Agent に許可されたプラグイン、MCP サーバー、ナレッジベース、ツールとその提供元、スキル、モデル、プラットフォーム API の識別子や名前、および選択フィールド、能力、権限フラグ。項目は実行経路により異なります                                                                                                        |
| エラー         | 調査用の完全なエラー記述：例外クラス、メッセージ、`Caused by` の原因チェーン、traceback 末尾数フレームのファイル・行番号・関数名（ソース行は含みません）。上限は約 4,000 文字で、超過時は先頭と末尾を残します。送信前に一般的な認証情報の形式（`sk-` キー、Bearer トークン、`api_key=`/`token=`/`password=` などのキー値、URL の秘密パラメーター）とメールアドレスをマスクします |

バインドされたリソースは、その実行で使用するよう設定された、または使用が許可されたリソースです。**実際の呼び出し、検索、消費を示すものではありません。** ルーティング先は `type:uuid` 形式で報告され、ユーザー定義のルール名は使用しません。

`model_name` は Pipeline、Agent、イベントプロセッサーの各経路で最初に呼び出した LLM を示し、UTF-8 で 128 バイト以内に切り詰めます。機能カウンターは既存のチェーン終了記録にのみ追加します。テレメトリを無効にするか `space.url` を空にすると、送信だけでなくカウントも停止します。

実行記録は、メッセージ本文、プロンプト、モデルの回答、プラットフォームのユーザー/グループ ID、ツール/API の引数や結果を意図的に収集しません。**ただし、認証情報のマスキングは一般的な形式との照合であり、確実なマスキングではありません。例外メッセージ（モデルサービスが返したエラー原文など）やユーザー定義のモデル・スキル・リソース名には、機密情報やユーザーコンテンツが含まれる可能性があります。** インスタンスとワークスペースの識別子がデプロイ環境やアカウントに結び付く場合があるため、匿名データではなく、ユーザーコンテンツを一切含まないとも保証できません。

### サンプリングとデバッグ実行

コミュニティ版では `space.execution_trace` で実行の送信を設定します。

| モード        | 動作                                                                                                                |
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `all`（既定）  | 送信条件を満たすすべての実行のノードと終了記録を記録します                                                                                     |
| `sampled`  | 入口でイベント識別子の安定したハッシュに基づき一度だけ判定し、成功した実行の約 `1/N` を保持します。N は `space.execution_trace_sample`（既定 20）で、同じ実行の全記録が判定を共有します |
| `failures` | 通常の実行ではノードを保持せず、失敗・キャンセル・タイムアウト、またはチェーンの失敗理由がある場合に終了記録のみを送信します                                                    |
| `off`      | ノードと終了記録を無効にします。独立した集計カウンターの送信は継続しません。ワークスペースのハートビートは全体のテレメトリ設定に従います                                              |

`sampled` で対象外になった実行が失敗した場合も、終了記録は送信します。ただし省略済みのノードは復元しないため、完全なチェーンがなく概要だけになる場合があります。WebUI のデバッグ実行は `all`、`sampled`、`failures` ではデバッグフラグ付きで保持します。`off` または全体の無効化設定では送信しません。

**Cloud は製品テレメトリが有効な場合、常に `all` を使用します。** 成功した実行のサンプリングが活動件数に影響することを避けるためです。インスタンス運用者は `space.disable_telemetry` で、このページの製品テレメトリを無効にできます。

### 送信と完全性

記録は `POST /api/v1/telemetry` に送信します。既定の送信間隔は 180 秒で、`space.telemetry_flush_seconds` で変更できます。1 回の送信は最大 128 件、メモリ内のバッファは最大 512 件です。送信が受け付けられた記録だけをバッファから削除し、失敗時は再試行します。バッファが満杯になると最も古い記録を破棄します。終了時には、限られた時間内で残りの記録の送信を試みます。

ネットワーク障害、タイムアウト、サーバーエラーによる送信失敗は業務処理を失敗させず、送信失敗の詳細は DEBUG ログに記録します。サンプリング、バッファ超過、プロセス終了、タスク間の関連付けの期限切れにより、不完全なチェーンになる場合があります。**全件記録モードでも完全な到達は保証されません。** プラットフォーム API の成功応答だけでは、ユーザーがメッセージを読んだことも確認できません。

## ハートビート、アンケート、旧バージョンのデータ

アクティブなワークスペースは起動約 30 秒後に最初の `instance_heartbeat` を送信します。通常のデプロイでは以後毎日、Cloud runtime では 5 分ごとに更新します。デプロイ環境、データベース/ベクトルデータベースの種類、サンドボックス設定と可用性、アダプターの種類、および Bot、Pipeline、プラグイン、Agent、イベントプロセッサー、イベントバインディング、MCP サーバー、ナレッジベース、スキルなどの数を含みます。リソース本文や接続用の認証情報は意図的に含めません。

任意参加のアプリ内アンケートでは、アンケート ID、送信した回答、インスタンス ID、バージョン、完了/閉じた状態を送信します。回答はユーザーが自発的に提供するコンテンツです。

Space は旧バージョンの `query` と `feature_execution` データにも対応しています。旧クエリ記録にはモデル名、機能カウンター、ユーザー定義のスキル/MCP 名、生の traceback が含まれる場合があります。現在の実行記録の制限は、過去のデータをマスキングしたり、稼働中の旧クライアントの送信内容を変更したりするものではありません。

## 保存と保持期間

データは設定された Space サービスに保存されます。実行一覧、チェーン詳細、集計は、権限を持つテレメトリ管理ユーザーまたはサービスクライアントのみが利用できます。`execution_node`、`execution_chain`、旧 `feature_execution` の生データは 30 日の保持期間に基づき、定期的に上限付きバッチで削除します。滞留やサービス停止で削除が遅れる場合があります。旧クエリテレメトリ、ハートビート、アンケート、アカウント、サービスログの保持規則は変更しません。

無効化すると以後の送信は停止しますが、サーバーに保存済みの記録は削除されません。過去のデータについては <hello@langbot.app> または利用中の Space 管理者にお問い合わせください。

## テレメトリの無効化

`data/config.yaml` の既存の `space` セクションで次を設定し、他の設定を保持したうえで LangBot を再起動します。

```yaml
space:
  disable_telemetry: true
```

このスイッチは、このページで説明した製品テレメトリとアンケート取得を無効にします。引用符を付けず YAML の真偽値を使用してください。既定の有効状態に戻すには `false` に変更し、再起動します。

環境変数 `SPACE__DISABLE_TELEMETRY` が設定されている場合、起動時にファイルの設定を上書きするため、併せて変更または削除してください。コンテナの環境変数を変更する場合はコンテナを再作成します。Cloud ではインスタンスの運用者が設定し、そのインスタンスの全ワークスペースに適用されます。Bot の動作や、メッセージングプラットフォーム、モデル提供者、プラグイン自体のプライバシー設定は変更しません。

Cloud の Plugin Runtime 運用状態の送信は製品テレメトリとは別で、`plugin.runtime_ops.enabled` で制御します。`space.disable_telemetry` では無効になりません。

[システム設定](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
> まず https://langbot.app/llms.txt を読み、公式の手順に従って LangBot の導入と利用、LangBot CLI のインストール、CLI によるインスタンスの設定と管理を手伝ってください。目的と環境に合わせ、既存のインスタンスがあれば再利用し、最後に対象のチャットプラットフォームで実際のメッセージと返信を確認してください。日本語で説明してください。
> ```

---

# 各メッセージプラットフォームの機能サポート

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` も含まれます。これらは現在の実行に対応するインスタンスとワークスペースを示すためのもので、プラグイン側の認可情報として使用しないでください。

リトライ、タイムアウト、数値思考予算、prompt caching、ヘッダー、ストリーム終了は [LLM リクエスト設定](https://langbot.app/docs/ja/plugin/dev/apis/llm-requests.md)を参照してください。

## 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) を参照してください。

リトライ、タイムアウト、数値思考予算、prompt caching、ヘッダー、ストリーム終了は [LLM リクエスト設定](https://langbot.app/docs/ja/plugin/dev/apis/llm-requests.md)を参照してください。

> info:
>
> このページのほとんどのメソッドには、プラグインが `manifest.yaml` で宣言し、インストール後にワークスペースのメンバーが許可した機能が必要です。たとえば `invoke_llm` には `models.invoke`、`send_message` には `bot.message.send` が必要です。許可のない呼び出しは `permission_denied` になります。各メソッドに必要な機能は[プラグインの権限](https://langbot.app/docs/ja/plugin/dev/permissions.md#機能)を参照してください。Agent、パイプライン、ボットなどのワークスペースリソースを管理するには[ワークスペース API](https://langbot.app/docs/ja/plugin/dev/apis/workspace.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)でバインドしてから、添付のインポートやツール実行を行います。

---

# LLM リクエスト設定

Source: https://langbot.app/docs/ja/plugin/dev/apis/llm-requests

プラグインと Runner のリトライ、タイムアウト、思考予算、キャッシュ、ストリーム終了

本ページの設定には [Core #2661](https://github.com/langbot-app/LangBot/pull/2661) を含む Core が必要です。マージとリリースは別です。既存の `extra_args` で指定し、プラグインと Runner のシグネチャ、メッセージ型、権限確認は変わりません。[LangBot API](https://langbot.app/docs/ja/plugin/dev/apis/common.md) と[コンテキスト API](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md)も参照してください。

## リトライとタイムアウト

非ストリーミング呼び出しでリクエスト設定と完全な使用量を扱う例です：

```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!")],
    timeout=110,
    extra_args={
        "request_policy": {
            "retries": 1,
            "total_timeout": 90,
            "first_event_timeout": 30,
            "stream_idle_timeout": 30,
            "connect_timeout": 10,
            "read_timeout": 60,
        },
    },
)
print(result.message.content)
if result.usage is not None:
    print(result.usage.model_dump())
```

Runner の `ctx.api.invoke_llm*` でも同じ `extra_args` を使えますが、実行の権限と残り時間に制限されます。実行コンテキスト内の `self.plugin` 呼び出しにも同じ制限が適用されます。

`timeout=` は SDK/RPC の待機期限（非ストリーミングでは既定 120 秒）です。`request_policy` は Core 内部のリクエストを制御します。総予算は外側の RPC/Runner の期限内に収めてください。Core の予算を増やしても外側の期限は延長されません。ストリーミングメソッドには `timeout=` 引数がなく、SDK/Runner の待機期限が適用されます。

| `request_policy` フィールド         | 既定値         | 意味                           |
| ------------------------------ | ----------- | ---------------------------- |
| `retries`                      | `0`         | 初回以外の追加試行数、整数 0–5            |
| `total_timeout`                | `300`       | リトライ待機を含む呼び出し全体の予算           |
| `first_event_timeout`          | `120`       | 最初の表示文字ではなく、最初の上流イベントを待つ期限   |
| `stream_idle_timeout`          | `120`       | ストリームイベント間の待機期限              |
| `connect_timeout`              | `10`        | 接続タイムアウト                     |
| `read_timeout`                 | `120`       | 読み取りタイムアウト                   |
| `write_timeout`                | `30`        | 書き込みタイムアウト                   |
| `pool_timeout`                 | `10`        | 接続プールの待機期限                   |
| `backoff_base` / `backoff_max` | `0.5` / `8` | full jitter を使う指数バックオフの基数と上限 |
| `attribution`                  | `True`      | アプリ識別ヘッダーの自動付与               |
| `conversation_header`          | `None`      | 生成するセッションヘッダー名（後述）           |

時間は秒単位で、タイムアウトは有限の正数です。未知のフィールドは拒否されます。優先順位はインスタンスの `llm_request_policy`、モデルの `extra_args`、呼び出しの `extra_args` の順です。同じ階層では `request_policy.retries` が旧 `num_retries` / `max_retries` より優先されます。呼び出し側の旧パラメーターでもモデル設定を上書きでき、`0` でリトライを無効化できます。旧数値 `extra_args["timeout"]` は読み取り、最初のイベント、ストリーム待機を設定し、総予算は延長しません。

認証失敗、不正なリクエスト、クォータ不足はリトライしません。思考や usage を含む上流イベントを受信した後も再試行しません。`Retry-After` は残りの総予算内に制限されます。Core は管理対象の LiteLLM/プロバイダー SDK 内蔵リトライを無効化しますが、中継サービスは独自に再試行する場合があります。ツール再実行、モデル切り替え、embedding/rerank のリトライは追加しません。旧サードパーティ requester の内部通信設定はその実装が管理します。

## 思考予算

既存の `reasoning_level` は変わりません。数値予算は以下を `extra_args` またはモデルの詳細パラメーターに指定します。`level` を省略すると `enabled` です：

```json
{
  "reasoning_config": {"budget_tokens": 2048},
  "max_tokens": 4096
}
```

予算と effort レベル（例：`medium`）、`disabled`、プロバイダー独自の思考パラメーターを併用しないでください。Anthropic 直結では予算より大きい `max_tokens` を明示する必要があり、Core は出力上限を自動で増やしません。

優先順位は保存済みモデル `reasoning_config`、モデル `extra_args.reasoning_config`、呼び出し `extra_args.reasoning_config`、明示的な Runner レベル指定です。各オブジェクトが前の設定を全置換し、effort 指定は低優先度の数値予算を削除します。

数値予算はネイティブ Anthropic、Gemini 2.5、対応 Qwen、OpenRouter 経由に変換されます。OpenAI/Codex 直結と adaptive のみの Claude は effort を使います。モデルの `reasoning_capabilities.budget_tokens` で対応と範囲を確認してください。未対応なら HTTP 送信前にエラーになります。上流の制限がより厳しい場合や、OpenRouter が予算を effort に変換する場合もあります。

## Prompt caching

`extra_args.prompt_caching` は Core 専用で、そのまま上流には送信されません。呼び出し設定がモデル設定を全置換します。既定の `{"mode": "provider_default"}` はフィールドを追加しません。ローカルの回答キャッシュではありません。

| 設定                                             | 動作                                                                                 |
| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
| `{"mode": "openai", "retention": "in_memory"}` | 会話コンテキストがあるとモデルと会話別の `prompt_cache_key` を生成。`retention` は省略可能で、対応モデルでは `24h` も指定可能 |
| `{"mode": "anthropic", "ttl": "5m"}`           | 先頭の system/developer 接頭辞の最後のテキストブロックに一時キャッシュマーカーを追加。`ttl` は `5m` または `1h`          |

OpenAI モードは対応する互換ルートおよび OpenRouter の OpenAI モデル向けです。明示したネイティブ `prompt_cache_key`、`prompt_cache_retention`、`prompt_cache_options` が優先されます。Anthropic モードはネイティブ Claude と OpenRouter Claude に対応します。既存マーカーがあれば追加せず、ツール/履歴の並べ替えやユーザーメッセージへの追加もしません。適切な接頭辞がなければ何も追加しません。

キャッシュヒントはヒットを保証しません。`usage.model_dump()` の `prompt_tokens_details.cached_tokens`、`cache_read_input_tokens` などで確認します。未提供はゼロではありません。最小接頭辞長、保持期間の対応、料金はプロバイダー次第です。Codex の制限付き Responses ボディはこの設定を受け付けず、既存のサーバー側キャッシュを維持します。汎用 Responses 移行と Gemini 明示的キャッシュリソース管理は今回の対象外です。

## アプリとセッションのヘッダー

OpenRouter 直結では `HTTP-Referer: https://langbot.app`、`X-OpenRouter-Title: LangBot`、会話コンテキストがあれば `x-session-id: lb-<opaque scoped hash>` を自動付与します。独自の中継 URL には自動付与しません。`request_policy.attribution=False` は自動アプリ識別のみを無効化します。明示した `extra_headers` は保持され、大文字小文字を区別せず優先されます。

中継サービスに合わせてセッションヘッダーを指定できます：

```json
{
  "request_policy": {"conversation_header": "x-litellm-session-id"},
  "extra_headers": {
    "HTTP-Referer": "https://langbot.app",
    "X-OpenRouter-Title": "LangBot"
  }
}
```

対応名は `x-session-id`、`x-litellm-session-id`、`x-langbot-conversation-id` です。最後は独自規約であり共通標準ではなく、自動的なルーティングやキャッシュ効果はありません。生成値は workspace/bot/pipeline/session ごとに分離され、生の ID やプロンプトを含みませんが、仮名化であり匿名化保証ではありません。コンテキストがなければ生成しません。New API などはヘッダーを削除・上書きする可能性があるため、転送設定と実際の出力を確認してください。

## ストリーム終了と互換性

途中でループを抜けるときは `aclosing` で生成器を確実に閉じ、タスクのキャンセル例外は伝播させてください：

```python
from contextlib import aclosing
from langbot_plugin.api.entities.builtin.provider.message import Message

async with aclosing(self.plugin.invoke_llm_stream_events(
    llm_model_uuid=model_uuid,
    messages=[Message(role="user", content="Hello!")],
    extra_args={"request_policy": {"retries": 0, "total_timeout": 90}},
)) as events:
    async for event in events:
        if event.usage is not None:
            print(event.usage.model_dump())
        if event.chunk is not None and event.chunk.content:
            print(event.chunk.content)
            break
```

この例は最初の空でない内容で停止するため、最後の usage を受け取れない場合があります。全文取得では `break` を除きます。最後のイベントが chunk なしの usage のみの場合もあります。`invoke_llm` は引き続き `Message`、`invoke_llm_stream` は `MessageChunk` を返します。使用量には `invoke_llm_with_usage` または `invoke_llm_stream_events` を使います。usage は `None` の場合があり、ネストしたキャッシュ/思考使用量や上流独自フィールドは保持されます。

SDK ≤0.7.11 には、プロキシの早期終了が上流へ即時伝播しない問題があります。確実な終了には **langbot-plugin ≥0.7.12** が必要です。この公開版は [SDK #177](https://github.com/langbot-app/langbot-plugin-sdk/pull/177) の修正を含みます。Core の依存固定だけでは別配置の Runtime やプラグイン開発環境は更新されないため、実行する各環境も更新してください。通常のシグネチャ、ペイロード、戻り値は互換です。総期限は消費時間も含みますが、生成器が `yield` で停止中に消費側を中断せず、次の読み取りで期限切れを確認します。

## 診断

Core の監視レコード `details` に `timing`、完全な `usage`、構造化 `error` を記録します。旧 SDK の例外伝送形式は変更しません。構造化エラーは `code`、`status_code`、`retryable`、`retry_after`、`request_id`、`phase` を含みますが、プラグインが受け取る旧例外にこれらがあるとは限りません。

時間はミリ秒で、`preparation_ms`、`transport_setup_ms`、`first_event_ms`、`first_reasoning_ms`、`first_content_ms`、`first_visible_chunk_ms`、`total_ms`、`retry_wait_ms`、および試行数 `attempts` を記録します。最初のイベントは思考や制御の場合があり、最初の表示チャンクも思考を含む場合があります。`request_started_ms` は SDK 呼び出し時刻で、パケット送信時刻ではありません。欠落は未観測でありゼロではありません。キャンセル前の部分 usage は監視に保持されますが、未提供の使用量は復元できません。

---

# メッセージプラットフォームエンティティ

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()` を呼び出すと、後続プラグインによる現在のイベント処理を停止できます。

#### モニタリングでの表示

プラグインがメッセージ系イベントで `prevent_default()` を呼び出してメッセージを引き受けると、LangBot のモニタリングではそのメッセージが「プラグインが処理 · 作者/プラグイン名」と表示され、パイプラインに設定された Runner は処理者として表示されなくなります。イベント処理中にプラグインが送った内容も記録されます。

- `event_context.reply()` で送った返信は、そのメッセージへの返信として記録されます。送信に失敗すると `PluginReplyError` エラーが記録されます。
- `self.plugin.send_message()` で送ったメッセージは、プラグインが送信したメッセージとして記録されます。送信に失敗すると `PluginSendError` エラーが記録されます。
- `self.plugin.invoke_llm()` / `invoke_llm_stream()` の呼び出しは LLM 呼び出しとして記録されます。

プラグインのメッセージや LLM 呼び出しをきっかけのメッセージに関連付けるには、イベント起点の関連付けに対応した Plugin Runtime（`langbot-plugin`）が必要です。古い Runtime でも記録はされますが、関連付けはされません。ハンドラーが戻った後に動くバックグラウンド処理は、元のメッセージに関連付けられません。

---

# プラットフォーム API

Source: https://langbot.app/docs/ja/plugin/dev/apis/platform

ボット UUID を指定してプラットフォームアダプターの API を呼び出します。メッセージチェーンの送信は `self.plugin.send_message()`、グループやユーザーの取得などは以下を使用します。

## メッセージ送信、返信、スレッド

標準の `send_message` API は `MessageResult` を返します。プラットフォームがメッセージ ID を提供する場合、`message_id` は送信したメッセージを識別します。`self.plugin.send_message()` はシリアライズされた辞書を返すため、オブジェクト属性ではなく `result["message_id"]` を参照します。プラットフォームが ID を返さない場合、この値は `None` または空文字列になります。

メッセージチェーン内の返信やスレッド参照には、標準の `Quote` コンポーネントを使います。`Quote.id` は参照先メッセージまたはスレッドのルートメッセージの ID、`origin` は引用元のメッセージチェーンで、空でも構いません。対応状況と返信／スレッドの動作はアダプターによって異なります。たとえば Slack はメッセージの `ts` を `message_id` として返し、`Quote(id=ts)` を含むチェーンをそのスレッドに送信します。受信したチャンネルのスレッド返信には、末尾に `Quote(id=thread_ts)` が追加されます。これは Slack 固有のアクションではなく、標準メッセージ API を使います。

```python
from langbot_plugin.api.entities.builtin.platform.message import MessageChain, Plain, Quote

result = await self.plugin.send_message(
    bot_uuid=bot_uuid,
    target_type="group",
    target_id=group_id,
    message_chain=MessageChain([Plain(text="Support request")]),
)
message_id = result.get("message_id") if result else None
if message_id is not None and message_id != "":
    await self.plugin.send_message(
        bot_uuid=bot_uuid,
        target_type="group",
        target_id=group_id,
        message_chain=MessageChain([
            Plain(text="Follow-up"),
            Quote(id=message_id, origin=MessageChain([])),
        ]),
    )
```

同じボット、同じ会話のメッセージ ID を使ってください。`Quote` はシリアライズ時に参照メタデータを保持しますが、`str(message_chain)` にはテキストを追加しないため、コマンドやキーワードの照合に影響しません。

## プラットフォーム 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に接続してデバッグできます。

---

# ワークスペース API

Source: https://langbot.app/docs/ja/plugin/dev/apis/workspace

プラグインから Agent、パイプライン、ボット、モデル、ナレッジベースなどのワークスペースリソースを参照・管理します。

ワークスペース API を使うと、プラグインは自分がインストールされているワークスペースを操作できます。Agent やパイプラインの一覧取得と編集、ボットの参照、モデルやナレッジベースの管理、モニタリングデータの読み取りなどです。公開されている操作は LangBot の HTTP API、MCP サーバー、ワークスペースアシスタントとまったく同じなので、メンバーがそれらで行えることは、メンバーが許可した範囲内でプラグインからも自動化できます。

各操作には `pipeline.list` や `knowledge.base.retrieve` のような固定の ID があります。プラグインが呼び出せるのは、[マニフェストで宣言](https://langbot.app/docs/ja/plugin/dev/permissions.md#権限を宣言する)し、かつメンバーがそのインストールに許可した操作だけです。

## 操作を呼び出す

どのコンポーネントからも `self.plugin.workspace` を使います。各操作には ID に対応した型付きメソッドがあります。

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


class WorkspaceSummary(Tool):
    async def call(self, params, session, query_id):
        result = await self.plugin.workspace.pipeline.list()
        if not result["ok"]:
            return f"パイプラインを取得できませんでした: {result['error']['message']}"

        names = [pipeline["name"] for pipeline in result["result"]]
        return "パイプライン: " + "、".join(names)
```

メソッドは操作の入力スキーマに対応するキーワード引数を受け取り、エディターでは型と説明が表示されます。一部の名前は Python として有効になるよう調整されます。Python のキーワードと重なる部分には末尾にアンダースコアが付き（例：`import_`）、その他の無効な文字はアンダースコアに置き換えられます。送信時には元の引数名が使われます。

呼び出す操作を実行時に決めたい場合は、ID を指定して呼び出せます。型付きメソッドとまったく同じように動作します。

```python
result = await self.plugin.workspace.call("knowledge.base.retrieve", kb_uuid=kb_uuid, query="返金ポリシー")
```

`await self.plugin.workspace.list()` は、インストールに許可された操作とその入力スキーマを `domains` ごとにまとめて返します。ツール一覧を動的に組み立てたり、機能を提供する前に許可の有無を確かめたりするのに便利です。

### Runner の中で使う

Runner では、実行に紐づいたプロキシを `ctx.api.workspace` として受け取ります。メソッドも、認可に使われるインストールの許可も同じです。違いは、LangBot が各呼び出しを現在の実行に記録する点です。

実行を開始した Agent やパイプラインが、モデルに見せるワークスペース操作を絞り込んでいる場合があります。その選択は `ctx.resources.workspace_operations` で渡されます。ワークスペース操作をツールとしてモデルに提供する Runner は、この中の操作だけを提供し、リストが空なら何も提供しないでください。LangBot 組み込みの LocalAgent もそのように動作します。

## 戻り値とエラー

ワークスペースの呼び出しは、業務上のエラーで例外を送出しません。常に辞書を返します。

```python
# 成功
{"ok": True, "result": ..., "operation": {"id": "pipeline.list", ...}}

# 失敗
{"ok": False, "error": {"code": "permission_denied", "message": "...", "details": {...}}}
```

`result` を読む前に `ok` を確認してください。主なエラーコード：

| コード                 | 意味                                                                              |
| ------------------- | ------------------------------------------------------------------------------- |
| `permission_denied` | この操作がインストールに許可されていないか、インストールが無効です。`details.denied_operations` に不足している ID が入ります。 |
| `invalid_input`     | 引数が操作の入力スキーマに合っていません。                                                           |
| `not_found`         | 参照したリソースが現在のワークスペースに存在しません。                                                     |
| `application_error` | 操作は実行されましたが失敗しました。理由は `message` にあります。                                          |

メンバーは宣言された権限の一部だけを許可することもあるため、権限不足は想定内の結果です。コマンドや実行全体を失敗させるのではなく、何が足りないかを説明してください。

## 宣言する操作の選び方

各操作にはリスクレベルがあり、メンバーは確認時にそれを目にします。

- **読み取り**：データを返すだけの操作。例：`pipeline.list`、`stats.basic`。
- **書き込み**：ワークスペースの設定を変更する操作。例：`pipeline.update`、`knowledge.file.store`。
- **高リスク**：リソースの削除、LangBot 外部への影響、大量のリソース消費を伴う操作。例：`bot.delete`、`pipeline.chat.broadcast`。確認ダイアログで強調表示されます。

操作を許可するメンバーは、その操作が要求する権限（下の表の最後の列）を自分で持っている必要があります。必要な操作だけを申請してください。高リスクの操作を多数申請すると、拒否されたり削られたりする可能性が高くなります。

`knowledge.*` のようなワイルドカードで、あるプレフィックス配下の操作をまとめて申請できますが、すべてのプレフィックスで使えるわけではありません。[ワイルドカード](https://langbot.app/docs/ja/plugin/dev/permissions.md#ワイルドカード)を参照してください。

## 操作一覧

現在の LangBot でプラグインが申請できるすべての操作を、ドメインごとに示します。メソッドは `workspace.…` と表記しています。コンポーネントでは `self.plugin.workspace`、Runner では `ctx.api.workspace` です。SDK の型付きメソッドはこのカタログから生成されているため、表のすべての操作がメソッドとして利用できます。

### Adapter (`adapter`)

| 操作                                                                    | ID とメソッド                                  | リスク  | 付与するメンバーに必要な権限  |
| --------------------------------------------------------------------- | ----------------------------------------- | ---- | --------------- |
| Get Adapter Get configuration schema and requirements for an adapter. | `adapter.get` `workspace.adapter.get()`   | 読み取り | `resource.view` |
| List Adapters List available chat platform adapters in the workspace. | `adapter.list` `workspace.adapter.list()` | 読み取り | `resource.view` |

### Agent (`agent`)

| 操作                                                                         | ID とメソッド                                            | リスク  | 付与するメンバーに必要な権限    |
| -------------------------------------------------------------------------- | --------------------------------------------------- | ---- | ----------------- |
| Create Agent Create a new autonomous AI agent in the workspace.            | `agent.create` `workspace.agent.create()`           | 書き込み | `resource.manage` |
| Debug Agent Execute a test turn on an agent for debugging purposes.        | `agent.debug` `workspace.agent.debug()`             | 書き込み | `runtime.operate` |
| Delete Agent Delete an autonomous AI agent from the workspace.             | `agent.delete` `workspace.agent.delete()`           | 高リスク | `resource.manage` |
| Get Agent Get full configuration and parameters for an AI agent.           | `agent.get` `workspace.agent.get()`                 | 読み取り | `resource.view`   |
| List Agents List all autonomous AI agents configured in the workspace.     | `agent.list` `workspace.agent.list()`               | 読み取り | `resource.view`   |
| Agent Metadata Get supported agent capabilities, model types, and schemas. | `agent.metadata` `workspace.agent.metadata()`       | 読み取り | `resource.view`   |
| Get Run Events Fetch step-by-step trace events for an agent execution run. | `agent.runs.events` `workspace.agent.runs.events()` | 読み取り | `resource.view`   |
| List Agent Runs List historical execution runs for an agent or processor.  | `agent.runs.list` `workspace.agent.runs.list()`     | 読み取り | `resource.view`   |
| Update Agent Update configuration, model, or prompts of an agent.          | `agent.update` `workspace.agent.update()`           | 書き込み | `resource.manage` |

### Bot (`bot`)

| 操作                                                                             | ID とメソッド                                                          | リスク  | 付与するメンバーに必要な権限    |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ---- | ----------------- |
| List Bot Admins List platform users configured as administrators for a bot.    | `bot.admins.list` `workspace.bot.admins.list()`                   | 読み取り | `resource.view`   |
| Create Bot Create a new chat bot connected to an IM adapter.                   | `bot.create` `workspace.bot.create()`                             | 書き込み | `resource.manage` |
| Delete Bot Delete a chat bot and remove its adapter connection.                | `bot.delete` `workspace.bot.delete()`                             | 高リスク | `resource.manage` |
| Get Bot Get detailed configuration and status for a specific bot.              | `bot.get` `workspace.bot.get()`                                   | 読み取り | `resource.view`   |
| Apply Group Filter Apply group filtering rules to enable or disable pipelines. | `bot.group_filter.apply` `workspace.bot.group_filter.apply()`     | 書き込み | `resource.manage` |
| Preview Group Filter Preview chat group filtering rules for a bot.             | `bot.group_filter.preview` `workspace.bot.group_filter.preview()` | 読み取り | `resource.manage` |
| List Bots List all configured chat bots in the workspace.                      | `bot.list` `workspace.bot.list()`                                 | 読み取り | `resource.view`   |
| Bot Logs Fetch runtime connection logs and events for a bot.                   | `bot.logs` `workspace.bot.logs()`                                 | 読み取り | `resource.view`   |
| Send Bot Message Send an outbound message to a chat user or group via a bot.   | `bot.message.send` `workspace.bot.message.send()`                 | 高リスク | `runtime.operate` |
| Test Bot Message Test bot messaging capability by sending a test message.      | `bot.message.test` `workspace.bot.message.test()`                 | 書き込み | `resource.manage` |
| Preview Routes Preview message routing decisions for a simulated event.        | `bot.routes.preview` `workspace.bot.routes.preview()`             | 読み取り | `resource.manage` |
| Routing Status Get active message routing bindings and rules for a bot.        | `bot.routes.status` `workspace.bot.routes.status()`               | 読み取り | `resource.view`   |
| Bot Runtime Status Inspect live connection state and health of a bot.          | `bot.runtime.get` `workspace.bot.runtime.get()`                   | 読み取り | `resource.view`   |
| Update Bot Update settings or pipeline bindings for an existing bot.           | `bot.update` `workspace.bot.update()`                             | 書き込み | `resource.manage` |

### Extension (`extension`)

| 操作                                                                                | ID とメソッド                                      | リスク  | 付与するメンバーに必要な権限  |
| --------------------------------------------------------------------------------- | --------------------------------------------- | ---- | --------------- |
| List All Extensions List all available plugins, MCP servers, and skills combined. | `extension.list` `workspace.extension.list()` | 読み取り | `resource.view` |

### Knowledge Base (`knowledge`)

| 操作                                                                                      | ID とメソッド                                                                            | リスク  | 付与するメンバーに必要な権限    |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---- | ----------------- |
| Create Knowledge Base Create a new knowledge base with storage and vector engine.       | `knowledge.base.create` `workspace.knowledge.base.create()`                         | 書き込み | `resource.manage` |
| Delete Knowledge Base Permanently delete a knowledge base and indexed documents.        | `knowledge.base.delete` `workspace.knowledge.base.delete()`                         | 高リスク | `resource.manage` |
| Get Knowledge Base Get configuration and indexing status of a knowledge base.           | `knowledge.base.get` `workspace.knowledge.base.get()`                               | 読み取り | `resource.view`   |
| List Knowledge Bases List all knowledge bases configured in the workspace.              | `knowledge.base.list` `workspace.knowledge.base.list()`                             | 読み取り | `resource.view`   |
| Retrieve Knowledge Chunks Search and retrieve relevant text chunks from knowledge base. | `knowledge.base.retrieve` `workspace.knowledge.base.retrieve()`                     | 読み取り | `resource.view`   |
| Update Knowledge Base Update configuration or description of a knowledge base.          | `knowledge.base.update` `workspace.knowledge.base.update()`                         | 書き込み | `resource.manage` |
| Engine Creation Schema Get configuration schema required to create an engine.           | `knowledge.engine.creation_schema` `workspace.knowledge.engine.creation_schema()`   | 読み取り | `resource.view`   |
| List Knowledge Engines List available storage and vector retrieval engine types.        | `knowledge.engine.list` `workspace.knowledge.engine.list()`                         | 読み取り | `resource.view`   |
| Engine Retrieval Schema Get parameter schema for retrieving from an engine.             | `knowledge.engine.retrieval_schema` `workspace.knowledge.engine.retrieval_schema()` | 読み取り | `resource.view`   |
| Delete Knowledge File Delete an indexed document from a knowledge base.                 | `knowledge.file.delete` `workspace.knowledge.file.delete()`                         | 高リスク | `resource.manage` |
| List Knowledge Files List all documents indexed within a knowledge base.                | `knowledge.file.list` `workspace.knowledge.file.list()`                             | 読み取り | `resource.view`   |
| Store Knowledge File Index and store a document into a knowledge base.                  | `knowledge.file.store` `workspace.knowledge.file.store()`                           | 書き込み | `resource.manage` |
| List Document Parsers List supported document parser formats and capabilities.          | `knowledge.parser.list` `workspace.knowledge.parser.list()`                         | 読み取り | `resource.view`   |

### MCP (`mcp`)

| 操作                                                                                      | ID とメソッド                                                      | リスク  | 付与するメンバーに必要な権限    |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---- | ----------------- |
| List MCP Resources List all resources exposed by connected MCP servers.                 | `mcp.resource.list` `workspace.mcp.resource.list()`           | 読み取り | `resource.view`   |
| Read MCP Resource Read contents of a specific resource from an MCP server.              | `mcp.resource.read` `workspace.mcp.resource.read()`           | 読み取り | `resource.view`   |
| List MCP Resource Templates List parameterized resource URI templates from MCP servers. | `mcp.resource.templates` `workspace.mcp.resource.templates()` | 読み取り | `resource.view`   |
| Delete MCP Server Disconnect and delete an MCP server from the workspace.               | `mcp.server.delete` `workspace.mcp.server.delete()`           | 高リスク | `resource.manage` |
| Get MCP Server Get configuration and parameters of a specific MCP server.               | `mcp.server.get` `workspace.mcp.server.get()`                 | 読み取り | `resource.view`   |
| List MCP Servers List configured Model Context Protocol (MCP) servers.                  | `mcp.server.list` `workspace.mcp.server.list()`               | 読み取り | `resource.view`   |
| MCP Server Logs Retrieve communication and error logs for an MCP server.                | `mcp.server.logs` `workspace.mcp.server.logs()`               | 読み取り | `audit.view`      |
| MCP Server Runtime Inspect live health and session state of an MCP server.              | `mcp.server.runtime` `workspace.mcp.server.runtime()`         | 読み取り | `resource.view`   |
| Test MCP Server Connection Test connectivity and ping an MCP server configuration.      | `mcp.server.test` `workspace.mcp.server.test()`               | 書き込み | `resource.manage` |

### Model (`model`)

| 操作                                                                                      | ID とメソッド                                                                          | リスク  | 付与するメンバーに必要な権限           |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---- | ------------------------ |
| Create Embedding Model Configure and add a new embedding model to the workspace.        | `model.embedding.create` `workspace.model.embedding.create()`                     | 書き込み | `provider_secret.manage` |
| Delete Embedding Model Delete an embedding model configuration from the workspace.      | `model.embedding.delete` `workspace.model.embedding.delete()`                     | 高リスク | `resource.manage`        |
| Get Embedding Model Get configuration and parameters of an embedding model.             | `model.embedding.get` `workspace.model.embedding.get()`                           | 読み取り | `resource.view`          |
| List Embedding Models List all text embedding models configured in the workspace.       | `model.embedding.list` `workspace.model.embedding.list()`                         | 読み取り | `resource.view`          |
| List Embeddings by Provider List embedding models configured under a specific provider. | `model.embedding.list_by_provider` `workspace.model.embedding.list_by_provider()` | 読み取り | `resource.view`          |
| Test Embedding Model Test vector generation and connectivity for embedding model.       | `model.embedding.test` `workspace.model.embedding.test()`                         | 書き込み | `provider_secret.manage` |
| Update Embedding Model Update configuration and parameters of an embedding model.       | `model.embedding.update` `workspace.model.embedding.update()`                     | 書き込み | `provider_secret.manage` |
| Create LLM Model Configure and add a new LLM model to the workspace.                    | `model.llm.create` `workspace.model.llm.create()`                                 | 書き込み | `provider_secret.manage` |
| Get Default LLM Model Get workspace default large language model configuration.         | `model.llm.default.get` `workspace.model.llm.default.get()`                       | 読み取り | `resource.manage`        |
| Delete LLM Model Delete an LLM model configuration from the workspace.                  | `model.llm.delete` `workspace.model.llm.delete()`                                 | 高リスク | `resource.manage`        |
| Get LLM Model Get configuration and parameters of a specific LLM model.                 | `model.llm.get` `workspace.model.llm.get()`                                       | 読み取り | `resource.view`          |
| List LLM Models List all configured large language models in the workspace.             | `model.llm.list` `workspace.model.llm.list()`                                     | 読み取り | `resource.view`          |
| List LLMs by Provider List LLM models configured under a specific model provider.       | `model.llm.list_by_provider` `workspace.model.llm.list_by_provider()`             | 読み取り | `resource.view`          |
| Get Starred LLM Model Get the starred favorite LLM model of the workspace.              | `model.llm.starred.get` `workspace.model.llm.starred.get()`                       | 読み取り | `resource.view`          |
| Set Starred LLM Model Designate a specific LLM model as the starred favorite.           | `model.llm.starred.set` `workspace.model.llm.starred.set()`                       | 書き込み | `provider_secret.manage` |
| Test LLM Model Test connectivity and response generation for an LLM model.              | `model.llm.test` `workspace.model.llm.test()`                                     | 書き込み | `provider_secret.manage` |
| Update LLM Model Update configuration and parameters of an LLM model.                   | `model.llm.update` `workspace.model.llm.update()`                                 | 書き込み | `provider_secret.manage` |
| Create Rerank Model Configure and add a new rerank model to the workspace.              | `model.rerank.create` `workspace.model.rerank.create()`                           | 書き込み | `provider_secret.manage` |
| Delete Rerank Model Delete a rerank model configuration from the workspace.             | `model.rerank.delete` `workspace.model.rerank.delete()`                           | 高リスク | `resource.manage`        |
| Get Rerank Model Get configuration and parameters of a rerank model.                    | `model.rerank.get` `workspace.model.rerank.get()`                                 | 読み取り | `resource.view`          |
| List Rerank Models List all document reranking models in the workspace.                 | `model.rerank.list` `workspace.model.rerank.list()`                               | 読み取り | `resource.view`          |
| List Reranks by Provider List rerank models configured under a specific provider.       | `model.rerank.list_by_provider` `workspace.model.rerank.list_by_provider()`       | 読み取り | `resource.view`          |
| Test Rerank Model Test connectivity and scoring capability of a rerank model.           | `model.rerank.test` `workspace.model.rerank.test()`                               | 書き込み | `provider_secret.manage` |
| Update Rerank Model Update configuration and parameters of a rerank model.              | `model.rerank.update` `workspace.model.rerank.update()`                           | 書き込み | `provider_secret.manage` |

### Monitoring (`monitoring`)

| 操作                                                                                        | ID とメソッド                                                                | リスク  | 付与するメンバーに必要な権限    |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ---- | ----------------- |
| Embedding Call Metrics Query embedding generation metrics and latency statistics.         | `monitoring.embedding_calls` `workspace.monitoring.embedding_calls()`   | 読み取り | `resource.view`   |
| Error Logs Query runtime errors and failures across bots and pipelines.                   | `monitoring.errors` `workspace.monitoring.errors()`                     | 読み取り | `resource.view`   |
| Execution Details Get detailed traces and step execution events for a specific execution. | `monitoring.execution.detail` `workspace.monitoring.execution.detail()` | 読み取り | `resource.view`   |
| List Executions Query execution history records across bots, pipelines, and agents.       | `monitoring.executions` `workspace.monitoring.executions()`             | 読み取り | `resource.view`   |
| List User Feedback List user ratings and feedback records on bot responses.               | `monitoring.feedback.list` `workspace.monitoring.feedback.list()`       | 読み取り | `resource.view`   |
| Feedback Statistics Get aggregated positive and negative user feedback metrics.           | `monitoring.feedback.stats` `workspace.monitoring.feedback.stats()`     | 読み取り | `resource.view`   |
| In-Flight Executions Inspect currently active in-flight requests and pipeline runs.       | `monitoring.inflight` `workspace.monitoring.inflight()`                 | 読み取り | `resource.view`   |
| LLM Call Metrics Query model invocation counts, latencies, and token stats.               | `monitoring.llm_calls` `workspace.monitoring.llm_calls()`               | 読み取り | `resource.view`   |
| Message Details Retrieve full metadata and trace details for a single message.            | `monitoring.message.detail` `workspace.monitoring.message.detail()`     | 読み取り | `resource.view`   |
| Query Messages Query processed chat messages across bot sessions.                         | `monitoring.messages` `workspace.monitoring.messages()`                 | 読み取り | `resource.view`   |
| Monitoring Overview Get aggregated monitoring overview statistics for bots and pipelines. | `monitoring.overview` `workspace.monitoring.overview()`                 | 読み取り | `resource.view`   |
| Session Analysis Analyze session metrics, duration, and token usage for a session.        | `monitoring.session.analysis` `workspace.monitoring.session.analysis()` | 読み取り | `resource.view`   |
| Reset Session Reset a chat session and clear its context window.                          | `monitoring.session.reset` `workspace.monitoring.session.reset()`       | 高リスク | `resource.manage` |
| List Sessions List active and historical chat sessions across bots.                       | `monitoring.sessions` `workspace.monitoring.sessions()`                 | 読み取り | `resource.view`   |
| Token Usage Statistics Query token consumption metrics aggregated by time buckets.        | `monitoring.tokens` `workspace.monitoring.tokens()`                     | 読み取り | `resource.view`   |
| Tool Call Metrics Query tool invocation history and execution performance.                | `monitoring.tool_calls` `workspace.monitoring.tool_calls()`             | 読み取り | `resource.view`   |

### Pipeline (`pipeline`)

| 操作                                                                                     | ID とメソッド                                                              | リスク  | 付与するメンバーに必要な権限    |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---- | ----------------- |
| Broadcast Chat Message Broadcast a message to all active pipeline chat clients.        | `pipeline.chat.broadcast` `workspace.pipeline.chat.broadcast()`       | 高リスク | `runtime.operate` |
| Pipeline Connections Inspect live websocket connection status for pipeline chat.       | `pipeline.chat.connections` `workspace.pipeline.chat.connections()`   | 読み取り | `runtime.operate` |
| Pipeline Chat History Retrieve debug chat message history for a pipeline session.      | `pipeline.chat.history` `workspace.pipeline.chat.history()`           | 読み取り | `runtime.operate` |
| Reset Chat Session Clear memory and chat history for a pipeline debug session.         | `pipeline.chat.reset` `workspace.pipeline.chat.reset()`               | 高リスク | `runtime.operate` |
| Copy Pipeline Duplicate an existing pipeline to create a new copy.                     | `pipeline.copy` `workspace.pipeline.copy()`                           | 書き込み | `resource.manage` |
| Create Pipeline Create a new processing pipeline in the workspace.                     | `pipeline.create` `workspace.pipeline.create()`                       | 書き込み | `resource.manage` |
| Pipeline Defaults Get template defaults and initial values for new pipelines.          | `pipeline.defaults` `workspace.pipeline.defaults()`                   | 読み取り | `resource.view`   |
| Delete Pipeline Permanently delete a pipeline from the workspace.                      | `pipeline.delete` `workspace.pipeline.delete()`                       | 高リスク | `resource.manage` |
| Get Pipeline Extensions Get bound plugins, MCP servers, and tools for a pipeline.      | `pipeline.extensions.get` `workspace.pipeline.extensions.get()`       | 読み取り | `resource.view`   |
| Update Pipeline Extensions Update bound plugins, MCP servers, and tools on a pipeline. | `pipeline.extensions.update` `workspace.pipeline.extensions.update()` | 書き込み | `resource.manage` |
| Get Pipeline Get complete definition and node graph of a pipeline.                     | `pipeline.get` `workspace.pipeline.get()`                             | 読み取り | `resource.view`   |
| List Pipelines List all message processing pipelines in the workspace.                 | `pipeline.list` `workspace.pipeline.list()`                           | 読み取り | `resource.view`   |
| Pipeline Metadata Get available component types and node specifications.               | `pipeline.metadata` `workspace.pipeline.metadata()`                   | 読み取り | `resource.view`   |
| Run Pipeline Execute a pipeline run with custom input data.                            | `pipeline.run` `workspace.pipeline.run()`                             | 書き込み | `runtime.operate` |
| Update Pipeline Update topology, nodes, or settings of a pipeline.                     | `pipeline.update` `workspace.pipeline.update()`                       | 書き込み | `resource.manage` |

### Plugin (`plugin`)

| 操作                                                                                        | ID とメソッド                                                              | リスク  | 付与するメンバーに必要な権限    |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---- | ----------------- |
| Get Plugin Config Get configured parameters and settings for a plugin.                    | `plugin.config.get` `workspace.plugin.config.get()`                   | 読み取り | `resource.view`   |
| Plugin Debug Info Inspect internal plugin runtime process state and memory.               | `plugin.debug_info` `workspace.plugin.debug_info()`                   | 読み取り | `resource.manage` |
| Get Plugin Get detailed metadata and manifest for an installed plugin.                    | `plugin.get` `workspace.plugin.get()`                                 | 読み取り | `resource.view`   |
| Plugin GitHub Assets List downloadable asset files for a GitHub release.                  | `plugin.github.assets` `workspace.plugin.github.assets()`             | 読み取り | `resource.view`   |
| Plugin GitHub Releases List releases of a plugin repository hosted on GitHub.             | `plugin.github.releases` `workspace.plugin.github.releases()`         | 読み取り | `resource.view`   |
| Install Plugin from Marketplace Install a certified plugin from the official marketplace. | `plugin.install.marketplace` `workspace.plugin.install.marketplace()` | 高リスク | `resource.manage` |
| List Plugins List all installed plugins and their running status.                         | `plugin.list` `workspace.plugin.list()`                               | 読み取り | `resource.view`   |
| Plugin Logs Fetch runtime logs and error messages from a plugin.                          | `plugin.logs` `workspace.plugin.logs()`                               | 読み取り | `audit.view`      |
| Search Plugin Marketplace Search the LangBot Plugin Marketplace for installable plugins.  | `plugin.marketplace.search` `workspace.plugin.marketplace.search()`   | 読み取り | `resource.view`   |
| Plugin Readme Get documentation and usage instructions for a plugin.                      | `plugin.readme` `workspace.plugin.readme()`                           | 読み取り | `resource.view`   |

### Model Provider (`provider`)

| 操作                                                                             | ID とメソッド                                                    | リスク  | 付与するメンバーに必要な権限           |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------- | ---- | ------------------------ |
| Create Provider Add a new model provider and credentials to the workspace.     | `provider.create` `workspace.provider.create()`             | 書き込み | `provider_secret.manage` |
| Delete Provider Delete a model provider and its associated models.             | `provider.delete` `workspace.provider.delete()`             | 高リスク | `resource.manage`        |
| Get Provider Get configuration and credentials of a model provider.            | `provider.get` `workspace.provider.get()`                   | 読み取り | `resource.view`          |
| List Providers List all configured model providers in the workspace.           | `provider.list` `workspace.provider.list()`                 | 読み取り | `resource.view`          |
| Provider Models Count Count models configured under a specific model provider. | `provider.models.count` `workspace.provider.models.count()` | 読み取り | `resource.view`          |
| Scan Provider Models Scan remote provider endpoint for available models.       | `provider.models.scan` `workspace.provider.models.scan()`   | 書き込み | `provider_secret.manage` |
| Update Provider Update credentials or base URL of a model provider.            | `provider.update` `workspace.provider.update()`             | 書き込み | `provider_secret.manage` |

### Requester (`requester`)

| 操作                                                                      | ID とメソッド                                      | リスク  | 付与するメンバーに必要な権限  |
| ----------------------------------------------------------------------- | --------------------------------------------- | ---- | --------------- |
| Get Requester Get configuration and capabilities of an HTTP requester.  | `requester.get` `workspace.requester.get()`   | 読み取り | `resource.view` |
| List Requesters List HTTP request client adapters used for model calls. | `requester.list` `workspace.requester.list()` | 読み取り | `resource.view` |

### Skill (`skill`)

| 操作                                                                      | ID とメソッド                                                  | リスク  | 付与するメンバーに必要な権限    |
| ----------------------------------------------------------------------- | --------------------------------------------------------- | ---- | ----------------- |
| Create Skill Create and register a new custom skill package.            | `skill.create` `workspace.skill.create()`                 | 書き込み | `resource.manage` |
| Delete Skill Delete a custom skill and remove its code files.           | `skill.delete` `workspace.skill.delete()`                 | 高リスク | `resource.manage` |
| List Skill Files List files and directories within a skill package.     | `skill.file.list` `workspace.skill.file.list()`           | 読み取り | `resource.view`   |
| Read Skill File Read the source code or content of a file in a skill.   | `skill.file.read` `workspace.skill.file.read()`           | 読み取り | `resource.view`   |
| Write Skill File Write or update a code file inside a skill package.    | `skill.file.write` `workspace.skill.file.write()`         | 書き込み | `resource.manage` |
| Get Skill Get full manifest and metadata for a specific skill.          | `skill.get` `workspace.skill.get()`                       | 読み取り | `resource.view`   |
| Preview GitHub Skill Preview a skill package from a GitHub repository.  | `skill.github.preview` `workspace.skill.github.preview()` | 読み取り | `resource.manage` |
| List Skills List all custom skills installed in the workspace.          | `skill.list` `workspace.skill.list()`                     | 読み取り | `resource.view`   |
| Reload Skills Reload all skill packages and refresh runtime registries. | `skill.reload` `workspace.skill.reload()`                 | 書き込み | `resource.manage` |
| Update Skill Update metadata or configuration of an existing skill.     | `skill.update` `workspace.skill.update()`                 | 書き込み | `resource.manage` |

### Statistics (`stats`)

| 操作                                                                                | ID とメソッド                                | リスク  | 付与するメンバーに必要な権限  |
| --------------------------------------------------------------------------------- | --------------------------------------- | ---- | --------------- |
| Basic Statistics Get workspace overview counters for bots, models, and pipelines. | `stats.basic` `workspace.stats.basic()` | 読み取り | `resource.view` |

### Task (`task`)

| 操作                                                                          | ID とメソッド                          | リスク  | 付与するメンバーに必要な権限  |
| --------------------------------------------------------------------------- | --------------------------------- | ---- | --------------- |
| Get Task Get the status of a background task such as a plugin installation. | `task.get` `workspace.task.get()` | 読み取り | `resource.view` |

### Tool (`tool`)

| 操作                                                                     | ID とメソッド                            | リスク  | 付与するメンバーに必要な権限  |
| ---------------------------------------------------------------------- | ----------------------------------- | ---- | --------------- |
| Get Tool Get parameter schema and description for a specific tool.     | `tool.get` `workspace.tool.get()`   | 読み取り | `resource.view` |
| List Tools List all registered function tools available for execution. | `tool.list` `workspace.tool.list()` | 読み取り | `resource.view` |

### Workspace (`workspace`)

| 操作                                                                                                   | ID とメソッド                                                      | リスク  | 付与するメンバーに必要な権限   |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---- | ---------------- |
| Get Workspace Language Get the Workspace language used for backend messages and default bot replies. | `workspace.language.get` `workspace.workspace.language.get()` | 読み取り | `workspace.view` |

`workspace.language.get` は `{"language": "zh_Hans", "supported_languages": [...]}` を返します。`language` はワークスペース設定のメッセージ言語（既定は `en_US`）で、メンバー個人の WebUI 言語とは無関係です。プラグインと Agent はこれを使って返信や生成内容をローカライズできます。言語の変更は引き続きメンバーのみが行えます。

---

# プラグイン設定情報の完成

Source: https://langbot.app/docs/ja/plugin/dev/basic-info

## マニフェストファイルの修正

プラグインディレクトリ内の`manifest.yaml`ファイルは、プラグインの基本情報を宣言します。これはLangBot UIまたはプラグインマーケットプレイスのインターフェースに表示されます。

プラグインレベルの `spec.permissions` には、プラグインに必要な機能とワークスペース操作を記載します。インストール後にワークスペースのメンバーが確認します。詳しくは[プラグインの権限](https://langbot.app/docs/ja/plugin/dev/permissions.md)を参照してください。

```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:
  permissions:  # プラグインに必要な機能とワークスペース操作。「プラグインの権限」を参照
    capabilities: []
    workspace_operations: []
  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つのコアメソッドを実装する必要があります。完全な実装は公式の [LangRAG ナレッジエンジン](https://github.com/langbot-app/LangBot/tree/master/plugins/KnowledgeEngine/LangRAG)を参照してください。

```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`メソッドでナレッジ検索ロジックを実装する必要があります。完全なコードは[official plugins](https://github.com/langbot-app/LangBot/tree/master/plugins)で見つけることができます。

```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/tree/master/plugins/misc/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/tree/master/plugins/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非同期プラグイン移行ガイドを参照してください。

---

# プラグインの権限

Source: https://langbot.app/docs/ja/plugin/dev/permissions

プラグインに必要な権限を宣言し、ワークスペースのメンバーがそれを許可・取り消しする仕組みを理解します。

プラグインはメッセージへの返信だけでなく、モデルの呼び出し、ナレッジベースの読み取り、任意のボットからのメッセージ送信、さらに[ワークスペース API](https://langbot.app/docs/ja/plugin/dev/apis/workspace.md) を通じた Agent やパイプラインの管理まで行えます。プラグインのインストールはそれぞれ 1 つのワークスペースの中で動くため、LangBot はプラグインに必要な機能を事前に宣言させ、ワークスペースのメンバーに承認してもらう仕組みになっています。

流れは次の 3 段階です。

1. **宣言**：プラグインが必要な権限を `manifest.yaml` に記載します。
2. **確認**：インストール後、メンバーがプラグインの詳細ページで申請内容を確認し、すべて、または一部を許可します。確認されるまで、インストールは無効のままです。
3. **検証**：プラグインが呼び出しを行うたびに、LangBot はそのインストールに許可された権限を確認します。許可範囲外の呼び出しは `permission_denied` になります。

権限を宣言しただけでは許可されません。メンバーが確認して初めて有効になります。

## 権限を宣言する

権限はプラグイン全体に属するため、コンポーネントの中ではなく `manifest.yaml` のプラグインレベルの `spec` に記載します。同じ許可がコマンド、イベントリスナー、ツール、ナレッジエンジン、パーサー、Runner など、プラグインのすべてのコンポーネントに適用されます。

```yaml
apiVersion: v1
kind: Plugin
metadata:
  author: acme
  name: WeeklyReport
  version: 1.0.0
spec:
  permissions:
    capabilities:
      - models.invoke      # LLM を呼び出す
      - bot.message.send   # レポートをグループに送信する
      - storage.plugin     # 前回の送信日時を記録する
    workspace_operations:
      - stats.basic        # ワークスペースの統計を読み取る
      - knowledge.*        # ナレッジベースのすべての操作
  config: []
  components: {}
```

2 つのリストはそれぞれ異なる種類のアクセスを表します。

- **`capabilities`（機能）**：`self.plugin` にある従来の SDK メソッド（`invoke_llm`、`send_message`、`set_plugin_storage` など）を利用可能にします。全 16 項目は[下の表](#機能)を参照してください。
- **`workspace_operations`（ワークスペース操作）**：[ワークスペース API](https://langbot.app/docs/ja/plugin/dev/apis/workspace.md) の操作を利用可能にします。LangBot の HTTP API、MCP サーバー、ワークスペースアシスタントが使うものと同じ操作で、各項目は `pipeline.list` のような操作 ID です。

実際に使う権限だけを宣言してください。短く妥当なリストほどメンバーに承認されやすく、許可範囲が小さいほど万一プラグインが悪用されたときの影響も小さくなります。

### 厳格モードと互換モード

宣言の仕方によって、インストールがどのモードで動くかが決まります。

| マニフェストの書き方                     | モード   | 動作                                         |
| ------------------------------ | ----- | ------------------------------------------ |
| `permissions:` に一方または両方のリストを記載 | 厳格モード | メンバーはすべて、または一部だけを許可できます。                   |
| `permissions: {}`              | 厳格モード | グローバルなアクセスを一切必要としません。                      |
| `permissions` フィールドなし          | 互換モード | 旧来のプラグインとして扱われます。[互換モード](#互換モード)を参照してください。 |

新しいプラグインでは、空であっても必ず権限を宣言してください。

### ワイルドカード

ワークスペース操作は `.*` で終えることで、あるプレフィックス配下の操作をまとめて申請できます（例：`knowledge.*`、`model.llm.*`）。メンバーが確認すると、LangBot はワイルドカードを具体的な操作 ID に展開して保存します。後の LangBot バージョンでそのプレフィックスに操作が追加されても自動では許可されず、インストールは再び確認待ちになります。

プラグインには決して許可できない操作もあります。ストリーミング操作、他の呼び出し元専用の操作（ログインしたメンバーだけが呼び出せる操作など）、そもそも API として公開されていない操作です。これらや未知の ID を宣言すると、権限の宣言は無効になります。ワイルドカードも同様で、プレフィックス配下にこうした操作が含まれていると全体が拒否されます。そのため `bot.*`、`agent.*`、`pipeline.*`、`plugin.*`、`monitoring.*` は使えません。個別に列挙するか、より狭いプレフィックスを使ってください。

現在使えるワイルドカード：

- ドメイン全体：`adapter.*`、`extension.*`、`knowledge.*`、`model.*`、`requester.*`、`stats.*`、`tool.*`
- より狭いプレフィックス：`agent.runs.*`、`bot.group_filter.*`、`bot.message.*`、`bot.routes.*`、`bot.runtime.*`、`mcp.resource.*`、`monitoring.execution.*`、`monitoring.feedback.*`、`monitoring.message.*`、`monitoring.session.*`、`pipeline.chat.*`、`pipeline.extensions.*`、`plugin.github.*`、`plugin.marketplace.*`、`provider.models.*`、`skill.file.*`、および `knowledge.` と `model.` 配下のすべてのプレフィックス

プラグインが申請できるすべての操作は[ワークスペース API の操作一覧](https://langbot.app/docs/ja/plugin/dev/apis/workspace.md#操作一覧)にあります。

## 機能

各機能は一連の SDK メソッドを利用可能にします。その機能を確認するメンバーには 3 列目のワークスペース権限が必要です。最後の列は、メンバーが何を承認することになるかを示しています。

| 機能                  | 利用可能になる SDK メソッド                                                                                                       | 付与するメンバーに必要な権限                      | 意味                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------ |
| `langbot.info`      | `get_langbot_version`                                                                                                  | `resource.view`                     | 読み取りのみ                               |
| `bot.read`          | `get_bots`、`get_bot_info`                                                                                              | `resource.view`                     | 読み取りのみ                               |
| `bot.message.send`  | `send_message`                                                                                                         | `runtime.operate`                   | ユーザーやグループにメッセージを送信                   |
| `bot.platform_api`  | `call_platform_api`                                                                                                    | `runtime.operate`、`resource.manage` | **危険**：IM プラットフォームのネイティブ API を直接呼び出し |
| `models.read`       | `get_llm_models`                                                                                                       | `resource.view`                     | 読み取りのみ                               |
| `models.invoke`     | `invoke_llm`、`invoke_llm_with_usage`、`invoke_llm_stream`、`invoke_llm_stream_events`、`invoke_embedding`、`invoke_rerank` | `runtime.operate`                   | モデルプロバイダーの利用枠を消費                     |
| `storage.plugin`    | `get/set/delete_plugin_storage`、`get_plugin_storage_keys`                                                              | `resource.manage`                   | プラグイン専用ストレージの読み書き                    |
| `storage.workspace` | `get/set/delete_workspace_storage`、`get_workspace_storage_keys`                                                        | `resource.manage`                   | 全プラグイン共有ストレージの読み書き                   |
| `knowledge.read`    | `list_knowledge_bases`、`retrieve_knowledge`、`get_knowledge_file_stream`                                                | `resource.view`                     | ナレッジベースの読み取り                         |
| `knowledge.vector`  | `vector_upsert`、`vector_search`、`vector_delete`、`vector_list`                                                          | `resource.manage`                   | ベクトルストアへの書き込み                        |
| `knowledge.parser`  | `list_parsers`、`invoke_parser`                                                                                         | `runtime.operate`                   | ドキュメントパーサーの実行                        |
| `config.read`       | `get_config_file`                                                                                                      | `resource.view`                     | アップロードされた設定ファイルの読み取り                 |
| `plugin_tools`      | プラグインのツールに対する `list_tools`、`get_tool_detail`、`call_tool`                                                               | `runtime.operate`                   | 他のプラグインのツールを実行                       |
| `mcp`               | MCP ツールに対する `call_tool`                                                                                                | `runtime.operate`                   | **危険**：MCP ツールを実行                    |
| `sandbox`           | `get_box_status`、`list_boxes`、`acquire_box`、およびサンドボックスツールに対する `call_tool`                                              | `runtime.operate`                   | **危険**：サンドボックスでコードを実行                |
| `plugin.read`       | `list_plugins_manifest`、`list_commands`                                                                                | `resource.view`                     | インストール済みプラグインの一覧                     |

ツールについて 2 点注意があります。プラグインが他のプラグインのツールを呼び出すと、そのツールはあなたの許可ではなく、**呼び出された側**のインストールの許可で実行されます。また、機能はツールの提供元ごとに確認されるため、`plugin_tools` だけでは MCP ツールやサンドボックスツールは呼び出せません。

プラグインが現在処理しているイベントや実行だけに作用する呼び出しには、機能は必要ありません。発生元の会話への返信、現在のクエリ変数の読み取り、LangBot が Runner に提供するツールの利用は、インストールの許可ではなく、そのイベントや実行自体によって認可されます。詳しくは [Agent 実行 API](https://langbot.app/docs/ja/plugin/dev/apis/agent-run.md) と[パイプラインイベント API](https://langbot.app/docs/ja/plugin/dev/apis/pipeline-events.md) を参照してください。

## インストールを確認する

新しくインストールされたプラグインや、アップグレード後に確認が必要なプラグインは、プラグイン一覧と詳細ページに **承認待ち** と表示され、無効のままになります。メンバーは詳細ページの **プラグイン権限** を開き、申請内容を確認して、許可したくない項目のチェックを外してから **許可** を選択します。確認ダイアログでは、危険な機能とメッセージ送信機能が強調表示されます。

確認できる人：

- 新たに許可を追加できるのは、WebUI にログインしたメンバー（およびサポート管理者）だけです。API キー、`lbctl`、プロセッサー、プラグイン、公開ボットはできません。API キーや `lbctl` でインストールしたプラグインは、あとでメンバーが WebUI で確認する必要があります。
- メンバーには `resource.manage` と、各許可が要求する権限が必要です。機能は上の表、ワークスペース操作はその操作の `permission` を見てください。開発者ロールは `resource.view`、`resource.manage`、`runtime.operate` を持つため、すべての機能を許可できます。ただし、メンバー管理や API キー管理など、自分のロールを超える操作を許可できるわけではありません。
- 申請の中に 1 つでもメンバーの権限を超える項目があると、リクエスト全体が `permission_denied` で失敗し、レスポンスの `denied_operations` と `denied_capabilities` に該当項目が示されます。LangBot が一部だけを黙って捨てることはありません。

厳格モードでは、メンバーは宣言された権限の任意の一部だけを許可できます。任意の権限が欠けていても、プラグインが穏やかに機能を縮退できるようにしてください。

許可はメンバーではなくインストールに属します。承認したメンバーが後でロールを変えたりワークスペースを離れたりしても、許可は有効なままです。

### インストール時の自動確認

セットアップウィザードとパイプラインの移行では、公式プラグインのインストールと同時に、宣言された権限も確認されます。この処理は手動の確認とまったく同じチェックを通ります。呼び出し元はメンバーであり、必要な権限をすべて持っている必要があります。いずれかのチェックに失敗した場合、プラグインはインストールされますが承認待ちのままです。HTTP では `POST /api/v1/plugins/install/marketplace` の `auto_confirm_permissions: true` に相当します。既定値は `false` で、API キーがこれを使ってメンバーの確認を回避することはできません。

### プラグインと Agent によるインストール

メンバーが該当する操作を許可すると、プラグイン、またはワークスペースツールを通じた Agent やパイプラインは、`plugin.marketplace.search` でマーケットプレイスを検索し、`plugin.install.marketplace` でプラグインをインストールできます。インストールは**高リスク**に分類されるため、Agent やパイプラインで選択すると機密ツールの警告が表示されます。これらの呼び出し元が行えるのは、マーケットプレイスからの新規インストールだけです。

- `auto_confirm_permissions: true` は `permission_denied` で拒否されます。新しいプラグインは、メンバーが詳細ページで権限を確認するまで無効のままです。
- すでにインストールされているプラグインのインストールは `plugin_already_installed` で失敗します。アップグレードや再インストールはメンバーが行います。
- インスタンスでマーケットプレイスが無効な場合、どちらの操作も `marketplace_disabled` で失敗します。
- GitHub やローカルファイルからのインストールは利用できません。

インストールの呼び出しは `task_id` を返します。`status` が `succeeded` または `failed` になるまで `task.get` をポーリングしてください。`pending_permission_confirmation: true` は、プラグインがメンバーの確認を待っていることを示します。

## 取り消しとアップグレード

`resource.manage` を持つメンバーは、チェックを外して保存するだけでいつでも許可を取り消せます。取り消しには確認も権限の上限も必要ありません。API キーは取り消しはできますが、追加はできません。

プラグインをアップグレードすると：

- 新しいバージョンでも宣言されている権限は、既存の許可がそのまま残ります。
- 新しいバージョンで追加された権限は、メンバーが確認するまで許可されず、インストールは再び **承認待ち** になります。
- 新しいバージョンで宣言されなくなった権限は、すぐに無効になります。

## Agent やパイプラインの設定との関係

Agent やパイプラインでツールを選んでも、何かが許可されるわけではありません。モデルに見せる範囲を絞るだけです。LocalAgent のような Runner がモデルに提供するのは、Agent（またはパイプラインの **プラグイン統合** ページ）で選択されたツールと、Runner プラグインのインストールに許可された操作の共通部分です。何も選択していなければ、モデルにはワークスペースのツールが一切提供されません。

そのため、Agent を編集できるメンバーは、自分では許可できないワークスペース操作を選択することもできます。十分な権限を持つメンバーがその操作を Runner プラグインに許可していない限り、その選択は何の効果も持ちません。

## 互換モード

プラグインの権限の仕組みができる前に作られたプラグインには `spec.permissions` がありません。LangBot はこれらを互換モードで実行します。

- **従来の 16 項目すべての機能**が固定のセットとして与えられ、**ワークスペース操作は含まれません**。
- メンバーはセット全体を一度に確認する必要があり、一部だけの確認はできません。マニフェストからはどの部分が安全かを判断できないためです。確認後は、個々の機能を取り消せます。
- 確認には `resource.view`、`resource.manage`、`runtime.operate` のすべてが必要です。
- 将来の LangBot で追加される機能は、すでに確認されたセットには自動では加わりません。

LangBot のアップグレード前から存在していたインストールは、このセットが確認済みの状態で移行され、有効・無効の状態もそのまま保たれます。互換モードのプラグインを新しくインストールしたり、アップグレードしたり（以前の宣言を削除したバージョンへのアップグレードを含む）すると、メンバーが再び確認するまで無効になります。

## 拒否された呼び出しへの対応

従来の SDK メソッドはエラーを送出し、そのデータには `code: permission_denied` と、必要に応じて `denied_capabilities` が含まれます。ワークスペース API の呼び出しは例外を送出せず、同じエラーコードで `{"ok": false, "error": {...}}` を返します。どちらの場合も、権限不足は通常の結果として扱ってください。ログに記録し、どの権限が足りないかをユーザーに伝え、その機能なしで処理を続けます。

## API で権限を管理する

WebUI は次のエンドポイントを使っており、メンバーのトークンで呼び出すこともできます。

- `GET /api/v1/plugins/{author}/{plugin_name}/permissions`：宣言された各項目の `granted` と `grantable`、インストールが互換モードか承認待ちか、そして呼び出し元の `can_manage` と `can_confirm` を返します。ワークスペース操作には所属する `domain` が付き、レスポンスの `domains` に各ドメインの名前が含まれます。
- `PUT /api/v1/plugins/{author}/{plugin_name}/permissions`：`workspace_operations`、`capabilities`、`confirm` を受け取ります。`confirm: false` のときはリストが現在の許可の部分集合である必要があるため、この形式では取り消ししかできません。`confirm: true` のときは上で説明した確認のルールがすべて適用されます。
- プラグインの一覧・詳細のレスポンスには、`compatibility_mode` と `pending_confirmation` を含む `permission_status` があります。

対応する Application API の操作は `plugin.permissions.get` と `plugin.permissions.update` です。LangBot の MCP サーバーは `get_plugin_permissions` と `revoke_plugin_permissions` を提供しています。API キーで認証された MCP クライアントは新しい許可を確認できません。

---

# 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. **送信** をクリックして完了します。LangBot がボットの識別情報を自動的に取得します。

> warning:
>
> ワンクリック設定ではアプリの認証情報が入力されますが、カードテンプレートは作成されません。ストリーミング返信には LangBot の返信テンプレートをインポートし、Use Card Replies を有効にして Card Template ID を設定すると自動的に有効になります。スイッチを無効にすると、テンプレート ID を削除せずにプレーンテキストで返信できます。人工入力には別のテンプレートをインポートし、Human Input Card Template ID を設定してください。DingTalk アプリのカード権限も必要です。

## カードテンプレートの設定（LangBot 提供のテンプレートを推奨）

カード返信には、LangBot が提供するテンプレートをインポートしてください。コンポーネントや変数を手動で設定する必要はありません。DingTalk アプリで必要なカード権限を有効にしてから、用途に応じたテンプレートを選びます。

| 用途                     | ダウンロードするファイル                     | LangBot の設定項目                |
| ---------------------- | -------------------------------- | ---------------------------- |
| 思考と回答を分けて表示するストリーミング返信 | `dingtalk_stream_card.json`      | Card Template ID             |
| ユーザーの入力・選択・確認を待って処理を続行 | `dingtalk_human_input_card.json` | Human Input Card Template ID |

### ストリーミング返信テンプレートの作成とインポート

1. DingTalk アダプター設定の **Card Template ID** の下にある **Download Streaming Reply Card Template** をクリックします。
2. [DingTalk カードプラットフォーム](https://open-dev.dingtalk.com/fe/card)でボットアプリと同じ組織を選び、**新規テンプレート**を作成します。
3. 名前を入力し、カード種類を **メッセージカード（消息卡片）**、シナリオを **AI カード（AI 卡片）** に設定します。現在のボットアプリを関連付け、作成方法で **空白から作成（空白搭建）** を選び、**空白テンプレートを作成（创建空白模板）** をクリックします。

![メッセージカード、AI カード、関連アプリ、空白から作成を選択する画面](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/create_ai_card_template.png)

4. エディター上部の **その他 → カードテンプレートをインポート（更多 → 导入卡片模板）** から `dingtalk_stream_card.json` を選択します。

![エディターのその他メニューにあるインポート項目](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/import_card_template.png)

> info:
>
> インポート項目はテンプレート一覧ではなく、エディター内にあります。インポートすると現在の内容が置き換わるため、新しい空白テンプレートを使用してください。インポートしたコンポーネント、変数、イベントの設定は維持します。

5. プレビューを確認して**保存・公開**し、テンプレート ID をコピーします。下書きの保存だけでは送信できません。`param.templateUnpublished` はテンプレートが未公開であることを示します。
6. LangBot の **Use Card Replies** を有効にし、**Card Template ID** に ID を入力して保存すると、ストリーミング返信が有効になります。スイッチを無効にするとプレーンテキストで返信し、テンプレート設定は非表示になりますが保持されます。再度有効にすると設定を再利用できます。

テンプレートには LangBot の表示があり、思考と回答を別々に表示します。生成中は思考欄が開き、完了後は折りたたまれます。クリックで再び展開できます。下部には回答のコピー、高評価・低評価、AI 生成コンテンツの表示があります。思考を削除するかどうかはパイプライン設定に従い、削除する場合は思考欄を表示しません。通常メッセージで思考を保持する場合は、`<think>` と `</think>` を文字として表示し、空行で回答と区切ります。

カードの自動ワイドレイアウトはデフォルトで有効です。提供する返信テンプレートには必要な変数が含まれています。既存のボットで無効にして保存している場合は、有効にして設定を保存してください。幅の狭い表示を希望する場合は無効のままでも使用できます。

更新時は最新版をダウンロードして再インポートし、保存・公開してください。別のテンプレートを作成した場合は LangBot 側の ID も変更します。`content` のみを使用する既存テンプレートも利用できますが、新しい思考欄の分離表示には対応しません。

## 人工入力カードテンプレートのインポート

人工入力は、ワークフローやプラグインがユーザーの情報入力・選択・確認を待ってから処理を続ける場面で使用します。Dify の Human Input ノードなどが該当します。通常のチャットやストリーミング返信だけなら、このテンプレートは不要です。

1. **Human Input Card Template ID** の横にある **Download Human Input Card Template** から `dingtalk_human_input_card.json` を保存します。
2. 上記と同じ手順で、別の **メッセージカード → AI カード → 空白から作成** テンプレートを作り、ボットアプリを関連付けます。
3. エディターの **その他 → カードテンプレートをインポート** から人工入力用 JSON を読み込みます。入力欄、ボタン、変数、イベントの設定は維持します。
4. **保存・公開**し、その ID を LangBot の **Human Input Card Template ID** に入力して設定を保存します。

2 種類のテンプレートは別々にインポートし、対応する設定項目に 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)

カードテンプレートは、上記の手順で LangBot 提供のテンプレートをインポートして公開してください。

### 設定情報の入力

「認証情報と基本情報」をクリックし、「Client ID」と「Client Secret」を記録します。
この認証情報を LangBot のアダプター設定に入力します。
`markdown_card`（Use Card Replies）は Markdown とストリーミングカード返信の共通スイッチです。有効でテンプレートが設定されていればストリーミング、未設定なら通常の Markdown で返信します。無効にすると設定を保持したままプレーンテキストで返信します。ワークフローの人工入力カードは別途設定します。
上記の設定項目を記録し、LangBot ボット設定フォームに入力します

[カードプラットフォーム](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV)をクリックし、テンプレートリストから対応するバインドされたテンプレート ID をコピーし、カードテンプレート ID フィールドに入力します。

**LangBot を起動します**。

### ボットの追加

この記事では DingTalk Windows デスクトップ版を例として使用します。上部の「検索」、「機能」をクリックし、先ほど作成したボットの名前を入力します。以下のように：
![robot\_png](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk5.png)

ボットをクリックしてチャットします。

グループに追加したい場合は、DingTalk グループの「グループ管理」、「ロボット」、「ロボットを追加」をクリックし、ボット名を検索してグループで使用します。

## イベント購読

DingTalk アプリ管理画面のイベント購読で Stream モードを選択し、必要なイベントを有効にしてください。ロボットのメッセージ受信設定とは別の設定です。

- `chat_add_member` → `group.member_joined`（メンバーごとに通知）。
- `chat_remove_member` / `chat_quit` → `group.member_left`（削除と自主退出を区別）。
- `chat_update_title` / `chat_update_owner` → `group.info_updated`。
- 通常のカード操作 → `dingtalk.card_action`。識別可能な評価は `feedback.received`、管理対象フォームは既存の対話処理に渡し、重複実行を防ぎます。
- グループ解散などその他の購読イベントは `platform.specific` に渡し、`action` にイベント名、`data` に元のヘッダーとデータを保持します。

グループイベントにはアプリ権限とグループ種別の制限があります。unionId のみを含むメンバー通知はプラットフォーム固有イベントとして保持します。メッセージ編集・撤回・リアクション、友達申請、ボットのミュートなど、対応するプッシュが未確認のイベントは対応済みと表示しません。

---

# 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) で **New Application** を選択します。アプリ名に `Discord` を含めると作成が拒否されます。画面に従って規約の確認と認証を完了してください。

1. **General Information** の **Application ID** をコピーします。LangBot の「クライアント ID」に使う値で、サーバー ID やチャンネル ID とは異なります。
2. **Bot → Reset Token** で認証を完了し、表示されたトークンを LangBot に入力します。表示は一度だけです。スクリーンショット、コード、公開メッセージには含めないでください。再生成すると旧トークンは無効になるため、LangBot 側も更新します。
3. **Privileged Gateway Intents** の **Server Members Intent** と **Message Content Intent** を有効にし、**Save Changes** で保存します。新アダプターは両方を要求します。**Presence Intent は不要です**。

## LangBot に接続する

新しい **Discord** アダプター（`discord-omni`）でボットを作成し、クライアント ID とトークンを入力して保存します。

続いてイベント処理を設定します。

- **Pipeline**：「受信メッセージへの返信」ルールを追加し、`message.received` をモデル設定済みの Pipeline に割り当てます。ボットのイベントルートの**トリガー条件**で、本文・会話タイプ・メッセージ要素を指定します。明示的なイベントルートは Pipeline 内のグループ応答ルールをスキップするため、無条件のルートはすべての受信メッセージを処理します。メンション要素の条件はボット以外への @ メンションにも一致します。
- **Agent**：イベントを Agent に割り当て、イベント返信ツールで実際にメッセージを送るよう指示します。テキストの生成だけでは送信されません。必要なツールだけを選択します。
- **プラグイン処理器**：ボット画面で既存のプラグイン処理器設定を別途追加します。プラグインが宣言したイベントを独立して受信し、Pipeline や Agent と併用できます。

コード実行やファイル生成には、利用可能な Box サンドボックスを有効にします。添付ファイルのために無関係な MCP サーバーを有効にする必要はありません。認証情報のない外部ツールは別のエラー原因になります。

ボットを有効にし、ログの `Discord adapter running as ...` を確認します。これは Gateway ログインの確認です。経路と配信の確認には Discord から実際にメッセージを送信してください。

## テストサーバーに追加する

**OAuth2 → URL Generator** で `bot` と **Guild Install** を選びます。通常のメッセージ、画像、ファイルのテストには次の権限を使用できます。

- View Channels
- Send Messages
- Embed Links
- Attach Files
- Read Message History
- Add Reactions

生成されたリンクを開き、自分のテストサーバーを選択して認証します。Administrator は不要です。メンバー管理やスレッドの権限は必要な場合だけ追加します。チャンネル固有の権限でも閲覧と送信が許可されている必要があります。

## 実際の送受信を確認する

サーバーのチャンネルで応答条件に一致するメッセージを送信し、ボットのプロフィールから DM も開きます。両方で通常返信、段階的なストリーミング、画像・テキストファイルの入力、添付ファイルの返送を確認します。返信文にファイル名や保存先が書かれているだけでは配信の証拠になりません。

Discord には一通の文字数制限があるため、長いストリーミング出力は分割して送信する必要があります。最後の部分と終了マーカーまで確認してください。LangBot の成功ログだけでは完全な配信を保証できません。画像認識には視覚対応モデル、ファイル処理には適切なツールとサンドボックスが必要です。

アダプターは編集、削除、リアクションの追加・削除、メンバーの参加・退出、ボットの参加・退出、プラットフォーム固有イベントも提供します。Pipeline はメッセージを処理するため、その他のイベントは Agent またはプラグインに割り当てます。対話の送信イベントは LangBot が送った対話コンポーネントから発生し、Discord の全イベントをそのまま転送する機能ではありません。

メッセージイベントの `chat_id` はチャンネル ID、`group.id` はサーバー ID です。チャンネルへの送信にはチャンネル ID、サーバーやメンバーの照会・管理にはサーバー ID を使います。混同しないでください。

メンバーの参加・退出イベントには送信元チャンネルがありません。返信にはサーバーで設定された **システムメッセージのチャンネル** を使用します。Discord のサーバー設定で指定し、Bot にチャンネルの閲覧とメッセージ送信を許可してください。未設定の場合、返信は明示的に失敗します。退出コールバックでは自主退出とキックを区別できないため、`is_kicked` を確実な管理判断に使用しないでください。

![Discord への実際の配信：プラグインが画像とテキストファイルを返し、その後 Pipeline の DM 返信も成功しています。](https://langbot.app/docs/images/zh/deploy/bots/discord/attachment-roundtrip.jpg)

## トラブルシューティング

- **Gateway に接続できない**：最新トークンと必須の二つの Intent、保存状態を確認します。ブラウザーのログイン成功はボットの認証成功とは別です。

- **オンラインでも返信がない**：有効化、イベント経路、モデル、応答条件、チャンネル権限を確認します。独立したプラグイン購読は別設定です。

- **添付ファイルで失敗する**：添付権限、実行ログ、Box の状態、添付 CDN への接続を確認します。Gateway と CDN の到達性は別々です。

- **ネットワーク制限**：LangBot から Discord の Gateway、API、添付 CDN に接続できる必要があります。必要に応じて環境に合ったプロキシを設定します。

- **スクリーンショット**：トークンや実際の利用者の私的な会話を含めないでください。

- **古い会話で添付の 404 が発生する**：Discord の添付 URL は期限切れになり、過去の画像によって後続のテキストだけの要求も失敗することがあります。添付を再アップロードし、会話のコンテキストをリセットしてください。EssentialCommands を導入している場合は `!reset` を送信できます（接頭辞はインスタンス設定に従います）。監視ログは削除されません。

---

# 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. **送信** をクリックして完了

### 権限とイベント購読の追加

> info:
>
> QR コードで作成・認証したアプリには、必要な権限やイベント購読がすべて設定されているとは限りません。メッセージを送受信できても、メンバーの参加・退出イベントは未購読の場合があります。ボットを作り直す必要はなく、開発者コンソールで既存のアプリに設定を追加できます。

1. [Feishu 開発者コンソール](https://open.feishu.cn/app)または [Lark 開発者コンソール](https://open.larksuite.com/app)で、作成・認証したアプリを選択します。App ID で確認できます。
2. **権限管理**で必要な権限を追加します。権限は、ボットが利用できるデータや操作を決めます。
3. **イベントとコールバック > イベント設定**で必要なイベントを購読します。購読は LangBot に送信される通知を決める設定です。権限を追加するだけではイベントは購読されません。
4. 設定を保存し、プラットフォームから求められるバージョン公開や管理者承認を完了します。有効になった後で再度イベントを発生させて確認してください。購読前の操作は自動再送されません。

> warning:
>
> **イベントを追加した後は、アプリの新しいバージョンを公開してください。** 開発者コンソールの**バージョン管理と公開**で公開を完了し、管理者承認が必要な場合は承認を待ちます。イベントを追加・保存しただけでは、公開待ちの変更は有効になりません。LangBot が正常に接続されていても、これらのイベントが届かない場合があります。

購読後もメンバーの参加・退出イベントが届かない場合は、まず公開待ち・承認待ちの変更がないか確認してください。新しいバージョンが有効になった後、ボットが参加しているグループでメンバーの参加・退出を再度行い、LangBot のイベント記録を確認します。

メンバーの参加・退出を受信するには、ボットが対象グループに参加し、次のイベントを購読している必要があります。

| 機能                | Feishu イベント                      |
| ----------------- | -------------------------------- |
| ユーザーのグループ参加       | `im.chat.member.user.added_v1`   |
| ユーザーの退出・グループからの削除 | `im.chat.member.user.deleted_v1` |

ボット自身の参加（`im.chat.member.bot.added_v1`）は別のイベントで、他のメンバーの参加・退出は含まれません。LangBot の**イベントルーティング**でも、対象イベントを Agent またはプラグイン処理器に振り分けてください。パイプラインはメッセージイベントのみを処理します。

***

## ボットの作成

[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` を入力し、設定の確認をクリックします。コールバックアドレスが正常に保存された場合、デプロイは成功です。「検証失敗」が表示された場合は、上記の設定項目が正しく入力されているかどうかを注意深く確認してください。

## グループ返信と At コンポーネント

QQ Official Omni の `Enable Markdown Rendering` は初期状態で無効です。グループのプレーンテキスト返信では、タグがそのまま表示されないよう At コンポーネントを省略し、元のメッセージの `msg_id` を保持します。QQ クライアントでのメンション通知を保証するものではありません。

明示的なメンションには、QQ ボットの Markdown 権限を確認してからこの設定を有効にしてください。表示名や QQ 番号ではなく、メンバーの元の OpenID を使用します。実際の QQ クライアントで表示を確認してください。LangBot が自動的に Markdown に切り替えることはありません。公式文書にはプレーンテキスト対応の記載がありますが、[アダプターでの検証](https://github.com/nonebot/adapter-qq/issues/220)とユーザーの確認ではタグがそのまま表示されています。

## 公開方法

「ホーム」のリリースプロセスに入り、プロセスに従ってボットを公開して起動します。

---

# ボット（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 クイック設定**を使うと、LangBot がアプリの権限、メッセージイベント、メッセージタブ、OAuth 戻り先 URL を自動設定します。設定トークンを入力して Slack でインストールを承認し、Socket Mode の場合は App-Level Token を追加してください。

### 1. ボットを作成して接続方式を選ぶ

LangBot の **ボット → ボットを作成**で名前を入力し、**Slack** を選んで送信します。設定ページで接続方式を選び、**Slack クイック設定 → 開始**をクリックします。

![ボットを作成して Slack アダプターを選択する](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-create-bot.jpg)

- **Socket Mode（推奨）**：LangBot から Slack に接続するため、公開イベント Webhook は不要です。ローカル環境やプライベートネットワークに適しています。
- **Webhook**：Slack がイベントを送信するため、公開 HTTPS エンドポイントが必要です。

![Socket Mode を選びクイック設定を開く](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-connection-mode.jpg)

### 2. App Configuration Tokens を取得する

[Slack アプリページ](https://api.slack.com/apps)を開き、**Your App Configuration Tokens → Generate Token** で対象のワークスペースを選択します。**Access Token** と **Refresh Token** をそれぞれコピーしてください。既存のトークンがある場合は、そのコピー用ボタンを使用できます。

![設定トークンの場所とコピーボタン](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-configuration-tokens.jpg)

これらはアプリの作成・設定用であり、**実行時に使う Bot Token や App-Level Token とは異なります**。アシスタントの対応する欄に入力し、アプリ名を確認します。

### 3. URL を確認してアプリを自動作成する

Socket Mode では **OAuth 戻り先 URL** を確認します。承認後にブラウザーを LangBot に戻す URL で、HTTPS または `http://localhost` を使用でき、末尾は `/api/v1/platform/adapters/slack/setup/callback` です。ブラウザーからアクセスできればよく、イベント Webhook ではありません。リモート環境では、ブラウザーから到達できないサーバー内部のアドレスを指定しないでください。

![Socket Mode のクイック設定フォーム](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-socket-mode.jpg)

Webhook の場合は **Webhook URL** が表示されます。公開ドメイン、HTTPS、リバースプロキシを確認し、末尾の `/bots/<ボット UUID>` を維持してください。この URL から OAuth 戻り先 URL が生成され、Slack のイベント URL 検証も自動で行われます。

**作成して自動設定**をクリックし、**Slack で承認**が表示されるまで待ちます。

### 4. Slack でインストールを承認する

**Slack で承認**を開き、アプリ名、ワークスペース、権限を確認して **Allow** をクリックします。ワークスペースのポリシーによっては管理者の承認が必要です。完了後、元の LangBot アシスタントに戻ります。

![Slack のインストール承認画面](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-slack-permissions.jpg)

### 5. Socket Mode：App-Level Token を追加する

Webhook の場合はこの手順をスキップします。Socket Mode ではアシスタントの**アプリ設定を開く**から **Basic Information → App-Level Tokens → Generate Token and Scopes** に進みます。

1. Token Name に `langbot-socket` などの名前を入力します。
2. **Add Scope** で **connections:write** を選択します。
3. **Generate** をクリックし、生成された `xapp-` トークンをコピーして、アシスタントの **App-Level Token** に入力します。

![App-Level Token に connections:write を追加する](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-app-token-scope.jpg)

**Token rotation** は無効のままにしてください。作成した同じ Slack アプリのトークンを使用します。手順 2 の Access Token や Refresh Token をここに入力しないでください。

### 6. 設定を反映し、ルーティングを設定して有効化する

承認完了が表示されたら、**アダプター設定に入力**をクリックします。Socket Mode では App-Level Token を入力すると、このボタンが有効になります。Bot Token などの認証情報は自動で反映されます。

![承認完了とアダプター設定への反映](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-authorized.jpg)

**イベントルーティング → アクションを追加 → 受信メッセージに返信**で、`message.received` に設定済みのパイプラインまたは Agent を指定し、ルートを有効にします。最後に右上の**保存して有効化**をクリックします。

![メッセージのルートを設定して保存する](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-routing.jpg)

### 7. 会話を確認する

Slack でアプリの **Messages** タブを開き、DM を送信します。ボットをチャンネルに招待してメンションすることもできます。返信が届けば接続成功です。

![Slack ボットとの会話成功例](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-conversation.png)

> info:
>
> 設定トークンは一時的な設定セッションでのみ使用し、実行用の認証情報として保存しません。セッションは 15 分間有効です。キャンセルしても作成済みの Slack アプリは削除されず、再実行すると別のアプリが作成される場合があります。戻り先ページでエラーが出ても、最初に元のアシスタントで承認完了になっていないか確認してください。

返信がない場合は、ボットとメッセージルートが有効か、処理先が正常に動作するか、ボットのログにエラーがないかを確認します。Socket Mode では同じアプリの App-Level Token と `connections:write` 権限を、Webhook では公開 URL と Slack の **Verified** 表示を確認してください。

## イベント、インタラクション、既存アプリの更新

クイック設定は以下の購読とインタラクションの受信設定を行います。インストール時にメッセージ、チャンネル、ユーザー、ファイル、リアクションの権限を要求し、リアクションには `reactions:read` を使用します。このボットが開始したスレッドへの返信は @メンションなしで受信できます。他のチャンネルメッセージには引き続き @メンションが必要です。スレッド返信の受信には `message.channels` と `channels:history`、プライベートチャンネルにはさらに `message.groups` と `groups:history` が必要です。権限を追加したら Slack アプリを再インストールしてください。

スレッド返信の配信はボットへのメンションを意味しません。メンションのない返信もプラグインで処理できますが、デフォルトのパイプラインのメンションに基づくグループ応答条件は満たしません。

| Slack イベント                                                                  | LangBot イベント                                                  |
| --------------------------------------------------------------------------- | ------------------------------------------------------------- |
| DM、`app_mention`、このボットが開始したスレッドへの返信                                         | `message.received`                                            |
| `message_changed` / `message_deleted` サブタイプ                                 | `message.edited` / `message.deleted`                          |
| `reaction_added` / `reaction_removed`                                       | `message.reaction`、`is_add` で区別                               |
| `member_joined_channel` / `member_left_channel`                             | `group.member_joined` / `group.member_left`                   |
| ボット自身の参加・退出                                                                 | 招待者がある場合は `bot.invited_to_group`、退出は `bot.removed_from_group` |
| チャンネル名、アーカイブ状態、トピック・用途の変更                                                   | `group.info_updated`                                          |
| `block_actions`、`view_submission`、`view_closed`、`shortcut`、`message_action` | `platform.specific`、`action` は `slack.` とコールバック名              |
| `app_home_opened`、`app_uninstalled`、`tokens_revoked`                        | `platform.specific`、`action` は `slack.` とイベント名                |

ボットのイベントルーティングでハンドラーを設定し、プラットフォームイベントは `action` で区別します。アンインストールとトークン失効は警告ログにも記録され、自動でチャット返信しません。リアクションをモデルへの評価とは自動判定しません。メッセージ ID は Slack の `ts` をチャンネルと組み合わせて識別し、スレッド返信は `thread_ts` を維持します。

インタラクションは受信確認後に非同期処理します。モーダル送信の確認応答での同期的な項目エラー返却と外部選択肢の読み込みには対応していません。`view_closed` を受信するにはモーダル作成時に `notify_on_close: true` が必要です。ボタン、ショートカット、モーダル自体は自動作成しません。Socket Mode と Webhook の両方で受信できますが、配信は Slack の権限、チャンネルへの参加、接続状態に依存します。

**LangBot の更新だけでは既存 Slack アプリの権限は更新されません。** アプリを作り直さず、次の設定を追加してください。

1. **OAuth & Permissions → Bot Token Scopes** で既存権限を維持し、`reactions:read` を追加します。`app_mentions:read`、`chat:write`、`channels:history`、`channels:read`、`groups:history`、`groups:read`、`im:history`、`im:read`、`im:write`、`mpim:history`、`mpim:read`、`users:read`、`files:read`、`files:write` を確認し、**Reinstall to Workspace** で再承認します。
2. **Event Subscriptions → Subscribe to bot events** に `app_mention`、`message.im`、`message.channels`、`message.groups`、`message.mpim`、`reaction_added`、`reaction_removed`、`member_joined_channel`、`member_left_channel`、`channel_rename`、`group_rename`、`channel_archive`、`channel_unarchive`、`group_archive`、`group_unarchive`、`app_home_opened`、`app_uninstalled`、`tokens_revoked` を設定します。編集・削除とトピック・用途変更はメッセージのサブタイプであり、個別の購読は不要です。
3. **Interactivity & Shortcuts** を有効にします。Webhook の **Request URL** はイベント購読と同じ LangBot `/bots/<ボット UUID>` を指定します。Socket Mode では公開インタラクション URL は不要です。
4. Slack の設定を保存し、LangBot のイベントルートを設定します。再インストールで Bot Token が変わった場合は更新してボットを保存してください。

各フィールドは [Slack App Manifest リファレンス](https://docs.slack.dev/reference/app-manifest/)を参照してください。

## 標準メッセージ API でスレッドを操作する

`send_message`、`reply_message` と標準メッセージコンポーネントを使用します。

- `send_message` が返す `MessageResult.message_id` は、最初に送信したメッセージの Slack `ts` です。テキストの後にファイルを送信する場合も同様です。この ID を保存して、そのメッセージの下にスレッドを作成できます。
- 送信チェーンに `Quote(id=message_id, origin=MessageChain([]))` を含めると、テキストとファイルをそのスレッドへ送信します。空でない ID を持つ最初の Quote が優先され、`reply_message` の元のスレッドや `quote_origin` の指定よりも優先します。origin の内容は送信しません。明示的な Quote ID がなければ、既存の送信・返信動作を維持します。
- 受信したチャンネルのスレッド返信には `Quote(id=thread_ts, group_id=channel, target_id=channel, origin=MessageChain([]))` が含まれます。現在のメッセージ ID は `Source.id` に残ります。スレッドの親メッセージとスレッド外のメッセージにはこの Quote は付きません。プラグインは別のコンテキスト照会なしで親メッセージ ID を取得できます。

## 手動設定（Webhook）

以下の画像は基本的な会話設定です。権限、イベント購読、インタラクションの完全な設定は、上の「イベント、インタラクション、既存アプリの更新」の最新リストを使用してください。

以下は手動 Webhook 設定です。手動で Socket Mode を使う場合は Slack 側で有効にし、Bot Token と App-Level Token を入力して `app_mention` と `message.im` を購読します。イベント Request URL は不要です。

### ボットの作成

[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:
>
> Webhook には公開 HTTPS URL が必要なため、まずドキュメント [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 の公式 [BotFather](https://t.me/BotFather) を開き、`/newbot` を送信します。名前と、末尾が `bot` のユーザー名を設定してください。発行された Token は秘密に保ち、グループやスクリーンショットに含めないでください。

この手順は LangBot 4.11 の新しい Telegram アダプター（内部名 `telegram-omni`）向けです。非推奨の旧アダプターは選択しないでください。

## 設定して有効にする

1. LangBot で利用可能なモデルプロバイダーとモデルを設定し、Pipeline、Agent、またはプラグインプロセッサーを作成します。
2. 「ボット」で新規作成し、Telegram を選択して Token を入力します。
3. `message.received` にメッセージプロセッサーを割り当てます。Pipeline は会話フロー、Agent はイベントとツールによる処理に適しています。プラグインは独立してイベントを購読することもできます。
4. 必要に応じて Markdown とストリーミングを有効にし、ボットを有効化して保存します。割り当ての変更後も保存が必要です。
5. Telegram のプライベートチャットで **Start** を押してテストメッセージを送信します。LangBot の実行記録でも状態と返信ツールの結果を確認してください。

アダプターはロングポーリングを使用するため、LangBot から `api.telegram.org` への接続が必要です。受信用の Webhook を外部公開する必要はありません。同じ Token を複数のポーリングインスタンスで同時に使用しないでください。

### プロセッサーを選ぶ

| 方式       | 設定と確認                                                                                         |
| -------- | --------------------------------------------------------------------------------------------- |
| Pipeline | モデルと起動条件を設定します。グループのメンションやプレフィックスの条件も満たす必要があります。ストリーミング対応プロセッサーでは Telegram のメッセージを段階的に更新できます。 |
| Agent    | モデル、指示、イベントツールを設定します。`event_reply` などの送信ツールを使うよう指示してください。モデルが文章を生成しただけでは Telegram に届きません。     |
| プラグイン    | プロセッサーをインストール・設定し、ボットに割り当てて保存します。独立購読とメインプロセッサーは並行して動くため、同じメッセージに二つの返信が返る場合があります。             |

添付ファイルを扱う場合はプロセッサーの Box を有効にし、サンドボックスツールと添付送信機能を使用します。Box が正常に動作していることを確認してください。外部のファイルシステム MCP と Box は別のファイルシステムです。画像の理解には画像入力に対応したモデルも必要です。

ストリーミング設定を有効にしても、すべてのツール呼び出しが逐次表示になるわけではありません。Agent の `event_reply` は完成したメッセージを送信します。プラグインのストリーミングは実装によります。Telegram の実際の表示と実行ログをそれぞれ確認してください。

## プライベートチャットとグループ

プライベートチャットでは先に **Start** を押します。グループではテスト用グループにボットを追加し、ボット宛てコマンドやボットへの返信など、プロセッサーの起動条件に合わせて送信します。

すべてのグループ利用で **Privacy Mode** を無効にする必要はありません。Telegram は宛先付きコマンド、返信、管理者ボット、通常のグループメッセージで配信条件が異なります。通常のメッセージも受信するには、BotFather でプライバシーモードを変更して必要に応じて再追加するか、用途に応じた管理者権限を付与します。[Telegram の公式説明](https://core.telegram.org/bots/features#privacy-mode)も参照してください。

メンバー状態やリアクションの更新には、その更新種別に対する Telegram の管理者要件を満たす必要があります。必要な権限だけを付与し、受信のためだけに削除・メンバー制限・管理者追加などをすべて有効にしないでください。Telegram の配信条件と LangBot の起動条件の両方が適用されます。

通常のグループをスーパーグループに変更すると ID が変わります。ログの Bot API グループ ID は Telegram Web の URL に含まれる ID とも異なる場合があります。URL から ID を組み立てないでください。

## 画像・ファイル・ストリーミング

画像やファイルはメッセージの添付としてプロセッサーに渡されます。質問を明記した画像と内容を検証できるテキストファイルで確認し、「送信しました」という文章だけでなく、実際に返された添付を確認してください。

ストリーミングの文章は Telegram メッセージを更新して表示し、添付は完了時に別途送信します。生成ファイルは添付出力機能で送信し、サンドボックスのパスだけを返さないようにします。Telegram が写真として処理できない画像は、元の内容を保持するためファイルとして再送信します。

![実際のグループでの検証：Agent が画像を認識し、ファイルを読み取り、ファイルと生成画像を返信します。](https://langbot.app/docs/images/telegram/agent-group-media.jpg)

## その他のイベント

必要なイベントに Agent またはプラグインプロセッサーを割り当てます。Pipeline は主にメッセージフロー用です。非メッセージイベントをすべて通常チャットとして扱わないでください。

| イベント                     | 発生条件・意味                                              |
| ------------------------ | ---------------------------------------------------- |
| `message.received`       | プライベートまたはグループのメッセージ。対応する添付を含みます。                     |
| `message.edited`         | 送信済みメッセージの編集。                                        |
| `message.reaction`       | リアクションの追加・削除。方向は `is_add`、削除した絵文字も `reaction` に残ります。 |
| `group.member_joined`    | メンバーの参加。                                             |
| `group.member_left`      | 退出または削除。`is_kicked` を確認します。                          |
| `group.member_banned`    | ミュートなどの権限制限。グループからの削除とは異なります。                        |
| `bot.invited_to_group`   | ボットの追加。                                              |
| `bot.removed_from_group` | ボットの削除。直前に制限状態だった場合も含みます。                            |
| `bot.muted`              | メッセージ送信権限を失った状態。無期限の場合は `duration: null`。            |
| `bot.unmuted`            | 送信権限の回復。その他の制限が残っていても発生します。                          |
| `platform.specific`      | 権限変更やコールバックなど。`action` と `data` を確認します。              |

まず記録のみ行うプラグインで受信を確認してから、返信や管理操作を追加してください。ミュート・削除されたボットはイベントを受け取れても、元のグループに返信できない場合があります。受信成功と送信権限は別々に確認します。

## トラブルシューティング

- **返信がない**：有効化状態、保存済みの割り当て、Start、プライバシーモード、起動条件、実行記録を順に確認します。
- **返信は届いたが実行は失敗**：実行記録を開いてツールの戻り値を確認します。Telegram に文章があるだけでは処理全体の成功とは判断できません。
- **モデルのエラーやタイムアウト**：プロバイダーとモデルを、Telegram の配信問題とは分けて確認します。
- **パスだけが返る**：Box、ツール権限、実際の添付送信ツール呼び出しを確認します。
- **返信が重複する**：メイン処理と独立購読の重複、複数のポーリングインスタンスを確認します。
- **リアクション・メンバーイベントが来ない**：管理者状態とイベントの割り当てを確認します。実メンバーに影響しない専用グループで試してください。

---

# ウェブページボット

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)

「会社作成」をクリックし、作成したボットを選択し、チャットインターフェイスに入ります。

同様に、ボットをグループチャットに招待したい場合は、グループチャットでメンバーを追加ボタンをクリックし、そこからボットを追加します。

### オーケストレーションイベント

新しい WeCom AI Bot アダプターは、WebSocket と Webhook の両モードで以下の業務イベントを提供します。ボットのイベントルーティングで、イベントごとに処理器を選択できます。

| イベント                           | 用途とデータ                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| `message.received`             | ユーザーのメッセージを受信し、会話やタスクを処理します。                                                                      |
| `wecombot.enter_chat`          | ユーザーがボットのチャットを開いた際に、歓迎や案内のフローを開始します。ユーザー、チャット ID、元のイベントデータを含みます。                                  |
| `wecombot.template_card_event` | カードのクリックや送信を処理し、`task_id`、`event_key`、`selected_items` に応じて分岐できます。カード種別、ユーザー、チャット、元のイベントデータを含みます。 |
| `feedback.received`            | ボットの回答に対するフィードバックを収集します。                                                                          |

チャットへの参加イベントは WeCom から送信され、友だち追加を意味しません。歓迎メッセージはプラットフォームの 5 秒以内の応答期限に収めてください。短い固定テキストを推奨します。イベントへのテキスト返信には専用の歓迎 API を使用し、期限切れは明示的にエラーになります。時間のかかるモデル呼び出しによる歓迎文の生成は避けてください。

LangBot のインタラクションフォームと Dify フォームは既存のコールバック処理を使用し、カードの業務イベントを重複して起動しません。接続、認証、再接続などの低レベル状態はオーケストレーションイベントに含めません。

### 効果の画像

![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 を入力して再起動します。

## 問い合わせリンクと QR コードを取得する

コールバックの設定後、WeChat ユーザーが問い合わせを開始するためのリンクまたは QR コードを取得します。

1. [WeChat カスタマーサービス管理画面](https://kf.weixin.qq.com/kf)に戻り、`客服帐号`（カスタマーサービスアカウント）から、LangBot に接続するアカウントを作成または選択します。
2. アカウントの接続ページを開き、`在微信外App/网页中接入`（WeChat 外のアプリ・Web ページに接続）までスクロールして、`去接入` をクリックします。

![WeChat 外のアプリ・Web ページへの接続入口](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/customer-service-entry.png)

3. 接続ページ上部の対象アカウントで、`复制链接` をクリックすると問い合わせリンクをコピーでき、`生成二维码` をクリックすると QR コードを表示できます。

![問い合わせリンクのコピーと QR コードの生成](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/customer-service-link.png)

> info:
>
> スクリーンショットのリンクは例です。自分のアカウントで生成したリンクまたは QR コードを使用してください。Webhook コールバック URL は LangBot へのイベント通知用で、問い合わせリンクと QR コードはユーザーが会話を開始するためのものです。

## QR コードで動作を確認する

1. LangBot のボットを有効にし、イベントルーティングで「メッセージ受信」イベントを使用するプロセッサーに割り当てます。
2. 通常の WeChat で生成した QR コードを読み取り、カスタマーサービスの会話を開いてメッセージを送信します。
3. LangBot のボットログ、セッション監視、対象プロセッサーの実行ログで受信と処理を確認し、WeChat に返信が届くことを確認します。

QR コードで動作を確認するだけなら、接続ページ下部のアプリ連携を設定する必要はありません。

## ルーティングできるイベント

ボットのイベントルーティングで、イベントごとにプロセッサーを選択できます。通常のメッセージにはパイプラインまたは Agent、それ以外には対象イベントに対応した Agent またはプラグインプロセッサーを使用します。

| イベント               | イベントタイプ                                     |
| ------------------ | ------------------------------------------- |
| メッセージ受信            | `message.received`                          |
| 顧客または担当者によるメッセージ撤回 | `message.deleted`                           |
| 顧客がリンクから会話に参加      | `wecomcs.enter_session`                     |
| メッセージ送信失敗          | `wecomcs.msg_send_fail`                     |
| 担当者の受付状態変更         | `wecomcs.servicer_status_change`            |
| 会話の受付、転送、終了、再開     | `wecomcs.session_status_change`             |
| 顧客メッセージの受信拒否設定変更   | `wecomcs.reject_customer_msg_switch_change` |

撤回イベントには元のメッセージ ID、操作者、チャット ID が含まれます。カスタマーサービス固有のイベントにはアカウント、顧客、`welcome_code`、`fail_type`、`change_type` などの関連フィールドが含まれます。未知のイベントは `platform.specific` として元のデータを保持します。

会話への参加イベントはリンクから入った場合に発生し、既存のチャット一覧から開いても発生しません。歓迎メッセージを送るにはプロセッサーの処理を設定してください。イベントの受信だけでは送信されません。

### 返信期限と歓迎メッセージ

- 通常の返信には顧客からのメッセージが必要で、48 時間以内に送信する必要があります。会話への参加だけではこの条件を満たしません。エラー `95002` は送信期限の条件を満たしていないことを示します。
- 参加イベントでの Agent の `event_reply` は、専用のイベント応答 API と `welcome_code` を使います。このコードは歓迎メッセージの条件を満たす場合のみ提供され、送信できるのは 1 件、有効期限は 20 秒です。時間のかかるモデル生成より、すぐに送信できる固定文面を推奨します。
- 会話状態変更イベントの `event_reply` は `msg_code` を使用し、有効期限と現在の会話状態による制限を受けます。現在のイベント返信はテキストに対応しています。コードがない場合、期限切れの場合、使用済みの場合は再送できません。古いイベントを再実行しても有効期限は延長されません。

詳細は公式の[メッセージ送信](https://developer.work.weixin.qq.com/document/path/94677)と[イベント応答送信](https://developer.work.weixin.qq.com/document/path/95122)を参照してください。

---

# 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 統合モード

新しい公式アカウントアダプターでは、次の 3 種類を選択できます。変更後はボット設定を保存してください。既存の設定は自動変更されず、デフォルトは `drop` です。旧版アダプターには `auto` はありません。

| モード           | 返信の仕組み                                                                             |
| ------------- | ---------------------------------------------------------------------------------- |
| `auto`        | 処理中のメッセージを返し、バックグラウンドで回答を生成します。カスタマーサービス API で送信し、利用制限がある場合は次のメッセージで受け取る方式に切り替えます。 |
| `passive`     | 処理中のメッセージを返し、回答を保存します。ユーザーが再度メッセージを送ると受け取れます。カスタマーサービス API は呼び出しません。               |
| `drop`（デフォルト） | 現在のコールバック内で返信します。5 秒以内に完了する処理向けです。カスタマーサービス API や受け取り方式への切り替えは使用しません。              |

### auto の判定方法

`auto` は認証状態を事前に取得しません。処理器が回答を送信する際にカスタマーサービス API を呼び出し、その結果で判定します。

- 成功した場合、追加メッセージを送らずに回答を受信できます。
- 権限不足（`48001`）、返信期限切れ（`45015`）、送信枠の上限（`45047`）、受信者が未フォロー（`43004`）の場合、回答を保存し、次のメッセージで受け取れるようにします。
- 認証情報、IP ホワイトリスト、ネットワークなどのその他のエラーは記録されます。一律に権限不足として扱うことはありません。

判定は返信ごとに行います。処理中の表示は回答の生成完了を意味しません。回答が届かない場合は処理器の実行ログを確認してください。

### 認証と返信期限

コールバックには認証の有無にかかわらず **5 秒以内**に応答する必要があります。`drop` はこの仕組みを使います。WeChat の再試行を安定した 15 秒の生成時間として利用することはできません。[公式の受動返信ドキュメント](https://developers.weixin.qq.com/doc/service/guide/product/message/Passive_user_reply_message.html)を参照してください。

カスタマーサービス API ではコールバック終了後も返信できます。現在の公式仕様では、公式アカウントとサービスアカウントは企業主体の認証が必要です。本人確認だけでこの権限が付与されるわけではありません。利用可否は実際の権限と API の応答で決まります。

| ユーザーの操作                           | 送信可能数 | 有効期限  |
| --------------------------------- | ----- | ----- |
| メッセージを送信                          | 5 件   | 48 時間 |
| 対象のカスタムメニューをクリック、フォロー、QR コードをスキャン | 3 件   | 1 分   |

これは AI の生成タイムアウトではなく、プラットフォームの制限です。最新の条件は[公式のカスタマーサービス API ドキュメント](https://developers.weixin.qq.com/doc/service/api/customer/message/api_sendcustommessage)を確認してください。

### 回答の受け取り

`passive` または `auto` の切り替え後は、次のメッセージは前の回答の受け取りに使われ、**同時に新しい質問として処理されません**。回答が未完成なら処理中の表示を再度返します。回答を受け取ってから新しい質問を送ってください。

`LoadingMessage` は `auto` と `passive` に適用され、`drop` には適用されません。`auto` では「処理中です。回答が届かない場合は、しばらくしてから任意のメッセージを送って受け取ってください」などを設定できます。空欄の場合は表示用のメッセージを送らずにコールバックの受信を確認します。

回答はメモリ上に保存され、LangBot の再起動やボット設定の再読み込みで消去されます。どのモードでも WeChat の内容や文字数の制限が適用されます。

イベントルーティングで処理器を接続してください。モードは Agent のすべてのテキスト出力を自動送信するものではありません。Agent には現在の会話への返信ツールを許可して使用するよう指示してください。プラグイン処理器は返信 API を呼び出す必要があります。

## ボットの作成

[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」で、上記の比較を参考に `auto`、`passive`、`drop` を選択してください。デフォルトは `drop` です。

「LoadingMessage」は `auto` と `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`          | オン       | 読み書き   | 既定制限 | 既定の選択、API アクセスや依存関係のダウンロード     |
| `offline`          | オフ       | 読み書き   | 既定制限 | ネットワーク不要のタスク、従来の default 設定を維持 |
| `offline_readonly` | オフ       | 読み取り専用 | より厳格 | 信頼できないファイルの読み込み                |
| `network_basic`    | 基本ネットワーク | 読み書き   | 既定制限 | API アクセス、依存関係インストール            |
| `network_extended` | フルネットワーク | 読み書き   | 緩和   | 開発、デバッグ、複雑なタスク                 |

`network_basic` は互換性のために維持され、設定は `default` と同じです。

最小権限を優先：ネットワークが不要なら `offline` または `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 4.11：从消息回复走向事件驱动智能体](https://langbot.app/docs/zh/articles/langbot-v411-event-driven-agents.md) — 2026-10-15
- [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

## 教程与集成

- [在飞书里查询 GitHub 更新：Dify Workflow + GPT-6 Astra + LangBot 实战](https://langbot.app/docs/zh/articles/dify-langbot-github-release-briefing.md) — 2026-09-16
- [让客服问题走对分支：Dify + LangBot 钉钉、企业微信机器人实战](https://langbot.app/docs/zh/articles/dify-langbot-support-triage.md) — 2026-09-16
- [把群公告交给 Dify：用 GPT-6 Astra 和 LangBot 搭建 QQ、飞书写作助手](https://langbot.app/docs/zh/articles/dify-langbot-writing-assistant.md) — 2026-09-16
- [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** 作为 Runner：

![Select Dify Runner](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)

---

# 在飞书里查询 GitHub 更新：Dify Workflow + GPT-6 Astra + LangBot 实战

Source: https://langbot.app/docs/zh/articles/dify-langbot-github-release-briefing

让 Dify 实时请求 GitHub API，代码节点提取版本信息，GPT-6 Astra 生成有来源的简报，再由 LangBot 返回。详解 Workflow 输入、HTTP、Code 和 summary 输出。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/dify-langbot-github-release-briefing).

发布于 2026-09-16 · 作者：LangBot Team

项目更新一多，群里的问题也很固定：“最新版本是什么？”“这次有哪些变化值得看？”直接让模型凭记忆回答，碰上刚发布的版本就不靠谱。

我们做了一个按需查询的 GitHub 简报助手：用户发消息后，Dify 真正请求 GitHub API，代码节点抽取发布信息，GPT-6 Astra 写成简短摘要，再由 LangBot 返回。下面用 LangBot 自己的公开仓库做例子；同样的方法也可以用在你关注的其他公开项目。

![真实 API 数据生成的中文简报，保留版本、时间与 GitHub 原文链接。](https://langbot.app/docs/images/articles/source/images/dify-langbot/082-release-chinese-reply-detail.png)

*真实 API 数据生成的中文简报，保留版本、时间与 GitHub 原文链接。*

## 先把 Dify 和 LangBot 跑起来

先安装 Docker Compose 和 Git，再分别按 [Dify Docker Compose 部署文档](https://docs.dify.ai/en/self-host/deploy/quick-start/docker-compose) 与 [LangBot Docker 部署文档](https://langbot.app/docs/en/deploy/langbot/docker.md) 启动两个服务。Dify 的基础步骤是克隆仓库、进入 `docker` 目录、将 `.env.example` 复制为 `.env`，再启动 Compose；LangBot 的文档提供完整的镜像和插件运行时配置。

本文截图来自 **Dify 1.17.1、LangBot v4.10.11** 的本机环境。我们把浏览器端口分别映射为 `8088` 和 `5368`；这是演示环境的自定义映射，官方默认部署通常分别使用 `80` 和 `5300`。如果沿用官方默认值，就打开 `http://localhost` 和 `http://localhost:5300`，不用为了对齐截图而改端口。各自创建管理员账户，并把界面语言设为 **English**。

![本地 Dify 的首次初始化页面。](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-dify-install.png)

*本地 Dify 的首次初始化页面。*

![本地 LangBot 的首次初始化页面。](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-langbot-install.png)

*本地 LangBot 的首次初始化页面。*

接入时最重要的是 **LangBot 容器能访问 Dify**。本次两个服务加入同一个 Docker 网络，因此 Runner 的 Base URL 使用 `http://nginx/v1`，其中 `nginx` 是 Dify 的服务名。你可以在两个 Compose 配置中为 Dify 的 `nginx` 和 LangBot 服务加入同一个外部网络；如果分别部署在不同主机，则填写 LangBot 能访问的 Dify HTTPS 地址并加上 `/v1`。下文表格里的 `http://nginx/v1` 都指本次共享网络环境，不能直接套到所有部署。容器内的 `localhost` 指向容器自己。

## 在 Dify 中配置 GPT-6 Astra

进入 **Integrations → Model Provider**，安装官方 **OpenAI-API-compatible** 插件，再点 **Add Model**。本次使用的插件版本是 0.0.66。

| 字段                                              | 本次设置                            |
| ----------------------------------------------- | ------------------------------- |
| Model Name / model name for API endpoint        | `gpt-6-astra`                   |
| Model Type / Completion mode                    | LLM / Chat                      |
| Model display name                              | GPT-6 Astra                     |
| API Base URL                                    | 你自己的 OpenAI 兼容服务地址，通常以 `/v1` 结尾 |
| API Key                                         | 你的模型服务密钥                        |
| API Type                                        | Chat Completions API            |
| Model context size / Upper bound for max tokens | 本教程设为 32768 / 4096              |

最后一行是这次演示的工作上限，不是对 Astra 完整规格的声明。保存时让 Dify 做连接验证，成功后再建应用。截图中的网关只是本次测试环境，实际使用时换成你自己的服务。模型参数和可用接口以所选服务为准。模型名称以你选用的服务实际提供的标识为准，本文保留本次实测的 `gpt-6-astra`。

![添加自定义模型。API Key 在截图前保持为空，实际运行时已配置。](https://langbot.app/docs/images/articles/source/images/dify-langbot/014-dify-astra-model-settings.png)

*添加自定义模型。API Key 在截图前保持为空，实际运行时已配置。*

## 用 Workflow，把数据获取放在模型之前

在 Dify 新建 **Workflow**，命名 `Astra Release Briefing`。这次不是 Chatflow，因为每条请求都可以独立查询最新发布记录。

流程是：

`User Request → HTTP Request → Code → LLM → End`

![实际运行的 GitHub 简报工作流。](https://langbot.app/docs/images/articles/source/images/dify-langbot/045-release-workflow-overview.png)

*实际运行的 GitHub 简报工作流。*

### 1. 用户输入字段要与 LangBot 对上

在 Start / User Request 节点添加必填段落字段：

```text
langbot_user_message_text
```

LangBot 的 Dify Workflow Runner 会把当前消息文本放到这个字段中。不要随手改成 `question` 或 `prompt`，否则你在 Dify 手动测试能跑，接入 LangBot 时却可能缺少必填参数。

![工作流运行表单中的输入变量名称。](https://langbot.app/docs/images/articles/source/images/dify-langbot/049-release-workflow-input.png)

*工作流运行表单中的输入变量名称。*

### 2. HTTP 节点读取 GitHub

方法选 GET，地址：

```text
https://api.github.com/repos/langbot-app/LangBot/releases/latest
```

请求头加上 `Accept: application/vnd.github+json` 和 `User-Agent: LangBot-Dify-Tutorial`。这是读取公开发布记录，本例不需要 GitHub Token。保留 SSL 验证，按实际网络设置连接和读取超时。

![HTTP 节点直接查询 GitHub Releases API。](https://langbot.app/docs/images/articles/source/images/dify-langbot/046-release-http-request-settings.png)

*HTTP 节点直接查询 GitHub Releases API。*

### 3. 代码节点缩小传给模型的数据

把 HTTP 的 `body` 和 `status_code` 分别传给代码节点。核心逻辑如下，完整代码在 DSL 中：

```python
import json

def main(body: str, status_code: int) -> dict:
    if status_code != 200:
        return {"release": json.dumps({"error": f"GitHub HTTP {status_code}"})}
    data = json.loads(body)
    return {"release": json.dumps({
        "repository": "langbot-app/LangBot",
        "tag": data.get("tag_name"),
        "published_at": data.get("published_at"),
        "url": data.get("html_url"),
        "notes": (data.get("body") or "")[:14000],
    }, ensure_ascii=False)}
```

保留标签、发布时间、链接和发布说明就够了。没有必要把作者头像、各种 API URL 等字段全部塞进模型上下文。这里的代码只做提取，没有修改 GitHub 数据。

![代码节点把原始 JSON 转成精简的发布资料。](https://langbot.app/docs/images/articles/source/images/dify-langbot/047-release-code-extraction-node.png)

*代码节点把原始 JSON 转成精简的发布资料。*

### 4. LLM 写摘要，End 返回 summary

LLM 选择 GPT-6 Astra。提示词要求：用用户的语言回答，包含仓库、版本、发布时间、三个实用变化和原文链接；只使用 API 返回的资料，出错时说明查询失败。把用户输入和代码节点的 `release` 都放进 User 消息。

在 End 节点，把 LLM 的 `text` 映射到名为 **`summary`** 的输出。这个名字同样是接入约定，不能只看着节点连线完整就忽略它。

![End 节点把模型文本返回为 summary。](https://langbot.app/docs/images/articles/source/images/dify-langbot/054-release-summary-output-verified.png)

*End 节点把模型文本返回为 summary。*

## 先核对数据，再看摘要

我分别运行了英文和中文请求。两次都读取到 `v4.10.11`，发布时间为 2026-09-12 04:55:58 UTC，并附上对应的 GitHub Release 链接。摘要提到了知识库导入、监控统计和平台兼容性变化。

![英文请求的真实运行结果。](https://langbot.app/docs/images/articles/source/images/dify-langbot/056-release-english-live-briefing.png)

*英文请求的真实运行结果。*

![同一条工作流根据用户语言生成中文简报。](https://langbot.app/docs/images/articles/source/images/dify-langbot/075-release-chinese-live-briefing.png)

*同一条工作流根据用户语言生成中文简报。*

“最新”会随仓库发布变化，复现时不必追求和截图相同的版本号。应检查它是否与 API 当前返回的 `tag_name`、`published_at`、`html_url` 对得上。

## 用 LangBot 接住消息入口

在 Dify 点 **Publish**，发布当前版本。然后进入 **Access Point → Backend Service API → API Key**，创建这个应用自己的密钥。

打开 LangBot，点 **Create Pipelines**，命名为 `Astra Release Briefing`。进入 **Configuration → AI**：

| 字段       | 值                 |
| -------- | ----------------- |
| Runner   | Dify Service API  |
| Base URL | `http://nginx/v1` |
| App Type | Workflow          |
| API Key  | 刚创建的 Dify 应用密钥    |

这里粘贴的是 **Dify 应用密钥**，不是前面配置 Astra 的模型密钥。一个负责调用应用，一个负责调用模型，别混用。保存后打开 **Debug Chat**，先验证整条调用链，再接平台。

![LangBot 的 Dify Runner 配置；截图时尚未填入应用密钥。](https://langbot.app/docs/images/articles/source/images/dify-langbot/078-langbot-release-workflow-settings.png)

*LangBot 的 Dify Runner 配置；截图时尚未填入应用密钥。*

## 工作流接进聊天之后

我从 LangBot 发了英文查询，收到完整简报和来源链接。中文查询曾遇到一次上游 SSL 连接临时中断，重试后成功；这也提醒我们，截图里的成功运行不代表外部 API 永远可用。

![LangBot 收到工作流的英文 summary 输出。](https://langbot.app/docs/images/articles/source/images/dify-langbot/079-langbot-release-english-roundtrip.png)

*LangBot 收到工作流的英文 summary 输出。*

![中文重试成功后的简报内容。](https://langbot.app/docs/images/articles/source/images/dify-langbot/082-release-chinese-reply-detail.png)

*中文重试成功后的简报内容。*

如果接到飞书项目群，建议先设置提及触发。需要时问一次，就查一次，避免机器人反复刷屏。本文做的是按需查询；定时推送需要额外增加调度与发送逻辑。

扩展到其他仓库时，可以先复制应用并替换固定 API URL。等规则稳定后再加入仓库参数、输入校验和限流，不要让任意用户输入直接变成不受限制的请求地址。

## 接到飞书、钉钉、企业微信，以及其他消息平台

在 LangBot 点 **Create Bots**，选择适配器，填写平台提供的凭据。创建后把机器人绑定到刚才的流水线；检查 Trigger 中的私聊、群聊和提及规则，再按平台要求发布或邀请机器人。

本次实测覆盖 **LangBot → Dify → GPT-6 Astra → LangBot 回复**。以下是实际界面核对过的接入方式，平台账户与群聊没有在本次演示中授权连接。

| 入口              | 配置方式                                                                                                            |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| 飞书 / Lark       | 选 Lark；可扫码创建应用，也可手填 App ID、App Secret、与平台一致的 Bot Name。中国平台域名选 Feishu，默认使用长连接；开发者后台配置消息权限、事件并发布应用。               |
| 钉钉              | 选 DingTalk；扫码或填写 Client ID、Client Secret。Robot Code 需从开发者后台复制；按文档配置 Stream 接收消息、机器人名称和需要的卡片模板。                  |
| 企业微信智能机器人       | 选 WeComBot；长连接用 BotId、Secret，填写机器人名称。Webhook 模式另配 Corpid、Token、EncodingAESKey。两套模式不要混填。                         |
| 企业微信内部应用 / 微信客服 | 分别选 WeCom 或 WeComCustomerService，按各自后台填写企业与应用凭据、Token、EncodingAESKey，完成 HTTPS 回调和可信 IP 配置。内部应用不能直接当群机器人使用。      |
| 微信个人会话          | 选 OpenClaw WeChat，通过界面的二维码授权登录，按适配器说明接入。                                                                        |
| 微信公众号           | 选 Official Account，填写 App ID、App Secret、Token、EncodingAESKey，配置公网回调与 IP 白名单。根据接口限制选择回复模式；耗时较长时可能需要用户再发一条消息取回结果。 |
| QQ：OneBot v11   | 运行兼容 OneBot v11 的协议端，配置反向 WebSocket 到 LangBot 的监听端口，两侧 Access Token 保持一致；演示环境的 Compose 把主机 2288 映射到容器 2280。     |
| QQ 官方机器人        | 选 QQ Official API；可扫码绑定或填写 App ID、Secret。当前界面说明 Token 可留空；接收模式、沙箱范围、发布审核以 QQ 官方及适配器文档为准。                        |

![钉钉适配器的凭据、Robot Code 与卡片配置。](https://langbot.app/docs/images/articles/source/images/dify-langbot/063-platform-dingtalk-fields.png)

*钉钉适配器的凭据、Robot Code 与卡片配置。*

![企业微信智能机器人的长连接与 Webhook 配置项。](https://langbot.app/docs/images/articles/source/images/dify-langbot/064-platform-wecombot-fields.png)

*企业微信智能机器人的长连接与 Webhook 配置项。*

LangBot 的适配器列表还包括 Discord、Slack、Telegram、LINE、Mattermost、Matrix、KOOK、Satori、HTTP Bot、Page Bot 和 WeChatPad。每种适配器需要的权限、回调和协议不同，不是填一个通用 Token 就全部接通。完整入口见 [LangBot 平台文档](https://langbot.app/docs/zh/usage/platforms/readme.md)。

如果只是想先模拟 QQ 消息，可以使用 matcha 之类的 OneBot 测试端；本文展示的对话来自 LangBot 自带 Debug Chat，没有把模拟对话当作真实群消息。

## 几个容易卡住的地方

遇到问题先按链路定位：Dify 预览能否回复、应用是否已 Publish、LangBot 的 Base URL 是否包含 `/v1`、应用类型是否正确，最后才看平台事件是否到达。如果改过 Dify 服务密码，Redis 与 Celery、Sandbox 与代码执行客户端的配置必须成对修改。

本机部署还遇到过代理软件返回虚拟 DNS 地址，导致 Dify 的 SSRF 代理拒绝插件下载。修好 DNS 后恢复，没必要关掉证书校验或内网访问保护。一次外部 API 的临时失败也不能当作模型或平台已经接通的证明，重试后仍应检查运行记录。

项目入口：[LangBot](https://github.com/langbot-app/LangBot) 和 [Dify](https://github.com/langgenius/dify)。截图和测试日期为 2026 年 9 月 16 日，后续版本的菜单名称可能会变化。

## 继续阅读

- [把群公告交给 Dify：用 GPT-6 Astra 和 LangBot 搭建 QQ、飞书写作助手](https://langbot.app/zh/blog/dify-langbot-writing-assistant)
- [让客服问题走对分支：Dify + LangBot 钉钉、企业微信机器人实战](https://langbot.app/zh/blog/dify-langbot-support-triage)

---

# 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)

---

# 让客服问题走对分支：Dify + LangBot 钉钉、企业微信机器人实战

Source: https://langbot.app/docs/zh/articles/dify-langbot-support-triage

用 GPT-6 Astra 和 Dify Question Classifier 区分账户、产品与人工复核请求，再接入 LangBot。三条分支逐一测试，说明回复规则与真实交接的边界。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/dify-langbot-support-triage).

发布于 2026-09-16 · 作者：LangBot Team

把所有客服问题塞给同一段提示词，刚开始挺省事。后来你会发现，登录失败、功能咨询、退款投诉混在一起，机器人经常用同一种口气回复，还容易在不该承诺的地方说得太满。

这次我们把流程拆成三条：账户问题给排查步骤，产品问题给使用说明，需要授权的事情提示人工复核。Dify 的 Question Classifier 决定走哪条路，GPT-6 Astra 生成对应回复，LangBot 把同一个应用接到钉钉、企业微信或 QQ。

![实际部署的三分支客服 Chatflow。](https://langbot.app/docs/images/articles/source/images/dify-langbot/039-triage-three-branch-overview.png)

*实际部署的三分支客服 Chatflow。*

## 先把 Dify 和 LangBot 跑起来

先安装 Docker Compose 和 Git，再分别按 [Dify Docker Compose 部署文档](https://docs.dify.ai/en/self-host/deploy/quick-start/docker-compose) 与 [LangBot Docker 部署文档](https://langbot.app/docs/en/deploy/langbot/docker.md) 启动两个服务。Dify 的基础步骤是克隆仓库、进入 `docker` 目录、将 `.env.example` 复制为 `.env`，再启动 Compose；LangBot 的文档提供完整的镜像和插件运行时配置。

本文截图来自 **Dify 1.17.1、LangBot v4.10.11** 的本机环境。我们把浏览器端口分别映射为 `8088` 和 `5368`；这是演示环境的自定义映射，官方默认部署通常分别使用 `80` 和 `5300`。如果沿用官方默认值，就打开 `http://localhost` 和 `http://localhost:5300`，不用为了对齐截图而改端口。各自创建管理员账户，并把界面语言设为 **English**。

![本地 Dify 的首次初始化页面。](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-dify-install.png)

*本地 Dify 的首次初始化页面。*

![本地 LangBot 的首次初始化页面。](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-langbot-install.png)

*本地 LangBot 的首次初始化页面。*

接入时最重要的是 **LangBot 容器能访问 Dify**。本次两个服务加入同一个 Docker 网络，因此 Runner 的 Base URL 使用 `http://nginx/v1`，其中 `nginx` 是 Dify 的服务名。你可以在两个 Compose 配置中为 Dify 的 `nginx` 和 LangBot 服务加入同一个外部网络；如果分别部署在不同主机，则填写 LangBot 能访问的 Dify HTTPS 地址并加上 `/v1`。下文表格里的 `http://nginx/v1` 都指本次共享网络环境，不能直接套到所有部署。容器内的 `localhost` 指向容器自己。

## 在 Dify 中配置 GPT-6 Astra

进入 **Integrations → Model Provider**，安装官方 **OpenAI-API-compatible** 插件，再点 **Add Model**。本次使用的插件版本是 0.0.66。

| 字段                                              | 本次设置                            |
| ----------------------------------------------- | ------------------------------- |
| Model Name / model name for API endpoint        | `gpt-6-astra`                   |
| Model Type / Completion mode                    | LLM / Chat                      |
| Model display name                              | GPT-6 Astra                     |
| API Base URL                                    | 你自己的 OpenAI 兼容服务地址，通常以 `/v1` 结尾 |
| API Key                                         | 你的模型服务密钥                        |
| API Type                                        | Chat Completions API            |
| Model context size / Upper bound for max tokens | 本教程设为 32768 / 4096              |

最后一行是这次演示的工作上限，不是对 Astra 完整规格的声明。保存时让 Dify 做连接验证，成功后再建应用。截图中的网关只是本次测试环境，实际使用时换成你自己的服务。模型参数和可用接口以所选服务为准。模型名称以你选用的服务实际提供的标识为准，本文保留本次实测的 `gpt-6-astra`。

![添加自定义模型。API Key 在截图前保持为空，实际运行时已配置。](https://langbot.app/docs/images/articles/source/images/dify-langbot/014-dify-astra-model-settings.png)

*添加自定义模型。API Key 在截图前保持为空，实际运行时已配置。*

## 先定义三类问题，再画流程

演示产品是一个虚构的帮助台产品 Northstar Desk。本文用到的规则直接写在三个分支中，不依赖另一篇教程或预先存在的知识库。

| 分支      | 适合的问题                 | 回复任务                        |
| ------- | --------------------- | --------------------------- |
| Account | 登录、邀请链接、工作区访问         | 说明邀请有效 48 小时，指导所有者重新发送邀请    |
| Product | 导出工单、试用限制、基础设置        | 回答已给定的产品规则和操作路径             |
| Human   | 退款、收费、企业报价、投诉、混合不清的问题 | 说明需要人工决定，收集简短说明并给出联系支持团队的建议 |

第三条分支的作用是生成交接提示。本例没有连接工单系统，也不会真的通知客服，所以回复不能写“已转交”“退款已批准”。以后接入工单 API 时，再把真实执行结果接到这条分支。

## 在 Dify 创建分流 Chatflow

新建 **Chatflow**，名称为 `Astra Support Router`。从 User Input 连到 **Question Classifier**，模型选择 GPT-6 Astra，Query Variable 指向 `sys.query`。

添加三类，说明尽量写清楚范围：

```text
Account: login, invitation, password or workspace access
Product: usage, ticket export, setup and trial limits
Human: billing, refunds, enterprise pricing, angry complaints
or unclear mixed questions
```

![分类节点里的类别说明会直接影响路由结果。](https://langbot.app/docs/images/articles/source/images/dify-langbot/040-triage-classifier-settings.png)

*分类节点里的类别说明会直接影响路由结果。*

在 Advanced Setting 中补充一句：缺少关键信息、需要授权或者混合问题不明确时，选择 Human。分类器的三条出口分别连接一个 LLM 节点，再各自接 Answer。

三个 LLM 都选 GPT-6 Astra，用户消息引用 `sys.query`，但系统规则分别写：

- **Account Reply**：邀请链接有效 48 小时；请工作区所有者到 `Settings > Members` 重新发送。不要索要密码。其他账户问题先问一个澄清问题。
- **Product Reply**：所有者从 `Settings > Data > Export` 导出 CSV，链接保留 7 天；试用 14 天、5 名成员、2 个收件箱。规则没覆盖的内容直接说明。
- **Human Reply**：理解诉求，解释需要人工决定，请对方提供简短问题描述和非敏感参考信息，联系其支持团队。不要编造客服地址、承诺处理时效或声称已经执行。

共用规则只有几条：跟随用户语言、简短、不要重复冗长开场。把业务规则分在对应节点里，以后修改退款交接话术时，就不用担心顺便改坏登录帮助。

## 每个分支都要实际跑一次

我们在 Preview 中做了三组测试：

| 输入                                | 实际路径           | 结果                      |
| --------------------------------- | -------------- | ----------------------- |
| My invitation link expired...     | Account Output | 建议让所有者重新发邀请，说明 48 小时有效期 |
| How do I export tickets as a CSV? | Product Output | 返回导出路径和 7 天有效期          |
| 我对收费很不满意，要求退款，马上处理。               | Human Output   | 说明需人工审核，不声称退款已经执行       |

![账户问题走 Account 分支。](https://langbot.app/docs/images/articles/source/images/dify-langbot/041-triage-account-path-result.png)

*账户问题走 Account 分支。*

![产品问题走 Product 分支。](https://langbot.app/docs/images/articles/source/images/dify-langbot/043-triage-product-path-result.png)

*产品问题走 Product 分支。*

![退款诉求走 Human 分支，输出人工复核建议。](https://langbot.app/docs/images/articles/source/images/dify-langbot/050-triage-human-review-chinese.png)

*退款诉求走 Human 分支，输出人工复核建议。*

注意看预览里的 **Workflow Process succeeded** 和具体的 Output 名称。只读最后一段回答，容易错过“答得似乎没错，但实际上走错了分支”的问题。

## 用 LangBot 接住消息入口

在 Dify 点 **Publish**，发布当前版本。然后进入 **Access Point → Backend Service API → API Key**，创建这个应用自己的密钥。

打开 LangBot，点 **Create Pipelines**，命名为 `Astra Support Router`。进入 **Configuration → AI**：

| 字段       | 值                 |
| -------- | ----------------- |
| Runner   | Dify Service API  |
| Base URL | `http://nginx/v1` |
| App Type | Chat              |
| API Key  | 刚创建的 Dify 应用密钥    |

这里粘贴的是 **Dify 应用密钥**，不是前面配置 Astra 的模型密钥。一个负责调用应用，一个负责调用模型，别混用。保存后打开 **Debug Chat**，先验证整条调用链，再接平台。

![LangBot 的 Dify Runner 配置；截图时尚未填入应用密钥。](https://langbot.app/docs/images/articles/source/images/dify-langbot/053-langbot-triage-dify-settings.png)

*LangBot 的 Dify Runner 配置；截图时尚未填入应用密钥。*

## 在 LangBot 中验证分流仍然有效

我们先在 LangBot 问邀请链接失效，得到 `Settings > Members` 的建议；再用中文提出退款诉求，得到人工复核提示。Dify 的分类逻辑不用在 LangBot 里再写一遍。

![LangBot 中的账户问题回复。](https://langbot.app/docs/images/articles/source/images/dify-langbot/055-langbot-triage-account-english.png)

*LangBot 中的账户问题回复。*

![同一应用处理中文退款诉求，保持人工审核边界。](https://langbot.app/docs/images/articles/source/images/dify-langbot/076-langbot-triage-human-chinese.png)

*同一应用处理中文退款诉求，保持人工审核边界。*

上线前可以再加一小组混合问题：“无法登录，而且我要退款”“不知道该找谁”。如果这些问题总被分进 Product，先调整类别描述和分类指令，再考虑换模型。

这个方案最适合把重复支持工作先分清楚。接下来要做真实交接，就在 Human 分支调用已有工单或通知服务，并把成功、失败结果分别呈现给用户。不要把“生成一句交接话术”当成已经完成交接。

## 接到钉钉、企业微信、QQ，以及其他消息平台

在 LangBot 点 **Create Bots**，选择适配器，填写平台提供的凭据。创建后把机器人绑定到刚才的流水线；检查 Trigger 中的私聊、群聊和提及规则，再按平台要求发布或邀请机器人。

本次实测覆盖 **LangBot → Dify → GPT-6 Astra → LangBot 回复**。以下是实际界面核对过的接入方式，平台账户与群聊没有在本次演示中授权连接。

| 入口              | 配置方式                                                                                                            |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| 飞书 / Lark       | 选 Lark；可扫码创建应用，也可手填 App ID、App Secret、与平台一致的 Bot Name。中国平台域名选 Feishu，默认使用长连接；开发者后台配置消息权限、事件并发布应用。               |
| 钉钉              | 选 DingTalk；扫码或填写 Client ID、Client Secret。Robot Code 需从开发者后台复制；按文档配置 Stream 接收消息、机器人名称和需要的卡片模板。                  |
| 企业微信智能机器人       | 选 WeComBot；长连接用 BotId、Secret，填写机器人名称。Webhook 模式另配 Corpid、Token、EncodingAESKey。两套模式不要混填。                         |
| 企业微信内部应用 / 微信客服 | 分别选 WeCom 或 WeComCustomerService，按各自后台填写企业与应用凭据、Token、EncodingAESKey，完成 HTTPS 回调和可信 IP 配置。内部应用不能直接当群机器人使用。      |
| 微信个人会话          | 选 OpenClaw WeChat，通过界面的二维码授权登录，按适配器说明接入。                                                                        |
| 微信公众号           | 选 Official Account，填写 App ID、App Secret、Token、EncodingAESKey，配置公网回调与 IP 白名单。根据接口限制选择回复模式；耗时较长时可能需要用户再发一条消息取回结果。 |
| QQ：OneBot v11   | 运行兼容 OneBot v11 的协议端，配置反向 WebSocket 到 LangBot 的监听端口，两侧 Access Token 保持一致；演示环境的 Compose 把主机 2288 映射到容器 2280。     |
| QQ 官方机器人        | 选 QQ Official API；可扫码绑定或填写 App ID、Secret。当前界面说明 Token 可留空；接收模式、沙箱范围、发布审核以 QQ 官方及适配器文档为准。                        |

![钉钉适配器的凭据、Robot Code 与卡片配置。](https://langbot.app/docs/images/articles/source/images/dify-langbot/063-platform-dingtalk-fields.png)

*钉钉适配器的凭据、Robot Code 与卡片配置。*

![QQ 的 OneBot v11 方案需要反向 WebSocket 监听地址和端口。](https://langbot.app/docs/images/articles/source/images/dify-langbot/066-platform-onebot-v11-fields.png)

*QQ 的 OneBot v11 方案需要反向 WebSocket 监听地址和端口。*

LangBot 的适配器列表还包括 Discord、Slack、Telegram、LINE、Mattermost、Matrix、KOOK、Satori、HTTP Bot、Page Bot 和 WeChatPad。每种适配器需要的权限、回调和协议不同，不是填一个通用 Token 就全部接通。完整入口见 [LangBot 平台文档](https://langbot.app/docs/zh/usage/platforms/readme.md)。

如果只是想先模拟 QQ 消息，可以使用 matcha 之类的 OneBot 测试端；本文展示的对话来自 LangBot 自带 Debug Chat，没有把模拟对话当作真实群消息。

## 几个容易卡住的地方

遇到问题先按链路定位：Dify 预览能否回复、应用是否已 Publish、LangBot 的 Base URL 是否包含 `/v1`、应用类型是否正确，最后才看平台事件是否到达。如果改过 Dify 服务密码，Redis 与 Celery、Sandbox 与代码执行客户端的配置必须成对修改。

本机部署还遇到过代理软件返回虚拟 DNS 地址，导致 Dify 的 SSRF 代理拒绝插件下载。修好 DNS 后恢复，没必要关掉证书校验或内网访问保护。一次外部 API 的临时失败也不能当作模型或平台已经接通的证明，重试后仍应检查运行记录。

项目入口：[LangBot](https://github.com/langbot-app/LangBot) 和 [Dify](https://github.com/langgenius/dify)。截图和测试日期为 2026 年 9 月 16 日，后续版本的菜单名称可能会变化。

## 继续阅读

- [把群公告交给 Dify：用 GPT-6 Astra 和 LangBot 搭建 QQ、飞书写作助手](https://langbot.app/zh/blog/dify-langbot-writing-assistant)
- [在飞书里查询 GitHub 更新：Dify Workflow + GPT-6 Astra + LangBot 实战](https://langbot.app/zh/blog/dify-langbot-github-release-briefing)

---

# 把群公告交给 Dify：用 GPT-6 Astra 和 LangBot 搭建 QQ、飞书写作助手

Source: https://langbot.app/docs/zh/articles/dify-langbot-writing-assistant

从基础 Chatbot 开始，把零散信息变成群公告，再通过 LangBot 连续追问、压缩和翻译。含真实部署截图、提示词和 QQ、飞书接入说明。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/dify-langbot-writing-assistant).

发布于 2026-09-16 · 作者：LangBot Team

群里要发一条活动通知，手头往往只有几句零散信息：时间、地点、报名方式，还得再花几分钟调整口吻。真正烦的不是写第一版，而是“短一点”“别那么正式”“换成企微群通知”这几轮来回。

这次我们把这件事做成了一个聊天助手：Dify 管提示词和会话，GPT-6 Astra 负责改写，LangBot 负责把入口放到平时就在用的消息平台里。下面从部署开始，做一个可以继续追问和改稿的应用。

![实际链路：在 LangBot 里把英文提醒改成中文飞书群提醒。](https://langbot.app/docs/images/articles/source/images/dify-langbot/026-langbot-writing-chinese-roundtrip.png)

*实际链路：在 LangBot 里把英文提醒改成中文飞书群提醒。*

## 先把 Dify 和 LangBot 跑起来

先安装 Docker Compose 和 Git，再分别按 [Dify Docker Compose 部署文档](https://docs.dify.ai/en/self-host/deploy/quick-start/docker-compose) 与 [LangBot Docker 部署文档](https://langbot.app/docs/en/deploy/langbot/docker.md) 启动两个服务。Dify 的基础步骤是克隆仓库、进入 `docker` 目录、将 `.env.example` 复制为 `.env`，再启动 Compose；LangBot 的文档提供完整的镜像和插件运行时配置。

本文截图来自 **Dify 1.17.1、LangBot v4.10.11** 的本机环境。我们把浏览器端口分别映射为 `8088` 和 `5368`；这是演示环境的自定义映射，官方默认部署通常分别使用 `80` 和 `5300`。如果沿用官方默认值，就打开 `http://localhost` 和 `http://localhost:5300`，不用为了对齐截图而改端口。各自创建管理员账户，并把界面语言设为 **English**。

![本地 Dify 的首次初始化页面。](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-dify-install.png)

*本地 Dify 的首次初始化页面。*

![本地 LangBot 的首次初始化页面。](https://langbot.app/docs/images/articles/source/images/dify-langbot/00-langbot-install.png)

*本地 LangBot 的首次初始化页面。*

接入时最重要的是 **LangBot 容器能访问 Dify**。本次两个服务加入同一个 Docker 网络，因此 Runner 的 Base URL 使用 `http://nginx/v1`，其中 `nginx` 是 Dify 的服务名。你可以在两个 Compose 配置中为 Dify 的 `nginx` 和 LangBot 服务加入同一个外部网络；如果分别部署在不同主机，则填写 LangBot 能访问的 Dify HTTPS 地址并加上 `/v1`。下文表格里的 `http://nginx/v1` 都指本次共享网络环境，不能直接套到所有部署。容器内的 `localhost` 指向容器自己。

## 在 Dify 中配置 GPT-6 Astra

进入 **Integrations → Model Provider**，安装官方 **OpenAI-API-compatible** 插件，再点 **Add Model**。本次使用的插件版本是 0.0.66。

| 字段                                              | 本次设置                            |
| ----------------------------------------------- | ------------------------------- |
| Model Name / model name for API endpoint        | `gpt-6-astra`                   |
| Model Type / Completion mode                    | LLM / Chat                      |
| Model display name                              | GPT-6 Astra                     |
| API Base URL                                    | 你自己的 OpenAI 兼容服务地址，通常以 `/v1` 结尾 |
| API Key                                         | 你的模型服务密钥                        |
| API Type                                        | Chat Completions API            |
| Model context size / Upper bound for max tokens | 本教程设为 32768 / 4096              |

最后一行是这次演示的工作上限，不是对 Astra 完整规格的声明。保存时让 Dify 做连接验证，成功后再建应用。截图中的网关只是本次测试环境，实际使用时换成你自己的服务。模型参数和可用接口以所选服务为准。模型名称以你选用的服务实际提供的标识为准，本文保留本次实测的 `gpt-6-astra`。

![添加自定义模型。API Key 在截图前保持为空，实际运行时已配置。](https://langbot.app/docs/images/articles/source/images/dify-langbot/014-dify-astra-model-settings.png)

*添加自定义模型。API Key 在截图前保持为空，实际运行时已配置。*

## 创建一个足够简单的 Chatbot

在 Dify Studio 点 **Create → Create from Blank → More basic app types → Chatbot**。命名 `Astra Writing Assistant`。这个需求只需要提示词和聊天记忆，用基础 Chatbot 就能做完整。

![展开基础应用类型，选择 Chatbot。](https://langbot.app/docs/images/articles/source/images/dify-langbot/010-dify-create-basic-app.png)

*展开基础应用类型，选择 Chatbot。*

![给写作助手命名，说明它负责什么。](https://langbot.app/docs/images/articles/source/images/dify-langbot/011-dify-writing-app-create.png)

*给写作助手命名，说明它负责什么。*

在 **Configure model** 选 GPT-6 Astra，然后把下面的指令放到 Instructions：

```text
You help a community manager turn rough notes into messages people can use.
Reply in the language of the user's request.
For an announcement, give: one clear headline, a short ready-to-send message,
and one optional reminder.
Preserve supplied dates, times, links, and requirements exactly.
Never invent missing event details, discounts, results, or promises.
If an essential detail is missing, ask one concise question.
Use a natural, direct tone. Avoid hype and excessive emojis.
Keep a typical reply under 180 words. When revising, use conversation context.
```

我们特意把“保留时间和报名方式”写进了规则。群公告最怕的不是文笔一般，而是模型把晚上 8 点改成下午 8 点，或者顺手编出一个报名链接。指令用英文写不影响中文回复；`Reply in the language...` 会跟随用户语言。

![写作助手的完整提示词编辑区。](https://langbot.app/docs/images/articles/source/images/dify-langbot/012-dify-writing-instructions.png)

*写作助手的完整提示词编辑区。*

先在右侧 **Debug & Preview** 输入：

> 帮我写一条飞书群公告：9月22日晚上8点举行机器人分享会，每人带一个机器人案例，在群里回复“报名”即可参加。口吻自然，100字以内。

实测回复保留了活动时间、案例要求和“报名”方式。接着可以继续说“删掉最后的提醒，只留两句话”。对于这种任务，第二轮是否记得上一轮，比第一次是否写得漂亮更有用。

![Dify 中的中文公告回复，日期和报名方式来自输入。](https://langbot.app/docs/images/articles/source/images/dify-langbot/022-writing-chinese-first-reply.png)

*Dify 中的中文公告回复，日期和报名方式来自输入。*

英文测试也做了一遍：先要求写 Discord demo day 通知，再让它缩短并删除可选提醒。第二轮沿用了第一轮给定的日期、UTC 时间和频道。

![多轮改写测试：继续修改已有公告。](https://langbot.app/docs/images/articles/source/images/dify-langbot/019-writing-english-context-revision.png)

*多轮改写测试：继续修改已有公告。*

基础 Chatbot 的改动需要通过 **Publish Update** 发布。不要只改了提示词就直接去平台测试，否则外部接口可能仍在使用上一个版本。

![Access Point 同时提供 Web App 和 Backend Service API。](https://langbot.app/docs/images/articles/source/images/dify-langbot/023-writing-access-point-api.png)

*Access Point 同时提供 Web App 和 Backend Service API。*

## 用 LangBot 接住消息入口

在 Dify 点 **Publish**，发布当前版本。然后进入 **Access Point → Backend Service API → API Key**，创建这个应用自己的密钥。

打开 LangBot，点 **Create Pipelines**，命名为 `Astra Writing Assistant`。进入 **Configuration → AI**：

| 字段       | 值                 |
| -------- | ----------------- |
| Runner   | Dify Service API  |
| Base URL | `http://nginx/v1` |
| App Type | Chat              |
| API Key  | 刚创建的 Dify 应用密钥    |

这里粘贴的是 **Dify 应用密钥**，不是前面配置 Astra 的模型密钥。一个负责调用应用，一个负责调用模型，别混用。保存后打开 **Debug Chat**，先验证整条调用链，再接平台。

![LangBot 的 Dify Runner 配置；截图时尚未填入应用密钥。](https://langbot.app/docs/images/articles/source/images/dify-langbot/007-langbot-dify-runner-config.png)

*LangBot 的 Dify Runner 配置；截图时尚未填入应用密钥。*

## 在 LangBot 再试一次

我们先发了一条英文 Telegram 提醒，拿到回复后继续要求改成中文飞书群提醒。最终回复保留了“9月22日晚上8点”和“每人带一个机器人案例”，说明 Dify 的会话上下文已经通过 LangBot 串起来了。

![LangBot 调用 Dify 返回英文活动提醒。](https://langbot.app/docs/images/articles/source/images/dify-langbot/025-langbot-writing-english-roundtrip.png)

*LangBot 调用 Dify 返回英文活动提醒。*

实际使用时，可以把这类助手放到运营群或项目群里，用提及触发。它适合把草稿变成能发送的文本：活动预告、版本通知、会议提醒、FAQ 回复。消息发送前仍由群成员决定是否采用，这样也方便继续改稿。

## 接到QQ、微信、飞书，以及其他消息平台

在 LangBot 点 **Create Bots**，选择适配器，填写平台提供的凭据。创建后把机器人绑定到刚才的流水线；检查 Trigger 中的私聊、群聊和提及规则，再按平台要求发布或邀请机器人。

本次实测覆盖 **LangBot → Dify → GPT-6 Astra → LangBot 回复**。以下是实际界面核对过的接入方式，平台账户与群聊没有在本次演示中授权连接。

| 入口              | 配置方式                                                                                                            |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| 飞书 / Lark       | 选 Lark；可扫码创建应用，也可手填 App ID、App Secret、与平台一致的 Bot Name。中国平台域名选 Feishu，默认使用长连接；开发者后台配置消息权限、事件并发布应用。               |
| 钉钉              | 选 DingTalk；扫码或填写 Client ID、Client Secret。Robot Code 需从开发者后台复制；按文档配置 Stream 接收消息、机器人名称和需要的卡片模板。                  |
| 企业微信智能机器人       | 选 WeComBot；长连接用 BotId、Secret，填写机器人名称。Webhook 模式另配 Corpid、Token、EncodingAESKey。两套模式不要混填。                         |
| 企业微信内部应用 / 微信客服 | 分别选 WeCom 或 WeComCustomerService，按各自后台填写企业与应用凭据、Token、EncodingAESKey，完成 HTTPS 回调和可信 IP 配置。内部应用不能直接当群机器人使用。      |
| 微信个人会话          | 选 OpenClaw WeChat，通过界面的二维码授权登录，按适配器说明接入。                                                                        |
| 微信公众号           | 选 Official Account，填写 App ID、App Secret、Token、EncodingAESKey，配置公网回调与 IP 白名单。根据接口限制选择回复模式；耗时较长时可能需要用户再发一条消息取回结果。 |
| QQ：OneBot v11   | 运行兼容 OneBot v11 的协议端，配置反向 WebSocket 到 LangBot 的监听端口，两侧 Access Token 保持一致；演示环境的 Compose 把主机 2288 映射到容器 2280。     |
| QQ 官方机器人        | 选 QQ Official API；可扫码绑定或填写 App ID、Secret。当前界面说明 Token 可留空；接收模式、沙箱范围、发布审核以 QQ 官方及适配器文档为准。                        |

![飞书适配器支持域名选择、扫码创建和手工配置。](https://langbot.app/docs/images/articles/source/images/dify-langbot/062-platform-lark-fields.png)

*飞书适配器支持域名选择、扫码创建和手工配置。*

![QQ 的 OneBot v11 方案需要反向 WebSocket 监听地址和端口。](https://langbot.app/docs/images/articles/source/images/dify-langbot/066-platform-onebot-v11-fields.png)

*QQ 的 OneBot v11 方案需要反向 WebSocket 监听地址和端口。*

LangBot 的适配器列表还包括 Discord、Slack、Telegram、LINE、Mattermost、Matrix、KOOK、Satori、HTTP Bot、Page Bot 和 WeChatPad。每种适配器需要的权限、回调和协议不同，不是填一个通用 Token 就全部接通。完整入口见 [LangBot 平台文档](https://langbot.app/docs/zh/usage/platforms/readme.md)。

如果只是想先模拟 QQ 消息，可以使用 matcha 之类的 OneBot 测试端；本文展示的对话来自 LangBot 自带 Debug Chat，没有把模拟对话当作真实群消息。

## 几个容易卡住的地方

遇到问题先按链路定位：Dify 预览能否回复、应用是否已 Publish、LangBot 的 Base URL 是否包含 `/v1`、应用类型是否正确，最后才看平台事件是否到达。如果改过 Dify 服务密码，Redis 与 Celery、Sandbox 与代码执行客户端的配置必须成对修改。

本机部署还遇到过代理软件返回虚拟 DNS 地址，导致 Dify 的 SSRF 代理拒绝插件下载。修好 DNS 后恢复，没必要关掉证书校验或内网访问保护。一次外部 API 的临时失败也不能当作模型或平台已经接通的证明，重试后仍应检查运行记录。

项目入口：[LangBot](https://github.com/langbot-app/LangBot) 和 [Dify](https://github.com/langgenius/dify)。截图和测试日期为 2026 年 9 月 16 日，后续版本的菜单名称可能会变化。

## 继续阅读

- [让客服问题走对分支：Dify + LangBot 钉钉、企业微信机器人实战](https://langbot.app/zh/blog/dify-langbot-support-triage)
- [在飞书里查询 GitHub 更新：Dify Workflow + GPT-6 Astra + LangBot 实战](https://langbot.app/zh/blog/dify-langbot-github-release-briefing)

---

# 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) 中的现有插件获取灵感。

---

# Telegram：体验 LangBot 沙箱 Agent

Source: https://langbot.app/docs/zh/articles/langbot-telegram-sandbox-agent

通过 Telegram 与 LangBot 沙箱 Agent 对话，让 AI 运行命令、处理文件、编写代码并完成实际任务。

发布于 2026-09-17 · 作者：LangBot Team

普通 AI 对话只能告诉你“应该怎么做”，连接沙箱后的 LangBot Agent 则可以在隔离工作区中真正执行任务。

你可以直接在 Telegram 中描述目标，让 Agent 运行命令、创建文件、修改内容、搜索资料或执行代码，再把结果返回给你。

![Telegram 沙箱 Agent 使用效果](https://langbot.app/docs/images/articles/telegram-sandbox.jpg)

## 不只是回答，而是动手完成

沙箱为 Agent 提供了一个可以操作的工作区。根据你的要求，它可以：

- 运行 Shell 命令
- 读取工作区中的文件
- 创建或覆盖文件
- 修改已有文件内容
- 按文件名查找文件
- 搜索文件中的文字
- 执行 Python 等代码
- 启动并管理任务进程

整个过程通过 Telegram 对话完成，不需要在聊天窗口和命令行之间反复切换。

## 可以让它做什么

### 处理文本和文件

你可以让 Agent 创建或整理文件：

- 帮我生成一份项目 README
- 把这段内容整理成 Markdown
- 创建一个包含标题和表格的报告
- 查找工作区中所有包含某个关键词的文件
- 修改配置文件中的指定参数

Agent 会在工作区中完成操作，并告诉你处理结果。

### 编写和运行代码

你可以直接描述一个小程序或数据处理任务：

- 写一个 Python 脚本统计 CSV 中每一列的平均值
- 生成 100 条测试数据并保存为 JSON
- 检查这段代码为什么运行失败
- 创建一个简单的网页并启动预览
- 运行测试并根据错误修改代码

连接沙箱后，Agent 不仅能生成代码，还能实际运行命令并根据结果继续处理。

### 分析工作区内容

当工作区中已有文件时，可以让 Agent 帮你快速定位信息：

- 列出当前目录下的所有 Markdown 文件
- 搜索哪些文件使用了某个函数
- 找出配置文件中重复的字段
- 读取日志并归纳最常见的错误

它会使用文件查找和内容搜索工具完成这些任务。

## 如何描述任务

任务越明确，Agent 越容易给出符合预期的结果。建议同时说明目标、输入和输出格式。

例如，不要只说：

> 帮我处理这个文件。

可以说得更具体：

> 读取工作区中的 sales.csv，按月份统计销售额，将结果保存为 summary.csv，并告诉我销售额最高的月份。

如果任务包含多个步骤，也可以一次完整说明。Agent 会根据执行结果继续推进，并在必要时向你确认信息。

## 关于沙箱

沙箱是 Agent 的独立执行环境，用于降低运行命令和处理文件时对其他环境的影响。不同会话的文件是否共享，取决于当前沙箱的作用域设置。

请不要在对话中发送密码、API Key、身份证件或其他敏感信息。对于删除文件、批量修改和长时间运行等操作，建议先明确范围，并在执行前确认。

## 在 LangBot Cloud 部署 Telegram 沙箱 Agent

LangBot Cloud 已经准备好托管环境、公网访问地址和沙箱，不需要购买服务器、安装 Docker 或配置运行时。开始前只需准备一个 Telegram 账号。

### 1. 创建 LangBot Cloud 实例

1. 打开 [LangBot Cloud](https://cloud.langbot.app)，登录 LangBot Account。
2. 为机器人选择一个名称。这个名称也会成为实例的 `.langbot.cloud` 访问地址。
3. 选择当前可用的体验版、免费版或订阅套餐。不同套餐的可用平台、资源和自动休眠规则以页面显示为准。
4. 确认配置并部署。实例通常会在 1 到 2 分钟内完成初始化。
5. 状态变为**运行中**后，点击**打开机器人**进入 LangBot 控制台。

Cloud 会为实例提供可直接使用的 LangBot Models 及一定的模型积分。你也可以在**模型**页面接入自己的模型 API Key。

### 2. 配置沙箱 Agent 流水线

进入**流水线**页面，打开默认流水线或创建一条新流水线，然后在 **AI 能力**中：

1. 将运行器选择为**内置 Agent**。
2. 选择一个支持工具调用的模型。接入自有模型时，需要同时启用模型的**工具使用能力**。
3. 确认沙箱已启用。Cloud 已经配置好沙箱后端，无需额外安装。
4. 选择沙箱作用域。个人私聊建议使用**每个会话**；多人群聊且需要隔离文件时，建议使用**每个用户**。
5. 保存流水线，并在**对话调试**中让 Agent 执行一个简单任务，例如“用 Python 计算 1 到 100 的和”。

如果 Agent 只返回代码但没有执行，请检查模型是否支持工具调用、是否启用了工具使用能力，以及流水线运行器是否为内置 Agent。

### 3. 在 Telegram 创建机器人

1. 打开 [BotFather](https://t.me/botfather)，发送 `/newbot`。
2. 按提示设置机器人名称和以 `bot` 结尾的用户名。
3. 保存 BotFather 返回的 API Token，不要将它发送给其他人。
4. 如果机器人需要读取群聊中的普通消息，在 BotFather 中执行 `/setprivacy`，选择该机器人并关闭 Privacy Mode；只用于私聊时可以保持默认设置。

### 4. 将 Telegram 接入 LangBot

回到 LangBot 控制台，进入**机器人**页面并创建机器人：

1. 平台选择 **Telegram**。
2. 填入 BotFather 提供的 API Token。
3. 绑定前面配置好的内置 Agent 流水线。
4. 保存并启用机器人。

打开 Telegram，进入刚创建的机器人会话并点击 **Start**，发送：

> 请用 Python 生成一份包含 20 条示例数据的 CSV 文件，并统计其中数值列的平均值。

Agent 能执行命令、创建文件并返回统计结果，就说明模型、沙箱、流水线和 Telegram 接入均已配置成功。完整配置项可继续参考 [Telegram 接入文档](https://langbot.app/docs/zh/usage/platforms/telegram.md)和[沙箱文档](https://langbot.app/docs/zh/usage/sandbox/readme.md)。如有私有部署要求，再参考 [Docker 部署文档](https://langbot.app/docs/zh/deploy/langbot/docker.md)。

## 扫码开始体验

使用 Telegram 扫描下方二维码，打开 LangBot 沙箱 Agent 后直接发送任务。

![Telegram 沙箱 Agent 二维码](https://langbot.app/docs/images/articles/telegram-sandbox-qr.png)

如果不知道从哪里开始，可以先试试：

> 请用 Python 生成一份包含 20 条示例数据的 CSV 文件，并统计其中数值列的平均值。

---

# 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 4.11：从消息回复走向事件驱动智能体

Source: https://langbot.app/docs/zh/articles/langbot-v411-event-driven-agents

LangBot 4.11 正式发布：事件路由让机器人响应入群、回应与卡片交互，AgentRunner 插件化连接不同智能体，工作区助手让配置更直观。附实机截图与升级指南。

本文同步自 LangBot Blog。 [阅读 Blog 原文](https://langbot.app/zh/blog/langbot-v411-event-driven-agents).

发布于 2026-10-15 · 作者：LangBot Team

LangBot 是一个开源的 AI 聊天机器人与智能体平台，支持多种即时通讯平台、大语言模型、知识库和插件，帮助你构建、部署和管理 AI 助手。

过去，搭建一个聊天机器人通常从“收到消息，然后回复”开始。但真正的协作不只发生在消息里：新成员加入群组、用户对一条回复作出表情回应、同事点击卡片按钮，都可能是一个任务的起点。

**LangBot 4.11 的核心变化，是把这些事件变成可以配置、交给智能体处理、并追踪执行过程的入口。** 配合插件化的 AgentRunner 和新的工作区助手，LangBot 在连接聊天平台的同时，也让“由谁处理、怎么处理、如何管理”变得更清楚。

## 一、事件驱动：机器人不再只等待下一条消息

4.11 引入事件驱动智能体（Event-Based Agents，EBA）。除了普通消息，入群、退群、消息撤回、表情回应、卡片点击等平台事件，也可以进入处理流程。本次发布中，13 个平台适配器已经基于 EBA 架构重写。

这不意味着每个平台都有完全相同的事件能力。实际能收到哪些事件，仍取决于对应平台、适配器以及机器人权限。变化在于：收到事件之后，LangBot 有了一套统一的路由和处理方式。

![事件路由可按平台事件选择处理器](https://langbot.app/docs/images/articles/source/images/langbot-411/eba-event-routing.png)

*4.11 正式版发布说明中的事件路由示例。*

### 从场景出发，而不是先写一段胶水代码

在「事件路由」中，可以从欢迎新成员、处理成员离开等常见场景建立规则，再决定由哪个处理器执行。

例如，一个社区可以把普通问题交给知识库问答 Pipeline，把新成员加入交给负责欢迎与介绍规则的 Agent，再把需要固定业务逻辑的事件交给插件处理器。这是配置思路示例；实际启用前，需要确认平台事件支持和所需权限，并测试对应路由。

这种组织方式的好处是，**平台接入与业务处理不必绑成一块**。欢迎流程变了，可以调整处理器；问答策略变了，可以修改 Pipeline，而不必把所有行为塞进同一段提示词。

### Pipeline、Agent、插件处理器，分别适合什么？

![实机中的三类处理器创建界面](https://langbot.app/docs/images/articles/source/images/langbot-411/processor-types.png)

*本文新启动的 LangBot 4.11.0 实例：创建处理器时，先选择处理方式。*

- **Pipeline**：处理消息事件，适合直接生成回复、知识库问答和已有的消息处理流程。它仍是固定步骤清晰、容易配置的选择。
- **Agent**：用自然语言描述不同事件该如何处理，由 AI 执行，或者交给外部 Agent 平台。适合需要结合上下文作判断的任务。
- **插件处理器**：由插件代码处理其声明支持的事件类型。适合规则明确、需要确定性逻辑或专门集成的场景。

不需要为了“用上智能体”而把每个流程都改成 Agent。明确的规则交给代码，稳定的问答交给 Pipeline，需要判断的部分再交给 Agent，往往更容易维护。

### 调试也围绕事件展开

事件调试器允许以表单编辑事件数据，查看运行日志和执行详情。配置好路由之后，可以先检查事件字段和处理结果，再到真实聊天平台验证。调试事件有助于定位问题，但不替代对平台连接、权限和真实回调的验证。

平台侧也有相应改进，包括 Slack Socket Mode、钉钉卡片交互、微信“正在输入”提示和 OneBot WebSocket 等；具体支持范围以对应平台文档为准。

## 二、AgentRunner 插件化：选择执行方式，不必等待 Core 发版

另一项重要变化是运行器与主程序的解耦。LocalAgent、Dify、Coze、n8n 等原内置运行器迁移为扩展市场中的官方插件，并新增 Codex、Claude Code、ACP 等运行器。

![实机扩展市场中的官方运行器入口](https://langbot.app/docs/images/articles/source/images/langbot-411/marketplace-live.png)

*实机访问扩展市场，可看到官方 Runner 专区。市场内容独立更新，展示状态以访问时为准。*

对于用户，最直接的变化是：**按需安装运行器，并独立更新它们**。你可以使用 LocalAgent 的模型、工具和知识检索能力，也可以把已有的 Dify 应用或 n8n 工作流接到聊天平台，不必为了不同的执行方式维护不同的机器人接入方案。

这也给开发者留下更清晰的扩展边界：实现 AgentRunner Protocol v1，就可以编写自己的运行器，而不必把特定平台的逻辑直接加入 Core。

![发布说明展示的多种 AgentRunner 插件](https://langbot.app/docs/images/articles/source/images/langbot-411/runner-plugins-marketplace.png)

*4.11 正式版发布说明中的运行器插件示例。不同 Runner 的账号、API、运行环境要求仍需分别配置。*

插件化并不等于把所有能力无条件交给插件。运行器只能调用当前上下文授权的工具与平台 API；扩展市场展示认证徽章，Core 校验认证插件的签名。认证与权限控制解决的是来源和授权问题，使用前仍应阅读插件说明，确认它适合自己的部署环境。

### 升级时，已有 Pipeline 怎么办？

4.11 提供迁移入口，自动安装所需插件，并备份原配置。升级后，在「流水线」页面完成迁移，再检查运行器、模型、知识库和工具配置。

需要特别留意：**迁移后的流水线会开始新会话**。旧版自定义 Runner 也需要改写为插件 Runner。离线环境可以选择「仅迁移数据」，再手动安装运行器插件。完整映射关系见 [4.11 迁移说明](https://github.com/langbot-app/LangBot/blob/v4.11.0/docs/pipeline-migration-config-map.zh-CN.md)。

## 三、工作区助手：把配置过程变成可确认的对话

WebUI 新增的工作区助手，面向的是管理 LangBot 的人，而不是聊天群中的终端用户。它可以查询当前工作区的资源，并通过对话帮助创建和配置流水线、知识库等资源。

![工作区助手与统一监控界面](https://langbot.app/docs/images/articles/source/images/langbot-411/workspace-assistant.png)

*实机中的工作区助手初始界面。此截图展示尚未配置模型的新工作区；使用前需要登录 LangBot Account 或配置可用模型。监控中的零值是这个新实例的真实空状态。*

你可以从“当前有哪些模型、知识库和流水线？”这样的只读查询开始，再提出“帮我创建一个知识库问答应用”。重点不是把表单换成聊天框，而是让助手先理解当前资源，再提出具体配置。

**所有写操作都需要确认后才会执行。** 因此，在让助手新建或修改资源时，应先核对它提出的对象、参数和影响范围，再确认。助手降低了寻找配置入口的成本，也保留了管理者对变更的控制。

## 四、让日常运维跟得上新的执行方式

### 统一看执行，而不只看消息数量

当一个事件可能由 Pipeline、Agent 或插件处理时，排查问题需要看到完整的执行过程。4.11 更新了统一执行视图、工具调用追踪和实时处理中面板。

日常检查可以按这条顺序进行：先看事件有没有进入，再看交给了哪个处理器，最后查看模型与工具调用是否完成。这样更容易区分平台接入问题、路由配置问题和执行阶段的问题，而不是仅凭“机器人没有回复”猜测原因。

### 账号安全与操作记录

![账号设置中的 Passkey 与两步验证](https://langbot.app/docs/images/articles/source/images/langbot-411/account-security.png)

*实机账号设置展示 Passkey 和两步验证入口；截图中的演示账号尚未启用这些功能。*

4.11 新增 WebAuthn Passkey 登录和 TOTP 两步验证，并提供记录每次操作变更的操作日志及完整性校验。对于多人维护的工作区，这些能力分别帮助加强登录保护、追踪“谁改了什么”。Passkey 的使用还需要满足浏览器安全上下文等条件，应在合适的 HTTPS 部署环境中配置。

媒体存储也有调整：媒体按内容去重存储，减少重复媒体导致的 `langbot.db` 膨胀。此外，`lbctl` 和 API Key 提供了管理与诊断实例的命令行入口，适合把日常检查接入已有运维流程。

## 五、新用户更容易开始，老用户按步骤升级

![实机新手引导中的平台选择](https://langbot.app/docs/images/articles/source/images/langbot-411/onboarding.png)

*新手引导从平台选择开始，再进入机器人配置与 AI 引擎设置。*

第一次使用 LangBot，可以跟随侧边栏引导和场景化机器人创建向导，从平台、机器人配置、AI 引擎逐步完成设置。建议先验证一个简单问答流程，再添加知识库、工具和事件路由，避免同时引入太多变量。

已有实例升级，建议按下面的顺序处理：

1. **先备份** `data/` 目录或 PostgreSQL 数据库，建议从最新 v4.10.x 升级，并保留当前部署配置。
2. **升级 Core 与配套 Runtime**，检查服务连接状态。4.11.0 正式版固定使用 SDK `0.7.11`，不要混用旧 Runtime。
3. **完成流水线迁移并更新插件**，检查迁移后的运行器及配置，注意新会话边界。
4. **验证真实业务链路**：先测试一个已有的消息问答，再逐步验证新事件路由和授权工具。
5. **检查遥测与配置变化**：新增执行遥测默认开启，不含消息内容；可用 `space.disable_telemetry: true` 关闭这一遥测。配置新增 `media_cache`、`api.host`、`runner.admin_plugins`，移除 `force_box_session_id_template`。详见[数据收集政策](https://langbot.app/docs/zh/insight/data-collection-policy.md)及正式发布说明。

## 开始使用 LangBot 4.11

4.11 的价值不在于新增了多少配置项，而在于把三个问题连起来：**什么事件触发任务、由什么执行方式处理、怎样安全地管理和观察它。** 你可以继续保留熟悉的消息问答，也可以逐步把社区协作、业务通知与交互任务放进同一套管理界面。

- [查看 v4.11.0 正式版与完整更新说明](https://github.com/langbot-app/LangBot/releases/tag/v4.11.0)
- [阅读部署与使用文档](https://langbot.app/docs/zh/insight/guide.md)
- [使用 LangBot Cloud](https://cloud.langbot.app)

感谢所有参与本次版本开发、测试、文档和问题反馈的贡献者。本文围绕主要更新展开，完整贡献者名单见正式发布说明。

*配图说明：事件路由与运行器插件总览来自 v4.11.0 GitHub Release，其余五张截图来自为本文独立运行的官方 `rockchin/langbot:v4.11.0` 实例。实机截图使用英文界面便于跨语言对照；没有连接生产机器人，也没有将演示界面描述为真实业务运行结果。*

---

# 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)

---

# LangBot 公众号：体验基础 AI 问答

Source: https://langbot.app/docs/zh/articles/langbot-wechat-official-account

通过 LangBot 公众号进行基础 AI 问答，并获取产品动态、使用教程和应用实践。

发布于 2026-09-17 · 作者：LangBot Team

LangBot 是一个开源的 AI 机器人平台，可以将大模型、知识库、Agent、插件和工作流连接到企业微信、Telegram、飞书、钉钉、QQ、Discord 等消息平台。

关注 **LangBot 公众号**，不仅可以了解产品更新、使用方法和真实应用实践，还可以直接发送消息，体验基础 AI 问答服务。

## 直接使用基础 AI 问答

在公众号中发送问题，即可与 LangBot 进行基础对话。例如：

- 帮我解释一个技术概念
- 把这段文字概括成三句话
- 帮我写一封简短的邮件
- 为一个活动想几个标题
- 翻译或润色一段内容
- 给我一些学习或工作建议

公众号适合日常咨询、内容生成、翻译润色和一般知识问答，打开微信即可使用。

## 三个入口有什么区别

公众号提供的是**基础 AI 问答**，当前不接入企业知识库，也不提供沙箱工具。请根据需要选择对应入口：

| 入口          | 提供的能力            | 适合的问题                        |
| ----------- | ---------------- | ---------------------------- |
| LangBot 公众号 | 基础 AI 问答         | 日常咨询、写作、总结、翻译和一般知识问答         |
| 企业微信客服      | LangBot 知识库      | 查询产品手册、价格政策、实施流程、公司制度和会议纪要   |
| Telegram    | LangBot 沙箱 Agent | 运行代码和命令、创建或修改文件、处理数据和完成多步骤任务 |

如果需要查询企业资料，请使用[企业微信客服知识库](https://langbot.app/docs/zh/articles/langbot-wecom-customer-service-knowledge-base.md)。如果需要让 Agent 执行命令、处理文件或运行代码，请使用[Telegram 沙箱 Agent](https://langbot.app/docs/zh/articles/langbot-telegram-sandbox-agent.md)。

## 你可以看到什么

### 产品动态

了解 LangBot 新版本带来的能力，包括模型支持、知识库、Agent 沙箱、Skills、插件系统和平台适配等更新。

每次重要版本发布后，公众号会用更容易理解的方式介绍新功能能解决什么问题，以及适合哪些使用场景。

### 使用教程

从部署 LangBot 到接入消息平台，从配置模型到使用知识库，公众号会持续发布可直接参考的教程。

内容包括：

- 快速部署 LangBot
- 接入企业微信、Telegram、飞书和钉钉
- 配置 GPT、Claude、Gemini、DeepSeek 等模型
- 创建企业知识库问答机器人
- 使用 Agent 沙箱执行任务
- 安装和使用插件
- 连接 Dify、n8n、Langflow 等外部工作流

### 应用案例

你可以了解 LangBot 在不同场景中的使用方式：

- 企业知识库与内部问答
- 微信客服与售前咨询
- 群聊 AI 助手
- 文件处理和代码执行 Agent
- 客户支持与故障排查
- 工作流自动化

这些案例可以帮助你判断 LangBot 是否适合自己的团队，也可以作为搭建机器人时的参考。

### 社区精选

LangBot 社区持续产生新的插件、用法和解决方案。公众号会整理值得关注的项目进展、社区实践和优秀案例，帮助你更快发现可以直接使用的能力。

## 在 LangBot Cloud 部署微信公众号 AI 助手

LangBot Cloud 自带公网域名和 HTTPS，不需要购买服务器、安装 Docker 或配置反向代理。开始前只需准备一个可登录[微信公众平台](https://mp.weixin.qq.com/)的公众号。

### 1. 创建 LangBot Cloud 实例

1. 打开 [LangBot Cloud](https://cloud.langbot.app)，登录 LangBot Account。
2. 为机器人选择一个名称。这个名称也会成为实例的 `.langbot.cloud` 访问地址。
3. 选择支持微信公众号的套餐，确认价格、资源和消息平台范围后继续。
4. 确认配置并部署。实例通常会在 1 到 2 分钟内完成初始化。
5. 状态变为**运行中**后，点击**打开机器人**进入 LangBot 控制台。

### 2. 配置模型和流水线

进入 LangBot 控制台的**模型**页面：

1. Cloud 会提供可直接使用的 LangBot Models 及一定的模型积分；也可以添加自己的模型供应商、Base URL 和 API Key。
2. 选择或添加一个对话模型。
3. 进入**流水线**页面，打开默认流水线。
4. 在 **AI 能力**中选择**内置 Agent**和刚添加的模型，然后保存。
5. 使用**对话调试**发送一条消息，确认模型可以正常回复。

只有调试对话成功后再继续接入公众号，这样出现问题时更容易区分是模型配置还是微信回调配置导致的。

### 3. 获取公众号开发配置

登录微信公众平台，进入**设置与开发 > 开发接口管理**：

1. 记录公众号的 `AppID` 和 `AppSecret`。
2. 按微信公众平台要求配置 IP 白名单。Cloud 实例需要填写的出口 IP 以实例或平台页面显示的信息为准。
3. 打开服务器配置，准备一个自定义 `Token`，并生成 `EncodingAESKey`。
4. 将消息加解密方式选择为**安全模式**。

`AppSecret`、`Token` 和 `EncodingAESKey` 都属于敏感信息，不要放进截图、公开仓库或聊天记录。

### 4. 在 LangBot 创建公众号机器人

进入 LangBot 控制台的**机器人**页面，创建一个**微信公众号**机器人，然后：

1. 填入 `AppID`、`AppSecret`、`Token` 和 `EncodingAESKey`。
2. `Mode` 选择 `drop` 时，公众号直接返回模型回答，但必须在微信规定的 15 秒内完成。
3. 模型响应可能超过 15 秒时，建议选择 `passive`；用户会先收到等待提示，再发送任意文字获取结果。
4. 绑定前面配置好的流水线，将 `enable` 设为 `true`，保存并启用机器人。
5. 从机器人配置页面复制 Webhook 回调地址。

### 5. 完成微信回调验证

回到微信公众平台的服务器配置，粘贴 LangBot 生成的完整 Webhook 地址。Cloud 地址已经配置好公网 HTTPS，形式类似：

```text
https://你的实例名.langbot.cloud/bots/xxxxx
```

确认微信公众平台和 LangBot 两边填写的 `Token`、`EncodingAESKey` 及加密模式完全一致，然后保存并启用服务器配置。微信提示保存成功，说明回调验证已经通过。

最后关注公众号并发送一条测试消息。如果回调验证失败，请优先检查 IP 白名单、Webhook 地址以及两端的 `Token`、`EncodingAESKey` 和加密模式是否一致。更多截图和字段说明见[微信公众号接入文档](https://langbot.app/docs/zh/usage/platforms/wxoa.md)。如有私有部署要求，再参考 [Docker 部署文档](https://langbot.app/docs/zh/deploy/langbot/docker.md)。

## 关注并开始问答

在微信中搜索 **LangBot** 公众号并关注。进入公众号后直接发送消息，即可开始基础 AI 问答。

也可以使用微信扫描下方二维码关注：

![LangBot 微信公众号二维码](https://langbot.app/docs/images/articles/langbot-wechat-official-account-qr.png)

你还可以访问以下资源了解 LangBot：

- [LangBot GitHub](https://github.com/langbot-app/LangBot)
- [LangBot 官方文档](https://langbot.app/docs/zh/insight/guide.md)
- [LangBot Cloud](https://cloud.langbot.app)

---

# 企业微信客服：体验 LangBot 知识库

Source: https://langbot.app/docs/zh/articles/langbot-wecom-customer-service-knowledge-base

通过企业微信客服，用自然语言查询产品、价格、服务流程、公司制度和最新业务信息。

发布于 2026-09-17 · 作者：LangBot Team

产品有几个版本？学校客户能参加优惠吗？客户签约后应该先做什么？去杭州出差能报销多少住宿费？

这些问题的答案通常分散在产品手册、销售政策、实施流程、员工制度和会议纪要中。现在，你不必逐份查找文档，直接在微信里向 LangBot 知识库提问即可。

![企业微信客服知识库问答效果](https://langbot.app/docs/images/articles/wecom-customer-service.jpg)

## 知识库里有什么

当前 LangBot 知识库汇集了企业日常使用的多类资料，包括：

- 客户案例：记录不同行业、团队规模、使用平台和方案选择
- 产品手册：介绍产品功能、版本区别、适用人数和部署方式
- 销售政策：包含标准价格、活动规则和适用条件
- 实施流程：说明签约交接、实施周期、测试和上线要求
- 故障处理手册：提供问题分级、排查顺序和处理方法
- 报销标准与员工制度：包含差旅住宿、交通、请假和费用报销规则
- 会议纪要：记录产品计划、功能调整和最新业务信息

知识库支持导入 **PDF、Word、Markdown** 等多种常用文档格式。不同部门可以直接使用已有资料建立知识库，不必把所有内容重新整理成固定问答。

![LangBot 企业知识库配置](https://langbot.app/docs/images/articles/wecom-knowledge-base-config.png)

## 像聊天一样查询企业资料

打开企业微信客服后，直接说出你想知道的事情。你不需要记住文件名，也不需要使用固定格式。

可以这样问：

- 200 人的公司应该购买哪个版本？
- 企业微信最低需要哪个版本？
- 学校客户 9 月购买专业版，可以享受 88 折吗？
- 客户昨天刚签合同，今天应该做什么？
- 机器人突然不回复，应该先检查什么？
- 去杭州出差，酒店最多可以报销多少？
- 企业微信新版文件解析什么时候上线？

LangBot 知识库会从相关资料中寻找依据，再把答案整理成容易理解的回复。

## 一个问题可以包含多个条件

你也可以把完整需求一次说清楚。例如：

> 我们有一个 260 人的教育客户，希望使用飞书，9 月份上线，还希望参加本月优惠。应该推荐哪个版本？有哪些风险？

面对这类问题，LangBot 知识库会同时参考产品版本、人数限制、行业政策、活动规则和类似客户案例，而不是只回答其中一个条件。

如果客户还要求数据本地存储，也可以继续追问：

> 客户要求数据必须保存在本地，版本选择会发生变化吗？

LangBot 知识库会结合私有化部署要求给出补充说明。

## 查询产品和价格

你可以询问产品能力、版本区别、适用人数和标准价格：

- 基础版、专业版和企业版有什么区别？
- 专业版最多支持多少人？
- 哪个版本支持 API？
- 哪个版本支持私有化部署？
- 专业版的标准价格是多少？

## 查询交付和故障处理

LangBot 知识库也可以根据实施流程和故障处理手册回答：

- SaaS 标准实施通常需要几个工作日？
- 正式上线前至少需要完成哪些测试？
- 知识库准确率只有 82%，建议上线吗？
- 单一客户完全不可用属于什么故障级别？
- API 连续失败几次后需要升级？

## 查询公司制度和最新消息

除了产品资料，你还可以查询员工制度和会议决定：

- 去上海出差的住宿标准是多少？
- 出差结束后多久需要提交报销？
- 某项功能的最新上线日期是什么时候？

当正式手册和最新会议纪要涉及同一件事时，LangBot 知识库会结合更新后的信息回答，帮助你减少使用旧资料的情况。

## 在 LangBot Cloud 部署企业微信客服知识库

LangBot Cloud 会托管运行环境，并提供企业微信回调所需的公网域名和 HTTPS。开始前请准备：

- 已完成企业认证并开通[微信客服](https://kf.weixin.qq.com/kf)的企业微信账号
- 用于问答的 PDF、Word 或 Markdown 文档

### 1. 创建 LangBot Cloud 实例

1. 打开 [LangBot Cloud](https://cloud.langbot.app)，登录 LangBot Account。
2. 为机器人选择一个名称。这个名称也会成为实例的 `.langbot.cloud` 访问地址。
3. 选择支持企业微信客服的套餐，确认价格、资源和消息平台范围后继续。
4. 确认配置并部署。实例通常会在 1 到 2 分钟内完成初始化。
5. 状态变为**运行中**后，点击**打开机器人**进入 LangBot 控制台。

### 2. 配置对话模型和嵌入模型

进入 LangBot 控制台的**模型**页面：

1. Cloud 会提供可直接使用的 LangBot Models 及一定的模型积分；也可以添加自己的模型供应商、Base URL 和 API Key。
2. 选择或添加一个对话模型，用于根据检索结果生成最终回答。
3. 准备一个嵌入模型，用于将文档和问题转换为向量。可以添加供应商提供的 Embedding 模型，也可以选择零配置的 `chroma-内置`。

先在流水线的**对话调试**中确认对话模型能正常回复，再继续创建知识库。

### 3. 创建并填充知识库

进入**知识库**页面，点击**创建知识库**：

1. 填写知识库名称和说明。
2. 选择已安装的 RAG 引擎。不同引擎的参数不同，使用内置方案时按页面提示选择刚才准备的嵌入模型。
3. 设置分块参数；首次使用可以先保留默认值，后续再根据文档结构和检索效果调整。
4. 创建完成后进入知识库的**文档**页面，上传 PDF、Word 或 Markdown 文件。
5. 等待解析和索引完成，确认文档状态正常后再测试问答。

建议先上传少量具有明确答案的资料，并用几个可以从原文核对的问题验证效果。资料中如有过期制度或互相冲突的版本，应先清理或标明生效日期。

### 4. 将知识库绑定到流水线

进入**流水线**页面，编辑默认流水线或创建一条客服专用流水线：

1. 在 **AI 能力**中将运行器选择为**内置 Agent**。
2. 选择已经配置好的对话模型。
3. 在知识库选项中勾选刚创建的知识库。
4. 如已配置 Rerank 模型，可以同时启用重排序并设置 Top-K；这一步是可选的。
5. 保存后进入**对话调试**，提出一个只能从上传文档中找到答案的问题。

回答能够引用文档中的有效信息后，再进行企业微信接入。知识库创建和检索参数的完整说明见[知识库文档](https://langbot.app/docs/zh/usage/knowledge/readme.md)。

### 5. 准备企业微信客服配置

登录[企业微信客服后台](https://kf.weixin.qq.com/kf)：

1. 在**企业信息**中记录企业 ID。
2. 进入**开发配置**并点击**开始使用**。
3. 生成并保存 `Token` 和 `EncodingAESKey`。
4. 暂时保留该页面，稍后需要填写 LangBot 生成的 Webhook URL，并复制企业微信生成的 `Secret`。

`Secret`、`Token` 和 `EncodingAESKey` 都属于敏感信息，不要公开或提交到代码仓库。

### 6. 在 LangBot 创建企业微信客服机器人

进入 LangBot 控制台的**机器人**页面，创建一个**企业微信客服**机器人：

1. 填入企业 ID、`Token` 和 `EncodingAESKey`。
2. 首次保存时 `Secret` 可先填写临时值。
3. 绑定前面配置好的知识库流水线，保存并启用机器人。
4. 从机器人配置页面复制完整的 Webhook 回调地址。Cloud 已经为 `.langbot.cloud` 地址配置好公网 HTTPS，无需替换域名。

回到企业微信客服后台，将该 URL 填入开发配置并保存。验证成功后，复制企业微信页面生成的 `Secret`，再回到 LangBot 用真实 `Secret` 替换临时值并保存。

### 7. 创建客服账号并验收

在企业微信客服后台进入**客服账号**，创建一个客服账号并获取对外服务入口。使用普通微信打开该入口，发送一个知识库测试问题。

如果能够收到依据上传文档生成的回答，说明企业微信回调、客服机器人、流水线和知识库均已连通。如果企业微信无法保存回调 URL，请优先检查 Webhook 地址以及两端的 `Token` 和 `EncodingAESKey` 是否一致。更多字段截图见[企业微信客服接入文档](https://langbot.app/docs/zh/usage/platforms/wecom/wecomcs.md)。如有私有部署要求，再参考 [Docker 部署文档](https://langbot.app/docs/zh/deploy/langbot/docker.md)。

## 扫码开始体验

使用微信扫描下方二维码，进入企业微信客服后即可直接提问。

![企业微信客服二维码](https://langbot.app/docs/images/articles/wecom-customer-service-qr.png)

如果不知道从哪里开始，可以先发送：

> 给我介绍一下产品手册。

---

# 用 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)

配置 **Runner**，选择 **Langflow API**：

![LangBot Runner Dropdown](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** 标签页，在 Runner 下拉菜单中选择 "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 运行。

> info:
>
> 官方 Docker 镜像已默认预装 `ffmpeg` 与 `pilk` 音频工具链（最小化安装），开箱即用支持微信原生语音条（SILK）转码与语音处理，无需额外在宿主机安装音频环境。

## 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` 安装。

### 可选的语音转码支持（SILK / 微信原生语音）

如果需要在微信等平台发送原生语音条（SILK 编码）或进行高级音频格式转码，需要系统安装 `ffmpeg` 并安装 `audio` 扩展依赖：

- **系统依赖**：`ffmpeg`（macOS 可用 `brew install ffmpeg`，Ubuntu/Debian 可用 `sudo apt-get install -y ffmpeg`，Windows 可用 `winget install Gyan.FFmpeg`）
- **Python 扩展**：
  ```bash
  uv sync --extra audio
  # 或同时启用 seekdb 与 audio
  uv sync --extra seekdb --extra audio
  ```

若未安装转码依赖，系统在需要转码为微信原生语音条时会自动进行**优雅降级**，将语音以音频文件的形式发送，确保用户仍能正常点击播放。

或者使用清华源

```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。

## 可选的语音转码支持（SILK / 微信原生语音）

如果需要在微信等平台发送原生语音条（SILK 格式）或进行音频格式转换，需要系统已安装 `ffmpeg`，并使用 `audio` extra 启动：

```bash
uvx --from 'langbot[audio]@latest' langbot
# 或同时启用 seekdb 与 audio
uvx --from 'langbot[seekdb,audio]@latest' langbot
```

若当前环境未安装 `ffmpeg` 或 `pilk`，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` 并重启。Cloud 的 Plugin Runtime 运维健康上报由独立的 `plugin.runtime_ops.enabled` 控制。

如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。

### 单事件执行链路

4.11 当前默认对符合上报条件的执行全量记录，包括平台事件、路由、Pipeline / Agent / 插件事件处理器，以及由此触发的平台 API 和工具调用。每个完成的节点生成一条记录，执行结束再生成一条结束记录，由 Space 重组链路。以下为同一 `space` 节点下的默认配置，修改后重启生效：

平台事件未命中业务路由，或被 `discard` 规则忽略且没有匹配的插件订阅时，整条事件不上报。本地日志和监控保留原有行为。插件订阅匹配、有效交互恢复及独立 WebUI/API/Pipeline 调用仍可上报；命中后的目标不可用、运行失败或 Pipeline 内部过滤也保留。该过滤在采样之前执行，Cloud 的 `all` 和失败兜底都不能绕过它，需要升级 Core 才能生效。

```yaml
space:
  execution_trace: all        # off | failures | sampled | all
  execution_trace_sample: 20  # sampled 模式下：按事件哈希保留约 1/N 的成功执行
  telemetry_flush_seconds: 180  # 执行记录缓冲区的刷新间隔，单位为秒
```

社区版的模式行为如下：

| 模式         | 上报行为                                                    |
| ---------- | ------------------------------------------------------- |
| `all`      | 默认值，记录所有符合上报条件的执行的节点和结束记录                               |
| `sampled`  | 按事件标识的稳定哈希决定是否保留，同一次执行共享采样决定；未命中的失败执行仍上报结束记录，但不追补节点     |
| `failures` | 普通执行不保留节点，只上报失败、取消、超时或有链路失败原因的结束记录                      |
| `off`      | 不上报执行节点和结束记录，也没有独立的窗口计数继续上报；心跳仍由 `disable_telemetry` 控制 |

WebUI 调试执行在 `all`、`sampled` 和 `failures` 下均保留并带有调试标记；`off` 或 `disable_telemetry: true` 会停止其上报。**Cloud 在产品遥测启用时固定使用 `all`，不采用上述采样模式配置**；实例运维方仍可使用总开关关闭产品遥测。

`execution_trace_sample` 接受 1–100000 的整数；`telemetry_flush_seconds` 接受 1–86400 的整数。无效值分别回退为 20 和 180，无效的模式回退为 `all`。抽样不是严格按顺序每 N 条保留一条。

每次刷新最多发送 128 条，缓冲最多 512 条；发送失败保留重试，缓冲满时丢弃最旧记录，因此全量模式也不保证完整送达。活跃工作区在启动约 30 秒后首次发送心跳，此后普通部署每天一次，Cloud runtime 每 5 分钟一次。执行原始记录按 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/enterprise/overview

在完整开源的 LangBot 之上，获得官方问题受理、安全更新，以及采购所需的合同与发票。

LangBot 企业支持订阅（LangBot Enterprise Support）面向需要**官方支持关系**和**正式采购凭证**的企业。您的订阅也将直接资助 LangBot 的持续开发。

> info:
>
> LangBot 仍按 Apache License 2.0 免费提供。企业支持订阅**不是商业使用许可**，不解锁任何功能，也不限制未订阅企业继续使用开源版本。

## 两档计划

|                      | 企业支持计划          | 企业保障计划             |
| -------------------- | --------------- | ------------------ |
| 年费（人民币）              | ¥3,980          | ¥7,980             |
| 适合                   | 希望资助项目并建立正式支持关系 | 已在生产环境正式使用 LangBot |
| 合同、发票与年度订阅证书         | ✓               | ✓                  |
| 企业工单，2 个工作日内首次响应     | ✓               | ✓                  |
| 严重安全问题通知、季度版本与安全摘要   | ✓               | ✓                  |
| 年度 60 分钟线上使用情况沟通     | 1 次             | 1 次                |
| 公开 Roadmap 提案优先评审    | ✓               | ✓                  |
| 官网企业支持者名单（可匿名，需授权）   | ✓               | ✓                  |
| 生产实例官方登记             | —               | 1 个                |
| 远程技术咨询（每次 60 分钟）     | —               | 每年 4 次             |
| 升级前兼容性咨询、故障优先分诊      | —               | ✓                  |
| 已确认的 Core 缺陷进入优先修复队列 | —               | ✓                  |
| 年度版本、依赖与安全状态说明       | —               | ✓                  |

按签约企业收取年费，不按人数或部署数量计费。税费、发票类别和服务期限以正式报价与合同为准。

## 下一步

- [服务范围与响应说明](https://langbot.app/docs/zh/enterprise/service-scope.md)：包含与不包含的内容、响应时间如何计算
- [提交支持工单](https://langbot.app/docs/zh/enterprise/submit-ticket.md)：已订阅企业如何提交问题
- [采购与开通](https://langbot.app/docs/zh/enterprise/procurement.md)：签约、开票与交付材料

咨询订阅请在[官网企业支持页面](https://langbot.app/zh/enterprise#enterprise-contact)提交咨询表单，填写使用场景、行业、身份和联系方式，我们会在 1–2 个工作日内与您联系。

---

# 采购与开通

Source: https://langbot.app/docs/zh/enterprise/procurement

企业支持订阅的签约、开票与交付材料。

## 开通流程

1. **提交咨询**：在[官网企业支持页面](https://langbot.app/zh/enterprise#enterprise-contact)填写咨询表单（使用场景、行业、身份和联系方式），我们会在 1–2 个工作日内与您联系。
2. **确认报价**：确认支持范围、税费和发票事项，签订年度服务合同。
3. **付款登记**：按合同付款，登记联系人、Space 账号和服务期限。
4. **开始使用**：收到订阅证书和服务说明后，即可[提交支持工单](https://langbot.app/docs/zh/enterprise/submit-ticket.md)。

> info:
>
> 首次咨询只需提供使用场景、行业、身份和联系方式。开票资料在签约前再提供，请勿通过公开工单或 GitHub 发送银行和税务信息。

## 合同与发票

| 项目   | 说明                                  |
| ---- | ----------------------------------- |
| 签约主体 | LangBot 项目运营主体，具体信息见报价与合同           |
| 合同标的 | LangBot 开源软件年度维护、版本信息与技术支持服务        |
| 计费方式 | 按签约企业收取年费，不按人数计费                    |
| 发票内容 | 由财务根据可开票范围确认，如软件服务费、信息技术服务费或技术支持服务费 |

订阅费用不作为捐赠，也不作为软件商业使用授权费开具。

## 交付材料

- 服务订单与合同，注明服务期限和指定联系人
- 年度企业支持订阅证书（证明支持服务关系，不构成额外软件授权）
- 服务范围与响应说明（注明版本）、Space 工单入口和账号登记
- 保障计划：生产实例登记和技术咨询额度
- 服务期间的季度维护摘要、工单与咨询记录；保障计划另附年度版本、依赖与安全状态说明

官网企业支持者名单的展示需要单独授权，也可以选择匿名。服务说明后续的更新不会自动改变已签合同的权益。

## 续费

续费需要另行确认，不会自动扣款。开始、结束、取消和退款安排以合同为准。

订阅不包含 LangBot Cloud 的算力、模型额度或托管服务。订阅到期后，您仍可按 Apache 2.0 继续使用 LangBot。

---

# 服务范围与响应说明

Source: https://langbot.app/docs/zh/enterprise/service-scope

企业支持订阅包含什么、不包含什么，以及首次响应时间如何计算。

企业支持订阅聚焦于 **LangBot Core 本身**，通过统一工单提供分诊与指引，而不是代运维或定制开发。

## 包含与不包含

| 包含                   | 不包含                           |
| -------------------- | ----------------------------- |
| LangBot Core 缺陷确认与分诊 | 代部署、代运维、7×24 值守、驻场            |
| 官方文档指引               | 企业网络、数据库、Kubernetes、模型供应商故障排查 |
| 升级兼容性建议              | 插件、第三方适配器、私有协议客户端维护           |
| 公开版本信息与安全公告          | 定制开发、历史数据迁移                   |
| 工单受理与分诊              | 恢复 SLA、固定修复期限、合规认证            |

定制需求不属于订阅范围，默认不承接。具有通用价值的需求可提交到公开 Roadmap。

## 首次响应

两档均承诺 **2 个工作日内首次人工响应**。首次响应是指人工确认问题范围、请求补充资料或给出初步分类，自动通知邮件不算。

> warning:
>
> 首次响应不等于修复或恢复。修复进度取决于问题严重程度、可复现性，以及问题是否属于 LangBot Core。

- **受理时间**：中国大陆法定工作日 09:00–18:00（北京时间），调休工作日计入，法定节假日顺延。
- **计时方式**：受理时间内提交的，从提交时刻起算两个工作日；受理时间外提交的，从下一个工作日 09:00 起算。
- **示例**：周五 14:00 提交，最晚下周二 14:00 前响应；周五 20:00 提交，最晚下周三 09:00 前响应。

## 支持版本

- 服务面向 LangBot Core **当前稳定版本**。旧版本问题会先给出升级建议，确认缺陷时可能需要在当前稳定版本上复现。
- 不提供历史版本补丁、LTS 分支或客户私有补丁。
- 插件和第三方组件不属于 Core 维护范围。

## 咨询与额度

|                   | 企业支持计划 | 企业保障计划 |
| ----------------- | ------ | ------ |
| 年度使用情况沟通（60 分钟）   | 1 次    | 1 次    |
| 远程技术咨询（60 分钟，需预约） | —      | 4 次    |

未使用的次数不结转到下一年。企业支持计划提供工单分诊、文档指引和缺陷确认，不包含对客户环境的持续远程排查。

## 实例登记（保障计划）

- 保障计划覆盖 **1 个登记的生产实例**。登记只用于界定支持范围，不限制 Apache 2.0 允许的部署数量，也不需要许可证或遥测。
- 登记内容：版本、部署概要、用途和联系人。更换生产实例时请通过工单更新登记。

## 安全信息

- 季度摘要基于公开的版本与安全信息。
- 严重安全问题通知基于维护团队确认的公告；我们不承诺判断您的环境是否受影响。
- 年度版本、依赖与安全状态说明（保障计划）基于登记版本和公开信息，不是安全审计、渗透测试或合规认证。

## 处理原则

- 一个工单对应一个问题，重复请求可能会被合并。
- 进入优先修复队列不代表有固定的修复时间；Roadmap 优先评审不代表承诺开发或排期。
- 支持统一通过工单进行，不提供群聊一对一支持。

## 服务期限

服务语言、联系人、起止日期和适用的服务说明版本以合同为准。到期后不再受理新请求，已受理的工单按合同完成分诊或交接。订阅到期不影响您继续使用开源 LangBot。

---

# 提交支持工单

Source: https://langbot.app/docs/zh/enterprise/submit-ticket

已订阅企业如何通过 LangBot Space 提交问题或预约咨询。

> idea:
>
> [前往 LangBot Space 提交工单 →](https://space.langbot.app/profile?tab=tickets\&language=zh)

## 提交步骤

1. 使用合同中登记的 Space 账号登录。
2. 进入「个人资料 → 工单」，选择模板：
   - **企业支持：问题受理**：报告 LangBot Core 的疑似缺陷
   - **企业支持：升级与咨询**：升级兼容性问题、技术咨询预约（保障计划）、文档与采购资料
3. 填写订阅/合同编号和企业名称，然后按表单填写问题信息。

团队会先核对合同、登记账号和服务期限，再确认权益。仅凭订阅编号不能证明身份。

## 需要准备的信息

**问题受理**

- LangBot 版本与部署方式
- 预期行为与实际行为
- 复现步骤
- 脱敏后的相关日志（没有日志请说明原因）
- 业务影响

**升级与咨询**

- 登记实例及当前版本、目标版本（如适用）
- 咨询目标与背景
- 希望沟通的时间（如需预约）

> warning:
>
> 请勿提交访问令牌、密码、完整聊天记录、客户个人信息或原始配置文件。截图请先脱敏。安全漏洞请不要发布到公开的 GitHub issue。

## 提交之后

团队核验订阅后进行分诊，可能会：

- 给出文档指引或请您补充资料
- 预约技术咨询（保障计划）
- 确认为 LangBot Core 缺陷，进入公共维护流程
- 说明问题不在服务范围内

确认的通用缺陷只会把必要且已脱敏的复现信息提交到公共维护流程，合同、日志和业务信息不会同步到公开 GitHub。补充资料请回复原工单，不要通过多个渠道重复提交。

---

# 社区资源

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 向 `space.url` 配置的 LangBot Space 服务（默认为 `https://space.langbot.app`）发送产品遥测，用于了解使用情况和改进可靠性。**遥测默认开启，可以关闭。** 以下说明对应 4.11 当前的执行遥测协议（`schema: 2`）；旧版本数据另见下文。

## 执行遥测

符合上报条件的一次执行由共享 `event_id` 的独立记录组成：每个工作流节点完成时生成一条 `execution_node`，执行结束时生成一条 `execution_chain`。Core 将记录放入有界缓冲区，后台批量发送；Space 将节点重组为执行链路。当前发送端不再使用旧的功能窗口计数或在本地拼装完整链路。

**平台事件没有命中业务路由，或最终命中 `discard`（忽略/丢弃）且没有匹配的插件订阅时，不上报任何执行节点或链路结束记录。** 路由禁用、事件类型或过滤条件不匹配也属于此范围；本地日志和监控仍保留原有行为。主路由未命中但插件事件处理器匹配时，保留实际处理的执行，省略未命中和丢弃旁支的遥测。

命中业务路由后，目标不可用、执行失败、超时或 Pipeline 内部过滤仍可上报。有效交互回调恢复原处理器、WebUI/API 调试及显式指定 Pipeline 的独立调用也可上报；无效回调不会单独取得上报资格。此过滤先于采样和失败兜底，对 Cloud 同样生效。升级 Core 后生效；旧客户端及已有历史记录不受追溯修改。

| 数据    | 内容                                                                                                                                                                        |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 标识与环境 | `instance_id`、`workspace_uuid`、`event_id`、版本、部署版本类型、时间戳、调试标记与采样信息                                                                                                         |
| 执行节点  | 平台事件、路由、Pipeline、Runner、平台 API 和工具调用的操作标识、处理模式、结果、起止时间、父子节点与顺序、路由目标和 Runner 运行标识                                                                                          |
| 链路结束  | 整体结果、关闭原因（`completed` 入站事件及其排队的下游处理全部结束；`merged` 被消息聚合并入另一条链路，附 `merged_into`；`timeout` 已移交的下游处理未在 30 分钟内回报）、耗时、节点数、因采样未上报的节点数、来源、模型名称、适配器、Runner 与管道插件                   |
| 功能使用  | `features` 中按执行累积的整数计数：各来源的工具调用、沙箱执行及错误、知识库检索尝试、技能激活和 LLM 调用尝试（含重试）。零值省略，每项上限为 65,535；这些计数不增加工具参数、输出或技能名称                                                                 |
| 绑定资源  | Pipeline 或 Agent 获准使用的插件、MCP 服务器、知识库、工具及来源、技能、模型、平台 API 的标识或名称，以及资源选择字段、能力与授权标记；实际字段取决于执行路径                                                                               |
| 错误    | 用于排查的完整错误描述：异常类型、异常消息、`Caused by` 原因链及调用栈末尾若干帧的文件、行号与函数名（不含源码行），上限约 4,000 字符，超长时保留首尾。上报前会遮蔽常见凭据形态（`sk-` 密钥、Bearer 令牌、`api_key=`/`token=`/`password=` 等键值、URL 中的密钥参数）和邮箱地址 |

绑定资源表示这次执行被配置或授权使用哪些资源，**不等于实际调用、检索或消耗了这些资源**。路由目标使用 `type:uuid`，不使用用户自定义规则名。

`model_name` 记录一次执行中最先调用的 LLM，覆盖 Pipeline、Agent 和事件处理器路径，并截断至 128 个 UTF-8 字节。功能计数仅附加到已有的链路结束记录；关闭遥测或将 `space.url` 留空时，不计数也不上报。

执行记录不会主动采集消息正文、提示词、模型回复、平台用户或群组 ID、工具/API 参数或结果。**但凭据遮蔽基于常见格式匹配，并非可靠脱敏；异常消息（例如模型服务返回的错误原文）以及自定义的模型、技能或资源名称仍可能含有敏感信息或用户内容。** 实例与工作区标识可能关联到部署或账户，不能将这些记录视为匿名数据或保证不含用户内容。

### 采样与调试执行

社区版通过 `space.execution_trace` 控制执行上报：

| 模式         | 行为                                                                                        |
| ---------- | ----------------------------------------------------------------------------------------- |
| `all`（默认）  | 记录所有符合上报条件的执行的节点和结束记录                                                                     |
| `sampled`  | 根据事件标识的稳定哈希，在入口决定是否采样；成功执行约保留 `1/N`，N 为 `space.execution_trace_sample`（默认 20），同一次执行共享采样决定 |
| `failures` | 普通执行不保留节点，只在失败、取消、超时或有链路失败原因时上报结束记录                                                       |
| `off`      | 关闭节点和链路结束记录；没有继续上报的独立窗口计数，工作区心跳仍由总开关控制                                                    |

`sampled` 未命中的执行如果失败，仍会上报链路结束记录，但不会追补已跳过的节点，因此可能只有摘要而没有完整链路。WebUI 调试执行在 `all`、`sampled` 和 `failures` 下均保留，并带有调试标记；`off` 或总开关关闭后不再上报。

**Cloud 在产品遥测启用时固定使用 `all`**，以避免对成功执行的采样影响活动计数；实例运维方仍可使用 `space.disable_telemetry` 关闭本页所述产品遥测。

### 发送与完整性

记录通过 `POST /api/v1/telemetry` 发送。默认刷新间隔为 180 秒，可通过 `space.telemetry_flush_seconds` 调整。每次刷新最多发送 128 条，内存缓冲最多 512 条；发送成功后才移除对应记录，失败会重试，缓冲满时丢弃最旧记录。停机时尝试在有限时间内发送剩余记录。

网络故障、超时或服务端错误不会使业务执行因遥测失败而报错，上报失败详情记录在 DEBUG 日志中。采样、缓冲溢出、进程退出或跨任务关联失效可能造成不完整链路，**全量模式不保证完整送达**。平台 API 返回成功也不代表用户已阅读消息。

## 心跳、问卷与旧版本数据

活跃工作区在启动约 30 秒后首次发送 `instance_heartbeat`。普通部署此后每天发送，Cloud runtime 每 5 分钟刷新。心跳包含部署平台、数据库/向量数据库类型、沙箱配置与可用性、适配器类型，以及机器人、Pipeline、插件、Agent、事件处理器、事件绑定、MCP、知识库和技能等资源数量；不主动包含资源正文或连接凭据。

自愿参与的应用内问卷会发送问卷 ID、提交的回答、实例 ID、版本及完成/关闭状态。问卷回答是用户主动提供的内容。

Space 仍兼容旧版本的 `query` 和 `feature_execution` 数据。旧查询记录可能含模型名称、功能使用计数、自定义技能/MCP 名称及原始 traceback。当前执行记录的字段限制不会追溯清理这些历史数据，也不会改变仍在运行的旧客户端的上报内容。

## 存储与保留

数据存储在所配置的 Space 服务。执行列表、链路详情和汇总仅供获授权的遥测管理用户或服务客户端访问。`execution_node`、`execution_chain` 及旧 `feature_execution` 原始记录按 30 天窗口定期分批清理；服务中断或积压可能延迟删除。该期限不改变旧查询遥测、心跳、问卷、账户或服务日志的保留规则。

关闭遥测会停止后续上报，但不会删除服务端已有记录。如需处理历史数据，请联系 <hello@langbot.app> 或所用 Space 的管理员。

## 关闭遥测

在 `data/config.yaml` 的现有 `space` 节点中设置以下值，保留其他配置，然后重启 LangBot：

```yaml
space:
  disable_telemetry: true
```

此开关统一关闭本页所述产品遥测，并关闭问卷获取。使用 YAML 布尔值，不要加引号。恢复默认开启状态时，改回 `false` 并重启。

如果部署设置了 `SPACE__DISABLE_TELEMETRY`，该环境变量会在启动时覆盖文件设置；请同时修改或移除它。容器环境变量改变后需要重新创建容器。Cloud 由实例运维方配置，对该实例所有工作区生效。此设置不影响机器人正常运行，也不修改消息平台、模型提供商或插件自身的隐私设置。

Cloud 的 Plugin Runtime 运维健康上报独立于产品遥测，由 `plugin.runtime_ops.enabled` 控制，不能通过 `space.disable_telemetry` 关闭。

参见[系统环境设置](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
> 请先阅读 https://langbot.app/llms.txt ，按照其中的官方指引帮助我部署和使用 LangBot，安装 LangBot CLI，并通过 CLI 配置和管理实例。结合我的目标和环境执行，优先复用已有实例，最后验证目标聊天平台上的真实消息回复。请用中文与我沟通。
> ```

> 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`。这些字段用于标识当前执行所在的实例和工作区，不应作为插件自行鉴权的依据。

重试、超时、数字思考预算、prompt caching、请求头和流式取消见 [LLM 请求配置](https://langbot.app/docs/zh/plugin/dev/apis/llm-requests.md)。

## 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)。

重试、超时、数字思考预算、prompt caching、请求头和流式取消见 [LLM 请求配置](https://langbot.app/docs/zh/plugin/dev/apis/llm-requests.md)。

> info:
>
> 本页大多数方法都需要相应的插件能力：插件在 `manifest.yaml` 中声明，工作区成员在安装后授予。例如 `invoke_llm` 需要 `models.invoke`，`send_message` 需要 `bot.message.send`。未获授权的调用会返回 `permission_denied`。每个方法需要哪项能力，见[插件权限](https://langbot.app/docs/zh/plugin/dev/permissions.md#插件能力)。如需管理 Agent、流水线、机器人等工作区资源，请使用[工作区 API](https://langbot.app/docs/zh/plugin/dev/apis/workspace.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)绑定到本次运行，再导入附件和执行工具。

---

# LLM 请求配置

Source: https://langbot.app/docs/zh/plugin/dev/apis/llm-requests

插件与 Runner 的重试、超时、思考预算、缓存和流式取消

本页对应 [Core #2661](https://github.com/langbot-app/LangBot/pull/2661) 的请求层能力。部署的 Core 必须包含该改动；合并不代表已发布。新配置通过已有的 `extra_args` 传入，不改变插件或 Runner 的方法签名、消息返回类型和权限检查。方法列表见 [LangBot API](https://langbot.app/docs/zh/plugin/dev/apis/common.md)，运行上下文见[上下文 API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md)。

## 重试与超时

以下示例在一次非流式调用中设置请求策略，并读取完整用量：

```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!")],
    timeout=110,
    extra_args={
        "request_policy": {
            "retries": 1,
            "total_timeout": 90,
            "first_event_timeout": 30,
            "stream_idle_timeout": 30,
            "connect_timeout": 10,
            "read_timeout": 60,
        },
    },
)
print(result.message.content)
if result.usage is not None:
    print(result.usage.model_dump())
```

Runner 的 `ctx.api.invoke_llm*` 同样接受 `extra_args`，并受当前运行的授权与剩余时间限制。`self.plugin` 在运行上下文内调用也会绑定这些限制。

`timeout=` 是 SDK/RPC 的等待期限，非流式默认 120 秒；`request_policy` 控制 Core 内部请求。总预算应小于外层 RPC 和 Runner 的剩余期限，增加 Core 预算不会延长外层期限。流式方法没有 `timeout=` 参数，仍受 SDK/Runner 的等待期限约束。

| `request_policy` 字段            | 默认值         | 含义                       |
| ------------------------------ | ----------- | ------------------------ |
| `retries`                      | `0`         | 首次尝试之外的重试次数，整数 0–5       |
| `total_timeout`                | `300`       | 整次调用预算，包含重试等待            |
| `first_event_timeout`          | `120`       | 等待首个上游事件，而非首个可见文字        |
| `stream_idle_timeout`          | `120`       | 流式事件之间允许的空闲时间            |
| `connect_timeout`              | `10`        | 建立连接的超时                  |
| `read_timeout`                 | `120`       | 传输层读取超时                  |
| `write_timeout`                | `30`        | 传输层写入超时                  |
| `pool_timeout`                 | `10`        | 等待连接池的超时                 |
| `backoff_base` / `backoff_max` | `0.5` / `8` | 指数退避基数与上限，使用 full jitter |
| `attribution`                  | `True`      | 自动添加应用身份头                |
| `conversation_header`          | `None`      | 指定生成的会话头名称，见下文           |

时间单位为秒，超时必须是有限正数，未知策略字段会被拒绝。优先级为实例 `llm_request_policy`、模型 `extra_args`、调用 `extra_args`。同层 `request_policy.retries` 优先于旧的 `num_retries` / `max_retries`；调用层旧参数仍可覆盖模型层策略，`0` 禁用重试。旧的数值 `extra_args["timeout"]` 同时设置读取、首事件和流式空闲超时，不延长总预算。

鉴权、非法请求和额度耗尽不重试；收到任何上游事件后（包括思考或 usage）不再重试。`Retry-After` 受剩余总预算约束。Core 关闭托管调用的 LiteLLM 和供应商 SDK 内置重试，中转站仍可能自行重试。这里不增加工具重放、模型回退或 embedding/rerank 重试。旧第三方 requester 仍负责自己的传输配置。

## 思考预算

已有的 `reasoning_level` 保持不变。需要数字预算时，通过 `extra_args.reasoning_config` 设置，省略 `level` 表示 `enabled`：

```json
{
  "reasoning_config": {"budget_tokens": 2048},
  "max_tokens": 4096
}
```

将此对象作为调用的 `extra_args`，或保存到模型高级参数。数字预算不能与 effort 等级（如 `medium`）、`disabled` 或供应商原生思考参数混用。直接调用 Anthropic 时必须显式设置大于预算的 `max_tokens`，Core 不会自动提高输出上限。

配置依次来自模型 `reasoning_config`、模型 `extra_args.reasoning_config`、调用 `extra_args.reasoning_config`、显式 Runner 等级覆盖。每个对象整体替换前一个，后设置的 effort 等级会清除低优先级的预算。

数字预算适用于原生 Anthropic、Gemini 2.5、支持该能力的 Qwen 和 OpenRouter 路由；直接 OpenAI/Codex 及仅支持 adaptive 的 Claude 仍使用 effort。根据模型的 `reasoning_capabilities.budget_tokens` 判断支持情况与上下限，不支持时在发请求前报错。供应商或中转站可能有更严格的限制，OpenRouter 也可能将预算转换为 effort。

## Prompt caching

`extra_args.prompt_caching` 是 Core 配置，不会原样发给供应商。调用配置整体替换模型配置，默认 `{"mode": "provider_default"}` 不添加字段。这不是本地回答缓存。

| 配置                                             | 行为                                                                       |
| ---------------------------------------------- | ------------------------------------------------------------------------ |
| `{"mode": "openai", "retention": "in_memory"}` | 有会话上下文时生成按模型和会话隔离的 `prompt_cache_key`；`retention` 可省略，也可为 `24h`，需要目标模型支持 |
| `{"mode": "anthropic", "ttl": "5m"}`           | 在开头 system/developer 前缀最后一个文本块添加临时缓存标记；`ttl` 可为 `5m` 或 `1h`              |

OpenAI 模式用于支持相关参数的 OpenAI 兼容路由和 OpenRouter OpenAI 模型。显式原生 `prompt_cache_key`、`prompt_cache_retention`、`prompt_cache_options` 优先。Anthropic 模式支持原生 Claude 和 OpenRouter Claude；已有原生缓存标记时不重复添加，不重排工具/历史、不标记用户消息，没有合适的前缀则不添加。

缓存提示不保证命中。使用 `usage.model_dump()` 检查供应商返回的 `prompt_tokens_details.cached_tokens`、`cache_read_input_tokens` 等字段；缺失不等于零。前缀最小长度、保留时间支持与计费由供应商决定。Codex 的受限 Responses 请求不接受此配置对象，保留现有服务端缓存。此改动不包含通用 Responses 迁移或 Gemini 显式缓存资源管理。

## 应用与会话请求头

直连 OpenRouter 时自动添加 `HTTP-Referer: https://langbot.app`、`X-OpenRouter-Title: LangBot`，有会话上下文时还会添加 `x-session-id: lb-<opaque scoped hash>`。自定义中转地址不会自动继承 OpenRouter 身份头。`request_policy.attribution=False` 仅关闭自动应用身份头；显式 `extra_headers` 仍保留，并以不区分大小写的方式优先。

中转站可按其配置显式选择会话头：

```json
{
  "request_policy": {"conversation_header": "x-litellm-session-id"},
  "extra_headers": {
    "HTTP-Referer": "https://langbot.app",
    "X-OpenRouter-Title": "LangBot"
  }
}
```

支持 `x-session-id`、`x-litellm-session-id`、`x-langbot-conversation-id`。最后一个是自定义约定，不是通用供应商标准，不会自动带来路由或缓存收益。生成的值按 workspace/bot/pipeline/session 隔离，不发送原始会话标识或提示词；它是化名标识，不是强匿名保证。没有上下文时不生成。New API 等中转站可能过滤或改写头，需核对其转发配置与实际出站请求。

## 流式取消与兼容性

提前退出异步流时，使用 `aclosing` 确定性关闭生成器，任务取消时也应让取消异常继续传播：

```python
from contextlib import aclosing
from langbot_plugin.api.entities.builtin.provider.message import Message

async with aclosing(self.plugin.invoke_llm_stream_events(
    llm_model_uuid=model_uuid,
    messages=[Message(role="user", content="Hello!")],
    extra_args={"request_policy": {"retries": 0, "total_timeout": 90}},
)) as events:
    async for event in events:
        if event.usage is not None:
            print(event.usage.model_dump())
        if event.chunk is not None and event.chunk.content:
            print(event.chunk.content)
            break
```

此例刻意只消费第一个非空内容块，提前结束可能收不到最终 usage。完整读取时不要 `break`，末尾可能只有 usage 而没有 chunk。`invoke_llm` 仍返回 `Message`，`invoke_llm_stream` 仍返回 `MessageChunk`；需要用量时选择 `invoke_llm_with_usage` 或 `invoke_llm_stream_events`，`usage` 可为 `None`，嵌套缓存、思考和供应商附加字段会保留。

SDK ≤0.7.11 存在代理层提前关闭不及时向上游传播的问题。确定性取消需要实际运行环境使用 **langbot-plugin ≥0.7.12**，该版本已发布 [SDK #177](https://github.com/langbot-app/langbot-plugin-sdk/pull/177) 的修复。Core 固定 SDK 依赖不会自动升级独立部署的 Runtime 或插件自己的开发环境；这些环境也需升级到包含修复的版本。普通调用的签名、参数载荷和返回结构保持兼容。总超时包含消费时间，但生成器停在 `yield` 时不会主动中断消费者，下一次拉取时才检查过期。

## 诊断

Core 监控记录的 `details` 提供 `timing`、完整 `usage` 与结构化 `error`，旧 SDK 的异常传输格式保持不变。结构化错误包含 `code`、`status_code`、`retryable`、`retry_after`、`request_id`、`phase`，不要假定插件收到的旧异常对象具有这些字段。

计时单位为毫秒，包括 `preparation_ms`、`transport_setup_ms`、`first_event_ms`、`first_reasoning_ms`、`first_content_ms`、`first_visible_chunk_ms`、`total_ms`、`attempts` 和 `retry_wait_ms`。首事件可能是思考或控制事件，首个可见块也可能包含思考；`request_started_ms` 是 SDK 调用时间，不是发出网络包的时间。缺失字段代表未观测到，不是零。取消前已收到的部分用量会留在监控中，但无法补出供应商未返回的用量。

---

# 消息平台实体

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()` 可阻止后续插件继续处理当前事件。

#### 在监控中的显示

插件对消息类事件调用 `prevent_default()` 接管消息后，LangBot 的监控页会把这条消息标记为「插件处理 · 作者/插件名」，流水线配置的 Runner 不会再显示为处理者。插件在处理事件时发出的内容也会记入监控：

- `event_context.reply()` 发出的回复，记为这条消息的回复；发送失败会记一条 `PluginReplyError` 错误。
- `self.plugin.send_message()` 发出的消息，记为插件发送的消息；发送失败会记一条 `PluginSendError` 错误。
- `self.plugin.invoke_llm()` / `invoke_llm_stream()` 的调用，记入 LLM 调用记录。

需要插件运行时（`langbot-plugin`）支持事件来源归因，才能把插件发出的消息和 LLM 调用关联到触发它的那条消息；较旧的运行时仍会记录这些内容，但不会关联。在处理函数返回后才执行的后台任务不会关联到原消息。

---

# 平台 API

Source: https://langbot.app/docs/zh/plugin/dev/apis/platform

通过机器人 UUID 调用平台适配器的 API。发送消息链可继续使用 `self.plugin.send_message()`；查询群组、用户及其他平台能力使用下面的接口。

## 发送消息、回复与线程

标准 `send_message` API 返回 `MessageResult`；平台提供消息 ID 时，`message_id` 表示已发送的消息。`self.plugin.send_message()` 返回其序列化字典，因此应读取 `result["message_id"]`，而不是对象属性。平台不返回消息 ID 时，该值可能为 `None` 或空字符串。

使用标准消息组件 `Quote` 表达回复或线程引用：`Quote.id` 为被引用消息或线程根消息的 ID，`origin` 为被引用的消息链，可以为空。具体支持情况和回复／线程行为由适配器决定。例如，Slack 将消息的 `ts` 作为 `message_id` 返回，带 `Quote(id=ts)` 的消息链会发到对应线程，入站频道线程回复的消息链末尾会附加 `Quote(id=thread_ts)`。这些操作使用标准消息 API，而非 Slack 专属 action。

```python
from langbot_plugin.api.entities.builtin.platform.message import MessageChain, Plain, Quote

result = await self.plugin.send_message(
    bot_uuid=bot_uuid,
    target_type="group",
    target_id=group_id,
    message_chain=MessageChain([Plain(text="Support request")]),
)
message_id = result.get("message_id") if result else None
if message_id is not None and message_id != "":
    await self.plugin.send_message(
        bot_uuid=bot_uuid,
        target_type="group",
        target_id=group_id,
        message_chain=MessageChain([
            Plain(text="Follow-up"),
            Quote(id=message_id, origin=MessageChain([])),
        ]),
    )
```

请使用同一机器人、同一会话中的消息 ID。`Quote` 在序列化时保留引用元数据，但不会向 `str(message_chain)` 添加文本，因此不会影响命令或关键词匹配。

## 调用平台 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 进行调试。

---

# 工作区 API

Source: https://langbot.app/docs/zh/plugin/dev/apis/workspace

在插件中读取和管理 Agent、流水线、机器人、模型、知识库等工作区资源。

工作区 API 让插件可以操作它所安装的工作区：列出和修改 Agent 与流水线、查询机器人、管理模型和知识库、读取监控数据等。它开放的操作与 LangBot 的 HTTP API、MCP 服务和工作区助手完全相同，因此成员能通过这些途径完成的事，插件都可以在成员授权的范围内自动完成。

每个操作都有一个稳定的 ID，例如 `pipeline.list` 或 `knowledge.base.retrieve`。插件只能调用自己[在 manifest 中声明](https://langbot.app/docs/zh/plugin/dev/permissions.md#声明权限)、并且已由成员授予该安装的操作。

## 调用操作

在任意组件中通过 `self.plugin.workspace` 调用。每个操作都有一个按 ID 命名、带类型标注的方法：

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


class WorkspaceSummary(Tool):
    async def call(self, params, session, query_id):
        result = await self.plugin.workspace.pipeline.list()
        if not result["ok"]:
            return f"无法获取流水线列表：{result['error']['message']}"

        names = [pipeline["name"] for pipeline in result["result"]]
        return "流水线：" + "、".join(names)
```

方法以关键字参数传参，参数与操作的输入结构一一对应，编辑器里能看到它们的类型和说明。少数名称会被调整为合法的 Python 标识符：如果某一段恰好是 Python 关键字，会在末尾加下划线（例如 `import_`），其他非法字符会替换为下划线。发送时仍使用原始参数名。

如果需要在运行时决定调用哪个操作，可以直接按 ID 调用，效果与类型化方法完全相同：

```python
result = await self.plugin.workspace.call("knowledge.base.retrieve", kb_uuid=kb_uuid, query="退款政策")
```

`await self.plugin.workspace.list()` 返回该安装已获授权的操作及其输入结构，并按 `domains` 分组。可以用它动态生成工具列表，或在提供某项功能前先确认是否已获授权。

### 在运行器中

运行器通过 `ctx.api.workspace` 拿到与本次运行绑定的代理。它提供相同的方法，也由相同的安装授权控制；区别在于 LangBot 会把每次调用记录到当前运行下。

发起本次运行的 Agent 或流水线，可能限定了模型应当看到哪些工作区操作，这个选择通过 `ctx.resources.workspace_operations` 传入。如果运行器要把工作区操作作为工具提供给模型，应当只提供这些操作；列表为空时，一个都不要提供。LangBot 内置的 LocalAgent 就是这样做的。

## 返回结果与错误

工作区调用不会因为业务错误抛出异常，而是始终返回一个字典：

```python
# 成功
{"ok": True, "result": ..., "operation": {"id": "pipeline.list", ...}}

# 失败
{"ok": False, "error": {"code": "permission_denied", "message": "...", "details": {...}}}
```

读取 `result` 之前先检查 `ok`。常见错误码：

| 错误码                 | 含义                                                             |
| ------------------- | -------------------------------------------------------------- |
| `permission_denied` | 该安装没有获得这个操作的授权，或者安装已停用。`details.denied_operations` 列出缺少的操作 ID。 |
| `invalid_input`     | 参数不符合操作的输入结构。                                                  |
| `not_found`         | 引用的资源在当前工作区中不存在。                                               |
| `application_error` | 操作已执行但失败，`message` 中说明原因。                                      |

权限不足是预料之中的情况，因为成员可能只授予插件所声明权限的一部分。遇到时应说明缺少什么，而不是让整个命令或运行失败。

## 选择要声明的操作

每个操作都有风险等级，成员确认时可以看到：

- **读**：只返回数据，例如 `pipeline.list`、`stats.basic`。
- **写**：修改工作区配置，例如 `pipeline.update`、`knowledge.file.store`。
- **高危**：删除资源、影响 LangBot 之外的对象，或消耗大量资源，例如 `bot.delete`、`pipeline.chat.broadcast`。确认对话框会单独标出这类操作。

授予某个操作的成员，自己必须具备该操作要求的权限（见下表最后一列）。只申请插件真正需要的操作；申请大量高危操作，很可能会被拒绝或被删减。

`knowledge.*` 这类通配符会申请某个前缀下的所有操作，但并不是每个前缀都可以这样用，详见[通配符](https://langbot.app/docs/zh/plugin/dev/permissions.md#通配符)。

## 操作列表

下表按领域列出当前 LangBot 版本中插件可以申请的全部操作。方法写作 `workspace.…`：在组件中是 `self.plugin.workspace`，在运行器中是 `ctx.api.workspace`。SDK 的类型化方法就是根据这份目录生成的，因此表中的每个操作都有对应的方法。

### 适配器 (`adapter`)

| 操作    | ID 与方法                                    | 风险 | 授予者需要           |
| ----- | ----------------------------------------- | -- | --------------- |
| 适配器详情 | `adapter.get` `workspace.adapter.get()`   | 读  | `resource.view` |
| 适配器列表 | `adapter.list` `workspace.adapter.list()` | 读  | `resource.view` |

### 智能体 (`agent`)

| 操作      | ID 与方法                                              | 风险 | 授予者需要             |
| ------- | --------------------------------------------------- | -- | ----------------- |
| 创建智能体   | `agent.create` `workspace.agent.create()`           | 写  | `resource.manage` |
| 调试智能体   | `agent.debug` `workspace.agent.debug()`             | 写  | `runtime.operate` |
| 删除智能体   | `agent.delete` `workspace.agent.delete()`           | 高危 | `resource.manage` |
| 智能体详情   | `agent.get` `workspace.agent.get()`                 | 读  | `resource.view`   |
| 智能体列表   | `agent.list` `workspace.agent.list()`               | 读  | `resource.view`   |
| 智能体元数据  | `agent.metadata` `workspace.agent.metadata()`       | 读  | `resource.view`   |
| 运行事件流   | `agent.runs.events` `workspace.agent.runs.events()` | 读  | `resource.view`   |
| 智能体运行列表 | `agent.runs.list` `workspace.agent.runs.list()`     | 读  | `resource.view`   |
| 更新智能体   | `agent.update` `workspace.agent.update()`           | 写  | `resource.manage` |

### 机器人 (`bot`)

| 操作       | ID 与方法                                                            | 风险 | 授予者需要             |
| -------- | ----------------------------------------------------------------- | -- | ----------------- |
| 机器人管理员列表 | `bot.admins.list` `workspace.bot.admins.list()`                   | 读  | `resource.view`   |
| 创建机器人    | `bot.create` `workspace.bot.create()`                             | 写  | `resource.manage` |
| 删除机器人    | `bot.delete` `workspace.bot.delete()`                             | 高危 | `resource.manage` |
| 机器人详情    | `bot.get` `workspace.bot.get()`                                   | 读  | `resource.view`   |
| 应用群组过滤   | `bot.group_filter.apply` `workspace.bot.group_filter.apply()`     | 写  | `resource.manage` |
| 群组过滤预览   | `bot.group_filter.preview` `workspace.bot.group_filter.preview()` | 读  | `resource.manage` |
| 机器人列表    | `bot.list` `workspace.bot.list()`                                 | 读  | `resource.view`   |
| 机器人运行日志  | `bot.logs` `workspace.bot.logs()`                                 | 读  | `resource.view`   |
| 发送机器人消息  | `bot.message.send` `workspace.bot.message.send()`                 | 高危 | `runtime.operate` |
| 测试发送消息   | `bot.message.test` `workspace.bot.message.test()`                 | 写  | `resource.manage` |
| 路由预览     | `bot.routes.preview` `workspace.bot.routes.preview()`             | 读  | `resource.manage` |
| 路由状态     | `bot.routes.status` `workspace.bot.routes.status()`               | 读  | `resource.view`   |
| 机器人运行时状态 | `bot.runtime.get` `workspace.bot.runtime.get()`                   | 读  | `resource.view`   |
| 更新机器人    | `bot.update` `workspace.bot.update()`                             | 写  | `resource.manage` |

### 扩展 (`extension`)

| 操作     | ID 与方法                                        | 风险 | 授予者需要           |
| ------ | --------------------------------------------- | -- | --------------- |
| 扩展全览列表 | `extension.list` `workspace.extension.list()` | 读  | `resource.view` |

### 知识库 (`knowledge`)

| 操作       | ID 与方法                                                                              | 风险 | 授予者需要             |
| -------- | ----------------------------------------------------------------------------------- | -- | ----------------- |
| 创建知识库    | `knowledge.base.create` `workspace.knowledge.base.create()`                         | 写  | `resource.manage` |
| 删除知识库    | `knowledge.base.delete` `workspace.knowledge.base.delete()`                         | 高危 | `resource.manage` |
| 知识库详情    | `knowledge.base.get` `workspace.knowledge.base.get()`                               | 读  | `resource.view`   |
| 知识库列表    | `knowledge.base.list` `workspace.knowledge.base.list()`                             | 读  | `resource.view`   |
| 检索知识库    | `knowledge.base.retrieve` `workspace.knowledge.base.retrieve()`                     | 读  | `resource.view`   |
| 更新知识库    | `knowledge.base.update` `workspace.knowledge.base.update()`                         | 写  | `resource.manage` |
| 引擎创建配置结构 | `knowledge.engine.creation_schema` `workspace.knowledge.engine.creation_schema()`   | 读  | `resource.view`   |
| 知识引擎列表   | `knowledge.engine.list` `workspace.knowledge.engine.list()`                         | 读  | `resource.view`   |
| 引擎检索配置结构 | `knowledge.engine.retrieval_schema` `workspace.knowledge.engine.retrieval_schema()` | 读  | `resource.view`   |
| 删除知识库文件  | `knowledge.file.delete` `workspace.knowledge.file.delete()`                         | 高危 | `resource.manage` |
| 知识库文件列表  | `knowledge.file.list` `workspace.knowledge.file.list()`                             | 读  | `resource.view`   |
| 导入知识库文件  | `knowledge.file.store` `workspace.knowledge.file.store()`                           | 写  | `resource.manage` |
| 文档解析器列表  | `knowledge.parser.list` `workspace.knowledge.parser.list()`                         | 读  | `resource.view`   |

### MCP 服务 (`mcp`)

| 操作         | ID 与方法                                                        | 风险 | 授予者需要             |
| ---------- | ------------------------------------------------------------- | -- | ----------------- |
| MCP资源列表    | `mcp.resource.list` `workspace.mcp.resource.list()`           | 读  | `resource.view`   |
| 读取MCP资源    | `mcp.resource.read` `workspace.mcp.resource.read()`           | 读  | `resource.view`   |
| MCP资源模板列表  | `mcp.resource.templates` `workspace.mcp.resource.templates()` | 读  | `resource.view`   |
| 删除MCP服务    | `mcp.server.delete` `workspace.mcp.server.delete()`           | 高危 | `resource.manage` |
| MCP服务详情    | `mcp.server.get` `workspace.mcp.server.get()`                 | 读  | `resource.view`   |
| MCP服务列表    | `mcp.server.list` `workspace.mcp.server.list()`               | 读  | `resource.view`   |
| MCP服务日志    | `mcp.server.logs` `workspace.mcp.server.logs()`               | 读  | `audit.view`      |
| MCP服务运行时状态 | `mcp.server.runtime` `workspace.mcp.server.runtime()`         | 读  | `resource.view`   |
| 测试MCP服务连接  | `mcp.server.test` `workspace.mcp.server.test()`               | 写  | `resource.manage` |

### 模型 (`model`)

| 操作          | ID 与方法                                                                            | 风险 | 授予者需要                    |
| ----------- | --------------------------------------------------------------------------------- | -- | ------------------------ |
| 创建嵌入模型      | `model.embedding.create` `workspace.model.embedding.create()`                     | 写  | `provider_secret.manage` |
| 删除嵌入模型      | `model.embedding.delete` `workspace.model.embedding.delete()`                     | 高危 | `resource.manage`        |
| 嵌入模型详情      | `model.embedding.get` `workspace.model.embedding.get()`                           | 读  | `resource.view`          |
| 嵌入模型列表      | `model.embedding.list` `workspace.model.embedding.list()`                         | 读  | `resource.view`          |
| 按供应商列出嵌入模型  | `model.embedding.list_by_provider` `workspace.model.embedding.list_by_provider()` | 读  | `resource.view`          |
| 测试嵌入模型      | `model.embedding.test` `workspace.model.embedding.test()`                         | 写  | `provider_secret.manage` |
| 更新嵌入模型      | `model.embedding.update` `workspace.model.embedding.update()`                     | 写  | `provider_secret.manage` |
| 创建大语言模型     | `model.llm.create` `workspace.model.llm.create()`                                 | 写  | `provider_secret.manage` |
| 获取默认LLM模型   | `model.llm.default.get` `workspace.model.llm.default.get()`                       | 读  | `resource.manage`        |
| 删除大语言模型     | `model.llm.delete` `workspace.model.llm.delete()`                                 | 高危 | `resource.manage`        |
| 大语言模型详情     | `model.llm.get` `workspace.model.llm.get()`                                       | 读  | `resource.view`          |
| 大语言模型列表     | `model.llm.list` `workspace.model.llm.list()`                                     | 读  | `resource.view`          |
| 按供应商列出LLM模型 | `model.llm.list_by_provider` `workspace.model.llm.list_by_provider()`             | 读  | `resource.view`          |
| 获取标星LLM模型   | `model.llm.starred.get` `workspace.model.llm.starred.get()`                       | 读  | `resource.view`          |
| 设置标星LLM模型   | `model.llm.starred.set` `workspace.model.llm.starred.set()`                       | 写  | `provider_secret.manage` |
| 测试大语言模型     | `model.llm.test` `workspace.model.llm.test()`                                     | 写  | `provider_secret.manage` |
| 更新大语言模型     | `model.llm.update` `workspace.model.llm.update()`                                 | 写  | `provider_secret.manage` |
| 创建重排模型      | `model.rerank.create` `workspace.model.rerank.create()`                           | 写  | `provider_secret.manage` |
| 删除重排模型      | `model.rerank.delete` `workspace.model.rerank.delete()`                           | 高危 | `resource.manage`        |
| 重排模型详情      | `model.rerank.get` `workspace.model.rerank.get()`                                 | 读  | `resource.view`          |
| 重排模型列表      | `model.rerank.list` `workspace.model.rerank.list()`                               | 读  | `resource.view`          |
| 按供应商列出重排模型  | `model.rerank.list_by_provider` `workspace.model.rerank.list_by_provider()`       | 读  | `resource.view`          |
| 测试重排模型      | `model.rerank.test` `workspace.model.rerank.test()`                               | 写  | `provider_secret.manage` |
| 更新重排模型      | `model.rerank.update` `workspace.model.rerank.update()`                           | 写  | `provider_secret.manage` |

### 监控审计 (`monitoring`)

| 操作       | ID 与方法                                                                  | 风险 | 授予者需要             |
| -------- | ----------------------------------------------------------------------- | -- | ----------------- |
| 嵌入模型调用统计 | `monitoring.embedding_calls` `workspace.monitoring.embedding_calls()`   | 读  | `resource.view`   |
| 错误日志     | `monitoring.errors` `workspace.monitoring.errors()`                     | 读  | `resource.view`   |
| 执行详情     | `monitoring.execution.detail` `workspace.monitoring.execution.detail()` | 读  | `resource.view`   |
| 执行记录列表   | `monitoring.executions` `workspace.monitoring.executions()`             | 读  | `resource.view`   |
| 用户反馈列表   | `monitoring.feedback.list` `workspace.monitoring.feedback.list()`       | 读  | `resource.view`   |
| 用户反馈统计   | `monitoring.feedback.stats` `workspace.monitoring.feedback.stats()`     | 读  | `resource.view`   |
| 进行中任务监控  | `monitoring.inflight` `workspace.monitoring.inflight()`                 | 读  | `resource.view`   |
| 大模型调用统计  | `monitoring.llm_calls` `workspace.monitoring.llm_calls()`               | 读  | `resource.view`   |
| 消息详情     | `monitoring.message.detail` `workspace.monitoring.message.detail()`     | 读  | `resource.view`   |
| 消息历史查询   | `monitoring.messages` `workspace.monitoring.messages()`                 | 读  | `resource.view`   |
| 监控总览     | `monitoring.overview` `workspace.monitoring.overview()`                 | 读  | `resource.view`   |
| 会话分析     | `monitoring.session.analysis` `workspace.monitoring.session.analysis()` | 读  | `resource.view`   |
| 重置会话     | `monitoring.session.reset` `workspace.monitoring.session.reset()`       | 高危 | `resource.manage` |
| 会话列表     | `monitoring.sessions` `workspace.monitoring.sessions()`                 | 读  | `resource.view`   |
| 代币消耗统计   | `monitoring.tokens` `workspace.monitoring.tokens()`                     | 读  | `resource.view`   |
| 工具调用统计   | `monitoring.tool_calls` `workspace.monitoring.tool_calls()`             | 读  | `resource.view`   |

### 流水线 (`pipeline`)

| 操作      | ID 与方法                                                                | 风险 | 授予者需要             |
| ------- | --------------------------------------------------------------------- | -- | ----------------- |
| 广播聊天消息  | `pipeline.chat.broadcast` `workspace.pipeline.chat.broadcast()`       | 高危 | `runtime.operate` |
| 流水线连接状态 | `pipeline.chat.connections` `workspace.pipeline.chat.connections()`   | 读  | `runtime.operate` |
| 流水线聊天历史 | `pipeline.chat.history` `workspace.pipeline.chat.history()`           | 读  | `runtime.operate` |
| 重置聊天会话  | `pipeline.chat.reset` `workspace.pipeline.chat.reset()`               | 高危 | `runtime.operate` |
| 复制流水线   | `pipeline.copy` `workspace.pipeline.copy()`                           | 写  | `resource.manage` |
| 创建流水线   | `pipeline.create` `workspace.pipeline.create()`                       | 写  | `resource.manage` |
| 流水线默认配置 | `pipeline.defaults` `workspace.pipeline.defaults()`                   | 读  | `resource.view`   |
| 删除流水线   | `pipeline.delete` `workspace.pipeline.delete()`                       | 高危 | `resource.manage` |
| 获取流水线扩展 | `pipeline.extensions.get` `workspace.pipeline.extensions.get()`       | 读  | `resource.view`   |
| 更新流水线扩展 | `pipeline.extensions.update` `workspace.pipeline.extensions.update()` | 写  | `resource.manage` |
| 流水线详情   | `pipeline.get` `workspace.pipeline.get()`                             | 读  | `resource.view`   |
| 流水线列表   | `pipeline.list` `workspace.pipeline.list()`                           | 读  | `resource.view`   |
| 流水线元数据  | `pipeline.metadata` `workspace.pipeline.metadata()`                   | 读  | `resource.view`   |
| 执行流水线   | `pipeline.run` `workspace.pipeline.run()`                             | 写  | `runtime.operate` |
| 更新流水线   | `pipeline.update` `workspace.pipeline.update()`                       | 写  | `resource.manage` |

### 插件 (`plugin`)

| 操作          | ID 与方法                                                                | 风险 | 授予者需要             |
| ----------- | --------------------------------------------------------------------- | -- | ----------------- |
| 获取插件配置      | `plugin.config.get` `workspace.plugin.config.get()`                   | 读  | `resource.view`   |
| 插件调试信息      | `plugin.debug_info` `workspace.plugin.debug_info()`                   | 读  | `resource.manage` |
| 插件详情        | `plugin.get` `workspace.plugin.get()`                                 | 读  | `resource.view`   |
| GitHub发布包资源 | `plugin.github.assets` `workspace.plugin.github.assets()`             | 读  | `resource.view`   |
| GitHub发布版本  | `plugin.github.releases` `workspace.plugin.github.releases()`         | 读  | `resource.view`   |
| 从市场安装插件     | `plugin.install.marketplace` `workspace.plugin.install.marketplace()` | 高危 | `resource.manage` |
| 插件列表        | `plugin.list` `workspace.plugin.list()`                               | 读  | `resource.view`   |
| 插件运行日志      | `plugin.logs` `workspace.plugin.logs()`                               | 读  | `audit.view`      |
| 搜索插件市场      | `plugin.marketplace.search` `workspace.plugin.marketplace.search()`   | 读  | `resource.view`   |
| 插件说明文档      | `plugin.readme` `workspace.plugin.readme()`                           | 读  | `resource.view`   |

### 模型供应商 (`provider`)

| 操作        | ID 与方法                                                      | 风险 | 授予者需要                    |
| --------- | ----------------------------------------------------------- | -- | ------------------------ |
| 创建供应商     | `provider.create` `workspace.provider.create()`             | 写  | `provider_secret.manage` |
| 删除供应商     | `provider.delete` `workspace.provider.delete()`             | 高危 | `resource.manage`        |
| 供应商详情     | `provider.get` `workspace.provider.get()`                   | 读  | `resource.view`          |
| 供应商列表     | `provider.list` `workspace.provider.list()`                 | 读  | `resource.view`          |
| 供应商模型数量   | `provider.models.count` `workspace.provider.models.count()` | 读  | `resource.view`          |
| 扫描供应商可用模型 | `provider.models.scan` `workspace.provider.models.scan()`   | 写  | `provider_secret.manage` |
| 更新供应商     | `provider.update` `workspace.provider.update()`             | 写  | `provider_secret.manage` |

### 请求器 (`requester`)

| 操作    | ID 与方法                                        | 风险 | 授予者需要           |
| ----- | --------------------------------------------- | -- | --------------- |
| 请求器详情 | `requester.get` `workspace.requester.get()`   | 读  | `resource.view` |
| 请求器列表 | `requester.list` `workspace.requester.list()` | 读  | `resource.view` |

### 技能 (`skill`)

| 操作         | ID 与方法                                                    | 风险 | 授予者需要             |
| ---------- | --------------------------------------------------------- | -- | ----------------- |
| 创建技能       | `skill.create` `workspace.skill.create()`                 | 写  | `resource.manage` |
| 删除技能       | `skill.delete` `workspace.skill.delete()`                 | 高危 | `resource.manage` |
| 技能文件列表     | `skill.file.list` `workspace.skill.file.list()`           | 读  | `resource.view`   |
| 读取技能文件     | `skill.file.read` `workspace.skill.file.read()`           | 读  | `resource.view`   |
| 写入技能文件     | `skill.file.write` `workspace.skill.file.write()`         | 写  | `resource.manage` |
| 技能详情       | `skill.get` `workspace.skill.get()`                       | 读  | `resource.view`   |
| 预览GitHub技能 | `skill.github.preview` `workspace.skill.github.preview()` | 读  | `resource.manage` |
| 技能列表       | `skill.list` `workspace.skill.list()`                     | 读  | `resource.view`   |
| 重新加载技能     | `skill.reload` `workspace.skill.reload()`                 | 写  | `resource.manage` |
| 更新技能       | `skill.update` `workspace.skill.update()`                 | 写  | `resource.manage` |

### 数据统计 (`stats`)

| 操作     | ID 与方法                                  | 风险 | 授予者需要           |
| ------ | --------------------------------------- | -- | --------------- |
| 基础数据统计 | `stats.basic` `workspace.stats.basic()` | 读  | `resource.view` |

### 任务 (`task`)

| 操作   | ID 与方法                            | 风险 | 授予者需要           |
| ---- | --------------------------------- | -- | --------------- |
| 查询任务 | `task.get` `workspace.task.get()` | 读  | `resource.view` |

### 工具 (`tool`)

| 操作   | ID 与方法                              | 风险 | 授予者需要           |
| ---- | ----------------------------------- | -- | --------------- |
| 工具详情 | `tool.get` `workspace.tool.get()`   | 读  | `resource.view` |
| 工具列表 | `tool.list` `workspace.tool.list()` | 读  | `resource.view` |

### 工作区 (`workspace`)

| 操作    | ID 与方法                                                        | 风险 | 授予者需要            |
| ----- | ------------------------------------------------------------- | -- | ---------------- |
| 工作区语言 | `workspace.language.get` `workspace.workspace.language.get()` | 读  | `workspace.view` |

`workspace.language.get` 返回 `{"language": "zh_Hans", "supported_languages": [...]}`。`language` 是工作区设置中的消息语言（默认 `en_US`），与成员个人的 WebUI 语言无关。插件和 Agent 可据此本地化回复与生成内容；修改语言仍只能由成员操作。

---

# 完善配置信息

Source: https://langbot.app/docs/zh/plugin/dev/basic-info

## 修改清单文件

插件目录下的`manifest.yaml`文件声明了插件的基础信息，这些信息会被展示到 LangBot UI 或插件市场等界面上。

插件级的 `spec.permissions` 列出插件需要的能力和工作区操作，安装后由工作区成员确认，详见[插件权限](https://langbot.app/docs/zh/plugin/dev/permissions.md)。

```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:
  permissions:  # 插件需要的能力和工作区操作，见“插件权限”
    capabilities: []
    workspace_operations: []
  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` 三个核心方法。完整实现可参考官方 [LangRAG 知识引擎](https://github.com/langbot-app/LangBot/tree/master/plugins/KnowledgeEngine/LangRAG)。

```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`方法中实现知识检索逻辑。完整代码可在[official plugins](https://github.com/langbot-app/LangBot/tree/master/plugins)中找到。

```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/tree/master/plugins/misc/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/tree/master/plugins/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 异步插件迁移指南。

---

# 插件权限

Source: https://langbot.app/docs/zh/plugin/dev/permissions

声明插件需要的权限，并了解工作区成员如何授予和撤销这些权限。

插件能做的远不止回复消息：它可以调用模型、读取知识库、通过任意机器人发消息，还能通过[工作区 API](https://langbot.app/docs/zh/plugin/dev/apis/workspace.md) 管理 Agent 和流水线。每个插件安装都运行在某一个工作区里，所以 LangBot 要求插件事先说明自己需要哪些能力，再由工作区成员确认授予。

整个流程分三步：

1. **声明**：插件在 `manifest.yaml` 里列出需要的权限。
2. **确认**：安装后，成员在插件详情页查看所申请的权限，授予全部或其中一部分。确认之前，插件安装保持停用状态。
3. **校验**：插件每次调用时，LangBot 都会检查该安装已获得的授权。超出授权范围的调用会返回 `permission_denied`。

声明权限并不等于获得权限，只有成员确认之后才会生效。

## 声明权限

权限属于整个插件，所以写在 `manifest.yaml` 插件级的 `spec` 下，而不是某个组件里。同一份授权适用于插件的所有组件：命令、事件监听器、工具、知识引擎、解析器和运行器。

```yaml
apiVersion: v1
kind: Plugin
metadata:
  author: acme
  name: WeeklyReport
  version: 1.0.0
spec:
  permissions:
    capabilities:
      - models.invoke      # 调用大模型
      - bot.message.send   # 把周报发到群里
      - storage.plugin     # 记录上次发送时间
    workspace_operations:
      - stats.basic        # 读取工作区统计数据
      - knowledge.*        # 所有知识库操作
  config: []
  components: {}
```

两个列表对应两类不同的访问：

- **`capabilities`（插件能力）**：解锁 `self.plugin` 上的常规 SDK 方法，例如 `invoke_llm`、`send_message`、`set_plugin_storage`。全部 16 项见[下表](#插件能力)。
- **`workspace_operations`（工作区操作）**：解锁[工作区 API](https://langbot.app/docs/zh/plugin/dev/apis/workspace.md) 中的操作。这些操作与 LangBot 的 HTTP API、MCP 服务和工作区助手所用的完全相同，每一项都是一个操作 ID，例如 `pipeline.list`。

只声明插件真正用到的权限。清单越短、越合理，成员越愿意授予；授权范围越小，插件一旦被滥用，造成的影响也越小。

### 严格模式与兼容模式

声明方式决定了插件安装以哪种模式运行：

| manifest 写法               | 模式   | 行为                      |
| ------------------------- | ---- | ----------------------- |
| `permissions:` 下写了一个或两个列表 | 严格模式 | 成员可以授予全部，也可以只授予一部分。     |
| `permissions: {}`         | 严格模式 | 插件不需要任何全局访问权限。          |
| 没有 `permissions` 字段       | 兼容模式 | 按旧版插件处理，见[兼容模式](#兼容模式)。 |

新插件都应该声明权限，哪怕是空集合。

### 通配符

工作区操作可以用 `.*` 结尾，一次申请某个前缀下的全部操作，例如 `knowledge.*` 或 `model.llm.*`。成员确认时，LangBot 会把通配符展开为具体的操作 ID 并保存下来。如果以后的 LangBot 版本在这个前缀下新增了操作，新操作不会自动授予，安装会重新进入待确认状态。

有些操作永远不能授予插件：流式操作、只允许其他调用方使用的操作（例如只有登录成员才能调用的操作），以及完全不通过 API 开放的操作。声明这类操作或未知的 ID 会让权限声明无效。通配符同理：只要前缀下包含这类操作，整个通配符就会被拒绝，所以 `bot.*`、`agent.*`、`pipeline.*`、`plugin.*` 和 `monitoring.*` 都不能用，需要逐个列出，或者改用更窄的前缀。

目前可用的通配符：

- 整个领域：`adapter.*`、`extension.*`、`knowledge.*`、`model.*`、`requester.*`、`stats.*`、`tool.*`
- 更窄的前缀：`agent.runs.*`、`bot.group_filter.*`、`bot.message.*`、`bot.routes.*`、`bot.runtime.*`、`mcp.resource.*`、`monitoring.execution.*`、`monitoring.feedback.*`、`monitoring.message.*`、`monitoring.session.*`、`pipeline.chat.*`、`pipeline.extensions.*`、`plugin.github.*`、`plugin.marketplace.*`、`provider.models.*`、`skill.file.*`，以及 `knowledge.` 和 `model.` 下的所有前缀

插件可以申请的全部操作见[工作区 API 操作列表](https://langbot.app/docs/zh/plugin/dev/apis/workspace.md#操作列表)。

## 插件能力

每项能力解锁一组 SDK 方法。确认这项能力的成员需要具备第三列的工作区权限；最后一列说明成员实际批准的是什么。

| 能力                  | 解锁的 SDK 方法                                                                                                             | 授予者需要                               | 含义                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | --------------------- |
| `langbot.info`      | `get_langbot_version`                                                                                                  | `resource.view`                     | 只读                    |
| `bot.read`          | `get_bots`、`get_bot_info`                                                                                              | `resource.view`                     | 只读                    |
| `bot.message.send`  | `send_message`                                                                                                         | `runtime.operate`                   | 可以给用户和群组发消息           |
| `bot.platform_api`  | `call_platform_api`                                                                                                    | `runtime.operate`、`resource.manage` | **危险**：直接调用 IM 平台原生接口 |
| `models.read`       | `get_llm_models`                                                                                                       | `resource.view`                     | 只读                    |
| `models.invoke`     | `invoke_llm`、`invoke_llm_with_usage`、`invoke_llm_stream`、`invoke_llm_stream_events`、`invoke_embedding`、`invoke_rerank` | `runtime.operate`                   | 消耗模型供应商额度             |
| `storage.plugin`    | `get/set/delete_plugin_storage`、`get_plugin_storage_keys`                                                              | `resource.manage`                   | 读写插件自己的存储             |
| `storage.workspace` | `get/set/delete_workspace_storage`、`get_workspace_storage_keys`                                                        | `resource.manage`                   | 读写所有插件共享的存储           |
| `knowledge.read`    | `list_knowledge_bases`、`retrieve_knowledge`、`get_knowledge_file_stream`                                                | `resource.view`                     | 读取知识库                 |
| `knowledge.vector`  | `vector_upsert`、`vector_search`、`vector_delete`、`vector_list`                                                          | `resource.manage`                   | 写入向量库                 |
| `knowledge.parser`  | `list_parsers`、`invoke_parser`                                                                                         | `runtime.operate`                   | 运行文档解析器               |
| `config.read`       | `get_config_file`                                                                                                      | `resource.view`                     | 读取上传的配置文件             |
| `plugin_tools`      | 对插件工具调用 `list_tools`、`get_tool_detail`、`call_tool`                                                                     | `runtime.operate`                   | 运行其他插件的工具             |
| `mcp`               | 对 MCP 工具调用 `call_tool`                                                                                                 | `runtime.operate`                   | **危险**：运行 MCP 工具      |
| `sandbox`           | `get_box_status`、`list_boxes`、`acquire_box`，以及对沙盒工具调用 `call_tool`                                                      | `runtime.operate`                   | **危险**：在沙盒中执行代码       |
| `plugin.read`       | `list_plugins_manifest`、`list_commands`                                                                                | `resource.view`                     | 列出已安装的插件              |

关于工具有两点需要注意。插件调用其他插件的工具时，那个工具按**它自己**安装的授权运行，而不是按你的授权。另外，能力是按工具来源分别检查的：只有 `plugin_tools` 并不能调用 MCP 工具或沙盒工具。

只作用于插件当前正在处理的事件或运行的调用，不需要任何能力。回复触发事件的会话、读取当前请求的变量、使用 LangBot 提供给运行器的工具，这些都由事件或运行本身授权，与安装授权无关。详见 [Agent 运行 API](https://langbot.app/docs/zh/plugin/dev/apis/agent-run.md) 和[流水线事件 API](https://langbot.app/docs/zh/plugin/dev/apis/pipeline-events.md)。

## 确认插件安装

新安装或升级后需要确认的插件，会在插件列表和详情页上显示 **待授权**，并保持停用。成员打开详情页的 **插件权限**，查看所申请的权限，取消勾选不想授予的项，再点 **授权**。确认对话框会单独标出危险能力和发消息能力。

谁可以确认：

- 只有登录 WebUI 的成员（以及支持管理员）可以新增授权。API Key、`lbctl`、处理器、插件和公开机器人都不行。通过 API Key 或 `lbctl` 安装的插件，需要成员之后在 WebUI 中确认。
- 成员需要 `resource.manage`，以及每项授权各自要求的权限：插件能力看上表，工作区操作看该操作自身的 `permission`。开发者角色拥有 `resource.view`、`resource.manage` 和 `runtime.operate`，因此可以授予所有插件能力；但这并不意味着他们能授予超出自身角色的操作，例如成员管理或 API Key 管理。
- 只要请求中有一项超出成员的权限上限，整个请求都会以 `permission_denied` 失败，响应中的 `denied_operations` 和 `denied_capabilities` 会列出具体是哪些项。LangBot 不会悄悄丢掉其中一部分。

严格模式下，成员可以只授予插件所声明权限中的任意子集，所以插件应当在缺少某项可选权限时平稳降级。

授权属于插件安装，而不属于某个成员。批准授权的成员之后即使换了角色或离开工作区，授权也依然有效。

### 安装时自动确认

初始化向导和流水线迁移在安装官方插件时，会一并确认它们声明的权限。这一步走的是与手动确认完全相同的检查：调用方必须是成员，并具备所有需要的权限。任何一项检查不通过，插件仍会安装，但保持待授权状态。在 HTTP 接口中，这对应 `POST /api/v1/plugins/install/marketplace` 的 `auto_confirm_permissions: true`；默认值为 `false`，API Key 也无法借此跳过成员确认。

### 由插件和 Agent 发起的安装

成员授予相应操作后，插件，或通过工作区工具调用的 Agent、流水线，可以用 `plugin.marketplace.search` 搜索插件市场，并用 `plugin.install.marketplace` 安装插件。安装操作标记为**高危**，为 Agent 或流水线勾选它时会显示敏感工具提示。这类调用方只能从插件市场新增安装：

- 传入 `auto_confirm_permissions: true` 会被拒绝，返回 `permission_denied`。新插件保持禁用，直到成员在插件详情页确认其权限。
- 安装已经安装的插件会失败，返回 `plugin_already_installed`；升级或重新安装仍由成员完成。
- 实例禁用插件市场时，两个操作都会返回 `marketplace_disabled`。
- 不能从 GitHub 或本地文件安装。

安装调用返回 `task_id`。轮询 `task.get`，直到 `status` 为 `succeeded` 或 `failed`；`pending_permission_confirmation: true` 表示插件正在等待成员确认。

## 撤销与升级

具备 `resource.manage` 的成员可以随时撤销授权：取消勾选后保存即可。撤销不需要确认，也不受权限上限限制。API Key 可以撤销，但永远不能新增。

插件升级时：

- 新版本仍然声明的权限，原有授权保留。
- 新版本新增的权限保持未授予，直到成员确认；安装会再次显示 **待授权**。
- 新版本不再声明的权限立即失效。

## 授权与 Agent、流水线设置的关系

在 Agent 或流水线里选择工具，并不会授予任何权限，只是缩小模型能看到的范围。像 LocalAgent 这样的运行器，提供给模型的是两者的交集：Agent（或流水线 **扩展集成** 页面）中选中的工具，与运行器插件安装已获得的操作授权。如果什么都没选，模型就拿不到任何工作区工具。

因此，能编辑 Agent 的成员可以选中一个自己无权授予的工作区操作：除非有足够权限的成员已经把这个操作授予了运行器插件，否则这个选择不会产生任何效果。

## 兼容模式

在插件权限机制出现之前编写的插件没有 `spec.permissions`，LangBot 以兼容模式运行它们：

- 它们获得固定的**全部 16 项旧版插件能力**，**不包含任何工作区操作**。
- 成员必须一次性确认整组能力，不能只确认其中一部分，因为 manifest 里没有信息能说明哪个子集是安全的。确认之后，成员可以逐项撤销。
- 确认需要同时具备 `resource.view`、`resource.manage` 和 `runtime.operate`。
- 以后 LangBot 新增的能力，不会自动加入已经确认过的这组授权。

升级 LangBot 之前就已存在的安装，会在迁移时直接带上这组已确认的授权，并保持原来的启用状态。重新安装兼容模式插件，或者升级这类插件（包括升级到删除了原有权限声明的版本），都会让它停用，直到成员再次确认。

## 处理被拒绝的调用

常规 SDK 方法会抛出错误，错误数据中带有 `code: permission_denied`，必要时还有 `denied_capabilities`。工作区 API 的调用不会抛出异常，而是返回 `{"ok": false, "error": {...}}`，错误码相同。无论哪种情况，都应把权限不足当作正常结果来处理：记录日志、告诉用户缺少哪项权限，然后在没有这项功能的情况下继续运行。

## 通过接口管理权限

WebUI 使用以下接口，你也可以用成员令牌调用：

- `GET /api/v1/plugins/{author}/{plugin_name}/permissions`：返回每一项已声明的权限及其 `granted`、`grantable` 状态，安装是否处于兼容模式或待确认，以及调用者的 `can_manage`、`can_confirm`。工作区操作带有所属的 `domain`，响应中的 `domains` 列出各领域的名称。
- `PUT /api/v1/plugins/{author}/{plugin_name}/permissions`：接收 `workspace_operations`、`capabilities` 和 `confirm`。`confirm: false` 时，列表必须是当前授权的子集，因此这种形式只能用来撤销；`confirm: true` 时适用上文的完整确认规则。
- 插件列表和详情接口的返回中包含 `permission_status`，其中有 `compatibility_mode` 和 `pending_confirmation`。

对应的 Application API 操作是 `plugin.permissions.get` 和 `plugin.permissions.update`。LangBot 的 MCP 服务提供 `get_plugin_permissions` 和 `revoke_plugin_permissions`；使用 API Key 认证的 MCP 客户端不能确认新的授权。

---

# 通过 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`，可由配置项`plugin.display_plugin_debug_url`中的端口覆盖）。
>
> - `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

企业服务已统一为 [LangBot 企业支持订阅](https://langbot.app/docs/zh/enterprise/overview.md)。

查看 [服务范围](https://langbot.app/docs/zh/enterprise/service-scope.md) 与 [采购方式](https://langbot.app/docs/zh/enterprise/procurement.md)，或扫码添加我们的企业微信。

![扫码添加 LangBot 企业微信](https://langbot.app/docs/images/enterprise/wecom-contact.png)

订阅提供有限官方支持，不包含代部署、代运维或定制开发。LangBot 仍按 Apache License 2.0 免费提供，企业无需购买商业使用许可。

---

# 消息平台稳定性

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. 点击**提交**，完成创建。当前版本会自动识别机器人身份。

> warning:
>
> 一键配置会填写应用凭据，不会自动创建卡片模板。开启「使用卡片回复」并填写「卡片模板 ID」即自动启用流式回复；关闭开关即可使用纯文本，无需删除模板 ID；使用按钮、输入框等人工交互，需要按下方步骤导入模板并填写「人工输入卡片模板 ID」。卡片功能还需在钉钉应用的权限管理中开通相应权限。

## 配置卡片模板（推荐使用 LangBot 模板）

使用卡片回复时，推荐直接导入 LangBot 提供的模板，无需自行搭建组件或绑定变量。先在钉钉应用的权限管理中开通卡片相关权限，再按用途选择模板：

| 用途                | 下载文件                             | LangBot 配置字段 |
| ----------------- | -------------------------------- | ------------ |
| 流式回复，分开展示思考与正文    | `dingtalk_stream_card.json`      | 卡片模板 ID      |
| 等待用户填写、选择或确认后继续执行 | `dingtalk_human_input_card.json` | 人工输入卡片模板 ID  |

### 创建并导入流式回复模板

1. 在 LangBot 的钉钉适配器配置中，点击「卡片模板 ID」下方的 **下载流式回复卡片模板**。
2. 打开[钉钉卡片平台](https://open-dev.dingtalk.com/fe/card)，确认组织与机器人应用一致，点击 **新建模板**。
3. 填写模板名称，**卡片类型**选择「消息卡片」，**卡片模板场景**选择「AI 卡片」，**关联应用**选择当前机器人应用，**创建方式**选择「空白搭建」，点击 **创建空白模板**。

![新建模板：消息卡片、AI 卡片、关联机器人应用、空白搭建](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/create_ai_card_template.png)

4. 进入卡片编辑器，在顶部点击 **更多 → 导入卡片模板**，选择下载的 `dingtalk_stream_card.json`。

![在卡片编辑器的更多菜单中导入卡片模板](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/import_card_template.png)

> info:
>
> 导入入口在卡片编辑器内，不在模板列表页。导入会替换当前模板内容，请使用新建的空白模板。保留导入后的组件、变量和事件绑定。

5. 检查预览，**保存并发布**模板，再复制模板 ID。只保存草稿不能发送卡片；`param.templateUnpublished` 表示模板尚未发布。
6. 返回 LangBot，开启 **使用卡片回复**，将 ID 填入 **卡片模板 ID** 并保存机器人配置，即自动启用流式回复。关闭开关后使用纯文本，模板 ID 等配置会隐藏并保留，再次开启即可恢复。

模板带有 LangBot 标识，思考与正文分区展示；思考区在输出时展开，完成后默认折叠，可点击展开。底部提供复制正文、赞／踩以及「内容由 AI 生成」标记。是否删除思考仍由流水线设置控制；删除后不展示思考区。普通消息保留思考时，会显示 `<think>`、`</think>` 标记并用空行分隔正文。

「卡片宽屏自动布局」默认开启，提供的流式回复模板已配置宽屏所需变量。已有机器人如果之前保存为关闭，需要手动开启并保存；如偏好窄卡片，也可关闭。

更新模板时，重新下载并导入最新版，保存并发布。如果新建了另一个模板，还需替换 LangBot 中的模板 ID。现有仅绑定 `content` 的模板仍可使用，但没有新版独立思考区的展示效果。

## 导入人工输入卡片模板

人工输入用于工作流或插件等待用户补充信息、选择选项或确认后再继续的场景，例如 Dify 的人工输入节点。普通聊天、仅展示流式回复不需要配置此模板。

1. 在「人工输入卡片模板 ID」旁点击 **下载人工输入卡片模板**，保存 `dingtalk_human_input_card.json`。
2. 按上方相同步骤，另建一个 **消息卡片 → AI 卡片 → 空白搭建** 模板，并关联当前机器人应用。
3. 在编辑器中选择 **更多 → 导入卡片模板**，导入人工输入 JSON。保留输入框、按钮、变量和事件绑定。
4. **保存并发布**，将此模板的 ID 填入 LangBot 的 **人工输入卡片模板 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)

卡片模板请按上方「配置卡片模板」步骤，直接导入 LangBot 提供的模板并发布。

### 填写配置信息

点击`凭证与基础信息`，记录`Client ID` 和 `Client Secret`。将这两项凭据填写到 LangBot 的适配器配置中。
`markdown_card`（使用卡片回复）统一控制 Markdown 和流式卡片回复。开启且配置模板时自动流式输出，未配置模板时使用普通 Markdown 回复；关闭后使用纯文本，保留模板设置。人工输入卡片用于工作流交互，单独配置。
将以上配置项 记录下来，填到 LangBot 机器人配置表单中。

点击[卡片平台](https://open-dev.dingtalk.com/fe/card?spm=ding_open_doc.document.0.0.33cf2281L0fXsV)模板列表复制绑定的对应的模板id填入卡片模板id

**启动 LangBot** 。

### 添加机器人

本文使用钉钉 windows 桌面版举例，点击上方的`搜索`，`功能`，然后输入刚才机器人创建的名称，如图：
![robot\_png](https://langbot.app/docs/images/zh/deploy/bots/dingtalk/dingtalk5.png)

点击机器人即可和机器人聊天。

如果想要添加到群里，那么点击钉钉群的`群管理`，`机器人`，`添加机器人`，然后搜索机器人名称就可以在群中使用。

## 事件订阅

在钉钉应用后台的「事件订阅」选择 Stream 模式，并勾选需要的事件。机器人收消息与事件订阅是两个入口，只开启机器人 Stream 收消息不会收到群变动事件。

- `chat_add_member` → `group.member_joined`，多人变更逐人触发。
- `chat_remove_member` / `chat_quit` → `group.member_left`，区分移除与主动退出。
- `chat_update_title` / `chat_update_owner` → `group.info_updated`。
- 普通卡片点击或提交 → `dingtalk.card_action`；可识别的点赞反馈仍使用 `feedback.received`，LangBot 管理的人工输入表单继续交给原交互流程，避免重复触发。
- 群解散及其他已订阅事件使用 `platform.specific`，`action` 保留钉钉事件名，`data` 保留原始头部与事件数据。

群事件受钉钉的应用权限和群类型范围限制，并非所有机器人所在群都支持。仅有 unionId、缺少可用用户 ID 的成员通知保留为平台专属事件，不把 unionId 当作可发送消息的用户 ID。消息编辑、撤回、表情反应、好友申请及机器人禁言等尚未确认有对应通用推送，不声明为支持。

---

# 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)中选择 **New Application（新 APP）**。应用名称不要包含 `Discord`，否则门户会拒绝创建。按页面提示完成条款确认和人机验证。

1. 在 **General Information（基本信息）** 复制 **Application ID**。它也是 LangBot 所需的 **客户端 ID**，不是服务器 ID 或频道 ID。
2. 打开 **Bot（机器人）**，点击 **Reset Token（重置令牌）** 并完成验证。令牌只显示一次；将它填写到 LangBot，不要放进截图、代码或公开消息。重置后，旧令牌立即失效，需要同步更新 LangBot。
3. 在 **Privileged Gateway Intents** 开启 **Server Members Intent** 和 **Message Content Intent**，点击 **Save Changes**。新版适配器会请求这两项；**Presence Intent 不需要开启**。

## 连接 LangBot

创建机器人，选择新版 **Discord** 适配器（`discord-omni`），填写客户端 ID 和令牌并保存。

接着配置事件处理：

- **Pipeline**：添加“回复收到的消息”规则，将 `message.received` 绑定到已配置模型的流水线。在机器人的事件路由中设置**触发条件**，按消息文本、会话类型或消息元素筛选。显式事件路由会跳过 Pipeline 内的群响应规则；无条件路由会处理每条收到的消息。“@某人”元素条件匹配提及消息，并不限定被提及者是机器人。
- **Agent**：将事件绑定到 Agent。明确要求 Agent 使用事件回复工具发送消息；单纯生成一段文本不等于已发送。只选择验收或业务实际需要的工具。
- **插件处理器**：在机器人页面单独添加已有插件处理器配置。它按插件声明的事件独立接收事件，可与 Pipeline 或 Agent 同时运行。

需要执行代码或生成文件时，为运行器启用可用的 Box 沙箱。不要为了发送附件而启用无关的 MCP 服务器；未配置凭据的外部工具会造成额外失败。

启用机器人，查看日志中的 `Discord adapter running as ...`。这说明网关已登录，还需要在 Discord 实际发送消息确认路由和回复正常。

## 邀请到测试服务器

在开发者门户的 **OAuth2 → URL Generator** 选择 `bot`，选择 **Guild Install（服务器安装）**。普通消息、图片和文件测试可使用以下权限：

- View Channels（查看频道）
- Send Messages（发送消息）
- Embed Links（嵌入链接）
- Attach Files（添加附件）
- Read Message History（阅读消息历史）
- Add Reactions（添加反应）

复制生成的链接，在浏览器中打开，选定自己的测试服务器后授权。不需要授予 Administrator；成员管理、子区等功能再按需增加权限。频道自身的权限覆盖也必须允许机器人访问和发送消息。

## 检查实际收发

先在服务器频道发送一条符合触发条件的消息，再从机器人的资料卡打开私信。分别检查普通回复、逐步更新的流式回复、图片和文本文件输入，以及返回的真实附件。文件名或下载路径出现在文字中不能代替附件送达。

Discord 单条消息有长度限制，长流式输出需要分段送达。检查最后一段和结束标记，不能仅凭 LangBot 运行日志的“成功”判断内容完整。图片理解需要视觉模型；文件处理需要运行器具备相应工具与沙箱能力。

新版适配器还提供消息编辑、删除、添加/移除表情、成员加入/离开、机器人加入/离开服务器，以及平台特定事件。Pipeline 仅处理消息；其他事件应交给 Agent 或对应插件。平台特定事件中的交互提交来自 LangBot 发出的交互组件，不代表任意 Discord 事件都会透传。

消息事件的 `chat_id` 是频道 ID，`group.id` 是服务器 ID。发送到频道时使用频道 ID，查询或管理服务器成员时使用服务器 ID；两者不能互换。

成员加入/离开事件没有来源频道，回复会发送到服务器配置的 **系统消息频道**。请在 Discord 服务器设置中配置该频道，并授予机器人查看频道、发送消息权限；未配置系统消息频道时，回复会明确失败。成员离开回调无法区分主动退群和被踢，不要将 `is_kicked` 作为可靠的管理判断依据。

![Discord 实际投递：插件原样回传上传的图片和文本文件，随后 Pipeline 私聊回复成功。](https://langbot.app/docs/images/zh/deploy/bots/discord/attachment-roundtrip.jpg)

## 排查问题

- **无法登录网关**：核对最新 Token，并确认两个必需 Intent 已开启且保存；浏览器登录成功不代表机器人 Token 正确。
- **在线但不回复**：核对启用状态、事件路由、处理器模型、群响应规则和频道权限。独立插件订阅与主路由分开检查。
- **附件失败**：同时检查 Discord 的附件权限、运行器日志、Box 状态和附件下载网络；图片 CDN 可达性与网关连接是两回事。
- **网络受限**：LangBot 所在环境必须能够连接 Discord 网关、API 和附件 CDN。按部署环境配置网络代理。
- **文档截图**：不要截取令牌显示页或真实用户的私人消息。
- **旧会话突然出现附件 404**：Discord 附件链接会过期，历史图片也可能让后续纯文本请求失败。重新上传附件，并使用会话上下文重置；安装 EssentialCommands 时可发送 `!reset`（命令前缀以实例配置为准）。重置上下文不删除监控记录。

---

# 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. 点击**提交**，完成创建

### 补充权限和事件订阅

> info:
>
> 扫码创建或授权应用后，应用权限和事件订阅可能尚未覆盖你要使用的全部功能。能正常收发消息，不代表已经订阅了成员进退群等事件。无需重新创建机器人，可以到开发者平台为现有应用补充配置。

1. 打开[飞书开发者平台](https://open.feishu.cn/app)（海外版使用 [Lark 开发者平台](https://open.larksuite.com/app)），选择扫码时创建或授权的应用，可通过 App ID 核对。
2. 在**权限管理**中，按需要添加功能所需的权限。应用权限决定机器人可以读取哪些数据、执行哪些操作。
3. 在**事件与回调 > 事件配置**中，添加需要接收的事件。事件订阅决定飞书会向 LangBot 推送哪些通知；仅添加权限不会自动订阅事件。
4. 按平台提示保存配置，并完成所需的版本发布或管理员审批。配置生效后，再触发一次事件验证，之前的操作不会因补充订阅而自动重放。

> warning:
>
> **添加事件后，别忘记发布应用新版本。** 在开发者平台的**版本管理与发布**中完成发布；如需管理员审批，还需等待审批通过。仅在配置页添加并保存事件，待发布的配置尚未生效，即使 LangBot 显示连接正常，也可能收不到这些事件。

如果添加订阅后仍收不到成员进退群等事件，先检查应用是否还有**待发布或待审批**的变更。确认新版本生效后，在机器人所在群内重新操作一次成员进群或退群，再查看 LangBot 的事件记录。

例如，监听群成员变化需要订阅以下两个事件，且机器人需要在对应群聊中：

| 功能           | 飞书事件                             |
| ------------ | -------------------------------- |
| 用户进群         | `im.chat.member.user.added_v1`   |
| 用户主动退群或被移出群聊 | `im.chat.member.user.deleted_v1` |

“机器人进群”是另一个事件（`im.chat.member.bot.added_v1`），只订阅它不会收到其他成员的进退群通知。订阅生效后，还需要在 LangBot 的**事件路由**中将对应事件交给 Agent 或插件处理器；流水线只处理消息事件。

***

## 手动配置

### 创建机器人

前往[飞书开放平台](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` ，点击确定配置。如果回调地址保存成功，那么意味着部署成功。若出现 `校验失败` 字样，请认真检查上述配置项是否填写正确。

## 群聊回复与 At 组件

在 QQ Official Omni 的机器人配置中，`启用 Markdown 渲染` 默认关闭。普通文本群聊回复不会输出 At 组件的原始标签；At 与正文仍合并处理，回复保留原消息的 `msg_id`。这不保证 QQ 客户端产生 @ 提醒。

需要显式 @ 群成员时，请先确认机器人已获得 QQ 的 Markdown 消息权限，再开启该选项。Markdown 回复使用发送者的原始 OpenID 生成原生 At 标签；显示名或 QQ 号码不能代替 OpenID。部分客户端对标签的解析存在差异，需要在实际 QQ 客户端验收。LangBot 不会为实现 At 自动切换到可能无权限的 Markdown 模式。

QQ 的[文本交互文档](https://bot.q.qq.com/wiki/develop/api-v2/server-inter/message/trans/text-chain.html)声明普通文本也支持 At，但已有[适配器实测反馈](https://github.com/nonebot/adapter-qq/issues/220)及用户验收发现普通文本会原样显示标签。因此 LangBot 对普通文本群聊采用上述兼容处理。

## 发布方式

进入 `首页` 的发布流程 ，按照流程进行机器人发布，上线。

---

# 机器人 (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 快速配置** 创建应用。LangBot 会自动配置机器人权限、消息事件、消息页和 OAuth 返回地址；你只需提供配置令牌、在 Slack 确认安装，并在长连接模式下补充 App-Level Token。

### 1. 创建机器人并选择接入方式

在 LangBot 的 **机器人 → 创建机器人** 中填写名称，选择 **Slack**，提交后进入配置页。选择接入方式，然后点击 **Slack 快速配置 → 开始**：

![创建机器人并选择 Slack 适配器](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-create-bot.jpg)

- **长连接（Socket Mode，推荐）**：LangBot 主动连接 Slack，无需公网事件 Webhook，适合本地或内网部署。
- **Webhook**：Slack 向 LangBot 推送事件，需要可从公网访问的 HTTPS 地址。

![选择长连接并打开 Slack 快速配置](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-connection-mode.jpg)

### 2. 获取 App Configuration Tokens

打开 [Slack 应用页面](https://api.slack.com/apps)，找到 **Your App Configuration Tokens**，点击 **Generate Token**，选择目标工作区。分别复制 **Access Token** 和 **Refresh Token**；已有令牌时，可以直接使用对应的复制按钮。

![Slack 配置令牌入口与复制按钮](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-configuration-tokens.jpg)

这两个令牌用于创建和配置应用，**不是机器人运行时使用的 Bot Token 或 App-Level Token**。在助手中分别填入对应字段，并确认应用名称。

### 3. 确认地址并自动创建应用

长连接模式下，确认 **OAuth 授权返回地址**。它用于授权完成后让浏览器返回 LangBot，支持 HTTPS 或 `http://localhost`，末尾为 `/api/v1/platform/adapters/slack/setup/callback`。只需你的浏览器能访问这个地址；它不是接收消息的 Webhook。远程部署时，不要填写浏览器所在电脑无法访问的服务器内部地址。

![长连接快速配置表单](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-socket-mode.jpg)

Webhook 模式下，助手显示的是 **Webhook 回调地址**。确认域名、HTTPS 和反向代理均可用，保留 `/bots/<机器人 UUID>` 后缀。LangBot 会从该地址生成 OAuth 返回地址，并自动完成 Slack 的事件地址验证。

点击 **创建并自动配置**，等待出现 **前往 Slack 授权**。

### 4. 在 Slack 安装授权

点击 **前往 Slack 授权**，核对应用名称、工作区和权限，然后点击 **Allow**。工作区策略可能要求管理员批准。完成后返回原来的 LangBot 配置助手。

![Slack 安装授权页面](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-slack-permissions.jpg)

### 5. 长连接模式：补充 App-Level Token

Webhook 模式可跳过本步。长连接模式中，点击助手的 **打开应用设置**，进入 **Basic Information → App-Level Tokens → Generate Token and Scopes**：

1. 填写 Token Name，例如 `langbot-socket`。
2. 点击 **Add Scope**，选择 **connections:write**。
3. 点击 **Generate**，复制生成的 `xapp-` 令牌，填回助手的 **App-Level Token**。

![为 App-Level Token 添加 connections:write 权限](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-app-token-scope.jpg)

不需要开启 **Token rotation**。这里必须使用刚创建的同一个 Slack 应用的令牌，不能填入第 2 步的 Access Token 或 Refresh Token。

### 6. 回填配置、设置路由并启用

助手显示 **授权完成** 后，点击 **填入适配器配置**。长连接模式需先填入 App-Level Token，此按钮才可用。Bot Token 等适配器凭据会自动回填。

![授权完成并回填适配器配置](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-authorized.jpg)

在 **事件路由 → 添加行为 → 回复收到的消息** 中，为 `message.received` 选择已配置好的流水线或 Agent，并保持该路由启用。最后点击页面右上角 **保存并启用**。

![配置收到消息的路由并保存启用](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-routing.jpg)

### 7. 验证对话

在 Slack 中打开应用的 **Messages** 页面，发送一条私聊消息。也可以将机器人加入频道后 @ 它。收到回复即表示接入成功。

![Slack 机器人成功回复消息](https://langbot.app/docs/images/zh/deploy/bots/slack/setup-conversation.png)

> info:
>
> 配置令牌仅在短期配置会话中使用，不作为机器人运行凭据保存。会话有效期为 15 分钟；取消助手不会删除已创建的 Slack 应用。重新开始可能创建另一个应用，请勿因为授权返回页显示异常就反复创建，先检查原助手是否已显示“授权完成”。

如果没有回复，先确认机器人及消息路由已启用、处理器本身能够正常运行，并查看机器人日志。长连接模式检查 App-Level Token 是否属于同一应用且包含 `connections:write`；Webhook 模式检查公网地址和 Slack 的 **Verified** 状态。

## 事件、交互与已有应用升级

新版快速配置向导会自动配置下列事件订阅和交互入口。安装授权页会申请消息、频道、用户、文件和表情反应权限，其中 `reactions:read` 用于表情反应事件。在本机器人发起的 thread 中回复无需 @ 机器人；其他频道消息仍需 @。接收这些 thread 回复需要订阅 `message.channels` 并授权 `channels:history`；私有频道还需要 `message.groups` 和 `groups:history`。添加权限后需重新安装 Slack 应用。

派发 thread 回复不等于 @ 机器人。没有 @ 的回复仍可供插件处理，但不会满足默认流水线基于 @ 的群响应条件。

| Slack 事件                                                                    | LangBot 事件                                                  |
| --------------------------------------------------------------------------- | ----------------------------------------------------------- |
| 私聊消息、`app_mention`、本机器人发起的 thread 中的回复                                      | `message.received`                                          |
| `message_changed` / `message_deleted` 消息子类型                                 | `message.edited` / `message.deleted`                        |
| `reaction_added` / `reaction_removed`                                       | `message.reaction`，通过 `is_add` 区分                           |
| `member_joined_channel` / `member_left_channel`                             | `group.member_joined` / `group.member_left`                 |
| 上述成员事件中的机器人自身                                                               | 有邀请者时为 `bot.invited_to_group`；离开时为 `bot.removed_from_group` |
| 频道重命名、归档/取消归档、主题/用途变化                                                       | `group.info_updated`                                        |
| `block_actions`、`view_submission`、`view_closed`、`shortcut`、`message_action` | `platform.specific`，`action` 为 `slack.` 加回调类型               |
| `app_home_opened`、`app_uninstalled`、`tokens_revoked`                        | `platform.specific`，`action` 为 `slack.` 加事件类型               |

在机器人的事件路由中为所需事件配置处理器；平台事件可按 `action` 区分。卸载和令牌撤销同时写入机器人警告日志，不自动发送聊天回复。表情反应是普通反应事件，不自动视为对模型的反馈。消息 ID 使用 Slack 消息时间戳 `ts`，需结合频道识别；线程回复保留 `thread_ts`。

交互回调先确认接收，再异步交给处理器；目前不支持在表单提交确认中同步返回字段校验错误，也不提供外部下拉选项加载。接收 `view_closed` 需要创建弹窗时设置 `notify_on_close: true`。回调不会自动创建按钮、快捷方式或弹窗。Socket Mode 和 Webhook 均支持上述接收逻辑，但实际投递受 Slack 授权、频道成员关系及连接状态限制。

**已有应用不会因升级 LangBot 自动获得新权限。** 无需重新创建应用，按以下步骤补齐：

1. 在 **OAuth & Permissions → Bot Token Scopes** 保留原权限，增加 `reactions:read`；确认包含 `app_mentions:read`、`chat:write`、`channels:history`、`channels:read`、`groups:history`、`groups:read`、`im:history`、`im:read`、`im:write`、`mpim:history`、`mpim:read`、`users:read`、`files:read`、`files:write`，然后 **Reinstall to Workspace** 重新授权。
2. 在 **Event Subscriptions → Subscribe to bot events** 配置：`app_mention`、`message.im`、`message.channels`、`message.groups`、`message.mpim`、`reaction_added`、`reaction_removed`、`member_joined_channel`、`member_left_channel`、`channel_rename`、`group_rename`、`channel_archive`、`channel_unarchive`、`group_archive`、`group_unarchive`、`app_home_opened`、`app_uninstalled`、`tokens_revoked`。编辑/删除、主题/用途变化属于消息子类型，无需单独订阅。
3. 在 **Interactivity & Shortcuts** 启用交互。Webhook 模式的 **Request URL** 与事件订阅使用同一个 LangBot `/bots/<机器人 UUID>` 地址；Socket Mode 不需要公网交互地址。
4. 保存 Slack 设置，在 LangBot 配置相应事件路由。若重新安装后 Bot Token 改变，回填新值并保存机器人。

字段定义参考 [Slack App Manifest](https://docs.slack.dev/reference/app-manifest/)。

## 使用标准消息 API 操作 thread

使用 `send_message`、`reply_message` 和标准消息组件：

- `send_message` 返回 `MessageResult`，其 `message_id` 为第一条发出消息的 Slack `ts`；文本后附文件时也取第一条消息。保存此 ID 即可在该消息下创建 thread。
- 出站消息链加入 `Quote(id=message_id, origin=MessageChain([]))`，文本和文件都会发到该 thread。取第一个 ID 非空的 Quote，优先于 `reply_message` 的来源 thread 或 `quote_origin` 选择，且不发送其 origin 内容。没有显式 Quote ID 时，原有发送和回复行为不变。
- 入站频道 thread 回复带有 `Quote(id=thread_ts, group_id=channel, target_id=channel, origin=MessageChain([]))`，当前消息 ID 仍在 `Source.id` 中。thread 根消息和非 thread 消息不带此 Quote，插件可直接从消息链读取父消息 ID，无需另查上下文。

## 手动配置（Webhook）

下方截图展示基础对话配置；完整权限、事件订阅和交互配置请使用上方“事件、交互与已有应用升级”中的最新清单。

下面保留手动 Webhook 配置步骤。若手动使用长连接，请在 Slack 开启 Socket Mode，填写 Bot Token 和 App-Level Token，并订阅 `app_mention` 和 `message.im`；无需配置事件 Request URL。

### 创建机器人

前往 [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:
>
> Webhook 模式要求公网 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 打开官方 [BotFather](https://t.me/BotFather)，发送 `/newbot`，依次设置名称和以 `bot` 结尾的用户名。保存 BotFather 返回的 Token，不要把它发到群里或放入截图。

本文适用于 LangBot 4.11 的新版 Telegram 适配器（内部名称 `telegram-omni`）。不要选择标记为过时的旧版适配器。

## 配置并启用

1. 在 LangBot 配置可用的模型供应商和模型，再创建 Pipeline、Agent 或插件处理器。
2. 在「机器人」中新建机器人，选择 Telegram，填写 Token。
3. 为 `message.received` 配置消息处理器。Pipeline 适合现有对话流程；Agent 通过事件与工具处理任务。插件处理器也可以独立订阅事件。
4. 根据需要打开 Markdown 和流式回复，启用机器人并保存。修改处理器绑定后也要保存。
5. 在 Telegram 私聊机器人，点击 **Start**，发送一条测试消息；同时在 LangBot 的处理器运行记录中检查状态和回复工具结果。

适配器通过长轮询连接 Telegram，需要 LangBot 所在环境能访问 `api.telegram.org`。不需要为收消息额外暴露入站 Webhook。一个 Token 只应由一个轮询实例使用；不要同时在另一套 LangBot 中启用同一个机器人。

### 选择处理器

| 方式       | 配置与检查                                                                   |
| -------- | ----------------------------------------------------------------------- |
| Pipeline | 配置模型和触发条件。群聊的 @、前缀等触发条件仍需满足；开启流式回复后，支持流式的处理器可逐步更新 Telegram 消息。          |
| Agent    | 配置模型、指令及事件工具。要求 Agent 使用 `event_reply` 等工具回复；模型生成了文本不等于消息已发送到 Telegram。 |
| 插件处理器    | 安装并创建相应插件处理器，将它绑定到机器人并保存。独立订阅可与主处理器并行，因此同一条消息可能产生两份回复。                  |

需要读写附件时，为相应处理器启用 Box，并使用其沙盒工具和附件发送能力。Box 必须处于可用状态。外部文件系统 MCP 与 Box 不是同一个文件系统。图片理解还需要支持视觉的模型。

机器人上的流式开关不会把所有工具调用都变成逐字输出。Agent 的一次 `event_reply` 是一次完整发送；插件是否流式取决于插件实现。请分别核对 Telegram 中的实际更新和处理器日志，不能只看开关。

## 私聊与群聊

私聊应先点击 **Start**。群聊则先把机器人加入测试群，再按处理器触发规则发送消息，例如发给机器人的命令或回复机器人的消息。

不必为了所有群聊场景都关闭 **Privacy Mode**。隐私模式会影响 Telegram 向机器人投递哪些消息；定向命令、回复和管理员身份的行为与普通群消息不同。如果需要接收群内普通消息，可以在 BotFather 中调整隐私模式，按 Telegram 的提示重新添加机器人，或按需要授予管理员身份。详见 [Telegram 官方隐私模式说明](https://core.telegram.org/bots/features#privacy-mode)。

接收成员状态、表情等更新时，需要满足 Telegram 对相应更新的管理员要求。只授予实际功能需要的权限；不要为了接收事件直接打开删除消息、封禁成员、添加管理员等全部权限。Telegram 侧投递规则和 LangBot 处理器触发条件需要同时满足。

普通群升级为超级群后，群 ID 会改变。事件日志中的 Bot API 群 ID 与 Telegram Web 地址栏中的 ID 也不一定相同，不要直接从网页地址拼接群 ID。

## 图片、文件与流式回复

图片和文件可以作为消息附件进入处理器。测试时发送带有明确问题的图片、内容可校验的文本文件，并检查真实返回的图片或文件，而不仅是“已发送”的文本。

流式文本在 Telegram 中通过持续更新消息展示；附件在结束时单独发送。生成文件必须使用处理器提供的附件输出机制，不能只返回沙盒路径。Telegram 无法作为照片处理的图片会尝试以文件发送，便于保留原始内容。

![真实群聊验收：Agent 识别图片、读取文件并返回文件和生成的图片。](https://langbot.app/docs/images/telegram/agent-group-media.jpg)

## 其他事件

在机器人中为所需事件绑定 Agent 或插件处理器。Pipeline 主要用于消息流程，不应把所有非消息事件都当作普通聊天测试。

| 事件                       | 触发与含义                                          |
| ------------------------ | ---------------------------------------------- |
| `message.received`       | 收到私聊或群聊消息，包括支持的附件。                             |
| `message.edited`         | 编辑已发送的消息。                                      |
| `message.reaction`       | 用户新增或移除消息表情；`is_add` 区分方向，`reaction` 保留被移除的表情。 |
| `group.member_joined`    | 成员加入群。                                         |
| `group.member_left`      | 成员离开或被移出；检查 `is_kicked`。                       |
| `group.member_banned`    | 成员权限受到限制，例如禁言；不代表成员已被移出。                       |
| `bot.invited_to_group`   | 机器人被加入群。                                       |
| `bot.removed_from_group` | 机器人被移出群，包括此前处于受限状态的机器人。                        |
| `bot.muted`              | 机器人失去发送消息权限。永久限制的 `duration` 为 `null`。         |
| `bot.unmuted`            | 机器人恢复发送消息权限，即使仍受其他权限限制。                        |
| `platform.specific`      | 其他平台事件，例如权限状态变化或回调。根据 `action` 和 `data` 处理。    |

先用只记录事件的插件处理器确认投递，再添加回复或管理操作。机器人被禁言或移出时，收到事件并不意味着仍有权限在原群回复。权限不足的发送失败应与事件接收成功分别判断。

## 排查问题

- **无响应**：检查机器人启用状态、保存后的绑定、私聊 Start、群隐私模式和触发规则，然后查看对应处理器运行记录。
- **消息发出了但运行失败**：展开运行记录核对工具返回值；仅有 Telegram 消息不是整次任务成功的证明。
- **模型报错或超时**：检查供应商和模型。上游模型错误与 Telegram 投递问题分别排查。
- **附件只有路径**：检查 Box、模型工具权限，以及是否真正调用了附件发送工具。
- **重复回复**：检查主处理器与独立订阅是否同时处理同一事件，以及是否有多个轮询实例。
- **收不到表情或成员事件**：检查机器人管理员身份和事件绑定；先在专用测试群操作，避免影响真实成员。

---

# 页面机器人

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)

点击`企业创建的`,选择创建的机器人，进入聊天界面。

同理，若想邀请机器人进入群聊，那么点击群聊的添加人员，在其中添加机器人。

### 编排事件

新版企业微信智能机器人适配器在长连接和 Webhook 模式下均提供以下业务事件，可在机器人的事件路由中分别选择处理器：

| 事件                             | 使用场景与数据                                                                           |
| ------------------------------ | --------------------------------------------------------------------------------- |
| `message.received`             | 收到用户消息，进入日常问答或任务处理流程。                                                             |
| `wecombot.enter_chat`          | 用户进入机器人会话，可触发欢迎和使用引导。包含用户、会话 ID 和原始事件数据。                                          |
| `wecombot.template_card_event` | 用户点击或提交模板卡片，可按 `task_id`、`event_key` 或 `selected_items` 分支处理。包含卡片类型、用户、会话和原始事件数据。 |
| `feedback.received`            | 用户对机器人回复提交反馈，可用于评价收集。                                                             |

进入会话事件由企业微信推送，不代表添加好友。欢迎语必须在平台的 5 秒窗口内完成，建议使用快速、固定的文本；通过事件回复发送文本时，LangBot 会使用专用欢迎语接口，超时会明确报错。不要依赖耗时的模型调用生成欢迎语。

LangBot 交互表单和 Dify 表单的卡片回调继续由原有交互流程处理，不会同时触发模板卡片业务事件。连接、鉴权和重连等底层状态不作为编排事件。

### 效果图

![效果图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，重新启动。

## 获取客服链接和二维码

完成回调配置后，还需要获取供微信用户发起咨询的入口。

1. 回到[微信客服后台](https://kf.weixin.qq.com/kf)，进入`客服帐号`，创建或选择需要接入 LangBot 的客服帐号。
2. 打开该帐号的接入页面，向下找到`在微信外App/网页中接入`，点击`去接入`。

![在微信外 App 或网页中接入微信客服](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/customer-service-entry.png)

3. 在接入页面顶部找到对应的客服帐号。点击`复制链接`可获取客服咨询链接，点击`生成二维码`可查看该帐号的咨询二维码。

![复制客服链接或生成二维码](https://langbot.app/docs/images/zh/deploy/bots/wecom/wecomcs/customer-service-link.png)

> info:
>
> 截图中的客服链接仅作示例，请使用自己帐号生成的链接或二维码。Webhook 回调地址用于微信向 LangBot 推送消息，客服链接和二维码用于用户发起咨询。

## 扫码测试

1. 确认 LangBot 中的机器人已启用，并在`事件路由`中将`收到消息`交给需要使用的处理器。
2. 使用普通微信扫描刚生成的二维码，进入客服会话后发送一条消息。
3. 在 LangBot 中查看机器人的日志、会话监控及对应处理器的运行日志，确认消息已接收并处理，再检查微信中是否收到回复。

如果只是扫码测试，获取二维码后即可发起咨询，无需继续配置页面下方的 App 关联。

## 可路由的事件

在机器人的「事件路由」中，可以分别为以下事件选择处理器。普通消息可交给流水线或 Agent；其他事件可交给支持相应事件的 Agent 或插件处理器。

| 事件                | 事件类型                                        |
| ----------------- | ------------------------------------------- |
| 收到消息              | `message.received`                          |
| 客户或接待人员撤回消息       | `message.deleted`                           |
| 客户通过链接进入会话        | `wecomcs.enter_session`                     |
| 客服消息发送失败          | `wecomcs.msg_send_fail`                     |
| 接待人员状态变更          | `wecomcs.servicer_status_change`            |
| 客服会话接入、转接、结束或重新接入 | `wecomcs.session_status_change`             |
| 拒收客户消息设置变更        | `wecomcs.reject_customer_msg_switch_change` |

撤回事件包含原消息 ID、操作者和会话 ID。客服专属事件保留客服帐号、客户及事件相关字段，例如 `welcome_code`、`fail_type` 和 `change_type`；处理器可按字段决定后续操作。未知事件仍通过 `platform.specific` 保留原始数据。

进入会话事件只在客户通过客服链接进入时触发，从已有聊天列表打开会话不会触发。接入事件不等于自动发送欢迎语，仍需配置相应处理逻辑。

### 回复窗口与欢迎语

- 普通消息回复要求客户先主动发消息，且在 48 小时内回复；仅进入会话不会开启此窗口。错误码 `95002` 表示不满足发送时间限制。
- Agent 的 `event_reply` 在进入会话事件中使用专用事件回复接口和 `welcome_code`，不会当作普通消息发送。微信只在符合欢迎语条件时提供此凭据，每个凭据只能发送一条消息，有效期仅 20 秒。建议使用快速固定文案，避免等待耗时较长的模型生成。
- 会话状态变化事件的 `event_reply` 使用 `msg_code`，仍受凭据有效期和当前会话状态限制。当前事件回复支持文本；凭据缺失、过期或已使用时无法补发，重新执行旧事件不能延长有效期。

详见微信官方的[发送消息](https://developer.work.weixin.qq.com/document/path/94677)和[发送事件响应消息](https://developer.work.weixin.qq.com/document/path/95122)。

---

# 微信公众号

Source: https://langbot.app/docs/zh/usage/platforms/wxoa

通过微信开发者平台配置消息推送，将微信公众号接入 LangBot。

本教程使用微信公众平台完成账号注册和主体实名认证，在微信开发者平台配置应用密钥、消息推送和 API IP 白名单。

## 1. 注册公众号并完成主体实名认证

进入[微信公众平台](https://mp.weixin.qq.com/)。已有公众号可直接扫码登录；尚未注册时，点击「立即注册」，选择「公众号」，按提示完成注册。

进入「设置与开发 → 账号设置 → 账号详情」，找到页面底部的「主体信息」，点击「详情」。如果显示「待完善」，请先完成主体信息。

![账号详情页面底部的主体信息入口](https://langbot.app/docs/images/zh/deploy/bots/wxoa/account-details.png)

在主体信息页面点击「实名验证」，按照微信提示完成实名认证。

![主体信息页面的实名验证按钮](https://langbot.app/docs/images/zh/deploy/bots/wxoa/identity-verification.png)

> info:
>
> 这里需要完成的是「主体信息」中的实名验证。账号详情中还有「申请微信认证」「个人认证」等入口，请按截图进入主体信息页面操作。

## 2. 获取应用信息并创建 LangBot 机器人

前往[微信开发者平台](https://developers.weixin.qq.com/platform)，进入公众号设置，选择要接入的公众号，打开「基础信息」。页面包含 AppID、「开发密钥」以及「域名与消息推送配置」。

![微信开发者平台的公众号基础信息、开发密钥及消息推送入口](https://langbot.app/docs/images/zh/deploy/bots/wxoa/developer-platform.png)

在 LangBot 中新建机器人，选择「微信公众号」适配器，进入机器人配置页：

1. 复制微信开发者平台中的 **AppID**，填写到 LangBot 的「应用 ID」。
2. 在微信开发者平台的「开发密钥」区域点击 AppSecret 的「重置」，按提示获取密钥，填写到 LangBot 的「应用密钥」。首次使用时，如果按钮显示为「启用」，先按提示启用 AppSecret。
3. 点击 LangBot 的「保存并启用」，保存机器人并启用。

下面是 LangBot 适配器配置区域。图中的「令牌」和「消息加解密密钥」会在下一步与微信平台一起配置。

![LangBot 微信公众号适配器的回调地址及配置字段](https://langbot.app/docs/images/zh/deploy/bots/wxoa/langbot-adapter-settings.png)

## 3. 启用消息推送并配置回调

回到微信开发者平台，在「基础信息」页面下方的「域名与消息推送配置」区域，点击「消息推送」旁的「启用」。

在「配置消息推送」弹窗中按以下顺序填写，暂时不要点击「确定」：

1. **URL**：复制 LangBot 机器人配置页显示的完整「Webhook 回调地址」并粘贴。地址通常为 `https://你的域名/bots/机器人UUID`，请保留完整路径。
2. **Token**：自行设置一个符合微信页面要求的 Token，并将同一个值填入 LangBot 的「令牌」。两边必须完全一致。
3. **EncodingAESKey**：点击微信平台的「随机生成」，复制生成的值，填入 LangBot 的「消息加解密密钥」。
4. **消息加密**：选择「安全模式（推荐）」。
5. **数据格式**：选择 **XML**。

![微信开发者平台的配置消息推送弹窗](https://langbot.app/docs/images/zh/deploy/bots/wxoa/message-push.png)

两个平台的配置对应关系如下：

| 微信开发者平台        | LangBot                    |
| -------------- | -------------------------- |
| AppID          | 应用 ID                      |
| AppSecret      | 应用密钥                       |
| URL            | Webhook 回调地址（从 LangBot 复制） |
| Token          | 令牌                         |
| EncodingAESKey | 消息加解密密钥                    |

保持微信平台弹窗开启，回到 LangBot **再次保存机器人**。确认机器人已启用且配置成功应用后，再回到微信平台点击「确定」。微信会访问回调地址进行验证，通过后消息推送配置即完成。

> idea:
>
> Webhook 回调地址需要能够从公网访问，建议使用 HTTPS。自部署可参考[配置 HTTP 反向代理和 SSL](https://langbot.app/docs/zh/workshop/production/proxy-and-ssl.md)，将公网域名转发到 LangBot 服务。使用 HTTP 时需使用 80 端口，HTTPS 使用 443 端口。
>
> 如页面显示的仍是本地地址，请将实例 `data/config.yaml` 中的 `api.webhook_prefix` 设置为公网地址，例如 `https://bot.example.com`，重启 LangBot 后重新复制回调地址。[LangBot Cloud](https://space.langbot.app/cloud) 提供可直接使用的公网回调地址。

### 常见错误：请求失败，HTTP 返回非 200

如果点击微信平台的「确定」后出现此提示，请依次检查：

- **URL 正确且公网可达**：使用 LangBot 显示的完整回调地址，包含 `/bots/机器人UUID`。本机地址、内网地址或仅填写域名首页均不能作为此机器人的回调地址。
- **机器人已保存并启用**：填写 Token 和 EncodingAESKey 后，需要先在 LangBot 保存，再在微信平台确认。
- **字段一致**：Token、EncodingAESKey 必须与 LangBot 完全一致；AppID、AppSecret 必须属于当前选择的公众号，复制时不要带入多余空格或换行。
- **转发配置有效**：检查反向代理或隧道是否仍在运行、HTTPS 证书是否有效，以及回调是否被登录验证或访问控制拦截。

旧界面可能显示「系统发生错误，请稍后重试」，同样可以按上述项目检查，并查看 LangBot 的机器人日志定位错误。

## 4. 配置 API IP 白名单

在微信开发者平台「基础信息 → 开发密钥」中找到 **API IP 白名单**，填入部署 LangBot 的服务器访问微信 API 时使用的**公网出站 IP**，保存配置。截图中未启用 AppSecret 时，该项会提示「启用 AppSecret 后，可配置」。

可以从服务器或云平台的网络配置中查找出站 IP。如果 LangBot 通过 NAT 网关或代理访问微信 API，应填写实际出口的公网 IP；存在多个出口时，按微信页面要求将它们加入白名单。

> info:
>
> 回调 URL 用于微信向 LangBot 推送事件；API IP 白名单用于 LangBot 调用微信接口。使用反向代理或 Cloudflare Tunnel 提供回调地址时，白名单仍应填写 LangBot 访问微信 API 的出站 IP，而不是回调域名解析出的 CDN 地址。

## 接入模式与后续使用

在新版「微信公众号」适配器的「接入模式」中选择回复方式，保存后生效。已有机器人不会自动切换模式；默认值仍为 `drop`。旧版适配器不提供 `auto`，请使用新版适配器。

| 接入模式（Mode） | 回复机制                                  | 适用场景                            |
| ---------- | ------------------------------------- | ------------------------------- |
| `auto`     | 先返回加载提示，后台生成回复；通过客服接口发送，受限时改为下一条消息领取。 | 希望生成完成后直接收到回复，或不确定账号是否具有客服接口权限。 |
| `passive`  | 先返回加载提示，后台生成回复；用户再发任意内容领取，不调用客服接口。    | 没有客服接口权限，或希望始终使用领取方式。           |
| `drop`（默认） | 在当前微信回调内直接返回回复，不调用客服接口，也不会自动转为领取方式。   | 能在 5 秒内完成的快速回复；不适合耗时较长的 AI 生成。  |

### auto 如何自动选择回复方式？

`auto` 不会预先查询或要求填写账号认证状态，而是在处理器发送回复时，根据微信客服接口的实际返回结果决定：

1. 收到用户消息后，先返回加载提示，处理器在后台继续运行。
2. 处理器生成并发送回复时，LangBot 尝试调用客服接口。成功后，用户直接收到回复，不必再发消息领取。
3. 微信明确返回无接口权限（`48001`）、超过回复时限（`45015`）、下发额度用尽（`45047`）或接收者未关注（`43004`）时，LangBot 缓存回复。用户随后向公众号发送任意内容，即可通过这次回调领取。

这个判断针对每次回复，不会把账号永久标记为“无权限”。AppID、AppSecret、IP 白名单错误以及网络异常等其他失败会记录报错，不会一律当作权限不足并回退。收到加载提示只能说明消息已进入处理流程；排查未收到回答时，还需要查看处理器执行日志。

### 认证与回复窗口有什么关系？

**被动回调和客服消息是两种不同的回复渠道。** 微信要求被动回调在 **5 秒内**响应；认证不会延长这个时间。`drop` 使用的就是被动回调，不能把微信重试当成稳定的 15 秒生成窗口。[被动回复官方说明](https://developers.weixin.qq.com/doc/service/guide/product/message/Passive_user_reply_message.html)

客服接口允许在回调结束后发送回复。微信官方当前标明，公众号、服务号需企业主体已认证才能调用；前文的「主体实名验证」不等于取得客服接口权限。具体以账号实际权限和微信接口返回为准。

| 用户操作                  | 客服消息下发额度 | 有效期   |
| --------------------- | -------- | ----- |
| 发送消息                  | 5 条      | 48 小时 |
| 点击符合条件的自定义菜单、关注、扫描二维码 | 3 条      | 1 分钟  |

这些是微信客服接口的限制，不是 AI 的生成超时设置，也不是所有事件都享有 48 小时窗口。规则可能调整，请以[微信客服消息官方文档](https://developers.weixin.qq.com/doc/service/api/customer/message/api_sendcustommessage)为准。

### 如何领取回复和设置加载提示？

在 `passive` 或 `auto` 回退后，用户发送的下一条消息用于领取上一轮回答，**不会同时作为新的问题交给处理器**。如果回答尚未生成，仍会返回加载提示；稍后再发送任意内容即可。领取完成后，再发送新的问题。

`LoadingMessage` 对 `auto` 和 `passive` 都有效，对 `drop` 无效。可以按模式修改，例如：

- `auto`：「正在处理，请稍候。若未收到回复，请稍后发送任意内容领取。」
- `passive`：「AI 正在思考中，请稍后发送任意内容获取回复。」

将加载提示留空时，LangBot 只向微信确认接收，不发送可见的加载消息。待领取回复保存在内存中，重启 LangBot 或重新加载机器人配置会清空，因此请在修改配置后重新发起对话。三种模式仍受微信消息内容和长度限制。

### 连接处理器

完成平台配置后，在 LangBot 的「事件路由」中将「收到消息」连接到需要使用的流水线、Agent 或插件处理器，再关注公众号并发送消息。

接入模式只决定回复如何送达，不会自动把 Agent 的所有文本输出发送到微信。使用 Agent 时，请批准「回复当前会话」工具，并在指令中要求使用该工具回复；使用插件处理器时，需要插件调用回复接口。

---

# 沙箱配置

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`          | 开启     | 读写 | 默认限制 | 默认选择，可访问 API 或下载依赖     |
| `offline`          | 关闭     | 读写 | 默认限制 | 无需联网的任务，保留原 default 配置 |
| `offline_readonly` | 关闭     | 只读 | 更严格  | 读取不可信文件                |
| `network_basic`    | 开启基础网络 | 读写 | 默认限制 | 需要访问 API 或下载依赖         |
| `network_extended` | 开启完整网络 | 读写 | 更宽松  | 开发、调试、复杂任务             |

`network_basic` 保留兼容，其配置与 `default` 相同。

优先使用最小权限：不需要网络就用 `offline` 或 `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)

现在即可在流水线中选择使用该模型。