Adicionar várias ferramentas ao seu agente

Este exemplo orienta você na criação de um agente que ajuda os analistas de segurança a entender o local de hospedagem de uma determinada URL. O exemplo de YAML usa ferramentas globais da Microsoft, GPT, API e ferramentas KQL (habilidades).

O processo geral é o seguinte:

• Etapa 1: criar e carregar o agente YAML
• Etapa 2: habilitar ou alternar o agente em Gerenciar origens
• Etapa 3: configurar o agente no Security Copilot
• Etapa 4: Executar o agente

Entender o fluxo de chamadas da ferramenta (habilidade)

Esta seção explica como o agente invoca ferramentas YAML (habilidades) e quais plug-ins ele requer.

O DCA URL Geolocation 090925 Agent foi projetado para ajudar os analistas de segurança a entender o local de hospedagem de uma determinada URL. Ele segue um fluxo de invocação estruturado definido no manifesto YAML usando várias ferramentas (habilidades) nos formatos GPT e KQL.

Entenda como o gatilho do agente é ativado

O gatilho do agente é ativado da seguinte maneira:

• O agente é acionado por meio do gatilho Padrão a cada 300 segundos.

• Primeiro, ele invoca o FetchSkill: Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925. A habilidade KQL (Format: KQL) consulta os logs do Defender em busca de URLs clicadas recentemente.

• Em seguida, ele invoca o ProcessSkill: Contoso.SecurityCopilot.Samples-090925.URL_Location_DCA_Agent_Entrypoint-090925. A habilidade do agente (Format:AGENT) investiga o local de hospedagem da URL.

Quando você executa o agente, a habilidade de busca é invocada Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925

Entender o ponto de entrada da habilidade do agente

A URL_Location_DC_Agent_Entrypoint-090925 habilidade do FORMAT:AGENT agente é definida na e executa as seguintes etapas:

• Entradas: Requer uma única entrada: URL (a URL a ser investigada).

• Instruções: O agente segue um processo de três etapas para invocar as habilidades filho:

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

  • GetDnsResolutionsByIndicators: usa o conjunto de habilidades da Inteligência contra Ameaças da Microsoft para recuperar os endereços IP associados ao nome do host. Certifique-se de que RequiredSkillsets: ThreatIntelligence.DTI deve ser adicionado sem qual GetDnsResolutionsByIndicators 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.

Etapa 1: criar e carregar o Agente YAML

O agente YAML é definido da seguinte forma:

Descriptor:
  Name: Contoso.SecurityCopilot.Samples-090925_1b
  Description: DCA URL Geolocation 090925 Agent_1b
  DisplayName: DCA URL Geolocation 090925 Agent_1b

SkillGroups:
- Format: AGENT
  Skills:
  - Name: URL_Location_DCA_Agent_Entrypoint-090925_1b
    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_1b
    - GetDnsResolutionsByIndicators
- Format: GPT
  Skills:
  - Name: ExtractHostname_DCA-090925_1b
    DisplayName: ExtractHostname_DCA-090925_1b
    Description: ExtractHostname_DCA-090925_1b
    Inputs:
    - Name: URL
      Description: A URL string
    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_1b
      Description: Returns recently clicked URLs
      Inputs:
        - Name: LookbackMinutes
          Description: Number of minutes to lookback
          Required: false
      Settings:
        Target: Defender
        Template: UrlClickEvents | sort by TimeGenerated desc | limit 10 | project Url

AgentDefinitions:
  - Name:  URLLocationAgent-090925_1b
    DisplayName: URLLocationAgent 090925_1b
    Description: An agent to help an analyst understand URL hosting 
    Publisher: Contoso
    Product: Security Copilot
    RequiredSkillsets:
      - SecurityCopilot
      - 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.SecurityCopilot.Samples-090925_1b.RecentUrlClicks_DCA-090925_1b
        ProcessSkill: Contoso.SecurityCopilot.Samples-090925_1b.URL_Location_DCA_Agent_Entrypoint-090925_1b
        Settings:
  
Settings:
    HistoryPassDownMode: None
    IncludeSessionHistory: false
WorkspaceId: SecurityCopilot_Workspace 

Etapa 2: habilitar ou alternar o agente em Gerenciar origens

As etapas para habilitar o agente são as seguintes:

1. Verifique se o YAML (plug-in) carregado está configurado ou alternado em Gerenciar fontes > personalizadas na barra de prompts.

   

2. DCA URL Geolocation 090925 AgentPesquise , que é o Descriptor.DisplayName.

Etapa 3: configurar o agente no Security Copilot

As etapas para configurar o agente são as seguintes:

1. Navegue até Agentes Domésticos>.

2. Procure o agente URLLocationAgent-090925 na Biblioteca de Agentes, que é do AgentDefinitions.DisplayName YAML. Atualize a tela na Biblioteca de agentes se a pesquisa não exibir o agente.

   

3. No card Agente, selecione Exibir detalhes para Configurar o agente.

   

   Você pode ver os plug-ins ativados na seção Plug-ins.

4. Forneça os parâmetros de entrada necessários para configurar o agente.

   

5. Selecione Entrar para autenticar.

   

Etapa 4: Executar o agente

As etapas para executar o agente são as seguintes:

1. Selecione Concluir para executar o agente. Isso exibe a tela de execução do agente.

   

2. Selecione Executar uma vez sem um gatilho para executar o agente.

   Os resultados da execução do agente são os exibidos.

   

3. Selecione Exibir atividade para ver o resultado de cada agente.