Smolagents: Framework AI Agent Ringan dari HuggingFace

Pendahuluan

Smolagents adalah framework AI agent yang ringan dan minimalis dari HuggingFace, dirancang untuk membangun AI agents dengan pendekatan code-first. Berbeda dengan framework agent lain yang cenderung kompleks dan heavy, Smolagents fokus pada kesederhanaan sambil tetap menyediakan fitur-fitur powerful seperti multi-step reasoning, custom tool creation, dan multi-agent orchestration.

Framework ini sangat cocok untuk developer yang ingin membangun AI agents tanpa overhead yang berlebihan. Smolagents menggunakan pendekatan unik dimana agent menghasilkan kode Python sebagai "aksi" alih-alih menggunakan format JSON yang kaku, membuat agent lebih fleksibel dan expressive.

Dalam tutorial ini, kita akan mempelajari cara menggunakan Smolagents mulai dari instalasi, memahami tipe agent, membuat custom tools, hingga membangun research agent yang dapat mencari informasi di web, memproses data, dan menghasilkan laporan.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

• Python 3.10 atau lebih baru
• pip package manager
• API key dari HuggingFace, OpenAI, atau Anthropic
• Pemahaman dasar Python dan konsep AI/LLM

Instalasi

Instalasi Dasar

# Instal smolagents
pip install smolagents

Instal dengan dependensi tambahan untuk semua fitur
pip install smolagents[all]

Atau instal dependensi spesifik
pip install smolagents[openai]      # Untuk OpenAI
pip install smolagents[anthropic]   # Untuk Anthropic
pip install smolagents[gradio]      # Untuk Gradio UI
pip install smolagents[telemetry]   # Untuk monitoring

Verifikasi Instalasi

import smolagents
print(f"Smolagents version: {smolagents.version}")

Test basic import
from smolagents import CodeAgent, HfApiModel
print("Import successful!")

Setup Environment Variables

# Untuk HuggingFace
export HFTOKEN="hfyourtokenhere"

Untuk OpenAI
export OPENAIAPIKEY="sk-your-key-here"

Untuk Anthropic
export ANTHROPICAPIKEY="sk-ant-your-key-here"

CodeAgent vs ToolCallingAgent

Smolagents menyediakan dua tipe agent utama yang memiliki pendekatan berbeda dalam menyelesaikan tugas.

CodeAgent

CodeAgent menghasilkan dan mengeksekusi kode Python sebagai aksinya. Ini adalah tipe agent yang direkomendasikan karena lebih fleksibel dan efisien.

from smolagents import CodeAgent, HfApiModel

Inisialisasi model
model = HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct")


Buat CodeAgent
agent = CodeAgent(
    tools=[],  # Tanpa tools tambahan
    model=model,
    maxsteps=5
)

Jalankan agent
result = agent.run("Hitung rata-rata dari angka berikut: 15, 28, 42, 37, 56")
print(result)

Keunggulan CodeAgent:

• Menghasilkan kode Python yang bisa melakukan komputasi kompleks
• Lebih efisien karena bisa menggabungkan beberapa operasi dalam satu langkah
• Mendukung variabel dan logic flow
• Output lebih mudah di-debug

ToolCallingAgent

ToolCallingAgent menggunakan format tool calling standar (mirip function calling di OpenAI). Agent ini memanggil tools satu per satu dalam format JSON.

from smolagents import ToolCallingAgent, HfApiModel

Inisialisasi model
model = HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct")


Buat ToolCallingAgent
agent = ToolCallingAgent(
    tools=[],
    model=model,
    maxsteps=5
)

Jalankan agent
result = agent.run("Berapa hasil dari 25  48?")

print(result)

from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool

Inisialisasi search tool
searchtool = DuckDuckGoSearchTool()


Buat agent dengan search tool
agent = CodeAgent(
    tools=[searchtool],
    model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),

    maxsteps=5
)

Cari informasi
result = agent.run("Cari informasi terbaru tentang perkembangan AI di Indonesia")
print(result)

from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    tools=[],
    model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),

    additionalauthorizedimports=["numpy", "pandas", "matplotlib"],

    maxsteps=5
)

Agent bisa menggunakan library yang diizinkan
result = agent.run("""
Buat array numpy berisi 100 angka random,
hitung mean, median, dan standard deviation-nya
""")
print(result)

from smolagents import CodeAgent, HfApiModel, VisitWebpageTool

Tool untuk mengunjungi dan membaca halaman web
visittool = VisitWebpageTool()


agent = CodeAgent(
    tools=[visittool],
    model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),

    maxsteps=5
)

result = agent.run("Baca halaman https://huggingface.co/blog dan rangkum artikel terbaru")
print(result)

from smolagents import tool, CodeAgent, HfApiModel

@tool
def getweather(city: str) -> str:

    """
    Mendapatkan informasi cuaca untuk kota tertentu.

    Args:
        city: Nama kota yang ingin dicek cuacanya

    Returns:
        String berisi informasi cuaca
    """
    import requests
    apikey = "yourweatherapikey"

    url = f"http://api.openweathermap.org/data/2.5/weather?q={city}&appid={apikey}&units=metric"

    response = requests.get(url)
    data = response.json()

    if response.statuscode == 200:

        temp = data['main']['temp']
        desc = data['weather'][0]['description']
        humidity = data['main']['humidity']
        return f"Cuaca di {city}: {desc}, Suhu: {temp}°C, Kelembaban: {humidity}%"
    else:
        return f"Tidak bisa mendapatkan data cuaca untuk {city}"

Gunakan tool dalam agent
agent = CodeAgent(
    tools=[getweather],
    model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),

    maxsteps=5
)

result = agent.run("Bagaimana cuaca di Jakarta hari ini?")
print(result)

@tool
def searchdatabase(query: str, table: str, limit: int = 10) -> str:

    """
    Mencari data di database berdasarkan query.

    Args:
        query: Kata kunci pencarian
        table: Nama tabel yang ingin dicari
        limit: Jumlah maksimum hasil yang dikembalikan

    Returns:
        Hasil pencarian dalam format string
    """
    import sqlite3
    conn = sqlite3.connect("app.db")
    cursor = conn.cursor()

    cursor.execute(
        f"SELECT  FROM {table} WHERE content LIKE ? LIMIT ?",
        (f"%{query}%", limit)
    )

    results = cursor.fetchall()
    conn.close()

    if results:
        return f"Ditemukan {len(results)} hasil:\n" + "\n".join(str(r) for r in results)
    else:
        return "Tidak ditemukan hasil yang sesuai"

from smolagents import Tool

class EmailSenderTool(Tool):
    name = "sendemail"
    description = "Mengirim email ke alamat tertentu dengan subjek dan isi yang diberikan"
    inputs = {
        "to": {
            "type": "string",
            "description": "Alamat email penerima"
        },
        "subject": {
            "type": "string",
            "description": "Subjek email"
        },
        "body": {
            "type": "string",
            "description": "Isi email"
        }
    }
    outputtype = "string"


    def forward(self, to: str, subject: str, body: str) -> str:
        import smtplib
        from email.mime.text import MIMEText

        msg = MIMEText(body)
        msg['Subject'] = subject
        msg['From'] = "agent@example.com"
        msg['To'] = to

        try:
            with smtplib.SMTP('smtp.example.com', 587) as server:
                server.starttls()
                server.login("agent@example.com", "password")
                server.sendmessage(msg)
            return f"Email berhasil dikirim ke {to}"
        except Exception as e:
            return f"Gagal mengirim email: {str(e)}"

Gunakan tool
emailtool = EmailSenderTool()

from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool

agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),
    maxsteps=10,  # Izinkan lebih banyak langkah

    verbose=True   # Tampilkan proses reasoning
)

result = agent.run("""
Lakukan analisis berikut:
Cari 3 perusahaan AI terbesar di Indonesia
Untuk setiap perusahaan, cari informasi tentang produk utama mereka
Bandingkan dan buat ringkasan perbandingan
""")
print(result)

agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),
    maxsteps=10,

    planninginterval=3  # Agent membuat rencana setiap 3 langkah
)

Integrasi Model

HuggingFace Inference API

from smolagents import CodeAgent, HfApiModel

Menggunakan model dari HF Hub
model = HfApiModel(
    modelid="Qwen/Qwen2.5-Coder-32B-Instruct",

    token="hfyourtoken"

)

agent = CodeAgent(tools=[], model=model)

from smolagents import CodeAgent, OpenAIServerModel

Menggunakan OpenAI
model = OpenAIServerModel(
    modelid="gpt-4o",
    apikey="sk-your-key"

)

agent = CodeAgent(tools=[], model=model)

from smolagents import CodeAgent, AnthropicServerModel

Menggunakan Anthropic Claude
model = AnthropicServerModel(
    modelid="claude-sonnet-4-20250514",
    apikey="sk-ant-your-key"

)

agent = CodeAgent(tools=[], model=model)

from smolagents import CodeAgent, OpenAIServerModel

Menggunakan model lokal via Ollama
model = OpenAIServerModel(
    modelid="llama3.1:8b",
    apibase="http://localhost:11434/v1",

    apikey="ollama"  # Ollama tidak memerlukan key
)

agent = CodeAgent(tools=[], model=model)

Agent dengan Memory

Smolagents mendukung memory untuk mempertahankan konteks antar interaksi.

from smolagents import CodeAgent, HfApiModel

Buat agent
agent = CodeAgent(
    tools=[],
    model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),

    maxsteps=5
)

Interaksi pertama
result1 = agent.run("Nama saya Budi dan saya seorang data scientist")
print(result1)

Interaksi kedua - agent mengingat konteks sebelumnya
result2 = agent.run("Siapa nama saya dan apa pekerjaan saya?")
print(result2)

Persistent Memory dengan File

import json
from smolagents import tool

@tool
def savememory(key: str, value: str) -> str:

    """
    Menyimpan informasi ke memory persisten.

    Args:
        key: Kunci untuk menyimpan informasi
        value: Nilai yang ingin disimpan

    Returns:
        Konfirmasi penyimpanan
    """
    try:
        with open("agentmemory.json", "r") as f:
            memory = json.load(f)
    except FileNotFoundError:
        memory = {}

    memory[key] = value

    with open("agentmemory.json", "w") as f:

        json.dump(memory, f, indent=2)

    return f"Berhasil menyimpan: {key} = {value}"

@tool
def recallmemory(key: str) -> str:
    """
    Mengambil informasi dari memory persisten.

    Args:
        key: Kunci informasi yang ingin diambil

    Returns:
        Nilai yang tersimpan atau pesan tidak ditemukan
    """
    try:
        with open("agentmemory.json", "r") as f:

            memory = json.load(f)
        return memory.get(key, f"Tidak ada informasi untuk kunci: {key}")
    except FileNotFoundError:
        return "Memory masih kosong"

from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool, ManagedAgent

model = HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct")

Agent spesialis untuk riset web
webresearcher = CodeAgent(

    tools=[DuckDuckGoSearchTool()],
    model=model,
    maxsteps=5
)

Bungkus sebagai ManagedAgent
managedresearcher = ManagedAgent(

    agent=webresearcher,
    name="webresearcher",

    description="Agent yang ahli dalam mencari dan menganalisis informasi dari internet. Gunakan agent ini ketika perlu mencari fakta, data, atau informasi terbaru."
)

Agent spesialis untuk analisis data
dataanalyst = CodeAgent(
    tools=[],
    model=model,
    additionalauthorizedimports=["numpy", "pandas"],
    maxsteps=5

)

managedanalyst = ManagedAgent(
    agent=dataanalyst,

    name="dataanalyst",
    description="Agent yang ahli dalam analisis data menggunakan Python. Gunakan agent ini untuk komputasi statistik, analisis dataset, dan visualisasi data."
)

Agent utama (orchestrator)
manageragent = CodeAgent(

    tools=[],
    model=model,
    managedagents=[managedresearcher, managedanalyst],
    maxsteps=10

)

Jalankan tugas kompleks
result = manageragent.run("""
Lakukan riset tentang pertumbuhan ekonomi digital di Asia Tenggara:
Cari data dan statistik terbaru
Analisis tren pertumbuhan
Buat ringkasan dengan insight utama
""")
print(result)

Pattern Multi-Agent yang Umum

# Pattern: Researcher + Writer
researcher = ManagedAgent(
    agent=CodeAgent(
        tools=[DuckDuckGoSearchTool()],
        model=model,
        maxsteps=5

    ),
    name="researcher",
    description="Mencari dan mengumpulkan informasi dari internet"
)

writer = ManagedAgent(
    agent=CodeAgent(
        tools=[],
        model=model,
        maxsteps=5
    ),
    name="writer",
    description="Menulis konten berdasarkan informasi yang diberikan"
)

Manager mengoordinasi researcher dan writer
manager = CodeAgent(
    tools=[],
    model=model,
    managedagents=[researcher, writer],

    maxsteps=10
)

Integrasi Gradio UI

Smolagents dapat diintegrasikan dengan Gradio untuk membuat antarmuka chat interaktif.

from smolagents import CodeAgent, HfApiModel, DuckDuckGoSearchTool, GradioUI

Buat agent
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),

    maxsteps=5
)

Luncurkan Gradio UI
ui = GradioUI(agent)
ui.launch(
    servername="0.0.0.0",

    serverport=7860,
    share=False
)

Setelah dijalankan, buka browser di http://localhost:7860 untuk mengakses antarmuka chat.

Kustomisasi Gradio UI

ui = GradioUI(
    agent,
    fileuploadfolder="./uploads",  # Folder untuk file yang diupload
)
ui.launch(
    servername="0.0.0.0",

    serverport=7860,
    share=True  # Buat public URL via Gradio
)

Contoh Praktis: Research Agent

Sekarang kita akan membangun research agent lengkap yang dapat mencari informasi di web, memproses data, dan menghasilkan laporan terstruktur.

Setup Project

mkdir research-agent && cd research-agent
pip install smolagents[all] python-dotenv

Membuat Custom Tools

# tools.py
import json
from datetime import datetime
from smolagents import tool

@tool
def savereport(title: str, content: str, format: str = "md") -> str:

    """
    Menyimpan laporan ke file.

    Args:
        title: Judul laporan
        content: Isi laporan
        format: Format file (md atau txt)

    Returns:
        Konfirmasi penyimpanan dengan path file
    """
    timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
    filename = f"reports/{title.lower().replace(' ', '')}{timestamp}.{format}"

    import os
    os.makedirs("reports", existok=True)


    with open(filename, "w") as f:
        f.write(content)

    return f"Laporan berhasil disimpan di: {filename}"

@tool
def analyzetext(text: str, analysistype: str) -> str:

    """
    Menganalisis teks dengan berbagai metode.

    Args:
        text: Teks yang akan dianalisis
        analysistype: Tipe analisis (wordcount, sentiment, summarystats)

    Returns:
        Hasil analisis dalam format string
    """
    if analysistype == "wordcount":
        words = text.split()
        sentences = text.split('.')
        paragraphs = text.split('\n\n')
        return json.dumps({
            "words": len(words),
            "sentences": len(sentences),
            "paragraphs": len(paragraphs),
            "avgwordspersentence": len(words) / max(len(sentences), 1)

        }, indent=2)

    elif analysistype == "summarystats":

        words = text.split()
        uniquewords = set(w.lower() for w in words)
        return json.dumps({
            "totalwords": len(words),

            "uniquewords": len(uniquewords),

            "vocabularyrichness": len(uniquewords) / max(len(words), 1),

            "mostcommon": max(set(words), key=words.count) if words else ""
        }, indent=2)

    else:
        return f"Tipe analisis '{analysistype}' tidak dikenal"


@tool
def formatreport(title: str, sections: str) -> str:
    """
    Memformat laporan penelitian dengan template standar.

    Args:
        title: Judul laporan
        sections: Konten sections dalam format JSON string

    Returns:
        Laporan terformat dalam markdown
    """
    try:
        sectiondata = json.loads(sections)

    except json.JSONDecodeError:
        return "Error: sections harus berupa valid JSON string"

    report = f"# {title}\n\n"
    report += f"Tanggal: {datetime.now().strftime('%d %B %Y')}\n"
    report += f"Generated by: Research Agent (Smolagents)\n\n"

    for section in sectiondata:
        report += f"## {section.get('heading', 'Untitled')}\n\n"
        report += f"{section.get('content', '')}\n\n"

    report += "## Disclaimer\n\n"
    report += "Laporan ini dihasilkan secara otomatis oleh AI Research Agent. "
    report += "Verifikasi data dan fakta diperlukan sebelum penggunaan resmi.\n"

    return report

Membangun Research Agent

# researchagent.py
from smolagents import (
    CodeAgent, HfApiModel, OpenAIServerModel,
    DuckDuckGoSearchTool, VisitWebpageTool, ManagedAgent
)
from tools import savereport, analyzetext, formatreport

Pilih model
model = OpenAIServerModel(modelid="gpt-4o")


Agent khusus riset web
webagent = CodeAgent(
    tools=[DuckDuckGoSearchTool(), VisitWebpageTool()],
    model=model,
    maxsteps=8,

    name="webresearcher",
    description="Mencari informasi dari internet"
)

managedweb = ManagedAgent(

    agent=webagent,
    name="webresearcher",

    description="Agent yang mencari dan mengumpulkan informasi dari internet. Berikan topik spesifik untuk dicari."
)

Agent khusus analisis dan penulisan
analysisagent = CodeAgent(
    tools=[analyzetext, formatreport, savereport],

    model=model,
    additionalauthorizedimports=["json", "datetime"],

    maxsteps=5,
    name="analystwriter",

    description="Menganalisis data dan menulis laporan"
)

managedanalyst = ManagedAgent(
    agent=analysisagent,

    name="analystwriter",
    description="Agent yang menganalisis data teks dan menulis laporan terformat. Berikan data mentah untuk dianalisis dan ditulis menjadi laporan."
)

Agent utama (orchestrator)
researchmanager = CodeAgent(

    tools=[],
    model=model,
    managedagents=[managedweb, managedanalyst],
    maxsteps=12,

    verbose=True
)

Jalankan riset
result = researchmanager.run("""
Lakukan riset mendalam tentang perkembangan Large Language Models (LLM)
open-source di tahun 2025-2026. Fokus pada:
Model-model open-source terbaru dan performanya
Perbandingan dengan model proprietary
Tren adopsi di industri dan startup
Prediksi perkembangan ke depan

Hasilkan laporan penelitian yang komprehensif dan simpan ke file.
""")

print("Riset selesai!")
print(result)

Menjalankan Research Agent

# Jalankan research agent
python researchagent.py

# app.py
from smolagents import CodeAgent, OpenAIServerModel, DuckDuckGoSearchTool, VisitWebpageTool, GradioUI
from tools import savereport, analyzetext, formatreport

model = OpenAIServerModel(modelid="gpt-4o")


agent = CodeAgent(
    tools=[
        DuckDuckGoSearchTool(),
        VisitWebpageTool(),
        analyzetext,
        formatreport,

        savereport
    ],
    model=model,
    additionalauthorizedimports=["json", "datetime"],
    maxsteps=10,

    verbose=True
)

Luncurkan UI
ui = GradioUI(agent)
ui.launch(servername="0.0.0.0", serverport=7860)

# Batasi imports yang diizinkan
agent = CodeAgent(
    tools=[],
    model=model,
    additionalauthorizedimports=["numpy", "pandas"],

    # Jangan izinkan os, subprocess, dll untuk keamanan
    maxsteps=5
)

Error Handling

from smolagents import CodeAgent, HfApiModel

try:
    agent = CodeAgent(
        tools=[],
        model=HfApiModel(modelid="Qwen/Qwen2.5-Coder-32B-Instruct"),

        maxsteps=5
    )
    result = agent.run("Analisis data ini")
except Exception as e:
    print(f"Agent error: {e}")
    # Fallback logic

Optimasi Performa

# Batasi jumlah langkah untuk menghemat token
agent = CodeAgent(
    tools=[],
    model=model,
    maxsteps=5,  # Jangan terlalu banyak

)

Gunakan system prompt yang spesifik
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
    systemprompt="""Kamu adalah research assistant yang efisien.
    Selalu:
Rencanakan langkah-langkah sebelum bertindak
Gunakan tools hanya jika diperlukan
Berikan jawaban yang ringkas dan terstruktur
    """
)

Logging dan Debugging

import logging
logging.basicConfig(level=logging.INFO)

Aktifkan verbose mode
agent = CodeAgent(
    tools=[],
    model=model,
    max_steps=5,
    verbose=True  # Tampilkan setiap langkah reasoning
)

Kesimpulan

Smolagents dari HuggingFace menawarkan pendekatan yang segar untuk membangun AI agents. Dengan filosofi code-first dan desain yang minimalis, framework ini memungkinkan developer untuk:

• Membangun agents dengan cepat menggunakan CodeAgent yang menghasilkan kode Python
• Membuat custom tools dengan mudah menggunakan decorator @tool
• Mengintegrasikan berbagai model LLM (HuggingFace, OpenAI, Anthropic, lokal)
• Mengorkestrasi multi-agent system dengan ManagedAgent
• Membuat UI interaktif dengan Gradio

Dibandingkan dengan framework agent lainnya, Smolagents menonjol karena kesederhanaannya. Tidak ada abstraksi yang berlebihan, tidak ada boilerplate yang rumit. Cukup definisikan tools, pilih model, dan jalankan agent.

Framework ini sangat cocok untuk prototyping cepat, proyek riset, dan aplikasi yang membutuhkan agent AI ringan tanpa overhead infrastruktur yang besar. Dengan dukungan komunitas HuggingFace yang aktif, Smolagents terus berkembang dengan fitur-fitur baru yang menarik.