​
Module Summary

  • Goal: Customize agent loops, add Python tools, and run the agent locally
  • Prerequisites: Python 3.12, Node.js v22

​
What you’ll do in This module

In this module, you’ll gain full control over your agent’s behavior.

You’ll learn how to:

  • Run your agent locally via a Jupyter notebook.
  • Customize the agent loop, allowing advanced logic or prompt shaping
  • Add your own Python tools to expand what the agent can do

​
Environment Setup

ToolRequired Version
Python3.12.7
Node.jsv22

Use pyenv and nvm to manage these versions if needed:

python3 --version     # 3.12.7
node --version        # v22.x

​
Clone the template repository

git clone https://github.com/xpander-ai/xpander.ai.git
cd xpander.ai/Getting-Started/hello-world
python3 -m venv .venv
source .venv/bin/activate

​
CLI Login & Agent Initialization

Install the CLI and initialize your agent:

npm i -g xpander-cli
xpander login
xpander initialize

To get the Agent ID of your SWE agent for the initialization part:

  1. Go back to the AI Workbench
  2. Click the “SDK” trigger node, at the top part of the canvas
  3. Copy the Agent ID from there, and paste it in the CLI prompt

This creates the following files:

  • xpander_config.json
  • agent_instructions.json
  • requirements.txt

​
Install agent dependencies

pip install -r requirements.txt
mv .env.example .env

Fill in the required values in .env:

If you’re running the workshop in an event, get the OpenAI key from the event’s Notes file, or use your own key.

OPENAI_MODEL_ID=gpt-4.1
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Run the agent via a Jupyter notebook.

Here, we’ll step through the agent lifecycle. Open my_agent.ipynb in VSCode, Cursor, Jupyter Lab, or any notebook viewer.

Run through the notebook, and then come back to this guide to add local tools in the next step.

​
Add a Local Tool to Star a GitHub Repository (Optional)

In this step, you’ll enable your agent to run a custom tool that stars a GitHub repository.

​
1. Generate a GitHub Token

First, create a GitHub personal access token:
👉 Generate Token

⏳ Note: Make sure to select full repo access scope in order to star a repo.

​
2. Add the Token to Your .env File

Update your .env file with the following:

OPENAI_MODEL_ID=gpt-4.1                            # Your existing model ID
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # Your existing OpenAI key
GITHUB_TOKEN=YOUR_TOKEN_GOES_HERE                  # Paste your GitHub token here

​
🧩 3. Define the Custom Tool

Replace the contents of tools/local_tools.py with:

import requests
from os import getenv

def star_github_repo(repo_full_name: str):
    result = {"success": False, "message": ""}
    try:
        token = getenv("GITHUB_TOKEN")
        if not token:
            result["message"] = "Error: GITHUB_TOKEN not found in environment variables."
            return result

        url = f"https://api.github.com/user/starred/{repo_full_name}"
        headers = {
            "Authorization": f"token {token}",
            "Accept": "application/vnd.github+json",
        }

        response = requests.put(url, headers=headers)
        result["success"] = response.status_code == 204
        result["message"] = "Done" if result["success"] else "Failed"
    except Exception as e:
        result["message"] = str(e)

    return result

local_tools = [
    {
        "declaration": {
            "type": "function",
            "function": {
                "name": "star_github_repo",
                "description": "Star a GitHub repository",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "repo_full_name": {
                            "type": "string",
                            "description": "Full name of the repository (e.g. xpander-ai/xpander.ai)"
                        }
                    },
                    "required": ["repo_full_name"]
                }
            }
        },
        "fn": star_github_repo
    }
]

# Helper mappings
local_tools_list = [tool["declaration"] for tool in local_tools]
local_tools_by_name = {tool["declaration"]["function"]["name"]: tool["fn"] for tool in local_tools}

​
🔄 4. Reload the Agent

Add a new cell to reinitialize the agent with the updated tools:

agent = MyAgent(xpander_agent)  # The agent will now include the updated local tools

​
🤖 5. Ask the Agent to Star a Repository

Add a new cell to send a prompt to the agent:

# Ask the agent to star a specific repo
await agent.chat("star repo xpander-ai/xpander.ai")

​
Agent activated. GitHub stars beware — you’ve built a coding assassin. 💻