17 建立代理程式
本節涵蓋透過視覺化流程產生器或透過程式碼建立 AI 代理。
多代理系統與主管模式
多代理程式系統是一種 AI 應用程式設計，由多個合作代理程式處理使用者要求，而不是由一個大型、全用途的代理程式處理。
每個代理程式都有自己的角色、指示、模型組態、記憶體原則及允許的工具。流程會定義要求在這些服務人員之間移動的方式，以及最終答案的產生方式。
此設計在工作流程自然分離為專家職責時非常有用。例如，一個專員可以擷取資料，另一個專員可以呼叫 API，另一個專員可以彙總結果，而主管可以決定要使用哪個專員，並將結果結合成單一回應。
附註：
作為設計原則，最好從符合需求的最小代理設計開始。分離問題可提高可靠性、安全性、維護性或可觀察性，同時增加多個專員的成本和複雜性。多代理系統的優點
- 專業化：為每個專員提供一個專注的工作、提示和工具集，而不是一個擁擠的指令區塊。
- 製程與分解：讓主管解譯請求、將其分割為子作業，並為每個子作業選擇正確的專員。
- 工具和資料隔離：僅向負責使用機密或高影響力的代理程式公開這些工具。
- 治理與疑難排解：讓交接、工具擁有權、記憶體設定值及失敗點更容易檢查。
何時選擇多重代理程式或單一代理程式設計
具有更多工具的單一專員通常是正確的第一個設計。測試、執行成本更低，以及更容易推理任務何時具有一個明確的目標與一個權限模型。當工作流程受惠於明確角色、有界限的工具存取，或可協調多個專家輸出的主管時，請使用多重代理程式設計。
| 設計問題 | 使用單一代理程式時機 ... | 使用多重代理程式時機 ... |
|---|---|---|
| 工作元件 Stencils | 要求有一個主要目標和一個回應磚塊。 | 要求必須經過分解、遞送、驗證，或跨專業領域進行合成。 |
| 工具與資料 | 相同的指令集和權限模型可以安全地管理所有工具 | 不同的代理程式需要不同的工具、資料來源或存取界限。 |
| 指示 | 即使在單一位置使用所有商業規則和工具指引，提示仍保持清晰。 | 指示可以較小、角色特定的提示進行維護。 |
| 成本和延遲 | 您希望從使用者訊息到答案的最短路徑。 | 可靠性、治理或維護性優點可證明額外的協調性。 |
| 疑難排解 | 在單一追蹤中對失敗進行除錯相當簡單。 | 您需要明確的交接、狀態隔離，以及更清晰的每個步驟所有權。 |
支援的樣式：協調程式 / 主管
目前的工作區體驗支援協調器 / 監督器樣式。在此模式中，「交談觸發程式」會接收使用者訊息、選擇性的「保全」會評估輸入，而「監督器代理程式」會作為其餘流程的協調器。
主管應著重於計劃、發送、委派與最終回應合成。它會決定應該處理工作的執行程式代理程式、傳送該執行程式的作用領域指示、複查結果，然後委派另一個步驟或傳回最終回應。執行人員代理程式應能縮小專家的範圍：他們會執行指派的工作、使用附加的工具，並將有用的結果傳回主管。
關於視覺流程畫面
代理程式的組合方式是將節點和工具樣板從左側選盤拖曳至工作區，然後依要求傳送的順序連線節點。
選取節點會在畫面底部開啟組態面板。
| 工作區元素 | 目的 |
|---|---|
| 對談觸發 | 使用者訊息的進入點。在螢幕擷取畫面中，此節點標示為「訊息」，且通常位於流程頂端。
線上交談觸發節點可以連線至專員、主管專員或監護人節點。每個工作區只能有一個線上交談觸發程式。 |
| 護欄 | 在模型工作之前或之後放置的選擇性政策與安全層。保護原則包括 PII、內容協調管制，以及提示插入偵測。
防護節點可篩選線上交談觸發程式與專員節點、主管與執行程式專員之間，或專員與工具節點之間的流量。我們建議在交談觸發程式和代理程式節點之間使用單一防護節點。 |
| 主管代理人 | 協調者。它會接收到使用者要求、決定應處理每個工作的執行程式代理程式或工具，以及協調最終答案。
工作區中只能有一個主管專員。 |
| 代理程式 | 執行程式代理程式。每個執行程式都應該有明確的專長，例如資料擷取、API 查詢、摘要或文件問題回答。
使用單一代理程式系統的代理程式 / 執行程式代理程式。 |
| 工具範本 | 可連附至個別執行程式或監督器代理程式的可重複使用功能。工具範本包括 SQL、RAG、提示、HTTP、遠端 MCP 伺服器和自訂工具。 |
| 開發 / 遊樂場 | 工作區上方的模式選取器。編輯代理程式系統時會使用開發；您可以使用 Playground 來起始測試階段作業及檢查代理程式行為。
Playground 需要將 AI 運算連附至您的代理程式。 |
| 縮放控制項 | 工作區縮放選取器。螢幕擷取畫面顯示 60% 與 90% 的縮放比例。 |
新增線上交談觸發程式和服務人員至 Visual Builder 工作區
使用 Visual Builder 建立專員之後的第一個步驟，應該是新增線上交談觸發程式和主管專員。
- 按一下並拖曳監督器代理程式至工作區。
設定主管代理程式
您必須設定已新增至 Visual Builder 工作區的主管代理程式，並附上主管角色概述的指示。
| 欄位 | 組態 |
|---|---|
| 代理程式名稱 | 提供主管代理程式的描述性名稱。透過追蹤和記錄對系統行為進行除錯時，一個好的描述性名稱會很有幫助。 |
| 專員描述 | 提供專員用途、角色及一般行為的描述。可用於說明文件。 |
| 區域 | 選擇主管代理程式所使用之 OCI Generative AI 模型的代管區域。請參閱按區域分類的生成式 AI 模型。 |
| Model | 選擇主管使用的 OCI Generative AI 服務模型。下拉式清單列出所選區域中可用的模型。 |
| 代理程式指示 | 描述主管角色、路由規則、委派原則、工具使用預期以及最終回應格式。 |
- 瀏覽至工作區中的代理程式。
- 按一下工作區上的監督器代理程式節點。
- 為您的主管代理程式提供易記的名稱和描述。
- 輸入主管所使用 OCI Generative AI 服務模型的區域和模型。
- 提供您「主管代理程式」的代理程式指示。
建議的主管指示
您應使用「主管專員」的「指示」欄位，讓主管負責協調，而非執行每個任務本身。
讓指示保持具體，以便預測路由決策。請參閱下列範例中的「主管」指示：
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 相關資訊環境視窗。要顯示完整瀏覽紀錄請關閉 。 |
| 截斷組態 | 如果啟用限制對話歷史記錄，請使用此欄位來設定截斷相關資訊環境視窗的條件。
選項包括：
|
| 最大訊息限制與變數替代字預算 | 視您選擇的截斷組態而定，會顯示其中一個或兩個選項。
預設值為 20 則訊息和 5000 個記號。建議您從中等值開始並視需要進行調整。 |
| 執行器代理程式的狀態隔離 | 選取無狀態、專用或共用。
|
- 瀏覽至工作區中的代理程式。
- 按一下工作區上的監督器代理程式節點。
- 按一下記憶體頁籤。
- 選擇是否要啟用限制對話歷史記錄。選取截斷組態並設定限制 (如果啟用)。
- 選擇執行程式代理程式的狀態隔離選項。
模型參數頁標
「模型參數」頁籤可讓您設定可供所選模型使用的模型特定參數。
您可以分別為 supervisor 和執行器代理程式設定模型參數。您可使用的參數包括溫度、最高 K、最高 P 和頻率懲罰。
附註：
只有模型子集會公開可設定的參數。此外，模型族群的參數也會不同。
新增界限至代理程式
您可以新增一或多個界限節點至工作區，為您的代理程式新增額外的保護層。
| 監護人 | 選項 | 使用時機 |
|---|---|---|
| 個人可識別資訊 (PII) |
|
當流程必須在模型處理前後封鎖或隱藏敏感的個人資料時使用。 |
| 預防內容審查 | 具有「區塊」、「通知」及「允許」選項的「輸入」與「輸出」列。 | 用來定義流程如何處理仇恨、性、暴力、有毒、貶損或騷擾內容。 |
| 提示注射檢測 | 具有「區塊」與「允許」選項的輸入列。 | 用來減少惡意指示覆寫系統或代理程式指示的機會。 |
- 將游標停駐在連線上並按一下紅色 X，以刪除「線上交談觸發程式」與「主管專員」之間的連線。
將執行程式代理程式和工具新增至代理程式
您可以將執行程式代理程式新增至工具，以執行 supervisor 代理程式的特殊工作。
- 瀏覽至工作區中的代理程式。
- 將「代理程式」節點從選用區拖曳至工作區。代理程式節點應該放置在「監督代理程式」之下。
- 將「工具」從選用區拖曳至工作區。
- 按一下並拖曳「監督器代理程式」上的連線器控制代碼，即可連線到「代理程式」節點。
- 按一下並拖曳「代理程式」上的連線器控制代碼，即可連線至「工具」節點。
執行器代理程式組態
您可以透過修改其「組態」、「記憶體」和「模型」頁籤上的設定值來設定代理程式節點，以協助您定義每個代理程式的用途。
代理程式應具有特定功能和目標，以便能夠可靠地遞送工作。
表格 17-1 代理程式組態頁籤
| 欄位 | 組態 |
|---|---|
| 代理程式名稱 | 最佳作法是根據每個執行程式代理程式的專業性來命名，例如 SQL_AGENT、DOCUMENT_AGENT、API_AGENT 或 SUMMARY_AGENT。
supervisor 代理程式可看到每個執行器代理程式的名稱，因此使用描述性名稱。 |
| 專員描述 | 提供每個執行程式代理程式的詳細描述。主管代理程式可以看到每個執行程式代理程式的描述。 |
| 區域 | 選擇代管代理程式所使用之 OCI Generative AI 模型的區域。請參閱按區域分類的生成式 AI 模型。 |
| Model | 選擇代理程式所使用的 OCI Generative AI 服務模型。下拉式功能表會列出所選區域中可用的模型。
選取適合執行程式工作的模型。執行器代理程式不需要使用與監督器代理程式相同的模型。 |
| 代理程式指示 | 描述執行程式應該執行的動作、它可能使用的工具以及它應該傳回的輸出結構。 |
執行器代理程式記憶體頁籤
如果執行程式代理程式連線至監督器代理程式，執行程式的記憶體會在監督器節點中設定，並套用至所有執行程式代理程式。
| 欄位 | 組態 |
|---|---|
| 啟用代理程式記憶體 | 當使用者需要多重週轉連續性時啟用。針對獨立的單次使用任務停用。 |
| 限制通話歷史記錄 | 啟用即可在達到指定的限制後截斷 LLM 相關資訊環境視窗。要顯示完整瀏覽紀錄請關閉 。 |
| 截斷組態 | 如果啟用限制對話歷史記錄，請使用此欄位來設定截斷相關資訊環境視窗的條件。
選項包括：
|
| 最大訊息限制與變數替代字預算 | 視您選擇的截斷組態而定，會顯示其中一個或兩個選項。
預設值為 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 體驗。
表 17-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 程式碼基礎，使用現有程式碼建立端對端代理程式應用程式。
附註：
您可以上傳個別檔案和資料夾，最多 500 個檔案，每個檔案的大小上限為 500MB。上傳大小限制為 5GB。- 按一下上傳。
透過程式碼建立新程式碼來建立代理程式
您可以透過程式碼編輯器，直接在代理程式中建立程式碼，使用現有的程式碼建立端對端代理程式應用程式。
- Python (.py)
- JSON
- 交易
- CSV
- PSV
- SH 語言
- 資料夾
- 按一下新增檔案。
透過代碼設定專員的輸入檔案
透過程式碼的 AI 代理程式需要一個項目檔案，該檔案具有預期的代理程式類別、設定及呼叫方法。
- 在項目檔案上按一下滑鼠右鍵，然後按一下設定項目檔案 (Set entry file) 。您也可以選取檔案，然後按一下程式碼編輯器右上方的設定項目檔案按鈕。
透過代碼設定代理程式的相依性檔案
您必須透過包含您程式碼相依之任何第三方程式庫的程式碼，設定代理程式流程的相依性檔案。
- 在相依性檔案上按一下滑鼠右鍵，然後按一下設定相依性。您也可以選取檔案，然後按一下程式碼編輯器右上方的設定相依性檔案按鈕。
測試代理代碼
您可以從「測試」頁籤測試代理程式使用的程式碼，以驗證和除錯程式碼。
- 按一下播放區頁籤。
- 按一下播放以測試選取的程式碼檔案。
編寫程式碼體驗的專員技能
專員技能可讓專員尋找並使用特定任務的指示、參考檔案、範本、資產及選擇性的可執行指令碼，而不需要將網域知識編碼到專員的指示中。
技能會儲存為服務人員代碼庫中的資料夾。每個技能都有必要的 SKILL.md 檔案，描述技能的作用以及服務人員應如何使用它。技能也可以包含支援的檔案，例如綱要、範例、提示、範本、資產或命令檔。
如需詳細資訊，請參閱專員技能概要。
- 專員發現有技能存在。
- 專員只有在相關時才會啟用技能。
- 只有在需要時，專員才會從技能資料夾載入其他檔案。
- 如果技能允許，專員可以執行明確宣告的技能進入點。
何時使用服務人員技能
- 網域特定指示
- 編碼或資料分析工作流程
- 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.
表 17-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 顯示可重複使用的執行檔行為。這適用於受控制的作業，例如計算、轉換、驗證或擷取結構化資料。
- 技能必須在允許的工具中包含
run_skill_entrypoint。 - 必須在
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.
可執行項目點的規則
- 位於技巧的文稿 / 目錄下
- 在技能的進入點前端中宣告
- 技能的
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_csventrypoints:
- name: run
- name: do_it 傳回結構化結果
執行檔應該盡可能傳回 JSON 序列化結果。這可讓代理程式更容易檢查和使用輸出。
避免不必要的執行
偏好使用說明與參考檔案 (若可行)。僅針對真正需要程式碼的作業使用可執行項目進入點。
專員技能疑難排解
如果您在導入「專員技能」時發生問題，請查看此清單以協助解決您的問題。
專員看不到我的技能
- 技能資料夾位於已設定的技能目錄下。
- 資料夾包含 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 為基礎的代理程式，以驗證和除錯您的代理程式。
- 在畫面頂端，按一下播放區。將代理程式推送至連附的運算可能需要數秒鐘的時間。
