Task API

Task API memungkinkan sistem Anda sendiri menjalankan agent sebagai pelaksana satu tugas. Server Anda mengirim satu input lewat REST dengan API key, agent mengerjakan tugasnya, dan hasil lengkapnya kembali di response HTTP. Tidak ada streaming, tidak ada percakapan, dan tidak ada tindak lanjut: setiap panggilan adalah tugas baru yang berdiri sendiri.

Gunakan API ini jika sebuah sistem membutuhkan penilaian, knowledge, dan tool agent Anda untuk satu pekerjaan dalam satu waktu, misalnya:

• Mengklasifikasikan tiket atau email. Helpdesk Anda mengirim setiap tiket baru dan menerima kategori, prioritas, dan ringkasan dalam bentuk JSON yang bisa langsung disimpan.
• Mengambil data dari dokumen. Back office Anda mengirim invoice atau laporan sebagai lampiran dan menerima field yang dibutuhkan.
• Menulis draf. CRM Anda mengirim data pelanggan dan menerima email tindak lanjut dalam Markdown, ditulis dengan pengetahuan agent tentang produk Anda.

Agent bekerja dengan instruksi utama, knowledge, dan tool miliknya, jadi apa yang Anda atur untuk chat juga dipakai di sini. Selain itu, Task API punya pengaturannya sendiri: instruksi tugas yang ditambahkan ke setiap panggilan, dan format hasil yang harus dipenuhi (Markdown, teks biasa, JSON, atau JSON yang sesuai dengan schema Anda).

Dalam contoh Mengajari Agent Anda, Atlas menyimpan SOP Kirana Group. Tim fasilitas Kirana mencatat tiket perawatan di sistemnya sendiri. Setiap tiket baru dikirim ke Task API milik Atlas, yang mengembalikan kategori, prioritas, dan ringkasan satu kalimat berdasarkan SOP perawatan Kirana, sehingga tiket langsung sampai ke tim yang tepat.

Sebelum memulai

• Hanya untuk service agent. Task API tersedia untuk service agent. Personal agent tidak bisa menyalakannya. Lihat Personal Agent vs Service Agent jika Anda belum yakin jenis agent Anda.
• Siapa yang bisa menyalakannya. Contributor agent serta Owner dan Admin organisasi.
• Mati secara default. Setiap agent dimulai dengan API ini dalam keadaan mati. Tidak ada yang bisa memanggilnya sampai seseorang menyalakannya dan membuat key.
• Panggil dari server. Key memberi akses penuh untuk menjalankan tugas di agent. Simpan di back-end Anda dan jangan pernah memanggil API dari halaman browser atau aplikasi mobile.

Cara agent bekerja dalam sebuah tugas

Dalam sebuah tugas, agent bekerja dalam mode tugas:

• Agent mengerjakan tugas dalam satu kali jalan dan hanya mengembalikan hasilnya.
• Agent tidak menyapa, tidak mengajukan pertanyaan lanjutan, dan tidak menawarkan bantuan lain.
• Agent tidak menampilkan widget interaktif atau canvas.
• Jika informasi yang dibutuhkan kurang, agent menyebutkan di hasilnya apa yang kurang, alih-alih menanyakannya.

Instruksi utama, knowledge, dan tool agent dipakai sesuai konfigurasinya, kecuali Anda mematikannya di pengaturan. Setiap tugas adalah percakapannya sendiri: agent tidak mengingat tugas sebelumnya.

Menyalakan API dan membuat key

Di CMS, buka Channels → Task API di sidebar agent Anda. Halaman ini punya tiga tab: Access, Settings, dan Test.

1. Di tab Access, nyalakan API. Halaman ini menampilkan endpoint untuk agent ini beserta contoh kode.
2. Agent punya dua slot key, Primary dan Secondary. Di salah satunya, buat key dan pilih Expiry: 7, 14, 30, 90, 180, atau 365 hari, atau tidak pernah. Setelah tanggal itu key berhenti bekerja.
3. Buat key lalu segera salin. Key lengkap (diawali qta_) hanya ditampilkan satu kali. Setelah itu halaman hanya menampilkan karakter terakhirnya dan tanggal kedaluwarsanya.
4. Simpan key di tempat penyimpanan rahasia server Anda (misalnya vault atau environment variable di server yang memanggil API).

Mengganti atau mencabut key

• Key hilang? Key tidak bisa dilihat lagi. Buat key baru di slot yang sama; key lama berhenti bekerja.
• Revoke (cabut) key untuk menghentikannya, misalnya jika key mungkin bocor atau sebuah sistem sudah tidak dipakai. Key yang sudah dicabut tidak bisa dinyalakan lagi.
• Matikan API untuk menghentikan semua key agent sekaligus.

Mencabut key atau mematikan API berlaku dalam hitungan detik.

Merotasi key tanpa downtime

Dua slot ini ada supaya Anda bisa mengganti key tanpa mengganggu sistem Anda:

1. Sistem Anda memakai key Primary.
2. Buat key di slot Secondary.
3. Pindahkan sistem Anda ke key Secondary, lalu pastikan tugasnya berhasil.
4. Revoke key Primary.

Rotasi berikutnya, lakukan hal yang sama ke arah sebaliknya.

Pengaturan tugas

Tab Settings mengatur cara agent menangani tugas. Pengaturan ini berlaku untuk setiap panggilan dengan key agent ini.

Pengaturan ini berlaku untuk task baru beberapa detik setelah disimpan, tanpa perlu publish. Lain halnya dengan agent itu sendiri (behavior, knowledge, dan tools): panggilan ke Task API memakai agent yang sudah di-publish, jadi perubahan pada agent baru berlaku setelah Anda klik Publish (lihat Preview dan Publish Perubahan).

Format response

Schema harus punya "type": "object" di root dan maksimal 20.000 karakter. Keyword yang didukung:

• type: string, number, integer, boolean, object, array, null, atau daftar dari tipe-tipe ini
• properties, required, additionalProperties (true atau false), items
• enum
• minimum dan maximum, minLength dan maxLength, minItems dan maxItems
• title dan description (pakai untuk menjelaskan field kepada agent)

Tips: untuk hasil paling ketat, cantumkan setiap property di required dan atur "additionalProperties": false. Belum yakin cara menulis schema? Pakai Generate from example di CMS untuk membuatnya dari contoh JSON yang Anda inginkan.

Schema untuk contoh tiket Kirana:

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["maintenance", "cleaning", "security", "it", "other"],
      "description": "The team that should handle the ticket."
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "description": "high = safety risk or work stopped; low = cosmetic."
    },
    "summary": {
      "type": "string",
      "maxLength": 200,
      "description": "One sentence describing the problem."
    }
  },
  "required": ["category", "priority", "summary"],
  "additionalProperties": false
}

Menguji tugas di CMS

Tab Test menjalankan tugas dari CMS tanpa key. Tab ini memakai pengaturan sebagaimana adanya di form, bahkan sebelum Anda menyimpannya, pada draf agent. Isi input lalu jalankan untuk melihat:

• output dan, untuk format JSON, hasil parse-nya,
• apakah hasilnya lolos validasi,
• tool yang dipanggil agent,
• apakah perbaikan dibutuhkan.

Pakai tab ini untuk menyempurnakan additional prompt dan schema sebelum menghubungkan sistem Anda.

Request

POST https://api.qlar.ai/dialog/api/task-api/v1/agents/{agentId}/tasks
X-Api-Key: qta_...
Content-Type: application/json

Endpoint dengan agent ID Anda sudah terisi ditampilkan siap disalin di tab Access.

Body:

{
  "input": "Ticket: the AC in room 3 has been leaking since yesterday.",
  "permissions": ["MANAGER"],
  "timezone": "Asia/Jakarta"
}

Seluruh body request maksimal 1 MB.

Lampiran

Setiap lampiran adalah objek dengan type dan url:

{
  "input": "Extract the invoice number, the date, and the total amount.",
  "attachments": [
    { "type": "image", "url": "https://example.com/photo.jpg" },
    { "type": "document", "url": "https://example.com/report.pdf", "fileName": "report.pdf" }
  ]
}

• Maksimal 5 lampiran per tugas.
• Gambar maksimal 10 MB, dokumen maksimal 20 MB.
• Jenis file sama dengan unggahan di chat, misalnya gambar JPG, PNG, dan WebP, serta dokumen PDF, DOCX, XLSX, TXT, dan MD.

Jika file tidak bisa diunduh atau dipakai, panggilan gagal dengan 400 attachment_invalid.

Response

{
  "taskId": "6f1c...",
  "status": "completed",
  "format": "json_schema",
  "output": "{\"category\":\"maintenance\",\"priority\":\"high\"}",
  "result": { "category": "maintenance", "priority": "high" },
  "durationMs": 6120
}

Timeout

Sebuah tugas bisa memakan waktu, terutama jika agent mencari di knowledge, memanggil tool, atau membaca lampiran. Qlar menunggu sampai 180 detik agar tugas selesai; setelah itu panggilan gagal dengan 504 run_timeout. Atur timeout HTTP client Anda minimal 200 detik, supaya client tidak menyerah sebelum Qlar menjawab.

Contoh kode

Setiap contoh mengirim satu tugas, menunggu sampai 200 detik, lalu mencetak hasilnya. Ganti YOUR_AGENT_ID dengan ID agent Anda, dan ambil key dari tempat penyimpanan rahasia Anda sebagai pengganti qta_your_key.

// Node.js 18 or later (built-in fetch)
const url = "https://api.qlar.ai/dialog/api/task-api/v1/agents/YOUR_AGENT_ID/tasks";
const apiKey = process.env.QLAR_TASK_KEY ?? "qta_your_key";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "Ticket: the AC in room 3 has been leaking since yesterday.",
    permissions: ["MANAGER"],
  }),
  signal: AbortSignal.timeout(200_000), // at least 200 seconds
});

const data = await response.json();

if (!response.ok) {
  console.error(`Task failed (${response.status}): ${data.code} - ${data.message}`);
  process.exit(1);
}

console.log("Output:", data.output);
if (data.result) {
  console.log("Category:", data.result.category);
}

using System.Text;
using System.Text.Json;

var url = "https://api.qlar.ai/dialog/api/task-api/v1/agents/YOUR_AGENT_ID/tasks";
var apiKey = Environment.GetEnvironmentVariable("QLAR_TASK_KEY") ?? "qta_your_key";

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(200) }; // at least 200 seconds
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);

var body = """
    {
      "input": "Ticket: the AC in room 3 has been leaking since yesterday.",
      "permissions": ["MANAGER"]
    }
    """;
var response = await http.PostAsync(url, new StringContent(body, Encoding.UTF8, "application/json"));

using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var root = doc.RootElement;

if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(
        $"Task failed ({(int)response.StatusCode}): {root.GetProperty("code")} - {root.GetProperty("message")}");
    return;
}

Console.WriteLine($"Output: {root.GetProperty("output").GetString()}");
if (root.TryGetProperty("result", out var result) && result.ValueKind == JsonValueKind.Object)
{
    Console.WriteLine($"Category: {result.GetProperty("category").GetString()}");
}

import os
import sys

import requests

url = "https://api.qlar.ai/dialog/api/task-api/v1/agents/YOUR_AGENT_ID/tasks"
api_key = os.environ.get("QLAR_TASK_KEY", "qta_your_key")

response = requests.post(
    url,
    headers={"X-Api-Key": api_key},
    json={
        "input": "Ticket: the AC in room 3 has been leaking since yesterday.",
        "permissions": ["MANAGER"],
    },
    timeout=200,  # at least 200 seconds
)

data = response.json()

if not response.ok:
    print(f"Task failed ({response.status_code}): {data.get('code')} - {data.get('message')}", file=sys.stderr)
    sys.exit(1)

print("Output:", data["output"])
if data.get("result"):
    print("Category:", data["result"]["category"])

// Java 11 or later (java.net.http). Text blocks need Java 15 or later.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class QlarTask {
    public static void main(String[] args) throws Exception {
        String url = "https://api.qlar.ai/dialog/api/task-api/v1/agents/YOUR_AGENT_ID/tasks";
        String apiKey = System.getenv().getOrDefault("QLAR_TASK_KEY", "qta_your_key");

        String body = """
            {
              "input": "Ticket: the AC in room 3 has been leaking since yesterday.",
              "permissions": ["MANAGER"]
            }
            """;

        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();

        HttpRequest request = HttpRequest.newBuilder(URI.create(url))
            .timeout(Duration.ofSeconds(200)) // at least 200 seconds
            .header("X-Api-Key", apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() / 100 != 2) {
            // The body is {"code": "...", "message": "..."}; parse it with your JSON library.
            System.err.println("Task failed (" + response.statusCode() + "): " + response.body());
            System.exit(1);
        }

        // The body holds taskId, output and, for the JSON formats, result.
        // Parse it with your JSON library (for example Jackson or Gson).
        System.out.println(response.body());
    }
}

Dengan format JSON schema dan schema di atas, tiket Kirana menghasilkan:

{
  "taskId": "6f1c...",
  "status": "completed",
  "format": "json_schema",
  "output": "{\"category\":\"maintenance\",\"priority\":\"high\",\"summary\":\"The AC in room 3 has been leaking since yesterday.\"}",
  "result": {
    "category": "maintenance",
    "priority": "high",
    "summary": "The AC in room 3 has been leaking since yesterday."
  },
  "durationMs": 6120
}

Permission

Kode permission bekerja sama seperti di percakapan agent: knowledge tanpa kode bisa dipakai di setiap tugas, dan knowledge dengan kode hanya dipakai jika tugas membawa salah satu kode tersebut. Kode ini juga diteruskan ke tool custom API milik agent, sehingga API Anda sendiri bisa memeriksanya. Lihat Permission Knowledge.

Pemanggil bertanggung jawab atas kode yang dikirimnya. Qlar tidak tahu siapa orang di balik sebuah tugas: Qlar memercayai kode yang dikirim pemegang key. Siapa pun yang memegang key bisa mengirim kode apa saja, termasuk kode untuk knowledge rahasia. Server Anda yang harus menentukan kode yang dibawa setiap tugas, misalnya dengan memetakan role atau grup di sistem Anda ke kode permission. Jangan pernah meneruskan kode dari browser pengguna apa adanya.

Biaya

Task API dikenai biaya seperti chat:

• Pemakaian AI (token) setiap tugas dibebankan ke kredit organisasi Anda, sama seperti jawaban chat dari agent yang sama. Tool seperti web search dikenai biaya seperti biasa.
• Jika agent berjalan dengan model AI milik organisasi Anda, pemakaian itu tidak memakai kredit Qlar, sama seperti chat. Lihat AI Models.
• Proses perbaikan untuk format JSON schema juga memakai token.
• Tugas yang dijalankan dari tab Test dikenai biaya seperti chat di Preview.

Jika kredit organisasi habis, panggilan gagal dengan 402 credit_exhausted. Lihat Cara Kerja Kredit.

Batas request

Task API belum punya batas request. Batas ini akan segera hadir; sampai saat itu, jaga agar jumlah tugas yang Anda kirim bersamaan tetap wajar.

Error

Error memakai kode status HTTP dan body JSON berisi code yang bisa dibaca mesin dan message yang bisa dibaca manusia. Jika tugas sudah sempat dimulai, body juga berisi taskId.

{
  "code": "invalid_request",
  "message": "input is required."
}

Bangun logika Anda berdasarkan code. Isi message bisa berubah dan ditujukan untuk manusia.

Praktik keamanan terbaik

• Simpan key di server. Panggil API hanya dari kode back-end. Jangan pernah menaruh key di halaman browser, aplikasi mobile, aplikasi desktop yang Anda distribusikan, atau repository publik: siapa pun yang bisa membaca kodenya bisa memakai key tersebut.
• Tentukan permission di server Anda. Kirim hanya kode yang menjadi hak orang yang menjadi tujuan tugas.
• Simpan key sebagai rahasia. Pakai vault atau secret variable di platform Anda, bukan file konfigurasi yang masuk ke source control. Jangan mencetak key di log.
• Pasang expiry dan rotasi key memakai dua slot, seperti dijelaskan di Merotasi key tanpa downtime.
• Segera cabut jika bocor. Jika sebuah key mungkin terekspos, cabut di tab Access dan buat key baru.
• Perlakukan input dan lampiran sebagai data. Apa pun yang Anda taruh di input atau lampiran akan dibaca agent. Taruh instruksi di Additional prompt, bukan di teks yang berasal dari luar organisasi Anda.
• Matikan API jika tidak dipakai lagi.

Troubleshooting

Halaman Terkait

• Permission Knowledge: kode permission yang dibawa tugas.
• Preview dan Publish Perubahan: memberlakukan perubahan pengaturan.
• API Pencarian Knowledge: menerima chunk knowledge agent yang cocok, bukan hasil jadi.
• Mengizinkan Agent Lain Memanggil Agent Anda: mengizinkan agent lain berbicara dengan agent Anda.
• Cara Kerja Kredit
• Referensi per field: Task API