Ajouter plusieurs outils à votre agent

Importante

Certaines informations contenues dans cet article concernent le produit en préversion, qui peut être considérablement modifié avant sa publication commerciale. Microsoft n’offre aucune garantie, explicite ou implicite, concernant les informations fournies ici.

Cet exemple vous guide dans la création d’un agent par le biais d’un exemple YAML qui utilise des outils Microsoft globaux, GPT, API et outils KQL (compétences).

Le processus global est le suivant :

Étape 1 : Créer et charger l’agent YAML
Étape 2 : Activer ou désactiver l’agent dans Gérer les sources
Étape 3 : Configurer l’agent dans Security Copilot
Étape 4 : Exécuter l’agent

Répartition de l’appel d’outil (compétence)

Cette section vous aide à comprendre comment les outils YAML de l’agent (compétences) sont appelés et quels plug-ins doivent être inclus.

le DCA URL Geolocation 090925 Agent est conçu pour aider les analystes de sécurité à comprendre l’emplacement d’hébergement d’une URL donnée. Il suit un flux d’appel structuré défini dans le manifeste YAML à l’aide de plusieurs outils (compétences) dans les formats GPT et KQL.

Déclencher l’activation

L’agent est déclenché via le déclencheur par défaut toutes les 300 secondes.
Il appelle d’abord fetchSkill : Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925. La compétence KQL (Format: KQL) interroge les journaux Defender pour les URL récemment cliquées.
Ensuite, il appelle processSkill : Contoso.SecurityCopilot.Samples-090925.URL_Location_DCA_Agent_Entrypoint-090925. La compétence agent (Format:AGENT) examine l’emplacement d’hébergement de l’URL.

Lorsque vous exécutez l’agent, la compétence Fetch est appelée Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925

Point d’entrée de compétence de l’agent

La URL_Location_DC_Agent_Entrypoint-090925 compétence agent est définie sous et FORMAT:AGENT effectue les étapes suivantes :

Entrées : nécessite une seule entrée : URL (URL à examiner).
Instructions : 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. 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.

Étape 1 : Créer et charger l’agent YAML

L’agent YAML est défini comme suit :

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

Étape 2 : Activer ou désactiver l’agent dans Gérer les sources

Vérifiez si le YAML (plug-in) chargé est configuré ou activé dans Gérer les sources > personnalisées à partir de la barre d’invite.
Recherchez DCA URL Geolocation 090925 Agent, qui est le Descriptor.DisplayName.

Remarque

En général, il peut y avoir des plug-ins qui nécessitent des configurations définies lors de la configuration de l’agent.

Étape 3 : Configurer l’agent dans Security Copilot

Accédez à Accueil > Agents.
Recherchez l’agent URLLocationAgent-090925 dans la bibliothèque d’agents, qui est le AgentDefinitions.DisplayName à partir de YAML. Actualisez l’écran dans la bibliothèque d’agents si la recherche n’affiche pas l’agent.
Dans le carte agent, sélectionnez Afficher les détails pour configurer l’agent.

Vous pouvez voir les plug-ins activés dans la section Plug-ins.
Fournissez les paramètres d’entrée requis pour configurer l’agent.
Sélectionnez Se connecter pour vous authentifier.

Étape 4 : Exécuter l’agent

Sélectionnez Terminer pour exécuter l’agent. L’écran d’exécution de l’agent s’affiche.
Sélectionnez Exécuter une seule fois sans déclencheur pour exécuter l’agent.

Les résultats de l’exécution de l’agent sont tels qu’affichés.
Sélectionnez Afficher l’activité pour afficher chaque résultat de l’agent.

Last updated on 2025-11-13

Partager via