Configure API Connections to Third-Party Software as Skills

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

We will create a programmed skill 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 within your agent.

---

Step 1: Defining the Programmed Skill

A programmed skill in Composabl 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 will act based on the information received.

1.1. Creating the API Integration Skill

We’ll define a programmed skill for making the API request. Here's an example of how to define the skill 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 to take based on the data.

Step 2: Adding the Programmed Skill to the Agent

2.1. Adding the Skill to Composabl UI

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

1. Create a new Skill using the Composabl 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"

entrypoint = "third_party_api_skill.controller:ThirdPartyAPISkill"

1. Publish the Skill 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 to Composabl SDK

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

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

# Define and add the third-party API skill 
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 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 that communicates with a third-party API into your Composabl agent. The agent can now take actions based on external data and dynamically respond to scenarios.

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

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