Add multiple tools to your agent

This example guides you through a sample YAML that uses global Microsoft tools, GPT, API, and KQL tools(skills).

The overall process is as follows:

• Step 1: Create and upload the agent YAML
• Step 2: Enable or toggle agent in Manage sources
• Step 3: Set up the agent in Security Copilot
• Step 4: Run the agent

Breakdown of the tool (skill) call

This section helps you understand how the agent YAML tools (skills) are invoked and which plugins need to be included.

The DCA URL Geolocation 090925 Agent is designed to help security analysts understand the hosting location of a given URL. It follows a structured invocation flow defined in the YAML manifest using multiple tools (skills) across GPT and KQL formats.

Trigger activation

• The agent is triggered via the Default trigger every 300 seconds.

• It first invokes the FetchSkill: Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925. The KQL skill (Format: KQL) queries Defender logs for recently clicked URLs.

• Then it invokes the ProcessSkill: Contoso.SecurityCopilot.Samples-090925.URL_Location_DCA_Agent_Entrypoint-090925. The agent skill (Format:AGENT) investigates the URL's hosting location.

When you run the agent, the Fetch Skill is invoked Contoso.SecurityCopilot.Samples-0909d.RecentUrlClicks_DCA-090925

Agent skill entrypoint

The URL_Location_DC_Agent_Entrypoint-090925 agent skill is defined under the FORMAT:AGENT and performs the following steps:

• Inputs: Requires a single input: URL (the URL to investigate).

• Instructions: The agent follows a three-step process to invoke the child skills:

  • ExtractHostname: Uses the GPT tool ExtractHostname_DCA-090925 to parse the hostname from the URL.

  • GetDnsResolutionsByIndicators: Uses the Microsoft Threat Intelligence skillset to retrieve the IP addresses associated with the hostname. Ensure that RequiredSkillsets: ThreatIntelligence.DTI must be added without which GetDnsResolutionsByIndicators tool is not invoked.

  • lookupIpAddressGeolocation: Is the operationId in the OpenAPI specification, which is referenced in the API plugin DCA_SampleAPIPlugin to look up geolocation data for each IP address. For reference, see Build API sample.

Step 1: Create and upload the Agent YAML

The agent YAML is defined as follows:

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 

Step 2: Enable or toggle agent in Manage sources

1. Check if the uploaded YAML (plugin) is set up or toggled in Manage sources > Custom from the prompt bar.

   

2. Search for DCA URL Geolocation 090925 Agent, which is the Descriptor.DisplayName.

Step 3: Set up the agent in Security Copilot

1. Navigate to Home > Agents.

2. Search for the agent URLLocationAgent-090925 in the Agent Library, which is the AgentDefinitions.DisplayName from YAML. Refresh the screen in the Agent Library if search doesn't display the agent.

   

3. On the Agent card, select View details to Set up the agent.

   

   You can see the plugins enabled in the Plugins section.

4. Provide the input parameters required to set up the agent.

   

5. Select Signin to authenticate.

   

Step 4: Run the agent

1. Select Finish to run the agent. This displays the agent run screen.

   

2. Select Run it one time without a trigger to run the agent.

   The results from the agent run are as displayed.

   

3. Select View activity to see each agent result.