エージェントに複数のツールを追加する

重要

この記事の一部の情報は、市販される前に大幅に変更される可能性があるプレリリース製品に関するものです。 Microsoft は、ここに記載された情報に関して、明示または黙示を問わず、いかなる保証も行いません。

この例では、グローバル Microsoft ツール、GPT、API、KQL ツール (スキル) を使用するサンプル YAML を使用してエージェントを作成する方法について説明します。

全体的なプロセスは次のとおりです。

手順 1: エージェント YAML を作成してアップロードする
手順 2: ソースの管理でエージェントを有効または切り替える
手順 3: Security Copilotでエージェントを設定する
手順 4: エージェントを実行する

ツール (スキル) 呼び出しの内訳

このセクションでは、エージェント YAML ツール (スキル) の呼び出し方法と、どのプラグインを含める必要があるかを理解するのに役立ちます。

DCA URL Geolocation 090925 Agentは、セキュリティアナリストが特定の URL のホスティング場所を理解できるように設計されています。これは、GPT 形式と KQL 形式の複数のツール (スキル) を使用して、YAML マニフェストで定義された構造化された呼び出しフローに従います。

トリガーのアクティブ化

エージェントは、300 秒ごとに既定のトリガーによってトリガーされます。
最初に FetchSkill: Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925 を呼び出します。 KQL スキル (Format: KQL) は、最近クリックした URL について Defender ログに対してクエリを実行します。
次に、ProcessSkill: Contoso.SecurityCopilot.Samples-090925.URL_Location_DCA_Agent_Entrypoint-090925を呼び出します。エージェントスキル (Format:AGENT) は、URL のホスティング場所を調査します。

エージェントを実行すると、Fetch Skill が呼び出されます Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925

エージェントスキルエントリポイント

URL_Location_DC_Agent_Entrypoint-090925 エージェントスキルは、FORMAT:AGENTで定義され、次の手順を実行します。

入力: 単一の入力が必要です: URL (調査する URL)。
手順: エージェントは、子スキルを呼び出す 3 つの手順に従います。
- ExtractHostname: GPT ツール ExtractHostname_DCA-090925 を使用して、URL からホスト名を解析します。
- GetDnsResolutionsByIndicators: Microsoft Threat Intelligence スキルセットを使用して、ホスト名に関連付けられている IP アドレスを取得します。 GetDnsResolutionsByIndicators ツールを呼び出さずに、RequiredSkillsets: ThreatIntelligence.DTIを追加する必要があることを確認します。
- lookupIpAddressGeolocation: OpenAPI 仕様の operationId です。これは、各 IP アドレスの位置情報データを検索するために API プラグイン DCA_SampleAPIPlugin で参照されます。リファレンスについては、「ビルド 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 (プラグイン) が、プロンプトバーから [ソースの管理] > [カスタム ] で設定または切り替えされているかどうかを確認します。
Descriptor.DisplayNameであるDCA URL Geolocation 090925 Agentを検索します。

注:

一般に、エージェントのセットアップ中にいくつかの構成を設定する必要があるプラグインが存在する場合があります。

手順 3: Security Copilotでエージェントを設定する

[ホーム > エージェント] に移動します。
エージェントライブラリでエージェント URLLocationAgent-090925 を検索します。これは YAML からの AgentDefinitions.DisplayName です。検索にエージェントが表示されない場合は、エージェントライブラリの画面を更新します。
エージェントカードで、[詳細の表示] を選択してエージェントを設定します。

[プラグイン] セクションで有効になっているプラグインを確認できます。
エージェントの設定に必要な入力パラメーターを指定します。
[ Signin]\(サインイン\) を選択して認証します。