Manifeste de l’agent

Le développement d’un agent Security Copilot et de ses outils (compétences) nécessite un fichier manifeste au format YAML ou JSON (par exemple, manifest.yaml). Ce fichier définit des métadonnées sur l’ensemble d’outils (plug-in) et spécifie comment chaque outil doit être appelé.

Un manifeste d’agent comprend trois clés de niveau supérieur qui sont les suivantes :

• Descripteur
• AgentDefinitions
• SkillGroups

Chaque clé contient son propre ensemble de paires sous-clé/valeur, dont certaines sont des champs obligatoires/facultatifs en fonction du format de l’outil.

Ce guide de référence décrit les champs de manifeste disponibles pour la création d’agents Security Copilot.

Agent YAML

Il s’agit d’un manifest.yaml exemple de fichier.

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

L’agent suit un processus en trois étapes pour appeler les compétences enfants :

• ExtractHostname: utilise l’outil ExtractHostname_DCA-090925 GPT pour analyser le nom d’hôte à partir de l’URL.

• GetDnsResolutionsByIndicators: utilise l’ensemble de compétences Microsoft Threat Intelligence pour récupérer les adresses IP associées au nom d’hôte. Vous devez activer le plug-in sous Gérer les sources > personnalisées. Vérifiez que RequiredSkillsets: ThreatIntelligence.DTI doit être ajouté sans quel GetDnsResolutionsByIndicators outil n’est pas appelé.

• lookupIpAddressGeolocation: dans la spécification OpenAPI, qui est référencée dans le plug-in DCA_SampleAPIPlugin d’API pour rechercher des operationId données de géolocalisation pour chaque adresse IP. Pour plus d’informations de référence, consultez Exemple d’API de build.

Échantillons

Consultez la liste complète de la collection Samples.

Pour l’exemple Agent sur l’agent interactif, consultez Agents interactifs.

Syntaxe YAML du manifeste

Voici les paramètres de manifeste de l’agent (champs) pour les trois clés de niveau supérieur et ses sous-clés :

Résumé des champs du descripteur

(* implique recommandé, mais non obligatoire)

Résumé du champ AgentDefinitions

Résumé du champ SkillGroups

Il s'agit d'une liste de groupes de compétences comprenant Format, Settings, et Skills.

Format (champ SkillGroups)

Options pour le Format champ :

API
GPT
AGENT
KQL
LogicApp

Compétences (champ SkillGroups)

Structure d’objet pour Skills le champ :

Paramètres (champ SkillGroups)

La structure d’objet du Settings champ est la suivante pour les formats pris en charge. Pour obtenir des exemples de compétence (outil), consultez Exemples d’outils.

API

GPT

AGENT

KQL

LogicApp

Paramètres spécifiques de la cible

• Microsoft Defender

  Aucun paramètre supplémentaire.

• Microsoft Sentinel

  Ces paramètres sont valides pour l’outil KQL où la cible est 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

  Ces paramètres sont valides pour l’outil KQL où la cible est Kusto.

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

Authentification

Security Copilot prend en charge plusieurs schémas d’authentification des outils. Consultez Types d’authentification. Pour obtenir des exemples sur les différents types d’authentification, consultez Plug-in d’API.

• +Ce champ est utilisé pour indiquer les deux types de chargement pris en charge dans Security Copilot.

• * Celles-ci représentent des méthodes d’authentification qui vont au-delà de ce qui était initialement pris en charge par OpenAI.

Types d’authentification

Le tableau présente les paramètres pris en charge pour chaque type d’authentification.