Manifesto do agente

O desenvolvimento de um agente do Security Copilot e suas ferramentas (também conhecidas como habilidades) exigem um arquivo de manifesto no formato YAML ou JSON (por exemplo, manifest.yaml). Este arquivo define metadados sobre o conjunto de ferramentas (plugin) e especifica como cada ferramenta deve ser invocada.

Um manifesto de agente inclui três chaves de nível superior que são as seguintes:

• Descritor
• AgentDefinitions
• Grupos de habilidades

Cada chave contém seu próprio conjunto de pares de subchave/valor, alguns dos quais são campos obrigatórios/opcionais, dependendo do formato da ferramenta.

Este guia de referência descreve os campos de manifesto disponíveis para a criação de agentes do Security Copilot.

YAML do agente

Este é um exemplo de um arquivo de exemplo 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

O agente segue um processo de três etapas para invocar as habilidades filhas:

• ExtractHostname: usa a ferramenta ExtractHostname_DCA-090925 GPT para analisar o nome do host da URL.

• GetDnsResolutionsByIndicators: usa o conjunto de habilidades de inteligência contra ameaças da Microsoft para recuperar os endereços IP associados ao nome do host. Você deve habilitar o plug-in em Gerenciar fontes > personalizadas. Certifique-se de que RequiredSkillsets: ThreatIntelligence.DTI isso deve ser adicionado sem o qual GetDnsResolutionsByIndicators a ferramenta não é invocada.

• lookupIpAddressGeolocation: está na operationId especificação OpenAPI, que é referenciada no plug-in DCA_SampleAPIPlugin da API para pesquisar dados de geolocalização para cada endereço IP. Para referência, consulte Exemplo de API de compilação.

Exemplos

Veja a lista completa da coleção de amostras.

Para obter o exemplo de Agente no agente interativo, consulte Agentes interativos.

Sintaxe YAML de manifesto

A seguir estão os parâmetros de manifesto do agente (campos) para as três chaves de nível superior e suas subchaves:

Resumo do campo descritor

(* implica recomendado, mas não obrigatório)

Resumo do campo AgentDefinitions

Resumo do campo SkillGroups

Consiste em uma lista de grupos de habilidades, incluindo Format, Settings e Skills.

Formato (campo SkillGroups)

Opções do campo Format:

API
GPT
AGENT
KQL
LogicApp

Habilidades (campo SkillGroups)

Estrutura de objeto para Skills o campo:

Configurações (campo SkillGroups)

A estrutura do objeto para o Settings campo é a seguinte para os formatos suportados. Para obter exemplos de habilidades (ferramentas), consulte Exemplos de ferramentas.

API

GPT

AGENTE

KQL

LogicApp

Configurações específicas do destino

• Microsoft Defender

  Nenhuma configuração adicional.

• Microsoft Sentinel

  Essas configurações são válidas para a ferramenta KQL, cujo destino é o 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

  Essas configurações são válidas para a ferramenta KQL em que o Destino é Kusto.

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

Autenticação

O Security Copilot dá suporte a vários esquemas para autenticar ferramentas. Consulte Tipos de autenticação. Para obter exemplos sobre os diferentes tipos de autenticação, consulte Plug-in de API.

• +Esse campo é usado para indicar os dois tipos diferentes de upload com suporte no Security Copilot.

• * Eles representam métodos de autenticação que vão além do que era inicialmente suportado pelo OpenAI.

Tipos de autenticação

A tabela mostra as configurações com suporte para cada tipo de autenticação.