代理元件

重要事項

本文中的部分資訊與發行前版本產品有關，在產品正式發行前可能會大幅度修改。 Microsoft 對此處提供的資訊，不提供任何明確或隱含的瑕疵擔保。

本文提供定義自訂 Security Copilot 代理功能的關鍵組成部分的概念概述，幫助您理解其結構、行為及操作邏輯。

代理程式

Security Copilot 中的代理是一個自成一體的半自主或完全自主的計算實體，致力於達成特定目標。它以感知與反應環境、做出決策並產生達成目標的能力為定義。代理的設計會告訴代理如何達成目標，決定使用哪些能力，無論是大型語言模型 (大型語言模型) 、連網工具 (技能) ，或兩者兼具。代理的決策受其輸入與指令引導，可能導致代理使用預設邏輯，或提示大型語言模型（LLM）解讀並執行這些指令。

代理人會透過觸發器被啟動，觸發觸發器會產生一次代理執行，並執行每個步驟 (或任務) 直到達成結果。在代理執行過程中，根據指令，它決定是利用大型語言模型（LLM）還是連接工具來完成任務。

代理可以透過兩種選擇策略之一，與工具、超越大型語言模型的外部資源及代理指令互動：

靜態工具：一組固定的資源，供代理程式呼叫，依據代理定義，用於單一步驟或整個代理執行。當如此定義時，代理中的大型語言模型（LLM）無法決定呼叫定義外的任何工具。這能提升速度，並提升工具成果的相關性。一個應該調用預設來源的威脅情報代理，可以這樣設計。
動態工具：工具呼叫會在代理執行時根據上下文、推理或對代理的輸入選擇。提供給代理的工具可以在執行時引入。需要對代理運行中遇到的條件做出反應的代理，也可以這樣設計。例如，一個能豐富實體的代理人，可能會根據提供給代理人的實體類型而有所不同。

開發者與 Security Copilot 使用者可依代理目標，採用任一工具選擇方式設計代理。目標同時有助於判斷代理人的結果是否服務於個人、團隊或組織。當代理使用同一身份時，結果的範圍與身份的權限應該保持一致。

無論你是在建構簡單的警報分流代理，或是為複雜調查協調多代理系統，本文都提供你從工具選擇、清單設計到觸發設定與治理，運用 Security Copilot 代理框架所需的基礎知識。

指示

指令是給予代理人的指示，用以定義其目標、指導決策並詳細說明結果。例如，你可以告訴分流人員專注於高嚴重事件，或引導資料代理人只拉取符合特定規則的資訊。說明有助於客服人員保持準確與一致性。

工具

一個工具 (技能) 是指在代理指令和大型語言模型之外可存取的資源，Security Copilot代理可以調用這些資源來協助完成其結果。把工具想像成傳統程式語言中的一個函式。它有一個名稱、幾個參數，當被呼叫時，它會執行一個明確定義的任務並回傳結果。

使用者可以建立所需工具，Security Copilot 可呼叫這些工具來執行專門任務或與外部系統互動。

例如：

回答關於未曾見過實體的解決或聲譽問題，例如「誰註冊了」 www.contoso.com?'
回答任何針對特定客戶資料的問題，例如「事件 1234 影響哪些使用者？」
與外部系統互動，例如「重設帳戶密碼」。testaccount@contoso.com
從像 SharePoint 這樣的知識來源擷取客戶專屬知識。

插件

這是一組相關工具，使用者可在 Security Copilot 中啟用，當與創建新的提示、提示簿或代理功能相關時。對於代理來說，外掛擴充了代理能做的事，讓它能存取代理和大型語言模型以外的資源。舉例來說，有一個外掛使用 API 連接外部服務，例如聲譽查詢，該外掛的底層工具定義可能會回傳聲譽分數、相關的惡意軟體、威脅情報等。

工具格式

Security Copilot平台支援多種方式來撰寫與託管工具 (技能) 以滿足不同需求。你可以用任何支援的技能來打造代理人。支援的工具格式如下：

工具格式	最佳選擇	範例使用案例
API	整合外部或內部系統	自動化密碼重設、從 API 取得威脅情報、觸發修復工作流程
GPT 架構	提供底層大型語言模型中原生無法提供的自然語言處理定義。	領域特定定義，以獨特格式總結事件
KQL	查詢Microsoft資料來源 (Microsoft Defender，Microsoft Sentinel)	取得登入日誌，偵測異常
代理商	利用大型語言模型 (大型語言模型) 子工具協調多步驟工作流程	了解 URL 的託管狀況，串連多個調查工具。
MCP	由 MCP 伺服器公開的動態多工具整合;Security Copilot 在執行時發現工具。	透過 MCP 伺服器彙整威脅情報或協調多個工具的修復。

代理人定義

代理定義作為代理的藍圖，也是清單檔案的關鍵組成部分。它是清單中的頂層金鑰之一，規範代理的核心配置、能力與行為。它明確規定：

描述性/元資料細節 (例如：名稱、描述) 。
描述導致代理執行的觸發事件定義。
代理人用來完成工作所需的相關工具或工具參考。

作為 Security Copilot 的開發者，您所建立的代理定義可供分析師執行並查看結果。

代理實例

代理實例是在特定工作空間中部署的代理定義版本。每個例子：

維持自己的身份或憑證。
儲存特定實例的記憶與回饋。
多個租戶和工作空間可以擁有相同的代理定義的獨立實例。某個實例的設定變更或記憶體更新不會影響其他實例。

資訊清單

清單以結構化的 YAML 或 JSON 格式定義代理的定義、身份、工具及操作邏輯。類似於傳統軟體系統中的設定檔，清單規定：

代理人的獨特目的與任務
一般操作指引
決策邏輯
它必須動用的工具
執行時可能呼叫的其他代理

清單包含代理定義 (技能的元資料) 代理人可使用的技能、這些技能的分組方式，以及代理人可執行的動作。清單檔案會被打包並部署為 Security Copilot 平台上代理工作流程的一部分。 SOC 分析師透過此平台與代理互動，代理會根據清單配置與工具邏輯回應提示或事件。

注意事項

在範例中，列出 YAML 格式是因為人類閱讀更清楚，且可包含註解，但兩種格式都同樣有效。 JSON 格式與 YAML 格式相同，但改用 JSON 語法。

代理 YAML

這是一個範例 manifest.yaml 檔案的範例。


Descriptor:
  Name: Contoso.SecurityOperations.Samples-090925
  Description: DCA URL Geolocation Agent
  DisplayName: DCA URL Geolocation Agent

SkillGroups:
- Format: AGENT
  Skills:
  - Name: URL_Location_DCA_Agent_Entrypoint-090925
    Description: The entrypoint into the URL Location Agent
    Interfaces:
    - Agent
    Inputs:
    - Required: true
      Name: URL
      Description: A URL the agent should investigate
    Settings:
      Model: gpt-4.1
      Instructions: |
            <|im_start|>system
            You are an AI agent that helps a security analyst understand the hosting situation of a URL (the input).
            You'll do this by following a three-step process:
            1) Use ExtractHostname to find the hostname from the URL provided as input
            2) Use GetDnsResolutionsByIndicators to extract IP Addresses that the hostname has been observed resolving to. This may produce a list of IP Addresses.
            3) One-at-a time, use lookupIpAddressGeolocation to look up the geolocation of an IP address.

            Produce a simply formatted response telling the security analyst which locations that URL is being served from.  
            If you encounter an error share that.  
            Always return something the user knows that something happened.
            
            <|im_end|>
            <|im_start|>user
            {{URL}}
            <|im_end|>

    ChildSkills:
    - lookupIpAddressGeolocation
    - ExtractHostname_DCA-090925
    - GetDnsResolutionsByIndicators
- Format: GPT
  Skills:
  - Name: ExtractHostname_DCA-090925
    DisplayName: ExtractHostname_DCA-090925
    Description: ExtractHostname_DCA-090925
    Inputs:
    - Name: URL
      Description: A URL string
      Required: true
    Settings:
      ModelName: gpt-4.1
      Template: |-
        <|im_start|>system
        Return the hostname component of the URL provided as input.  For example:
        - If the input is 'https://www.mlb.com/', return 'www.mlb.com'
        - If the input is 'http://dev.mycompany.co.uk/sign-up/blah?a=12&b=12&c=32#23', return 'dev.mycompany.co.uk'
        - If the input is 'ftp:/x.espon.com', return 'x.espon.com'
        <|im_end|>
        <|im_start|>user
        {{URL}}
        <|im_end|>
- Format: KQL
  Skills:
    - Name: RecentUrlClicks_DCA-090925
      Description: Returns 10 recently clicked URLs
      Settings:
        Target: Defender
        Template: UrlClickEvents | sort by TimeGenerated desc | limit 10 | project Url

AgentDefinitions:
  - Name:  URLLocationAgent-090925
    DisplayName: URLLocationAgent
    Description: An agent to help an analyst understand URL hosting 
    Publisher: Contoso
    Product: SecurityOperations
    RequiredSkillsets:
      - Contoso.SecurityOperations.Samples-090925
      - ThreatIntelligence.DTI
      - DCA_SampleAPIPlugin
    AgentSingleInstanceConstraint: None
    Settings:
      - Name: LookbackWindowMinutes
        Label: Max Lookback Window in minutes
        Description: The maximum number of minutes to find clicked URLs
        HintText: You should probably enter 5
        SettingType: String
        Required: true
    Triggers:
      - Name: Default
        DefaultPeriodSeconds: 300
        FetchSkill: Contoso.SecurityOperations.Samples-090925.RecentUrlClicks_DCA-090925
        ProcessSkill: Contoso.SecurityOperations.Samples-090925.URL_Location_DCA_Agent_Entrypoint-090925

代理人會依循三個步驟來啟動兒童技能：

ExtractHostname：使用 GPT 工具 ExtractHostname_DCA-090925 解析主機名稱與網址。
GetDnsResolutionsByIndicators：使用 Microsoft 威脅情報 技能組來取得與主機名稱相關的 IP 位址。你必須在「管理來源 > 自訂」下啟用該外掛。確保 RequiredSkillsets: ThreatIntelligence.DTI 必須加入時不會被調用哪個 GetDnsResolutionsByIndicators 工具。
lookupIpAddressGeolocation：是 operationId OpenAPI 規範中的，API 外掛 DCA_SampleAPIPlugin 會引用該規範來查詢每個 IP 位址的地理位置資料。參考資料請參閱 Build API 範例。

觸發程序

觸發器是啟動客服人員工作流程的標誌。它可以手動啟動，也可以設定為排程運行。一旦觸發器啟動，代理人會依照計畫自動執行行動。

代理人依據結構化的行動計畫行動並執行該計畫。例如，釣魚分流代理可能會從其預先設定的能力集合中決定要調用哪些工具或其他代理。觸發器中定義的 FetchSkill 與 ProcessSkill 等工具，作為進入代理工作流程的入口，引導任務執行。

以下範例如下：

Triggers:
      - Name: Default
        DefaultPeriodSeconds: 300
        FetchSkill: Contoso.SecurityCopilot.Samples-090925_1b.RecentUrlClicks_DCA-090925_1b
        ProcessSkill: Contoso.SecurityCopilot.Samples-090925_1b.URL_Location_DCA_Agent_Entrypoint-090925_1b
        Settings:

1. 每 5 分鐘呼叫以 RecentUrlClicks_DCA-090925_1b 取得新資料。

2. 接著，對每個回傳的項目啟動 ProcessSkill URL_Location_DCA_Agent_Entrypoint-090925_1b 來對資料採取行動。

每個週期都是觸發執行，每次呼叫 ProcessSkill 都是觸發執行。這些技能呼叫會在與代理實例及觸發器相關聯的會話中執行，並使用代理的相關身份。

FetchSkill 與 ProcessSkill

FetchSkill 抓取技能

當觸發器在代理執行時被啟動，設定後的 FetchSkill 會收集資料。 ProcessSkill 定義了代理在執行過程中如何對這些資料採取行動。資料被擷取後，ProcessSkill 會接手，利用該資料作為輸入執行特定動作或分析。這兩個元件協同運作，以實現動態且資料驅動的工作流程。如果 FetchSkill 值被設定，觸發器會先啟動 FetchSkill。

重要事項

Fetch 和 ProcessSkills 必須依技能組命名。他們必須遵循格式 Skillset name.Skill name。

從 Triggers 的例子來看，是 Skill nameRecentUrlClicks_DCA。 Skillset name例如 Contoso.SecurityCopilot.Samples-090925_1b) 的 Descriptor.name (。所以完整合格的技能名稱是 Contoso.SecurityCopilot.Samples-090925_1b。RecentUrlClicks_DCA。

流程技能

若定義了 FetchSkill，則對每個輸出物件都會呼叫 ProcessSkill，並以輸出值作為 ProcessSkill 的輸入。如果沒有定義 FetchSkill，則會啟動 ProcessSkill。

{
    [
        {
            "Incident": 1,
            "name": "Item One",
            "created_at": "2024-02-17T12:34:56Z"
        },
        {
            "Incident": 2,
            "name": "Item Two",
            "created_at": "2024-02-17T12:35:30Z"
        },
        {
            "Incident": 3,
            "name": "Item Three",
            "created_at": "2024-02-17T12:36:10Z"
        }
    ]
}

在這個範例中，ProcessSkill 會被呼叫三次，輸入Incident為、 namecreated_at 和。

工作區

一個工作容器。代理在工作空間的情境中運作。 Workspace 提供存取、設定、消費及資料處理的控制單元。

記憶體

記憶讓代理人能在互動間保留上下文，進而提供更智慧且個人化的回應。透過儲存相關資訊，如過去的操作、使用者偏好或事件歷史，客服人員能持續提供連續性並隨時間改善決策。

Last updated on 2025-11-19

共用方式為