エージェントマニフェスト

重要

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

Security Copilot エージェントとそのツール (スキル) を開発するには、YAML 形式または JSON 形式 (manifest.yaml など) のマニフェストファイルが必要です。このファイルは、ツールセット (プラグイン) に関するメタデータを定義し、各ツールを呼び出す方法を指定します。

エージェントマニフェストには、次の 3 つの最上位のキーが含まれています。

表記
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

エージェントは、子スキルを呼び出す 3 つの手順に従います。

ExtractHostname: GPT ツール ExtractHostname_DCA-090925 を使用して、URL からホスト名を解析します。
GetDnsResolutionsByIndicators: Microsoft Threat Intelligence スキルセットを使用して、ホスト名に関連付けられている IP アドレスを取得します。 [ソースの管理] > [カスタム] でプラグインを有効にする必要があります。 GetDnsResolutionsByIndicators ツールが呼び出されないRequiredSkillsets: ThreatIntelligence.DTIを追加する必要があることを確認します。
lookupIpAddressGeolocation: OpenAPI 仕様の operationId です。これは、各 IP アドレスの位置情報データを検索するために API プラグイン DCA_SampleAPIPlugin で参照されます。リファレンスについては、「ビルド API サンプル」を参照してください。

サンプル

Samples コレクションの完全な一覧を参照してください。

対話型エージェントのエージェントサンプルについては、「対話型エージェント」を参照してください。

マニフェスト YAML 構文

3 つの最上位キーとそのサブキーのエージェントマニフェストパラメーター (フィールド) を次に示します。

記述子フィールドの概要

フィールド	種類	説明	制約	必須
`Name`	string	スキルセットの内部名。ワークスペース内の一意の名前にする必要があります。	`/ , \ ? # @`を許可しません。空白を含めることはできません。	はい
`DisplayName`	string	スキルセットの人間が判読できる名前。		いいえ*
`Description`	string	スキルセットの人間が判読できる説明。	null または空にすることはできません。	はい
`Authorization`	object	承認値を設定します。詳細については、「認証」を参照してください。		いいえ;API ツールに必要であり、`None`と等しくない`SupportedAuthTypes`。
`SupportedAuthTypes`	配列	スキルセットでサポートされている認証の種類の一覧。詳細については、「認証」を参照してください。		いいえ;API ツールに必要

(* は推奨を意味しますが、必須ではありません)

AgentDefinitions フィールドの概要

フィールド	種類	説明	制約	必須
`Name`	string	エージェントのインストールに使用される名前。	空白、ピリオド (.) を含めず、null または空にすることはできません。	はい
`DisplayName`	string	UI 表示のわかりやすい名前。		はい
`Description`	string	エージェントの目的と機能の人間が判読できる概要。		はい
`Publisher`	string	エージェントの発行元の名前。		はい
`Product`	string	エージェントに関連付けられているソース製品。エージェント定義を列挙するときにフィルター処理に使用されます。		はい
`RequiredSkillsets`	string	エージェントが機能するために必要なスキルセット。		はい
`AgentSingleInstanceConstraint`	string	エージェントをデプロイできる場所を定義します。 `None`、`Workspace`、または`Tenant`に設定できます。 - `None`: 制限なし。 - `Workspace`: ワークスペースごとに 1 つのインスタンス。 - `Tenant`: テナントごとに 1 つのインスタンス。		いいえ
`Settings`	object	FetchSkill 呼び出しにのみ適用されます。		いいえ
`Triggers`	object	エージェントをトリガーする方法とタイミングを定義します。少なくとも 1 つのトリガーが必要です。 `Name`: トリガーのわかりやすい名前。 `DefaultPeriodSeconds`: スケジュールされた実行の間隔 (秒単位)。トリガーは同時実行を妨げるわけではありません。スケジュールされた実行を無効にするには、この値を 0 に設定します。 `FetchSkill`: 設定すると、トリガーは最初にこのスキル (ツール) を呼び出します。トリガーはオブジェクトの配列を受け取ります。オブジェクトごとに、オブジェクトの値を`ProcessSkill`への入力として使用して`ProcessSkill`を呼び出します。一般的なパターンは、ListAlerts FetchSkill と、InvestigateAlertAgent ProcessSkill を使用することです。トリガーの詳細については、「エージェントコンポーネント」を参照してください。	`Name`: 空白文字を含めることはできません	はい; `Name` と `ProcessSkill`。
`PromptSkill`	object	エージェントで対話機能またはチャットエクスペリエンスを有効にします。		はい;対話型エージェントにのみ適用されます。

SkillGroups フィールドの概要

Format、Settings、Skills を含むスキルグループのリストで構成されます。

フィールド	種類	説明	必須
`Format`	string	利用可能なオプションについては、「形式」セクションを参照してください。	はい
`Skills`	object	オブジェクト構造については、スキルセクションを参照してください。	はい;形式: `GPT`、 `API`、 `KQL`、 `AGENT`
`Settings`	object	オブジェクトの構造については、「設定」セクションを参照してください。	はい;形式: `API`、 `GPT`、 `KQL`、 `AGENT`

形式 (SkillGroups フィールド)

Format フィールドのオプション:

API
GPT
AGENT
KQL
LogicApp

スキル (SkillGroups フィールド)

Skills フィールドのオブジェクト構造:

フィールド	種類	説明	制約	必須
`Name`	string	このツールの内部名 (スキル)	空白文字とピリオド (.) を含めることはできません。	はい
`DisplayName`	string	このツールの人間が判読できる名前。		推奨
`Description`	string	このツールの人間が判読できる説明	null または空にすることはできません。	推奨
`Inputs`	object	ツールへのユーザー入力に必要な、または省略可能なオブジェクトの名前、説明、およびオプションのオブジェクトの一覧。		いいえ
`Settings`	object	スキル [形式] に基づいたカスタム設定。		はい
`ChildSkills`	文字列の配列	実行中にエージェントが依存または呼び出すツール名の一覧。ツールは特定のタスクを実行し、その目的を達成するためにエージェントによって呼び出されます。複数のツールのチェーンまたは構成を有効にして、より複雑なエージェントの動作を構築できます。		いいえ;ただし、 `FORMAT: AGENT` スキルにのみ適用され、必要です。
`Interfaces`	object	対話型エージェントをビルドするときに `InteractiveAgent` に設定します。		はい
`SuggestedPrompts`	object	`Prompt`: ユーザーに表示する実際のプロンプト (スタータープロンプトの場合) または推奨されるプロンプトを生成するためのテンプレートとして使用します。 `Title`: プロンプトのタイトル。 `Personas`: プロンプトが配置されているペルソナ型。 `IsStarterAgent`: スタータープロンプトの場合は true に設定します。推奨事項: Starter と推奨されるプロンプトの最大 2 つの文に設定します。		はい;対話型エージェントにのみ適用されます。 `Title` と `Personas` (スタータープロンプトにのみ必要)。

設定 (SkillGroups フィールド)

Settings フィールドのオブジェクト構造は、サポートされている Formats に対して次のとおりです。スキル (ツール) サンプルについては、「ツールのサンプル」を参照してください。

API

設定名	型	説明	必須
`OpenApiSpecUrl`	string	パブリック OpenAPI 仕様への URL。	はい
`EndpointUrl`	string	パブリックエンドポイントへの URL。	いいえ;OpenAPI 仕様に記載されている API サーバーを使用しない場合にのみを指定します。
`EndpointUrlSettingName`	string	プラグインのセットアップ中にパブリックエンドポイントの URL を要求するカスタマイズ可能な設定。	いいえ;API エンドポイントを構成可能にする場合にのみを指定します。
`EnableSkillContextApi`	bool	これは、API ツールが SkillContext API にアクセスする必要がある場合にのみ設定します。	不要

GPT

設定名	型	説明	制約	必須
`ModelName`	string	使用する GPT モデルを選択します。	gpt-4.1 である必要があります	はい
`Template`	文字列	GPT プロンプトテンプレート。	最大 80,000 文字をサポート	はい