# Tutorial OpenAI Agents SDK TypeScript: Bangun Agent dengan Tool

> Membangun agent dengan @openai/agents dari sisi TypeScript: tool bertipe zod, hosted file search, handoff, streaming dari route Next.js, batas maxTurns, dan test trajectory dengan promptfoo.

URL: https://www.matthewswong.com/id/blog/openai-agents-sdk-typescript-tutorial/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-10-01
- Updated: 2026-10-01
- Category: AI

> **Key takeaway:** OpenAI Agents SDK untuk TypeScript, @openai/agents 0.18.0, membangun agent yang memakai tool dari tiga bagian: tool() dengan schema zod v4, Agent dengan tools dan handoffs, serta run() dengan opsi stream, context, dan maxTurns. Lakukan otorisasi di dalam execute, tetapkan model secara eksplisit, dan uji trajectory tool call dengan provider openai:agents dari promptfoo.

Sebagian besar contoh OpenAI Agents SDK ditulis dalam Python. Bagi tim yang back end ERP-nya memakai NestJS dan portalnya Next.js, sidecar Python untuk asisten status pesanan berarti deployment kedua, salinan kedua dari tipe sales order, dan satu network hop antara agent dan database yang justru menjadi alasan agent itu ada.

Tutorial ini membangun agent tersebut dengan OpenAI Agents SDK untuk TypeScript, yang dipublikasikan di npm sebagai @openai/agents dan berada di versi 0.18.0 saat tulisan ini dibuat. Isinya mencakup function tool bertipe zod, hosted file search tool, handoff ke agent spesialis refund, streaming lewat route handler Next.js, batas maxTurns dengan fallback, dan eval suite di promptfoo. Semua nama opsi diambil dari panduan resmi SDK yang ditautkan di akhir, dan kalau dua halaman resmi saling bertentangan, saya sebutkan.

## Menyiapkan OpenAI Agents SDK di TypeScript

Instalasinya cukup satu: @openai/agents ditambah zod. README-nya mencantumkan Node.js 22 atau lebih baru, Deno, Bun, dan Cloudflare Workers dengan nodejs_compat aktif sebagai runtime yang didukung, dan package ini mendeklarasikan zod ^4.0.0 sebagai peer dependency. Jadi codebase yang masih di zod 3 harus menyelesaikan upgrade itu dulu sebelum menulis tool pertama. API key dibaca secara lazy dari OPENAI_API_KEY saat SDK pertama kali membutuhkan client.

Pengaturan yang sekarang saya anggap wajib adalah model. Panduan models di SDK menyebut agent tanpa model akan memakai default, saat ini gpt-5.6-luna dengan reasoning effort none dan verbosity rendah, dan OPENAI_DEFAULT_MODEL bisa menggantinya untuk seluruh proses. Halaman provider promptfoo untuk SDK yang sama justru menyebut gpt-5.4-mini sebagai default untuk v0.10 ke atas dan memperingatkan bahwa nilai itu bisa berubah. Dua sumber resmi yang tidak sepakat soal default adalah alasan paling jelas untuk tidak pernah bergantung padanya.

## Function tool bertipe dengan zod dan RunContext

Function tool adalah tool() dengan name, description, schema parameters, dan fungsi execute. Dengan schema zod, SDK mengaktifkan strict mode, sehingga argumen yang gagal validasi dikembalikan ke model sebagai error dan tidak pernah sampai ke kode Anda. Argumen kedua execute adalah RunContext, yang membawa objek apa pun yang Anda berikan sebagai context ke run(). Di sini isinya tenant dan user dari session yang sudah terautentikasi: nilai yang tidak pernah dipilih model dan tidak bisa ditimpanya.

Dua detail layak dipasang di setiap tool yang menyentuh database. timeoutMs membatasi setiap pemanggilan, dan dalam mode default error_as_result, timeout mengembalikan pesan ke model bahwa tool tersebut timeout, sehingga query ERP yang lambat menjadi sesuatu yang bisa dijelaskan agent, bukan request yang menggantung. Mengembalikan objek biasa untuk kasus data tidak ditemukan, alih-alih throw, membuat run tetap berjalan: SDK melakukan serialisasi hasil non-string untuk model, sedangkan exception dari execute di-rethrow secara default karena errorFunction default dinonaktifkan.

> isEnabled menentukan apakah model bisa melihat sebuah tool pada turn ini, tetapi ia berjalan sebelum model menghasilkan argumen apa pun, dan panduan tools menegaskan bahwa isEnabled tidak menggantikan otorisasi yang bergantung pada argumen tersebut. Periksa tenant di dalam execute, terhadap nomor order yang benar-benar dipilih model, seperti pada kode di atas.

## Function tool, hosted tool, agent sebagai tool, dan handoff

SDK ini menyediakan lebih banyak cara memberi kemampuan pada agent daripada yang ditunjukkan quickstart, dan semuanya berbeda dalam hal di mana pekerjaan dijalankan dan siapa yang akhirnya menjawab user. Inilah empat yang penting untuk agent pertama.

| Primitive | Dijalankan di mana | Siapa yang menjawab user | Pakai saat |
| --- | --- | --- | --- |
| Function tool tool() | Proses Node Anda, di dalam execute | Agent pemanggil | Membaca atau menulis ke sistem Anda sendiri, seperti database ERP atau API internal |
| Hosted tool: fileSearchTool, webSearchTool, codeInterpreterTool | Server OpenAI, di samping model, lewat Responses API | Agent pemanggil | Mencari di vector store yang Anda upload, web search, atau eksekusi kode di sandbox |
| agent.asTool() | Run bersarang dari agent lain | Agent pemanggil, yang tetap memegang kendali | Langkah spesialis, misalnya ringkasan, yang output-nya dipakai ulang oleh parent |
| handoff() | Run yang sama, dengan agent aktif yang berbeda | Agent spesialis, yang mengambil alih percakapan | Pekerjaan lain dengan instruksi berbeda, seperti refund |

Hosted tool paling mudah ditambahkan sekaligus paling mudah disalahgunakan. Panduan tools mencantumkannya untuk model Responses API, yang menjadi default SDK, jadi memindahkan proses ke Chat Completions dengan setOpenAIAPI membuatnya tidak bisa dipakai. Hosted tool juga berjalan di tempat yang tidak bisa disadap kode Anda, artinya tidak ada execute untuk logging, timeout, atau otorisasi. Untuk kebijakan retur itu tidak masalah, karena dokumennya sama dan publik untuk semua pelanggan. Untuk apa pun yang terikat tenant, tulis function tool.

## Handoff ke agent spesialis refund

Handoff disajikan ke model sebagai tool bernama transfer_to_ diikuti nama agent, jadi agent bernama Refunds agent menjadi transfer_to_refunds_agent. Membungkus target dengan handoff() menambahkan inputType, schema zod kecil yang diisi model saat memilih handoff, dan callback onHandoff yang menerima nilai hasil parse. Saya memakainya untuk alasan refund, yang masuk ke audit log sebelum agent spesialis sempat berbicara.

Dua detail dari panduan handoffs membentuk kode ini. Buat agent triage dengan Agent.create, bukan new Agent, supaya TypeScript menyimpulkan union dari tipe final output di seluruh graph handoff. Lalu, secara default agent penerima melihat seluruh percakapan; berikan inputFilter seperti removeAllTools dari @openai/agents-core/extensions kalau agent spesialis tidak perlu mewarisi tool call dari agent sebelumnya. Setelah run, result.lastAgent memberi tahu agent mana yang menghasilkan jawaban.

## Streaming agent dari route handler Next.js

Memberikan stream: true membuat run() mengembalikan StreamedRunResult, bukan hasil yang sudah selesai. Untuk kotak chat, toTextStream() adalah tingkat detail yang tepat: ia hanya memancarkan teks dari assistant, sehingga tool call, handoff, dan permintaan approval tetap di server kecuali Anda sengaja meneruskannya dari event stream lengkap.

- signal mengikat run ke HTTP request. Panduan streaming menyebut abort pada signal itu sebagai cara menghentikan run lebih awal, sehingga request yang dibatalkan berhenti menghabiskan token alih-alih selesai ke socket yang sudah tertutup.
- stream.completed baru resolve setelah run dan pekerjaan yang tertunda, seperti persistensi session, selesai. Tunggu dengan await, atau pasang catch untuk logging, sebelum menganggap run sudah tuntas.
- Setiap pemanggilan run() adalah satu turn percakapan. Untuk pesan berikutnya, kirim balik result.history, pasang session, atau pakai ulang conversationId atau previousResponseId di sisi server, dan pilih tepat satu, karena panduan running agents memperingatkan bahwa mencampur state client dan server bisa menggandakan context.

## maxTurns dan error handlers: jaring pengaman

Loop runner-nya sederhana: panggil model, jalankan tool call yang ada, tambahkan hasilnya, panggil model lagi, dan berhenti saat model mengembalikan teks tanpa tool call. Setiap putaran adalah satu turn, maxTurns default-nya 10, dan saat batas itu tercapai, SDK melempar MaxTurnsExceededError. Agent yang terus mengulang query sebuah order karena bingung dengan hasilnya akan menabrak batas itu, dan batas itulah yang menentukan apakah kesalahan tersebut hanya memakan enam pemanggilan model atau tagihan tanpa ujung.

errorHandlers mengubah kegagalan yang didukung menjadi jawaban akhir, bukan exception. Key-nya adalah maxTurns, modelRefusal, dan invalidFinalOutput, dengan default sebagai fallback, dan handler mengembalikan finalOutput yang harus cocok dengan outputType agent, ditambah flag includeInHistory yang opsional. Saya lebih suka catch eksplisit di background job, karena kegagalan di sana harus sampai ke orang, dan handler di chat yang dilihat user, karena fallback yang sopan lebih baik daripada HTTP 500.

> Memberikan maxTurns: null menonaktifkan batas sepenuhnya. Panduan running agents mendokumentasikan opsi ini, tetapi pada agent yang punya tool untuk menulis data, opsi ini menghapus satu-satunya batas berapa kali model boleh memanggil tool tersebut dalam satu run.

## Menguji tool call dengan provider openai:agents dari promptfoo

Hanya memeriksa pesan akhir akan melewatkan kegagalan yang paling penting pada agent: jawaban benar yang dicapai lewat tool yang salah, atau tool yang benar dipanggil dengan nomor order yang salah. Provider openai:agents dari promptfoo menjalankan agent yang di-export dari file TypeScript, meneruskan vars setiap test ke run context, dan dengan tracing aktif memungkinkan Anda membuat assertion atas jalurnya sendiri lewat trajectory:tool-used, trajectory:tool-args-match, trajectory:tool-sequence, dan trajectory:goal-success.

Ada dua hal di halaman promptfoo yang perlu dibaca sebelum run pertama. Baris instalasinya mengunci @openai/agents ke ^0.11.8, dan caret pada versi 0.x berhenti sebelum 0.12.0, padahal rilis terbaru di npm adalah 0.18.0; karena halaman yang sama juga meminta Anda memakai promptfoo lokal di project agar eval dan agent berbagi satu instalasi SDK, periksa versi mana yang benar-benar di-resolve oleh lockfile Anda. Lalu, mock mode, yang mengganti hasil tool untuk test yang deterministik, fails closed untuk objek handoff() eksplisit dan untuk hosted tool, dan agent ini memakai keduanya. Karena itu saya membagi suite menjadi tiga.

1. Jalankan agent asli, dengan tool asli terhadap tenant test yang sudah di-seed, untuk assertion trajectory di seluruh graph handoff.
2. Export agent kedua untuk mock mode yang memakai handoff langsung ke agent dan tanpa hosted tool, supaya toolMocks bisa menggantikan get_sales_order.
3. Tetapkan model di agent yang di-export atau di config.model, sesuai rekomendasi halaman provider, supaya perubahan default SDK tidak menggeser baseline Anda.

> @openai/agents membundel @openai/agents-core, @openai/agents-openai, dan @openai/agents-realtime di versi yang sama, saat ini 0.18.0, dan bergantung pada openai ^7.2.0. Kalau aplikasi sudah memanggil package openai secara langsung di tempat lain, pastikan keduanya resolve ke satu salinan saja.

SDK TypeScript ini sudah cukup lengkap sehingga tim NestJS atau Next.js tidak punya alasan menjalankan sidecar Python untuk agent dengan tool. Aturan yang saya bawa dari pembangunan ini singkat: lakukan otorisasi di execute, bukan di isEnabled; jauhkan data tenant dari hosted tool; tetapkan model; batasi maxTurns dan putuskan apa yang terjadi saat batas itu tercapai; dan uji trajectory-nya, bukan hanya balasannya.

## Sumber

- openai/openai-agents-js di GitHub: README, runtime yang didukung, dan instalasi
- OpenAI Agents SDK untuk JavaScript: panduan Models dan model default
- OpenAI Agents SDK untuk JavaScript: panduan Tools dan referensi opsi tool
- OpenAI Agents SDK untuk JavaScript: panduan Handoffs
- OpenAI Agents SDK untuk JavaScript: Running agents, maxTurns, errorHandlers, dan exception
- OpenAI Agents SDK untuk JavaScript: panduan Streaming
- Dokumentasi promptfoo: provider OpenAI Agents dan assertion trajectory

## Source links

- https://github.com/openai/openai-agents-js
- https://openai.github.io/openai-agents-js/guides/models/
- https://openai.github.io/openai-agents-js/guides/tools/
- https://openai.github.io/openai-agents-js/guides/handoffs/
- https://openai.github.io/openai-agents-js/guides/running-agents/
- https://openai.github.io/openai-agents-js/guides/streaming/
- https://www.promptfoo.dev/docs/providers/openai-agents/

## FAQ

### Apakah ada versi TypeScript resmi dari OpenAI Agents SDK?

Ada. OpenAI memublikasikannya sebagai @openai/agents di npm, dikembangkan di repository openai/openai-agents-js berdampingan dengan SDK Python. README-nya mencantumkan Node.js 22 atau lebih baru, Deno, Bun, dan Cloudflare Workers dengan nodejs_compat sebagai runtime yang didukung.

### Versi zod berapa yang dibutuhkan @openai/agents?

Package ini mendeklarasikan zod ^4.0.0 sebagai peer dependency, dan quickstart-nya menyebut SDK memakai Zod v4 untuk schema tool dan structured output. Project yang masih di zod 3 sebaiknya upgrade dulu sebelum menulis tool. Memberikan schema zod sebagai parameters sebuah tool juga mengaktifkan validasi argumen strict.

### Apa yang terjadi kalau agent OpenAI melewati maxTurns di TypeScript?

Run akan melempar MaxTurnsExceededError. Batas default-nya 10 turn, dengan satu turn berarti satu pemanggilan model, dan Anda bisa mengubahnya per run lewat opsi maxTurns. Kalau ingin mengembalikan jawaban fallback, atur errorHandlers.maxTurns agar mengembalikan finalOutput.

### Bisakah respons OpenAI Agents SDK di-stream dari route handler Next.js?

Bisa. Panggil run() dengan stream: true, lalu kembalikan stream.toTextStream() yang di-pipe lewat TextEncoderStream sebagai body Response. Berikan signal dari request supaya request yang dibatalkan ikut menghentikan run, dan await atau catch stream.completed, yang baru selesai setelah run dan pekerjaan persistensi tuntas.

### Bagaimana cara menguji tool call agent @openai/agents dengan promptfoo?

Gunakan provider openai:agents dari promptfoo dengan agent yang di-export dari file TypeScript dan tracing aktif. Assertion trajectory seperti trajectory:tool-used, trajectory:tool-args-match, dan trajectory:tool-sequence memeriksa tool mana yang berjalan dan dengan argumen apa. Perlu dicatat bahwa dokumentasi provider mengunci @openai/agents ke ^0.11.8, dan mock mode tidak mendukung objek handoff() eksplisit maupun hosted tool.

---

- HTML version: https://www.matthewswong.com/id/blog/openai-agents-sdk-typescript-tutorial/
- English: https://www.matthewswong.com/en/blog/openai-agents-sdk-typescript-tutorial/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
