18 關於代理程式工具
Oracle AI Data Platform Workbench 支援可設定存取資料並符合使用案例的工具範本。
專員支援由單一專員組成的組態，可連接一或多個工具。AI Data Platform Workbench 提供三種工具範本，可透過視覺化流程或程式碼設定使用：
- 自訂程式碼：自訂程式碼工具可讓 AI 開發人員使用 Python 實作其工具。開發人員將工具封裝成 ZIP 格式、上傳至工作區，然後將其設定為代理程式中的節點。自訂程式碼工具適用於內建工具無法提供所需整合的情況。
- HTTP 要求： HTTP 要求工具可讓開發人員運用 AI 資料平台工作台 API 及其提供的功能，在其代理程式中使用支援的 REST API 呼叫。代理程式可以使用 REST API 來建立工作區物件、檢查詳細資訊、提取清單或修改現有物件。如需可用 API 的完整清單，請參閱 Oracle AI Data Platform Workbench 的 REST API 。
- 提示：提示工具可讓 AI 開發人員定義參數化的提示，以便針對其選擇發放給 LLM。提示工具的一般使用案例包括電子郵件草擬工作、翻譯工作、樣式轉換、Git 確認訊息，以及程式碼說明。
- RAG ：RAG 工具可讓專員在產生回應之前提取相關的外部知識。在 AI Data Platform Workbench 中，RAG 工具會查詢知識庫 (26ai Vector Search)，並擷取與語意相關的文件區塊。接著，這些區塊會傳送給代理程式以產生回應。
- SQL ：此 SQL 工具可讓代理程式針對透過外部目錄 (例如 Oracle Autonomous AI Lakehouse 、Oracle Autonomous AI Transaction Processing 或 Oracle Autonomous AI Database) 註冊的結構化資料來源執行 SQL 查詢。此工具適用於預先定義 SQL 查詢且可參數化的案例。目標是讓專員將值指派給參數。此工具不是根據自然語言提示產生 SQL 查詢的 NL2SQL 工具。
附註：
SQL 工具只會針對外部目錄中的資料執行查詢。它不支援儲存在標準目錄中的資料。
透過視覺流程的代理程式流程工具
透過視覺化流程將工具新增至服務人員時，您可以在服務人員中的工具範本底下找到工具。將工具拖放至視覺化流程工作區，即可將工具新增至您的代理程式。在工作區上拖曳工具節點後，節點會自動與代理程式連線。
您可以在「參數」頁籤中設定每個工具，然後按一下「測試」頁籤，即可獨立測試代理程式。
附註：
您必須先將 AI 運算連附至您的代理程式，才能測試系統工具。如果未連附運算，則會停用「測試」頁籤。透過 LangGraph 代碼的代理程式工具
您可以透過 AIDPToolConf() 類別的執行處理，將工具新增至 LangGraph 編碼的代理程式。
from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool = AIDPToolConf(name, description, tool_class, conf, params)
- 名稱：協助使用者和 LLM 瞭解工具用途的描述性名稱。
- 描述：提供足夠資訊給使用者與 LLM 的完整摘要，以瞭解工具的功能。
- tool_class：支援的工具類型
PromptTool、SQLTool、RAGTool、HTTPTool及MCPTool。 - conf：工具組態。此資訊會對 LLM 隱藏。
- 參數：對 LLM 顯示的參數。
自訂的工具
自訂程式碼工具可讓代理程式開發人員使用自己的 Python 程式碼擴充 AI 資料平台。
您可以將工具實作封裝為 ZIP 檔案、將它上傳至您的工作區，然後將其設定為代理程式中的「自訂程式碼」工具節點。代理程式會在程式實際執行時使用 LLM 提供的參數，將您的程式碼呼叫為工具。
「自訂程式碼」工具適用於內建工具 (HTTP、SQL、RAG、MCP) 未涵蓋您需要整合的情況 — 例如，當您需要執行本機運算、剖析網域特定格式，或組成多個應以單一工具呼叫方式顯示給代理程式的步驟時。
為您的自訂程式碼工具上傳含有 Python 程式碼的 ZIP 檔案時，AI Data Platform Workbench 有下列限制：
| 限制條件 | 限制 |
|---|---|
| ZIP 大小上限 | 10 MB |
| ZIP 檔內的最大檔案大小 | 每個檔案 10 MB |
| 未壓縮大小總計上限 | 500 MB |
| 路徑遍歷 | 已封鎖 (../ 已拒絕) |
附註：
在連附至您代理程式的 AI 運算上執行自訂程式碼工具。此程式碼可以存取受限於工作區網路組態的運算環境和外送網路存取。只上傳您信任的原始碼。自訂程式碼工具參數
在「參數」頁籤上，您可以為套件中的每個工具類別設定靜態設定。「工具類別」下拉式清單可讓您在套件中發現的工具之間切換。
- 工具類別：選取要設定的工具類別。下拉式清單中會填入
tool_implementation.py中註冊的類別。 - 描述：工具功能的清楚簡要描述。說明會提供給專員，並協助 LLM 決定何時呼叫工具。預設描述是從 tool_config.json 讀取，可以在此處覆寫。
- 組態：工具在程式實際執行時所需的靜態設定值。這些是在
tool_config.json的 conf 物件中定義的索引鍵。範例包括逾時、base_dir、max_output_lines 以及證明資料參照。組態值支援{{variable}}程式實際執行參數參照。階段作業變數目前不會取代為自訂工具組態；如果您需要階段作業值，請將它當作代理程式的程式實際執行參數來傳送。 - AI 工具定義：對代理程式公開的結構，包括工具名稱、描述，以及代理程式可以通過的執行時期參數。綱要會自動從
tool_config.json中的綱要陣列轉譯。
自訂程式碼工具製作
「自訂程式碼」工具套件是具有下列結構的 ZIP 檔案：
my_tool.zip
├── tool_implementation.py # Required. Contains the tool class(es).
├── tool_config.json # Required. Tool metadata and schema.
├── requirements.txt # Optional. Python dependencies.
├── utils/ # Optional. Helper modules.
│ ├── __init__.py
│ └── helpers.py
├── config/ # Optional. Static configuration files.
│ └── settings.yaml
└── wheels/ # Optional. Bundled wheel files for offline install.
└── humanize-4.15.0-py3-none-any.whl 工具 _ 導入 .py
每個工具類別都會擴充 CustomToolBase，並以 @BaseTool.register 裝飾。類別必須實行 _execute_tool 類別方法，該方法會接收工具組態、代理程式的程式實際執行參數以及系統相關資訊環境變數，並傳回如 dict、str 或 list 的值。
以下為 tool_implementation.py 的空白範例範本：
"""Custom Code tool implementation."""
from aidputils.agents.tools.custom_tools.base import CustomToolBase
@BaseTool.register
class MyTool(CustomToolBase):
"""Brief description of what the tool does."""
@classmethod
def _validate_config(cls, conf, runtime_params, **context_vars):
"""Optional. Validate configuration before execution.
Raise ValueError to abort the call.
"""
# Example: require an api_key in the tool configuration
if not conf.get("conf", {}).get("api_key"):
raise ValueError("api_key is required")
@classmethod
def _execute_tool(cls, conf, runtime_params, **context_vars):
"""Required. Implement the tool logic.
Args:
conf: the AIDPToolConf dict. User configuration values
live under conf["conf"] when the tool is invoked from
a deployed agent. During a Test run the tool may
receive a flat conf dict; the Developer Toolkit example
below uses a small _get_cfg helper that tolerates both
shapes.
runtime_params: the runtime parameters passed by the
agent at invocation time.
context_vars: system context (such as datalake_id).
Returns:
Any value (dict, str, list, ...). It will be wrapped into
the MCP response by the framework.
To signal a failure, raise an exception:
- ValueError -> INVALID_CONFIG
- any other exception -> TOOL_EXECUTION_ERROR
Do NOT return {"error": "..."}; the framework wraps a
successful return in {"response": ..., "success": True},
so a returned error dict is treated as a normal payload
and the agent will not see it as a failure.
"""
tool_conf = conf.get("conf", conf)
param_value = runtime_params.get("my_param", "")
# Tool logic here
return {"output": f"Processed: {param_value}"}
@classmethod
def _transform_response(cls, response):
"""Optional. Transform the response before MCP formatting."""
return response工具 _config.json
tool_config.json 檔案描述套裝程式中的工具 — 其顯示名稱、描述、版本、程式實際執行參數綱要以及預設組態值。在 tool_implementation.py 中註冊的每個工具在工具陣列中都必須有對應的項目。
tool_config.json 的空白範例範本：{
"displayName": "My Tool Package",
"description": "Brief description of the tool package.",
"tools": [
{
"toolClassName": "MyTool",
"displayName": "My Tool",
"description": "Clear description of when the agent should call this tool.",
"version": "1.0.0",
"schema": [
{
"name": "my_param",
"type": "string",
"description": "What this parameter is for."
}
],
"conf": {
"timeout": 30
}
}
]
}
結構欄位類型
視覺化產生器中的「參數」頁籤接受字串、數字和布林值。以手動撰寫 tool_config.json 時，程式實際執行接受較寬的集合：int，integer，float，double，number，bytes，list，sequence，dict，map，set，tuple，none，null，plus generic form 如 list[int]。這些較廣泛的類型可從 JSON 使用，但不會顯示在 UI 下拉式清單中。
要求 .txt
requirements.txt 檔案會列出您工具所需的 Python 相依性。支援標準管線語法，包括版本指定器和註解。此檔案是選擇性的 — 如果您的工具只使用 Python 標準程式庫或預先安裝的套裝軟體，您就不需要使用 requirements.txt。
以下為 requirements.txt 的空白範例：
# List third-party dependencies one per line.
# Examples:
# humanize>=4.0
# python-dateutil>=2.8,<3.0
# beautifulsoup4==4.12.3 AI Data Platform Workbench 會先篩選 requirements.txt 中的相依性，再於 AI 運算中安裝相依性，以防止程式實際執行與平台本身發生衝突。篩選規則如下：
| 類別 | 範例 | 動作 |
|---|---|---|
| 平台套件 | langgraph、langchain-core、langchain-oci、langchain_mcp_adapters、pyyaml | 已捨棄 (會中斷代理程式程式實際執行)。 |
| 預先安裝的套件 | oci，要求，要求工具，websockets，加密，認證，pyopenssl，urllib3，pydantic，pydantic-core，pydantic-settings，numpy，oracledb，sqlalchemy，aiohttp，httpx，httpx-sse，anyio，jsonschema，orjson | 已略過 (已可供使用，不需要宣告)。 |
| URL 或 VCS 安裝 | git+https://..., -e ./local_pkg | 已封鎖 (安全性)。 |
| 其他所有項目 | 人化，美湯 4，jmespath | 已安裝。 |
附註：
在requirements.txt 中宣告的相依性會在代理程式完整部署期間安裝。從配置面板執行單一測試時，不會安裝相依性。如果您的工具取決於協力廠商套裝軟體，請先部署代理程式，然後從 Playground 執行該工具。
對於需要未預先安裝的相依性，以及確定性、離線安裝非常重要的工具，您可以在 ZIP 根目錄的 wheels/ 目錄中組合 .whl 檔案。此平台會先從本機操控盤目錄進行安裝，且只有在需要時才倒回套裝程式索引。這是生產工具的建議方法。
用於離線安裝的搭售車輪
pip download \
--dest wheels/ \
--platform manylinux_2_28_x86_64 \
--python-version 3.11 \
--only-binary=:all: \
-r requirements.txt
工具生命週期鉤點
自訂程式碼工具支援三種生命週期方法。只需要 _execute_tool。
| 方法 | 呼叫時 | 目的 |
|---|---|---|
| _validate_config | 在 _execute_tool 之前 | 驗證組態。產生 ValueError 以在執行前中止呼叫。 |
| _ 執行工具 | 在每次工具呼叫時 | (必要) 實作工具的行為。傳回任何值 (dict，str，list) 並發出異常狀況來表示失敗 (ValueError → INVALID_CONFIG，任何其他異常狀況 → TOOL_EXECUTION_ERROR)。請勿使用傳回的 {"error"："..."} dict，因為它被視為一般有效負載。 |
| _transform_response | 執行 _tool 之後 | 將回應包裝成 MCP 格式並傳回給代理程式之前，請先轉換回應。 |
| prompt_template | 字串 | LLM 使用的提示樣板，其變數為 {{variable}} 格式以進行動態插入 |
組態值與程式實際執行參數
「自訂程式碼」工具有兩個容易混淆的不同輸入來源。組態值來自「參數」頁籤的「組態」區段，而且會在建置代理程式時放入工具中。程式實際執行參數來自呼叫時的代理程式，且在每次呼叫時都不同。
- 可透過 conf.get ("conf"，conf) 存取組態值。您可以針對呼叫之間沒有變更的項目使用它們 - 基本 URL、證明資料參照、逾時、輸出限制。
- 可透過 runtime_params.get ("name") 存取程式實際執行參數。將它們用於代理程式實際在呼叫時決定的值 - 查詢、檔案路徑、要求主體。
附註：
組態值可以通過樣板替代，即使您將它們定義為數字，也可能會到達字串。一律強制數值組態值，例如：int(tool_conf.get("timeout", 30))。
每個套件多工具
單一 ZIP 可以包含多個工具類別。在 @CustomToolBase.register 註冊的每個類別都會成為代理程式中的個別工具。「套裝程序」頁籤上的「工具」面板會列出所有找到的工具，並可讓您個別啟用每個工具。每個工具都會透過「工具類別」下拉式清單在「參數」頁籤上個別設定。
透過 LangGraph 程式碼的程式碼工具
從程式碼建構器中，透過 aidpUtils Python 程式庫註冊「自訂程式碼」工具，方法是參照已上傳的套裝軟體並選取其其中一個工具類別。
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf
hello_tool_conf = AIDPToolConf(
name="hello_tool",
description="Returns a hello world greeting.",
tool_class="HelloTool", # the class registered with @BaseTool.register
conf={}, # values from tool_config.json "conf"; supports {{variable}} substitution
params=[
{"name": "name", "type": "string",
"description": "Name to greet."}
],
)
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())
tool_class 必須是透過 @BaseTool.register 在 tool_implementation.py 中註冊的確切類別名稱。架構會查詢 BaseTool.tool_class_registry[tool_class] 中的類別。conf 會鏡射 tool_config.json 中相符項目的 conf 物件。
附註：
請勿將package_path 或 tool_class_name 放置在 conf 中，因為不會使用它們。
測試代理程式自訂程式碼工具
測試頁籤可讓您在不執行完整代理程式的情況下執行工具。提供組態中所參照之任何程式實際執行參數和所有階段作業變數的值，然後按一下「執行」來呼叫工具並檢視回應。
附註：
如果您的工具取決於requirements.txt 中宣告的協力廠商套裝軟體，則會在代理程式的完整部署期間 (而不是在單一測試執行期間) 安裝相依性。若要測試相依於其他套裝程式的程式碼，請先部署代理程式，然後再從 Playground 呼叫工具。
新增自訂工具至專員
您可以在代理程式中新增自訂工具，以使用您自己的 Python 程式碼擴充 AI 資料平台。
附註：
新增自訂程式碼工具之前，必須先將 AI 運算連附至您的代理程式。必須要有 AI 運算，才能安裝相依性並執行此工具。- 在套件頁籤中，按一下以選取具有自訂程式碼的 ZIP 檔案，或將它拖放到畫面上。等待上傳完成。
- 在「套裝程式」頁籤的工具區段中，複查找到的工具清單。在您的
tool_implementation.py中找到的每個工具類別都會列出其類別名稱、描述和版本。
- 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。
遠端 MCP 伺服器工具
代理程式流程開發人員可以使用「遠端 MCP 伺服器」工具，將其代理程式流程連線至遠端模型相關資訊環境協定 (MCP) 伺服器。
視覺化產生器以及程式碼產生器體驗都提供 MCP 工具。在程式碼建構器體驗中，MCP 連線可以透過 aidpUtils Python 程式庫設定。在本節中，我們將帶您瞭解 Visual Builder 和程式碼產生器體驗。
附註：
此功能支援具有 HTTP 串流傳輸 (遠端伺服器) 的 MCP 伺服器。本機、stdio-transport MCP 伺服器不支援。Oracle AI Data Platform Workbench 證明資料存放區中的 MCP 證明資料
設定 MCP 伺服器時，您必須選取遠端 MCP 伺服器是否需要沒有認證或 Bearer 記號。如果您的 MCP 伺服器需要認證權杖，則必須先將該權杖新增至您的「證明資料存放區」，MCP 伺服器才能參照該權杖。
建立 MCP 伺服器證明資料時，您可以選取證明資料類型的加密密碼記號選項，然後提供 ID 金鑰，例如 API 金鑰和記號值。如需詳細資訊，請參閱建立證明資料 (預覽) 。
附註：
單一證明資料可保存多個金鑰。可公開使用的 MCP 伺服器不需要額外的認證 。例如，連線至 https://mcp.deepwiki.com/mcp 的外觀如下：
![將會顯示 [Add custom MCP Server] (新增自訂 MCP 伺服器) 對話方塊。系統會填入可公開使用之 MCP 伺服器 DeepWiki 的資訊。](img/mcpserver-publicmcp.png "將會顯示 [Add custom MCP Server] (新增自訂 MCP 伺服器) 對話方塊。系統會填入可公開使用之 MCP 伺服器 DeepWiki 的資訊。")
如何向服務人員公開 MCP 工具
成功連線至遠端 MCP 伺服器後，您就可以開始設定要向代理程式公開的伺服器上代管的工具。如果是 DeepWiki MCP 伺服器，下方會顯示 MCP 伺服器組態面板。
「工具」頁籤會在左側顯示 MCP 伺服器中可用的工具清單。您必須新增工具，才能向您的專員公開這些工具。您可以按一下全部新增選項來一次顯示所有工具，或按一下個別的每個工具新增選項來選取工具的子集。
在下面的範例中，我們新增了兩種工具 (read_wiki_structure、read_wiki_structure)。您可以按一下移除來移除工具。
「工具」頁籤的右側面板提供每個工具的相關文件，包括工具名稱、工具描述以及工具參數。在下面的螢幕擷取畫面中，顯示 GitHub MCP 伺服器工具 add_comment_to_pending_review 的範例。
Oracle AI Data Platform Workbench 對每個工具提供了一些額外的控制項。您可以隱藏代理程式的參數，並將值指派給這些參數。例如，在 GitHub 中，您可以選擇讓代理程式僅對一個預先決定的儲存區域 (例如 oracle-aidp-samples) 加註。若要達到此目的，請停用 repo 參數，並在文字方塊中指派預設值：
在工具指示欄位中，您也可以置換工具描述，並提供其他指示的替代描述。對於大多數使用案例，建議您採用 MCP 伺服器提供的描述。
透過 LangGraph 程式碼的遠端 MCP 伺服器工具
aidpUtils Python 程式庫可讓開發人員選取遠端 MCP 伺服器，並將其工具子集公開給使用 LangGraph 建立的代理程式。如需輔助功能 API 參照，請參閱 Oracle AI Data Platform Workbench 的輔助功能 API 。
您可以建立 build_structured_tools_from_allowed_mcp_tools 執行處理來建置允許的工具集合：
from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools
TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>,
server_name=<MCP_SERVER_NAME>,
endpoint=<MCP_ENDPOINT>,
transport="streamable_http",
auth=<MCP_AUTH>,
headers={}
)- <MCP_SERVER_NAME> 是您要提供給 MCP 伺服器的顯示名稱。這是用於文件用途，不會對代理程式顯示。
- <MCP_ENDPOINT> 是 MCP 伺服器的端點 (例如 https://api.githubcopilot.com/mcp/)
- <MCP_AUTH> 是索引鍵為 "authType" 的字典。此索引鍵接受兩個值：
NO_AUTH或BEARER_TOKEN。如果是BEARER_TOKEN，則應使用另一個索引鍵：含有 Bearer 權杖值的 "token"。 - <ALLOWED_MCP_TOOLS> 是要向您的代理程式公開之 MCP 伺服器中的工具清單。每個工具都需要遵循 MCP 通訊協定的完整 JSON 工具定義。
範例如下：
MCP_SERVER_NAME = "test_mcp"
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp"
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }
{
"ALLOWED_TOOLS": [
{
"tool": {
"name": "get_current_weather",
"description": "Get current weather for a given city with advanced options.",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"unit": {
"type": "string",
"default": "metric"
},
"include_historical": {
"type": "boolean",
"default": false
},
"detailed": {
"type": "boolean",
"default": true
},
"timeout": {
"type": "integer",
"default": 30
}
},
"required": [
"city"
]
}
},
"instruction": "",
"argOverrides": {}
},
{
"tool": {
"name": "get_forecast",
"description": "Get forecast for a given city with customizable options.",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
},
"days": {
"type": "integer",
"default": 5
},
"unit": {
"type": "string",
"default": "metric"
},
"include_alerts": {
"type": "boolean",
"default": false
},
"detailed": {
"type": "boolean",
"default": true
},
"hourly": {
"type": "boolean",
"default": false
}
},
"required": [
"city"
]
}
},
"instruction": "",
"argOverrides": {}
}
]
}
MCP_HEADERS = {}
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
server_name=MCP_SERVER_NAME,
endpoint=MCP_ENDPOINT,
transport="streamable_http",
auth=MCP_AUTH,
headers=MCP_HEADERS,
)
在您類別代理程式定義的 setup() 方法中，使用 langchain.agent create_agent 建立代理程式的執行處理時，即可使用 TOOLS 物件：
def setup(self):
logger.info("Initializing TestMcpAgent")
oci_llm = init_oci_llm(llm_conf)
system_prompt = textwrap.dedent(
"""
You're a weather agent. Append 12345 to every response.
"""
).strip()
self.agent = create_agent(
name="test_mcp_high_code",
model=oci_llm,
tools=TOOLS,
system_prompt=system_prompt,
debug=True,
)
logger.info("Agent ready.")或者，如果您使用階段作業變數來儲存 Bearer 權杖的值，則可以將先前建立之階段作業變數的參照指派給 auth 組態說明的權杖索引鍵。舉例而言：
test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=test_mcp_mcp_allowed_tools,
server_name="test_mcp",
endpoint="http://144.25.36.217:9301/mcp",
transport="streamable_http",
auth=test_mcp_mcp_auth_config,
headers={}
)遠端 MCP 伺服器工具的程式碼範例
我們會在 AI Data Platform Workbench 範例 GitHub repository 中為多個 MCP 案例提供端對端程式碼範例。
測試遠端 MCP 伺服器工具
選取工具之後，下一個步驟通常是測試個別工具，以確保工具如預期般運作。這可以透過 MCP 工具節點的「測試」頁籤來完成。
選取您在「工具」頁籤中新增的工具，提供參數值，然後按一下「測試」按鈕。
工具的輸出會顯示在右側面板中。
詳細資訊頁籤提供認證方法、MCP 伺服器 URL 和描述的相關資訊。
認證方法旁的「編輯」按鈕可讓您修改遠端 MCP 工具節點的組態。您可以變更建立連線時所使用的顯示名稱、描述以及 Bearer 權杖：
![將會顯示 [Edit custom MCP Server] (編輯自訂 MCP 伺服器) 對話方塊。系統會填入 https://api.githubcopilot.com/mcp 的詳細資訊。](img/mcpserver-test4.png "將會顯示 [Edit custom MCP Server] (編輯自訂 MCP 伺服器) 對話方塊。系統會填入 https://api.githubcopilot.com/mcp 的詳細資訊。")
從 Visual Builder 將代理程式連線至遠端 MCP 伺服器
您可以將自訂 MCP 伺服器工具節點拖曳至工作區，將遠端 MCP 伺服器的存取權新增至您的代理程式。
附註：
代管代理程式的 AI 運算會繼承其工作區的網路設定值。如果啟用代管 AI 運算之工作區的專用網路存取，您的代理程式就只能連線所選專用 VCN 和子網路中代管的 MCP 伺服器。您的代理程式可能無法連線公用網際網路上可用的遠端 HTTP 伺服器。- 瀏覽至您的專員。
- 在流程頁籤的工具樣板下，按一下自訂 MCP 伺服器並將其拖曳至工作區。
- 提供 MCP 伺服器的伺服器 URL。
- 提供 MCP 伺服器的顯示名稱。這是視覺化產生器工作區中顯示的節點名稱。
- 可選：為您的 MCP 伺服器提供說明。並未將描述欄位提供給代理程式。
- 從認證下拉式功能表中，選取一種認證方法。
- 無認證：如果遠端 MCP 伺服器可公開使用且不需要認證，請使用此選項。
- Bearer token ：如果遠端 MCP 伺服器要求驗證 token，請使用此選項。您必須將 API 金鑰儲存在 Oracle AI Data Platform Workbench 證明資料存放區中，並且提供證明資料存放區項目的參照。
- 按一下連線。AI Data Platform Workbench 會測試連線並回報結果。
HTTP 要求工具
HTTP 要求工具可讓您的代理程式呼叫任何 HTTPS REST API。
您可以設定要求，包括方法、URL、標頭、查詢參數、要求主體、認證，以及選擇性地設定回應最佳化步驟。代理程式接著會在程式實際執行時呼叫端點。視覺化產生器和程式碼產生器都提供 HTTP 要求工具。在程式碼產生器中，此工具是透過 aidpUtils Python 程式庫進行設定。
附註：
HTTP 要求工具僅支援 https：// 和 HTTP：// 要求。不支援 WebSocket 連線 (ws/wss)、二進位檔案上傳及自行簽署憑證。附註：
代管代理程式的 AI 運算會繼承其工作區的網路設定值。如果您對代管 AI 運算的工作區啟用專用網路存取，您的代理程式將只會連線您所選專用 VCN 和子網路中的 HTTP 端點。您的代理程式無法連線公用網際網路上的端點。設定「HTTP 要求」工具時，必須提供下列設定值：
| 組態 | 描述 |
|---|---|
| HTTP 方法 | 要使用的 HTTP 動詞 。支援的方法包括 GET、POST、PUT、PATCH 和 DELETE。 |
| URL | 目標端點的完整 URL。此 URL 支援 {{sessionVariables.variable_name}} 階段作業變數參照和 {{variable}} 程式實際執行參數參照。例如：https://api.example.com/users/{{user_id}}/orders。
|
| Timeout | 工具等待遠端端點回應的最長時間。預設值為 30 秒，上限為 300 秒。 |
| 認證類型 | 呼叫端點時所使用的認證方法。請參閱下方的「認證」段落，瞭解支援的認證方法清單。 |
附註：
在連附至您代理程式的 AI 運算上執行自訂程式碼工具。此程式碼可以存取受限於工作區網路組態的運算環境和外送網路存取。只上傳您信任的原始碼。標頭
標頭是與 HTTP 要求一起傳送的索引鍵 - 值組。您可以按一下「新增」按鈕，視需要新增標頭。標頭值可以使用 {{variable_name}} 語法參照階段作業變數和程式實際執行參數。
附註：
對於機密標頭，您應該使用「認證類型」欄位，以確保從「證明資料存放區」安全地插入證明資料。授權、Cookie 及 X-API 金鑰為機密標頭，無法透過「標頭」區段進行設定。查詢參數
查詢參數會附加至 URL 作為查詢字串。您可以按一下「新增」按鈕，視需要新增多個查詢參數。如同標頭，查詢參數值可以參照階段作業變數和程式實際執行參數。
描述
描述欄位描述工具的作用、使用時間，以及其產生的輸出或效果種類。說明會提供給專員，並協助 LLM 決定何時呼叫工具。
- • 目的：說明工具在清楚的句子中所設計的用途。範例：「此工具會從知識庫擷取客戶支援回報項目，並依優先順序層級彙總它們。」
- 使用時機：描述服務人員應呼叫此工具與其他工具的條件。
- 輸入與輸出：簡短描述工具所需的參數及其傳回內容的形狀。
HTTP 要求認證
「HTTP 要求」工具支援多種認證方法。從「認證類型」下拉式清單中選取適當的方法。
| 認證類型 | 描述 |
|---|---|
| 不認證 | 未新增任何認證至要求。將此用於可公開存取的端點。 |
| OCI 資源負責人 | 要求是使用 AI 運算的 OCI 資源主體簽署。呼叫 OCI 服務 (例如物件儲存) 或 OCI Generative AI 服務時使用此選項。存取受 OCI IAM 原則管控。 |
| 基本認證 | 使用者名稱和密碼會在「授權」標頭中編碼並傳送。證明資料必須儲存在「證明資料存放區」。 |
| Bearer 權杖 | 「授權」標頭中會傳送 Bearer 權杖。權杖必須儲存在「證明資料儲存庫」中。 |
| 標頭認證 | API 金鑰會以自訂標頭傳送 (例如 X-API-Key)。標頭名稱是可設定的，且金鑰值必須儲存在「證明資料存放區」中。 |
當您選取需要加密密碼的認證方法時，組態面板會顯示證明資料選擇器。按一下證明資料選擇器以選取先前儲存的證明資料，或從「證明資料存放區」建立新的證明資料。如需逐步程序，請參閱 MCP 伺服器文件的「將證明資料儲存在證明資料存放區」小節中。
階段作業變數與程式實際執行參數
您可以使用 {{sessionVariables.variable_name}} 語法，在 URL、標頭值、查詢參數值以及要求主體中參照階段作業變數。代理程式在呼叫時傳送的程式實際執行參數可以使用 {{variable_name}} 語法參照。
https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/o工具執行時，{{sessionVariables.region}} 會取代為目前階段作業的區域階段作業變數值，而 {{bucket}} 會取代為代理程式在呼叫時傳送的值。
附註：
替代至 URL 或查詢參數時，範本值會自動以 URL 編碼。您不需要自行使用 URL 編碼。AI 工具定義
組態面板右側會顯示 [AI 工具 ] 定義。這是對代理程式公開的綱要，包括工具名稱、描述，以及代理程式在呼叫工具時可傳送的程式實際執行參數清單。AI 工具定義會從「描述」欄位以及從 URL、標頭、查詢參數和主體中偵測到的 {{variable}} 預留位置自動產生。
[AI 工具定義 ] 窗格是此文件之前顯示之 HTTP 工具配置面板右側的面板。在您提供描述並定義至少一個執行時期參數之前，「AI 工具」定義窗格會顯示預留位置訊息。在 URL、標頭、查詢參數或主體中填入描述並參照至少一個 {{variable}} 之後，會在窗格中呈現綱要。
最佳化代理程式的回應
許多 API 會傳回包含代理程式不需要之欄位的大型回應。將整個回應傳回給代理程式會使用記號，並且可以降低代理程式推理的品質。「HTTP 要求」工具提供「回應最佳化」區段，可讓您在將回應有效負載傳回給代理程式之前縮減回應有效負載。
- 選擇 JSON 欄位：從 JSON 回應選取欄位子集。您可以使用點標記 (例如 data.results) 指定巢狀物件的路徑，以及要包含或排除的欄位清單。
- HTML CSS 選取器：使用 CSS 選取器 (例如 article.content) 擷取 HTML 回應的子集。選擇性地去除 HTML 標籤，只傳回文字 。
- 文字截斷：回應的字元數上限，以防止文字回應過大。
錯誤處理與錯誤代碼
當 HTTP 要求失敗時，工具會傳回代理程式的結構化錯誤回應。錯誤包括錯誤代碼、人類可讀取的訊息，以及有關失敗的詳細資訊。代理程式可以使用此資訊來決定是要重試、回到其他工具，還是要向使用者報告失敗。
| 錯誤代碼 | 類別 | 意義 | 可重試 |
|---|---|---|---|
| CONNECTION_TIMEOUT | 網路圖 | 遠端端點未在設定的逾時內回應。 | 是 |
| DNS 失敗 | 網路圖 | 無法解析 URL 中的主機名稱。 | 是 |
| CONNECTION_REFUSED | 網路圖 | 遠端端點拒絕連線。 | 是 |
| SSL 憑證錯誤 | TLS | 無法驗證遠端端點的 TLS 憑證。 | 編號 |
| 未授權 | HTTP 401 | 遠端端點拒絕證明資料。確認證明資料參照有效且未過期。對於 OCI 資源主體，請確認 AI 運算在此環境中有作用中的資源主體。 | 編號 |
| 禁止 | HTTP 403 | 已順利認證證明資料，但沒有要求之資源的權限。請檢查連附至資源的 API 範圍、權限或 IAM 原則。 | 編號 |
| 找不到 (_F) | HTTP 404 | 遠端端點找不到要求的資源。 | 編號 |
| 速率 _ 限制 | HTTP 429 | 遠端端點的速率限制為呼叫程式。請在「重試之後」標頭指示的延遲之後重試。 | 是 |
| SERVER_ERROR | HTTP 5xx | 遠端端點傳回伺服器錯誤。通常為暫時性問題。 | 是 |
| SERVICE_UNAVAILABLE 無法 | HTTP 503 | 遠端端點暫時無法使用。 | 是 |
| 無效範本 | 驗證 | 無法解析 {{variable}} 參照。確認已定義每個參照的階段作業變數與程式實際執行參數，而且在呼叫階段有值。
|
編號 |
| 無效網址 | 驗證 | URL 的格式錯誤、使用不支援的協定或解析為封鎖的位址 (例如，專用 IP 位址或雲端描述資料端點)。 | 編號 |
| 回應放大 | 驗證 | 回應超過 10 MB 的最大回應大小。 | 編號 |
| 已超過費率限制 | 平台 | 代理程式已超過平台的每個代理程式要求速率限制 (每分鐘 60 個要求) 或並行限制 (10 個並行要求)。 | 是 |
每個錯誤回應都包含一個具有建議下一步的導引欄位，以及包含經歷時間和任何錯誤特定相關資訊環境 (例如 HTTP 狀態代碼) 的詳細資訊欄位。
透過 LangGraph 程式碼的 HTTP 要求工具
從程式碼建構器中，HTTP 要求工具是透過 aidpUtils Python 程式庫設定。定義 AIDPToolConf，並將 tool_class 設為 HttpEndpointTool ，然後在 conf 欄位中傳送組態說明。
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf
weather_http_tool_def = {
"method": "GET",
"url": "https://api.openweathermap.org/data/2.5/weather",
"params": {
"q": "{city}",
"units": "metric",
"appid": "{api_key}"
},
"auth_type": "NO_AUTH",
"auth_config": {}
}
weather_http_tool_params = [
{"name": "city", "type": "string",
"description": "Name of the city."},
{"name": "api_key", "type": "string",
"description": "OpenWeather API key."}
]
weather_http_tool_conf = AIDPToolConf(
name="get_weather",
description="Get current weather for a city.",
tool_class="HttpEndpointTool",
conf=weather_http_tool_def,
params=weather_http_tool_params
)
weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())
conf 說明支援與 Visual Builder 相同的欄位：方法、URL、標頭、參數、主體、auth_type、auth_config 和 response_optimization。參數清單定義代理程式可通過的執行時期參數。
| auth_type | auth_config 欄位 |
|---|---|
| 沒有認證 (_A) | {} (空白)
|
| 資源 _ 主要項目 | {} (空白)
|
| 基本 _ 認證 | OCI 保存庫中證明資料的使用者名稱、密碼 (或 username_vault_id、password_vault_id) |
| 持有人授權 | bearer_token (或 bearer_token_vault_id) |
| API 金鑰認證 | api_key (或 api_key_vault_id)，header_name (預設 X-API 金鑰) |
| OAUTH2_CLIENT_CREDENTIALS | token_endpoint，scope，client_id，client_secret (或 client_id_vault_id，client_secret_vault_id) |
測試代理程式自訂程式碼工具
測試頁籤可讓您在不執行完整代理程式的情況下執行工具。提供組態中所參照之任何程式實際執行參數和所有階段作業變數的值，然後按一下「執行」來呼叫工具並檢視回應。
回應面板會顯示 HTTP 狀態代碼、回應標頭、回應主體以及經歷時間 (毫秒)。如果啟用回應最佳化，則最佳化回應也會顯示在原始回應旁邊。
新增 HTTP 要求工具至代理程式
您可以新增 HTTP 要求工具至您的代理程式，以便呼叫 HTTPS REST API。
附註：
新增自訂程式碼工具之前，必須先將 AI 運算連附至您的代理程式。必須要有 AI 運算，才能安裝相依性並執行此工具。- 從「工具」樣板，將「HTTP 要求」工具拖放至工作區。
- 提供 HTTP 要求的標頭。按一下新增以新增其他標頭。
- 為您的 HTTP 要求提供任何查詢參數。按一下新增以新增其他參數。
- 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。
提示工具
提示工具可讓您在具有範本提示的 AI 代理程式中呼叫 LLM，然後將 LLM 回應傳回代理程式。
您提供給 LLM 的提示可以包含以雙大括號識別的參數，例如 {{PARAMETER_NAME}}。參數值會在呼叫工具時由代理程式指派。
何時使用提示工具
- 您的提示長度相當長，需要跨數個 100 記號的詳細格式指示。
- 在代理程式指示中合併提示會增加相關資訊環境使用量並大幅增加成本，尤其是在代理程式使用 SOTA LLM 時。
- 想要將提供給代理程式的指示大小降到最低，以降低成本。
- 提示工具所定義的工作可以比使用代理程式的推理模型更小、更快的 LLM 來處理。較小的模型通常符合成本效益，在某些情況下，可以專門以特定形式或格式產生資料。
- 提示工具允許結構化輸入參數控制輸出產生。如果您的使用案例可以參數化，且產生可能會因階段作業而異，則在提示工具中封裝產生是合理的。
此外，在提示工具中封裝產生指示會遵循許多現代化的代理程式架構最佳實務，包括工具重複使用性、維護性、模態性、輸出一致性、擴展性及治理。部分範例使用案例包括：
- 在可作為範本的預先定義、已核准結構之後，產生電子郵件、報表、摘要、文章等
- 產生複雜的 JSON 輸出
- 文件的摘要、主要句子擷取、說明工作
- 產生查詢
- 針對特定模型最佳化的特定模組產生 (例如影像、影片、音訊、點雲資料等)
透過視覺流程提示工具
以下為透過視覺化流程建立的提示工具範例，要求 LLM 根據代理程式指派的主題產生部落格文章標題：
您是主要部落格策略師。您的任務是腦力激盪引人注目的部落格文章根據指定主題的想法。針對指定的 {{topic}}，產生 5 個唯一的部落格張貼標題。針對每個標題，包括貼文所採用的角度一句描述。以編號清單的方式顯示輸出。
- 工具名稱：使用工具的描述性名稱來協助引導代理程式。在此範例中，我們建議使用
blog_ideas。避免使用沒有幫助的名稱，例如 tool123。
- 工具描述：提供工具功能的完整描述。如果工具有限制，或有不應使用工具的案例，請在描述欄位中列出這些工具。
- OCI 區域和 GenAI 服務 LLM：選取 OCI 區域以植入該區域中可用的 LLM 清單，然後選取您的 LLM。
- LLM 參數：模型參數頁籤中會設定輸出記號上限、溫度以及 top p 之類的參數。如果您未指定任何值，則會使用 OCI Generative AI 服務的預設值。
- 查詢：用來定義工具用途的提示是在查詢欄位中定義。
您在提示中定義的參數會自動植入 AI 工具定義面板。如果適用，請為您的專員提供每個參數的描述以及參數類型和預設值。
透過 LangGraph 代碼的提示工具
如果您是透過程式碼建置代理程式，可以在視覺流程範例中設定相同的提示工具，如下所示：
prompt_config = {
"llm": {
"model_id" : "xai.grok-4",
"model_provider" : "generic",
"compartment_id" : "<your-compartment-ocid>",
"endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
}, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
"name" : "topic",
"type" : "string",
"description" : "Blog topic",
"defaultValue" : "golf"
} ]
然後建立 AIDPToolConf，如下所示：
blogger_tool = AIDPToolConf(name="blog_posts_topics",
description= "Write blog posts ideas about a particular topic. ",
tool_class = "PromptTool", conf=prompt_config params=prompt_params)
最後，您可以從 aidputils 建立與 create_langgraph_tool() 公用程式功能相容的 LangGraph 工具：
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())
您將新建立的工具新增至 ReAct 代理程式。在 LangGraph 中，程式碼的外觀如下：
tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>,
tools=tools_agent1,
prompt=<system_prompt>,
debug=True, checkpointer= checkpointer)
表格 18-1 提示工具組態特性
| 特性 | Type | 描述 |
|---|---|---|
| 磅 | 物件 | LLM 連線詳細資訊和參數 |
| model_id | 字串 | 要使用之模型的 ID (例如 "xai.grok-4") |
| 模型提供者 | 字串 | LLM 模型的提供者名稱 (例如 "generic") |
| compartment_id | 字串 | Oracle Cloud Infrastructure (OCI) 區間 OCID |
| endpoint | 字串 | 模型的端點 URL |
| prompt_template | 字串 | LLM 使用的提示樣板，其變數為 {{variable}} 格式以進行動態插入 |
測試代理程式提示工具
按一下測試頁籤並填入每個參數的值，即可獨立測試代理程式的工具。提示會提交至您選取的 LLM。
確保已正確定義並記錄提示工具，以改善服務人員的結果。
新增提示工具至專員
您可以將提示工具新增至代理程式，以允許您定義對您選擇的 LLM 發出的參數化提示。
- 瀏覽至您的專員。
- 從「工具」範本，將「提示」工具拖放至工作區。
- 在「組態」頁標中，選取要使用的 LLM，並提供 LLM 提示。按一下程式碼
以提供 JSON 程式碼的組態。 - 以 0.0 到 1.0 之間的值提供回應的溫度，其中 0.0 提供嚴格的實際回應，1.0 則提供最具創意的回應。
- 按一下套用
。 - 提供您在組態中建立之任何參數的定義。按一下程式碼 以提供 JSON 程式碼的組態。
- 按一下
申請。 - 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。
RAG 工具
RAG 工具會對向量儲存區發出自然語言查詢，並根據查詢與預存文件之間的語意相似性擷取文件。
附註：
知識庫是建立 RAG 工具的先決條件。如需詳細資訊，請參閱 Knowledge Bases 。透過視覺流程的 RAG 工具
RAG 工具會要求您作為代理程式開發人員提供下列參數的值：
- 專員面對：
- 工具名稱：工具的描述性名稱，可協助您和其他使用者識別其功能。
- 工具描述：提供工具總覽的簡短摘要。
- 工具組態：
- 知識庫：儲存在其中一個 Oracle AI Data Platform Workbench 目錄中的知識庫。
- 知識庫：儲存在其中一個 Oracle AI Data Platform Workbench 目錄中的知識庫。
專員將根據其與一般使用者的對話來設定查詢欄位的值。此查詢欄位接受自然語言查詢。
「限制」是您希望工具從向量儲存區擷取的文件區塊數目。此值是由代理程式開發人員設定，而非代理程式本身。
您也可以按一下 RAG 的測試頁籤來模擬代理程式所發出的查詢：
透過 LangGraph 代碼的 RAG 工具
若要透過程式碼在代理程式中建置 RAG 工具，必須設定與視覺化流程相同的設定值和參數。例如，設定 RAG 參數如下：
rag_params = [ { "name" : "query",
"type" : "string",
"description" : "<insert a description>",
"defaultValue" : "<empty>”} ]然後設定 RAG 組態：
rag_config = { "catalog": "<catalog>",
"schema": "<schema>",
"knowledgeBase": "<knowledge-base-name>",
"top_k": <number-of-documents-retrieved>,
"llm": {
"model_id" : "<model-name>",
"model_provider" : "<model-provider>",
"compartment_id" : "<your-compartment-OCID>",
"endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" }
}最後，您可以從 aidputils 建立與 create_langgraph_tool() 公用程式功能相容的 LangGraph 工具：
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>",
description= "<your-tool-description>",
tool_class = "RAGTool",
conf=rag_config,
params=rag_params)
rag_tool = create_langgraph_tool(rag_conf.model_dump())表格 18-2 RAG 工具組態特性
| 特性 | Type | 描述 |
|---|---|---|
| 磅 | 物件 | LLM 連線詳細資訊 |
| catalog | 字串 | 資料目錄 ID |
| schema | 字串 | 目錄內的綱要 |
| KnowledgeBase | 字串 | 要搜尋的知識庫名稱或索引鍵 |
| 最上層 _k | 整數 | 要擷取的最上層相符文件數目 |
測試代理程式 RAG 工具
將代理程式連附至 AI 運算叢集之後，您可以從測試頁籤測試 RAG 工具。如需詳細資訊，請參閱將現有的 AI 叢集附加至代理程式。
新增 RAG 工具至代理程式
您可以將檢索增強生成 (RAG) 工具新增至您的代理程式，讓代理程式在產生回應時提取相關的外部知識。
- 瀏覽至您的專員。
- 從「工具」範本，將 RAG 工具拖放至工作區。
- 在「組態」頁籤中，選取 RAG 工具從中提取資訊的知識庫，並提供定義要提取資訊的提示。按一下程式碼 以提供 JSON 程式碼的組態。
- 按一下套用 。
- 提供您在組態中建立之任何參數的定義。按一下程式碼 以提供 JSON 程式碼的組態。
- 按一下 申請。
- 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。
SQL 工具
SQL 工具可讓代理程式開發人員針對在 Oracle AI Data Platform 目錄中註冊的表格執行預先定義的 SQL 查詢。
您可以在設計階段撰寫查詢，並定義它需要的任何執行時期變數。代理程式會在呼叫工具時為這些變數提供值，而結果會傳回為代理程式可彙總或傳遞至下游節點的結構化資料列。
SQL 工具支援兩個查詢方言。Spark SQL 會對儲存在 AI 資料平台中的標準目錄表格執行，且需要 Spark 叢集。Oracle SQL 是針對外部資料庫 (例如 Oracle Autonomous AI Database) 執行。您可以選擇每個工具的方言，其餘的組態則與兩者相同。
附註：
SQL 工具適用於讀取查詢。一般工具會執行 SELECT 敘述句並傳回列。您設定的目錄、綱要和查詢是工具專用的，不會對代理程式顯示。代理程式只會顯示工具名稱、描述和 AI 工具定義 (程式實際執行變數)。附註：
SQL 查詢工具不會自動啟動停止的叢集。因此，用於 Spark SQL 查詢工具的 Spark 叢集的持續時間應為回復。如果允許叢集在閒置逾時進行微調，則叢集停止後，Spark SQL 查詢便會在生產環境中停止運作。靜態與動態查詢
靜態查詢會傳回您所指定的確切內容，代理程式不會決定程式實際執行。動態查詢包含一或多個 {{variable}} 預留位置，這些預留位置會向代理程式表示值是在執行時期設定的。為每個預留位置提供名稱、類型、選擇性預設值，以及代理程式用來選擇值的描述。
SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = 2025
ORDER BY customer_name {{year}} 預留位置，會將它變成動態查詢，代理程式可以參數化： SELECT customer_name, region, amount, category
FROM test_customers
WHERE period_year = {{year}}
ORDER BY customer_name 當您新增預留位置時，「AI 工具」定義窗格會填入每個變數，以便設定其類型、預設值和描述。
SELECT incident_id, project_id, incident_date, incident_type,
severity, description, workers_involved, days_lost,
root_cause, corrective_action, reported_by, status
FROM safety_incidents
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')為每個變數提供清楚的描述和合理的預設值。此描述會告知專員哪些值有效，且在專員未提供時會使用預設值。
附註：
預留位置名稱有區分大小寫。寫入為{{SEVERITY}} 且寫入為 {{severity}} 的預留位置會被視為兩個不同的變數，除非您一貫使用小寫。
以 JSON 身分編輯組態
{
"catalogKey": "construction_data",
"schemaKey": "admin",
"query": "SELECT project_id, project_name, client_name, ...",
"isRowLimitEnabled": null,
"maxRows": null
}
資料列限額
您可以選取要傳回的資料列上限並輸入限制值，以限制工具傳回的資料列數目。資料列限制可保護效能，並控制要將多少資料傳回代理程式。
相對於您服務人員使用的模型，設定此值。當查詢傳回大列或具有大文字值的資料欄時，較大的值可能會導致代理程式失敗。如果您看到未預期的代理程式錯誤，請從減少 maxRows 開始。
資料列限制會在查詢執行前套用到 SQL 查詢本身。大多數模型都會偵測限制並將其呈現給一般使用者。若為靜態查詢，限制會傳回前 n 個可用的資料列。
附註：
如果您不想讓一般使用者看到資料列限制，請依指示指示指示專員。查詢範例
您可以從檢視查詢範例和指南按鈕查看撰寫 SQL 工具查詢的查詢範例和指南。
此指南顯示不同的查詢樣式，並提供不同的查詢參數建議。
透過 LangGraph 程式碼的 SQL 工具
就像視覺化流程一樣，您可以透過建立查詢，開始透過 LangGraph 程式碼為代理程式建立 SQL 工具：
sql_config = { "catalogKey": "adw23ai_phx",
"schemaKey": "gold",
"query": """Select ... from ... limit {{max_number}}""" }
您可以在參數引數中，以 name、type、description 及 (選擇性) defaultValue 記錄 SQL 查詢中的每個參數。
sql_params = [ { "name" : "max_number",
"type" : "string",
"description" : "<your-description>",
"defaultValue" : "<your-default-value>" } ]最後，您可以從 aidputils 建立與 create_langgraph_tool() 公用程式功能相容的 LangGraph 工具：
from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>",
description= "<your-tool-description>",
tool_class = "SQLTool",
conf=sql_config,
params=sql_params)
sql_tool = create_langgraph_tool(sql_conf.model_dump())表格 18-3 SQL 工具組態特性
| 特性 | Type | 描述 |
|---|---|---|
| 目錄金鑰 | 字串 | 目錄或資料庫連線的 ID |
| 綱要金鑰 | 字串 | 目錄 / 資料庫內的綱要名稱 |
| Query - 查詢 | 字串 | SQL 查詢字串可能包括 {{}} 中的預留位置 |
測試代理程式 SQL 工具
「測試」頁籤會自行執行工具，而不會執行完整的代理程式。兩種方言的測試方式相同。開啟「測試」頁籤，提供每個程式實際執行參數的值 (或使用預設值)，然後按一下「送出」來執行查詢並檢視回應。
附註：
若要測試工具，您的代理程式必須連附至 AI 運算。如果 AI 運算標籤為綠色，且所選 AI 運算處於 ACTIVE 狀態，則會附加 AI 運算。SQL 命令參照
SQL 工具查詢是從標準 SQL 子句建立的讀取查詢。Oracle SQL 方言遵循 Oracle SQL 與外部資料庫。Spark SQL dialect 目標為 Delta Lake 表格的標準目錄表格；標準目錄目前以 Delta Lake 3.2.0 執行 Spark 3.5。大多數子句在兩個方言中都是以相同的方式撰寫，因為這兩個子句都遵循標準 SQL。主要差異在於每個方言限制列數的方式。下表列出 SQL 工具查詢中最常使用的子句和關鍵字，以及每個方言的表單。
| 關鍵字或子句 | 目的 | Oracle SQL | Spark SQL |
|---|---|---|---|
| SELECT | 選擇要傳回的資料欄 | SELECT col1, col2 |
|
| DISTINCT | 只傳回唯一資料列 | SELECT DISTINCT col |
SELECT DISTINCT col |
| FROM | 命名來源表格 | FROM table_name |
FROM table_name |
| WHERE | 依條件篩選資料列 | WHERE col = value |
WHERE col = value |
| 且否 | 合併或否定條件 | a AND b OR NOT c |
a AND b OR NOT c |
| IN | 符合清單中的任一值 | col IN (a, b, c) |
col IN (a, b, c) |
| BETWEEN | 比對內含範圍 | col BETWEEN x AND y |
col BETWEEN x AND y |
| LIKE | 符合文字樣式 | col LIKE 'A%' |
col LIKE 'A%' |
| IS NULL | 測試遺漏的值 | col IS NULL |
col IS NULL |
| ORDER BY | 排序結果 | ORDER BY col DESC |
ORDER BY col DESC |
| 群組方式 | 群組資料列以進行聚總 | GROUP BY col |
GROUP BY col |
| HAVING | 篩選分組的資料列 | HAVING COUNT(*) > 1 |
HAVING COUNT(*) > 1 |
| 加入 | 結合兩個表格的資料列 | a JOIN b ON a.id = b.id |
a JOIN b ON a.id = b.id |
| AS | 別名欄或表格 | col AS name |
col AS name |
| UNION ALL | 合併兩個結果集 | q1 UNION ALL q2 |
q1 UNION ALL q2 |
| CASE | 有條件地傳回值 | CASE WHEN c THEN x END |
CASE WHEN c THEN x END |
| 聚總 | 彙總資料列 | COUNT SUM AVG MIN MAX |
COUNT SUM AVG MIN MAX |
| 資料列限制 | 限制資料列數目 | FETCH FIRST n ROWS ONLY |
LIMIT n |
附註：
您通常不會自行寫入資料列限制。「要傳回的列數上限」設定會為您套用。FETCH FIRST 和 LIMIT 表單只有在您想要查詢內的明確限制時才有用。如需完整的 SQL 文法和每個方言背後的查詢引擎，請參閱下列參照：
Spark SQL 和 Delta Lake (標準目錄)
- Apache Spark SQL 語法：DML 敘述句 Spark SQL 查詢和 DML 敘述句語法。
- 差異資料湖：刪除、更新及合併表格差異表格上的 DELETE、UPDATE 以及 MERGE 作業。
- Delta Lake：表格公用程式命令公用程式作業，例如 OPTIMIZE 與 VACUUM。
- Delta Lake：在 Delta 表格使用液態叢集差異表格版面配置的液態叢集。
新增 SQL 工具至代理程式
您可以將 SQL 工具新增至代理程式，讓代理程式針對已註冊外部目錄中的結構化資料來源執行 SQL 查詢。
- 按一下並拖曳代理程式上的連線器控制碼，以連線至工具節點。
- 選擇查詢方言：
- Spark SQL 會根據標準 AI 資料平台目錄寫入查詢。
- Oracle SQL 會針對外部 AI 資料平台目錄寫入查詢。
附註：
Spark SQL 需要在「AI 資料平台工作台」工作區中執行中的 Spark 叢集。
- 從叢集下拉式清單中，選取執行中的 Spark 叢集。按一下建立叢集以啟動設定新的 Spark 叢集。如需建立新叢集的指南，請參閱建立自訂叢集。
附註：
SQL 查詢工具不會自動啟動停止的叢集。因此，用於 Spark SQL 查詢工具的 Spark 叢集的持續時間應為回復。如果允許叢集在閒置逾時進行微調，則叢集停止後，Spark SQL 查詢便會在生產環境中停止運作。
- 在瀏覽目錄下，使用搜尋欄位依名稱尋找目錄，或按一下目錄管理員來尋找目錄。
- 在查詢欄位中，輸入您的查詢。按一下檢視查詢範例和指南，開啟內含可複製或調整之現成樣式的面板。
- 在 AI 工具定義窗格中，設定查詢中所設定變數的類型、預設值及描述。
- 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。