Condividi tramite

Manifesto dell'agente

Importante

Alcune informazioni in questo articolo fanno riferimento alle caratteristiche di un prodotto prima del rilascio, che possono essere modificate sostanzialmente prima della distribuzione al pubblico. Microsoft non fornisce alcuna garanzia, esplicita o implicita, in relazione alle informazioni contenute in questo documento.

Lo sviluppo di un agente Security Copilot e dei relativi strumenti (competenze) richiede un file manifesto in formato YAML o JSON ,ad esempio manifest.yaml. Questo file definisce i metadati relativi al set di strumenti (plug-in) e specifica come richiamare ogni strumento.

Un manifesto dell'agente include tre chiavi di primo livello che sono le seguenti:

Ogni chiave contiene il proprio set di coppie sottochiave/valore, alcune delle quali sono campi obbligatori/facoltativi a seconda del formato dello strumento.

Questa guida di riferimento descrive i campi manifesto disponibili per la creazione di agenti Security Copilot.

Agent YAML

Questo è un esempio di un file di esempio 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

L'agente segue un processo in tre passaggi per richiamare le competenze figlio:

  • ExtractHostname: usa lo strumento ExtractHostname_DCA-090925 GPT per analizzare il nome host dall'URL.

  • GetDnsResolutionsByIndicators: usa il set di competenze di Microsoft Threat Intelligence per recuperare gli indirizzi IP associati al nome host. È necessario abilitare il plug-in Gestisci origini > personalizzato. Assicurarsi che RequiredSkillsets: ThreatIntelligence.DTI debba essere aggiunto senza quale GetDnsResolutionsByIndicators strumento non viene richiamato.

  • lookupIpAddressGeolocation: oggetto operationId nella specifica OpenAPI, a cui si fa riferimento nel plug-in DCA_SampleAPIPlugin API per cercare i dati di georilevazione per ogni indirizzo IP. Per informazioni di riferimento, vedere Esempio di API di compilazione.

Campioni

Vedere l'elenco completo della raccolta Samples.

Per l'esempio dell'agente nell'agente interattivo, vedere Agenti interattivi.

Sintassi YAML del manifesto

Di seguito sono riportati i parametri del manifesto dell'agente (campi) per le tre chiavi di primo livello e le relative sottochiavi:

Riepilogo del campo descrittore

Campo Tipo Descrizione Vincoli Obbligatorio
Name stringa Nome interno del set di competenze. Deve essere un nome univoco nell'area di lavoro. Non consente / , \ ? # @; non può contenere spazi vuoti. Sì
DisplayName stringa Nome leggibile dell'insieme di competenze. No*
Description stringa Descrizione leggibile dell'insieme di competenze. Non può essere null o vuoto. Sì
Authorization oggetto Impostare i valori di autorizzazione. Per altre informazioni, vedere Autenticazione per altri dettagli. No; Obbligatorio per lo strumento API e SupportedAuthTypes diverso da None.
SupportedAuthTypes array Elenco dei tipi di autenticazione supportati per il set di competenze. Per altre informazioni, vedere Autenticazione per altri dettagli. No; Obbligatorio per lo strumento API

(* implica consigliato ma non obbligatorio)

Riepilogo del campo AgentDefinitions

Campo Tipo Descrizione Vincoli Obbligatorio
Name stringa Nome usato per l'installazione dell'agente; Non può contenere spazi vuoti, punto (.) e non può essere Null o vuoto. Sì
DisplayName stringa Nome descrittivo per la visualizzazione dell'interfaccia utente. Sì
Description stringa Riepilogo leggibile dello scopo e della funzionalità dell'agente. Sì
Publisher stringa Nome dell'editore dell'agente. Sì
Product stringa Prodotto di origine associato all'agente. Utilizzato per filtrare durante l'enumerazione delle definizioni degli agenti. Sì
RequiredSkillsets stringa Set di competenze necessari per il funzionamento dell'agente. Sì
AgentSingleInstanceConstraint stringa Definisce dove è possibile distribuire l'agente. Può essere impostato su None, Workspaceo Tenant.
- None: nessuna restrizione.
- Workspace: un'istanza per area di lavoro.
- Tenant: un'istanza per tenant.		 No
Settings oggetto Applicato solo alla chiamata FetchSkill. No
Triggers oggetto Definisce come e quando viene attivato l'agente. È necessario almeno un trigger.
  • Name: nome descrittivo per il trigger.
  • DefaultPeriodSeconds: intervallo in secondi per l'esecuzione pianificata. I trigger non impediscono esecuzioni simultanee. Per disabilitare l'esecuzione pianificata, impostare questo valore su 0.
  • FetchSkill: se impostato, il trigger richiama prima questa competenza (strumento). Il trigger prevede una matrice di oggetti . Per ogni oggetto, chiama ProcessSkill utilizzando i valori dell'oggetto come input per ProcessSkill. Un modello comune sarebbe quello di avere un ListAlerts FetchSkill e un InvestigateAlertAgent ProcessSkill. Per altre informazioni su Trigger, vedere Componenti dell'agente.
    		•  Name: non può contenere spazi vuoti Sì; Name e ProcessSkill.
    PromptSkill oggetto Abilitare l'interattività o l'esperienza di chat con l'agente. Sì; Applicabile solo per gli agenti interattivi.

    Riepilogo del campo SkillGroups

    È costituito da un elenco di gruppi di funzionalità tra cui Format, Settings e Skills.

    Campo Tipo Descrizione Vincoli Obbligatorio
    Format stringa Per le opzioni disponibili, vedi la sezione Formato. Sì
    Skills oggetto Per la struttura degli oggetti, vedi la sezione Competenze. Sì; per i formati: GPT, API, , KQL, AGENT
    Settings oggetto Per la struttura degli oggetti, vedi la sezione Impostazioni. Sì; per i formati: API, GPT, , KQL, AGENT

    Formato (campo SkillGroups)

    Opzioni per il campo Format:

    API
    GPT
    AGENT
    KQL
    LogicApp

    Competenze (campo SkillGroups)

    Struttura dell'oggetto per il Skills campo:

    Campo Tipo Descrizione Vincoli Obbligatorio
    Name stringa Nome interno per questo strumento (competenza) Non può contenere spazi vuoti e punti(.) Sì
    DisplayName stringa Nome leggibile per questo strumento. Consigliata
    Description stringa Descrizione leggibile per questo strumento Non può essere null o vuoto. Consigliata
    Inputs oggetto Elenco di oggetti Name, Description e Required o facoltativi per l'input dell'utente nello strumento. No
    Settings oggetto Impostazioni personalizzate in base al formato della funzionalità. Sì
    ChildSkills matrice di stringhe Elenco di nomi di strumenti che l'agente dipende o richiama durante l'esecuzione. Gli strumenti eseguono attività specifiche e vengono chiamati dall'agente per soddisfare i propri obiettivi. Consente il concatenamento o la composizione di più strumenti per creare un comportamento dell'agente più complesso. No; Tuttavia, applicabile e obbligatorio solo per FORMAT: AGENT la competenza.
    Interfaces oggetto InteractiveAgent Impostare su quando si compila un agente interattivo. Sì
    SuggestedPrompts oggetto
  • Prompt: richiesta effettiva da visualizzare all'utente (se richiesta iniziale) o da usare come modello per la generazione di prompt suggeriti.
  • Title: titolo del prompt.
  • Personas: il tipo di persona a cui è allineato un prompt.
  • IsStarterAgent: impostare su true per la richiesta di avvio.
    Raccomandazione: impostare su due frasi max per Starter e prompt suggeriti.
    		•  Sì; Applicabile solo per gli agenti interattivi. Title e Personas (obbligatorio solo per i prompt di avvio).

    Impostazioni (campo SkillGroups)

    La struttura dell'oggetto per il Settings campo è la seguente per i formati supportati. Per esempi di competenza (strumento), vedere Esempi di strumenti.

    API

    Nome impostazione Tipo Descrizione Vincoli Obbligatorio
    OpenApiSpecUrl stringa URL della specifica OpenAPI pubblica. Sì
    EndpointUrl stringa URL per l'endpoint pubblico. No; Specificare solo se non si vuole usare il server API elencato nella specifica OpenAPI.
    EndpointUrlSettingName stringa Impostazione personalizzabile per richiedere l'URL per l'endpoint pubblico durante l'installazione del plug-in. No; Specificare solo se si vuole configurare l'endpoint API.
    EnableSkillContextApi bool Impostare questa impostazione solo se gli strumenti API devono accedere all'API SkillContext. No

    GPT

    Nome impostazione Tipo Descrizione Vincoli Obbligatorio
    ModelName stringa Seleziona il modello GPT da usare. Deve essere gpt-4.1 Sì
    Template stringa Modello di richiesta di GPT. Supporta fino a 80.000 caratteri Sì

    AGENTE

    Nome impostazione Tipo Descrizione Vincoli Obbligatorio
    Instructions stringa Indicazioni o indicazioni chiare che definiscono il comportamento e la missione dell'agente. Le indicazioni vengono usate per indirizzare le risposte dell'agente e assicurarsi che siano allineate al caso d'uso previsto. In genere scritto in linguaggio naturale e include formattazione come markdown o commenti. Sì

    KQL

    Nome impostazione Tipo Descrizione Vincoli Obbligatorio
    Target stringa Selezionare il sistema o la piattaforma in cui viene eseguito lo strumento. Vedere Impostazioni specifiche della destinazione. Sì
    Template stringa Modello di richiesta di KQL. Supporta fino a 80.000 caratteri. Sì se TemplateUrl non è specificato.
    TemplateUrl stringa URL pubblico per scaricare il modello di richiesta KQL (fino a 80.000 caratteri). Sì. Specificare o TemplatUrl ma Template non entrambi.
    PackageUrl stringa URL pubblico per il file ZIP con il modello di richiesta di KQL. Nota: specificato a livello di SkillGroup. Sì se Template o TemplateUrl non sono specificati.
    TemplateFile stringa Percorso relativo del modello di prompt KQL (fino a 80.000 caratteri) all'interno del PackageUrl file ZIP. Sì se PackageUrl è specificato.

    LogicApp

    Nome impostazione Tipo Descrizione Obbligatorio
    SubscriptionId stringa Microsoft Azure ID sottoscrizione da App per la logica. La sottoscrizione deve trovarsi nello stesso tenant del tenant utente Security Copilot. Sì
    ResourceGroup stringa Microsoft Azure gruppo di risorse dall'app per la logica in cui viene creata la risorsa. Sì
    WorkflowName stringa Nome della risorsa app per la logica. Sì
    TriggerName stringa Nome del trigger creato in App per la logica. Sì

    Impostazioni specifiche della destinazione

    • Microsoft Defender

      Nessuna impostazione aggiuntiva.

    • Microsoft Sentinel

      Queste impostazioni sono valide per lo strumento KQL in cui la destinazione è 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

      Queste impostazioni sono valide per lo strumento KQL in cui target è Kusto.

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

    Autenticazione

    Security Copilot supporta diversi schemi per l'autenticazione degli strumenti. Vedere Tipi di autenticazione. Per esempi sui diversi tipi di autenticazione, vedere Plug-in API.

    Schema Descrizione Supporto del manifesto copilot Supporto OpenAI +
    None Nessuna autenticazione Sì Sì
    Basic Autenticazione di base Sì No
    ApiKey Autenticazione basata su ApiKey. ApiKey viene passato in un'intestazione personalizzata o in un parametro di query. Sì Sì*
    ServiceHttp Autenticazione basata sul token fornito. Sì Sì
    OAuthAuthorizationCodeFlow Il flusso di codice di autorizzazione OAuth 2.0 è un metodo di autenticazione più sicuro e complesso usato per concedere l'accesso ad applicazioni di terze parti senza condividere le credenziali utente. Sì Sì
    OAuthClientCredentialsFlow Analogamente all'autenticazione di base, ma usata per la comunicazione da server a server o quando si accede a dati pubblici che non richiedono autorizzazioni specifiche dell'utente. Sì No
    OAuthPasswordGrantFlow Un modo legacy per scambiare le credenziali di un utente con un token di accesso usando il tipo di concessione della password OAuth 2.0. Non è più consigliato. Sì No
    AAD Microsoft Entra accesso solo all'applicazione. Sì Sì*
    AADDelegated Accesso solo utente + Microsoft Entra applicazione. Sì Sì*

    • +Questo campo viene usato per indicare i due diversi tipi di caricamento supportati in Security Copilot.

    • * Questi rappresentano metodi di autenticazione che si estendono oltre quello che è stato inizialmente supportato da OpenAI.

    Tipi di autenticazione

    La tabella mostra le impostazioni supportate per ogni tipo di autenticazione.

    Tipo di autenticazione Impostazione Descrizione
    AAD o AADDelegated EntraScopes Elenco delimitato da virgole di ambiti Microsoft Entra da richiedere.
    Basic o OAuthPasswordGrantFlow Username Nome utente da usare per l'autenticazione di base.
    Password Password da usare per l'autenticazione di base.
    ApiKey Key Nome del parametro di intestazione/query. Il valore predefinito è Authorization, ma può essere un valore personalizzato. Ad esempio, X-ApiKey.
    AuthScheme Nome dello schema di autenticazione anteposto al valore se usato in un'intestazione. Le opzioni accettabili sono una stringa vuota, Bearer o Basic.
    Location Percorso della chiave API, ovvero Header o QueryParams. Il valore predefinito è Intestazione.
    Value Chiave/token da usare.
    ServiceHttp AccessToken Chiave/token da usare. Bearer AuthScheme viene anteposto al token nell'intestazione della richiesta di autorizzazione.
    OAuthAuthorizationCodeFlowo o OAuthClientCredentialsFlowOAuthPasswordGrantFlow TokenEndpoint Endpoint da cui richiedere il token.
    Scopes Elenco facoltativo delimitato da virgole di ambiti da richiedere.
    ClientId ID client da usare quando si richiede il token. Facoltativo per OAuthPasswordGrantFlow.
    ClientSecret Segreto client da usare quando si richiede il token. Facoltativo per OAuthPasswordGrantFlow.
    AuthorizationContentType Tipo di contenuto usato durante l'invio della richiesta di token. Il valore predefinito è application/x-www-form-urlencoded.
    OAuthAuthorizationCodeFlow AuthorizationEndpoint Endpoint da cui richiedere il codice di autorizzazione.
    • Last updated on