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 calledfreeipapi.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), seeBuild 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, seeAuth types.

openapi: 3.0.0info:    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 calledhttp_manifest.yaml that is of the tool formatAPI.

       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 theCustom 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 toSystem Capabilities in Prompts and search forlookupIpAddressGeolocation, which is theoperationId value from the API specification, which you defined inStep 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 chooseAnyone in this workspace inAdd 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, theopenapispec.yaml must be included in the package.

• TheOpenApiSpecUrl must reference the local file path within the package.

• TheEndpointUrl is the publicly hosted endpoint for the OpenAPI spec.

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

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