Добавление нескольких инструментов в агент

Важно!

Некоторые сведения относятся к предварительно выпущенному продукту, который может быть существенно изменен перед выпуском. Корпорация Майкрософт не дает никаких гарантий, явных или подразумеваемых, относительно предоставленных здесь сведений.

В этом примере описывается создание агента с помощью примера YAML, использующего глобальные инструменты Майкрософт, GPT, API и средства KQL.

Общий процесс выглядит следующим образом:

Шаг 1. Создание и отправка агента YAML
Шаг 2. Включение или переключение агента в разделе Управление источниками
Шаг 3. Настройка агента в Security Copilot
Шаг 4. Запуск агента

Разбивка вызова средства (навыка)

Этот раздел поможет вам понять, как вызываются средства (навыки) YAML агента и какие подключаемые модули необходимо включить.

Предназначен DCA URL Geolocation 090925 Agent для того, чтобы помочь аналитикам безопасности понять расположение размещения заданного URL-адреса. Он следует структурированный поток вызова, определенный в манифесте YAML с использованием нескольких инструментов (навыков) в форматах GPT и KQL.

Активация триггера

Агент активируется через триггер по умолчанию каждые 300 секунд.
Сначала он вызывает FetchSkill: Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925. Навык KQL (Format: KQL) запрашивает журналы Defender для недавно выбранных URL-адресов.
Затем вызывается ProcessSkill: Contoso.SecurityCopilot.Samples-090925.URL_Location_DCA_Agent_Entrypoint-090925. Навык агента (Format:AGENT) исследует расположение размещения URL-адреса.

При запуске агента вызывается навык получения. Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925

Точка входа в навыки агента

Навык URL_Location_DC_Agent_Entrypoint-090925 агента определяется в и FORMAT:AGENT выполняет следующие действия:

Входные данные: требуется один URL-адрес (URL-адрес для исследования).
Инструкции. Агент выполняет трехэтапный процесс вызова дочерних навыков:
- ExtractHostname: использует средство ExtractHostname_DCA-090925 GPT для синтаксического анализа имени узла из URL-адреса.
- GetDnsResolutionsByIndicators: использует набор навыков Microsoft Threat Intelligence для получения IP-адресов, связанных с именем узла. Убедитесь, что RequiredSkillsets: ThreatIntelligence.DTI необходимо добавить, без какого GetDnsResolutionsByIndicators средства не вызывается.
- lookupIpAddressGeolocation: объект operationId в спецификации OpenAPI, на который ссылается подключаемый модуль DCA_SampleAPIPlugin API для поиска данных о географическом расположении для каждого IP-адреса. Дополнительные сведения см. в разделе Пример API сборки.

Шаг 1. Создание и отправка YAML агента

Агент YAML определяется следующим образом:

Descriptor:
  Name: Contoso.SecurityCopilot.Samples-090925_1b
  Description: DCA URL Geolocation 090925 Agent_1b
  DisplayName: DCA URL Geolocation 090925 Agent_1b

SkillGroups:
- Format: AGENT
  Skills:
  - Name: URL_Location_DCA_Agent_Entrypoint-090925_1b
    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_1b
    - GetDnsResolutionsByIndicators
- Format: GPT
  Skills:
  - Name: ExtractHostname_DCA-090925_1b
    DisplayName: ExtractHostname_DCA-090925_1b
    Description: ExtractHostname_DCA-090925_1b
    Inputs:
    - Name: URL
      Description: A URL string
    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_1b
      Description: Returns recently clicked URLs
      Inputs:
        - Name: LookbackMinutes
          Description: Number of minutes to lookback
          Required: false
      Settings:
        Target: Defender
        Template: UrlClickEvents | sort by TimeGenerated desc | limit 10 | project Url

AgentDefinitions:
  - Name:  URLLocationAgent-090925_1b
    DisplayName: URLLocationAgent 090925_1b
    Description: An agent to help an analyst understand URL hosting 
    Publisher: Contoso
    Product: Security Copilot
    RequiredSkillsets:
      - SecurityCopilot
      - 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.SecurityCopilot.Samples-090925_1b.RecentUrlClicks_DCA-090925_1b
        ProcessSkill: Contoso.SecurityCopilot.Samples-090925_1b.URL_Location_DCA_Agent_Entrypoint-090925_1b
        Settings:
  
Settings:
    HistoryPassDownMode: None
    IncludeSessionHistory: false
WorkspaceId: SecurityCopilot_Workspace

Шаг 2. Включение или переключение агента в разделе Управление источниками

Проверьте, настроен ли отправленный YAML (подключаемый модуль) или переключен ли он в разделе Управление источниками > Пользовательский с панели запросов.
Выполните поиск по запросу DCA URL Geolocation 090925 Agent, который является .Descriptor.DisplayName

Примечание.

Как правило, могут быть подключаемые модули, для которых при настройке агента необходимо настроить некоторые конфигурации.

Шаг 3. Настройка агента в Security Copilot

Перейдите в раздел Главная > агенты.
Найдите агент URLLocationAgent-090925 в библиотеке агентов, которая является AgentDefinitions.DisplayName из YAML. Обновите экран в библиотеке агентов, если при поиске агент не отображается.
На карта агента выберите Просмотреть сведения, чтобы настроить агент.

Подключаемые модули включены в разделе Подключаемые модули.
Укажите входные параметры, необходимые для настройки агента.
Выберите Signin (Вход), чтобы пройти проверку подлинности.

Шаг 4. Запуск агента

Нажмите кнопку Готово , чтобы запустить агент. Откроется экран запуска агента.
Выберите Запустить один раз без триггера , чтобы запустить агент.

Отображаются результаты выполнения агента.
Выберите Просмотреть действие , чтобы просмотреть результат каждого агента.

Last updated on 2025-11-13