Adicionar várias ferramentas ao agente

Importante

Algumas informações neste artigo estão relacionadas ao produto pré-lançado que pode ser modificado substancialmente antes de ser lançado comercialmente. A Microsoft não faz garantias, expressas ou implícitas, quanto às informações fornecidas aqui.

Este exemplo orienta-o na criação de um Agente através de um YAML de exemplo que utiliza ferramentas globais da Microsoft, GPT, API e ferramentas KQL(competências).

O processo geral é o seguinte:

Passo 1: Criar e carregar o agente YAML
Passo 2: Ativar ou ativar o agente em Gerir origens
Passo 3: Configurar o agente no Security Copilot
Passo 4: Executar o agente

Discriminação da chamada de ferramenta (competência)

Esta secção ajuda-o a compreender como as ferramentas YAML (competências) do agente são invocadas e quais os plug-ins que têm de ser incluídos.

O DCA URL Geolocation 090925 Agent foi concebido para ajudar os analistas de segurança a compreender a localização de alojamento de um determinado URL. Segue um fluxo de invocação estruturado definido no manifesto YAML com múltiplas ferramentas (competências) em formatos GPT e KQL.

Ativação do acionador

O agente é acionado através do acionador Predefinido a cada 300 segundos.
Em primeiro lugar, invoca o FetchSkill: Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925. A competência KQL (Format: KQL) consulta os registos do Defender para URLs clicados recentemente.
Em seguida, invoca o ProcessSkill: Contoso.SecurityCopilot.Samples-090925.URL_Location_DCA_Agent_Entrypoint-090925. A competência do agente (Format:AGENT) investiga a localização de alojamento do URL.

Quando executa o agente, a Competência de Obtenção é invocada Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925

Ponto de entrada de competência do agente

A URL_Location_DC_Agent_Entrypoint-090925 competência do agente é definida no FORMAT:AGENT e efetua os seguintes passos:

Entradas: requer uma única entrada: URL (o URL para investigar).
Instruções: 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. 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).

Passo 1: Criar e carregar o YAML do Agente

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

Passo 2: Ativar ou ativar o agente em Gerir origens

Verifique se o YAML carregado (plug-in) está configurado ou alternado em Gerir origens Personalizadas > na barra de pedidos.
DCA URL Geolocation 090925 AgentProcure , que é o Descriptor.DisplayName.

Observação

Em geral, podem existir plug-ins que requerem algumas configurações definidas durante a configuração do agente.

Passo 3: Configurar o agente no Security Copilot

Navegue para Agentes Domésticos>.
Procure o agente URLLocationAgent-090925 na Biblioteca de Agente, que é o AgentDefinitions.DisplayName do YAML. Atualize o ecrã na Biblioteca de Agentes se a pesquisa não apresentar o agente.
Na card Agente, selecione Ver detalhes para Configurar o agente.

Pode ver os plug-ins ativados na secção Plug-ins.
Indique os parâmetros de entrada necessários para configurar o agente.
Selecione Iniciar sessão para autenticar.

Passo 4: Executar o agente

Selecione Concluir para executar o agente. Esta ação apresenta o ecrã de execução do agente.
Selecione Executar uma vez sem um acionador para executar o agente.

Os resultados da execução do agente são apresentados.
Selecione Ver atividade para ver cada resultado do agente.

Last updated on 2025-11-13

Compartilhar via