agent-starter — Starter Pack

Minimal tool-using agent in Python (no heavy frameworks). Tools: search (stub), calc, retrieve (local file).
Updated: 9 Oct 2025

This repository is a starter pack. Don’t clone it for your project.
Create your own repository from this template, or bootstrap from scratch using the steps below.

---

Option A — Use as a GitHub Template (recommended)

1. Click Use this template → Create a new repository in your org/user.
2. Clone your new repository.
3. Follow Run locally below.

---

Option B — Create from scratch

# 1) Project
mkdir my-agent && cd my-agent
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install --upgrade pip

# 2) (Optional) simple search dependency
pip install duckduckgo-search==6.1.0  # or replace with your own search tool

# 3) Agent script
cat > agent.py <<'PY'
from typing import List, Dict, Any
try:
    from duckduckgo_search import DDGS
    HAVE_SEARCH = True
except Exception:
    HAVE_SEARCH = False

def tool_search(q: str, max_results: int = 3) -> List[Dict[str, Any]]:
    if not HAVE_SEARCH:
        return [{"title": "search disabled", "body": "Install duckduckgo-search to enable."}]
    with DDGS() as ddgs:
        return [r for r in ddgs.text(q, max_results=max_results)]

def tool_calc(expr: str) -> Any:
    # minimal, sandboxed eval for arithmetic only
    allowed = {"__builtins__": {}}
    return eval(expr, allowed, {})  # e.g., "3*7+1"

def tool_retrieve(path: str, max_chars: int = 2000) -> str:
    with open(path, "r", encoding="utf-8", errors="ignore") as f:
        return f.read(max_chars)

def agent(task: str) -> Any:
    task = task.strip()
    if task.startswith("search:"):
        return tool_search(task.split(":", 1)[1].strip())
    if task.startswith("calc:"):
        return tool_calc(task.split(":", 1)[1].strip())
    if task.startswith("read:"):
        return tool_retrieve(task.split(":", 1)[1].strip())
    return "No tool matched. Use: 'search:<query>' | 'calc:<expr>' | 'read:<path>'"

if __name__ == "__main__":
    # examples
    print(agent("calc:2+2"))
    print(agent("search:Turku weather"))
    print(agent("read:README.md"))
PY

---

Run locally

# activate venv if not active
source .venv/bin/activate  # Windows: .venv\Scripts\activate

python agent.py
# or pass tasks:
python -c "import agent; print(agent.agent('calc:3*7+1'))"

---

Minimal project structure

agent.py            # agent + tools (search/calc/read)
.venv/              # local virtual env (not committed)

---

Extend the agent

• Add tools as plain functions (e.g., tool_fetch_api, tool_sql).
• Route by simple prefixes ("api:", "sql:"), or swap to a parser.
• Keep each tool pure and testable (no global state).

---

Safety notes

• The calc tool uses eval with builtins disabled (arithmetic only). Do not pass untrusted input in production.
• For file access, restrict to a safe directory and validate paths before reading.
• If you add network tools, enforce timeouts and domain allowlists.

---

Common tasks

pip install -U duckduckgo-search  # enable search
pip freeze > requirements.txt     # optional: pin deps
pytest -q                         # add tests when ready

---

License: MIT