Add an API tool to your agent

Agent developers often need to make HTTP requests to build complete use cases.

This example creates an agent that connects to a REST API that uses a service called freeipapi.com that provides Geo-IP lookup services. Ensure you use test data and not sensitive data if you run this agent.

The overall process is as follows:

• Step 1: Create and publish an OpenAPI specification that defines the API
• Step 2: Create and upload the manifest file to Security Copilot
• Step 3: Create and upload an agent that uses the plugin

Step 1: Create and publish an OpenAPI specification

The example integrates with the Free IP REST API to perform IP Address geolocation lookups. You must publish this specification online (a GitHub gist works well). Refer to the following sample to create and host your specification.

openapi: 3.0.0

info:
    title: Free IP API
    description: A free IP lookup API
    version: "v1"

servers:
    - url: https://freeipapi.com/api/

paths:
    /json/{ipaddress}:
        get: 
            operationId: lookupIpAddressGeolocation
            summary: Lookup IP Address Geolocation information
            parameters:
                - in: path
                  name: ipaddress
                  schema:
                      type: string
                  required: true
                  description: The ip address to lookup
            responses:
                "200":
                    description: OK
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/lookupIpAddressGeolocationResponse"

components:
    schemas:
        lookupIpAddressGeolocationResponse:
            type: object
            properties:
                ipVersion:
                    type: integer
                    description: The IP address version
                ipAddress:
                    type: string
                    description: The IP address
                latitude:
                    type: number
                    description: The latutude
                longitude:
                    type: number
                    description: The longitude
                countryName:
                    type: string
                    description: The country
                zipCode:
                    type: string
                    description: The zip code
                cityName:
                    type: string
                    description: The city
                regionName:
                    type: string
                    description: The region
                continent:
                    type: string
                    description: The continent

Step 2: Create and upload the API manifest (plugin)

1. Create a file called http_manifest.yaml that is of the tool format API:

   Descriptor:
     Name: DCA_SampleAPIPlugin
     DisplayName: TESTDCA_Free IP API
     Description: Skills for looking up geolocation information for an IP address using the Free IP API
   
   SkillGroups:
     - Format: API
       Settings:
         OpenApiSpecUrl: <Reference to your openapi.yaml schema created in Step 1>
   

2. Upload the yaml to Security Copilot. The instructions for uploading the YAML are covered at, Build agent manifest.

   Note

   You need to complete the setup steps for the plugin to be available for use and appear in the Custom section. The uploaded YAML or manifest is published as an agent to Active agents only if the manifest YAML has an agent definition (AgentDefinitions) defined.

3. You can test this tool or plugin by navigating to System Capabilities in Prompts and search for lookupIpAddressGeolocation, which is the operationId value from the API specification, which you defined in Step 1.

   

   The response after executing the tool is displayed.

   

Step 3: Create and upload an agent that uses the API plugin

Now, upload the agent that uses the API plugin.

1. When you upload an agent, ensure you choose Anyone in this workspace in Add a plugin screen.
2. Upload the agent YAML to Security Copilot.

For a YAML sample that uses the API tool, see Build agent using multiple tools. This sample provides you with instructions on how to upload the agent, set up and run the agent in the Active agents.