> For the complete documentation index, see [llms.txt](https://docs.amesa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amesa.com/build-multi-agent-systems/define-skills/configure-api-connections-to-third-party-software-as-skills.md).

# Configure API Connections to Third-Party Software as Skill Agents

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

We will create a **programmed 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 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 Agent

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

```python
import requests 
from amesa import AgentController

# Define the programmed skill 
class ThirdPartyAPISkill(AgentController): 

    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 Agent to the Orchestration

#### 2.1. Adding the Agent to the AMESA Agent Orchestration Studio

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

1. Create a new 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"

```shell
amesa agent new
```

2. 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:

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

entrypoint = "third_party_api_skill.controller:ThirdPartyAPISkill"
```

3. Publish the Skill Agent to the UI

```shell
amesa login
```

```shell
amesa agent publish third_party_api_skill
```

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

#### 2.2. Adding the Skill Agent to AMESA SDK

Once the agent is defined, you can add it to your agent system using the `add_agent()` 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:

```python
# Define and add the third-party API skill agent
third_party_skill = Agent("third_party_api", ThirdPartyAPISkill) 
orchestration.add_agent(third_party_skill) 
```

By importing and creating the class with `AgentController`, 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 agent** that communicates with a third-party API into your AMESA orchestration. The orchestration 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 orchestrators ensures the agent system executes the correct skill agents at the right time, whether the agents are learned or programmed.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amesa.com/build-multi-agent-systems/define-skills/configure-api-connections-to-third-party-software-as-skills.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.