Agent-Manifest

Die Entwicklung eines Security Copilot-Agents und seiner Tools (Skills) erfordert eine Manifestdatei im YAML- oder JSON-Format (z. B. manifest.yaml). Diese Datei definiert Metadaten zum Toolsatz (Plug-In) und gibt an, wie die einzelnen Tools aufgerufen werden sollen.

Ein Agentmanifest enthält drei Schlüssel der obersten Ebene, die wie folgt aussehen:

• Beschreibung
• AgentDefinitions
• SkillGroups

Jeder Schlüssel enthält einen eigenen Satz von Unterschlüssel-Wert-Paaren, von denen einige je nach Toolformat erforderlich/optional sind.

In diesem Referenzhandbuch werden die Manifestfelder beschrieben, die zum Erstellen Security Copilot-Agents verfügbar sind.

Agent-YAML

Dies ist ein Beispiel für eine Beispieldatei 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

Der Agent folgt einem dreistufigen Prozess, um die untergeordneten Skills aufzurufen:

• ExtractHostname: Verwendet das GPT-Tool ExtractHostname_DCA-090925 , um den Hostnamen aus der URL zu analysieren.

• GetDnsResolutionsByIndicators: Verwendet den Microsoft Threat Intelligence-Skillsatz , um die dem Hostnamen zugeordneten IP-Adressen abzurufen. Sie müssen das Plug-In unter Quellen > verwalten benutzerdefiniert aktivieren. Stellen Sie sicher, dass RequiredSkillsets: ThreatIntelligence.DTI hinzugefügt werden muss, ohne welches GetDnsResolutionsByIndicators Tool nicht aufgerufen wird.

• lookupIpAddressGeolocation: Ist die operationId in der OpenAPI-Spezifikation, auf die im API-Plug-In DCA_SampleAPIPlugin verwiesen wird, um Geolocationdaten für jede IP-Adresse nachzuschlagen. Eine Referenz finden Sie unter Build-API-Beispiel.

Beispiele

Sehen Sie sich die vollständige Liste der Samples-Auflistung an.

Das Agent-Beispiel für interaktive Agents finden Sie unter Interaktive Agents.

YAML-Manifestsyntax

Im Folgenden sind die Agent-Manifestparameter (Felder) für die drei Schlüssel der obersten Ebene und ihre Unterschlüssel aufgeführt:

Zusammenfassung des Deskriptorfelds

(* impliziert empfohlen, aber nicht erforderlich)

AgentDefinitions-Feldzusammenfassung

SkillGroups-Feldzusammenfassung

Besteht aus einer Liste von Qualifikationsgruppen, einschließlich Format, Settingsund Skills.

Format (SkillGroups-Feld)

Optionen für Format-Feld:

API
GPT
AGENT
KQL
LogicApp

Fertigkeiten (SkillGroups-Feld)

Objektstruktur für Skills Feld:

Einstellungen (SkillGroups-Feld)

Die Objektstruktur für das Settings Feld sieht für die unterstützten Formate wie folgt aus. Beispiele für Skills (Tool) finden Sie unter Toolbeispiele.

API

GPT

AGENT

KQL

LogicApp

Zielspezifische Einstellungen

• Microsoft Defender

  Keine zusätzlichen Einstellungen.

• Microsoft Sentinel

  Diese Einstellungen gelten für das KQL-Tool, bei dem das Ziel Microsoft Sentinel ist.

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

  Diese Einstellungen gelten für das KQL-Tool, bei dem das Ziel Kusto ist.

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

Authentifizierung

Security Copilot unterstützt mehrere Schemas für die Authentifizierung von Tools. Weitere Informationen finden Sie unter Authentifizierungstypen. Beispiele zu den verschiedenen Authentifizierungstypen finden Sie unter API-Plug-In.

• +Dieses Feld wird verwendet, um die zwei verschiedenen Uploadtypen anzugeben, die in Security Copilot unterstützt werden.

• * Diese stellen Authentifizierungsmethoden dar, die über das hinausgehen, was ursprünglich von OpenAI unterstützt wurde.

Authentifizierungstypen

Die Tabelle enthält die unterstützten Einstellungen für jeden Authentifizierungstyp.