# Deploy an AI Agent

### Prerequisites

* Latest version of [python package](/documentation-hackerbot-industries/software/python-package.md) installed
* Python virtual environment configured
* Microphone and speaker connected to your robot
* Hackerbot AI + recommended
* Access to [Google Gemini API](https://ai.google.dev/) (or equivalent LLM provider)

***

### Setup

Move into the Hackerbot tutorials directory where the LLM scripts are located:

```sh
cd ~/hackerbot/hackerbot-tutorials/AI
```

Install the Python libraries required:

```sh
pip install -r requirements.txt
# Or with uv
uv pip install -r requirements.txt
```

***

### Obtain an API Key from Gemini

1. Go to [Google AI Studio](https://aistudio.google.com/app/apikey).
2. Sign in with your Google account.
3. Create a new API Key.
4. Copy the generated key — you’ll need it for the next step.

***

### Set Up the `.env` File

Create a `.env` file in the directory `~/hackerbot/hackerbot-tutorials/` if it does not exist:

```sh
touch .env
```

Open `.env` and add your Gemini API key:

```sh
GOOGLE_API_KEY=your-api-key-here
```

***

### Customize the AI Agent

The behavior and response format of your Hackerbot AI agent can be customized inside `speak_w_gemini.py` (or your main script).

Here are the important sections:

#### 1. Configure the Agent’s **Personality**

You can set the *tone* or *role* of the AI when initializing the chat history:

```python
chat = model.start_chat(history=[
    {
        "role": "user",
        "parts": [{"text": 
            "You are a colleague named Robby, and you are experiencing Monday blues.\n"
            ...
        }]
    },
    ...
])
```

> **Tip:**\
> You can modify the personality to make the robot more cheerful, formal, or specialized (e.g., teacher, tour guide, etc.).

Example alternatives:

* "You are an enthusiastic personal trainer motivating someone to exercise."
* "You are a formal assistant robot trained to help users navigate a warehouse."

***

#### 2. Configure the agent's voice

In the `speak` function inside `actions.py`, make sure you load the appropriate Piper TTS model. For details on how to do this, check the [documentation here](/documentation-hackerbot-industries/tutorials/basic-examples.md#voice).

#### 3. Configure the **Response Format**

The Gemini agent is instructed to only respond with raw JSON.\
This allows the robot to *parse actions reliably* without extra text.

Example of the prompt instructions:

```python
Respond ONLY with JSON in one of the following formats:
- {"action": "action_name"}
- {"action": "speak", "parameters": {"text": "your text"}}
- or a list of such objects if you want the robot to perform multiple actions.

DO NOT add explanations.
DO NOT use markdown formatting (like triple backticks).
```

This strict format ensures the robot can easily extract and execute actions from the AI’s response.

***

#### 4. Add New Supported **Actions**

{% hint style="info" %}
In the original example, head movement actions are included. If your robot doesn't have a head, feel free to exclude those actions from the supported list.
{% endhint %}

Supported actions are listed in the same prompt:

```python
Supported actions are: shake_head, nod_head, look_left, look_right, look_up, look_down, spin_right, spin_left, spin_around, and speak.
```

If you want to add a new action, you must:

1. Define the function in `actions.py`:

   ```python
   def wave_hand():
       print("Waving hand!")
       # Add your robot command here
   ```
2. Update the *`execute_robot_action`* function in `utils.py`:

   ```python
   "new_action":  lambda: new_action(bot),
   ```
3. Update the Gemini prompt to include the new action name:

   ```python
   Supported actions are: new_action, shake_head, nod_head, wave_hand, look_left, look_right, ...
   ```

This tells Gemini it can now trigger the new action.

***

### Run the Robot Assistant

After everything is configured, start the assistant:

```sh
python3 speak_w_gemini.py
```

The robot will:

* Listen for your voice commands
* Send them to Gemini
* Parse the response
* Execute the requested action(s)

***

### Troubleshooting

* **Authentication Error**:\
  Make sure `.env` is correctly set with your API key.
* **Speech Recognition Error**:\
  Ensure your microphone is accessible and configured, and `espeak` or `espeak-ng` is installed.
* **Action Not Triggering**:\
  Confirm the action function exists in `actions.py` and the action name matches the prompt.
* **Gemini Response Invalid**:\
  If Gemini returns invalid JSON, double-check your prompt to enforce strict JSON responses.

***

## Summary

By following these steps, you can successfully deploy an LLM-powered interaction system on Hackerbot.\
You can expand functionality further by adding new actions, switching to other LLM APIs, or enhancing the user input handling.


---

# Agent Instructions: 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:

```
GET https://hackerbot-industries.gitbook.io/documentation-hackerbot-industries/tutorials/deploy-an-ai-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.