Subagen
Gunakan subagen di ChatGPT dan Codex, serta konfigurasikan agen Codex khusus
- Aplikasi desktop ChatGPT Proyek, file, dan tugas yang lebih lama di desktop.
- ChatGPT web Percakapan, proyek, dan Work di browser Anda.
- Codex CLI Codex di terminal Anda.
- Ekstensi IDE Codex Codex di editor Anda.
ChatGPT Work dan Codex dapat menjalankan alur kerja subagen dengan membuat agen khusus secara paralel, lalu mengumpulkan hasilnya dalam satu respons. Fitur ini dapat sangat membantu untuk tugas kompleks yang sangat mudah diparalelkan, seperti menjelajahi basis kode atau menerapkan rencana fitur bertahap.
Di klien Codex lokal, Anda juga dapat menentukan agen khusus dengan konfigurasi model dan instruksi yang berbeda untuk tugas yang berbeda.
Ketersediaan
ChatGPT Work menyediakan alur kerja dan aktivitas subagen untuk akun yang memenuhi syarat.
Rilis Codex saat ini mengaktifkan alur kerja subagen secara default. Aktivitas subagen muncul di aplikasi desktop ChatGPT, Codex CLI, dan ekstensi IDE.
Karena setiap subagen menjalankan pekerjaan model dan alatnya sendiri, alur kerja subagen menggunakan lebih banyak token daripada eksekusi agen tunggal yang sebanding.
Di ChatGPT Work, minta ChatGPT mendelegasikan pekerjaan independen kepada subagen. Agen berjalan di lingkungan yang dihosting ChatGPT, dan percakapan menampilkan aktivitas serta hasilnya. Pada sebagian besar tingkat kecerdasan, minta delegasi secara eksplisit. Dengan Ultra, ChatGPT dapat secara proaktif mendelegasikan pekerjaan jika agen paralel dapat meningkatkan kecepatan atau kualitas secara berarti.
Minta Codex dalam percakapan aplikasi untuk mendelegasikan bagian pekerjaan yang independen kepada
subagen. Rilis Codex lokal saat ini melakukan delegasi saat Anda memintanya secara langsung atau saat
instruksi AGENTS.md maupun skill yang berlaku memintanya. Aplikasi menampilkan setiap
utas subagen agar Anda dapat memeriksa pekerjaannya dan ringkasan yang dikembalikan ke
percakapan utama.
Minta Codex dalam sesi CLI interaktif untuk menggunakan subagen. Codex juga dapat mengikuti
instruksi AGENTS.md atau skill yang berlaku dan meminta pendelegasian. Gunakan
/subagents untuk memeriksa dan beralih antarutas agen saat agen berjalan. Utas
utama menggabungkan hasil subagen ke dalam respons akhirnya.
Minta Codex dalam percakapan IDE untuk mendelegasikan bagian pekerjaan yang independen kepada subagen.
Codex juga dapat mengikuti instruksi AGENTS.md atau skill yang berlaku dan meminta
delegasi. Saat UI agen latar belakang tersedia, subagen aktif muncul
di atas kolom penulisan. Perluas panel untuk melihat statusnya, menghentikan semua
subagen aktif, atau membuka utas subagen tertentu.
Mengapa alur kerja subagen membantu
Bahkan dengan jendela konteks yang besar, model tetap memiliki batas. Jika Anda memenuhi percakapan utama (tempat Anda menetapkan persyaratan, batasan, dan keputusan) dengan output perantara yang bising seperti catatan eksplorasi, log pengujian, pelacakan tumpukan, dan output perintah, keandalan sesi dapat menurun seiring waktu.
Hal ini sering disebut sebagai:
- Polusi konteks: informasi yang berguna terkubur di bawah output perantara yang bising.
- Pembusukan konteks: kinerja menurun ketika percakapan dipenuhi detail yang kurang relevan.
Untuk latar belakang, lihat tulisan Chroma tentang pembusukan konteks.
Alur kerja subagen membantu dengan memindahkan pekerjaan yang bising dari utas utama:
- Jaga agar agen utama tetap berfokus pada persyaratan, keputusan, dan output akhir.
- Jalankan subagen khusus secara paralel untuk eksplorasi, pengujian, atau analisis log.
- Kembalikan ringkasan dari subagen, bukan output perantara mentah.
Alur kerja ini juga dapat menghemat waktu jika pekerjaan dapat dijalankan secara independen dan paralel, serta membuat tugas berskala lebih besar lebih mudah ditangani dengan memecahnya menjadi bagian-bagian terbatas. Misalnya, Codex dapat membagi analisis dokumen dengan jutaan token menjadi masalah yang lebih kecil dan mengembalikan kesimpulan ringkas kepada utas utama.
Sebagai titik awal, gunakan agen paralel untuk tugas yang banyak melibatkan pembacaan seperti eksplorasi, pengujian, triase, dan peringkasan. Berhati-hatilah dengan alur kerja paralel yang banyak melibatkan penulisan karena agen yang mengedit kode secara bersamaan dapat menimbulkan konflik dan meningkatkan beban koordinasi.
Istilah inti
Codex menggunakan beberapa istilah terkait dalam alur kerja subagen:
- Alur kerja subagen: Alur kerja tempat Codex menjalankan agen paralel dan menggabungkan hasilnya.
- Subagen: Agen terdelegasi yang dimulai Codex untuk menangani tugas tertentu.
- Utas agen: Utas tempat subagen melakukan pekerjaannya. Klien yang didukung memungkinkan Anda membuka utas ini untuk memeriksa kemajuan atau hasil.
Memicu alur kerja subagen
Pada sebagian besar tingkat kecerdasan, minta penggunaan subagen atau pekerjaan agen paralel secara langsung. Ultra memungkinkan delegasi proaktif, sehingga ChatGPT dapat mendelegasikan pekerjaan independen yang sesuai tanpa permintaan terpisah.
Mintalah subagen atau pekerjaan agen paralel secara langsung. Codex juga dapat mendelegasikan saat instruksi proyek atau skill yang berlaku memintanya.
Dalam praktiknya, pemicuan manual berarti menggunakan instruksi langsung seperti "buat dua agen," "delegasikan pekerjaan ini secara paralel," atau "gunakan satu agen per poin." Alur kerja subagen menggunakan lebih banyak token daripada eksekusi agen tunggal yang sebanding karena setiap subagen menjalankan pekerjaan model dan alatnya sendiri.
Prompt subagen yang baik harus menjelaskan cara membagi pekerjaan, apakah Codex harus menunggu semua agen sebelum melanjutkan, serta ringkasan atau output apa yang harus dikembalikan.
Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.Memilih model dan penalaran
Agen yang berbeda memerlukan pengaturan model dan penalaran yang berbeda.
Di ChatGPT Work, pilih model dan tingkat kecerdasan dari kolom penulisan. Tingkat kecerdasan yang tersedia dapat mencakup Light, Medium, High, Extra High, dan Max, tergantung pada model yang dipilih. Ultra hanya tersedia bagi akun yang memenuhi syarat dan model yang didukung. Tingkat ini menggunakan penalaran maksimum dan memungkinkan ChatGPT mendelegasikan pekerjaan yang sesuai secara proaktif kepada subagen.
Pada tingkat kecerdasan lainnya, mintalah subagen secara eksplisit saat Anda ingin pekerjaan didelegasikan secara paralel.
Jika Anda tidak mengonfigurasi model subagen atau model_reasoning_effort,
subagen mewarisi model dan upaya penalaran agen induk. Jika permintaan pembuatan eksplisit
atau nilai default [agents] memilih model tanpa
upaya penalaran yang eksplisit atau dikonfigurasi, subagen menggunakan upaya penalaran default
model tersebut. Untuk menyeimbangkan kecerdasan, kecepatan, dan biaya untuk setiap tugas,
minta model atau upaya penalaran tertentu dalam prompt Anda,
konfigurasikan nilai default [agents] di config.toml, atau tetapkan model dan
model_reasoning_effort langsung dalam file agen kustom.
Misalnya, gunakan gpt-6-luna untuk pemindaian cepat atau konfigurasi gpt-6.1-sol dengan upaya penalaran lebih tinggi untuk penalaran yang lebih menuntut.
Pilihan model
gpt-6.1-sol: Mulailah di sini untuk agen dengan tugas yang menuntut. Gunakan untuk pekerjaan ambigu dengan beberapa langkah yang memerlukan perencanaan, penggunaan alat, validasi, dan tindak lanjut hingga tuntas dalam konteks yang lebih luas.gpt-6-luna: Gunakan untuk agen cepat dengan cakupan sempit yang menangani pekerjaan yang jelas, berulang, atau bervolume tinggi.
Upaya penalaran (model_reasoning_effort)
Untuk GPT-6.1 Sol, gunakan upaya penalaran yang didukung oleh klien dan model
pilihan Anda. Untuk pengaturan model eksplisit, mulailah dengan high untuk GPT-6 Luna atau low
untuk GPT-6 Astra. Sesuaikan dengan tugas menggunakan tingkat yang didukung model pilihan Anda.
ultra: Gunakan untuk penalaran terdalam jika model pilihan mendukungnya.maxdanxhigh: Gunakan untuk penalaran yang sangat menuntut jika model pilihan mendukung tingkat ini.high: Gunakan saat agen perlu menelusuri logika kompleks, memeriksa asumsi, atau menangani kasus tepi (misalnya, agen peninjau atau agen yang berfokus pada keamanan).medium: Menyeimbangkan kecepatan dan kedalaman.low: Gunakan jika tugasnya sederhana dan kecepatan menjadi prioritas utama.
Upaya penalaran yang lebih tinggi meningkatkan waktu respons dan penggunaan token, tetapi dapat meningkatkan kualitas untuk pekerjaan kompleks. Untuk detailnya, lihat Model, Dasar-dasar konfigurasi, dan Referensi Konfigurasi.
Orkestrasi dan kontrol utas
ChatGPT atau Codex menangani orkestrasi antaragen, termasuk membuat subagen baru, mengarahkan instruksi tindak lanjut, menunggu hasil, dan menutup utas agen.
Saat banyak agen berjalan, Codex menunggu hingga semua hasil yang diminta tersedia, lalu mengembalikan respons gabungan.
Pada sebagian besar tingkat kecerdasan, ChatGPT membuat agen setelah menerima permintaan langsung. Dengan Ultra, ChatGPT juga dapat mendelegasikan secara proaktif saat pekerjaan paralel berguna.
Rilis Codex lokal saat ini membuat agen setelah menerima permintaan langsung atau instruksi proyek maupun skill yang berlaku.
Untuk melihat cara kerjanya, coba prompt berikut pada proyek Anda:
I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the codeMengelola subagen
Buka Subagents untuk melihat daftar Active dan Done yang bersifat hanya baca. Pilih subagen yang telah selesai untuk memeriksa detail dan hasilnya. Bilah samping web melaporkan aktivitas subagen; bilah ini tidak menyediakan kontrol untuk menghentikan atau mengarahkan subagen tertentu.
- Buka utas subagen dari aktivitas yang ditampilkan di utas utama untuk memeriksa pekerjaannya.
- Minta Codex secara langsung untuk mengarahkan subagen yang sedang berjalan, menghentikannya, atau menutup utas subagen yang telah selesai.
- Gunakan
/subagentsdi CLI untuk beralih antarutas agen aktif dan memeriksa utas yang sedang berjalan. - Minta Codex secara langsung untuk mengarahkan subagen yang sedang berjalan, menghentikannya, atau menutup utas agen yang telah selesai.
- Jika panel agen latar belakang tersedia, perluas panel tersebut untuk memeriksa status, menghentikan subagen aktif, atau membuka utas subagen.
- Minta Codex secara langsung untuk mengarahkan subagen yang sedang berjalan, menghentikannya, atau menutup utas subagen yang telah selesai.
Persetujuan dan kontrol sandbox
Subagen mewarisi kebijakan sandbox Anda saat ini.
ChatGPT Work menjalankan subagen di lingkungan yang dihostingnya dan tidak menyediakan sandbox Codex lokal atau kontrol mode persetujuan. Subagen menggunakan alat yang tersedia bagi percakapan induk. Izin situs web dan konektor tetap berlaku khusus untuk masing-masing alat.
Subagen mewarisi mode izin yang dipilih di bawah kolom penulisan. Pilih mode izin untuk giliran induk sebelum Anda meminta Codex mendelegasikan pekerjaan.
Dalam sesi CLI interaktif, permintaan persetujuan dapat muncul dari utas agen yang tidak aktif
meskipun Anda sedang melihat utas utama. Lapisan persetujuan
menampilkan label utas sumber, dan Anda dapat menekan o untuk membuka utas tersebut sebelum
menyetujui, menolak, atau menjawab permintaan.
Dalam alur noninteraktif, atau kapan pun suatu eksekusi tidak dapat menampilkan persetujuan baru, tindakan yang memerlukan persetujuan baru akan gagal dan Codex menyampaikan kesalahan tersebut kembali ke alur kerja induk.
Subagen mewarisi pengaturan sandbox dan persetujuan yang berlaku pada giliran induk,
termasuk perubahan yang dibuat dengan /permissions atau --yolo. File agen kustom
tidak dapat menggantikan pengaturan tersebut.
Subagen mewarisi mode izin yang dipilih di bawah kotak penulisan pesan. Pilih mode izin untuk giliran induk sebelum Anda meminta Codex mendelegasikan pekerjaan.
Atur kontrol sandbox dan persetujuan pada sesi induk. Instruksi agen kustom dapat meminta agen untuk menghindari pengeditan, tetapi tidak membuat sandbox hanya baca yang terpisah.
Agen khusus
Codex disertai agen bawaan:
default: agen fallback serbaguna.worker: agen yang berfokus pada eksekusi untuk implementasi dan perbaikan.explorer: agen eksplorasi basis kode yang banyak melibatkan pembacaan.
Untuk menentukan agen khusus Anda sendiri, tambahkan file TOML mandiri di bawah
~/.codex/agents/ untuk agen pribadi atau .codex/agents/ untuk agen dengan cakupan
proyek.
Setiap file mendefinisikan satu agen kustom. Agen kustom dapat mengubah pengaturan model dan instruksi atau menonaktifkan kemampuan yang didukung. Agen ini mewarisi izin, penyedia, dan MCP server dari induknya; file agen kustom tidak dapat menimpa pengaturan tersebut.
Setiap file agen khusus mandiri harus menentukan:
namedescriptiondeveloper_instructions
Jika file agen kustom menetapkan model atau model_reasoning_effort, nilai dalam
file tersebut diutamakan. Sebelum menerapkan file, Codex menentukan setiap pengaturan
berdasarkan nilai eksplisit saat pembuatan agen, lalu nilai bawaan [agents] yang sesuai, lalu
nilai induknya. Jika permintaan pembuatan agen yang eksplisit atau nilai bawaan [agents]
memilih model dan keduanya tidak menentukan tingkat upaya penalaran, Codex menggunakan
tingkat upaya bawaan model tersebut. File agen kustom yang hanya menetapkan model
mempertahankan tingkat upaya yang telah ditentukan ini. Tetapkan juga model_reasoning_effort dalam
file tersebut jika model yang dipilih tidak mendukung tingkat upaya tersebut atau Anda menginginkan
tingkat yang berbeda. Skill diwarisi dari induk, dan agen kustom dapat menonaktifkan
skill tertentu dengan skills.config.
Pengaturan global
Pengaturan subagen global tetap berada di bawah [agents] dalam konfigurasi Anda.
| Bidang | Jenis | Wajib | Tujuan |
|---|---|---|---|
agents.enabled |
boolean | Tidak | Mengaktifkan atau menonaktifkan alat multiagen. |
agents.max_concurrent_threads_per_session |
number | Tidak | Membatasi utas agen hasil pembuatan yang terbuka bersamaan, tidak termasuk agen utama. |
agents.default_subagent_model |
string | Tidak | Menetapkan model default untuk agen hasil pembuatan. |
agents.default_subagent_reasoning_effort |
string | Tidak | Menetapkan upaya penalaran default untuk agen hasil pembuatan. |
agents.interrupt_message |
boolean | Tidak | Mencatat pesan yang terlihat oleh model saat giliran agen dihentikan. |
Catatan:
agents.enabledsecara default bernilaitrue. Tetapkan menjadifalseuntuk menonaktifkan alat multiagen.- Jika Anda tidak menetapkan
agents.max_concurrent_threads_per_session, Codex memilih default. Konfigurasi yang sudah ada dapat tetap menggunakanagents.max_threadssebagai alias lama. - Nilai pembuatan eksplisit menggantikan
agents.default_subagent_modeldanagents.default_subagent_reasoning_effort. agents.interrupt_messagesecara default bernilaitrue. Tetapkan menjadifalseuntuk menghilangkan pesan penghentian yang terlihat oleh model dari konteks agen.- Jika nama agen khusus sama dengan agen bawaan seperti
explorer, agen khusus Anda menjadi prioritas.
Skema file agen khusus
| Bidang | Jenis | Wajib | Tujuan |
|---|---|---|---|
name |
string | Ya | Nama agen yang digunakan Codex saat membuat atau merujuk agen ini. |
description |
string | Ya | Panduan bagi pengguna tentang kapan Codex harus menggunakan agen ini. |
developer_instructions |
string | Ya | Instruksi inti yang menentukan perilaku agen. |
Gunakan model, model_reasoning_effort, model_reasoning_summary, dan
model_verbosity untuk menyesuaikan perilaku model.
Lihat referensi konfigurasi untuk mengetahui
nilai yang diterima.
Untuk mengurangi kemampuan agen kustom, tetapkan kunci fitur yang didukung ke false:
features.shell_tool, features.apps, features.plugins,
features.memories, atau features.request_permissions_tool. Nonaktifkan
skill tertentu dengan skills.config atau skill bawaan dengan
skills.bundled.enabled = false. Tetapkan skills.include_instructions = false untuk
menghilangkan blok instruksi skill otomatis. Persyaratan terkelola tetap berlaku.
Pengaturan sesi lainnya, termasuk sandbox_mode, approval_policy,
model_provider, dan mcp_servers, tidak menimpa konfigurasi induk
jika ditempatkan dalam file agen kustom. Tingkat layanan juga mengikuti preferensi
sesi utama. Konfigurasikan MCP server pada sesi induk agar agen
dapat menggunakannya.
Codex mengidentifikasi agen khusus berdasarkan bidang name. Menyamakan nama file dengan
nama agen merupakan konvensi paling sederhana, tetapi bidang name adalah sumber
kebenarannya.
Contoh agen khusus
Agen khusus terbaik memiliki cakupan sempit dan pendirian yang tegas. Berikan setiap agen tugas yang jelas, permukaan alat yang sesuai dengan tugas tersebut, dan instruksi yang mencegahnya beralih ke pekerjaan lain di luar cakupan.
Contoh-contoh ini menggunakan GPT-6.1 Sol jika akun yang Anda gunakan untuk masuk atau ruang kerja Anda memiliki akses. Jika model tersebut tidak tersedia, pilih model yang dapat Anda gunakan.
Contoh 1: Peninjauan PR
Pola ini membagi peninjauan kepada tiga agen khusus yang berfokus:
pr_explorermemetakan basis kode dan mengumpulkan bukti.reviewermencari risiko kebenaran, keamanan, dan pengujian.docs_researchermemeriksa dokumentasi kerangka kerja atau API melalui MCP server khusus.
Konfigurasi proyek (.codex/config.toml):
[agents]
max_concurrent_threads_per_session = 8
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp".codex/agents/pr-explorer.toml:
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
""".codex/agents/reviewer.toml:
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Review code like an owner.
Do not edit files.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
""".codex/agents/docs-researcher.toml:
name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"""
Penyiapan ini cocok untuk prompt seperti:
Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.Contoh 2: Men-debug integrasi frontend
Pola ini berguna untuk regresi UI, alur browser yang tidak stabil, atau bug integrasi yang melintasi kode aplikasi dan produk yang sedang berjalan.
Konfigurasi proyek (.codex/config.toml):
[agents]
max_concurrent_threads_per_session = 6
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20.codex/agents/code-mapper.toml:
name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Map the code that owns the failing UI flow.
Do not edit files.
Identify entry points, state transitions, and likely files before the worker starts editing.
""".codex/agents/browser-debugger.toml:
name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
""".codex/agents/ui-fixer.toml:
name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
"""
[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = falsePenyiapan ini cocok untuk prompt seperti:
Investigate why the settings modal fails to save. Have browser_debugger reproduce it, code_mapper trace the responsible code path, and ui_fixer implement the smallest fix once the failure mode is clear.