# Use MyBuddy Built-in Tools in Kalimera

## Feature Overview
MyBuddy provides a wide range of **built-in tools** that can be configured and used in a bot.
The goal is to make these tools available in **Kalimera**, without duplicating logic. Instead of re-implementing them, Kalimera should **consume and invoke MyBuddy’s tools via APIs**.

This feature will allow Kalimera agents to configure and use MyBuddy’s built-in tools seamlessly.

---

### Goals
- Expose MyBuddy built-in tools in a consumable way (via API).
- Enable Kalimera to:
- Retrieve the list of available tools.
- Allow users to configure selected tools in their agent.
- Store tool configuration inside the agent’s definition.
- Invoke the tool via MyBuddy when needed.
- Ensure extensibility for future tools with minimal changes.

---

## Requirements
1. **Expose Tools in MyBuddy**
- Provide an endpoint to list available tools.
- Provide an endpoint to invoke a tool (with required parameters).

2. **Consume Tools in Kalimera**
- Retrieve available tools and display them in the Kalimera UI.
- Allow users to select and configure tools for their agent.
- Store tool configuration in the agent’s configuration schema.
- Each configured tool should include:
- Tool name
- Description
- Parameters (with types and defaults, if any)

3. **Agent Configuration Update**
- When tools are configured, a new node is added to the agent configuration.
- This node contains metadata required for tool invocation.

---

### API Contracts (Draft)

### MyBuddy
- **GET** `/tools` → returns list of available tools

  [
    {
      "name": "Translate",
      "description": "Translates text into the specified language",
      "parameters": {
        "text": "string",
        "target_language": "string"
      }
    }
  ]

- **POST** `/tools/invoke` → invokes a specific tool

  {
    "tool": "Translate",
    "parameters": {
      "text": "Hello world",
      "target_language": "fr"
    }
  }

**Response**

  {
    "result": "Bonjour le monde"
  }

---

### Open Questions

* Should Kalimera cache the available tools list, or always fetch from MyBuddy?
* How will authentication/authorization between Kalimera and MyBuddy work?
* How will errors from MyBuddy be surfaced in Kalimera UI?

---

### Acceptance Criteria

* [ ] MyBuddy exposes an endpoint with the full list of built-in tools.
* [ ] MyBuddy exposes an endpoint to invoke a tool with parameters.
* [ ] Kalimera can display available tools in the UI.
* [ ] Users can configure tools for their agent in Kalimera.
* [ ] The agent’s configuration schema is updated with the tool metadata.
* [ ] The agent can invoke the selected tool via MyBuddy.
* [ ] Tool results are returned to the agent workflow.
* [ ] Error handling is defined.

---

## Tasks per Team

### MyBuddy
- **Responsibilities**
- Implement and expose the following endpoints:
- `GET /tools` → returns list of available tools.
- `POST /tools/invoke` → invokes a tool with given parameters.
- Provide tool metadata (name, description, parameters).
- Handle validation, execution, and error reporting for tool invocation.
- **Order of Work**
- Must be implemented **first**, so Kalimera can consume them.

---

### Kalimera
- **Responsibilities**
- Consume MyBuddy APIs:
- Fetch list of available tools.
- Invoke tools during agent execution.
- Present available tools in the Kalimera UI.
- Allow users to configure tools for their agents.
- Update agent configuration schema with tool metadata.
- **Order of Work**
- Can only start once MyBuddy APIs are available.
- After implementation, outputs updated agent configuration that AIHub can consume.

---

### Orchestrator
- **Responsibilities**
- Consume updated agent configuration from Kalimera.
- Enable new plugins/tools during agent execution based on the configuration.
- **Order of Work**
- Comes **last** in the chain.
- Depends on Kalimera producing the new configuration format.

---

### Chart

    graph TD;
    A[MyBuddy]-->|Send tools|B[Kalimera.ai];
    B[Kalimera.ai]-->|Request tools|A[MyBuddy];
    B[Kalimera.ai]-->|Provide configuration with the selected tools|C[VoiceAI];
    C[VoiceAI] --> |Invoke tools|A[MyBuddy]
   

---

## Test Cases (Examples)

### MyBuddy API

* **GET `/tools`**

* Returns a list of tools in correct schema.
* Returns empty list if no tools are available.

* **POST `/tools/invoke`**

* Returns correct output for valid parameters.
* Returns validation error if parameters are missing/invalid.
* Returns error if tool does not exist.

### Test Case 1

* Google Search
* Given an agent with a Google Search enabled
* The user asks "Which is the adress of the offices of OpenComm in Athens"
* The agent should respond with the correct address

---

## Risks

* **Performance Overhead:** Wrapping MyBuddy APIs introduces latency.
* **Dependency Risk:** Kalimera is tightly coupled to MyBuddy’s API contract.
* **Error Handling:** MyBuddy errors must be mapped correctly in Kalimera.

---

## References

* [Semantic Kernel Plugin Definition](https://learn.microsoft.com/en-us/semantic-kernel/)