Configure API Connections to Third-Party Software as Skill Agents

In this tutorial, we will walk through how to set up a skill agent in AMESA that integrates with a third-party API. This type of integration allows your agent system to communicate with external systems, such as machine performance APIs, and use the data to make informed decisions.

We will create a programmed skill agent that connects to a mock third-party API, process its response, and return an action based on the data received. This tutorial will also touch on orchestrating this skill agent within your agent system.

---

Step 1: Defining the Programmed Skill Agent

A programmed skill agent in AMESA is created by specifying the logic for interacting with the external API and processing the response. In this case, we will create a simple API connection to a fake endpoint that returns data about machine performance. The agent system will act based on the information received.

1.1. Creating the API Integration Skill Agent

We’ll define a programmed skill agent for making the API request. Here's an example of how to define the skill agent using a controller function that calls the API and processes the response.

import requests 
from composabl import SkillController

# Define the programmed skill 
class ThirdPartyAPISkill(SkillController): 

    def __init__(self, *args, **kwargs):
        self.api_url = "https://api.example.com/machine-status" 

    async def compute_action(self, obs, action):
        # Send sensor data to the third-party API 
        response = self._call_api(obs) 
        # Process the response and return an action 
        action = self._process_response(response) 
        return action
  
    def _call_api(self, observation): 
        try: 
            response = requests.post( 
                self.api_url,  
                json=observation,  
                headers={'Content-Type': 'application/json'} 
            ) 
            response.raise_for_status() 
            return response.json() 

        except requests.RequestException as e: 
            print(f"API call failed: {e}") 
            return None 

    def _process_response(self, response): 
        if not response:
            # Default action 
            return 0.0

        action = float(response.get("action"))
        reason = response.get("reason", "No reason provided") 

        print(f"Action: {action} - Reason: {reason}") 
        return action

    async def transform_sensors(self, obs):
        return obs

    async def filtered_sensor_space(self):
        return ['sensor1', 'sensor2', 'sensor3']

    async def compute_success_criteria(self, transformed_obs, action):
        return False

    async def compute_termination(self, transformed_obs, action):
        return False

In this example:

• The compute_action() method sends observation data (e.g., from sensors) to a third-party API.

• The _call_api() function makes the API call and handles any errors that might occur.

• The _process_response() function processes the response from the third-party API and determines the appropriate action for the agent system to take based on the data.

Step 2: Adding the Programmed Skill Agent to the Agent System

2.1. Adding the Skill Agent to AMESA UI

Once the skill agent is defined, you can add it to your agent system in the UI using the methods below:

1. Create a new Skill Agent using the AMESA CLI with a given name and description and implementation type, that in this case will be a controller. The name will be "third_party_api_skill"

composabl skill new

1. Change the controller.py code to use the class that you created: ThirdPartyAPISkill(). Change the pyproject.toml file to include your class ThirdPartyAPISkill in the entrypoint and its name:

[project]
name = "Third Party API Skill Agent"

entrypoint = "third_party_api_skill.controller:ThirdPartyAPISkill"

1. Publish the Skill Agent to the UI

composabl login

composabl skill publish third_party_api_skill

Select your organization and project that you want to publish it to.

Reference: https://docs.composabl.io/changelog/0-8-0.html

2.2. Adding the Skill Agent to AMESA SDK

Once the skill agent is defined, you can add it to your agent system using the add_skill() SDK method. This allows the agent system to execute the API connection skill agent when necessary.

Here’s how to add the ThirdPartyAPISkill to the skill agent:

# Define and add the third-party API skill agent
third_party_skill = Skill("third_party_api", ThirdPartyAPISkill) 
agent.add_skill(third_party_skill) 

By importing and creating the class with SkillController, you are indicating that this skill agent is programmed and does not require training. It will use predefined logic to interact with the third-party API and make decisions based on the data returned.

---

Conclusion

By following these steps, you’ve successfully defined and integrated a programmed skill agent that communicates with a third-party API into your AMESA agent system. The agent system can now take actions based on external data and dynamically respond to scenarios.

This approach allows agent systems to interface with a wide range of external systems, from monitoring equipment to adjusting machine settings, all through programmable skill agents.

Orchestration of skill agents through selectors ensures the agent system executes the correct skill agents at the right time, whether the skill agents are learned or programmed.