Skip to main content

AgentBuilder 數據類型

AgentBuilder 組件設計為接受和產生特定類型的輸入和輸出。 輸入和輸出數據類型定義組件之間資訊的結構和FLOW。 了解這些結構有助於您建置提供有效輸入並正確預期輸出格式的應用程式。

組件連接埠 代表每個組件可以傳送和接收的數據類型。 某些數據類型從它們附加的欄位可以明顯看出；例如，System Message 欄位接受訊息數據。 連接埠顏色 也表示連接埠的數據類型。 例如 Data Port，由 表示，麼接受麼發出結構化數據物件。

建置FLOW時，將輸出連接埠連接到相同類型（顏色）的輸入連接埠，以在兩個組件之間傳輸該類型的數據。

tip

  • 在工作區中，將滑鼠懸停在連接埠上以查看該連接埠的連接詳細資料。 按一下連接埠以 Search 相容組件。

  • 如果兩個組件具有不相容的數據類型，您可以使用處理組件（如 Type Convert 組件）在組件之間轉換數據。

Data​

Data 連接埠 接受或產生 Data 類型，這是一個結構化數據物件，就像您可能傳送到 API 的 JSON 有效負載。 此數據類型用於在組件之間傳遞鍵值對，例如使用者個人資料、設定或其他結構化資訊。

Data 物件包括一個主要文字欄位，由 text_key 表示，以及其他元數據。

結構描述和屬性​

結構描述定義在 data.py 中。

以下屬性可用：

  • data：Data 物件在 .data 屬性中儲存鍵值對。這是 Data 物件的核心字典。每個鍵是一個欄位名稱，值可以是任何支援的數據類型。
  • text_key：data 中被視為主要文字值的鍵。
  • default_value：如果 text_key 遺失的後備。預設 text_key 是 "text"。

_10
data_obj = Data(
_10
text_key="text",
_10
data={
_10
"text": "Hello world",
_10
"name": "Charlie",
_10
"age": 28
_10
},
_10
default_value=""
_10
)

Data 物件可以序列化為 JSON、從 JSON 建立，或從其他字典數據建立。 不過，產生的 Data 物件是一個具有驗證和方法的結構化物件，而不是純字典。 例如，當序列化為 JSON 時，先前的 Python 範例會成為以下 JSON 物件：


_10
{
_10
"text_key": "text",
_10
"data": {
_10
"text": "Hello world",
_10
"name": "Charlie",
_10
"age": 28
_10
},
_10
"default_value": ""
_10
}

DataFrame​

DataFrame 連接埠 接受或產生 pandas DataFrames，類似於表格 CSV 數據。

使用 DataFrame 類型處理包含多行或記錄的數據。

結構描述和屬性​

結構描述定義在 dataframe.py 中。

以下屬性可用：

  • 完整 pandas 相容性：支援所有 pandas DataFrame 方法和功能

  • AgentBuilder 整合：接受 Data 物件 清單、字典或現有 DataFrames。

  • 便利方法：

    • to_data_list()
    • add_row()
    • add_rows()
    • to_lc_documents()
    • to_data()
    • to_message()

  • 文字鍵支援：為 Data 物件 相容性維護 text_key 和 default_value 屬性。

DataFrame 結構​

DataFrame 具有表格數據結構，具有行和列。 鍵是列，陣列中的每個物件是一行。


_12
[
_12
{
_12
"name": "Charlie Lastname",
_12
"age": 28,
_12
"email": "charlie.lastname@example.com"
_12
},
_12
{
_12
"name": "Alexandra Example",
_12
"age": 34,
_12
"email": "alexandra@example.com"
_12
}
_12
]

當表示為表格數據時，前述 DataFrame 物件結構如下：


_10
| name | age | email |
_10
|------|-----|-------|
_10
| Charlie Lastname | 28 | charlie.lastname@example.com |
_10
| Alexandra Example | 34 | alexandra@example.com |

Embeddings​

Embeddings 連接埠 發出或擷取向量嵌入以支援相似性搜尋等功能。

Embeddings 數據類型專門由產生或消耗向量嵌入的組件使用，例如嵌入模型組件和向量儲存組件。

例如，嵌入模型組件輸出 Embeddings 數據，您可以將其連接到向量儲存組件上的 Embedding 輸入連接埠。

有關產生 Embeddings 的底層 Python 類別的資訊，請參閱 LangChain Embedding models 文件。

LanguageModel​

LanguageModel 類型是一種特定數據類型，可以由語言模型組件產生，並由使用 LLM 的組件接受。

當您將語言模型組件的輸出類型從 Model Response 變更為 Language Model 時，組件的輸出連接埠會從 Message 連接埠變更為 Language Model 連接埠 。 然後，您將傳出 Language Model 連接埠連接到相容組件上的 Language Model 輸入連接埠，例如 Smart Function 組件。

有關在FLOW中使用這些組件和切換 LanguageModel 輸出的更多資訊，請參閱語言模型組件。

LanguageModel 是 LangChain ChatModel 的實例

因為 AgentBuilder 建置在 LangChain 上，LanguageModel 實際上是使用原始組件中設定的配置參數的 LangChain 聊天模型實例。

通常，組件會產生專為特定模型提供者設計的整合聊天模型實例，例如 ChatOpenAI 或 ChatAnthropic。

您可以檢查組件程式碼以查看它產生的特定 Chat 實例。

Memory​

Memory 連接埠 用於將 Message History 組件與外部聊天記憶體儲存整合。

有關更多資訊，請參閱 Message History 組件。

Message​

Message 連接埠 接受或產生 Message 數據，這擴展了 Data 類型，具有聊天FLOW中通常使用的文字輸入的附加欄位和方法。

此數據類型由許多組件使用。

tip

接受或產生 Message 數據的組件可能不會在傳入或傳出的 Message 數據中包含所有屬性。 只要數據與 Message 結構描述相容，它就可以是有效的。

建置FLOW時，專注於工作區中每個組件上顯示的欄位，而不是組件之間傳遞的數據類型。 特定數據類型的詳細資料通常只在您除錯沒有產生預期輸出的FLOW或組件時才相關。

例如，Chat Input 組件只需要 Input Text (input_value) 欄位的內容。 然後，組件會建構完整的 Message 物件，然後將數據傳遞給FLOW中的其他組件。

結構描述、結構和屬性​

Message 結構描述定義在 message.py 中。 某些 Message 屬性有自己的結構描述定義，例如 content_block.py。

Message 數據結構化為 JSON 物件。 例如：


_10
{
_10
"text": "Name: Charlie Lastname, Age: 28, Email: charlie.lastname@example.com",
_10
"sender": "User",
_10
"sender_name": "Charlie Lastname",
_10
"session_id": "some-session-id",
_10
"timestamp": "2024-06-01T12:00:00Z",
_10
"files": [],
_10
"content_blocks": [],
_10
"category": "message"
_10
}

特定 Message 物件中包含的屬性取決於上下文，包括組件類型、FLOW活動，以及訊息是查詢還是回應。 一些常見屬性包括以下：

  • text：主要訊息內容。
  • sender：將聊天訊息的發送者識別為 User 或 Language Model。
  • sender_name：發送者的顯示名稱。預設為 User 或 Language Model。
  • session_id：聊天工作階段識別碼。
  • flow_id：訊息相關聯的FLOW ID。如果FLOW不使用自訂工作階段 ID，flow_id 和 session_id 相同。
  • timestamp：訊息傳送的 UTC 時間戳。
  • files：訊息包含的檔案路徑或影像清單
  • content_blocks：豐富內容輸入的容器，例如文字、媒體或程式碼。也包含如果 LLM 無法處理輸入的錯誤訊息資訊。
  • category："message"、"error"、"warning" 或 "info"。

並非所有屬性都是必需的，某些組件接受訊息相容輸入，例如原始文字輸入。 嚴格性取決於組件。

輸入和輸出組件中的訊息數據​

在具有 Chat Input and Output 組件 的FLOW中，Message 數據為聊天互動提供一致的結構，並且非常適合聊天機器人、對話分析，以及其他基於與 LLM 或 agent 對話的用例。 在這些FLOW中，Playground 聊天介面只列印與對話相關的 Message 屬性，例如 text、files 和來自 content_blocks 的錯誤訊息。 要查看所有 Message 屬性，請檢查 Playground 中的訊息日誌。

在具有 Text Input and Output 組件 的FLOW中，Message 數據用於傳遞簡單的文字字串，而沒有聊天相關的元數據。 這些組件將 Message 數據處理為獨立的文字字串，而不是進行中對話的一部分。 因此，只有 Text Input and Output 組件的FLOW與 Playground 不相容。 有關更多資訊，請參閱輸入和輸出組件。

使用 AgentBuilder API 時，回應包括 Message 物件以及FLOW執行中的其他回應數據。 AgentBuilder API 回應可能非常冗長，因此您的應用程式必須包含從回應中提取相關數據以返回給使用者的程式碼。 如需範例，請參閱 AgentBuilder 快速入門。

此外，傳送到輸入/輸出組件輸入連接埠的輸入_不需要_是完整的 Message 物件，因為組件會建構然後傳遞給FLOW中的其他組件或作為FLOW輸出返回的 Message 物件。 事實上，某些組件不應該接收完整的 Message 物件，因為某些屬性（如 timestamp）應該由組件添加以確保準確性。

Tool​

Tool 連接埠 將工具連接到 Agent 組件。

工具可以是您啟用 Tool Mode 的其他組件、專用的 MCP Tools 組件，或僅支援 Tool Mode 的其他組件。 多個工具可以連接到相同 Agent 組件的相同連接埠。

功能上，Tool 數據是一個可以在 agent FLOW中使用的 LangChain StructuredTool 物件。

有關更多資訊，請參閱為 agent 配置工具和使用 AgentBuilder 作為 MCP 客戶端。

未知或多種類型​

如果連接埠可以接受或產生多種數據類型，它由灰色連接埠圖示表示 。

將滑鼠懸停在連接埠上以查看接受或產生的數據類型。

在FLOW中查看數據類型​

在 AgentBuilder 中，您可以使用 Inspect output 查看個別組件的輸出。 這可以幫助您了解不同的數據類型並除錯無效或格式錯誤的輸入和輸出問題。

以下範例顯示如何檢查 Type Convert 組件 的輸出，它可以將數據從一種類型轉換為另一種：

  1. 建立FLOW，然後將 Chat Input 組件連接到 Type Convert 組件。

  2. 在 Chat Input 組件中，輸入一些文字供類型轉換器處理。

  3. 在 Type Convert 組件上，按一下 Run component，然後按一下 Inspect output。

    預設輸出是 Message 數據，這與來自 Chat Input 組件的輸入相同。 要查看 Message 數據轉換為 Data 或 DataFrame，請變更 Type Convert 組件上的 Output Type，然後重新執行組件。


    _10
    Input text

另請參閱​

Search