Манифест агента

Важно!

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

Для разработки агента 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: использует средство ExtractHostname_DCA-090925 GPT для синтаксического анализа имени узла из URL-адреса.

• GetDnsResolutionsByIndicators: использует набор навыков Microsoft Threat Intelligence для получения IP-адресов, связанных с именем узла. Необходимо включить подключаемый модуль в разделе Управление источниками > Пользовательский. Убедитесь, что RequiredSkillsets: ThreatIntelligence.DTI необходимо добавить, без какого GetDnsResolutionsByIndicators средства не вызывается.

• lookupIpAddressGeolocation: объект operationId в спецификации OpenAPI, на который ссылается подключаемый модуль DCA_SampleAPIPlugin API для поиска данных о географическом расположении для каждого IP-адреса. Дополнительные сведения см. в разделе Пример API сборки.

Примеры

См. полный список примеров коллекции.

Пример агента для интерактивного агента см. в разделе Интерактивные агенты.

Синтаксис YAML манифеста

Ниже приведены параметры (поля) манифеста агента для трех ключей верхнего уровня и его подразделов.

Сводка по полю дескриптора

Поле	Тип	Описание	Ограничения	Обязательный
Name	string	Внутреннее имя набора навыков. Должно быть уникальным именем в рабочей области.	Не разрешает / , \ ? # @; не может содержать пробелы.	Да
DisplayName	string	Понятное имя набора навыков.		Нет*
Description	string	Понятное описание набора навыков.	Не может быть пустым или пустым.	Да
Authorization	объект	Задайте значения авторизации. Дополнительные сведения см. в разделе Проверка подлинности .		Нет; Требуется для средства API и SupportedAuthTypes не равен None.
SupportedAuthTypes	массив	Список поддерживаемых типов проверки подлинности для набора навыков. Дополнительные сведения см. в разделе Проверка подлинности .		Нет; Требуется для средства API

(* подразумевает рекомендуемые, но не обязательные)

Сводка по полю AgentDefinitions

Поле	Тип	Описание	Ограничения	Обязательный
Name	string	Имя, используемое для установки агента;	Не может содержать пробелы, точку (.) и не может быть пустой или пустой.	Да
DisplayName	string	Понятное имя для отображения пользовательского интерфейса.		Да
Description	string	Удобочитаемая сводка о назначении и функциональности агента.		Да
Publisher	string	Имя издателя агента.		Да
Product	string	Исходный продукт, связанный с агентом. Используется для фильтрации при перечислении определений агентов.		Да
RequiredSkillsets	string	Наборы навыков, необходимые для работы агента.		Да
AgentSingleInstanceConstraint	string	Определяет, где можно развернуть агент. Можно задать значение None, Workspaceили Tenant. - None: нет ограничений. - Workspace: один экземпляр на рабочую область. - Tenant: один экземпляр на клиент.		Нет
Settings	объект	Применяется только к вызову FetchSkill.		Нет
Triggers	объект	Определяет, как и когда активируется агент. Требуется по крайней мере один триггер. Name: описательное имя триггера. DefaultPeriodSeconds: интервал в секундах для запланированного выполнения. Триггеры не предотвращают одновременные выполнения. Чтобы отключить запланированное выполнение, задайте для этого значения значение 0. FetchSkill: если задано значение , триггер сначала вызывает этот навык (инструмент). Триггер ожидает массив объектов. Для каждого объекта он вызывает ProcessSkill , используя значения объекта в качестве входных данных для ProcessSkill. Распространенным шаблоном будет listAlerts FetchSkill и InvestigateAlertAgent ProcessSkill. Дополнительные сведения об триггере см. в разделе Компоненты агента.	Name: не может содержать пробелы	Да; Name и ProcessSkill.
PromptSkill	объект	Включите взаимодействие или взаимодействие с агентом в чате.		Да; Применимо только для интерактивных агентов.

Сводка по полю SkillGroups

Состоит из списка групп навыков, включая Format, Settings и Skills.

Поле	Тип	Описание	Ограничения	Обязательный
Format	string	Доступные параметры см. в разделе Формат.		Да
Skills	объект	См. раздел Навыки для получения сведений о структуре объекта.		Да; для форматов: GPT, API, KQL, AGENT
Settings	объект	Структуру объекта см. в разделе Параметры.		Да; для форматов: API, GPT, KQL, AGENT

Формат (поле SkillGroups)

Параметры поля Format:

API
GPT
AGENT
KQL
LogicApp

Навыки (поле SkillGroups)

Структура объекта для Skills поля:

Поле	Тип	Описание	Ограничения	Обязательный
Name	string	Внутреннее имя этого средства (навык)	Не может содержать пробелы и точку(.)	Да
DisplayName	string	Понятное имя для этого средства.		Рекомендуемый
Description	string	Понятное описание для этого средства	Не может быть пустым или пустым.	Рекомендуемый
Inputs	объект	Список имен, описаний и обязательных или необязательных объектов для ввода пользователем средства.		Нет
Settings	объект	Настраиваемые параметры, основанные на формате навыка.		Да
ChildSkills	массив строк	Список имен инструментов, от которые зависит агент или вызывает во время выполнения. Средства выполняют определенные задачи и вызываются агентом для выполнения своих целей. Позволяет создавать цепочку или состав нескольких средств для создания более сложного поведения агента.		Нет; Однако применимо и требуется только для FORMAT: AGENT навыка.
Interfaces	объект	При создании интерактивного агента задайте значение InteractiveAgent .		Да
SuggestedPrompts	объект	Prompt: фактический запрос для отображения пользователю (если начальный запрос) или используйте в качестве шаблона для создания предлагаемых запросов. Title: заголовок запроса. Personas: тип persona, с которого выравнивается запрос. IsStarterAgent: для начального запроса задайте значение true. Рекомендация. Задайте для начального и рекомендуемого подсказок максимальное количество предложений в двух предложениях.		Да; Применимо только для интерактивных агентов. Title и Personas (требуется только для начальных запросов).

Параметры (поле SkillGroups)

Структура объекта для Settings поля выглядит следующим образом для поддерживаемых форматов. Примеры навыков (инструментов) см. в разделе Примеры инструментов.

API

Имя параметра	Тип	Описание	Ограничения	Обязательный
OpenApiSpecUrl	string	URL-адрес общедоступной спецификации OpenAPI.		Да
EndpointUrl	string	URL-адрес общедоступной конечной точки.		Нет; Укажите, только если вы не хотите использовать сервер API, указанный в спецификации OpenAPI.
EndpointUrlSettingName	string	Настраиваемый параметр для запроса URL-адреса общедоступной конечной точки во время настройки подключаемого модуля.		Нет; Укажите, только если нужно настроить конечную точку API.
EnableSkillContextApi	логический	Установите этот параметр, только если средствам API требуется доступ к API SkillContext.		Нет

GPT

Имя параметра	Тип	Описание	Ограничения	Обязательный
ModelName	string	Выбирает модель GPT для использования.	Должен быть gpt-4.1	Да
Template	string	Шаблон запроса GPT.	Поддерживает до 80 000 символов	Да

АГЕНТ

Имя параметра	Тип	Описание	Ограничения	Обязательный
Instructions	string	Руководство или четкие указания, определяющие поведение и миссию агента. Руководство используется для управления ответами агента и обеспечения их соответствия предполагаемому варианту использования.	Обычно написан на естественном языке и включает в себя форматирование, например markdown или комментарии.	Да

KQL

Имя параметра	Тип	Описание	Ограничения	Обязательный
Target	string	Выберите систему или платформу, на которой выполняется средство. См. раздел Целевые параметры.		Да
Template	string	Шаблон запроса KQL.	Поддерживает до 80 000 символов.	Да, если TemplateUrl параметр не указан.
TemplateUrl	string	Общедоступный URL-адрес для скачивания шаблона запроса KQL (до 80 000 символов).		Да. Укажите либо один TemplatUrl из этих вариантов, Template но не оба.
PackageUrl	string	Общедоступный URL-адрес ZIP-файла с шаблоном запроса KQL. Примечание. Указывается на уровне SkillGroup.		Да, если Template или TemplateUrl не указаны.
TemplateFile	string	Относительный путь к шаблону запроса KQL (до 80 000 символов) в PackageUrl ZIP-файле.		Да, если PackageUrl задан параметр .

LogicApp

Имя параметра	Тип	Описание	Обязательный
SubscriptionId	string	Microsoft Azure идентификатор подписки из Logic Apps. Подписка должна находиться в том же клиенте, что и клиент пользователя Security Copilot.	Да
ResourceGroup	string	Microsoft Azure группу ресурсов из приложения логики, где создается ресурс.	Да
WorkflowName	string	Имя ресурса приложения логики.	Да
TriggerName	string	Имя триггера, созданного в Logic Apps.	Да

Параметры целевого объекта

• Microsoft Defender

  Никаких дополнительных параметров.

• Microsoft Sentinel

  Эти параметры допустимы для средства KQL, где целевой объект Microsoft Sentinel.

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

  Эти параметры допустимы для средства KQL, где целевой объект — Kusto.

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

Проверка подлинности

Security Copilot поддерживает несколько схем проверки подлинности средств. См . раздел Типы проверки подлинности. Примеры различных типов проверки подлинности см. в разделе Подключаемый модуль API.

Схема	Описание	Поддержка манифеста Copilot	Поддержка OpenAI +
None	Без проверки подлинности	Да	Да
Basic	Обычная проверка подлинности	Да	Нет
ApiKey	Проверка подлинности на основе ApiKey. ApiKey передается в пользовательском заголовке или параметре запроса.	Да	Да*
ServiceHttp	Проверка подлинности на основе предоставленного маркера.	Да	Да
OAuthAuthorizationCodeFlow	Поток кода авторизации OAuth 2.0 — это более безопасный и сложный метод проверки подлинности, используемый для предоставления доступа к сторонним приложениям без совместного использования учетных данных пользователя.	Да	Да
OAuthClientCredentialsFlow	Аналогично обычной проверке подлинности, но используется для обмена данными между серверами или при доступе к общедоступным данным, для которых не требуются разрешения пользователя.	Да	Нет
OAuthPasswordGrantFlow	Устаревший способ обмена учетными данными пользователя на маркер доступа с помощью типа предоставления пароля OAuth 2.0. Больше не рекомендуется.	Да	Нет
AAD	доступ только к приложению Microsoft Entra.	Да	Да*
AADDelegated	Доступ только для пользователей и Microsoft Entra приложений.	Да	Да*

• +Это поле используется для указания двух разных типов отправки, поддерживаемых в Security Copilot.

• * Они представляют собой методы проверки подлинности, которые выходят за рамки первоначально поддерживаемых OpenAI.

Типы проверки подлинности

В таблице показаны поддерживаемые параметры для каждого типа проверки подлинности.

Тип проверки подлинности	Setting	Описание
AAD или AADDelegated	EntraScopes	Разделенный запятыми список областей Microsoft Entra для запроса.
Basic или OAuthPasswordGrantFlow	Username	Имя пользователя, используемое для обычной проверки подлинности.
	Password	Пароль, используемый для обычной проверки подлинности.
ApiKey	Key	Имя параметра заголовка или запроса. Значение по умолчанию — Authorization, но может быть пользовательским значением. Например, X-ApiKey.
	AuthScheme	Имя схемы проверки подлинности, которая добавляется к значению при использовании в заголовке. Допустимыми параметрами являются пустая строка, носитель или базовый.
	Location	Расположение ключа API, заголовка или QueryParams. Значение по умолчанию — Заголовок.
	Value	Используемый ключ или маркер.
ServiceHttp	AccessToken	Используемый ключ или маркер. Bearer AuthScheme добавляется к маркеру в заголовке запроса авторизации.
OAuthAuthorizationCodeFlowили OAuthClientCredentialsFlowOAuthPasswordGrantFlow	TokenEndpoint	Конечная точка для запроса маркера.
	Scopes	Необязательный список областей, разделенных запятыми.
	ClientId	Идентификатор клиента, используемый при запросе маркера. Необязательный для OAuthPasswordGrantFlow.
	ClientSecret	Секрет клиента, используемый при запросе маркера. Необязательный для OAuthPasswordGrantFlow.
	AuthorizationContentType	Тип контента, используемый при отправке запроса маркера. Значение по умолчанию — application/x-www-form-urlencoded.
OAuthAuthorizationCodeFlow	AuthorizationEndpoint	Конечная точка для запроса кода авторизации.