建立自訂 Python Components

自訂Components通過繼承自 Component 的 Python 類別來擴展 AgentBuilder 的功能。這實現了新功能整合、資料操作、外部服務和專用工具。

在 AgentBuilder 的節點式環境中，每個節點都是執行離散功能的「Components」。自訂Components是定義以下內容的 Python 類別：

• 輸入 — Components需要的資料或參數。
• 輸出 — Components提供給下游節點的資料。
• 邏輯 — 如何處理輸入以產生輸出。

建立自訂Components的優點包括無限擴展性、可重用性、基於輸入的視覺化編輯器自動欄位生成，以及節點間的類型安全連接。

為執行專用任務、呼叫 API 或新增進階邏輯而建立自訂Components。

AgentBuilder 中的自訂Components建置於：

• 繼承自 Component 的 Python 類別。
• 識別和描述Components的類別級別屬性。
• 決定資料流的輸入和輸出列表。
• 日誌記錄和進階邏輯的內部變數。

類別級別屬性

定義這些屬性來控制自訂Components的外觀和行為：

_10

class MyCsvReader(Component):

_10

display_name = "CSV Reader"

_10

description = "Reads CSV files"

_10

icon = "file-text"

_10

name = "CSVReader"

_10

documentation = "http://docs.example.com/csv_reader"

• display_name: 在視覺化編輯器中顯示的使用者友好標籤。

• description: 簡短摘要，顯示在工具提示中，並在新增到FLOW時印在Components名稱下方。

• icon: 來自 AgentBuilder 圖示庫的裝飾性圖示，印在名稱旁邊。

  AgentBuilder 使用 Lucide 作為圖示。要為您的Components分配圖示，請將 icon 屬性設定為 Lucide 圖示的名稱作為字串，例如 icon = "file-text"。AgentBuilder 會自動從 Lucide 庫渲染圖示。

• name: 唯一的內部識別碼，通常與包含Components程式碼的資料夾名稱相同。

• documentation: 指向外部文件的可選連結，例如 API 或產品文件。

自訂Components的結構

AgentBuilder 自訂Components不僅僅是一個具有輸入和輸出的類別。它包括具有可選生命週期步驟、輸出生成、前端互動和邏輯組織的內部結構。

基本Components：

• 繼承自 langflow.custom.Component。
• 宣告如 display_name、description、icon 等元資料。
• 定義 inputs 和 outputs 列表。
• 實作與輸出規格匹配的方法。

最小自訂Components骨架包含以下內容：

_14

from langflow.custom import Component

_14

from langflow.template import Output

_14

_14

class MyComponent(Component):

_14

display_name = "My Component"

_14

description = "A short summary."

_14

icon = "sparkles"

_14

name = "MyComponent"

_14

_14

inputs = []

_14

outputs = []

_14

_14

def some_output_method(self):

_14

return ...

內部生命週期和執行FLOW

AgentBuilder 的引擎管理：

• 實例化：Components被建立並初始化內部結構。
• 分配輸入：來自視覺化編輯器或連接的值被分配到Components欄位。
• 驗證和設定：可選的鉤子如 _pre_run_setup。
• 輸出生成：run() 或 build_results() 觸發輸出方法。

可選鉤子：

• initialize_data 或 _pre_run_setup 可以在Components主要執行之前運行設定邏輯。
• __call__、run() 或 _run() 可以被覆寫以自訂Components被呼叫的方式或定義自訂執行邏輯。

輸入和輸出

自訂Components輸入使用以下屬性定義：

• name、display_name
• 可選：info、value、advanced、is_list、tool_mode、real_time_refresh

例如：

• StrInput：簡單文字輸入。
• DropdownInput：可選取選項。
• HandleInput：專用連接。

自訂Components Output 屬性定義：

• name、display_name、method
• 可選：info

有關更多資訊，請參閱 自訂Components輸入和輸出。

關聯方法

每個輸出連結到一個方法：

• 輸出方法名稱必須與方法名稱匹配。
• 方法通常返回如 Message、Data 或 DataFrame 的物件。
• 方法可以使用 self.<input_name> 使用輸入。

例如：

_12

Output(

_12

display_name="File Contents",

_12

name="file_contents",

_12

method="read_file"

_12

)

_12

#...

_12

def read_file(self) -> Data:

_12

path = self.filename

_12

with open(path, "r") as f:

_12

content = f.read()

_12

self.status = f"Read {len(content)} chars from {path}"

_12

return Data(data={"content": content})

具有多個輸出的Components

Components可以定義多個輸出。 每個輸出可以有不同的對應方法。 例如：

_10

outputs = [

_10

Output(display_name="Processed Data", name="processed_data", method="process_data"),

_10

Output(display_name="Debug Info", name="debug_info", method="provide_debug_info"),

_10

]

使用 group_outputs 的輸出分組行為

預設情況下，AgentBuilder 中產生多個輸出的Components在視覺化編輯器中只允許一個輸出選取。 Components將只有一個輸出連接埠，使用者可以在其中選取偏好的輸出類型。

此行為由 group_outputs 參數控制：

• group_outputs=False (預設)：當Components有多個輸出且 group_outputs 為 false 或未設定時，輸出在視覺化編輯器中被分組，使用者必須選取一個。

  當Components預期在FLOW中使用時只返回一種輸出類型時，請使用此選項。

• group_outputs=True：所有輸出在視覺化編輯器中同時可用。Components為每個輸出有一個輸出連接埠，使用者可以將零個或多個輸出連接到其他Components。

  當Components預期返回多個值，由下游Components或FLOW並行使用時，請使用此選項。

False 或未設定

在此示例中，視覺化編輯器提供單個輸出連接埠，使用者可以選取其中一個輸出。 由於 group_outputs=False 是預設行為，它不需要在Components中明確設定，如此示例所示：

_12

outputs = [

_12

Output(

_12

name="structured_output",

_12

display_name="Structured Output",

_12

method="build_structured_output",

_12

),

_12

Output(

_12

name="dataframe_output",

_12

display_name="DataFrame Output",

_12

method="build_structured_dataframe",

_12

),

_12

]

True

在此示例中，所有輸出在視覺化編輯器中同時可用：

2. group_outputs=True

_14

outputs = [

_14

Output(

_14

name="true_result",

_14

display_name="True",

_14

method="true_response",

_14

group_outputs=True,

_14

),

_14

Output(

_14

name="false_result",

_14

display_name="False",

_14

method="false_response",

_14

group_outputs=True,

_14

),

_14

]

常見內部模式

_pre_run_setup()

使用計數器設定初始化自訂Components：

_10

def _pre_run_setup(self):

_10

if not hasattr(self, "_initialized"):

_10

self._initialized = True

_10

self.iteration = 0

覆寫 run 或 _run

您可以覆寫 async def _run(self): ... 以定義自訂執行邏輯，儘管基底類別的預設行為通常涵蓋大多數情況。

在 self.ctx 中儲存資料

使用 self.ctx 作為Components執行FLOW中資料或計數器的共享儲存：

_10

def some_method(self):

_10

count = self.ctx.get("my_count", 0)

_10

self.ctx["my_count"] = count + 1

目錄結構要求

預設情況下，AgentBuilder 在 /components 目錄中尋找自訂Components。

如果您使用 LANGFLOW_COMPONENTS_PATH 環境變數 在不同位置建立自訂Components，Components必須組織在特定目錄結構中，才能在視覺化編輯器中正確載入和顯示：

每個類別目錄 必須 包含 __init__.py 文件，AgentBuilder 才能正確識別和載入Components。 這是 Python 套件要求，確保目錄被視為模組。

_10

/your/custom/components/path/ # 由 LANGFLOW_COMPONENTS_PATH 設定的基礎目錄

_10

└── category_name/ # 決定選單名稱的必要類別子資料夾

_10

├── __init__.py # 必要

_10

└── custom_component.py # Components文件

Components必須放置在類別資料夾內，而不是直接在基礎目錄中。

類別資料夾名稱決定Components在 AgentBuilder Core components 選單中出現的位置。 例如，要將Components新增到 Helpers 類別，請將其放置在 helpers 子資料夾中：

_10

/app/custom_components/ # LANGFLOW_COMPONENTS_PATH

_10

└── helpers/ # 在 "Helpers" 類別中顯示

_10

├── __init__.py # 必要

_10

└── custom_component.py # 您的Components

您可以有多個類別資料夾來將Components組織到不同類別中：

_10

/app/custom_components/

_10

├── helpers/

_10

│ ├── __init__.py

_10

│ └── helper_component.py

_10

└── tools/

_10

├── __init__.py

_10

└── tool_component.py

此資料夾結構對於 AgentBuilder 正確發現和載入您的自訂Components是必要的。直接放置在基礎目錄中的Components不會被載入。

_10

/app/custom_components/ # LANGFLOW_COMPONENTS_PATH

_10

└── custom_component.py # 不會被載入 - 缺少類別資料夾！

自訂Components輸入和輸出

輸入和輸出定義資料如何通過Components流動，如何在視覺化編輯器中出現，以及如何驗證與其他Components的連接。

輸入

輸入在類別級別的 inputs 列表中定義。當 AgentBuilder 載入Components時，它使用此列表在視覺化編輯器中渲染Components欄位和 連接埠。使用者或其他Components提供值或連接來填充這些輸入。

輸入通常是來自 langflow.io 的類別實例（如 StrInput、DataInput 或 MessageTextInput）。最常見的建構函數參數是：

• name：內部變數名稱，使用 self.<name> 存取。
• display_name：在視覺化編輯器中向使用者顯示的標籤。
• info (可選)：工具提示或簡短描述。
• value (可選)：預設值。
• advanced (可選)：如果為 true，將欄位移到「Advanced」區段。
• required (可選)：如果為 true，強制使用者提供值。
• is_list (可選)：如果為 true，允許多個值。
• input_types (可選)：限制允許的連接類型（例如 ["Data"]、["LanguageModel"]）。

以下是最常使用的輸入類別及其典型用法。

文字輸入：用於簡單文字條目。

• StrInput 建立單行文字欄位。
• MultilineInput 建立多行文字區域。

數值和布林輸入：確保使用者只能輸入有效的數值或布林資料。

• BoolInput、IntInput 和 FloatInput 提供布林、整數和浮點值的欄位，確保類型一致性。

下拉選單：用於從預定義選項中選取，對模式或級別很有用。

• DropdownInput

機密：專用於敏感資料的輸入，確保在視覺化編輯器中隱藏輸入。

• SecretStrInput 用於 API 金鑰和密碼。

專用資料輸入：確保視覺化編輯器中的類型檢查和顏色編碼連接。

• DataInput 期望 Data 物件（通常具有 .data 和可選的 .text）。
• MessageInput 期望 Message 物件，用於聊天或 agent flow。
• MessageTextInput 簡化對 Message 的 .text 欄位的存取。

基於句柄的輸入：用於連接特定類型的輸出，確保正確的管道連接。

• HandleInput

檔案上傳：允許使用者通過視覺化編輯器直接上傳檔案，或從其他Components接收檔案路徑。

• FileInput

列表：設定 is_list=True 以接受多個值，對批次或分組操作理想。

此示例定義三個輸入：文字欄位 (StrInput)、布林切換 (BoolInput) 和下拉選取 (DropdownInput)。

_10

from langflow.io import StrInput, BoolInput, DropdownInput

_10

_10

inputs = [

_10

StrInput(name="title", display_name="Title"),

_10

BoolInput(name="enabled", display_name="Enabled", value=True),

_10

DropdownInput(name="mode", display_name="Mode", options=["Fast", "Safe", "Experimental"], value="Safe")

_10

]

輸出

輸出在類別級別的 outputs 列表中定義。當 AgentBuilder 渲染Components時，每個輸出成為視覺化編輯器中的連接器點。當您將某物連接到輸出時，AgentBuilder 會自動呼叫對應的方法並將返回的物件傳遞到下一個Components。

輸出通常是來自 langflow.io 的 Output 實例，具有常見參數：

• name：內部變數名稱。
• display_name：在視覺化編輯器中顯示的標籤。
• method：呼叫以產生輸出的方法名稱。
• info (可選)：懸停時顯示的幫助文字。

方法必須存在於類別中，並且建議為其返回類型加上註釋，以便更好的類型檢查。 您也可以在方法內設定 self.status 訊息來顯示進度或日誌。

常見返回類型：

• Message：結構化聊天訊息。
• Data：具有 .data 和可選 .text 的靈活物件。
• DataFrame：基於 Pandas 的表格 (langflow.schema.DataFrame)。
• 原始類型 (str、int、bool)：允許返回原始類型，但在視覺化編輯器中為了更好的連貫性，建議包裝在 Data 或 Message 中。

在此示例中，DataToDataFrame Components定義其輸出使用 outputs 列表。df_out 輸出連結到 build_df 方法，因此當連接到另一個Components（節點）時，AgentBuilder 呼叫此方法並將其返回的 DataFrame 傳遞到下一個節點。這演示了每個輸出如何映射到產生實際輸出資料的方法。

_37

from langflow.custom import Component

_37

from langflow.io import DataInput, Output

_37

from langflow.schema import Data, DataFrame

_37

_37

class DataToDataFrame(Component):

_37

display_name = "Data to DataFrame"

_37

description = "Convert multiple Data objects into a DataFrame"

_37

icon = "table"

_37

name = "DataToDataFrame"

_37

_37

inputs = [

_37

DataInput(

_37

name="items",

_37

display_name="Data Items",

_37

info="List of Data objects to convert",

_37

is_list=True

_37

)

_37

]

_37

_37

outputs = [

_37

Output(

_37

name="df_out",

_37

display_name="DataFrame Output",

_37

method="build_df"

_37

)

_37

]

_37

_37

def build_df(self) -> DataFrame:

_37

rows = []

_37

for item in self.items:

_37

row_dict = item.data.copy() if item.data else {}

_37

row_dict["text"] = item.get_text() or ""

_37

rows.append(row_dict)

_37

_37

df = DataFrame(rows)

_37

self.status = f"Built DataFrame with {len(rows)} rows."

_37

return df

工具模式

支援 工具模式 的Components可以用作獨立Components（當 不在 工具模式 中時）或作為具有 Tools 輸入的其他Components的工具，例如 Agent Components。

您可以通過設定 tool_mode=True 來允許自訂Components支援 工具模式：

_10

inputs = [

_10

MessageTextInput(

_10

name="message",

_10

display_name="訊息",

_10

info="輸入將由工具直接處理的訊息",

_10

tool_mode=True,

_10

),

_10

]

AgentBuilder 目前支援 工具模式 的以下輸入類型：

• DataInput
• DataFrameInput
• PromptInput
• MessageTextInput
• MultilineInput
• DropdownInput

類型註釋

在 AgentBuilder 中，類型註釋 允許 AgentBuilder 視覺化引導使用者並維持FLOW一致性。

類型註釋提供：

• 顏色編碼：如 -> Data 或 -> Message 的輸出獲得不同顏色。
• 驗證：AgentBuilder 自動阻止不相容的連接。
• 可讀性：開發人員可以快速理解資料流。
• 開發工具：程式碼編輯器中更好的程式碼建議和錯誤檢查。

常見返回類型

• Message：用於聊天式輸出。連接到任何幾個 Message 相容輸入。

  
  

  _10

  def produce_message(self) -> Message:

  _10

  return Message(text="Hello! from typed method!", sender="System")

  
  

• Data：用於結構化資料如字典或部分文字。只連接到接受 Data 的 DataInput（連接埠）。

  
  

  _10

  def get_processed_data(self) -> Data:

  _10

  processed = {"key1": "value1", "key2": 123}

  _10

  return Data(data=processed)

  
  

• DataFrame：用於表格資料。只連接到接受 DataFrame 的 DataFrameInput（連接埠）。

  
  

  _10

  def build_df(self) -> DataFrame:

  _10

  pdf = pd.DataFrame({"A": [1, 2], "B": [3, 4]})

  _10

  return DataFrame(pdf)

  
  

• 原始類型 (str、int、bool)：允許返回原始類型，但在視覺化編輯器中為了更好的連貫性，建議包裝在 Data 或 Message 中。

  
  

  _10

  def compute_sum(self) -> int:

  _10

  return sum(self.numbers)

  
  

類型註釋提示

使用類型註釋時，請考慮以下最佳實務：

• 始終註釋輸出：指定如 -> Data、-> Message 或 -> DataFrame 的返回類型，以啟用適當的視覺化編輯器顏色編碼和驗證。
• 包裝原始資料：使用 Data、Message 或 DataFrame 包裝器而不是返回純結構。
• 謹慎使用原始類型：直接 str 或 int 返回對簡單FLOW來說很好，但包裝改善了靈活性。
• 也註釋助手：即使是內部的，輸入也改善了可維護性和清晰度。
• 處理邊緣情況：當需要時，優先返回帶有錯誤欄位的結構化 Data。
• 保持一致：在Components中使用相同類型以使FLOW可預測且更容易建置。

啟用動態欄位

在 AgentBuilder 中，動態欄位允許輸入基於使用者互動而改變或出現。您可以通過設定 dynamic=True 使輸入動態。 可選地，設定 real_time_refresh=True 會觸發 update_build_config 方法，以即時調整輸入的可見性或屬性，創造僅基於使用者選擇公開相關欄位的上下文視覺化編輯器體驗。

在此示例中，operator 欄位以 real_time_refresh=True 觸發更新。 regex_pattern 欄位最初隱藏並以 dynamic=True 控制。

_22

from langflow.io import DropdownInput, StrInput

_22

_22

class RegexRouter(Component):

_22

display_name = "Regex Router"

_22

description = "Demonstrates dynamic fields for regex input."

_22

_22

inputs = [

_22

DropdownInput(

_22

name="operator",

_22

display_name="Operator",

_22

options=["equals", "contains", "regex"],

_22

value="equals",

_22

real_time_refresh=True,

_22

),

_22

StrInput(

_22

name="regex_pattern",

_22

display_name="Regex Pattern",

_22

info="Used if operator='regex'",

_22

dynamic=True,

_22

show=False,

_22

),

_22

]

實作 update_build_config

當修改具有 real_time_refresh=True 的欄位時，AgentBuilder 呼叫 update_build_config 方法，傳遞更新的欄位名稱、值和Components的配置，以動態調整基於使用者輸入的其他欄位的可見性或屬性。

此示例將在使用者選取不同運算子時顯示或隱藏 regex_pattern 欄位。

_10

def update_build_config(self, build_config: dict, field_value: str, field_name: str | None = None) -> dict:

_10

if field_name == "operator":

_10

if field_value == "regex":

_10

build_config["regex_pattern"]["show"] = True

_10

else:

_10

build_config["regex_pattern"]["show"] = False

_10

return build_config

額外動態欄位控制

您也可以在 update_build_config 中修改其他屬性，例如：

• required：設定 build_config["some_field"]["required"] = True/False

• advanced：設定 build_config["some_field"]["advanced"] = True

• options：修改動態下拉選項。

管理動態欄位的提示

使用動態欄位時，請考慮以下最佳實務以確保順暢的使用者體驗：

• 最小化欄位變更：僅隱藏真正不相關的欄位以避免混淆使用者。
• 測試行為：確保新增或移除欄位不會意外清除使用者輸入。
• 保留資料：使用 build_config["some_field"]["show"] = False 隱藏欄位而不遺失其值。
• 澄清邏輯：新增 info 註記來解釋欄位為何基於條件出現或消失。
• 保持可管理：如果動態邏輯變得太複雜，請考慮將其分解為更小的Components，除非它在單一節點中服務於明確目的。

錯誤處理和日誌記錄

在 AgentBuilder 中，強大的錯誤處理確保您的Components即使在發生意外情況時也能可預測地運作，例如無效輸入、外部 API 失敗或內部邏輯錯誤。

錯誤處理技術

• 引發例外：如果發生關鍵錯誤，您可以引發標準 Python 例外如 ValueError，或專用例外如 ToolException。AgentBuilder 會自動捕獲這些並在視覺化編輯器中顯示適當的錯誤訊息，幫助使用者快速識別問題所在。

  
  

  _10

  def compute_result(self) -> str:

  _10

  if not self.user_input:

  _10

  raise ValueError("No input provided.")

  _10

  # ...

  
  

• 返回結構化錯誤資料：而不是突然停止FLOW，您可以返回包含 "error" 欄位的 Data 物件。此方法允許FLOW繼續運作，並啟用下游Components優雅地偵測和處理錯誤。

  
  

  _10

  def run_model(self) -> Data:

  _10

  try:

  _10

  # ...

  _10

  except Exception as e:

  _10

  return Data(data={"error": str(e)})

  
  

改善除錯和FLOW管理

• 使用 self.status：每個Components都有狀態欄位，您可以在其中儲存關於執行結果的簡短訊息 — 如成功摘要、部分進度或錯誤通知。這些直接出現在視覺化編輯器中，使故障排除更容易。

  
  

  _10

  def parse_data(self) -> Data:

  _10

  # ...

  _10

  self.status = f"Parsed {len(rows)} rows successfully."

  _10

  return Data(data={"rows": rows})

  
  

• 使用 self.stop(...) 停止特定輸出：當某些條件失敗時，您可以停止個別輸出路徑，而不影響整個Components。這對於具有多個輸出分支的Components特別有用。

  
  

  _10

  def some_output(self) -> Data:

  _10

  if <some condition>:

  _10

  self.stop("some_output") # Tells AgentBuilder no data flows

  _10

  return Data(data={"error": "Condition not met"})

  
  

• 日誌事件：您可以在Components內日誌記錄關鍵執行詳細資訊。日誌顯示在Components的詳細視圖的「Logs」或「Events」區段中，並且可以稍後通過FLOW的除錯面板或匯出文件存取，提供Components行為的清晰追蹤以便更容易除錯。

  
  

  _10

  def process_file(self, file_path: str):

  _10

  self.log(f"Processing file {file_path}")

  _10

  # ...

  
  

錯誤處理和日誌記錄提示

為了建置更可靠的Components，請考慮以下最佳實務：

• 早期驗證輸入：在開始時捕獲缺失或無效輸入以防止損壞邏輯。
• 使用 self.status 摘要：使用簡短成功或錯誤摘要來幫助使用者快速理解結果。
• 保持日誌簡潔：專注於有意義的訊息以避免雜亂視覺化編輯器。
• 返回結構化錯誤：在適當時，返回 Data(data={"error": ...}) 而不是引發例外以允許下游處理。
• 選擇性停止輸出：僅在必要時使用 self.stop(...) 停止特定輸出，以保留其他地方的正確FLOW行為。

為 AgentBuilder 貢獻自訂Components

請參閱 AgentBuilder 的 GitHub 儲存庫為 AgentBuilder 貢獻您的自訂Components。