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 the OpenAPI specification that defines the API

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

3. Step 3: Upload the 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 the OpenAPI specification

The following sections explain how to build an agent using an API plugin and OpenAPI specification for geolocation lookups.

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.

4. Search for lookupIpAddressGeolocation, which is the operationId value from the API specification, which you defined in Step 1.

   👁 Image of the tool lookup in Security Copilot
   

   The response after executing the tool is displayed.

   👁 Image of the tool run response in Security Copilot
   

Step 3: Upload the 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: Publish package to Security Store (optional)

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.