Tools Kustom

Jika Anda menambahkan Custom API, AI akan melakukan aksi sesuai konteks yang diminta pengguna. Contoh: ketika pengguna berkata “catat pengeluaran 50k untuk kopi”, AI akan otomatis:

• Memanggil GET daftar kategori,
• Menentukan kategori yang paling relevan (mis. kopi/food & beverage),
• Mengirim POST transaksi dengan jumlah, tanggal, catatan, dan kategori yang sesuai.

Di mana menemukannya

1. Buka Dashboard
2. Masuk ke Agent Builder
3. Pilih Custom API
4. Klik Tambah Custom API

Konfigurasi Custom Tools

Gunakan urutan ini agar tidak membingungkan: mulai dari AI Variables → Parameters → Body → Headers → Authorization. Editor menyediakan pratinjau request langsung, bantuan variabel, dan panel uji.

Details

• Name: huruf/angka/garis bawah (contoh: send_email).

• Description: apa aksi yang dikerjakan dan arti hasilnya.

• Confirmation:

  • Need confirmation: minta persetujuan sebelum dijalankan dari chat.
  • Always call: panggil di setiap respons AI. Gunakan hati‑hati (biaya/efek samping).

• Praktik terbaik

  • Nama singkat, berorientasi aksi: create_invoice, get_weather.
  • Jelaskan intent dan output.
  • Aktifkan konfirmasi untuk aksi yang menulis/berbiaya.

AI Variables (Mulai dari sini)

Panduan Lengkap Custom Tool dengan Variable AI

Konsep Dasar

Custom Tool itu seperti formulir pintar yang diisi otomatis oleh AI. Setiap kolom adalah variabel AI yang bisa dipakai di mana saja dengan format {{nama_variabel}} - baik untuk URL, parameter, header, maupun body permintaan.

Cara Kerja

1. Deklarasi Variabel - Daftarkan variabel beserta deskripsi detail
2. Penempatan Placeholder - Letakkan {{nama_variabel}} di tempat yang dibutuhkan
3. Eksekusi Otomatis - AI mengisi variabel sesuai deskripsi, lalu request dikirim

Struktur Variabel Lengkap

Setiap variabel AI memiliki komponen berikut:

1. Nama Variabel

• Format: nama_variabel (huruf kecil, underscore untuk spasi)
• Contoh: recipient_email, api_token, max_retry_count

2. Tipe Data

• string - Teks, email, URL, token
• number - Angka, jumlah, limit
• boolean - True/False, ya/tidak
• enum - Pilihan tetap yang sudah ditentukan
• object - Data bersarang, akses dengan {{objek.properti}}

3. Status Kewajiban

• required - Wajib diisi
• optional - Boleh kosong
• readonly - Hanya bisa diisi sistem (password, token rahasia)

4. Deskripsi Natural Language

Ini yang paling penting! Jelaskan kepada AI bagaimana cara mengisi variabel ini dengan bahasa sehari-hari.

Contoh Implementasi Lengkap

Kasus: Tool Kirim Email Marketing

Deklarasi Variabel:

variables:
  recipient_name:
    type: string
    required: true
    description: "Nama lengkap penerima email. Ambil dari konteks percakapan atau minta kepada user jika tidak ada. Format: 'John Doe' tanpa gelar."

  recipient_email:
    type: string  
    required: true
    description: "Email address penerima. Harus valid formatnya (nama@domain.com). Jika ada beberapa email, gunakan yang pertama saja."

  email_subject:
    type: string
    required: true
    description: "Judul email. Buat menarik dan relevan dengan konten. Maksimal 50 karakter. Hindari kata spam seperti 'GRATIS' atau 'PROMO'."

  email_body:
    type: string
    required: true
    description: "Isi email lengkap. Gunakan format HTML jika perlu. Sertakan salam pembuka (Hai [nama]) dan penutup. Panjang ideal 200-500 kata."

  sender_name:
    type: string
    optional: true
    description: "Nama pengirim. Default 'Tim Support' jika tidak ditentukan. Format: 'Nama Perusahaan' atau 'Tim [Departemen]'."

  urgency_level:
    type: enum
    optional: true
    enum_values: ["normal", "high", "urgent"]
    description: "Tingkat urgensi email. Pilih 'urgent' jika perlu balasan cepat, 'high' jika penting, 'normal' untuk biasa."

  api_token:
    type: string
    readonly: true
    description: "Token API untuk autentikasi. Diisi otomatis oleh sistem, jangan minta ke user."

Implementasi di Endpoint:

URL: https://api.emailservice.com/v2/send

Headers:

Body (JSON):

{
  "recipient": {
    "name": "{{recipient_name}}",
    "email": "{{recipient_email}}"
  },
  "message": {
    "subject": "{{email_subject}}",
    "body": "{{email_body}}",
    "format": "html"
  },
  "metadata": {
    "timestamp": "{{current_time}}",
    "source": "ai_tool"
  }
}

Tips Deskripsi yang Efektif

✅ Deskripsi Baik:

user_age:
  type: number
  required: true
  description: "Usia user dalam angka. Ambil dari profil user atau tanyakan langsung. Pastikan angka realistis (1-120)."

❌ Deskripsi Kurang Baik:

user_age:
  type: number
  required: true
  description: "age"

Contoh untuk Berbagai Tipe Data

String dengan Validasi:

phone_number:
  type: string
  required: true
  description: "Nomor HP user. Format Indonesia: 08xx-xxxx-xxxx. Hilangkan karakter +62 jika ada."

Enum dengan Pilihan Jelas:

payment_method:
  type: enum
  enum_values: ["transfer", "ewallet", "credit_card", "cash"]
  description: "Metode pembayaran. Pilih 'transfer' untuk bank transfer, 'ewallet' untuk GoPay/Dana/OVO, 'credit_card' untuk kartu kredit, 'cash' untuk tunai."

Object dengan Nested Access:

user_data:
  type: object
  description: "Data profil user lengkap. Akses properti dengan dot notation seperti `{{user_data.profile.name}}`."

Boolean dengan Konteks:

send_notification:
  type: boolean
  description: "Kirim notifikasi ke user? True jika user harus dapat notifikasi, False jika silent processing."

Best Practices

1. Deskripsi Spesifik - Jelaskan konteks, format, dan sumber data
2. Contoh Nilai - Sertakan contoh format yang diharapkan
3. Error Handling - Beri tahu AI apa yang harus dilakukan jika data tidak valid
4. Default Values - Sebutkan nilai default jika ada
5. Dependencies - Jelaskan jika variabel bergantung pada variabel lain

Dengan struktur ini, AI akan lebih mudah memahami dan mengisi variabel dengan tepat sesuai kebutuhan tool yang kamu buat!

Parameters

• Parameters = parameter kueri + input deklaratif untuk menyelesaikan {{placeholder}} di URL, headers, body.

• Setiap parameter: nama, tipe, deskripsi, flags (nullable, enum). Wajib punya nilai saat Test.

• Perilaku URL

  • Tabel Params adalah sumber utama query di URL; mengetik ?key=value di URL akan diurai balik ke tabel.
  • Otomatis URL‑encode; kosong/nullable dihapus dari URL akhir.
  • Array: ulangi key (tag=red&tag=blue) atau gaya bracket (tag[]=red&tag[]=blue) sesuai API.
  • Boolean jadi string true/false.

• Mengisi headers/body

  • Placeholder di headers/body diisi dari Parameters dulu, lalu Variables.

• Contoh

  • URL template: https://api.example.com/search?query={{q}}&page={{page}}
  • Params uji: q=laptop, page=2
  • Hasil uji: .../search?query=laptop&page=2

Body (payload utama)

• Mode konten:

  • Form: application/x-www-form-urlencoded, multipart/form-data (edit sebagai key/value; bukan JSON).
  • Raw: application/json, text/plain (edit sebagai teks mentah).

• Praktik terbaik

  • Payload kompleks → pilih JSON mentah dan dokumentasikan field.
  • Gunakan multipart untuk unggah file atau campuran field/file.

• Kesalahan umum

  • Content-Type tidak selaras dengan mode.
  • JSON tidak valid (kutip ganda, tanpa trailing comma).

• Contoh JSON

  json

  { "to": "{{recipient}}", "subject": "{{subject}}", "text": "{{message}}" }

Headers (jelas setelah body)

• Tambahkan pasangan key/value. Nilai boleh {{variabel}}.

• Samakan Content-Type dengan mode Body; override jika penyedia meminta nilai khusus.

• Contoh

  • Content-Type: application/json
  • Authorization: Bearer {{api_token}}

Authorization (terakhir)

• Tipe: Bearer, Basic, API Key, atau header custom.

• Nilai disimpan terenkripsi di server; tidak bocor ke klien.

• Tips

  • Utamakan Bearer/API Key; Basic hanya jika wajib.
  • Custom: tentukan headerKey (mis. X-API-KEY).

• Contoh

  • Bearer: Authorization: Bearer {{api_token}}
  • API Key: X-API-KEY: {{api_key}}

Visibility & Access

• Public: bisa diakses siapa pun di Korin (semua pengguna).

• Private: tambahkan daftar email yang diizinkan. Saat beralih ke private, email Anda otomatis ditambahkan (dapat dikelola).

• Praktik terbaik

  • Mulai dari Private dan beri akses ke kolaborator; ubah ke Public saat sudah stabil.
  • Simpan Tools sensitif sebagai Private dan tinjau akses secara berkala.
  • Sebelum mengubah ke Public, pastikan logging/auditing aktif dan konfirmasi dihidupkan jika Tools punya efek samping.

• Contoh

  • Tools private dengan allowlist: you@example.com, teammate@example.com

Contoh Tools Kustom (end‑to‑end)

Tujuan

• Menunjukkan konfigurasi aksi tulis (Kirim Email) dengan otorisasi dan variabel.
• Menampilkan pengujian langsung, termasuk pratinjau request dan respons.

Persiapan

• Endpoint dan method API (contoh: POST https://api.example.com/send).
• Pilihan otentikasi dan kredensial (mis., Bearer token).
• Variabel/parameter wajib dan tipenya (mis., recipient, subject, message).
• Bentuk body dan jenis konten.

Konfigurasi

• Details: nama, deskripsi, perilaku konfirmasi.
• Endpoint: method + URL; tambahkan query param seperlunya.
• Headers/Auth: content type dan header auth.
• Body: JSON mentah atau pasangan key/value.
• Variables: deklarasikan input dan tandai nullable/readonly/enum.
• Test: isi nilai uji dan jalankan.

Ekspektasi

• Pratinjau request menampilkan method akhir, URL (dengan param terselesaikan), header, dan body memakai nilai uji.
• Panel Test mengembalikan status HTTP dan payload respons (JSON/teks) untuk validasi cepat.
• Penanganan rahasia dan keamanan:
  • Headers, Authorization, dan Body yang Anda atur disimpan terenkripsi di backend.
  • Aman menaruh rahasia (mis., token API) di Authorization atau header; tidak akan terekspos ke pengguna lain dan dikirim dari server ke server saat aksi berjalan.
  • Di pratinjau UI, nilai sensitif dapat ditutupi tergantung tipe auth; nilai asli hanya dipakai saat eksekusi.
  • Kasus gagal: jika Parameters/Variables wajib kurang atau tidak valid, panel Test menyorot field dan menampilkan pesan jelas.

Pemecahan Masalah

• Respons 4xx/5xx: cek ulang endpoint, auth, dan bentuk payload.
• Pesan variabel hilang: isi semua nilai uji wajib; tandai yang opsional sebagai nullable.
• Bentuk body tidak cocok: pastikan Content-Type sesuai mode editor (KV vs raw).
• Akses ditolak di chat: konfirmasi visibilitas dan daftar akses untuk Tools private.
• 401/403 Tidak Sah/Terlarang: verifikasi skema Authorization (Bearer/Basic/API Key), kunci header untuk Custom, dan kredensial valid.
• 404 Tidak Ditemukan: pastikan base URL, segmen path, dan apakah API butuh trailing slash.
• 415 Unsupported Media Type: server menolak tipe body; sesuaikan Content-Type dengan JSON mentah vs mode form.
• 429 Kena batas kuota (Rate limited): tunda dan coba lagi; pertimbangkan dry_run atau uji di luar jam sibuk.
• 5xx Error server: coba lagi nanti; validasi payload dengan dokumentasi dan perkecil data/kompleksitas.
• Error JSON: JSON tidak valid di Body; gunakan mode JSON dan formatkan sebelum uji.
• Masalah multipart/form: pastikan setiap kunci sesuai spesifikasi; unggah file harus multipart/form-data.
• Validasi enum: berikan salah satu nilai yang diizinkan; definisikan opsi enum di Variables.
• Parameter readonly: nilai yang disuntik sistem (mis., korin_user_email) tidak butuh input uji dan tidak bisa ditimpa.
• Timeout: payload besar atau endpoint lambat bisa habis waktu; perkecil data atau uji dengan dry_run dulu.
• TLS/SSL: pastikan menggunakan https:// jika API memerlukan TLS.

Topik Terkait

• Agent Bawaan
• Memberi Pengetahuan
• Orkestrasi Agen
• Template Prompt