Manifiesto del agente

El desarrollo de un agente de Security Copilot y sus herramientas (aptitudes) requieren un archivo de manifiesto en formato YAML o JSON (por ejemplo, manifest.yaml). Este archivo define los metadatos sobre el conjunto de herramientas (complemento) y especifica cómo se debe invocar cada herramienta.

Un manifiesto de agente incluye tres claves de nivel superior que son las siguientes:

• Descriptor
• AgentDefinitions
• SkillGroups

Cada clave contiene su propio conjunto de pares de subclave/valor, algunos de los cuales son campos obligatorios o opcionales en función del formato de la herramienta.

En esta guía de referencia se describen los campos de manifiesto disponibles para crear agentes Security Copilot.

YAML del agente

Este es un ejemplo de un archivo de ejemplo 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

El agente sigue un proceso de tres pasos para invocar las aptitudes secundarias:

• ExtractHostname: usa la herramienta ExtractHostname_DCA-090925 GPT para analizar el nombre de host de la dirección URL.

• GetDnsResolutionsByIndicators: usa el conjunto de aptitudes de Microsoft Threat Intelligence para recuperar las direcciones IP asociadas al nombre de host. Debe habilitar el complemento en Administrar orígenes > personalizados. Asegúrese de que RequiredSkillsets: ThreatIntelligence.DTI se debe agregar sin qué GetDnsResolutionsByIndicators herramienta no se invoca.

• lookupIpAddressGeolocation: es en operationId la especificación de OpenAPI, a la que se hace referencia en el complemento DCA_SampleAPIPlugin de API para buscar datos de geolocalización para cada dirección IP. Para obtener referencia, consulte Ejemplo de API de compilación.

Muestras

Consulte la lista completa de la colección Samples.

Para obtener el ejemplo de agente en el agente interactivo, consulte Agentes interactivos.

Sintaxis YAML del manifiesto

A continuación se muestran los parámetros de manifiesto del agente (campos) para las tres claves de nivel superior y sus subclaves:

Resumen del campo descriptor

(* implica que se recomienda pero no es necesario)

Resumen del campo AgentDefinitions

Resumen del campo SkillGroups

Consta de una lista de grupos de aptitudes que incluye Format, Settings, y Skills.

Formato (campo SkillGroups)

Opciones para el campo Format:

API
GPT
AGENT
KQL
LogicApp

Aptitudes (campo SkillGroups)

Estructura de objetos para el Skills campo:

Configuración (campo SkillGroups)

La estructura de objetos del campo es la Settings siguiente para los formatos admitidos. Para obtener ejemplos de aptitudes (herramientas), consulte Ejemplos de herramientas.

API

GPT

AGENTE

KQL

LogicApp

Configuración específica de destino

• Microsoft Defender

  No hay ninguna configuración adicional.

• Microsoft Sentinel

  Esta configuración es válida para la herramienta KQL donde el destino es 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

  Esta configuración es válida para la herramienta KQL, donde el destino es Kusto.

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

Autenticación

Security Copilot admite varios esquemas para autenticar herramientas. Consulte Tipos de autenticación. Para obtener ejemplos sobre los diferentes tipos de autenticación, consulte Complemento de API.

• +Este campo se usa para indicar los dos tipos diferentes de carga admitidos en Security Copilot.

• * Estos representan métodos de autenticación que se extienden más allá de lo que inicialmente admitía OpenAI.

Tipos de autenticación

En la tabla se muestra la configuración admitida para cada tipo de autenticación.