Belajar Hermes AI Agent - Tooling & External Integrations

#Pendahuluan

Di episode 5 kalian sudah merancang system prompt, task instructions, dan response formatting lewat profile agent di agents/. Sejauh ini Hermes hanya pandai beretorika — ia belum bisa menyentuh dunia nyata. Episode ini adalah titik di mana agent kalian "hidup": terhubung ke provider LLM dan dilengkapi tool untuk bertindak.

Roadmap episode ini tiga hal: pertama menghubungkan OpenAI, Azure OpenAI, atau provider lain; kedua mengintegrasikan tool web search, database query, API fetch, dan file system; ketiga membahas safety considerations yang wajib kalian pahami setiap kali agent memanggil tool.

#Memilih dan Menghubungkan LLM Provider

Hermes dirancang provider-agnostic: satu interface yang sama dipakai untuk model mana pun. Konfigurasi provider ditaruh di hermes.config.ts, dan Hermes membaca kredensial dari environment variable yang otomatis dimuat dari .env.

export default defineHermesConfig({
  model: {
    provider: "openai",
    model: "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY,
    temperature: 0.4,
    maxTokens: 4096,
  },
  tools: {
    registry: true,
    directory: "./tools",
  },
});

Untuk Azure OpenAI, ganti blok model agar memakai endpoint, API version, dan nama deployment milik Azure — karena Azure punya struktur deployment sendiri. Pola yang sama berlaku untuk provider lain seperti Anthropic atau model open-source via endpoint yang kompatibel dengan OpenAI.

model:
  provider: azure
  model: gpt-4o
  azureEndpoint: "https://belajar-hermes.openai.azure.com/"
  apiVersion: "2025-08-01-preview"
  deployment: hermes-deployment

Kunci dari semuanya: .env harus berisi OPENAI_API_KEY atau AZURE_OPENAI_API_KEY, dan file itu wajib masuk .gitignore. Untuk mengecek provider mana yang aktif dan apakah kredensialnya valid, jalankan hermes doctor.

#Mendaftarkan Tool di Agent Profile

Tool di Hermes dideklarasikan di profile agent, bersama persona dan capability yang sudah kalian buat di episode 4. Setiap tool punya nama, deskripsi, dan permission level yang menentukan kapan tool boleh dieksekusi.

name: support-agent
persona: "Asisten support produk yang teliti"
goals:
  - "Menjawab pertanyaan berdasarkan dokumentasi"
capabilities:
  - tools
  - browsing
tools:
  - name: web.search
    permission: auto
  - name: web.fetch
    permission: confirm
  - name: db.query
    readOnly: true
    permission: auto
  - name: fs.read
    allow: ["./docs", "./kb"]
    permission: auto
  - name: http.post
    permission: denied

Perhatikan permission level: auto artinya tool langsung dieksekusi oleh controller tanpa bertanya, confirm artinya agent meminta persetujuan kalian, dan denied melarang total. Kombinasi inilah yang membuat agent powerful sekaligus terkendali.

#Integrasi Web Search & API Fetch

Tool web memberi agent akses ke informasi terbaru yang tidak ada di data latih model. web.search mengambil daftar hasil dari mesin pencari, lalu web.fetch membaca isi halaman tertentu untuk disimpulkan.

Pola kerja keduanya berpasangan: controller menyuruh agent mencari dulu, lalu agent memilih tautan paling relevan untuk di-fetch. Tanpa web.fetch, hasil pencarian hanya berisi judul dan deskripsi singkat. Ini contoh konkret tool chaining yang akan kalian pelajari lebih dalam di episode 10.

Untuk integrasi API, tool http.get dan http.post memanggil REST endpoint eksternal. Hasilnya otomatis di-parsing sebagai JSON dan disuntikkan ke context agent sebagai data terbaru.

{
  "status": 200,
  "data": {
    "order_id": "ORD-2026-0142",
    "status": "shipped",
    "tracking": "JNE-8821"
  }
}

Kalau endpoint butuh autentikasi, daftarkan kredensial terpisah di secret store — jangan pernah menaruhnya langsung di profile agent.

#Database Query & File System

Tool db.query mengeksekusi SQL terhadap database yang sudah dikonfigurasi. Keselamatan nomor satu: set readOnly: true agar agent hanya bisa menjalankan pernyataan SELECT, bukan INSERT, UPDATE, atau DELETE. Hermes menolak pernyataan penulisan selama flag ini aktif.

File system juga dibatasi dengan allow-list path. Agent boleh membaca ./docs dan ./kb, tetapi tidak bisa menyentuh file di luar itu. Batasi juga tool fs.write — kalau tidak benar-benar dibutuhkan, set permission-nya ke denied.

hermes run agents/support.yml --session order-check

Kalau semua konfigurasi benar, kalian bisa meminta agent mengecek status order dan jawabannya akan merujuk data nyata dari database.

#Safety Considerations pada Tool Invocation

Memberi tool pada agent artinya memberi efek samping. Ada empat prinsip yang wajib kalian pegang:

• Least privilege — berikan permission seminimal mungkin untuk tugas yang dijalankan. Tool yang tidak dipakai langsung di deny.
• Allow-list, bukan deny-list — domain web, tabel database, dan path file yang boleh diakses didaftarkan eksplisit. Segala yang tidak terdaftar otomatis diblokir.
• Human in the loop — operasi berisiko seperti pengiriman email atau pembayaran dipasang di permission confirm agar ada persetujuan manusia.
• Waspada prompt injection — agent bisa dimanipulasi lewat isi halaman web atau dokumen yang dibacanya. Tambahkan instruksi di system prompt bahwa konten dari tool adalah data, bukan perintah.

Di episode 7 kita akan melihat bagaimana semua pemanggilan tool ini direkam — lengkap dengan argumen dan hasilnya — supaya kalian bisa melacak dan memutar ulang perilaku agent.

#Penutup

Episode 6 membuat agent kalian tidak lagi buta dan bisu: provider LLM terhubung lewat hermes.config.ts, tool web search, database query, API fetch, dan file system terdaftar di profile dengan permission level masing-masing. Yang terpenting, kalian punya prinsip safety yang jelas sebelum agent diberi kemampuan mengeksekusi.

Inti yang harus dibawa pulang:

• Provider LLM dikonfigurasi di hermes.config.ts; kredensial selalu lewat environment variable.
• Tool dideklarasikan di profile agent bersama permission level auto, confirm, atau denied.
• web.search dan web.fetch bekerja berpasangan untuk membaca informasi terkini.
• Akses database dan file system wajib di-restrict dengan readOnly dan allow-list path.
• Safety dimulai dari least privilege dan kewaspadaan terhadap prompt injection.

Di episode 7 berikutnya kita masuk ke Basic Observability & Logging — event logging percakapan, debugging action execution dan tool calls, serta replay log untuk memantau perilaku agent. Sampai jumpa!