OpenAI Responses API
AgentBuilder 包含一個與 OpenAI Responses API 相容的端點。
它可在 POST /api/v1/responses 取得。
此端點允許您使用現有的 OpenAI 客戶端程式庫，只需最少的程式碼變更。
您只需要將 model 名稱，例如 gpt-4，替換為您的 flow_id。
您可以在 API access 窗格 的程式碼片段中找到FLOW ID，或在FLOW的 URL 中找到。
先決條件
為了與 AgentBuilder 的 OpenAI Responses API 端點相容，您的FLOW和請求必須遵守以下要求：
- 聊天輸入：您的FLOW必須包含 Chat Input Components。
沒有此Components的FLOW傳遞到此端點時會返回錯誤。
Components類型
ChatInput和Chat Input被識別為聊天輸入。 - 工具：
tools參數不受支援，如果提供會返回錯誤。 - 模型名稱：在您的請求中，
model欄位必須包含有效的FLOW ID 或端點名稱。 - 認證：所有請求都需要在
x-api-key標頭中傳遞 API 金鑰。 有關更多資訊，請參閱 API 金鑰和認證。
OpenAI 客戶端程式庫的額外配置
此端點與 OpenAI 的 API 相容，但在使用 OpenAI 客戶端程式庫時需要特殊配置。
AgentBuilder 使用 x-api-key 標頭進行認證，而 OpenAI 使用 Authorization: Bearer 標頭。
使用 OpenAI 客戶端程式庫向 AgentBuilder 發送請求時，您必須配置自訂標頭並包含 api_key 配置。
api_key 參數可以有任何值，例如客戶端示例中的 "dummy-api-key"，因為實際認證通過 default_headers 配置處理。
在以下示例中，將 LANGFLOW_SERVER_URL、LANGFLOW_API_KEY 和 FLOW_ID 的值替換為您部署的值。
- OpenAI Python Client
- OpenAI TypeScript Client
_14from openai import OpenAI_14_14client = OpenAI(_14 base_url="LANGFLOW_SERVER_URL/api/v1/",_14 default_headers={"x-api-key": "LANGFLOW_API_KEY"},_14 api_key="dummy-api-key" # OpenAI SDK 需要但 Langflow 不使用_14)_14_14response = client.responses.create(_14 model="FLOW_ID",_14 input="There is an event that happens on the second wednesday of every month. What are the event dates in 2026?",_14)_14_14print(response.output_text)
_16import OpenAI from "openai";_16_16const client = new OpenAI({_16 baseURL: "LANGFLOW_SERVER_URL/api/v1/",_16 defaultHeaders: {_16 "x-api-key": "LANGFLOW_API_KEY"_16 },_16 apiKey: "dummy-api-key" // OpenAI SDK 需要但 Langflow 不使用_16});_16_16const response = await client.responses.create({_16 model: "FLOW_ID",_16 input: "There is an event that happens on the second wednesday of every month. What are the event dates in 2026?"_16});_16_16console.log(response.output_text);
Response
_14Here are the event dates for the second Wednesday of each month in 2026:_14- January 14, 2026_14- February 11, 2026_14- March 11, 2026_14- April 8, 2026_14- May 13, 2026_14- June 10, 2026_14- July 8, 2026_14- August 12, 2026_14- September 9, 2026_14- October 14, 2026_14- November 11, 2026_14- December 9, 2026_14If you need these in a different format or want a downloadable calendar, let me know!
示例請求
_10curl -X POST \_10 "$LANGFLOW_SERVER_URL/api/v1/responses" \_10 -H "x-api-key: $LANGFLOW_API_KEY" \_10 -H "Content-Type: application/json" \_10 -d '{_10 "model": "$YOUR_FLOW_ID",_10 "input": "Hello, how are you?",_10 "stream": false_10 }'
標頭
| 標頭 | 必需 | 描述 | 示例 |
|---|---|---|---|
x-api-key | 是 | 用於認證的 AgentBuilder API 金鑰 | "sk-..." |
Content-Type | 是 | 指定 JSON 格式 | "application/json" |
X-LANGFLOW-GLOBAL-VAR-* | 否 | FLOW的全域變數 | "X-LANGFLOW-GLOBAL-VAR-API_KEY: sk-..." 有關更多資訊，請參閱 在標頭中傳遞全域變數給您的FLOW。 |
請求主體
| 欄位 | 類型 | 必需 | 預設 | 描述 |
|---|---|---|---|---|
model | string | 是 | - | 要執行的FLOW ID 或端點名稱。 |
input | string | 是 | - | 要處理的輸入文字。 |
stream | boolean | 否 | false | 是否串流回應。 |
background | boolean | 否 | false | 是否在背景處理。 |
tools | list[Any] | 否 | null | 工具尚未支援。 |
previous_response_id | string | 否 | null | 繼續對話的先前回應 ID。有關更多資訊，請參閱 使用回應和會話 ID 繼續對話。 |
include | list[string] | 否 | null | 要包含的額外回應資料，例如 ['tool_call.results']。有關更多資訊，請參閱 檢索工具調用結果。 |
示例回應
_35{_35 "id": "e5e8ef8a-7efd-4090-a110-6aca082bceb7",_35 "object": "response",_35 "created_at": 1756837941,_35 "status": "completed",_35 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_35 "output": [_35 {_35 "type": "message",_35 "id": "msg_e5e8ef8a-7efd-4090-a110-6aca082bceb7",_35 "status": "completed",_35 "role": "assistant",_35 "content": [_35 {_35 "type": "output_text",_35 "text": "Hello! I'm here and ready to help. How can I assist you today?",_35 "annotations": []_35 }_35 ]_35 }_35 ],_35 "parallel_tool_calls": true,_35 "previous_response_id": null,_35 "reasoning": {"effort": null, "summary": null},_35 "store": true,_35 "temperature": 1.0,_35 "text": {"format": {"type": "text"}},_35 "tool_choice": "auto",_35 "tools": [],_35 "top_p": 1.0,_35 "truncation": "disabled",_35 "usage": null,_35 "user": null,_35 "metadata": {}_35}
回應主體
回應包含 AgentBuilder 動態設定的欄位和使用 OpenAI 相容預設值的欄位。
上面顯示的 OpenAI 相容預設值目前是固定的，無法通過請求修改。 它們被包含在內以維持 API 相容性並提供一致的回應格式。
對於您的請求，您只會設定動態欄位。 預設值在此記錄以完整性和顯示完整回應結構。
AgentBuilder 動態設定的欄位：
| 欄位 | 類型 | 描述 |
|---|---|---|
id | string | 唯一的回應識別碼。 |
created_at | int | 回應建立的 Unix 時間戳。 |
model | string | 已執行的FLOW ID。 |
output | list[dict] | 輸出項目陣列（訊息、工具調用等）。 |
previous_response_id | string | 如果繼續對話，則為先前回應的 ID。 |
具有 OpenAI 相容預設值的欄位
| 欄位 | 類型 | 預設值 | 描述 |
|---|---|---|---|
object | string | "response" | 始終為 "response"。 |
status | string | "completed" | 回應狀態："completed"、"in_progress" 或 "failed"。 |
error | dict | null | 錯誤詳細資訊（如果有）。 |
incomplete_details | dict | null | 不完整回應詳細資訊（如果有）。 |
instructions | string | null | 回應指示（如果有）。 |
max_output_tokens | int | null | 最大輸出權杖（如果有）。 |
parallel_tool_calls | boolean | true | 是否啟用平行工具調用。 |
reasoning | dict | {"effort": null, "summary": null} | 具有努力和摘要的推理資訊。 |
store | boolean | true | 是否儲存回應。 |
temperature | float | 1.0 | 溫度設定。 |
text | dict | {"format": {"type": "text"}} | 文字格式配置。 |
tool_choice | string | "auto" | 工具選擇設定。 |
tools | list[dict] | [] | 可用工具。 |
top_p | float | 1.0 | Top-p 設定。 |
truncation | string | "disabled" | 截斷設定。 |
usage | dict | null | 使用統計（如果有）。 |
user | string | null | 使用者識別碼（如果有）。 |
metadata | dict | {} | 額外元資料。 |
示例串流請求
當您將 "stream": true 與您的請求一起設定時，API 會返回一個串流，其中每個區塊在生成時包含回應的一小部分。這提供了實時體驗，使用者可以看到 AI 的輸出逐字出現，類似於 ChatGPT 的打字效 果。
_10curl -X POST \_10 "$LANGFLOW_SERVER_URL/api/v1/responses" \_10 -H "x-api-key: $LANGFLOW_API_KEY" \_10 -H "Content-Type: application/json" \_10 -d '{_10 "model": "$FLOW_ID",_10 "input": "Tell me a story about a robot",_10 "stream": true_10 }'
Result
_10{_10 "id": "f7fcea36-f128-41c4-9ac1-e683137375d5",_10 "object": "response.chunk",_10 "created": 1756838094,_10 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_10 "delta": {_10 "content": "Once"_10 },_10 "status": null_10}
串流回應主體
| 欄位 | 類型 | 描述 |
|---|---|---|
id | string | 唯一的回應識別碼。 |
object | string | 始終為 "response.chunk"。 |
created | int | 區塊建立的 Unix 時間戳。 |
model | string | 已執行的FLOW ID。 |
delta | dict | 新的內容區塊。 |
status | string | 回應狀態："completed"、"in_progress" 或 "failed"（可選）。 |
串流會繼續直到具有 "status": "completed" 的最終區塊表示回應已完成。
Final completion chunk
_10{_10 "id": "f7fcea36-f128-41c4-9ac1-e683137375d5",_10 "object": "response.chunk",_10 "created": 1756838094,_10 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_10 "delta": {},_10 "status": "completed"_10}
使用回應和會話 ID 繼續對話
對話連續性允許您跨多個 API 調用維持上下文，從而實現與您的FLOW的多輪對話。這對於建置聊天應用程式至關重要，使用者可以在其中進行持續對話。
當您發出請求時，API 會返回一個包含 id 欄位的回應。您可以在下一個請求中使用此 id 作為 previous_response_id 來從中斷的地方繼續對話。
第一則訊息：
_10curl -X POST \_10 "http://$LANGFLOW_SERVER_URL/api/v1/responses" \_10 -H "x-api-key: $LANGFLOW_API_KEY" \_10 -H "Content-Type: application/json" \_10 -d '{_10 "model": "$FLOW_ID",_10 "input": "Hello, my name is Alice"_10 }'
Result
_23{_23 "id": "c45f4ac8-772b-4675-8551-c560b1afd590",_23 "object": "response",_23 "created_at": 1756839042,_23 "status": "completed",_23 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_23 "output": [_23 {_23 "type": "message",_23 "id": "msg_c45f4ac8-772b-4675-8551-c560b1afd590",_23 "status": "completed",_23 "role": "assistant",_23 "content": [_23 {_23 "type": "output_text",_23 "text": "Hello, Alice! How can I assist you today?",_23 "annotations": []_23 }_23 ]_23 }_23 ],_23 "previous_response_id": null_23}
後續訊息：
_10curl -X POST \_10 "http://$LANGFLOW_SERVER_URL/api/v1/responses" \_10 -H "x-api-key: $LANGFLOW_API_KEY" \_10 -H "Content-Type: application/json" \_10 -d '{_10 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_10 "input": "What's my name?",_10 "previous_response_id": "c45f4ac8-772b-4675-8551-c560b1afd590"_10 }'
Result
_23{_23 "id": "c45f4ac8-772b-4675-8551-c560b1afd590",_23 "object": "response",_23 "created_at": 1756839043,_23 "status": "completed",_23 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_23 "output": [_23 {_23 "type": "message",_23 "id": "msg_c45f4ac8-772b-4675-8551-c560b1afd590",_23 "status": "completed",_23 "role": "assistant",_23 "content": [_23 {_23 "type": "output_text",_23 "text": "Your name is Alice. How can I help you today?",_23 "annotations": []_23 }_23 ]_23 }_23 ],_23 "previous_response_id": "c45f4ac8-772b-4675-8551-c560b1afd590"_23}
或者，您可以為 previous_response_id 使用您自己的會話 ID 值：
_10curl -X POST \_10 "http://$LANGFLOW_SERVER_URL/api/v1/responses" \_10 -H "x-api-key: $LANGFLOW_API_KEY" \_10 -H "Content-Type: application/json" \_10 -d '{_10 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_10 "input": "What's my name?",_10 "previous_response_id": "session-alice-1756839048"_10 }'
Result
此示例使用與其他 previous_response_id 示例相同的FLOW，但 LLM 尚未在指定會話中被介紹給 Alice：
_23{_23 "id": "session-alice-1756839048",_23 "object": "response",_23 "created_at": 1756839048,_23 "status": "completed",_23 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_23 "output": [_23 {_23 "type": "message",_23 "id": "msg_session-alice-1756839048",_23 "status": "completed",_23 "role": "assistant",_23 "content": [_23 {_23 "type": "output_text",_23 "text": "I don't have access to your name unless you tell me. If you'd like, you can share your name, and I'll remember it for this conversation!",_23 "annotations": []_23 }_23 ]_23 }_23 ],_23 "previous_response_id": "session-alice-1756839048"_23}
檢索工具調用結果
當您向 /api/v1/responses 端點發送請求來運行包含工具或函數調用的FLOW時，您可以通過新增 "include": ["tool_call.results"] 到請求載荷來檢索每個工具執行的原始詳細資訊。
如果沒有 include 參數，工具調用會返回基本的函數調用資訊，但不會返回原始工具結果。
例如：
_10{_10 "id": "fc_1",_10 "type": "function_call",_10 "status": "completed",_10 "name": "evaluate_expression",_10 "arguments": "{\"expression\": \"15*23\"}"_10},
要獲取每個工具執行的 results，請將 include: ["tool_call.results"] 新增到請求載荷：
_10curl -X POST \_10 "http://$LANGFLOW_SERVER_URL/api/v1/responses" \_10 -H "Content-Type: application/json" \_10 -H "x-api-key: $LANGFLOW_API_KEY" \_10 -d '{_10 "model": "FLOW_ID",_10 "input": "Calculate 23 * 15 and show me the result",_10 "stream": false,_10 "include": ["tool_call.results"]_10 }'
回應現在包含工具調用的結果。 例如：
_10{_10 "id": "evaluate_expression_1",_10 "type": "tool_call",_10 "tool_name": "evaluate_expression",_10 "queries": ["15*23"],_10 "results": {"result": "345"}_10}
Result
_58{_58 "id": "a6e5511e-71f8-457a-88d2-7d8c6ea34e36",_58 "object": "response",_58 "created_at": 1756835379,_58 "status": "completed",_58 "error": null,_58 "incomplete_details": null,_58 "instructions": null,_58 "max_output_tokens": null,_58 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_58 "output": [_58 {_58 "id": "evaluate_expression_1",_58 "queries": [_58 "15*23"_58 ],_58 "status": "completed",_58 "tool_name": "evaluate_expression",_58 "type": "tool_call",_58 "results": {_58 "result": "345"_58 }_58 },_58 {_58 "type": "message",_58 "id": "msg_a6e5511e-71f8-457a-88d2-7d8c6ea34e36",_58 "status": "completed",_58 "role": "assistant",_58 "content": [_58 {_58 "type": "output_text",_58 "text": "The result of 23 * 15 is 345.",_58 "annotations": []_58 }_58 ]_58 }_58 ],_58 "parallel_tool_calls": true,_58 "previous_response_id": null,_58 "reasoning": {_58 "effort": null,_58 "summary": null_58 },_58 "store": true,_58 "temperature": 1.0,_58 "text": {_58 "format": {_58 "type": "text"_58 }_58 },_58 "tool_choice": "auto",_58 "tools": [],_58 "top_p": 1.0,_58 "truncation": "disabled",_58 "usage": null,_58 "user": null,_58 "metadata": {}_58}
在標頭中傳遞全域變數給您的FLOW
全域變數允許您將動態值傳遞到您的FLOW，這些值可以被該FLOW運行中的Components使用。這對於在請求之間可能變化的 API 金鑰、使用者 ID 或任何其他配置傳遞很有用。
/responses 端點接受格式為 X-LANGFLOW-GLOBAL-VAR-{VARIABLE_NAME} 的自訂 HTTP 標頭的全域變數。
變數僅在此特定請求執行期間可用，且不會持續。
變數名稱會自動轉換為大寫。
此示例演示傳遞 OPENAI_API_KEY 變數，這是 AgentBuilder 自動從環境變數偵測到的變數，使用兩個自訂變數用於 USER_ID 和 ENVIRONMENT。變數不必在 AgentBuilder 的全域變數部分中建立 - 您可以在 X-LANGFLOW-GLOBAL-VAR-{VARIABLE_NAME} 標頭格式中傳遞任何變數名稱。
_11curl -X POST \_11 "$LANGFLOW_SERVER_URL/api/v1/responses" \_11 -H "x-api-key: $LANGFLOW_API_KEY" \_11 -H "Content-Type: application/json" \_11 -H "X-LANGFLOW-GLOBAL-VAR-OPENAI_API_KEY: sk-..." \_11 -H "X-LANGFLOW-GLOBAL-VAR-USER_ID: user123" \_11 -H "X-LANGFLOW-GLOBAL-VAR-ENVIRONMENT: production" \_11 -d '{_11 "model": "your-flow-id",_11 "input": "Hello"_11 }'
Result
_23{_23 "id": "4a4d2f24-bb45-4a55-a499-0191305264be",_23 "object": "response",_23 "created_at": 1756839935,_23 "status": "completed",_23 "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",_23 "output": [_23 {_23 "type": "message",_23 "id": "msg_4a4d2f24-bb45-4a55-a499-0191305264be",_23 "status": "completed",_23 "role": "assistant",_23 "content": [_23 {_23 "type": "output_text",_23 "text": "Hello! How can I assist you today?",_23 "annotations": []_23 }_23 ]_23 }_23 ],_23 "previous_response_id": null_23}
使用 X-LANGFLOW-GLOBAL-VAR-{VARIABLE_NAME} 傳遞的變數始終可用於您的FLOW，無論它們是否存在於資料庫中。
如果您的FLOWComponents引用未在標頭或您的 AgentBuilder 資料庫中提供的變數，FLOW預設會失敗。
要避免此情況，您可以將 FALLBACK_TO_ENV_VARS 環境變數設定為 true，這允許FLOW在未以其他方式指定時使用 .env 檔案中的值。
在上面的示例中，如果未在標頭中提供，OPENAI_API_KEY 將回退到資料庫變數。
如果啟用了 FALLBACK_TO_ENV_VARS，USER_ID 和 ENVIRONMENT 將回退到環境變數。
否則，FLOW會失敗。
