Tutorial teknis + mental model + praktik OpenAI Agents API

Untuk audiens @kayadigital.ai <callout icon="✅" color="green_bg">

STATUS VERIFIKASI — 29 September 2026

Tutorial ini diverifikasi terhadap dokumentasi resmi OpenAI Agents API dan pengumuman OpenAI tanggal 10 September 2026. Contoh perusahaan di bagian use case nyata berasal dari customer statements yang dipublikasikan OpenAI. Kode praktik adalah tutorial yang kita susun berdasarkan API resmi, bukan kode internal perusahaan yang disebutkan. </callout>

Inti materi: model menentukan kemampuan reasoning. Harness menjalankan dan mempertahankan proses agent: model/tool loop, session, context, tool use, serta koordinasi subagent. Sandbox/environment adalah komponen terpisah. <table_of_contents/>

1. Apa Itu Agent Harness?

Kalau chatbot sederhana dibayangkan seperti ini:

mermaid

flowchart LR
    U["👤 USER"] -->|prompt| M["🧠 MODEL"]
    M -->|single response| R["💬 RESPONSE"]

maka agent system lebih dekat ke:

mermaid

flowchart TB
    T["🎯 TASK"] --> H["⚙️ AGENT HARNESS"]
    M["🧠 MODEL"] <--> H
    H --> C["🗂️ CONTEXT"]
    H --> TL["🛠️ TOOL LOOP"]
    H --> S["💾 SESSION"]
    H --> A["👥 SUBAGENTS"]
    C --> H
    TL --> H
    S --> H
    A --> H
    H --> R["✅ RESULT"]

Dalam arsitektur OpenAI Agents API, OpenAI mendefinisikan harness sebagai instance Codex yang menjalankan model + tool loop dan mempertahankan session agent. Artinya harness bukan “model kedua”. Ia adalah runtime/orchestration layer yang menjaga proses kerja model tetap berjalan.

Sumber resmi:

OpenAI — Agents API Architecture
OpenAI — Introducing the Agents API <callout icon="💡" color="blue_bg">

Mental model paling sederhana

MODEL = berpikir dan memilih langkah.

HARNESS = menjalankan loop pekerjaan dan menjaga continuity.

ENVIRONMENT / SANDBOX = tempat agent menjalankan code, command, dan bekerja dengan file. </callout>

2. Kenapa Model Pintar Saja Belum Cukup?

Bayangkan task:

“Riset 20 perusahaan, baca sumber terbaru, kelompokkan positioning mereka, lalu buat laporan.” Ini bukan lagi satu kali prompt → satu kali jawaban. Agent perlu melakukan pola seperti:

mermaid

flowchart TD
    A["🎯 Baca task"] --> B["🔎 Cari informasi"]
    B --> C["🧪 Periksa hasil"]
    C --> D{"Informasi cukup?"}
    D -- "Belum" --> B
    D -- "Ya" --> E["💾 Simpan progress"]
    E --> F["📊 Analisis"]
    F --> G{"Perlu dibagi?"}
    G -- "Ya" --> H["👥 Delegasikan subtask"]
    H --> I["🧩 Gabungkan hasil"]
    G -- "Tidak" --> I
    I --> J["📄 Final report"]

Model dapat memutuskan apa yang perlu dilakukan, tetapi sebuah agent system juga membutuhkan mekanisme untuk:

menjalankan tool;
membawa hasil tool kembali ke model;
mempertahankan session;
menjaga context agar tetap berguna;
mengelola progress;
menangani pekerjaan panjang;
membagi pekerjaan ke subagents bila memang bermanfaat. Agents API mengelola session, orchestration, context compaction, dan recovery. OpenAI juga menyebut managed Codex harness mereka mendukung automatic context compaction, multi-agent orchestration, programmatic tool calling, dan MCP. Sumber:
Agents API Overview
Agents overview

3. Empat Hal yang Perlu Dipahami dari Infografis

A. Context — apa yang perlu diketahui agent sekarang?

Long-running agent menghasilkan history yang terus bertambah: user message, hasil tool, intermediate reasoning state, file, dan output lain. Agents API menyediakan automatic context compaction ketika session mendekati context limit. Tujuannya bukan menyimpan semua teks mentah selamanya, tetapi mempertahankan informasi yang dibutuhkan agent agar dapat melanjutkan pekerjaan.

Compaction bukan “memory database”. Ini adalah mekanisme menjaga working context pada session panjang. Sumber: Introducing the Agents API — Keep agents working across long sessions

B. Tool Loop — bukan cuma “AI punya tools”

Loop dasarnya:

mermaid

flowchart LR
    M["🧠 MODEL"] --> D{"Perlu tool?"}
    D -- "Ya" --> T["🛠️ TOOL CALL"]
    T --> X["⚡ EXECUTION"]
    X --> O["📥 RESULT / OBSERVATION"]
    O --> M
    D -- "Tidak" --> F["✅ FINAL ANSWER"]

Agents API menjalankan agent loop untuk developer. Tool dapat berasal dari built-in tools, custom function, MCP, atau capability lain yang didukung. Sumber:

C. Session — pekerjaan punya continuity

Session menyimpan konfigurasi agent, conversation, dan saved work dari waktu ke waktu. Session yang sama dapat menerima follow-up agar pekerjaan dilanjutkan, bukan memulai conversation baru tanpa state session sebelumnya. Sumber: Run and Continue Sessions

D. Subagents — pecah pekerjaan yang independen

Saat multi-agent diaktifkan, main agent dapat mendelegasikan task ke subagents. Setiap subagent memiliki context sendiri dan dapat bekerja paralel. Main agent mengoordinasikan serta menggabungkan hasilnya. OpenAI menyarankan subagent untuk pekerjaan yang independen, misalnya:

meninjau dokumen berbeda;
menyelidiki penyebab masalah yang berbeda;
melakukan beberapa jalur riset paralel. Task pendek atau step yang saling bergantung kuat biasanya lebih sederhana bila tetap dikerjakan main agent. Sumber: Agents API — Multi-agent

4. Harness ≠ Sandbox

Ini salah satu hal yang mudah tercampur.

Harness	Environment / Sandbox
Menjalankan model + agent/tool loop	Menjalankan command dan code
Menjaga session	Tempat bekerja dengan files
Mengoordinasikan tool dan workflow	Dapat OpenAI-hosted atau self-hosted
Dikelola OpenAI pada Agents API	Dipilih sesuai kebutuhan workload

OpenAI bahkan menjelaskan bahwa harness bisa bekerja tanpa environment jika agent hanya perlu menjawab pertanyaan atau memakai service-connected tools. Jika agent butuh shell, code execution, file workspace, atau local software, barulah environment menjadi relevan. Sumber: Agents API Architecture

5. Use Case Produksi Nyata: Apakah Harness Benar-Benar Dipakai?

Ya. Yang penting adalah membedakan contoh production yang dipublikasikan dari demo tutorial kita.

A. SafetyKit — case review workflow

Dalam pengumuman Agents API, SafetyKit menyatakan bahwa setelah memigrasikan case review workflow ke Agents API, mereka melihat:

60% reduction in cost per case;
latency lebih rendah;
token efficiency membaik;
performance existing workflow tetap dipertahankan. Ini merupakan customer statement yang dipublikasikan OpenAI; detail arsitektur internal SafetyKit tidak dipublikasikan di halaman tersebut.

B. Hypha — financial services agent reliability

Hypha menyatakan bahwa pemisahan agent harness dari sandbox menurunkan failed agent responses sebesar 86% pada sistem mereka. Sekali lagi: metrik ini berasal dari customer statement di artikel OpenAI, bukan pengukuran independen kita.

C. Nash.ai — long-running agents di logistik

Nash.ai menyatakan mereka menjalankan ribuan long-running AI agents untuk mengelola operasi yang berkaitan dengan ratusan juta deliveries pada jaringan logistik global. Menurut Nash, Agents API menyediakan durable session dan orchestration layer untuk context, recovery, serta multi-step execution, sementara Nash menyediakan tools dan execution environment yang terhubung ke dunia operasional mereka. Ini contoh yang sangat dekat dengan pesan infografis:

Model saja bukan seluruh agent system. Sumber seluruh contoh produksi: OpenAI — Introducing the Agents API <callout icon="⚠️" color="yellow_bg">

Jangan overclaim: kita tidak tahu prompt, tools, database, evaluasi internal, atau architecture detail perusahaan-perusahaan tersebut selain yang mereka nyatakan secara publik. Karena itu tutorial praktik di bawah bukan rekonstruksi sistem mereka. </callout>

6. Praktik: Bangun Business Research Agent Sederhana

Sekarang kita buat agent yang menunjukkan empat konsep di infografis:

Model
Tools
Session
Subagents Use case demo:

“Riset sebuah perusahaan, cari fakta terbaru, petakan produk, customer/market, dan risiko utama, lalu buat brief.” Ini adalah lab yang bisa dipraktikkan, bukan klaim production case.

Requirement

Yang dibutuhkan:

akun OpenAI Platform;
API key pada project;
permission untuk Agents API;
Python environment;
package `openai` terbaru. Dokumentasi quickstart menyebut API key perlu scope:
`api.agents.read`
`api.agents.write`
`api.responses.write` Install SDK: ```bash pip install --upgrade openai ``` Set API key:

macOS / Linux

```bash export OPENAI_API_KEY="YOUR_API_KEY" ```

Windows PowerShell

```powershell $env:OPENAI_API_KEY="YOUR_API_KEY" ``` Sumber: Agents API Quickstart

7. STEP 1 — Buat Agent dengan Web Search

Buat file: ```plain text research_agent.py ``` Isi: ```python import json from openai import OpenAI client = OpenAI() session_id = None with client.beta.agents.sessions.create( agent={ "model": "gpt-6-astra", "instructions": ( "Kamu adalah business research agent. " "Gunakan sumber web untuk fakta yang dapat diverifikasi. " "Pisahkan fakta, inferensi, dan hal yang belum diketahui. " "Untuk klaim penting, sertakan sumber." ), "tools": [ { "type": "web_search", "mode": "live" } ], }, environment={"type": "none"}, input=( "Riset OpenAI. Buat brief singkat tentang: " "1) produk/API utama terbaru, " "2) target pengguna, " "3) perkembangan agent platform, " "4) tiga hal yang perlu diverifikasi lebih lanjut." ), stream=True, ) as events: for event in events: payload = json.loads(event.to_json(indent=None)) if payload.get("type") == "agent.session.created": session_id = payload["data"]["id"] print("SESSION:", session_id) if payload.get("type") in { "agent.session.turn.completed", "agent.session.turn.failed", "agent.session.failed", }: print(payload.get("type")) print(event.tojson(indent=None)) ``` Jalankan: ```bash python researchagent.py ```

Apa yang sedang terjadi?

Bukan sekadar:

mermaid

flowchart LR
    P["📝 PROMPT"] --> M["🧠 MODEL"] --> J["💬 SATU JAWABAN"]

Tetapi secara konseptual:

mermaid

flowchart TD
    T["🎯 TASK"] --> M["🧠 MODEL"]
    M --> D{"Butuh data?"}
    D -- "Ya" --> W["🌐 WEB SEARCH"]
    W --> R["📥 SEARCH RESULT"]
    R --> M
    D -- "Sudah cukup" --> V["🔍 Verifikasi & sintesis"]
    V --> O["📄 FINAL RESULT"]

Harness mengelola loop tersebut. OpenAI mendokumentasikan web search sebagai built-in tool yang dapat dipasang pada agent. Agents API mengelola agent loop di atas tools itu. Sumber:

8. STEP 2 — Jangan Kehilangan Session ID

Pada stream akan muncul event `agent.session.created`. Simpan `session_id`. Session ID adalah referensi continuity pekerjaan agent. Konsepnya:

mermaid

flowchart TB
    S["💾 SESSION ID"]
    S --> A["🎯 Initial task"]
    S --> B["💬 Conversation"]
    S --> C["🛠️ Tool activity"]
    S --> D["📦 Saved work"]
    S --> E["🔁 Current turn"]
    E --> F["➕ Next turn"]
    F --> S

OpenAI secara eksplisit menyarankan aplikasi menyimpan session ID bersama conversation state aplikasi. Untuk melihat session-session yang ada: ```python from openai import OpenAI client = OpenAI() page = client.beta.agents.sessions.list(limit=20) for session in page.data: print(session.id, session.status) ``` Sumber: Manage Sessions

9. STEP 3 — Lanjutkan Pekerjaan, Jangan Mulai dari Nol

Setelah punya `session_id`, kirim follow-up ke session yang sama. ```python from openai import OpenAI client = OpenAI() session_id = "sess_GANTI_DENGAN_SESSION_MU" client.beta.agents.sessions.events.create( session_id, events=[ { "type": "agent.session.input.message", "input": [ { "role": "user", "content": [ { "type": "input_text", "text": ( "Sekarang fokuskan riset hanya pada Agents API. " "Bandingkan dengan hasil sebelumnya dan buat " "5 poin perubahan yang paling penting." ), } ], } ], } ], ) ``` Menurut dokumentasi, pesan baru ke session yang idle memulai turn baru dengan conversation yang sudah ada. Jika agent sedang bekerja, input baru dapat digunakan untuk steer active turn.

Untuk aplikasi produksi, buka event stream atau gunakan webhook supaya progress dan early events tidak terlewat. Sumber: Run and Continue Sessions

10. STEP 4 — Tambahkan Subagents

Sekarang ubah konfigurasi awal agent: ```python "multi_agent": { "enabled": True, "max_concurrent_subagents": 3 } ``` Contoh konfigurasi penuh bagian agent: ```python agent={ "model": "gpt-6-astra", "instructions": ( "Kamu adalah lead business research agent. " "Untuk pekerjaan yang independen, delegasikan riset " "ke subagents. Gabungkan temuan, hilangkan duplikasi, " "dan tandai konflik antar sumber." ), "tools": [ { "type": "web_search", "mode": "live" } ], "multi_agent": { "enabled": True, "max_concurrent_subagents": 3 } } ``` Task:

mermaid

flowchart TB
    U["🎯 Riset perusahaan X"] --> L["🧠 LEAD AGENT"]
    L --> A["📦 Agent A<br>Produk & positioning"]
    L --> B["📈 Agent B<br>Customer, market & partnership"]
    L --> C["⚠️ Agent C<br>Risk & verifikasi"]
    A --> S["🧩 SYNTHESIS"]
    B --> S
    C --> S
    S --> O["📄 EXECUTIVE BRIEF"]

Ketika multi-agent diaktifkan, harness menyediakan mekanisme untuk membuat, berkomunikasi dengan, menunggu, dan menghentikan subagents. Kita tidak mendefinisikan primitive tersebut satu per satu. Sumber: Agents API — Multi-agent <callout icon="💡" color="blue_bg">

Jangan otomatis pakai subagents. Jika pekerjaan kecil atau setiap step bergantung langsung pada step sebelumnya, satu agent biasanya lebih sederhana. Gunakan subagents saat pekerjaan benar-benar dapat dipisah menjadi task independen. </callout>

11. STEP 5 — Kapan Perlu Sandbox?

Research agent di atas memakai: ```python environment={"type": "none"} ``` Itu valid karena web search dapat berjalan sebagai service-connected tool dan task kita tidak membutuhkan filesystem atau shell. Tetapi jika task berubah menjadi:

“Cari data → buat CSV → jalankan Python untuk analisis → simpan report.md” kita dapat memberi environment: ```python environment={ "type": "openai_hosted" } ``` Sekarang agent punya environment untuk:

menjalankan code;
bekerja dengan file;
menghasilkan artifact.

Ini alasan kita tidak menyamakan harness dengan sandbox.

Sumber:

12. STEP 6 — Hubungkan Tool Bisnis Sendiri

Agent baru mulai berguna untuk bisnis ketika ia punya capability yang relevan. Contoh: ```plain text get_customer(customer_id) get_ticket(ticket_id) search_contract(query) create_draft_report(data) ``` Function tool pada Agents API bekerja seperti ini:

mermaid

flowchart LR
    M["🧠 MODEL"] -->|request tool| H["⚙️ HARNESS"]
    H -->|function call| A["🖥️ APPLICATION SERVER"]
    A --> F["🔧 BUSINESS FUNCTION"]
    F -->|result| A
    A -->|function result| H
    H -->|observation| M
    M --> O["✅ NEXT ACTION / FINAL"]

Contoh definisi function: ```python { "type": "function", "name": "get_customer", "description": "Ambil profil customer berdasarkan customer ID.", "parameters": { "type": "object", "properties": { "customer_id": { "type": "string" } }, "required": ["customer_id"], "additionalProperties": False } } ``` Perhatikan: mendefinisikan function belum membuat database atau CRM otomatis. Application kita tetap harus menangani function call dan mengembalikan result. Sumber: Agents API — Functions

13. MCP Masuk di Mana?

MCP adalah salah satu cara memberikan tools kepada agent. Contoh:

mermaid

flowchart TB
    H["⚙️ AGENT HARNESS"] <--> M["🧠 MODEL"]
    M --> D{"Pilih capability"}
    D --> F["ƒ CUSTOM FUNCTION"]
    F --> A["🖥️ APP CODE"]
    A --> DB["🗃️ CRM / DB / INTERNAL API"]
    D --> MCP["🔌 MCP"]
    MCP --> S["🌐 MCP SERVER"]
    S --> X["📚 EXTERNAL SYSTEM / DATA"]
    DB --> H
    X --> H

Agents API dapat menemukan tools dari MCP server, memanggilnya, lalu mengembalikan hasil ke agent. Ini berbeda dari mengatakan:

“MCP adalah Agent Harness.” Bukan.

Harness mengelola agent loop.

MCP adalah protokol/tool integration yang dapat digunakan di dalam agent system. Sumber: Agents API — MCP Connections

14. Bagaimana Membaca Event Agent?

Untuk belajar harness, jangan hanya lihat final answer. Lihat lifecycle-nya. Beberapa event/state penting yang perlu dikenali:

mermaid

flowchart LR
    C["🆕 session.created"] --> P["⚙️ session.in_progress"]
    P --> T["✅ turn.completed"]
    T --> I["⏸️ session.idle"]
    I -->|new input| P
    P -. error .-> F["❌ turn/session.failed"]

Failure dapat muncul sebagai turn/session failure. OpenAI mengingatkan bahwa turn completed tidak otomatis berarti setiap tool call sukses. Periksa saved items/tool result jika reliability penting. Ini mindset penting untuk AI Builder:

Jangan mengevaluasi agent hanya dari final text. Periksa prosesnya. Sumber:

15. Framework Troubleshooting: Agent Gagal? Jangan Langsung Ganti Model

Gunakan checklist ini.

1. CONTEXT

Tanya:

Apakah informasi penting tersedia?
Apakah agent membawa terlalu banyak informasi yang tidak relevan?
Apakah instruksi saling bertentangan?

2. TOOLS

Tanya:

Apakah agent punya tool yang benar?
Apakah description tool jelas?
Apakah function benar-benar mengembalikan data yang model butuhkan?
Apakah permission cukup tetapi tidak berlebihan?

3. SESSION

Tanya:

Apakah menggunakan session yang sama ketika memang perlu continuity?
Apakah session ID tersimpan?
Apakah aplikasi membaca status/result dengan benar?

4. LOOP

Tanya:

Apakah tool result benar-benar kembali ke model?
Apakah workflow berhenti terlalu cepat?
Apakah failure terjadi di tool, environment, atau model step?

5. DELEGATION

Tanya:

Apakah task terlalu besar untuk satu agent?
Atau sebaliknya: apakah kita memakai terlalu banyak subagents untuk pekerjaan sederhana? <callout icon="🛠️" color="gray_bg"> Framework troubleshooting ini adalah framework edukasi @kayadigital.ai, bukan nama checklist resmi OpenAI. Pertanyaannya diturunkan dari konsep resmi harness, sessions, tools, environment, dan multi-agent. </callout>

16. Kapan Agent Harness Tidak Diperlukan?

Tidak semua automation perlu agent yang long-running. Jika kebutuhan hanya:

mermaid

flowchart LR
    I["📥 INPUT"] --> A["🔗 FIXED API CALL"]
    A --> T["⚙️ TRANSFORM DATA"]
    T --> O["📤 OUTPUT"]

workflow deterministik biasa sering lebih sederhana, murah, dan mudah diuji. Harness menjadi lebih bernilai ketika task membutuhkan kombinasi:

banyak langkah;
model memilih next action;
tool calls;
recovery/continuity;
context panjang;
parallel investigation;
session yang berlangsung lebih lama. Rule sederhana:

Jika flow sudah sepenuhnya deterministik, jangan memaksa semuanya menjadi agent.

17. Dari Demo ke Production: Tambahkan Guardrails dan Observability

Tutorial di atas baru membahas harness dasar. Sebelum production, pertimbangkan:

authentication dan authorization;
least privilege untuk tools;
human approval untuk action sensitif;
logging dan tracing;
retry/failure handling;
evals;
cost monitoring;
data retention;
sandbox isolation;
webhook untuk background/long-running session. Khusus function yang mempunyai side effect seperti:
mengirim email;
mengubah record;
menghapus data;
melakukan transaksi;
menjalankan command sensitif; jangan hanya mengandalkan “model pasti memilih benar”. Bangun authorization boundary yang eksplisit.

18. Arsitektur Akhir yang Bisa Kamu Jadikan Template

Untuk business research agent:

mermaid

flowchart TB
    U["👤 User / Business Task"] --> H["⚙️ AGENT HARNESS"]
    M["🧠 MODEL"] <--> H

    subgraph CAP["CAPABILITIES"]
        W["🌐 Web Search"]
        F["ƒ Business Functions"]
        A["👥 Subagents"]
    end

    subgraph STATE["CONTINUITY"]
        S["💾 Durable Session"]
        C["🗂️ Working Context"]
    end

    H <--> W
    H <--> F
    H <--> A
    H <--> S
    H <--> C
    H --> O["📄 Verified Brief / Report"]

Jika butuh code/files:

mermaid

flowchart LR
    H["⚙️ AGENT HARNESS"] -->|request execution| E["🧪 ENVIRONMENT / SANDBOX"]
    E --> C["💻 Run Code"]
    E --> F["📁 Files"]
    E --> R["📦 Artifacts"]
    C --> E
    F --> E
    R --> E
    E -->|execution result| H

Dua diagram tersebut jangan digabung menjadi anggapan bahwa sandbox = harness.

19. Ringkasan

Kalau hanya mengingat lima hal dari tutorial ini:

Model bukan seluruh Agent System.
Harness menjalankan model/tool loop dan mempertahankan session.
Tools memberi capability; harness mengoordinasikan penggunaannya.
Environment/sandbox adalah tempat agent menjalankan code dan bekerja dengan file — bukan harness itu sendiri.
Subagents berguna bila task benar-benar dapat dipecah menjadi pekerjaan independen. Takeaway paling sederhana:

MODEL menentukan seberapa pintar AI berpikir.

HARNESS menentukan bagaimana AI terus bekerja sepanjang workflow.

Referensi Resmi

OpenAI — Introducing the Agents API
OpenAI Developers — Agents API Overview
OpenAI Developers — Architecture
OpenAI Developers — Quickstart
OpenAI Developers — Run and Continue Sessions
OpenAI Developers — Manage Sessions
OpenAI Developers — Multi-agent
OpenAI Developers — Web Search
OpenAI Developers — Functions
OpenAI Developers — MCP Connections
OpenAI Developers — OpenAI-hosted Sandboxes <callout icon="✅" color="green_bg">

Status materi: istilah, arsitektur, API flow, session behavior, multi-agent, tools, dan sandbox di atas diverifikasi terhadap dokumentasi resmi OpenAI yang tersedia pada 29 September 2026. Contoh SafetyKit, Hypha, dan Nash.ai diberi atribusi sebagai customer statements yang dipublikasikan OpenAI. Demo Business Research Agent adalah tutorial praktik kita sendiri dan tidak diklaim sebagai implementasi perusahaan tersebut. </callout>