代理组件

重要

本文中的某些信息与预发行的产品有关，该产品在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。

本文提供定义自定义Security Copilot代理工作方式的关键组件的概念性概述，帮助你了解其结构、行为和作逻辑。

代理

Security Copilot 中的代理是一个自包含半或完全自治的计算实体，用于实现特定目标。它的定义是能够感知和应对其环境、做出决策和产生结果以实现其目标。代理的设计通过决定使用大型语言模型 (LLM) 、连接工具 (技能) 或两者兼有的功能，告知代理如何实现其目标。代理的决策由其输入和指令指导，这可能导致代理使用预定义逻辑，或提示 LLM 解释和处理这些指令。

代理通过触发器激活，该触发器创建代理运行，并在 (或任务) 执行每个步骤，直到实现结果。在整个代理运行过程中，根据说明，它会决定利用 LLM 还是连接工具完成任务。

代理可以使用以下两种选择策略之一与 LLM 以外的工具、外部资源和代理指令进行交互：

静态工具：一组固定的资源，可供代理调用，如代理定义中所述，用于单个步骤或整个代理运行。以这种方式定义时，代理中的 LLM 无法决定调用所定义内容以外的任何工具。这可以提高速度和工具结果的相关性。可以通过这种方式设计应调用预定义源的威胁情报代理。
动态工具：在代理运行期间，根据对代理的上下文、推理或输入选择工具调用。可在运行时引入可用于代理的工具。需要对代理运行中遇到的条件作出反应的代理可以采用这种方式进行设计。例如，扩充实体的代理可以根据作为代理输入提供的实体类型以不同的方式运行。

开发人员和Security Copilot用户可以根据代理的目标使用任一工具选择方法来设计代理。目标还有助于告知代理的结果是否为个人、团队或组织服务。当代理使用标识运行时，结果的范围和标识的权限应保持一致。

无论是构建简单的警报会审代理，还是为复杂的调查协调多代理系统，本文都提供了使用Security Copilot代理框架所需的基础知识，从工具选择和清单设计到触发配置和治理。

说明

指令是给代理的指示，用于定义其目标、告知其决策并详细说明其结果。例如，可以告知会审代理专注于高严重性事件，或引导数据代理仅拉取遵循特定规则的信息。说明可帮助代理保持准确和一致。

工具

(技能) 的工具是在代理说明和 LLM 之外访问的资源，Security Copilot代理可以调用这些资源来帮助其完成其结果。将工具视为传统编程语言中的函数。它有一个名称、几个参数，当调用时，它会执行一个定义明确的任务并返回一个结果。

用户可以创建所需的工具，Security Copilot可以调用这些工具来执行专用任务或与外部系统交互。

例如：

回答有关以前未见过的实体的解决或信誉问题，例如“谁注册了” www.contoso.com?'
回答有关任何特定于客户的数据的问题，例如“事件 1234 影响哪些用户？”
与外部系统交互，例如“重置”testaccount@contoso.com的帐户密码。
从知识源（如 SharePoint）检索客户特定知识。

插件

与创建新的提示、提示簿或代理功能相关时，用户可以在Security Copilot中启用相关工具的集合。对于代理，插件通过授予代理访问代理和 LLM 外部资源的权限来扩展代理可以执行的作。例如，使用 API 连接到外部服务（如信誉查找）的插件，其中插件的基础工具定义可以返回信誉分数、相关恶意软件、威胁情报等。

工具格式

Security Copilot平台支持多种方法来创作和托管工具， (技能) 以满足各种需求。可以使用任何受支持的技能生成代理。支持的工具格式如下：

工具格式	最适合	示例用例
API	集成外部或内部系统	自动重置密码，从 API 提取威胁情报，触发修正工作流
GPT	提供基础 LLM 中本身不可用的自然语言处理定义。	特定于域的定义，以唯一格式汇总事件
KQL	查询Microsoft数据源 (Microsoft Defender，Microsoft Sentinel)	检索登录日志，检测异常
代理	使用大型语言模型 (LLM) 和子工具协调多步骤工作流	了解 URL 的托管情况，链接多个工具以供调查。
MCP	由 MCP 服务器公开的动态多工具集成;安全警察在运行时发现工具。	通过 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 分析 URL 中的主机名。
GetDnsResolutionsByIndicators：使用 Microsoft威胁情报 技能集检索与主机名关联的 IP 地址。必须在“管理源 > ”“自定义”下启用插件。确保 RequiredSkillsets: ThreatIntelligence.DTI 必须添加，而不调用哪个 GetDnsResolutionsByIndicators 工具。
lookupIpAddressGeolocation：OpenAPI operationId 规范中的，在 API 插件 DCA_SampleAPIPlugin 中引用它来查找每个 IP 地址的地理位置数据。有关参考，请参阅生成 API 示例。

Trigger

触发器是启动代理工作流的功能。它可以手动启动，也可以设置为按计划运行。激活触发器后，代理将遵循其计划并自动执行作。

代理基于结构化的行动计划进行作，并执行该计划。例如，网络钓鱼会审代理可以确定要从其预配置功能集调用哪些工具或其他代理。触发器中定义的 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。

重要

提取和 ProcessSkills 必须由技能组命名空间。它们必须遵循格式 Skillset name.Skill name。

在触发器的示例中， Skill name 为 RecentUrlClicks_DCA。 Skillset name是 Descriptor.name (，例如 Contoso.SecurityCopilot.Samples-090925_1b) 。因此，完全限定的技能名称为 Contoso.SecurityCopilot.Samples-090925_1b。RecentUrlClicks_DCA。

ProcessSkill

如果定义了 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"
        }
    ]
}

在此示例中，使用、 name和 created_at 作为输入调用 ProcessSkill 三次Incident。

工作区

用于工作的容器。代理在工作区的上下文中运行。工作区为访问、配置、使用和数据处理提供一个控制单元。

内存

内存允许代理跨交互保留上下文，从而实现更智能和个性化的响应。通过存储相关信息（例如过去的作、用户首选项或事件历史记录），代理可以随着时间的推移提供连续性并改进决策。

Last updated on 2025-11-11

通过