Add an API tool (plugin) to your agent

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

This example demonstrates creating an Agent that leverages a plugin with an API tool to connect to a REST API service called freeipapi.com, which provides Geo-IP lookup functionality.

The overall process is as follows:

1. Step 1: Create and publish an OpenAPI specification that defines the API

2. Step 2: Create and upload the manifest file to Security Copilot

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

4. Step 4: Publish package to Security Store (applicable only for partner agents)

   Note

   For a manifest YAML sample that uses the API tool (skill), see Build agent using multiple tools. It provides you with instructions on how to upload the agent, set up and run the agent published on the Active agents page.

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. For examples on authentication, see Auth types.

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 openapispec.yaml schema created in Step 1>
             EndpointUrl: https://sampleurl <The server endpoint that is hosting the API>
   

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.

Step 4: (optional) Publish package to Security Store

This step is applicable only to partners developing their agent that must be published to Security Store.

Important considerations for publishing an API manifest to the Security Store:

• When publishing your package to Security Store, the openapispec.yaml must be included in the package.

• The OpenApiSpecUrl must reference the local file path within the package.

• The EndpointUrl is the publicly hosted endpoint for the OpenAPI spec.

• If the ChildSkills are referenced in an Open API specification, ensure that the global URL for your OpenAPISpec and the local OpenAPISpec yaml are up-to-date.

• The openapispec.yaml must be in the same folder as the Agent manifest yaml(http_manifest.yaml) and must follow the naming convention: openapispec_<number>.yaml.