22 AI 代理程式

本章提供有關在您的工作區中建立、測試、部署及監督代理程式的資訊。

代理程式是端對端代理程式應用程式。代理程式是透過不同類型 (觸發程式、代理程式、監護人或工具) 的節點所代表的步驟圖表來定義。代理程式可透過無程式碼視覺化流程產生器或透過第三方程式庫 (例如 LangGraph) 的程式碼來定義。

Oracle AI Data Platform Workbench 提供多種工具範本，可進行設定以存取您的資料及符合使用案例。支援的工具包括：

• 自訂工具：代理程式開發人員可使用自己的 Python 程式碼擴充 AI 資料平台。您可以將工具實行封裝為 ZIP 檔案、將它上傳至您的工作區，然後進行設定。代理程式會在程式實際執行時使用 LLM 提供的參數，將您的程式碼呼叫為工具。
• HTTP ：HTTP 要求工具可讓您的代理程式呼叫任何 HTTPS REST API。您可以設定要求，包括方法、URL、標頭、查詢參數、要求主體、認證，以及選擇性地設定回應最佳化步驟。代理程式接著會在程式實際執行時呼叫端點。視覺化產生器和程式碼產生器都提供 HTTP 要求工具。在程式碼產生器中，此工具是透過 aidpUtils Python 程式庫進行設定。
• 提示：提示工具可讓 AI 開發人員定義參數化的提示，以便針對其選擇發放給 LLM。提示工具的一般使用案例包括電子郵件草擬工作、翻譯工作、樣式轉換、Git 確認訊息，以及程式碼說明。
• 遠端 MCP 伺服器：代理程式開發人員可以使用「遠端 MCP 伺服器」工具，將其代理程式連線至遠端模型相關資訊環境協定 (MCP) 伺服器。
• RAG ：RAG 工具可讓專員在產生回應之前提取相關的外部知識。在 AI Data Platform Workbench 中，RAG 工具會查詢知識庫 (23ai Vector Search)，並擷取與語意相關的文件區塊。接著，這些區塊會傳送給代理程式以產生回應。
• SQL ：此 SQL 工具可讓代理程式針對透過外部目錄 (例如 Oracle Autonomous AI Lakehouse、Oracle Autonomous AI Transaction Processing 或 Oracle AI Database) 註冊的結構化資料來源執行 SQL 查詢。此工具適用於預先定義 SQL 查詢且可參數化的案例。目標是讓專員將值指派給參數。此工具不是根據自然語言提示產生 SQL 查詢的 NL2SQL 工具。

  附註：

  SQL 工具只會針對外部目錄中的資料執行查詢。它不支援儲存在標準目錄中的資料。

附註：

您必須先將 AI 運算連附至您的代理程式，才能測試系統工具。如果未連附運算，則會停用「測試」頁籤。

在 AI Data Platform Workbench 中建立代理程式會在您選取的工作區資料夾中產生代理程式使用者自建物件檔案 (.aflow)。無法修改此檔案。

多代理系統與主管模式

多代理程式系統是一種 AI 應用程式設計，由多個合作代理程式處理使用者要求，而不是由一個大型、全用途的代理程式處理。

每個代理程式都有自己的角色、指示、模型組態、記憶體原則及允許的工具。流程會定義要求在這些服務人員之間移動的方式，以及最終答案的產生方式。

此設計在工作流程自然分離為專家職責時非常有用。例如，一個專員可以擷取資料，另一個專員可以呼叫 API，另一個專員可以彙總結果，而主管可以決定要使用哪個專員，並將結果結合成單一回應。

附註：

作為設計原則，最好從符合需求的最小代理設計開始。分離問題可提高可靠性、安全性、維護性或可觀察性，同時增加多個專員的成本和複雜性。

多代理系統的優點

多代理系統最適合：

• 專業化：為每個專員提供一個專注的工作、提示和工具集，而不是一個擁擠的指令區塊。
• 製程與分解：讓主管解譯請求、將其分割為子作業，並為每個子作業選擇正確的專員。
• 工具和資料隔離：僅向負責使用機密或高影響力的代理程式公開這些工具。
• 治理與疑難排解：讓交接、工具擁有權、記憶體設定值及失敗點更容易檢查。

何時選擇多重代理程式或單一代理程式設計

具有更多工具的單一專員通常是正確的第一個設計。測試、執行成本更低，以及更容易推理任務何時具有一個明確的目標與一個權限模型。當工作流程受惠於明確角色、有界限的工具存取，或可協調多個專家輸出的主管時，請使用多重代理程式設計。

設計問題	使用單一代理程式時機 ...	使用多重代理程式時機 ...
工作元件 Stencils	要求有一個主要目標和一個回應磚塊。	要求必須經過分解、遞送、驗證，或跨專業領域進行合成。
工具與資料	相同的指令集和權限模型可以安全地管理所有工具	不同的代理程式需要不同的工具、資料來源或存取界限。
指示	即使在單一位置使用所有商業規則和工具指引，提示仍保持清晰。	指示可以較小、角色特定的提示進行維護。
成本和延遲	您希望從使用者訊息到答案的最短路徑。	可靠性、治理或維護性優點可證明額外的協調性。
疑難排解	在單一追蹤中對失敗進行除錯相當簡單。	您需要明確的交接、狀態隔離，以及更清晰的每個步驟所有權。

支援的樣式：協調程式 / 主管

目前的工作區體驗支援協調器 / 監督器樣式。在此模式中，「交談觸發程式」會接收使用者訊息、選擇性的「保全」會評估輸入，而「監督器代理程式」會作為其餘流程的協調器。

主管應著重於計劃、發送、委派與最終回應合成。它會決定應該處理工作的執行程式代理程式、傳送該執行程式的作用領域指示、複查結果，然後委派另一個步驟或傳回最終回應。執行人員代理程式應能縮小專家的範圍：他們會執行指派的工作、使用附加的工具，並將有用的結果傳回主管。

關於視覺流程畫面

代理程式的組合方式是將節點和工具樣板從左側選盤拖曳至工作區，然後依要求傳送的順序連線節點。

選取節點會在畫面底部開啟組態面板。

工作區元素	目的
對談觸發	使用者訊息的進入點。在螢幕擷取畫面中，此節點標示為「訊息」，且通常位於流程頂端。 線上交談觸發節點可以連線至專員、主管專員或監護人節點。每個工作區只能有一個線上交談觸發程式。
護欄	在模型工作之前或之後放置的選擇性政策與安全層。保護原則包括 PII、內容協調管制，以及提示插入偵測。 防護節點可篩選線上交談觸發程式與專員節點、主管與執行程式專員之間，或專員與工具節點之間的流量。我們建議在交談觸發程式和代理程式節點之間使用單一防護節點。
主管代理人	協調者。它會接收到使用者要求、決定應處理每個工作的執行程式代理程式或工具，以及協調最終答案。 工作區中只能有一個主管專員。
代理程式	執行程式代理程式。每個執行程式都應該有明確的專長，例如資料擷取、API 查詢、摘要或文件問題回答。 使用單一代理程式系統的代理程式 / 執行程式代理程式。
工具範本	可連附至個別執行程式或監督器代理程式的可重複使用功能。工具範本包括 SQL、RAG、提示、HTTP、遠端 MCP 伺服器和自訂工具。
開發 / 遊樂場	工作區上方的模式選取器。編輯代理程式系統時會使用開發；您可以使用 Playground 來起始測試階段作業及檢查代理程式行為。 Playground 需要將 AI 運算連附至您的代理程式。
縮放控制項	工作區縮放選取器。螢幕擷取畫面顯示 60% 與 90% 的縮放比例。

建立代理程式

您可以在具有「管理」權限的工作區中建立代理程式。

1. 在首頁上，瀏覽至您的工作區。
2. 按一下左側導覽窗格中的代理程式流程。
3. 按一下 建立代理程式，或按一下右上方的建立。
   
   

   

   
   
4. 提供代理程式的名稱和描述。
5. 在代理程式流程編寫模式中，選取視覺化產生器。
   
   

   

   
   
6. 選擇性：從 AI 運算下拉式功能表中，選取要用於代理程式的運算。
7. 按一下建立。將選用區中的節點拖曳至工作區，即可開始建立您的代理程式。

   附註：

   開始您的第一個專員建置簡單：一個「線上交談觸發程式」，一個執行程式「專員」。成功執行第一個建置後，增加複雜性，例如防護軌、其他工具，甚至是多代理程式系統設計。

新增線上交談觸發程式和服務人員至 Visual Builder 工作區

使用 Visual Builder 建立專員之後的第一個步驟，應該是新增線上交談觸發程式和主管專員。

觸發器會接收使用者訊息。主管解譯要求、計劃工作，以及委派給執行人員代理程式或工具。您可以拖曳工作區中的節點、設定節點，然後在稍後連線。

1. 瀏覽至您工作區中的代理程式。
2. 按一下交談觸發程式，並將其從選用區拖曳至工作區。節點會以「訊息」形式顯示在工作區上。
3. 按一下並拖曳監督器代理程式至工作區。
   
   

   

   
   
4. 按一下並拖曳「交談觸發程式」節點上的連線器控制代碼，以將其連線至「代理程式」節點。

「Supervisor 代理程式」標記會顯示已連線的代理程式和工具數目。在新的組建中，「監督員代理程式」會顯示「代理程式 (0) 工具 (0)」。

設定主管代理程式

您必須設定已新增至 Visual Builder 工作區的主管代理程式，並附上主管角色概述的指示。

您可以使用下列欄位設定監督代理程式。

欄位	組態
代理程式名稱	提供主管代理程式的描述性名稱。透過追蹤和記錄對系統行為進行除錯時，一個好的描述性名稱會很有幫助。
專員描述	提供專員用途、角色及一般行為的描述。可用於說明文件。
區域	選擇主管代理程式所使用之 OCI Generative AI 模型的代管區域。請參閱按區域分類的生成式 AI 模型。
Model	選擇主管使用的 OCI Generative AI 服務模型。下拉式清單列出所選區域中可用的模型。
代理程式指示	描述主管角色、路由規則、委派原則、工具使用預期以及最終回應格式。

1. 瀏覽至工作區中的代理程式。
2. 按一下工作區上的監督器代理程式節點。
3. 為您的主管代理程式提供易記的名稱和描述。
4. 輸入主管所使用 OCI Generative AI 服務模型的區域和模型。
5. 提供您「主管代理程式」的代理程式指示。

建議的主管指示

您應使用「主管專員」的「指示」欄位，讓主管負責協調，而非執行每個任務本身。

讓指示保持具體，以便預測路由決策。請參閱下列範例中的「主管」指示：

You are the supervisor for a multi-agent system.

Responsibilities:
- Understand the user's request and break it into subtasks.
- Select the most appropriate executor agent or tool for each subtask.
- Do not perform specialist work yourself when an executor agent is available.
- Ask for clarification only when required information is missing.
- Combine executor outputs into a concise final answer.
- Mention important assumptions, limits, or failed tool calls in the final answer.

Routing rules:
- Use the SQL agent for structured data questions.
- Use the HTTP agent/tool for external API lookups.
- Use the RAG agent/tool for document or knowledge-base questions.
- Use the prompt tool for reusable prompt-only transformations.

設定監督器代理程式記憶體與狀態隔離

「監督器代理程式」的「記憶體」頁籤可控制主管有多少對話和工具輸出歷史記錄，以及有多少相關資訊環境與執行程式代理程式共用。

您可以在下列欄位中設定「超級代理程式」的記憶體與隔離狀態。

欄位	組態
啟用代理程式記憶體	當使用者需要多重週轉連續性時啟用。針對獨立的單次使用任務停用。 無法停用「主管代理程式」的這個欄位。
限制通話歷史記錄	啟用即可在達到指定的限制後截斷 LLM 相關資訊環境視窗。要顯示完整瀏覽紀錄請關閉 。
截斷組態	如果啟用限制對話歷史記錄，請使用此欄位來設定截斷相關資訊環境視窗的條件。 選項包括： 保留最後 N 則訊息 權杖預算 二者
最大訊息限制與變數替代字預算	視您選擇的截斷組態而定，會顯示其中一個或兩個選項。 預設值為 20 則訊息和 5000 個記號。建議您從中等值開始並視需要進行調整。
執行器代理程式的狀態隔離	選取無狀態、專用或共用。 無狀態：每個執行程式代理程式只會看到主管所指派的工作。通話之間不會結轉任何歷史記錄。若要使用最強的隔離環境和最少的跨代理程式相關資訊環境，請選取此選項。 專用：每個執行程式代理程式只會看到自己的過去互動。它無法看到原始使用者對話的其他執行程式代理程式。如果您的執行程式需要本身作業的連續性，但不應該與其他代理程式共用相關資訊環境，請選取此選項。 共用：執行者代理程式可以查看所有代理程式和使用者的完整對話歷史記錄。所有代理程式都從一個共用相關資訊環境運作。如果您需要廣泛的內容共用，並且已複查隱私權和立即插入風險，請選取此選項。

1. 瀏覽至工作區中的代理程式。
2. 按一下工作區上的監督器代理程式節點。
3. 按一下記憶體頁籤。
4. 選擇是否要啟用限制對話歷史記錄。選取截斷組態並設定限制 (如果啟用)。
5. 選擇執行程式代理程式的狀態隔離選項。

模型參數頁標

「模型參數」頁籤可讓您設定可供所選模型使用的模型特定參數。

您可以分別為 supervisor 和執行器代理程式設定模型參數。您可使用的參數包括溫度、最高 K、最高 P 和頻率懲罰。

附註：

只有模型子集會公開可設定的參數。此外，模型族群的參數也會不同。

新增界限至代理程式

您可以新增一或多個界限節點至工作區，為您的代理程式新增額外的保護層。

根據預設，除了所選模型提供者為其模型提供立即可用的服務之外，您的專員系統不會套用界線。您可以在「交談觸發程式」與「主管專員」之間放置界限，以便在要求到達主管專員之前，以及在主管專員將回應傳回給來電者之前，先套用原則。

監護人	選項	使用時機
個人可識別資訊 (PII)	輸入和輸出頁籤 人員、地址、電話號碼、電子郵件的核取方塊	當流程必須在模型處理前後封鎖或隱藏敏感的個人資料時使用。
預防內容審查	具有「區塊」、「通知」及「允許」選項的「輸入」與「輸出」列。	用來定義流程如何處理仇恨、性、暴力、有毒、貶損或騷擾內容。
提示注射檢測	具有「區塊」與「允許」選項的輸入列。	用來減少惡意指示覆寫系統或代理程式指示的機會。

如需防護軌設定的詳細資訊，請參閱防護軌。

1. 瀏覽至工作區中的代理程式。
2. 將選用區中的監護人節點拖曳至工作區。將它放置在您的「交談觸發程式」節點與「監督代理程式」節點之間。
3. 將游標停駐在連線上並按一下紅色 X，以刪除「線上交談觸發程式」與「主管專員」之間的連線。
   
   

   

   
   
4. 按一下「交談觸發程式」上的連線器控制代碼並將其拖曳至 Guardrail 節點。接著，從 Guardrail 節點按一下連線器處理並拖曳至「監督器代理程式」。
5. 按一下 Guardrail 節點，即可開啟「組態」頁面。
6. 設定監護人以選取要進行輸入和輸出檢查的動作。

將執行程式代理程式和工具新增至代理程式

您可以將執行程式代理程式新增至工具，以執行 supervisor 代理程式的特殊工作。

在下面的範例中，「主管代理人」委派 AGENT_1 與 AGENT_2。AGENT_1 已連線至 SQL_1 和 HTTP_1 工具。

1. 瀏覽至工作區中的代理程式。
2. 將「代理程式」節點從選用區拖曳至工作區。代理程式節點應該放置在「監督代理程式」之下。
3. 將「工具」從選用區拖曳至工作區。
4. 按一下並拖曳「監督器代理程式」上的連線器控制代碼，即可連線到「代理程式」節點。
5. 按一下並拖曳「代理程式」上的連線器控制代碼，即可連線至「工具」節點。

執行器代理程式組態

您可以透過修改其「組態」、「記憶體」和「模型」頁籤上的設定值來設定代理程式節點，以協助您定義每個代理程式的用途。

代理程式應具有特定功能和目標，以便能夠可靠地遞送工作。

表格 22-1 代理程式組態頁籤

欄位	組態
代理程式名稱	最佳作法是根據每個執行程式代理程式的專業性來命名，例如 SQL_AGENT、DOCUMENT_AGENT、API_AGENT 或 SUMMARY_AGENT。 supervisor 代理程式可看到每個執行器代理程式的名稱，因此使用描述性名稱。
專員描述	提供每個執行程式代理程式的詳細描述。主管代理程式可以看到每個執行程式代理程式的描述。
區域	選擇代管代理程式所使用之 OCI Generative AI 模型的區域。請參閱按區域分類的生成式 AI 模型。
Model	選擇代理程式所使用的 OCI Generative AI 服務模型。下拉式功能表會列出所選區域中可用的模型。 選取適合執行程式工作的模型。執行器代理程式不需要使用與監督器代理程式相同的模型。
代理程式指示	描述執行程式應該執行的動作、它可能使用的工具以及它應該傳回的輸出結構。

執行器代理程式記憶體頁籤

如果執行程式代理程式連線至監督器代理程式，執行程式的記憶體會在監督器節點中設定，並套用至所有執行程式代理程式。

欄位	組態
啟用代理程式記憶體	當使用者需要多重週轉連續性時啟用。針對獨立的單次使用任務停用。
限制通話歷史記錄	啟用即可在達到指定的限制後截斷 LLM 相關資訊環境視窗。要顯示完整瀏覽紀錄請關閉 。
截斷組態	如果啟用限制對話歷史記錄，請使用此欄位來設定截斷相關資訊環境視窗的條件。 選項包括： 保留最後 N 則訊息 權杖預算 二者
最大訊息限制與變數替代字預算	視您選擇的截斷組態而定，會顯示其中一個或兩個選項。 預設值為 20 則訊息和 5000 個記號。建議您從中等值開始並視需要進行調整。
執行器代理程式的狀態隔離	選取無狀態、專用或共用。 無狀態：每個執行程式代理程式只會看到主管所指派的工作。通話之間不會結轉任何歷史記錄。若要使用最強的隔離環境和最少的跨代理程式相關資訊環境，請選取此選項。 專用：每個執行程式代理程式只會看到自己的過去互動。它無法看到原始使用者對話的其他執行程式代理程式。如果您的執行程式需要本身作業的連續性，但不應該與其他代理程式共用相關資訊環境，請選取此選項。 共用：執行者代理程式可以查看所有代理程式和使用者的完整對話歷史記錄。所有代理程式都從一個共用相關資訊環境運作。如果您需要廣泛的內容共用，並且已複查隱私權和立即插入風險，請選取此選項。

執行程式代理程式模型參數頁籤

「模型參數」頁籤可讓您設定可供所選模型使用的模型特定參數。

附註：

只有模型子集會公開可設定的參數。參數也會因模型族群而異。

參數的範例包括溫度、頂端 K、頂端 P 和頻率懲罰。您可以分別為 supervisor 和執行器代理程式設定模型參數。

建議的執行程式指示

You are the SQL executor agent.

Responsibilities:
- Translate the supervisor's task into safe SQL tool usage.
- Use only the SQL tools attached to this agent.
- Return a concise answer plus any important query assumptions.
- Do not invent data. If the tool cannot answer, say what is missing.
- Return structured output with: answer, evidence, assumptions, and follow_up_needed.

透過 Visual Builder 的代理程式檢查清單

使用這份清單作為指南，確保您已為使用 Visual Builder 建立的代理程式包含和設定每個必要的元件。

建立核對清單

• 專員只有一個預期的進入點：對談觸發程式 / 訊息。
• 保全會以預期的位置連接，並在需要時啟用。建議您在觸發程式訊息與代理程式之間插入界限。
• 「監督員代理程式」具有選取的區域、選取的模型及協調流程指示。執行程式代理程式相同。
• 在「監督器」代理程式的「記憶體」頁籤中設定多重代理程式系統的記憶體。選取符合隱私權和持續性需求的執行程式狀態隔離。
• 每個執行程式代理程式都有明確的專業和狹窄的指示。
• 每個工具僅會附加至應使用工具的代理程式。
• 未中斷任何節點連線。
• AI 運算會連附至代理程式系統，以測試個別工具及執行 Playground 體驗。

表 22-2 常見問題

問題	可能的原因	建議的動作
主管未呼叫執行程式	主管指示太模糊，或執行程式未連線。	新增明確的路由規則，並確認執行程式節點已連線至主管。
執行器傳回廣泛或非主題的答案	執行器指示太一般。	將執行者角色變窄並定義所需的輸出結構。
未使用工具	工具已中斷連線或附加至錯誤的代理程式。	檢查工具連線和代理程式工具計數標記。
Guardrail 不會觸發	已設定 Guardrail 區段，但尚未啟用。	開啟 Guadrails 節點，並確認區段切換是否開啟。
跨服務人員的相關資訊環境流失	狀態隔離設定為「共用」，或記憶體比預期更大。	使用無狀態或專用隔離進行更嚴格的區隔。
後續問題會失去相關資訊環境	記憶體被停用或截斷太積極。	開啟記憶體並調整最大訊息限制 。

專線服務員流程代碼

您可以在 Oracle AI Data Platform Workbench 中將自己的 LangGraph 程式碼基礎帶入 AI 代理程式，也可以透過代理程式編碼體驗直接在平台上建立新的 LangGraph 代理程式。

您可以使用 AI Data Platform Workbench 公用程式 Python 程式庫 aidputils 來設定基礎模型，並將系統工具匯入至您的代理程式。如需輔助功能 API 參照，請參閱 Oracle AI Data Platform Workbench 的輔助功能 API 。

您可以透過程式碼上傳現有程式碼檔案，或透過內嵌編輯器直接在代理程式中建立程式碼檔案，藉此建立代理程式。

代理程式中的內嵌程式碼編輯器支援下列程式碼檔案類型：

• Python (.py)
• JSON
• 交易
• CSV
• PSV
• SH 語言
• 資料夾

您可以按一下檔案選取器下拉式清單，查看並瀏覽可用的程式碼檔案。

項目與相依性檔案

輸入檔是具有類別的程式碼檔案，其類別具有定義為程式碼的代理程式預期設定和呼叫方法。Oracle AI Data Platform Workbench 需要您透過程式碼為專員設定輸入檔案。

相依性檔案是包含您代理程式定義為程式碼所需之第三方程式庫的檔案。相依性檔案通常是包含必要第三方程式庫清單的 requirements.txt 檔案。

附註：

當您按一下「播放」按鈕或在透過「測試」頁籤測試代理程式時，會在編輯器中測試您的程式碼時，安裝協力廠商程式庫。建議您先測試程式碼，以安裝第三方程式庫。安裝程式庫時發生錯誤會顯示在輸出儲存格中。

代理程式類別

AgentBasic 是使用狀態性 LangGraph 工作流程來設定和呼叫簡單對話代理程式的範本類別。它示範以兩種主要方法開發最基本的代理程式所需的結構：

• setup()：起始代理程式工作流程並定義圖表。
• invoke(user_query, **kwargs)：在使用者訊息上執行代理程式並傳回回應。

它可以在整合至較大的系統之前，使用 main() 函數直接執行和測試。

定義

class AgentBasic:
    def __init__(self) -> None:
        self.graph = None
    def setup(self) -> None:
        self.graph = StateGraph(MessagesState)
        self.graph.add_node(mock_llm)
        self.graph.add_edge(START, "mock_llm")
        self.graph.add_edge("mock_llm", END)
        self.graph = self.graph.compile()
        system_prompt = "Be a helpful assistant."
    async def invoke(self, user_query: str, **kwargs):
        user_message = HumanMessage(content=user_query)
        messages = {"messages": [dict(user_message)]}
        try:
            return self.graph.invoke(messages)
        except Exception as e:
            import traceback
            logger.error(f"Exception while calling invoke {e}", exc_info=True)
            print("Stack trace:\n", traceback.format_exc()) 

測試呼叫

此測試呼叫適用於初始功能測試。

附註：

包含獨立測試的主要進入點。

import asyncio

async def main():
test_agent = AgentBasic()
test_agent.setup()
result = await test_agent.invoke("Hi there")
print("Agent response:", result)
if __name__ == "__main__":
   asyncio.run(main())

運作方式：

• 指令碼會建立專員、加以設定，並傳送範例使用者訊息。
• 代理程式在此範例中回應 ({"messages"：[{"role"："ai"，"content"："hello world"}]}。

使用指南

使用設定和呼叫方法建立 Agent 類別。

setup()	起始代理程式工作流程	代理加盟
invoke()	使用使用者訊息執行代理程式	等待 agent.invoke (「您的問題」)

• 非同步：invoke() 為非同步方法；將它與 await 搭配使用，或在非同步迴圈中執行。
• 測試：內含的 main() 防護 (if __name__ == "__main__":) 可讓您在部署之前輕鬆測試代理程式。

依上傳透過代碼建立專線服務員

您可以上傳 LangGraph 程式碼基礎，使用現有程式碼建立端對端代理程式應用程式。

Oracle AI Data Platform Workbench 支援 LangGraph 版本 1.0.1。

附註：

您可以上傳個別檔案和資料夾，最多 500 個檔案，每個檔案的大小上限為 500MB。上傳大小限制為 5GB。

1. 瀏覽至您工作區中的代理程式。按一下代理程式名稱。
2. 按一下上傳。
   
   

   

   
   
3. 將檔案拖放至窗格中，或按一下以瀏覽以選取檔案。
4. 按一下上傳。

透過程式碼建立新程式碼來建立代理程式

您可以透過程式碼編輯器，直接在代理程式中建立程式碼，使用現有的程式碼建立端對端代理程式應用程式。

程式碼編輯器支援下列檔案類型：

• Python (.py)
• JSON
• 交易
• CSV
• PSV
• SH 語言
• 資料夾

1. 瀏覽至您工作區中的代理程式。按一下代理程式名稱。
2. 按一下新增檔案。
   
   

   

   
   
3. 輸入您的代碼檔案的名稱。
4. 從下拉式清單選取檔案類型。
5. 按一下建立。

透過代碼設定專員的輸入檔案

透過程式碼的 AI 代理程式需要一個項目檔案，該檔案具有預期的代理程式類別、設定及呼叫方法。

1. 瀏覽至您工作區中的代理程式。按一下代理程式名稱。
2. 在「程式碼編輯器 (Code Editor)」頁籤中，於左側導覽窗格中找到項目檔案。如果檔案不存在，您可以按一下上傳來上傳檔案，或按一下新增檔案來建立檔案。
3. 在項目檔案上按一下滑鼠右鍵，然後按一下設定項目檔案 (Set entry file) 。您也可以選取檔案，然後按一下程式碼編輯器右上方的設定項目檔案按鈕。
   
   

   

   
   

透過代碼設定代理程式的相依性檔案

您必須透過包含您程式碼相依之任何第三方程式庫的程式碼，設定代理程式流程的相依性檔案。

1. 瀏覽至您工作區中的代理程式。按一下代理程式名稱。
2. 在「程式碼編輯器」頁籤的左側導覽窗格中，尋找相依性檔案 (通常是 requirements.txt)。如果檔案不存在，您可以按一下上傳來上傳檔案，或按一下新增檔案來建立檔案。
3. 在相依性檔案上按一下滑鼠右鍵，然後按一下設定相依性。您也可以選取檔案，然後按一下程式碼編輯器右上方的設定相依性檔案按鈕。
   
   

   

   
   

測試代理代碼

您可以從「測試」頁籤測試代理程式使用的程式碼，以驗證和除錯程式碼。

您的代理程式必須附加 AI 運算才能進行測試。

1. 瀏覽至您工作區中的代理程式。按一下代理程式名稱。
2. 按一下播放區頁籤。
   
   

   

   
   
3. 按一下播放以測試選取的程式碼檔案。
   
   

   

   
   

在程式碼編輯器視窗下半部的輸出單元，會顯示程式碼中列印或記錄敘述句的輸出結果。錯誤也會顯示在輸出儲存格中。

編寫程式碼體驗的專員技能

專員技能可讓專員尋找並使用特定任務的指示、參考檔案、範本、資產及選擇性的可執行指令碼，而不需要將網域知識編碼到專員的指示中。

技能會儲存為服務人員代碼庫中的資料夾。每個技能都有必要的 SKILL.md 檔案，描述技能的作用以及服務人員應如何使用它。技能也可以包含支援的檔案，例如綱要、範例、提示、範本、資產或命令檔。

如需詳細資訊，請參閱專員技能概要。

專員技能支援漸進式公開模型：

1. 專員發現有技能存在。
2. 專員只有在相關時才會啟用技能。
3. 只有在需要時，專員才會從技能資料夾載入其他檔案。
4. 如果技能允許，專員可以執行明確宣告的技能進入點。

何時使用服務人員技能

若要封裝可重複使用的代理程式功能，例如：

• 網域特定指示
• 編碼或資料分析工作流程
• SQL 產生指引
• 業務流程手冊
• 檔案範本
• 綱要參考
• 用於安全計算、轉換或查尋的可重複使用指令碼

技能在專員應該可以存取專業且可重複使用的知識時很有用，但您不想將所有知識直接放置在專員提示中。

技能在程式實際執行時的運作方式

在執行時期，主機應用程式會決定可用的技能目錄，例如專案層級和使用者層級的技能資料夾。此平台會從 SKILL.md 載入每個技能的中繼資料，並建立以技能名稱為關鍵碼的型錄。

然後，專員可以使用技能相關工具：

工具	目的
activate_skill(name)	從 SKILL.md 載入技能指示。
list_skill_files(name, path)	列出技能資料夾內可用的檔案。
load_skill_file(name, path)	從技能資料夾載入支援檔案。
run_skill_entrypoint(name, entrypoint, args_json, timeout_seconds)	執行明確宣告的 Python 進入點 (如果技能允許的話)。

有些環境也可能會將可用技能的摘要直接內嵌至系統提示中。在該設定中，代理程式可以從提示中尋找可用的技能，然後在需要完整指示時使用 activate_skill。

技能資料夾結構

技能使用「專員技能」樣式的資料夾版面配置：

<skills_dir>/
	some-skill/
		SKILL.md
		references/
		...
		scripts/
		...
		assets/
		...

只需要 SKILL.md。其他資料夾則為選擇性。

資料夾或檔案	這是必要欄位。	目的
SKILL.md	是	主要技能中繼資料與指示。
references/	編號	支援文件、綱要、範例或樣板。
scripts/	編號	只有在明確宣告為進入點時才能執行的 Python 命令檔。
assets/	編號	技能所使用的靜態資產。

寫入 SKILL.md

每個技能都必須包含 SKILL.md 頂端的 YAML 前置標記，後面接著 Markdown 指示。

基本範例

---
name: sql-helper
description: Helps the agent write safe SQL queries using project schemas.
license: internal
compatibility: "agent-platform"
metadata:
  owner: data-platform
  domain: analytics
allowed-tools: "analyzeQuery inspectSchema"
---

# SQL Helper

Use this skill when the user asks for SQL generation, query review, or schema-aware analysis.

Before writing SQL:
1. Inspect the relevant schema files in `references/`.
2. Prefer explicit column names.
3. Avoid destructive statements unless the user explicitly asks for them and the environment allows them.

表 22-3 支援的前端子欄位

欄位	這是必要欄位。	描述
名稱	是	型錄與工具所使用的唯一技能名稱。
描述	是	用於尋找與路由的簡短描述。
license	編號	技能的授權或使用政策。
相容性	編號	支援之程式實際執行或平台的相容性注意事項。
中繼資料	編號	字串至字串描述資料對應。
容許工具	編號	此技能允許的工具清單，以空格分隔。
進入點	編號	技能宣告的可執行進入點清單。

新增支援檔案

支援檔案可讓技能將詳細內容保留在主要指示之外。這會讓 SKILL.md 保持焦點，同時仍然讓代理程式存取更豐富的內容。舉例而言：

skills/
	sql-helper/
		SKILL.md
		references/
			warehouse_schema.md
			query_style_guide.md
			examples.md

代理程式可以使用下列項目來檢查這些檔案：

list_skill_files("sql-helper", "references")
load_skill_file("sql-helper", "references/warehouse_schema.md")

對下列內容使用支援檔案：

• 資料庫綱要
• API 例子
• 提詞樣板
• 樣式指南
• 網域詞彙
• 逐步的手冊
• 測試案例或範例

建立可執行技能

技能可以選擇性地透過 run_skill_entrypoint 顯示可重複使用的執行檔行為。這適用於受控制的作業，例如計算、轉換、驗證或擷取結構化資料。

執行技能必須符合兩個要求：

1. 技能必須在允許的工具中包含 run_skill_entrypoint。
2. 必須在 SKILL.md 的進入點區段中明確宣告命令檔。

執行技能範例

skills/
	statistics-helper/
		SKILL.md
		scripts/
			summarize_numbers.py

繁體中文

---
name: statistics-helper
description: Computes basic summary statistics for numeric data.
allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
entrypoints:
  - name: summarize_numbers
    script: scripts/summarize_numbers.py
    func: run
    description: Returns count, min, max, mean, and median for a list of numbers.
---

# Statistics Helper

Use this skill when the user asks for basic descriptive statistics.
scripts/summarize_numbers.py:
from statistics import mean, median

def run(*, values: list[float]) -> dict:
    if not values:
        raise ValueError("values must not be empty")

    return {
        "count": len(values),
        "min": min(values),
        "max": max(values),
        "mean": mean(values),
        "median": median(values),
    }
Example invocation:
run_skill_entrypoint(
  name="statistics-helper",
  entrypoint="summarize_numbers",
  args_json="{\"values\": [10, 20, 30, 40]}",
  timeout_seconds=10
)
The runner returns structured output that includes exit_code, stdout, stderr, and a best-effort parsed result when the script prints or returns JSON.

可執行項目點的規則

執行檔的進入點會被刻意限制。此平台只執行以下各項的 Python 檔案：

• 位於技巧的文稿 / 目錄下
• 在技能的進入點前端中宣告
• 技能的 allowed-tools 設定允許

此平台未提供一般用途的任意命令檔執行。未在 SKILL.md 中宣告的指令碼無法執行。

程序檔執行程式使用逾時，預設為 10 秒，以隔離模式運作方式執行 Python，並套用路徑限制。不過，以子處理作業為基礎的執行並不是完整的作業系統封閉測試環境。對於生產環境使用，應考量較高的隔離環境，例如容器、受限制的檔案系統或網路控制。

使用 allowed-tools 的工具權限

allowed-tools 會作為技能層級的權限關卡。若是僅說明文件的技能，您可能只允許使用檔案讀取工具：

allowed-tools: "load_skill_file list_skill_files"

對於可執行宣告指令碼的技能，請包含 run_skill_entrypoint：

allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint" 

除非技能真的需要執行檔行為，否則請勿新增 run_skill_entrypoint。

如何讓專員探索和使用技能

若要以技能補充專員，您必須使用 aidpUtils 程式庫中的下列物件，建立技能目錄、技能中介軟體並將技能轉換為工具：

工具	目的
discover_skill_catalog	決定預設技能搜尋位置 (專案 + 使用者) 從找到的目錄建立技能目錄
SkillMiddleware	將可用的技能摘要與遞送規則附加至系統提示。 為工作區導向的中介軟體建構提供工廠協助。
make_skill_tools	此方法會傳回 activate_skill、list_skill_files、load_skill_file 和 run_skill_entrypoint 等技能尋找工具。服務人員可以使用這些工具來啟用和執行不同的技能。

以下為您的輸入檔案所包含的範例：

from aidputils.agents.skills.discovery import discover_skill_catalog
from aidputils.agents.skills.middleware import SkillMiddleware
from aidputils.agents.skills.tools.factories import make_skill_tools
...
class SchoolGradeAgentWithEmbededSkills:
	...
	def init(self) -> None: 
		...
		self.catalog = discover_skill_catalog(skill_folder_whitelist=None)
		self.skill_middleware = SkillMiddleware(self.catalog)
		self.tools = make_skill_tools(self.catalog)

您可以在程式碼中新增此日誌陳述式，以對技能目錄進行除錯。這會列印技能目錄中發現的所有技能：

for info in self.catalog.list():
	logger.info("skill_id=%s name=%s desc=%s root=%s skill_file=%s", info.skill_id, info.name, info.description, info.root_dir, info.skill_file)

技能優先順序

此平台可以從多個位置載入技能，例如專案層級和使用者層級目錄。型錄會將這些地點彙總為單一名稱關鍵技能清單。

當多個商店包含相同名稱的技能時，優先順序會決定使用哪一個。稍後會儲存置換先前版本，讓主機應用程式控制使用者層級技能、專案層級技能或工作區層級技能是否優先。

技能撰寫最佳實務

保持 SKILL.md 焦點

使用 SKILL.md 以取得專員在啟用後立即所需的核心指示。將長的綱要、範例和參照資料放在參照 / 中。

撰寫純文字描述

描述欄位用於尋找。明確地讓專員知道何時啟動技能。

良好：

description: Helps generate BigQuery SQL using the finance warehouse schema.

較少有用：

description: Helps with data.

使用明確的進入點名稱

進入點名稱應該清楚描述作業：

entrypoints: 
   - name: validate_query 
   - name: summarize_numbers 
   - name: transform_csv

避免使用模糊名稱，例如：

entrypoints: 
   - name: run 
   - name: do_it 

傳回結構化結果

執行檔應該盡可能傳回 JSON 序列化結果。這可讓代理程式更容易檢查和使用輸出。

避免不必要的執行

偏好使用說明與參考檔案 (若可行)。僅針對真正需要程式碼的作業使用可執行項目進入點。

新增技能

您可以在技能目錄內建立新資料夾，並新增必要的檔案和資料夾，以新增「專員」技能。

1. 在技能目錄下建立資料夾：.agents/skills/<skill-name>/。
2. 新增具有所需前端內容的 SKILL.md 檔案。

   ---
   name: <skill-name>
   description: <what this skill helps the agent do>
   ---
   

3. 在前面的 Markdown 中撰寫技能指示。
4. 在下列位置新增選擇性支援檔案：

   references/
   assets/
   scripts/
   

5. 如果技能可執行，請將 run_skill_entrypoint 加到 allowed-tools，在 SKILL.md 中宣告 entrypoints，然後將 Python 實作置於 scripts/ 下。

新增現有技能的可執行能力

您可以新增執行檔作業至現有技能，以擴充 SKILL.md 的功能。

1. 1. 在技能的 scripts/ 目錄下新增 Python 檔案。

   .agents/skills/<skill-name>/scripts/my_operation.py 

2. 2. 實行 run(...) 函數。

   def run(*, input_text: str) -> dict:
       return {
           "length": len(input_text),
           "uppercase": input_text.upper(),
       }
   

3. 3. 新增相符的進入點至 SKILL.md。

   allowed-tools: "load_skill_file list_skill_files run_skill_entrypoint"
   entrypoints:
     - name: my_operation
       script: scripts/my_operation.py
       func: run
       description: Processes input text and returns structured output.
   

4. 4. 使用 JSON 物件作為引數測試進入點。

   {
     "input_text": "hello"
   }
   

專員技能疑難排解

如果您在導入「專員技能」時發生問題，請查看此清單以協助解決您的問題。

專員看不到我的技能

請檢查：

• 技能資料夾位於已設定的技能目錄下。
• 資料夾包含 SKILL.md。
• SKILL.md 具有有效的 YAML 前置標記。
• 前置標記包括名稱和描述。

專員啟動錯誤的技能

檢查跨技能目錄是否有重複的技能名稱。如果兩個技能的名稱相同，目錄優先順序會決定使用的技能。

無法載入支援檔案

請檢查：

• 檔案位於技能資料夾內。
• 此路徑不包含導線，例如 ../。
• 檔案未隱藏。
• 未排除檔案，例如 __pycache__ 或 .pyc。

將不會執行進入點

請檢查：

• run_skill_entrypoint 包含在 allowed-tools 中。
• 進入點會在 SKILL.md 中宣告。
• 文稿路徑位於 scripts/ 之下 。
• 命令檔是 .py 檔案。
• 命令檔中存在函數名稱。
• 引數是有效的 JSON 物件。

進入點逾時

只有在作業需要較長的時間時，才增加 timeout_seconds。對於長時間執行或需要大量資源的作業，請考慮將作業搬移至專用服務或更獨立的執行環境。

範例：完成專員技能

此範例示範實作之後的完整專員技能外觀。

資料夾架構

skills/
	customer-support-reply/
		SKILL.md
		references/
			tone_guide.md
			refund_policy.md
			escalation_rules.md

繁體中文

---
name: customer-support-reply
description: Helps draft customer support replies using the company tone guide and policy references.
allowed-tools: "load_skill_file list_skill_files"
metadata:
  owner: support-operations
  domain: customer-support
---

# Customer Support Reply

Use this skill when the user asks for help drafting, reviewing, or improving a customer support response.

Workflow:

1. Identify the customer’s issue.
2. Load the relevant policy file from `references/` if needed.
3. Draft a clear, empathetic response.
4. Avoid making commitments that are not supported by policy.
5. Recommend escalation when the request matches the escalation rules.
This skill does not run code. It gives the agent structured instructions and optional policy files that can be loaded only when relevant.

代理程式測試

您可以測試代理程式以預覽並除錯其輸出。您也可以建立及管理測試階段作業，探索代理程式的不同測試案例。

測試代理程式的第一步是將您的代理程式連附至 AI 運算。附加代理程式的動作會將您代理程式的複本推送至 AI 運算。只要您的代理程式連附至 AI 運算，每次按一下「測試」按鈕時，您對代理程式所做的任何變更都會傳輸至連附的運算。

按一下「測試」按鈕之後，就會移至測試操場。

測試操控區包含下列元件：

• 交談視窗，您可以在其中起始階段作業並開始與專員交談，或繼續現有階段作業
• 以圖形表示的代理程式
• 顯示階段作業期間產生之追蹤和跨度的樹狀結構面板
• 追蹤與跨度總管面板，顯示追蹤與跨度屬性、輸入 / 輸出。「詳細資訊」頁籤包括 ID、開始和結束時間、執行時間，而「事件」頁籤則會在執行期間標示出任何錯誤。

Playground 可讓您獨立互動及測試每個專員 (如果您想要這麼做)。依照預設，會選取主管代理程式，但您可以選擇與每個執行程式代理程式個別交談並測試。這可讓您模擬對執行程式代理程式發出要求的監督器代理程式行為。若要這麼做，請在線上交談視窗的下拉式功能表中選取要測試的專員。

當您建立第一則訊息時，中央面板中便會顯示追蹤與跨度。每個任務對應至不同的使用者訊息。您可以按一下左側注意事項來展開追蹤並檢查跨度。

在遊戲場測試您的代理程式

您可以從「測試」遊樂場測試 Visual Builder 和以 LangGraph 為基礎的代理程式，以驗證和除錯您的代理程式。

您的代理程式必須附加 AI 運算才能進行測試。您可以依照建立代理程式的 AI 叢集來新增 AI 運算叢集，或依照將現有的 AI 叢集連附至代理程式來連附現有的 AI 運算叢集。

1. 瀏覽至您工作區中的代理程式。按一下代理程式名稱。
2. 在畫面頂端，按一下播放區。將代理程式推送至連附的運算可能需要數秒鐘的時間。
   
   

   

   
   

您的專員會顯示在測試操場中。

建立代理程式測試階段作業

您可以建立測試階段作業，以起始與專員的新對話。

代理程式在測試操場目標中建立的所有階段作業都會代管在連附的運算上。階段作業建立之後，便可以在稍後繼續。

1. 瀏覽至您工作區中的代理程式。按一下代理程式名稱。
2. 在畫面頂端，按一下播放區
3. 在階段作業選取器中，按一下 建立階段作業。
   
   

   

   
   
4. 在線上交談方塊中輸入查詢，以開始與您的專員對話。
   
   

   

   
   

繼續代理程式測試階段作業

您可以繼續先前建立的代理程式測試階段作業。

附註：

您只能恢復您所建立的梯次。

1. 瀏覽至您工作區中的代理程式。按一下代理程式名稱。
2. 在畫面頂端，按一下播放區
3. 從階段作業下拉式清單中，選取上一個階段作業。
   
   

   

   
   
4. 在交談方塊中輸入查詢，以恢復與專員的對話。

刪除代理程式測試階段作業

您可以刪除附加 AI 運算上代管之代理程式的測試階段作業，以及已在已部署代理程式上建立的階段作業。

1. 瀏覽至您工作區中的代理程式。
2. 按一下「階段作業」頁籤。
   
   

   

   
   
3. 在您要刪除的階段作業旁邊，按一下 動作，然後按一下刪除。
   
   

   

   
   
4. 按一下「刪除」。

關於代理程式工具

Oracle AI Data Platform Workbench 支援可設定為存取資料及符合使用案例的工具範本。

專員支援由單一專員組成的組態，可連接一或多個工具。Oracle AI Data Platform Workbench 提供三種工具範本，可透過視覺流程或程式碼設定使用：

• 自訂程式碼：自訂程式碼工具可讓 AI 開發人員使用 Python 實作其工具。開發人員將工具封裝成 ZIP 格式、上傳至工作區，然後將其設定為代理程式中的節點。自訂程式碼工具適用於內建工具無法提供所需整合的情況。
• HTTP 要求： HTTP 要求工具可讓開發人員運用 AI Data Platform Workbench 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 AI Database) 註冊的結構化資料來源執行 SQL 查詢。此工具適用於預先定義 SQL 查詢且可參數化的案例。目標是讓專員將值指派給參數。此工具不是根據自然語言提示產生 SQL 查詢的 NL2SQL 工具。

  附註：

  SQL 工具只會針對外部目錄中的資料執行查詢。它不支援儲存在標準目錄中的資料。

透過視覺流程的代理程式流程工具

透過視覺化流程將工具新增至服務人員時，您可以在服務人員中的工具範本底下找到工具。將工具拖放至視覺化流程工作區，即可將工具新增至您的代理程式。在工作區上拖曳工具節點後，節點會自動與代理程式連線。

您可以在「參數」頁籤中設定每個工具，然後按一下「測試」頁籤，即可獨立測試代理程式。

附註：

您必須先將 AI 運算連附至您的代理程式，才能測試系統工具。如果未連附運算，則會停用「測試」頁籤。

透過 LangGraph 代碼的代理程式流程工具

您可以透過 AIDPToolConf() 類別的執行處理，將 RAG、SQL 和提示工具新增至 LangGraph 編碼的代理程式。

from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool =  AIDPToolConf(name, description, tool_class , conf, params)

參數會反映工具的視覺流程體驗。對於每個工具，您必須提供：

• 名稱：協助使用者和 LLM 瞭解工具用途的描述性名稱。
• 描述：提供足夠資訊給使用者與 LLM 的完整摘要，以瞭解工具的功能。
• tool_class：支援的工具類型為 PromptTool、SQLTool 或 RAGTool。
• 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 運算，才能安裝相依性並執行此工具。

1. 瀏覽至您的專員。
2. 從「工具」範本，將「自訂」工具拖放至工作區。
3. 在套件頁籤中，按一下以選取具有自訂程式碼的 ZIP 檔案，或將它拖放到畫面上。等待上傳完成。
   
   

   

   
   
4. 在「套裝程式」頁籤的工具區段中，複查找到的工具清單。在您的 tool_implementation.py 中找到的每個工具類別都會列出其類別名稱、描述和版本。
   
   

   

   
   
5. 選取要啟用的工具。停用的工具不會對代理程式顯示。
6. 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。

遠端 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 的外觀如下：

如何向服務人員公開 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 權杖：

從 Visual Builder 將代理程式連線至遠端 MCP 伺服器

您可以將自訂 MCP 伺服器工具節點拖曳至工作區，將遠端 MCP 伺服器的存取權新增至您的代理程式。

如果沒有看到可用的自訂 MCP 伺服器工具，您可能需要重新啟動現有的 AI 運算或建立新的運算。

附註：

代管代理程式的 AI 運算會繼承其工作區的網路設定值。如果啟用代管 AI 運算之工作區的專用網路存取，您的代理程式就只能連線所選專用 VCN 和子網路中代管的 MCP 伺服器。您的代理程式可能無法連線公用網際網路上可用的遠端 HTTP 伺服器。

1. 瀏覽至您的專員。
2. 在流程頁籤的工具樣板下，按一下自訂 MCP 伺服器並將其拖曳至工作區。
3. 提供 MCP 伺服器的伺服器 URL。
4. 提供 MCP 伺服器的顯示名稱。這是視覺化產生器工作區中顯示的節點名稱。
5. 可選：為您的 MCP 伺服器提供說明。並未將描述欄位提供給代理程式。
6. 從認證下拉式功能表中，選取一種認證方法。
   • 無認證：如果遠端 MCP 伺服器可公開使用且不需要認證，請使用此選項。
   • Bearer token ：如果遠端 MCP 伺服器要求驗證 token，請使用此選項。您必須將 API 金鑰儲存在 Oracle AI Data Platform Workbench 證明資料存放區中，並且提供證明資料存放區項目的參照。
7. 按一下連線。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}} 語法參照。

例如，下列 URL 會將區域的階段作業變數與儲存桶名稱的程式實際執行參數結合：

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 運算，才能安裝相依性並執行此工具。

1. 瀏覽至您的專員。
2. 從「工具」樣板，將「HTTP 要求」工具拖放至工作區。
   
   

   

   
   
3. 在參數頁籤中，提供 HTTP 方法。支援的 moethod 為 GET、POST、PUT、PATCH 以及 DELETE。
4. 在 URL 中，提供目標端點的完整 URL。您可以使用 {{sessionVariables.variable_name}} 階段作業變數參照和 {{variable}} 程式實際執行參數參照。例如：https://api.example.com/users/{{user_id}}/orders。
5. 針對逾時，提供工具等待遠端端點回應的最長時間 (秒)。最大逾時值為 300。如果未提供任何值，預設值為 30 秒。
6. 從認證下拉式功能表中，選取適當的認證類型。
7. 提供 HTTP 要求的標頭。按一下新增以新增其他標頭。
   
   

   

   
   
8. 為您的 HTTP 要求提供任何查詢參數。按一下新增以新增其他參數。
   
   

   

   
   
9. 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。

提示工具

提示工具可讓您在具有範本提示的 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)

表格 22-4 提示工具組態特性

特性	Type	描述
磅	物件	LLM 連線詳細資訊和參數
模型識別碼	字串	要使用之模型的 ID (例如 "xai.grok-4")
模型提供者	字串	LLM 模型的提供者名稱 (例如 "generic")
compartment_id	字串	Oracle Cloud Infrastructure (OCI) 區間 OCID
endpoint	字串	模型的端點 URL
prompt_template	字串	LLM 使用的提示樣板，其變數為 {{variable}} 格式以進行動態插入

測試代理程式提示工具

按一下測試頁籤並填入每個參數的值，即可獨立測試代理程式的工具。提示會提交至您選取的 LLM。

確保已正確定義並記錄提示工具，以改善服務人員的結果。

新增提示工具至專員

您可以將提示工具新增至代理程式，以允許您定義對您選擇的 LLM 發出的參數化提示。

1. 瀏覽至您的專員。
2. 從「工具」範本，將「提示」工具拖放至工作區。
3. 在「組態」頁標中，選取要使用的 LLM，並提供 LLM 提示。按一下程式碼 以提供 JSON 程式碼的組態。
4. 以 0.0 到 1.0 之間的值提供回應的溫度，其中 0.0 提供嚴格的實際回應，1.0 則提供最具創意的回應。
5. 按一下套用 。
6. 提供您在組態中建立之任何參數的定義。按一下程式碼 以提供 JSON 程式碼的組態。
7. 按一下 申請。
8. 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。

RAG 工具

RAG 工具會對向量儲存區發出自然語言查詢，並根據查詢與預存文件之間的語意相似性擷取文件。

附註：

知識庫是建立 RAG 工具的先決條件。如需詳細資訊，請參閱 Knowledge Bases 。

透過視覺流程的 RAG 工具

RAG 工具會要求您作為代理程式開發人員提供下列參數的值：

• 專員面對：
  • 工具名稱：工具的描述性名稱，可協助您和其他使用者識別其功能。
  • 工具描述：提供工具總覽的簡短摘要。
• 工具組態：
  • 知識庫：儲存在其中一個 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())

表格 22-5 RAG 工具組態特性

特性	Type	描述
磅	物件	LLM 連線詳細資訊
catalog	字串	資料目錄 ID
schema	字串	目錄內的綱要
KnowledgeBase	字串	要搜尋的知識庫名稱或索引鍵
最上層 _k	整數	要擷取的最上層相符文件數目

測試代理程式 RAG 工具

將代理程式連附至 AI 運算叢集之後，您可以從測試頁籤測試 RAG 工具。如需詳細資訊，請參閱將現有的 AI 叢集附加至代理程式。

新增 RAG 工具至代理程式

您可以將檢索增強生成 (RAG) 工具新增至您的代理程式，讓代理程式在產生回應時提取相關的外部知識。

1. 瀏覽至您的專員。
2. 從「工具」範本，將 RAG 工具拖放至工作區。
3. 在「組態」頁籤中，選取 RAG 工具從中提取資訊的知識庫，並提供定義要提取資訊的提示。按一下程式碼 以提供 JSON 程式碼的組態。
4. 按一下套用 。
5. 提供您在組態中建立之任何參數的定義。按一下程式碼 以提供 JSON 程式碼的組態。
6. 按一下 申請。
7. 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。

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 工具」定義窗格會填入每個變數，以便設定其類型、預設值和描述。

預留位置可以出現在查詢的任何位置，包括在函數中。下列 Spark SQL 查詢符合不區分大小寫的嚴重度值：

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 身分編輯組態

您可以使用程式碼檢視切換，直接以 JSON 格式編輯 SQL 工具組態。這對於在流程之間複製工具或進行大量編輯非常有用。

{ 
  "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())

表格 22-6 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 文法和每個方言背後的查詢引擎，請參閱下列參照：

Oracle AI 資料平台 SQL

• SQL 文法
  • 目錄 SQL 文法
  • 綱要 SQL 文法
  • 磁碟區 SQL 文法
  • 表格 SQL 文法
  • DML 查詢

Spark SQL 和 Delta Lake (標準目錄)

標準目錄表為差異湖表。標準目錄目前使用 Delta Lake 3.2.0 執行 Spark 3.5。

• Apache Spark SQL 語法：DML 敘述句 Spark SQL 查詢和 DML 敘述句語法。
• 差異資料湖：刪除、更新及合併表格差異表格上的 DELETE、UPDATE 以及 MERGE 作業。
• Delta Lake：表格公用程式命令公用程式作業，例如 OPTIMIZE 與 VACUUM。
• Delta Lake：在 Delta 表格使用液態叢集差異表格版面配置的液態叢集。

新增 SQL 工具至代理程式

您可以將 SQL 工具新增至代理程式，讓代理程式針對已註冊外部目錄中的結構化資料來源執行 SQL 查詢。

1. 瀏覽至您的專員。
2. 從「工具」範本，將 SQL 工具拖放至工作區。
3. 按一下並拖曳代理程式上的連線器控制碼，以連線至工具節點。
   
   

   

   
   
4. 按兩下 SQL 節點，即可開啟組態面板。
5. 為您的工具提供名稱與描述。系統會將描述提供給代理程式，並協助決定何時呼叫工具。
6. 選擇查詢方言：
   • Spark SQL 會根據標準 AI 資料平台目錄寫入查詢。
   • Oracle SQL 會針對外部 AI 資料平台目錄寫入查詢。

   附註：

   Spark SQL 需要在「AI 資料平台工作台」工作區中執行中的 Spark 叢集。
   
   

   

   
   
7. 從叢集下拉式清單中，選取執行中的 Spark 叢集。按一下建立叢集以啟動設定新的 Spark 叢集。如需建立新叢集的指南，請參閱建立自訂叢集。

   附註：

   SQL 查詢工具不會自動啟動停止的叢集。因此，用於 Spark SQL 查詢工具的 Spark 叢集的持續時間應為回復。如果允許叢集在閒置逾時進行微調，則叢集停止後，Spark SQL 查詢便會在生產環境中停止運作。

   
   

   

   
   
8. 在瀏覽目錄下，使用搜尋欄位依名稱尋找目錄，或按一下目錄管理員來尋找目錄。
   
   

   

   
   
9. 在查詢欄位中，輸入您的查詢。按一下檢視查詢範例和指南，開啟內含可複製或調整之現成樣式的面板。
   
   

   

   
   
10. 選取要傳回的資料列上限，以限制查詢結果傳回的資料列數目。

    附註：

    如果您的查詢可以傳回超過此限制的資料列，請考慮新增搜尋參數 (例如 {{customer_name}} 或 {{region}})，讓代理程式可以找到更多特定的資料。
11. 在 AI 工具定義窗格中，設定查詢中所設定變數的類型、預設值及描述。
    
    

    

    
    
12. 選擇性：按一下測試頁籤。提供測試參數，然後按一下送出。在測試結果窗格中查看測試結果。

代理程式記憶體

代理程式記憶體是 AI 代理程式系統的一部分，可讓代理程式跨回合、工作或階段作業保留及重複使用資訊。

與模型的相關資訊環境視窗不同 (暫時性且僅限於目前的提示)，記憶體可以保存環境的事實、偏好設定、先前的決策、工具輸出、中繼計畫或監測項目。

AI 資料平台中的代理程式記憶體

AI Data Platform 提供短期記憶體，僅限於階段作業的持續時間。您可以在代理程式的「記憶體」頁籤中設定可保留在記憶體中的項目。

單一代理程式記憶體組態

您可以在代理程式節點的「記憶體」頁籤中找到單一代理程式系統的記憶體組態。

記憶體組態	描述
啟用代理程式記憶體	此設定會啟用代理程式記憶體。停用時，代理程式基本上是無狀態系統。每輪流均獨立處理，不會詢問後續問題。建議您啟用記憶體。
限制通話歷史記錄	停用此選項時，前一輪會填滿記憶體，直到模型用完環境定義並傳回錯誤為止。如果預期短暫階段作業，則可以停用此設定。不過，對於大多數使用案例，建議您限制對話歷史記錄。
截斷組態	如果您選擇限制對話歷史記錄，可以決定透過下列方式截斷歷史記錄： 僅保留最後 N 則訊息 (使用者 + 專員) 設定整體權杖預算 (先進先出) 或者兩者，以先觸發代理程式記憶體截斷的條件為準
訊息上限	如果您選擇保留最後 N 則訊息，您可以將值設為 N。
權杖預算	或者，您可以設定整體的記號預算。消除第一個記號，以將最新的記號保留在記憶體中。

多代理程式系統記憶體組態 (監督器樣式)

多重代理程式系統的記憶體是在監督器代理程式的「記憶體」頁籤中設定。

多重代理程式系統的記憶體已強制執行且無法停用，而且監督器代理程式節點中顯示的記憶體截斷選項只會套用至監督器代理程式記憶體。您可以根據為整個系統選取的狀態隔離原則，在執行程式節點「記憶體」頁籤中設定每個執行程式代理程式記憶體截斷原則。

多代理程式系統記憶體組態也可讓您選取執行程式代理程式的記憶體共用原則。可能有三個選項：「無狀態」、「專用」和「共用」。請注意，原則會套用至所有執行程式代理程式。

執行器代理程式的狀態隔離	描述
無狀態	每個執行程式代理程式只會見到主管所指派的工作。通話之間不會結轉任何歷史記錄。執行程式代理程式無法對監督器代理程式提出後續追蹤要求。 如果選取無狀態，則會停用每個執行程式代理程式的記憶體。
專用	每個執行程式代理程式只會看到自己的過去互動。 它無法看到其他執行程式代理程式或與主管代理程式的原始使用者對話。
共用	執行者代理程式可以查看所有代理程式和使用者的完整對話歷史記錄。所有代理程式都從一個共用相關資訊環境運作。 如果選取共用，您可以為每個代理程式節點「記憶體」頁籤中的每個執行程式代理程式分別設定記憶體截斷原則。

階段作業變數

您可以使用自訂的代理程式定義階段作業變數，在使用者階段作業期間為代理程式提供額外的相關資訊環境資料點。

什麼是階段作業變數？

自訂的代理程式定義階段作業變數會在使用者階段作業期間，為代理程式提供額外的相關資訊環境資料點。變數可用於各種用途，包括在工具中設定參數值、向專員提供整體指示，以及提供有關來電者和 (或) 內嵌專員之應用程式的情境資訊。

以下是我們建置客戶支援專員的簡化案例。客戶支援專員已整合至零售網站。當使用者登入零售網站時，用戶端應用程式 (使用者 ID、使用者名稱、地理位置、使用的裝置、購物車 ID 等) 會擷取該使用者的資訊，以及下游支援專員可以使用該資訊。以下範例說明如何在 AIDP 的代理程式指示欄位中使用這些階段作業參數：

You are a customer support agent for the retail website belts-and-buckles.com, specializing in the sales of belts and buckles. Your objective is to answer questions that customers have about their current and past orders, answer questions about items they put in their shopping cart, and answer general questions about belts-and-buckles.com.  
A few guidelines before your start:  
    You are interacting with user {{sessionVariable.userName}}. Always start with a welcome message: Hello {{sessionVariable.preferredSalutation}} {{sessionVariable.userName}}! What’s the weather like today in {{sessionVariable.currentUserGeo}}?  

上述範例使用三個階段作業變數：

• userName
• 偏好稱謂
• 目前使用者地理位置

專員事先不知道使用者與零售網站互動，不知道使用者地點為何，也不知道使用者購物車中的內容。原則上，從屬端應用程式可以知道這些值的所有或子集，並將要求中的這些值傳送給代理程式。以下是對代理程式提出之要求的範例，包括階段作業參數。

附註：

此範例說明此要求的外觀。它並非代表實作決策。

"input": [  
{ "role": "user", 
         "content": [  
{ "type": "input_text”,  
	  "text": "What material is the belt Mr Outcast made of?", 
	  “variables”: [“userName”: “Paul”, “preferredSalutation”: “Hon”, “cartID”: NULL, “currentUserGeo”: “Cancun, MX”]  
} 
  ]  
} 
] 

服務人員會回答：「保羅先生，今天在墨西哥坎昆的天氣如何？」

這些階段作業參數的另一個用途是在設定工具中的參數值。例如，SQL 查詢可以使用階段作業參數 {{sessionParam.CartID}} 來擷取購物車的內容：

Select productID, productName, productDescription, 
productPrice from cartTable where cartID == 
{{sessionVariable.cartID}}  

階段作業變數是由代理程式開發人員在建立其代理程式時所定義，而這些屬性的值則是由從屬端應用程式在建立或繼續階段作業時所設定。

建立新的階段作業變數時，您可以設定下列設定值：

設定	描述
必要變數	啟用即可讓代理程式的每個呼叫都需要此階段作業變數。停用會讓每次呼叫的階段作業變數成為選擇性。
日誌變數	啟用即可擷取日誌和追蹤中階段作業變數的值。停用可防止變數出現在日誌中。建議對含有機密資料的變數停用此設定。
名稱	階段作業變數的名稱。使用描述性名稱可讓您與其他使用者輕鬆決定變數的用途。
預設值	如果定義了預設值，如果呼叫呼叫中未定義另一個值，系統就會將預設值指派給階段作業變數。如果保留空白，則必須將值指派為呼叫的一部分。
描述	階段作業變數的描述。提供有用的描述，讓您和其他使用者能夠瞭解階段作業變數的功能。

範例：在工具組態中使用階段作業變數

您可以在 SQL 工具組態中使用階段作業變數作為 SQL 查詢本身的一部分。

在此範例中，使用階段作業變數 geo 來篩選 SQL 查詢的結果：

您可以在同一個查詢中使用階段作業變數和工具參數。在下面的範例中，當呼叫應用程式提供階段作業變數 geo 時，代理程式會設定 titleID 參數。

系統產生的階段作業變數

當遠端 MCP 伺服器連線至代理程式且 MCP 伺服器需要認證 (例如 Bearer 權杖) 時，會自動產生階段作業變數。

階段作業變數會保留 Bearer 權杖的值。無法變更此系統產生階段作業變數的名稱，且為必要變數。當 MCP 節點從工作區移除時，系統變數就會被刪除。

在「操場」中，您提供系統產生之階段作業變數的值。在此情況下，您必須提供 Bearer 權杖才能使用 MCP 伺服器。您可以選取在 MCP 節點組態期間使用的相同 (或其他) 記號。

部署代理程式時也同樣適用。您需要提供授權權杖。如需詳細資訊，請參閱從 Playground 指定值給階段作業變數。

範例：呼叫建置的端點時指派值給階段作業變數

在此範例中，您有兩個階段作業變數：userLocation 和 UserName，從屬端應用程式會透過 body 的 metadata 欄位傳送階段作業變數值。我們將示範如何透過 Python 和 OCI CLI 指派值。

如果您使用 Python 要求程式庫，則有效負載如下：

body = { 

            "isStreamEnabled" : False, 

            "trace" : False, 
            "input" :[{ 
                "role":"User", 
                "content":[{ 
                    "type" : "INPUT_TEXT", 
                    "text" : “Hello how can you help me?”                  
                }] 
            }], 

            "metadata": { 
            "sessionvariables.userLocation": "Canada",  
            "sessionvariables.UserName": "George" 
        } 
        } 

response = requests.post( 
url = <insert-chat-url>,  
params = None,  
auth = <insert-oci-signer>, 
json = body, 
headers={“x-session-id": <insert-a-session-key>,} 
)  

或者，如果您使用 OCI CLI，則有效負載如下：

oci raw-request \ 
  --http-method POST \ 
  --auth security_token \ 
  --request-body '{ 
    "isStreamEnabled": false, 
    "input": [ 
      { 
        "role": "user", 
        "content": [ 
          { 
            "type": "INPUT_TEXT", 
            "text": "Hello how can you help me?" 
          } 
        ] 
      } 
    ], 
    "metadata": { 
      "sessionvariables.userName": "George", 
      "sessionvariables.userLocation": "Canada"}" 
    } 
  }' \ 
  --request-headers '{ 
    "x-session-id": "george-session-may11" 
  }' \ 
  --target-uri "<insert-your-agent-flow-uri>" 

在代理程式變數頁籤中建立階段作業變數

您可以建立新的階段作業變數，然後從「變數」頁籤將它新增至您的代理程式。

1. 瀏覽至您要新增階段作業變數的代理程式。
2. 按一下變數頁籤。
   
   

   

   
   
3. 按一下 新增階段作業變數。
   
   

   

   
   
4. 如果階段作業變數是必要的變數，請選取此選項。
5. 選取要在日誌與追蹤中記錄階段作業變數的值。機密資料若維持此設定值為停用狀態。
6. 為您的階段作業變數提供有意義的名稱與描述。
7. 提供階段作業變數的預設值。如果在呼叫呼叫期間未指派其他值，就會將預設值指派給階段作業變數。
8. 按一下建立。

請參閱代理程式流程指示中的階段作業變數

您可以在代理程式指示和工具組態中參照階段作業變數，包括 SQL 和提示工具查詢。

1. 瀏覽至您的專員流程。
2. 按一下「操場」中的「SQL」或「提示」工具節點。
   
   

   

   
   
3. 在「查詢」欄位中，輸入 {{sessionvariables 。
4. 從現有階段作業變數清單中選取階段作業變數。

使用階段作業變數檢視代理程式和工具

您可以使用代理程式流程中「變數」頁籤的特定階段作業變數來檢視代理程式和工具清單。

1. 使用您要檢視相關服務人員和工具的階段作業變數瀏覽至服務人員流程。
2. 按一下變動式頁籤。
3. 在階段作業變數的用於：旁邊，按一下下拉式功能表。就會顯示使用階段作業變數的代理程式與工具清單。

從遊戲場指定工作階段變數的值

您可以隨時從「操控區」頁籤將值指派給階段作業變數。

1. 瀏覽至您的專員流程。
2. 在「遊樂場」頂端，按一下 階段作業參數。就會顯示代理程式流程中所有階段作業變數的清單。
   
   

   

   
   
3. 修改您的階段作業變數。繼續您的「操場」階段作業之後，就會使用上一個指派的階段作業變數值。
   
   

   

   
   

護欄

Guardrails 是引導和控制 AI 代理行為的安全機制。

在 Oracle AI Data Platform Workbench 中，系統會設定保全，以防止代理程式流程產生或使用有毒和惡意的內容。導軌也會防止代理程式流程洩漏個人識別資訊 (PII)。AI Data Platform Workbench 中提供的特定防護欄適用於內容協調管制、提示注入及 PII。

附註：

Oracle AI Data Platform Workbench 提供的界限僅提供英文版本。

AI Data Platform Workbench 中提供的 Guardrails 由 OCI Generative AI 服務團隊導入。請參閱 OCI Generative AI 指南。AI Data Platform Workbench 服務會根據您的監護人組態，在 OCI 租用戶內呼叫套用監護人 API 。

視覺流程畫面中的界限

根據預設，除了模型提供者的原生安全控制之外，系統不會套用任何防護軌。若要新增監護人，您必須將監護人節點拖曳至您的代理程式視覺流程產生器，並將其連線至代理程式。

防護節點可篩選線上交談觸發程式與專員節點、主管與執行程式專員之間，或專員與工具節點之間的流量。在大多數情況下，我們建議在線上交談觸發器與專員節點之間使用單一防護節點。這會確保來自內送使用者的所有訊息和代理程式產生的訊息，都會透過保全項目進行篩選。

Guardrails 節點只能插入以下各項：

• 對談觸發節點與專員 (主管或執行者)

有哪些 Guardrails？

下圖顯示一般使用者與專員之間的簡單互動。在此情況下，會套用所有軌跡 (內容調解 – CM、提示注入預防 – PI 和 PII 偵測 – PII)。PI 僅適用於使用者查詢。

在一般使用者發出的第二則訊息之後，偵測到 PI 嘗試，且在代理程式開發人員對 PI 偵測 (封鎖) 選取動作之後封鎖使用者訊息。

內容管理

內容協調管制是大多數生成式 AI 中安全防護功能的通用實作。未勾選，LLM 可以產生有害的內容、促進暴力、種族歧視和性明確的內容。要讓專員開發人員完整檢視並控制如何監控與專員進行的使用者互動，以瞭解潛在有害的內容。內容協調管制可防止代理程式流程考慮或產生仇恨、性、暴力、有毒、貶損或騷擾行為的內容。我們的監護人模型會將這六個類別的內容分類，並標示屬於其中一個類別的內容。

您可以選擇對使用者輸入查詢或模型回應採取動作：

• 區塊：您可以防止代理程式處理使用者輸入並產生回應。使用者會收到代理程式流程的錯誤回應。
• 通知：您可以允許代理程式流程處理使用者輸入並產生回應。代理程式會通知使用者輸入或回應包含符合監護條件的內容。
• 允許：您可以允許代理程式流程處理和 (或) 產生潛在有害的內容。

建立代理程式流程時，會選取封鎖動作以進行內容協調管制。Oracle 建議您保留區塊作為選擇內容的監護人。

提示插入

AI 代理的提示注入防護軌是一種保護機制，可偵測、防止和減輕使用者輸入中內嵌的惡意或非預期指示。提示插入攻擊會透過插入隱藏文字，告知模型忽略先前規則、篩選秘密或執行未經授權的動作，嘗試置換或反轉代理程式的原始指示、原則或目標。

您可以選擇對內容審查採取的相同動作：封鎖、通知或允許。提示注入防護軌僅適用於使用者輸入查詢。

• 區塊：您可以防止代理程式處理使用者輸入。使用者會收到代理程式流程的錯誤回應。
• 通知：您可以允許代理程式流程處理使用者輸入。代理程式會通知使用者輸入包含符合監護條件的內容。
• 允許：您可以允許代理程式流程處理潛在有害的內容。

當您建立代理程式流程時，會選取區塊動作來插入。Oracle 建議您保留區塊作為監護人選擇，以便立即插入。

個人身分資訊 (PII)

PII 防護軌會自動從使用者輸入查詢或代理程式回應中偵測、封鎖或遮罩 PII。此防護措施可防止代理程式以違反隱私權法規或組織原則的方式公開機密使用者資訊。

PII 防護軌支援四種實體類型：

• 電子郵件
• Telephone number
• 實體位址
• 人員姓名

對於這四個實體中的每個實體，您可以選擇套用代理程式對輸入使用者查詢或代理程式回應所採取的下列其中一個動作：

• 區塊：您可以防止代理程式處理使用者輸入並產生回應。使用者會收到代理程式流程的錯誤回應。
• 通知：您可以允許代理程式流程處理使用者輸入並產生回應。代理程式會通知使用者輸入或回應包含 PII。
• 遮罩：您可以允許代理程式流程處理輸入並產生遮罩回應。使用的任何 PII 都會被隱匿以防止暴露。
• 允許：您可以允許代理程式流程處理和 (或) 產生 PII 資料。

在新的代理程式流程中，預設允許使用者輸入和回應中使用 PII。Oracle 建議您根據安全需求，謹慎地選取 PII 的監護人。

在節點中啟用特定保全

您可以選擇要啟用的監護人，以及新增監護人節點至視覺化工作區時如何設定這些監護人。

1. 瀏覽至您工作區中的服務人員流程。
2. 將選用區的監護人節點拖曳至工作區。
3. 提供有意義的節點名稱與描述。
   
   

   

   
   
4. 切換防護軌以啟用它並開始設定。再次按下切換會停用監護人和其組態。
   
   

   

   
   
5. 選取每個類別所需的界限組態。
   
   

   

   
   

建立代理程式的 AI 叢集

您可以直接從代理程式介面建立新的 AI 叢集，然後立即附加。

如需詳細資訊，請參閱 AI Compute 。

1. 在「首頁」上，瀏覽至您的專員。
2. 按一下「運算」，然後按一下「建立新的 AI 運算」。
3. 提供 AI 運算叢集的名稱和描述。
4. 選取 AI 運算叢集的 OCPU 數目和記憶體大小。
5. 按一下建立。

將現有的 AI 叢集連附至代理程式

您可以將先前建立的 AI 叢集附加至您至少擁有 USE 權限的代理程式。

1. 在「首頁」上，瀏覽至您的專員。
2. 按一下「運算」，然後按一下「附加至 AI 運算」。
3. 從清單中按一下您要使用的叢集。
   您的代理程式會在順利連附後顯示 AIcompute：(ClusterName) 執行中。這可能需要數分鐘的時間。

從 AI 運算取消連附代理程式

您可以將代理程式與 AI 運算分離。若取消連附 AI 運算，會移除在連附運算上執行的代理程式程式碼，並且不進行測試。

附註：

從 AI 運算取消連附代理程式並不會刪除代理程式。您可以將代理程式連附至相同或不同的 AI 運算，以繼續建立及測試代理程式。

1. 在「首頁」上，瀏覽至您的專員。
2. 按一下「運算」，然後按一下「從 AI 運算切離」。
   
   

   

   
   

A2A 代理程式部署

Agent2Agent (A2A) 通訊協定是獨立 AI 代理程式之間通訊的開放標準，包括使用不同架構建置的代理程式、由不同供應商代管，或以不透明的遠端系統執行。

其目的是為這些專員提供共用的互動模型，以便他們探索彼此的功能、協商支援的輸入 / 輸出格式、委派或協作任務，以及安全地交換資訊，而不公開內部記憶體、工具或導入詳細資料。如需詳細資訊，請參閱 Agent2Agent (A2A) Protocol 。

A2A 旨在解決代理程式互通性：從屬端或其他代理程式可以使用一組通用概念和作業，與任何符合 A2A 規範的遠端代理程式互動，而不是每個自訂的代理程式整合。此規格中心包含訊息、任務、零件、構件、串流更新和推播通知；它支援同步回覆、長時間執行的非同步工作、串流和企業風格的認證 / 安全模式。

在 Oracle AI Data Platform 中，所有已部署的代理程式都提供 /A2A 呼叫路徑，可供 A2A 從屬端應用程式呼叫。

什麼是代理卡？

代理程式卡是由 A2A 伺服器發布的 JSON 描述資料文件。在 AIDP 中，A2A 伺服器是代管代理程式部署的 AI 運算。

此卡描述代理程式的身分識別、服務端點、支援的協定 / 傳輸、功能、技能、支援的輸入 / 輸出模式以及認證需求；從屬端會使用此卡來尋找代理程式是否適合，以及如何呼叫它。正確記錄的代理程式卡是 A2A 通訊協定的必要條件。

AI Data Platform Workbench 中的專員卡處於「草稿」狀態，表示專員尚未部署或「已發布」，表示卡片與專員一起部署。

代理卡動作

在開發客服員期間，卡可在客服員的「動作」功能表中使用。

有兩張專員卡可供使用：

• 草稿卡會反映代理程式目前開發中的狀態。
• 發布的卡片會對應至建置代理程式時所取得的卡片快照。發布的卡會反映已部署代理程式的狀態。

專員卡欄位

AI Data Platform Workbench 支援目前 A2A 通訊協定代理程式卡欄位的子集，可從此處取得： A2A 通訊協定 - 代理程式卡。

欄位	這是必要欄位。	描述
name	是	代理程式的人類可讀名稱。範例：「處方代理程式」
description	是	人為可判讀的專員描述，可協助使用者和其他專員瞭解其目的。範例：「幫助使用食譜和烹飪的代理程式」。
Agent Version	是	代理程式的版本。範例："1.0.0"
Documentation URL	編號	提供代理程式其他相關文件的 URL。
Provider - Organization	編號	代理程式的服務提供者。
Provider - URL	編號	服務提供者的 URL。
Capabilities	是	代理程式支援的 A2A 功能集。 只能設定 streaming (True/False)
Skills	是	技能代表服務人員的能力。這大致上是描述性的概念，但代表專員可能成功的一組更重點的行為。技能代表 AgentSkill 的陣列。

每個 AgentSkill 都是由數個記錄代理程式功能的欄位所組成。在服務人員卡中定義服務人員技能是最耗時的作業，而且是反覆的處理。技能可在部署前在服務人員卡草稿中編輯 (連同其他服務人員卡)。

附註：

inputModes、outputModes 及 securityRequirements 由 AI Data Platform Workbench 提供，無法修改。

欄位	這是必要欄位。	描述
Skill ID	是	專員技能的唯一識別碼。
Skill Name	是	技能的人類可讀名稱。
Description	是	技能的詳細描述。
Tags	是	一組描述技能能力的關鍵字。
Examples	編號	此技能可處理的提示或案例範例。

代理程式部署端點 A2A 路徑

除了 /chat 之外，已部署代理程式的 URL 中會顯示一個 /a2a 路徑。

例如，代理程式會將這些路徑公開給外部用戶端：

• https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/chat
• https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a

兩個路徑 (/chat、/a2a) 都可由個別的從屬端使用。

A2A 中的階段作業變數

階段作業變數的值可以傳遞至訊息 metadata 欄位中的 A2A 代理程式。下方的 JSON 片段顯示發出給 a2a 代理程式之使用者訊息的有效負載 (包含三個階段作業變數)：userName、geoLocation 和 os：

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "contextId": "session_12345",
    "taskId": "task_67890",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "What is the current status of my order?",
        }
      ],
      "metadata": {
        "sessionvariables.userName": "George",
        "sessionvariables.geoLocation": “Dallas, TX”,
        "sessionvariables.os": "mobile_ios"
      }
    }
  },
  "id": "rpc-99821"
}

範例：使用 OCI CLI 呼叫 A2A 代理程式 (非串流處理)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/send",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": "<your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<your-user-principal>"
  }' \
  --target-uri " <your-a2a-agent-endpoint-url>"

範例：使用 OCI CLI 呼叫 A2A 代理程式 (串流)

oci raw-request \
  --http-method POST \
  --auth security_token \
  --request-body '{
    "id": "<your-request-id>",
    "jsonrpc": "2.0",
    "method": "message/stream",
    "params": {
      "configuration": {
        "acceptedOutputModes": [
          "text/plain",
          "text"
        ]
      },
      "message": {
        "contextId": "<your-context-id>",
        "kind": "message",
        "messageId": " <your-message-id>",
        "parts": [
          {
            "kind": "text",
            "text": "What is the capital of India?"
          }
        ],
        "role": "user"
      }
    }
  }' \
  --request-headers '{
    "x-session-id": "<your-session-id>",
    "dh-user-principal": "<user-principal>"
  }' \
  --target-uri "<your-a2a-agent-endpoint-url>"

範例：A2A Client SDK

import asyncio
import json
import logging
import typing
from collections.abc import Iterator
import uuid
import httpx
import oci
from a2a.client import A2AClient, ClientFactory
from a2a.types import (
    AgentCard,
    Message,
    Part,
    Role,
    TextPart,
    SendMessageRequest,
    MessageSendParams,
    MessageSendConfiguration,
    Task, SendMessageSuccessResponse, SendStreamingMessageRequest,
)

class OCIAuth(httpx.Auth):
    """httpx auth implementation using OCI signer via requests auth adapter."""

    def __init__(self, signer: oci.signer.AbstractBaseSigner):
        self._requests_auth = _OCIRequestsAuth(signer)

    def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
        req = RequestsRequest(
            method=request.method,
            url=str(request.url),
            headers=dict(request.headers),
            data=request.content,
        )
        prepared: RequestsPreparedRequest = req.prepare()
        prepared = self._requests_auth(prepared)
        request.headers.update(dict(prepared.headers))
        yield request



def getOCIAuth():
    conf = oci.config.from_file(profile_name="DEFAULT")
    token_file = conf['security_token_file']
    token = None
    with open(token_file, 'r') as f:
        token = f.read()
    private_key = oci.signer.load_private_key_from_file(conf['key_file'])
    signer = oci.auth.signers.SecurityTokenSigner(token, private_key)
    auth = OCIAuth(signer=signer)
    return auth


async def _call_agent_with_a2a(agent_url: str, query: str, context_id: str,auth:OCIAuth) -> str:
    """Call an agent using the A2A protocol."""
    try:
        # Initialize OCI signer
        #headers = {"dh-user-principal": "dh-user"}
        headers = {"Accept": "*/*",
                   "dh-user-principal": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}

        async with httpx.AsyncClient(timeout=60.0, auth=auth,headers=headers) as hc:
            agent_card = await _get_agent_card(agent_url,auth)
            print(f"Agent card is {agent_card}")

            client =  A2AClient(httpx_client=hc, agent_card=agent_card)
            # Create message
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
                metadata={"sessionvariables.cred.mcp.weatherReportMCP.bearer": "valid-123"}
            )
            request = SendMessageRequest(
                id=str(uuid.uuid4()),  # Add the required id field
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            #json_string = json.dumps(message, indent=4)
            print(f"Send request : {request}")

            response = await client.send_message(request)

            logging.info("Received response from A2A server: %s", response.root.result)
            # Extract response
            result = response.root.result
            # Handle different response types


            if isinstance(result, Task):
                # Task response
                if result.artifacts:
                    # Extract text from artifacts
                    texts = []
                    for artifact in result.artifacts:
                        for part in artifact.parts:
                            if hasattr(part, "root") and hasattr(part.root, "text"):
                                texts.append(part.root.text)
                    return "\n".join(texts) if texts else "Task completed with no text response"
                elif result.status and result.status.message:
                    logging.info(f"Received Task status {result.status.state} from A2A server and status message is {result.status.message}", result.status.message)
                    if  result.status.state== "failed":
                        print("Failure observed in Task invocation")
                        for m_part in result.status.message.parts:
                           print(f"Error message  { m_part.root.text}")

                    return get_message_text(result.status.message)
                else:
                    return f"Task {result.id} status: {result.status.state if result.status else 'unknown'}"

            elif isinstance(result, Message):
                return get_message_text(result)
            else:
                logging.warning(f"Unexpected response type: {type(result)}")
                return "Received response but unable to extract text"
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"


async def _call_agent_with_a2a_with_stream(agent_url: str, query: str, context_id: str, auth: OCIAuth) -> str:
    """Call an agent using the A2A protocol with streaming (SSE) and return the final artifact text."""
    try:
        async with httpx.AsyncClient(timeout=60.0, auth=auth) as hc:
            agent_card = await _get_agent_card(agent_url)
            if not agent_card:
                return "No Agent Card Found"
            print(f"Agent card is {agent_card}")

            client = A2AClient(httpx_client=hc, agent_card=agent_card)
            message = Message(
                message_id=str(uuid.uuid4()),
                context_id=context_id,
                role=Role.user,
                parts=[Part(root=TextPart(text=query))],
            )
            request = SendStreamingMessageRequest(
                id=str(uuid.uuid4()),
                params=MessageSendParams(
                    message=message,
                    configuration=MessageSendConfiguration(acceptedOutputModes=["text/plain", "text"]),
                ),
            )
            print("Invoking Remote Agent request (beautified JSON):")
            print(json.dumps(request.model_dump(), indent=2, ensure_ascii=False))
            # Expected event types:
            # - TaskStatusUpdateEvent (working/in-progress)
            # - TaskArtifactUpdateEvent (contains Artifact.parts[].root.text) -> final output
            final_artifact_text_parts: list[str] = []

            async for event in client.send_message_streaming(request):
                # Print each SSE event as-is (SDK object)
                print(f"[A2A stream event] {event}")

                try:
                    result = getattr(event.root, "result", None)
                    if not result:
                        continue

                    # TaskArtifactUpdateEvent and TaskStatusUpdateEvent are SDK types; to avoid tight coupling,
                    # extract by attribute presence.
                    artifact = getattr(result, "artifact", None)
                    if artifact and getattr(artifact, "parts", None):
                        for part in artifact.parts:
                            root = getattr(part, "root", None)
                            txt = getattr(root, "text", None)
                            if txt:
                                final_artifact_text_parts.append(txt)
                except Exception:
                    # Keep streaming even if an event can't be parsed
                    continue

            return "\n".join([t for t in final_artifact_text_parts if t]).strip() or "Stream completed (no artifact text)."
    except Exception as ex:
        logging.error(f"Error calling agent at {agent_url}: {ex}", exc_info=True)
        return f"Error communicating with agent: {str(ex)}"

編輯草稿專員卡

您可以編輯尚未建置之代理程式的代理程式卡。

1. 瀏覽至您的專員。
2. 按一下動作，然後按一下檢視服務人員卡與草稿服務人員卡。
   
   

   

   
   
3. 按一下編輯。
   
   

   

   
   
4. 您可以按一下右上方的表單或 JSON 來切換檢視。JSON 檢視較完整，但為唯讀。您只能編輯「表單」檢視中的欄位。
   
   

   

   
   
5. 視需要修改欄位。
6. 按一下新增技能以新增要對 A2A 從屬端公開的技能。
   
   

   

   
   
7. 按一下「儲存」。

編輯已發布的專員卡

您可以修改已發布的代理程式卡，而不需取消部署或重新部署代理程式。

發布的卡片會對應至部署時草稿卡的快照。

附註：

您對已發佈的卡片所做的變更會立即反映在 A2A 用戶端可存取的 agent-card.json 檔案中。

1. 瀏覽至您的專員。
2. 按一下動作，然後按一下檢視服務人員卡與已發布的服務人員卡。
   
   

   

   
   
3. 您可以按一下右上方的表單或 JSON 來切換檢視。JSON 檢視較完整，但為唯讀。您只能編輯「表單」檢視中的欄位。
4. 按一下編輯。
   
   

   

   
   
5. 視需要修改欄位。
6. 按一下新增技能以新增要對 A2A 從屬端公開的技能。
   
   

   

   
   
7. 按一下「發布變更」。

公布的專員卡無法公開使用。使用者必須經過認證，並且具備檢查 agent-card.json 內容的權限 (READ)。其他代理程式可以透過 HTTP GET 要求，在標準路徑上尋找您的代理程式功能和描述資料：

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/a2a/agent-card.json

代理程式部署

部署代理程式會將您的代理程式轉換成代管的應用程式。

您可以將代理程式部署到連接到其遊樂場或不同 AI 運算的相同 AI 運算中。當您將代理程式的最新變更部署到附加的 AI 運算時，部署的代理程式代表部署時代理程式的快照。若要將部署的代理程式更新為最新版本，您必須重新部署代理程式。

每個代理程式都有穩定的部署 URL，取決於唯一的代理程式金鑰。重新建置代理程式多次會覆寫建置 URL 後面的代理程式。

部署代理程式有下列限制：

• 代理程式在任何指定時間都只能部署到一個 AI 運算叢集。
• 在相同的 AI 運算叢集多次部署相同的代理程式，會覆寫先前部署的代理程式重複。

部署專員之後，您可以擷取線上交談 URI，以程式設計方式發出查詢，並從專員的詳細資料頁籤中擷取專員的回應。

端點 URL 穩定且與每個代理程式連結。此 URL 包含指派給每個代理程式的唯一 agentID。換句話說，如果您取消建置代理程式並再次建置代理程式，URL 會保持不變。優點是您不需要修改呼叫端點的從屬端程式碼，這項缺點是您可以覆寫生產環境中的代理程式。

URL 的結構如下：

https://gateway.aidp.{oci-region}.oci.oraclecloud.com/agentendpoint/{agentId}/{protocol}

其中：

• oci-region 對應至「AI 資料平台」實例區域；
• agentId 是與代理程式關聯的唯一 ID
• protocol 是通訊協定：chat，遵循 OpenAI 回應 API 格式，而 a2a 則遵循代理程式對代理程式通訊協定。每個代理程式端點均可使用這兩種協定。如需詳細資訊，請參閱 A2A 代理程式部署。

附註：

「詳細資訊」頁籤中會列出兩個 AI 計算。連附至 AI 運算主要用於測試操場中的代理程式。部署到 AI Compute 會代管部署的代理程式。

部署代理程式之後，就會填入端點 URL 欄位。您可以從生產環境應用程式呼叫此端點 URL。

部署代理程式

您可以部署已建立並設定的代理程式，讓其他使用者能夠在 AI Data Platform 執行處理中查看並使用該代理程式。

1. 在首頁上，瀏覽至包含您要部署之代理程式的資料夾。
2. 在代理程式旁邊，按一下 動作，然後按一下建置。您也可以按一下代理程式名稱，然後按一下右上方的部署。
   
   

   

   
   
3. 選取要連附至已部署代理程式的 AI 運算。
4. 選取授權類型的 AIDP 工作台。
5. 選取階段作業資料保留原則。
   • 在保留期間中，提供階段作業資料保留的天數。
   • 若為階段作業大小限制，請提供階段作業可達到的大小上限。
   • 若為繫線計數限制，請提供保留的階段作業繫線數目上限。
6. 按一下部署。

使用 OAuth2 部署代理程式

您可以部署已建立並設定為使用 OAuth2 認證連線至外部身分識別提供者的代理程式。

1. 在首頁上，瀏覽至包含您要部署之代理程式的資料夾。
2. 在代理程式旁邊，按一下 動作，然後按一下建置。您也可以按一下代理程式名稱，然後按一下右上方的部署。
   
   

   

   
   
3. 選取要連附至已部署代理程式的 AI 運算。
4. 選取 OAuth2 作為授權類型。
5. 提供對象請款。AI Data Platform Workbench 會自動填入此欄位，但您可以使用身分識別提供者的訴求對象取代此欄位。
6. 提供發照者申請與 URI 以擷取 JWKS 。此資訊衍生自您的身分識別提供者。
7. 選取階段作業資料保留原則。
8. 按一下部署。

呼叫建置的代理程式

您可以從生產環境應用程式呼叫代理程式的端點 URL。

無論用於呼叫代理程式端點的程式設計介面為何，都必須向 OCI 進行認證，並具有相關權限。如果是「代理程式流程」端點，則呼叫者必須至少具備代理程式端點的 USE 權限。

端點 URI 會記錄在代理程式 UI 的「詳細資訊」頁籤中。您可以將該端點 URI 複製到您的程式碼中，以呼叫代理程式。

呼叫端點 URI 的方法

您可以透過不同的工具、SDK 和 CLI 來呼叫代理程式端點 URI。

下列方法可讓您在 Oracle AI Data Platform Workbench 代理程式中呼叫您的端點 URI。

使用 OCI CLI 呼叫

提供的範例示範如何使用 OCI CLI，並使用安全權杖進行認證。將 <your-agent-flow-endpoint-uri> 取代為您的代理程式端點 URI，將 <security_token> 取代為您的 OCI 安全權杖。

oci raw-request
--http-method POST
--target-uri <your-agent-flow-endpoint-uri>
--request-body '{"query":"Tell me about the Ryder Cup in 1985"}'
--auth <security_token>

使用 Python 要求函式庫呼叫

您可以使用 OCI Python SDK 建立簽署者以使用 OCI 進行認證。Python 要求程式庫可用來將要求張貼至代理程式端點 URI 並傳回回應。下列範例示範如何透過 OCI 組態和私密金鑰檔案使用您的使用者主體：

import oci import requests import json import uuid from contextlib import closing from requests import Request, Response
class AuthHelper: """ AuthHelper allows creating an OCI signer with either API key or security_token (which are short term sessions) """ def init(self, oci_profile: str, use_security_token:bool = True): config = oci.config.from_file(file_location="/Volumes/jr/default/misc/config",profile_name=oci_profile) if use_security_token: with open(config["security_token_file"], 'r') as f: token = f.read() private_key = oci.signer.load_private_key_from_file(config["key_file"])
 self.signer = oci.auth.signers.SecurityTokenSigner(token, private_key) else: self.signer = oci.signer.Signer( tenancy=config["tenancy"], user=config["user"], fingerprint=config["fingerprint"], private_key_file_location=config["key_file"], #pass_phrase=config.get("pass_phrase"), #private_key_content=config.get("key_content") )
@property
def Signer(self):
    return self.signer
 
class MyRawJsonRpcClient: """ Simple class using requests lib to post JSON to chat endpoint using OCI signing """ def init(self, chat_url:str, oci_profile: str, sessionKey:str, use_security_token:bool = True): self.authhelper = AuthHelper(oci_profile=oci_profile, use_security_token=use_security_token) self.authsigner = self.authhelper.Signer self.chat_url = chat_url self.sessionKey = sessionKey
def send(self, input:str) -> Response:
    body = {
        "isStreamEnabled" : False,
        "sessionKey" : self.sessionKey,
        "trace" : False,
        "input" :[{
            "role":"User",
            "content":[{
                "type" : "INPUT_TEXT",
                "text" : input                   
            }]
        }]
    }

    response:Request = requests.post(
        url =self.chat_url,
        params = None,
        auth = self.authsigner,
        json=body,
        headers={}
    )
    return response

您可以透過建立 MyRawJsonRPCClient 類別並提供 OCI 設定檔值 (在 OCI 組態檔中找到)、代理程式端點 URI (chat_url) 和 sessionKey 來呼叫代理程式端點 URI。您可以任意提供 sessionKey。sessionKey 是代理程式之使用者階段作業的唯一 ID。如果您持續重複使用相同的 sessionKey，使用者訊息和代理程式回應會附加至相同的保留。

client = MyRawJsonRpcClient(chat_url="<your-agent-flow-endpoint-uri>",
   oci_profile = "DEFAULT",
   sessionKey= “<your-session-key>”,
   use_security_token = False )

您也可以提供使用者訊息，並使用從屬端將訊息傳送至代理程式端點 URI：

user_input = f"Hello, tell me a good dad joke."
r = client.send(input = user_input)
response_json = r.json()

透過 APEX

您可以使用 AI Data Platform Workbench 範例 Github 儲存庫中的程式碼範例。此範例會逐步引導您從 APEX 應用程式呼叫代理程式部署端點。

透過 Streamlit

您可以使用 AI Data Platform Workbench 範例 Github 儲存庫中的程式碼範例。此範例會逐步引導您從 Streamlit 應用程式呼叫代理程式部署端點。

最佳作法 - 非同步與非同步回應

建議您使用非同步回應撰寫您的從屬端程式碼。舉例而言：

import httpx 
 
async def fetch_data(): 
    async with httpx.AsyncClient() as client: 
        response = await client.get(URL) 
        return response.json()

取消部署代理程式

您可以選擇取消建置您具有「管理」權限的代理程式，使其無法使用。

1. 在首頁上，瀏覽至包含您要取消部署之代理程式的資料夾。
2. 在代理程式旁邊，按一下 動作，然後按一下取消建置。
   
   

   

   
   
3. 按一下取消建置。

監督代理程式

您可以監督與代理程式的階段作業和測量結果相關的詳細資訊，以查看其使用方式、使用的資源等相關資訊。

您的代理程式中有多個頁籤可供追蹤使用狀況詳細資訊、階段作業頁籤、測量結果頁籤以及活動頁籤。您可以在服務人員工作區的頂端找到它們。

追蹤與跨度

追蹤透過擷取和顯示代理程式要求的流程，為您的代理程式提供可觀察性。跨度是構成追蹤的物件。每個跨度都是流程中的不同步驟，例如來自使用者的線上交談提示、專員呼叫及工作流程任務。

您可以查看目前階段作業、測試執行或先前階段作業的追蹤。若要查看目前的階段作業追蹤，請移至「流程」頁籤，然後按一下「操控區」。頁面底端的「詳細資訊」窗格會在左窗格中顯示目前階段作業的追蹤。您可以按一下追蹤中的物件來展開或檢視更詳細的資訊。在右窗格中，您可以按一下「資訊」、「詳細資訊」或「事件」頁籤，以進一步瞭解選取的跨度物件。

按一下階段作業的名稱，即可在階段作業頁籤中查看先前階段作業的追蹤。

階段作業

在階段作業頁籤中，您可以查看此代理程式的階段作業歷史記錄。您可以查看每個階段作業是否成功或失敗、URI 來源、階段作業啟動時、階段作業的持續時間，以及階段作業中使用的記號。您可以按一下階段作業 ID 以取得有關該階段作業的更多特定詳細資訊，並查看該特定階段作業的追蹤。

您可以使用「搜尋」列依階段作業 ID 或 URI 來源篩選顯示的階段作業，使用日期篩選僅顯示特定日期範圍，使用「階段作業狀態」下拉式功能表則依階段作業成功或失敗篩選。

度量

測量結果頁籤顯示所有代理程式階段作業的使用狀況資料摘要。「日期範圍」下拉式清單會篩選您要在顯示的卡片中查看摘要的期間。URI 選擇項目會篩選您要查看詳細資訊的 URI 選擇項目來源。您可以修改顯示哪些卡片，以及是否包含圖表作為使用視覺表示法。

活動

活動頁籤顯示代理程式部署狀態的摘要。「作業」資料欄指定建置作業的類型 (「建置」或「取消建置」)，而「狀態」資料欄指定作業的結果 (「成功」、「錯誤」、「警告」、「失敗」)。您可以查看起始作業的人員、起始時間，以及與作業結果相關聯的狀態訊息。

檢視代理程式階段作業

您可以檢視專員的階段作業歷史記錄並篩選結果以查看趨勢並協助進行疑難排解。

1. 在「首頁」上，瀏覽至您的專員。
2. 按一下「階段作業」頁籤。
3. 使用篩選來變更顯示的階段作業。

檢視代理程式度量

您可以檢視所使用代理程式的摘要詳細資訊，例如記號使用狀況、階段作業持續時間、延遲等等。

1. 在「首頁」上，瀏覽至您的專員。
2. 按一下測量結果頁籤。
3. 從日期範圍下拉式清單中選取不同的選項，以查看度量在時間軸上的差異。
4. 從 URI 選擇下拉式清單中選取其他選項，以篩選特定 URI 來源。

移動代理程式

您可以移動您擁有或具有管理權限的代理程式。

1. 在「首頁」上，瀏覽至包含您要移動之代理程式的資料夾。
2. 在您要修改的代理程式旁邊，按一下 動作，然後按一下移動。
3. 選取代理程式的新工作區位置。按一下移動。

複製代理程式

您可以將您擁有的代理程式或具有可用工作區的「管理」權限，複製到另一個位置。

您可以將代理程式複製到相同或不同的資料夾。代理程式流程可以複製到您有權存取之不同工作區中的資料夾。系統會複製代理程式組態以及工具和監護人設定值。不會複製 AI 運算叢集連附項，您必須將代理程式連附至新的 AI 運算叢集，才能繼續開發。

1. 在「首頁」上，瀏覽至包含您要移動之代理程式的資料夾。
2. 在您要修改的代理程式旁邊，按一下 動作，然後按一下複製到工作區。
3. 視需要提供複製之代理程式的新名稱和描述。
4. 按一下瀏覽，然後選取工作區中的新位置以複製代理程式。按一下「選取」。
5. 按一下「複製」。

下載代理程式檔案

您可以下載包含該代理程式定義之代理程式檔案及其監護人檔案。

代理程式檔案是副檔名為 AFLOW 的 JSON 檔案，並且包含代理程式的定義。監護人檔案會標示為 _guardrails.JSON，並包含代理程式的監護人定義。

1. 瀏覽至您工作區中的代理程式資料夾。
2. 按一下您要下載之代理程式的名稱。
   
   

   

   
   
3. 在您代理程式的 AFLOW 檔案旁邊，按一下 動作，然後按一下下載。檔案就會下載到您的本機機器。
4. 在 _guardrails.JSON 檔案旁邊，按一下 動作，然後按一下下載。檔案就會下載到您的本機機器。