代理清单

开发Security Copilot代理及其工具 (技能) 需要 YAML 或 JSON 格式的清单文件， (例如 manifest.yaml) 。 此文件定义有关工具集 (插件) 的元数据，并指定应如何调用每个工具。

代理清单包括三个顶级密钥，如下所示：

• 描述符
• AgentDefinitions
• SkillGroups

每个键都包含自己的子项/值对集，其中一些是必需/可选字段，具体取决于工具格式。

此参考指南概述了可用于创作Security Copilot代理的清单字段。

代理 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 示例。

示例

请参阅 示例集合的完整列表。

有关交互式代理上的代理示例，请参阅 交互式代理。

清单 YAML 语法

下面是三个顶级键及其子项的代理清单参数 (字段) ：

描述符字段摘要

(* 表示建议但不需要)

AgentDefinitions 字段摘要

SkillGroups 字段摘要

由技能组的列表组成，包括 Format、Settings 和 Skills。

格式 (SkillGroups 字段)

字段 Format 的选项:

API
GPT
AGENT
KQL
LogicApp

技能 (SkillGroups 字段)

字段的对象 Skills 结构：

设置 (SkillGroups 字段)

支持的“格式”字段 Settings 的对象结构如下所示。 有关技能 (工具) 示例，请参阅 工具示例。

API

GPT

代理

KQL

LogicApp

特定于目标的设置

• Microsoft Defender

  无其他设置。

• Microsoft Sentinel

  这些设置对目标Microsoft Sentinel的 KQL 工具有效。

Settings:
  Target: Sentinel
  # The ID of the AAD Organization that the Sentinel workspace is in.
  TenantId: '{{TenantId}}'
  # The id of the Azure Subscription that the Sentinel workspace is in.
  SubscriptionId: '{{SubscriptionId}}'
  # The name of the Resource Group that the Sentinel workspace is in.
  ResourceGroupName: '{{ResourceGroupName}}'
  # The name of the Sentinel workspace.
  WorkspaceName: '{{WorkspaceName}}'

• Kusto

  这些设置对目标为 Kusto 的 KQL 工具有效。

Settings:
  # The Kusto cluster URL. 
  Cluster: 
  # The Kusto database name.
  Database: 

身份验证

Security Copilot支持多种用于对工具进行身份验证的方案。 请参阅 身份验证类型。 有关不同身份验证类型的示例，请参阅 API 插件。

• +此字段用于指示Security Copilot中支持的两种不同类型的上传。

• * 这些表示的身份验证方法超出了 OpenAI 最初支持的范围。

身份验证类型

下表显示了每种身份验证类型的支持设置。