Manifesto do Agente

O desenvolvimento de um agente Security Copilot e as respetivas ferramentas (competências) requerem um ficheiro de manifesto no formato YAML ou JSON (por exemplo, manifest.yaml). Este ficheiro define metadados sobre o conjunto de ferramentas (plug-in) 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
• SkillGroups

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

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

AGENTE YAML

Este é um exemplo de um ficheiro 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 passos para invocar as competências subordinadas:

• ExtractHostname: utiliza a ferramenta ExtractHostname_DCA-090925 GPT para analisar o nome do anfitrião do URL.

• GetDnsResolutionsByIndicators: utiliza o conjunto de competências do Microsoft Threat Intelligence para obter os endereços IP associados ao nome do anfitrião. Tem de ativar o plug-in em Gerir origens Personalizadas > . Certifique-se de que RequiredSkillsets: ThreatIntelligence.DTI tem de ser adicionada sem a ferramenta que GetDnsResolutionsByIndicators não é invocada.

• lookupIpAddressGeolocation: está na operationId especificação OpenAPI, que é referenciada no plug-in DCA_SampleAPIPlugin da API para procurar dados de geolocalização para cada endereço IP. Para referência, veja Build API sample (Exemplo de API de Criação).

Exemplos

Veja a lista completa da coleção Exemplos.

Para obter o exemplo do Agente no agente interativo, veja Agentes interativos.

Sintaxe YAML do manifesto

Seguem-se os parâmetros de manifesto do agente (campos) para as três chaves de nível superior e as respetivas subchaves:

Resumo do campo descritor

(* implica recomendado, mas não necessá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 do 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 competências (ferramentas), veja Tool samples (Exemplos de ferramentas).

API

GPT

AGENTE

KQL

LogicApp

Configurações específicas do destino

• Microsoft Defender

  Sem definições adicionais.

• Microsoft Sentinel

  Estas definições são válidas para a ferramenta KQL onde o Destino é 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

  Estas definições são válidas para a ferramenta KQL em que Target é Kusto.

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

Autenticação

Security Copilot suporta vários esquemas para ferramentas de autenticação. Veja Tipos de autenticação. Para obter exemplos sobre os diferentes tipos de autenticação, veja Plug-in da API.

• +Este campo é utilizado para indicar os dois tipos diferentes de carregamento suportados no Security Copilot.

• * Estes representam métodos de autenticação que se estendem para além do que foi inicialmente suportado pela OpenAI.

Tipos de autenticação

A tabela mostra as definições suportadas para cada tipo de autenticação.