← Dokumentasi

Hosted Agents API

Hosted agent adalah model AI yang menjalankan loop tool-calling di server Kiosapi — Anda tidak menjalankan loop-nya sendiri. Anda mendefinisikan model, system prompt, dan skema tool satu kali, lalu menjalankan agen secara asinkron: Kiosapi memanggil model berulang kali, berhenti untuk meminta Anda mengeksekusi tool bila perlu, dan melanjutkan sampai ada jawaban akhir. Panduan ini mencakup model sumber daya, panduan curl end-to-end, mesin status, batasan, dan penagihan.

Coba tanpa menulis kode di playground dashboard → (buat agen, jalankan thread, isi hasil tool secara manual).

1. Apa itu hosted agent

Dengan POST /v1/chat/completions + tools, Andalah yang menjalankan loop: panggil model, lihat apakah model minta memanggil tool, jalankan tool-nya, tempel hasilnya ke daftar pesan, panggil model lagi — dan ulangi sampai model berhenti. Anda juga yang menyimpan seluruh riwayat percakapan.

Hosted agent memindahkan loop itu ke server Kiosapi. Anda mendefinisikan agen sekali (model, system prompt, skema tool, batas langkah). Setiap kali agen dijalankan (run), Kiosapi:

1. Memanggil model dengan riwayat percakapan (disimpan di server).
2. Jika model menjawab langsung → run selesai (succeeded), teks jawaban ada di field output.
3. Jika model minta memanggil tool → run berhenti di requires_action dan mengembalikan daftar pending_tool_calls kepada Anda.
4. Anda mengeksekusi tool di sisi Anda sendiri (panggil API cuaca, query database, dsb.), lalu mengirim hasilnya kembali lewat POST /v1/runs/:id/tool_outputs.
5. Run melanjutkan dari titik itu. Ulangi sampai selesai.

Loop tetap berjalan di server walau koneksi Anda putus — Anda cukup polling GET /v1/runs/:id. Konteks percakapan, penyimpanan riwayat, deteksi loop, dan batas langkah semuanya ditangani Kiosapi.

2. Model sumber daya: Agent, Thread, Run

Alurnya: buat Agent sekali → buat Thread per percakapan → kirim Run setiap kali ada giliran baru dari pengguna Anda.

3. Autentikasi

Setiap panggilan butuh header Authorization: Bearer kios_live_… — API key yang sama dengan REST API Kiosapi lainnya (dashboard → Kunci API). Base URL: https://api.kiosapi.id. Rate limit sama dengan endpoint REST lain: 120 req/menit untuk akun berbayar (tier yang berlaku untuk agent — lihat di bawah), dan 300 req/menit untuk akun korporat. Lewat batas → HTTP 429.

Agent hanya mendukung model teks berbayar. Model free tier, Google Gemini (Vertex), dan GPT-5.6 (yang memakai Responses API untuk tool calling) belum bisa dipakai sebagai model agen — POST /v1/agents dan PATCH /v1/agents/:id menolaknya dengan HTTP 400 unsupported_model.

4. Panduan curl lengkap

Contoh end-to-end: agen cuaca dengan satu tool get_weather yang Anda eksekusi sendiri.

Langkah 1 — Buat agent · POST /v1/agents

curl https://api.kiosapi.id/v1/agents \
  -H "Authorization: Bearer kios_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Asisten Cuaca",
    "model_id": "openai/gpt-4o",
    "system_prompt": "Kamu asisten cuaca. Pakai tool get_weather untuk data terkini.",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Ambil cuaca terkini untuk sebuah kota",
          "parameters": {
            "type": "object",
            "properties": { "city": { "type": "string" } },
            "required": ["city"]
          }
        }
      }
    ],
    "max_steps": 20
  }'

# Respons 201 — baris agent:
# { "id": "agt_b3f1...", "name": "Asisten Cuaca", "model_id": "openai/gpt-4o",
#   "system_prompt": "...", "tools": [ ... ], "builtin_tools": [],
#   "max_steps": 20, "created_at": "...", "updated_at": "..." }

system_prompt, tools, dan max_steps opsional (default "", [], 20). max_steps harus 1..40; tools maksimal 64 item, tiap item { type: "function", function: { name, … } }. Ubah agen dengan PATCH /v1/agents/:id, hapus dengan DELETE /v1/agents/:id (menghapus thread & run turunannya).

Langkah 2 — Buat thread · POST /v1/agents/:id/threads

curl https://api.kiosapi.id/v1/agents/agt_b3f1.../threads \
  -H "Authorization: Bearer kios_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{}'

# Respons 201:
# { "id": "thr_9a2c...", "agent_id": "agt_b3f1...",
#   "title": null, "metadata": null, "created_at": "..." }

Body opsional: { "title": "…", "metadata": { … } }. Satu thread menahan percakapan lintas banyak run, jadi buat satu thread per percakapan pengguna dan pakai ulang untuk tiap giliran.

Langkah 3 — Kirim run · POST /v1/threads/:id/runs

curl https://api.kiosapi.id/v1/threads/thr_9a2c.../runs \
  -H "Authorization: Bearer kios_live_xxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6d7f2e10-8b1a-4c33-9f7e-2a1b3c4d5e6f" \
  -d '{ "input": "Cuaca di Jakarta?" }'

# Respons 202 — run view:
# { "id": "run_f4e8...", "thread_id": "thr_9a2c...", "agent_id": "agt_b3f1...",
#   "status": "queued", "step_count": 0, "max_steps": 20, "cost_rupiah": 0,
#   "pending_tool_calls": null, "error": null,
#   "created_at": "...", "updated_at": "..." }

input boleh berupa string, atau array pesan untuk menyuntik peran eksplisit: { "input": [ { "role": "user", "content": "…" } ] } (role: user / assistant / system). Header Idempotency-Key opsional — mengirim ulang dengan key sama pada thread yang sama mengembalikan run yang sudah ada (202), bukan run baru.

Langkah 4 — Poll run · GET /v1/runs/:id

curl https://api.kiosapi.id/v1/runs/run_f4e8... \
  -H "Authorization: Bearer kios_live_xxxx"

# masih berjalan:
# { "status": "running", "step_count": 1, "cost_rupiah": 12,
#   "pending_tool_calls": null, "error": null, ... }

# model minta memanggil tool:
# { "status": "requires_action", "step_count": 1, "cost_rupiah": 12,
#   "pending_tool_calls": [
#     { "id": "call_abc", "name": "get_weather", "arguments": "{\"city\":\"Jakarta\"}" }
#   ], "error": null, ... }

# selesai:
# { "status": "succeeded", "step_count": 2, "cost_rupiah": 21,
#   "output": "Cuaca di Jakarta cerah, sekitar 32 derajat C.", ... }

Polling tiap ~1–2 detik sudah cukup. Field output (teks assistant akhir) hanya muncul saat status = succeeded. arguments adalah string JSON — parse sendiri di sisi Anda.

Langkah 5 — Kirim tool_outputs · POST /v1/runs/:id/tool_outputs

Saat run requires_action: eksekusi setiap panggilan di pending_tool_calls di sisi Anda, lalu kirim hasilnya kembali sebagai string. Setiap tool_call_id yang pending wajib disertakan dalam satu request.

curl https://api.kiosapi.id/v1/runs/run_f4e8.../tool_outputs \
  -H "Authorization: Bearer kios_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "outputs": [
      { "tool_call_id": "call_abc", "output": "{\"temp_c\":32,\"kondisi\":\"cerah\"}" }
    ]
  }'

# Respons 200 — run view. status kembali "running" (atau "requires_action" lagi
# bila model langsung minta tool berikutnya). Lanjutkan poll GET /v1/runs/:id.

Membatalkan run · POST /v1/runs/:id/cancel

curl -X POST https://api.kiosapi.id/v1/runs/run_f4e8.../cancel \
  -H "Authorization: Bearer kios_live_xxxx"

# Respons 200 — run view dengan "status": "cancelled".
# Run yang sudah terminal dikembalikan apa adanya (tidak error).

Endpoint bantu lain: GET /v1/agents, GET /v1/agents/:id/threads, GET /v1/threads/:id, dan GET /v1/threads/:id/messages (transkrip lengkap thread, kronologis).

5. Mesin status

queued ──► running ──────────► succeeded   jawaban akhir → "output" terisi
              │   ▲
              ▼   │  POST /v1/runs/:id/tool_outputs
        requires_action                model minta tool → "pending_tool_calls" terisi
              │
   run mana pun yang non-terminal bisa berakhir di:
              ├─► failed      step > max_steps · wall-clock 10 mnt · loop · saldo habis · error model
              ├─► expired     requires_action tanpa tool_outputs selama > 1 jam
              └─► cancelled   POST /v1/runs/:id/cancel

• queued — run dibuat, belum melangkah.
• running — sedang memanggil model / memproses langkah.
• requires_action — menunggu tool_outputs dari Anda. pending_tool_calls berisi [{ id, name, arguments }].
• succeeded — selesai; output = teks jawaban akhir.
• failed — error berisi alasan (step_limit, timeout, loop, insufficient_balance, atau pesan kegagalan model).
• expired — run requires_action dibiarkan > 1 jam tanpa tool_outputs.
• cancelled — dibatalkan lewat endpoint cancel.

running ⇄ requires_action bisa bolak-balik beberapa kali dalam satu run sebelum mencapai status terminal (succeeded / failed / expired / cancelled).

6. Batasan

7. Penagihan

Setiap panggilan model di dalam loop ditagih persis seperti panggilan /v1/chat/completions biasa — per token, tarif model yang sama — dan dicatat di Pemakaian dengan source: agent. Poin penting:

• Charge-as-you-go — biaya dipotong tiap langkah. Run yang failed di tengah jalan tetap menagih langkah-langkah yang sudah berjalan.
• Diskon paket & tier volume berlaku otomatis, sama seperti Chat biasa.
• cost_rupiah pada run view adalah total berjalan — bertambah setiap langkah, bisa dipantau lewat polling.
• Agent selalu memakai model berbayar, jadi setiap langkah memotong saldo Rupiah — tidak ada jalur free tier di sini.
• Saldo dicek sebelum tiap langkah berbayar. Bila saldo habis, run berhenti failed dengan error: "insufficient_balance" — langkah yang terlanjur jalan tetap tertagih.

8. Built-in tools (dijalankan di server)

Dua tool bawaan dijalankan langsung di server Kiosapi di dalam loop run — tanpa memerlukan round-trip tool_outputs dari Anda:

Batasan built-in tools: Setiap run dikenai biaya maksimal Rp20.000 untuk semua built-in tools di dalamnya (ceiling per-run). Setiap model turn dapat menjalankan maksimal 3 built-in calls — lebih banyak akan disampaikan sebagai synthetic error tool result (bukan crash). Kegagalan built-in disampaikan sebagai tool result yang normal — run tidak berhenti, model dapat bereaksi terhadapnya.

Status generate_image: generate_image belum tersedia sebagai built-in tool. Untuk sekarang, gunakan client-executed tools (field tools + tool_outputs, lihat bagian 5–6): Anda bisa menjalankan sendiri pembuatan gambar via POST /v1/images/generations lalu mengirim hasilnya sebagai tool_outputs.

9. Belum tersedia

• Built-in tool generate_image — masih dalam pengembangan (tidak tersedia sebagai built-in tool). Gunakan client-executed tools saat ini. text_to_speech + rag_search sudah live — lihat bagian 8. web_search masih menunggu tinjauan ToS.
• Server MCP eksternal — agen belum bisa menyambung ke server MCP milik Anda.
• Orkestrasi multi-agen — satu agen memanggil agen lain / pola "tim".
• Streaming respons — run hanya bisa di-poll, belum ada SSE.
• UI dashboard — agent, thread, dan run dikelola lewat API saja.
• Model yang belum didukung sebagai model agen: semua model free tier, Google Gemini (Vertex), dan GPT-5.6 (yang memakai Responses API untuk tool calling). Pakai model teks berbayar dari OpenAI (mis. openai/gpt-4o), Anthropic, DeepSeek, Moonshot, MiniMax, Mistral, Z.ai, atau xAI. Penolakan terjadi saat membuat atau mengubah agent (POST /v1/agents / PATCH /v1/agents/:id) → HTTP 400 unsupported_model, bukan saat run berjalan.

10. Referensi endpoint

Butuh loop tool-calling di sisi klien (Anda yang mengendalikan tiap giliran)? Pakai POST /v1/chat/completions dengan tools — lihat dokumentasi utama.