Eksekusi workflow
Ikuti eksekusi workflow milik agen: status dan event-nya, kapan pekerjaan selesai, apa yang diblokir oleh sebuah eksekusi, anggaran, dan batas.
Workflow (alur kerja) adalah program yang ditulis oleh agen untuk menjalankan banyak agen dan menggabungkan apa yang mereka kembalikan. Workflow run (eksekusi workflow) adalah satu kali jalannya sebuah workflow. Dynamic workflows (alur kerja dinamis) adalah fitur yang memungkinkan agen menulis workflow dan memulai eksekusi. Anda mengaktifkan atau menonaktifkannya dengan pengaturan workflows di blok multiagent milik agen.
Server menjalankan workflow di latar belakang. Agen-agennya bekerja di thread sesi yang dibuat server sesuai kebutuhan workflow. Anda mengikuti eksekusi melalui aliran event sesi. Hanya agen yang memulai eksekusi. Tidak ada event yang Anda kirim yang mengakhiri eksekusi; mengarsipkan sesi dapat mengakhirinya.
Cara kerja alur kerja dinamis
Agen yang dijalankan sesi menulis setiap workflow untuk pekerjaan yang Anda jelaskan. Workflow adalah sebuah program: ia menjalankan agen lain, mengumpulkan apa yang dikembalikan masing-masing, dan menggabungkan hasilnya. Dengan begitu, agen dapat menangani tugas yang terlalu besar untuk satu percakapan, seperti peninjauan ratusan dokumen. Selama eksekusi, agen dapat terus bekerja atau mengakhiri gilirannya, dan ia dapat memeriksa eksekusi tersebut.
Diagram menunjukkan satu contoh. Setiap workflow yang ditulis agen memiliki fase dan agennya sendiri. Sebuah eksekusi memiliki lapisan-lapisan berikut:
- Eksekusi workflow: Server menjalankan workflow di latar belakang, sebagai satu eksekusi workflow. Sebuah sesi dapat memiliki beberapa eksekusi yang terbuka pada saat yang sama.
- Fase: Workflow dapat membagi pekerjaannya menjadi fase-fase. Fase adalah tahap bernama dari eksekusi, seperti "Read the contracts". Anda mengikuti kemajuan eksekusi melalui event fasenya.
- Thread agen: Dalam sebuah fase, program menjalankan agen. Setiap agen bekerja di thread sesi miliknya sendiri, dengan prompt yang ditulis oleh program. Agen dalam sebuah eksekusi dapat berupa agen inline, yang didefinisikan sendiri oleh program, atau agen predefined, yang Anda cantumkan di
workflows.predefined_agents. Untuk apa yang ditampilkan setiap thread, lihat Thread sebuah eksekusi.
Program dapat melakukan hal-hal berikut:
- Menjalankan agen pada saat yang sama: Program dapat menjalankan banyak agen pada saat yang sama, yang disebut "fanning out" (penyebaran). Dalam diagram, tiga agen membaca kontrak di fase pertama.
- Meneruskan hasil dari satu agen ke agen lain: Setiap agen mengembalikan hasilnya ke program. Program dapat meneruskan hasil tersebut ke agen lain. Dalam diagram, agen di fase kedua bekerja dengan apa yang dikembalikan oleh tiga agen pertama. Agen-agen dalam sebuah eksekusi juga bekerja dengan file yang sama, di sandbox sesi.
- Mengambil langkah berikutnya sendiri: Hasil agen masuk ke program, bukan ke agen yang dijalankan sesi. Program menentukan agen mana yang berjalan berikutnya, dan ia menulis prompt mereka.
- Mengulang dan memilih: Di dalam sebuah fase, program dapat mengulang pekerjaan dan memilih langkah berikutnya berdasarkan apa yang dikembalikan agen. Misalnya, program dapat meminta sebuah draf direvisi hingga peninjauan lolos atau sejumlah putaran yang ditetapkan habis. Dalam diagram, program dapat mengulang sebuah langkah di dalam fase kedua.
- Menangani agen yang gagal: Ketika salah satu agennya gagal, program dapat menangani kegagalan tersebut atau membiarkannya mengakhiri eksekusi.
Ketika eksekusi berakhir, agen yang dijalankan sesi mendapat giliran untuk membaca apa yang dilakukan eksekusi tersebut. Agen kemudian dapat menjawab Anda atau memulai eksekusi lain. Event eksekusi mencantumkan kasus-kasus di mana giliran itu datang belakangan atau tidak datang.
Anda dapat memandu cara eksekusi melakukan pekerjaan, misalnya cara ia membagi pekerjaan dan apa yang dilakukannya ketika sebuah agen gagal. Lihat Beri tahu agen kapan menggunakan eksekusi.
Bagaimana eksekusi berpindah antar statusnya
Sebuah eksekusi dimulai dalam status running atau idle. Mencapai anggaran, misalnya, menjeda eksekusi yang sedang berjalan, sehingga menjadi idle; menaikkan atau menghapus anggaran kemudian membuatnya berjalan lagi, kecuali jika interupsi juga menjedanya. Eksekusi yang sedang berjalan berakhir ketika workflow-nya selesai, agen menghentikannya, eksekusi gagal, masa hidupnya habis, atau sesi diarsipkan. Eksekusi yang idle juga dapat berakhir, misalnya ketika agen menghentikannya atau sesi diarsipkan.
Sebuah eksekusi terbuka sejak event workflow_run.created hingga event workflow_run.status_ended, baik saat berjalan maupun idle. Eksekusi berstatus idle selama dijeda, misalnya pada anggaran sesi. Masa hidup eksekusi secara default adalah 24 jam. Agen dapat menetapkan masa hidup yang lebih pendek saat memulai eksekusi. Waktu yang dihabiskan eksekusi untuk menunggu klien Anda dihitung dalam masa hidup tersebut. Jeda tidak menghentikan berjalannya masa hidup eksekusi, sehingga eksekusi yang tetap dijeda dapat berakhir dengan timeout_error. Event-event berikut melaporkan awal eksekusi, fase-fasenya, dan akhirnya. Jeda pada anggaran juga mengirim satu event. Jeda setelah interupsi mungkin tidak mengirim event apa pun. Setiap event workflow_run.* menyertakan workflow_run_id, yang bernilai null hanya pada workflow_run.error ketika tidak ada eksekusi yang dibuat.
Event eksekusi
Event eksekusi tiba di aliran event sesi, yaitu aliran thread utama, dan mencantumkan event sesi juga mengembalikannya. Event eksekusi tidak memicu webhook. Event status dari thread eksekusi tiba di aliran yang sama. Masing-masing menyebutkan thread-nya di session_thread_id, dan thread sebuah eksekusi adalah thread yang event session.thread_created-nya memiliki workflow_run_id eksekusi tersebut.
| Event | Kapan tiba | Apa yang harus dilakukan |
|---|---|---|
workflow_run.created | Agen memulai sebuah eksekusi. Menyertakan workflow_run_id (wrun_…), name dan description eksekusi, serta phases, yaitu fase-fase yang dideklarasikan workflow, masing-masing dengan id, name, dan description. description bernilai null ketika workflow tidak memberikannya. phases selalu ada dan dapat kosong. name dan description eksekusi dan fase adalah teks yang ditulis model, sehingga dapat mengulang kata-kata dari permintaan Anda. name eksekusi juga dapat berupa nama yang ditetapkan server. | Lacak eksekusi sebagai terbuka. Tampilkan name-nya, dan kemajuan terhadap phases. |
workflow_run.status_running | Ketika eksekusi mulai dijalankan, yang bisa beberapa saat setelah created, dan setiap kali eksekusi dilanjutkan setelah jeda pada anggaran. Melanjutkan setelah interupsi mungkin tidak mengirimnya. Eksekusi yang dimulai dalam status idle mungkin mendapat workflow_run.status_idle terlebih dahulu. | Tampilkan eksekusi sebagai sedang berjalan. |
workflow_run.status_idle | Eksekusi dijeda, misalnya pada anggaran sesi. Event ini tidak menyebutkan alasannya. Jeda setelah interupsi mungkin tidak mengirimnya. | Untuk melanjutkan, lihat Anggaran dan batas atau Menginterupsi sesi dengan eksekusi yang terbuka. |
workflow_run.phase_started, workflow_run.phase_ended | Workflow memasuki atau meninggalkan sebuah fase, atau akhir eksekusi menutup fase yang masih terbuka. Event akhir tidak menyebutkan apakah pekerjaan fase tersebut selesai. Keduanya menyertakan workflow_run_phase_id. Event akhir juga memiliki phase_started_id, yaitu id dari event awal yang ditutupnya. Keduanya tidak memiliki nama fase: cari berdasarkan workflow_run_phase_id di phases dari workflow_run.created. | Perbarui kemajuan. Fase berjalan satu per satu, dalam urutan phases, masing-masing paling banyak sekali, tetapi API tidak menjaminnya. Cocokkan akhir fase dengan awalnya berdasarkan phase_started_id. Tangani lebih dari satu fase yang terbuka, fase yang tidak ada di phases, dan fase yang tercantum tetapi tidak pernah dimulai, bahkan dalam eksekusi yang selesai. Setiap fase yang dimulai juga berakhir, sebelum workflow_run.status_ended eksekusi. |
workflow_run.status_ended | Eksekusi berakhir. Selalu menjadi event terakhir dari event workflow_run.* eksekusi. Menyertakan result. | Baca result (tabel berikutnya). Agen kemudian mendapat giliran untuk membaca bagaimana eksekusi berakhir. Pada anggaran, atau saat thread utama menunggu klien Anda, giliran itu datang belakangan. Setelah interupsi, giliran itu mungkin tidak datang: kirim user.message, atau baca result sendiri. Setelah pengarsipan atau penghentian, giliran itu tidak datang. |
workflow_run.error | Server melaporkan error dari sebuah eksekusi, atau permulaan yang ditolaknya. Eksekusi yang berakhir dengan error mendapat event ini, dengan error yang sama, sebelum workflow_run.status_ended-nya. Menyertakan error: sebuah type dan message yang aman untuk dicatat di log. workflow_run_id bernilai null ketika tidak ada eksekusi yang dibuat. | Catat di log, dan jangan anggap sebagai akhir eksekusi. Jika workflow_run_id bernilai null, tidak ada eksekusi yang dimulai. Jika tidak, terus lacak eksekusi hingga workflow_run.status_ended-nya. |
result | Arti |
|---|---|
{"type": "completed"} | Workflow selesai berjalan. Hasil ini tidak menyebutkan apakah pekerjaan tersebut berhasil. Eksekusi dapat berakhir completed meskipun pekerjaan di thread-nya gagal, atau sebuah thread tidak dapat dibuat. Untuk menemukan pekerjaan yang gagal, baca event dari setiap thread eksekusi. |
{"type": "stopped"} | Agen menghentikan eksekusi, atau sesi diarsipkan. Event ini tidak menyebutkan yang mana, dan rilis mendatang mungkin menambahkan penyebab lain. |
error dengan timeout_error | Eksekusi mencapai masa hidupnya: 24 jam secara default, atau yang ditetapkan agen. |
error dengan program_error | Workflow gagal. Kodenya gagal, atau melanggar aturan untuk workflow, selain batas. Atau salah satu thread eksekusi gagal, atau tidak dapat dibuat, dan workflow membiarkan hal itu mengakhiri eksekusi. |
error dengan thread_limit_error | Eksekusi melampaui batas jumlah agen yang dimulai oleh workflow. |
error dengan unknown_error | Server tidak dapat melanjutkan eksekusi, atau eksekusi melampaui salah satu batas lain server untuk workflow. |
Hasil error terlihat seperti {"type": "error", "error": {"type": "timeout_error", "message": "..."}}, di mana message aman untuk dicatat di log. Perlakukan result.type yang tidak dikenali sebagai eksekusi yang berakhir dengan cara lain, dan error.type yang tidak dikenali sebagai error. Ketika sesuatu yang menjadi ketergantungan sesi gagal, seperti model, server MCP, kredensial, atau penagihan, aliran thread yang gagal mendapat session.error. Hal itu tidak mengakhiri eksekusi dengan sendirinya. Tetapi jika hal itu membuat salah satu thread eksekusi gagal, dan workflow membiarkan hal itu mengakhiri eksekusi, eksekusi berakhir dengan program_error.
Misalnya, Anda bertanya kepada agen peninjau kontrak mana dari 300 kontrak yang memiliki klausul perubahan kendali, dan agen memulai sebuah eksekusi:
workflow_run.createdmenamai eksekusi "Find change-of-control clauses" dan mencantumkan fase "Read the contracts" dan "Reconcile the findings" diphases. Kemudianworkflow_run.status_runningmenyusul.- Event fase menandai setiap fase, dan setiap thread yang dibuat eksekusi mengirim
session.thread_createddenganworkflow_run_ideksekusi. workflow_run.status_endedtiba denganresult: {"type": "completed"}.- Agen menjawab, "41 dari 300 kontrak memilikinya," dan
session.status_idletiba denganend_turn.
Event pertama eksekusi mencantumkan fase-fasenya:
{
"type": "workflow_run.created",
"id": "sevt_01abc...",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"name": "Find change-of-control clauses",
"description": "Reads each contract and lists those that have the clause.",
"phases": [
{
"id": "wrph_01Kd3a1f3",
"name": "Read the contracts",
"description": "Reads each contract for the clause."
},
{ "id": "wrph_01Kd3b7c9", "name": "Reconcile the findings", "description": null }
],
"processed_at": "2026-10-09T14:01:45Z"
}Setiap event fase menyebutkan fasenya berdasarkan workflow_run_phase_id. Itu adalah sebuah id di phases, tetapi API tidak menjaminnya:
{
"type": "workflow_run.phase_started",
"id": "sevt_01def...",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"workflow_run_phase_id": "wrph_01Kd3a1f3",
"processed_at": "2026-10-09T14:01:46Z"
}Event terakhir eksekusi melaporkan bagaimana eksekusi berakhir:
{
"type": "workflow_run.status_ended",
"id": "sevt_01ghi...",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"result": { "type": "completed" },
"processed_at": "2026-10-09T14:09:12Z"
}Thread sebuah eksekusi
Setiap agen dalam sebuah eksekusi bekerja di thread sesi miliknya sendiri, yang dibuat server sesuai kebutuhan workflow. Anda dapat mencantumkan, membaca, dan melakukan streaming thread eksekusi seperti thread anak mana pun, dan menjawab panggilan alatnya dari aliran utama. Untuk menghentikannya, minta agen menghentikan eksekusi (lihat Menginterupsi sesi dengan eksekusi yang terbuka). Anda tidak dapat menghentikan satu thread berdasarkan ID-nya, atau mengarsipkannya selama eksekusinya terbuka.
- Pengelompokan: Thread eksekusi membawa
workflow_run_ideksekusi, begitu pula eventsession.thread_createdyang mengumumkannya. Thread lain, dan eventsession.thread_createdyang mengumumkannya, memilikiworkflow_run_idyang diatur kenull. - Agen:
agentmenunjukkan agen yang dijalankan thread. Untuk agen yang Anda cantumkan dimultiagent.workflows.predefined_agents,agentmemilikiiddanversionagen tersebut, seperti pada thread subagen yang Anda cantumkan. Untuk agen yang didefinisikan workflow (agen inline),agentmemilikitypeinlinedan tanpaidatauversion. Agen ini memiliki prompt sistem yang ditulis workflow, bukan milik agen sesi. Agen ini juga memiliki nama dan deskripsi yang diberikan workflow; server menetapkan nama jika workflow tidak memberikannya. Agen ini menggunakan model agen sesi, yaitu agen yang dijalankan sesi. Alat, server MCP, dan skill-nya adalah subset dari milik agen sesi. Agen ini mendapatkan semuanya, tetapi API tidak menjaminnya. Alat-alatnya mempertahankan kebijakan izinnya. - Apa yang dibagikan thread: Thread eksekusi bekerja di sandbox sesi, sehingga setiap thread bekerja dengan file yang sama. Itu termasuk file dari memory store yang di-mount sesi. Agen yang didefinisikan workflow menggunakan server MCP-nya dengan kredensial yang di-resolve sesi untuknya. Setiap thread memiliki riwayat percakapannya sendiri.
- Event: Event
session.thread_created,session.thread_status_running,session.thread_status_idle, dansession.thread_status_terminateddari thread eksekusi juga tiba di aliran utama (lihat Event eksekusi). Event pesannya tetap di alirannya sendiri. Webhook thread-nya dikirim seperti untuk thread anak mana pun. Untuk apa yang dicatat aliran thread itu sendiri, lihat Event thread sesi. - Fase: Tidak ada event atau field yang menyebutkan di fase mana sebuah thread bekerja, dan thread dari satu eksekusi dapat memiliki
agent_nameyang sama. Ikuti kemajuan eksekusi melalui event fasenya, dan bedakan thread-nya berdasarkansession_thread_id. - Batas thread: Thread eksekusi dikecualikan dari batas thread anak sesi.
- Memulai eksekusi: Hanya agen di thread utama sesi yang memulai eksekusi. Agen yang bekerja di thread eksekusi tidak dapat memulai eksekusinya sendiri, sehingga eksekusi tidak bersarang.
- Pengarsipan: Server mengarsipkan setiap thread paling lambat pada akhir eksekusinya. Server dapat mengarsipkannya lebih awal, setelah thread mengembalikan hasilnya atau eksekusi selesai dengannya. Jika thread masih berjalan atau menunggu klien Anda pada saat itu, server menghentikannya terlebih dahulu. Thread yang diarsipkan tetap ada di daftar thread, dengan status
terminated. Anda tidak perlu mengarsipkan thread eksekusi sendiri. Selama eksekusi terbuka, permintaan untuk mengarsipkan thread yang belum diarsipkan server mengembalikan 400 denganerror.details.error_code: "workflow_run_open". - Visibilitas: Anda tidak melihat kode workflow, tetapi Anda dapat meminta workflow tersebut kepada agen, seperti yang dijelaskan tip setelah daftar ini. Anda juga tidak melihat panggilan alat yang dilakukan agen untuk memulai dan mengelola eksekusi, atau hasil yang dikembalikan setiap thread ke workflow.
Mengetahui kapan pekerjaan selesai
Selama eksekusi berjalan, sesi diharapkan tetap running, bahkan ketika tidak ada thread-nya yang bekerja. Sesi menjadi idle dengan requires_action ketika tidak ada thread yang bekerja dan sebuah thread menunggu klien Anda. Status idle saja tidak berarti pekerjaan selesai. Pekerjaan selesai ketika kedua hal berikut benar:
- Setiap eksekusi yang Anda lihat dibuat memiliki
workflow_run.status_ended-nya. - Setelah itu,
session.status_idletiba denganstop_reasonend_turn, dan bukan permintaan Anda sendiri, seperti interupsi, yang menyebabkannya. Setelah Anda menginterupsi, hitung hanya idle yang datang setelahuser.messageatauuser.define_outcomeAnda berikutnya.
- Eksekusi yang dijeda: Eksekusi yang dijeda tidak membuat sesi tetap
running, sehingga sesi dapat menjadi idle selagi eksekusi masih terbuka. Pada anggaran, misalnya, sesi menjadi idle denganbudget_reached. Pekerjaan belum selesai hingga eksekusi berakhir. - Eksekusi lain: Agen dapat memulai eksekusi baru ketika membaca sebuah hasil, jadi periksa lagi.
- Outcome: Jika Anda mendefinisikan outcome, tidak ada evaluasi yang dimulai selama eksekusi terbuka, baik sedang berjalan maupun idle. Giliran di mana agen membaca hasil eksekusi dapat memulai evaluasi.
retries_exhausted: Giliran agen gagal karena error: percobaan ulang habis, atau error tidak dapat dicoba ulang, seperti kegagalan penagihan. Sebuah eksekusi mungkin masih berjalan ketika idle ini datang. Jika sebuah eksekusi berakhir dan agen belum membaca hasilnya, server memulai giliran baru tanpa input dari Anda. Sesi kembalirunning, jadi tunggu idle berikutnya. Jika sesi tetap idle, bacasession.erroryang datang sebelumnya dan perbaiki penyebabnya. Kemudian kirimuser.message, atau bacaresultsetiap eksekusi sendiri.
Mengikuti eksekusi
Contoh ini mengikuti sesi dari pesan Anda hingga jawaban agen. Contoh ini membuka aliran dan mengirim pesan. Kemudian contoh ini melakukan hal-hal berikut:
- Melacak setiap eksekusi dari
workflow_run.createdhinggaworkflow_run.status_ended-nya, dan mencetak setiap fase saat dimulai. - Menjawab panggilan alat kustom ketika setiap
agent.custom_tool_usetiba, karena thread eksekusi dapat menunggu klien Anda selagi sesi tetaprunning. Jika alat agen Anda meminta konfirmasi, tambahkan cabang yang menjawab setiapagent.tool_useatauagent.mcp_tool_useyangevaluated_permission-nya adalahask. Contoh ini tidak memilikinya, karena cabang yang mengizinkan setiap panggilan akan mengubahalways_askmenjadi selalu mengizinkan. - Berhenti ketika pekerjaan selesai: tidak ada eksekusi yang terbuka, dan sesi menjadi idle dengan
end_turn. Contoh ini juga berhenti jika sesi dihentikan. Pada idle dengan alasan berhenti lain selainrequires_action, sepertibudget_reached,retries_exhausted, ataurefusal, contoh ini mencetak alasannya dan berhenti, jadi tangani hal-hal tersebut dalam kode Anda sendiri. Contoh ini berhenti padaretries_exhaustedbahkan ketika server akan memulai giliran baru dengan sendirinya. Contoh ini terus menunggu padarequires_action, dan padaend_turnselama sebuah eksekusi terbuka.
open_runs: dict[str, str] = {} # workflow_run_id -> run name
phase_names: dict[tuple[str, str], str] = {} # (run ID, phase ID) -> phase name
# Buka stream terlebih dahulu, lalu kirim pesan pengguna
with client.beta.sessions.events.stream(session_id) as stream:
client.beta.sessions.events.send(
session_id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Which contracts in /contracts have a change-of-control clause?",
},
],
},
],
)
for event in stream:
match event.type:
case "workflow_run.created":
open_runs[event.workflow_run_id] = event.name
for phase in event.phases:
phase_names[event.workflow_run_id, phase.id] = phase.name
print(f"Run started: {event.name}")
case "workflow_run.phase_started":
phase_id = event.workflow_run_phase_id
key = (event.workflow_run_id, phase_id)
print(f" Phase: {phase_names.get(key, phase_id)}")
case "workflow_run.status_ended":
name = open_runs.pop(event.workflow_run_id, event.workflow_run_id)
print(f"Run ended: {name} ({event.result.type})")
case "agent.custom_tool_use":
# Jawab saat event tiba. Thread sebuah eksekusi dapat menunggu
# klien Anda sementara sesi tetap berjalan.
result = call_tool(event.name, event.input)
try:
client.beta.sessions.events.send(
session_id,
events=[
{
"type": "user.custom_tool_result",
"custom_tool_use_id": event.id,
"content": [{"type": "text", "text": result}],
},
],
)
except anthropic.BadRequestError as error:
# Server menolak hasil yang datang terlambat, setelah server
# mengarsipkan thread panggilan tersebut. Terus ikuti eksekusinya.
print(f" Answer to {event.name} refused: {error.message}")
case "session.status_idle":
# Selesai saat setiap eksekusi telah berakhir dan agen telah menyelesaikan gilirannya
if not open_runs and event.stop_reason.type == "end_turn":
break
# Status idle dengan requires_action menunggu klien Anda, jadi terus baca.
# Pada alasan berhenti lainnya, cetak alasannya lalu berhenti.
if event.stop_reason.type not in ("end_turn", "requires_action"):
print(f"Session idle: {event.stop_reason.type}")
break
case "session.status_terminated":
breakMenginterupsi sesi dengan eksekusi yang terbuka
Kirim user.interrupt tanpa session_thread_id, atau dengan ID thread utama. Ini menghentikan giliran agen. Ini tidak mengakhiri eksekusi apa pun. Eksekusi sesi mungkin dijeda atau terus berjalan, dan event-nya mungkin tidak menunjukkan yang mana. Masa hidup eksekusi yang dijeda terus berjalan, sehingga eksekusi dapat berakhir dengan timeout_error selama dijeda.
- Panggilan alat yang menunggu: Setelah interupsi, panggilan alat dari thread eksekusi mungkin masih menunggu klien Anda. Jawab masing-masing. Untuk membatalkan panggilan yang meminta konfirmasi, tolak panggilan tersebut. Untuk membatalkan panggilan alat kustom, kirim hasil dengan
is_errordiatur ketruedan teks dicontentyang menjelaskan alasannya. Selama sesi berstatusidledenganrequires_action,user.messagemengembalikan 400, jadi jawab panggilan-panggilan tersebut terlebih dahulu. - Untuk menghentikan eksekusi: Kirim
user.messageyang meminta agen menghentikan eksekusinya. Eksekusi yang dihentikan berakhir denganresult{"type": "stopped"}. Selama sesi berstatusidledenganbudget_reached,user.messagemengembalikan 400 hingga Anda menaikkan atau menghapus anggaran. Menaikkan atau menghapusnya juga melanjutkan eksekusi yang dijeda oleh anggaran, kecuali jika interupsi juga menjedanya. - Untuk melanjutkan: Kirim
user.messageyang meminta agen melanjutkan eksekusinya. Setelah interupsi, eksekusi mungkin menunggu pesan ini. Jika sesi berstatusidledenganbudget_reached, naikkan atau hapus anggaran terlebih dahulu. - Hasil eksekusi: Eksekusi yang berakhir setelah interupsi tetap mengirim
workflow_run.status_ended.
Selama eksekusi terbuka
| Permintaan | Selama eksekusi terbuka | Apa yang harus dilakukan |
|---|---|---|
| Mengarsipkan atau menghapus sesi | Mungkin mengembalikan 400 selama eksekusi terbuka, apa pun status sesinya. error.details.error_code dari error tersebut dapat berupa "workflow_run_open". Mungkin juga berhasil. | Minta agen menghentikan eksekusinya, atau tunggu hingga setiap eksekusi berakhir. Eksekusi yang dijeda berakhir dengan sendirinya hanya ketika masa hidupnya habis. Kemudian kirim permintaan setelah sesi berstatus idle. Pengarsipan yang berhasil mengakhiri setiap eksekusi yang terbuka dengan {"type": "stopped"}. Setelah pengarsipan, workflow_run.status_ended eksekusi, dan workflow_run.phase_ended dari fase yang masih terbuka, tidak tiba di aliran. Cantumkan event sesi untuk membacanya. Setelah penghapusan yang berhasil, tidak ada event workflow_run yang melaporkan akhir eksekusi sesi. |
| Mengarsipkan salah satu thread eksekusi | Mengembalikan 400 dengan error.details.error_code: "workflow_run_open" selama eksekusi terbuka, baik berjalan maupun idle, kecuali server telah mengarsipkan thread tersebut. | Tidak ada. Server mengarsipkan thread eksekusi. |
Memperbarui agent sesi | Mengembalikan 400 dengan error.details.error_code: "workflow_run_open" selama ada eksekusi yang terbuka, bahkan yang dijeda. Memperbarui agen yang mendasarinya tetap diterima, dan sesi menyimpan salinannya sendiri. Permintaan yang juga mengirim field lain, seperti budget, ditolak seluruhnya. | Tunggu hingga setiap eksekusi memiliki workflow_run.status_ended-nya, atau minta agen menghentikan eksekusinya. |
| Menjawab panggilan alat atau konfirmasi alat dari thread eksekusi | Diizinkan. Panggilan tersebut tiba di aliran utama, dan session_thread_id-nya menyebutkan thread-nya. | Jawab segera setelah event tiba, dengan meneruskan id event sebagai tool_use_id atau custom_tool_use_id. Jangan menunggu session.status_idle: sesi dapat tetap running selagi thread lain dari eksekusi bekerja. Setelah server mengarsipkan thread, hasil alat untuk salah satu panggilannya tidak berpengaruh, dan dapat mengembalikan 400. Ketika hasil alat mengembalikan 400, temukan thread panggilan tersebut di daftar thread. Jika statusnya terminated, hasil tersebut datang terlambat, jadi abaikan. Kirim setiap hasil alat dalam permintaannya sendiri, karena server menolak seluruh permintaan ketika menolak salah satu event-nya. Konfirmasi alat yang datang terlambat mengembalikan 200, yang tidak berarti alat tersebut dijalankan. |
Membangun ulang status eksekusi setelah Anda terhubung kembali
Bangun ulang status setiap eksekusi dari event sesi. Aliran tidak memutar ulang apa yang Anda lewatkan: koneksi baru hanya mengirimkan event yang dipancarkan setelah koneksi dibuka. Jadi cantumkan event dengan filter types, satu entri types[] untuk setiap jenis event, seperti di Mendaftar event sebelumnya. Teruskan next_page setiap respons sebagai page hingga next_page bernilai null atau tidak ada. workflow_run.created, workflow_run.status_running, workflow_run.status_idle, dan workflow_run.status_ended memberikan status setiap eksekusi, kecuali bahwa eksekusi yang dijeda setelah interupsi mungkin masih tampil sebagai berjalan. workflow_run.phase_started dan workflow_run.phase_ended membangun ulang kemajuan. Eksekusi yang belum memiliki event status belum mulai dijalankan. Tidak ada endpoint yang mencantumkan eksekusi.
Anggaran dan batas
Permintaan model dari sebuah eksekusi dihitung dalam anggaran sesi. Eksekusi tidak memiliki harga tersendiri. Token yang digunakan agen-agennya ditagih seperti token sesi lainnya, sesuai tarif setiap model. Untuk semua biaya sesi, lihat Harga Claude Managed Agents.
- Penggunaan satu eksekusi: Cantumkan thread sesi dan jumlahkan hitungan token di
usagedari thread denganworkflow_run_ideksekusi tersebut. Daftar ini menyertakan thread yang diarsipkan, yang statusnyaterminated, sehingga thread dari eksekusi yang sudah selesai ikut dihitung. Teruskannext_pagesetiap respons sebagaipagehingganext_pagebernilainullatau tidak ada, dan lewati thread yangusage-nya bernilainull. Jika Anda menjumlahkanlist_costthread sebagai gantinya, totalnya tidak mencakup runtime sesi, dan setiap angka dibulatkan secara terpisah. - Pada anggaran: Setiap eksekusi yang terbuka dijeda, dan sesi melaporkan
idledenganbudget_reached, ataurequires_actionjika ada panggilan alat yang juga menunggu. Setiap thread menyelesaikan permintaan model yang sudah dimulainya, sehingga eksekusi dapat melampaui anggaran sebanyak satu permintaan untuk setiap thread yang bekerja. Menaikkan atau menghapus anggaran melanjutkan eksekusi yang dijedanya, kecuali jika interupsi juga menjeda eksekusi tersebut. Jika penggunaan sesi mencakup model tanpa harga daftar, hanya menghapus anggaran yang dapat melakukannya; lihat Model tanpa harga daftar.
| Batas | Nilai | Saat batas tercapai |
|---|---|---|
| Thread yang bekerja bersamaan dalam satu eksekusi | 64 | Eksekusi tidak membuat thread lagi hingga salah satunya selesai. API tidak menjamin angka ini, sehingga dapat berubah. |
| Agen yang dimulai workflow sepanjang masa hidup eksekusi | 1.000 | Ketika workflow meminta lebih banyak, server tidak memulai agen lain, dan eksekusi berakhir dengan thread_limit_error. Server dapat menjalankan ulang agen yang gagal di thread baru, sehingga sebuah eksekusi mungkin memiliki lebih dari 1.000 thread. |
| Masa hidup eksekusi | 24 jam secara default, atau masa hidup yang ditetapkan agen | Eksekusi berakhir dengan timeout_error. Tidak ada event yang menyebutkan masa hidup yang ditetapkan agen. |
| Eksekusi yang terbuka bersamaan dalam satu sesi | 10 secara default | Server menolak memulai eksekusi lain. Panggilan alat agen mendapat error, dan Anda mendapat workflow_run.error yang error.type-nya adalah max_workflow_runs_error. Eksekusi yang idle dihitung dalam batas ini. |
Server memendekkan name eksekusi atau fase menjadi 64 karakter dan description-nya menjadi 256. Server memiliki batas lain untuk workflow, dan aturan untuknya, yang tidak dicantumkan di sini. Apa yang Anda lihat bergantung pada kapan server menemukan masalahnya:
| Apa yang terjadi | Apa yang Anda lihat |
|---|---|
| Workflow melampaui salah satu batas lain ketika agen memulai eksekusi | Permulaan ditolak. Anda mendapat workflow_run.error, dan tidak ada eksekusi. |
| Eksekusi melampaui salah satu batas lain di kemudian waktu | Anda mendapat workflow_run.error, lalu eksekusi dapat berakhir dengan unknown_error. |
| Server menemukan setelah permulaan bahwa workflow melanggar aturan untuk workflow, selain batas | Anda mendapat workflow_run.error, lalu eksekusi dapat berakhir dengan program_error. |
Sebuah sesi dapat memulai eksekusi dalam jumlah berapa pun sepanjang masa hidupnya.
Batas laju
Pekerjaan sebuah eksekusi dihitung dalam "rate limit" (batas laju) yang sudah dimiliki organisasi Anda.
| Apa | Dihitung dalam | Apa yang harus dilakukan |
|---|---|---|
| Permintaan klien Anda untuk mengambil atau mencantumkan sesi, thread-nya, dan event-nya | Batas baca untuk endpoint Managed Agents | Ikuti eksekusi di aliran event sesi alih-alih melakukan polling. |
| Permintaan model dari thread eksekusi | Batas laju Messages API Anda untuk model yang digunakan setiap thread, bersama dengan lalu lintas Anda yang lain | Sisakan ruang untuk eksekusi dalam batas-batas tersebut, atau minta batas yang lebih tinggi. |
Ketika permintaan model dari salah satu thread eksekusi terkena batas laju, atau model kelebihan beban, aliran thread itu sendiri dapat menerima session.error dengan jenis model_rate_limited_error atau model_overloaded_error:
- Jika
retry_status.type-nya adalahretrying, server sedang mencoba ulang permintaan, dan thread masih bekerja. - Jika nilainya
exhausted, thread telah gagal. Jika workflow membiarkan kegagalan itu mengakhiri eksekusi, eksekusi berakhir denganprogram_error, yang tidak menyebutkan penyebabnya. Baca event dari thread yang gagal untuk menemukannya.
Server juga membatasi seberapa banyak yang dilakukan semua sesi organisasi Anda setiap menit. Thread yang mencapai batas ini berhenti, dengan session.error di alirannya sendiri yang pesannya menyebutkan batas laju. Tunggu satu menit sebelum Anda meminta agen untuk melanjutkan.
Sebuah eksekusi dapat membuat lebih dari satu thread untuk bagian pekerjaan yang sama, jadi pastikan alat yang dipanggil agen Anda aman untuk dipanggil dua kali.
Was this page helpful?