Agent runs

Satu agent run ialah tugasan autonomi: model itu merancang, memanggil alat (web, kod, data workspace, penciptaan fail, pelayar sebenar), mengesahkan, dan menyampaikan hasil — distrim langkah demi langkah. Tidak seperti sembang, ia memiliki tugasan hujung ke hujung.

Mulakan run

POST/v1/workspaces/{workspace_id}/agent/runs —

mulakan run. Run dinyahkan daripada sambungan: endpoint ini memulangkan objek JSON kecil serta-merta dan enjin terus berkerja secara terpisah. Jejak strim langsung dengan GET …/attach (di bawah).

Integrasi minimum — satu medan. Hantar sahaja {"task": "…"} dan anda siap. Platform ini auto-lalukan ke model terbaik, auto-pilih dan panggil alat yang betul (gelintar web, pangkalan pengetahuan anda, kod, pelayar…), dan strimkan hasil kembali. Anda tidak pernah memasang alat, model atau prompt sendiri — setiap medan body lain di bawah ialah penggantian pilihan apabila anda mahu lebih kawalan. Lihat Cookbook untuk contoh salin-tampal.

POST memulangkan {"run_id", "trace_id"} — run id ialah semua yang anda perlukan untuk mengekornya. Pemutusan sambungan pelanggan tidak pernah membunuh run; pengebilan, penerusan dan jawapan akhir sentiasa mendarat.

Wajib:

task — apa yang perlu dilakukan, dalam bahasa semula jadi (sehingga 20,000 aksara). Itulah satu-satunya medan yang anda mesti hantar.

Pilihan (semuanya mempunyai lalai yang munasabah — ganti hanya apabila perlu):

model — kosong membenarkan platform memilih pemacu yang mampu guna alat. Pin hanya untuk memaksa yang tertentu.
max_steps — siling lelaran alat/fikir (1–50).
budget_usd — siling kos tegar (> 0, sehingga 100).
pro — membuka kunci penaakulan yang lebih dalam dan berbilang bebenang (sub-agents selari pada tugas kompleks).
project_id — jalankan dengan arahan dan fail project yang disuntik sebagai konteks.
conversation_id — jalinkan run ini di bawah perbualan sembang sedia ada (hasil ditulis semula ke thread itu). Tinggalkan untuk tugas berdiri sendiri.
skills — slug skills yang dipilih pengguna secara nyata (sehingga 8); kosong menjalankan garis asas tulen (skills tidak pernah dilampirkan secara automatik).
persona_slug — satu peranan pakar daripada pustaka agency-agents; disuntik sebagai pengepala identiti untuk run ini. Selebih-lebihnya satu.
history — giliran terkini ({role, content}, role ialah user atau assistant) untuk kesinambungan antara giliran. Diabaikan apabila conversation_id ditetapkan (sejarah dibina semula di pelayan).
mode — pembayang lorong penggubah (auto membenarkan penghala pilih chat / agent / cowork / code). Hanya dirujuk apabila penghala bersatu didayakan.
approval_mode — postur untuk tindakan mesin tempatan berbahaya: ask (lalai, jeda untuk OK pengguna) atau auto (jalankan tanpa jeda).

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Bandingkan jadual yuran Wise dan Airwallex; hasilkan satu jadual.",
       "pro": true, "budget_usd": 0.5}'
# -> {"run_id": "…", "trace_id": "…"}

Ikuti run (Server-Sent Events)

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/attach —

jejak strim acara run (text/event-stream). Setiap bingkai ialah satu objek JSON pada baris data:.

Ia selamat disambung semula: baris id: membawa id kemasukan strim, jadi EventSource menjejaki lastEventId secara natif dan menghantarnya semula sebagai Last-Event-ID apabila disambung semula — segar, flip WiFi, atau peranti kedua membuka run itu menyambung tepat di mana ia terhenti (backlog dimainkan semula daripada id terakhir yang anda lihat). Penjana ditutup selepas bingkai terminal run; tempoh terbiar mendapat degupan jantung : ping supaya proksi tidak memutuskan sambungan.

Jenis acara type:

type	medan	bila
`step_start`	`step_no`	lelaran gelung bermula
`llm_delta`	`step_no`, `text`	teks model yang distrim
`reasoning` / `reasoning_delta`	`step_no`, `text`	rantai penaakulan langkah itu (penuh pada akhir giliran; delta distrim secara langsung)
`tool_call` / `tool_call_delta`	`step_no`, `tool_name`, `arguments`	model meminta alat (delta strimkan argumen)
`tool_progress`	`step_no`, `tool_name`, `message`, `progress?`	alat panjang melaporkan kemajuan perantaraan
`tool_result`	`step_no`, `tool_name`, `ok`, `preview`, `duration_ms`, …	alat selesai (mungkin membawa `artifacts`, `sources`, `screenshot_url`)
`approval_request` / `approval_resolved`	`step_no`, `approval_id`, …	tindakan tempatan berbahaya sedang menunggu (atau mendapat) keputusan pengguna
`step_end`	`step_no`, `cost_usd`	lelaran selesai
`context_compacted`	`step_no`, `summary`	giliran lama digulung menjadi ringkasan agar muat tetingkap konteks
`run_end`	`status`, `step_count`, `cost_usd`, `final_text`, `latency_ms`	terminal — jawapan akhir ada dalam `final_text`
`error`	`message`	kegagalan terminal

Setiap acara juga membawa run_id (dan step_no) supaya pengguna berbilang strim boleh menghala bingkai tanpa keadaan per-sambungan. Strim berakhir dengan bingkai terminal run_end (atau error) — tiada penjaga [DONE].

bash

curl -N https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs/$RUN_ID/attach \
  -H "Authorization: Bearer $NEXEVO_API_KEY"
# id: 1719900000-0
# data: {"type":"step_start","run_id":"…","step_no":1}
# id: 1719900000-1
# data: {"type":"llm_delta","run_id":"…","step_no":1,"text":"…"}
# …
# data: {"type":"run_end","run_id":"…","status":"succeeded","final_text":"…",…}

Utamakan GET …/attach berbanding ulang POST: ia boleh disambung semula daripada Last-Event-ID, jadi pelanggan yang menyambung semula tidak pernah kehilangan bingkai. Run itu berterusan sama ada ada sesiapa dilampirkan atau tidak.

Urus run

GET/v1/workspaces/{workspace_id}/agent/runs —

senaraikan run (query: limit, project_id, scheduled_only, include_archived).

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

ambil satu: status, final_text yang diteruskan, trajektori steps penuh, kos, dan artifacts yang dihasilkan.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/cancel —

hentikan tugas yang sedang berjalan. Kooperatif dan rentas-pekerja (menetapkan bendera yang disemak gelung pada sempadan langkah seterusnya); idempoten — membatalkan run yang telah selesai ialah no-op yang memulangkan status terminalnya.

PATCH/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

edit entri terkini: title, archived, favorited, atau alihkan project_id ( project_id null mengalih keluarnya).

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

padam run daripada sejarah (langkahnya berjatu). Batalkan run yang sedang berjalan dahulu.

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/artifacts.zip —

muat turun setiap artifact yang dihasilkan run sebagai satu .zip.

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

cipta / tarik balik pautan ulang-tayang awam baca-sahaja (body: expires_in_days pilihan).

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/approvals/{approval_id} —

jawab kelulusan tindakan-tempatan-berbahaya (body: {approved: true|false}), jenis yang ditonjolkan oleh acara approval_request.

Status run

run_end.status (dan GET …/runs/{run_id}) ialah salah satu daripada pending, running, succeeded, failed, cancelled, atau partial (tugas selesai dengan hasil separa yang masih berguna). Keadaan terminal ialah succeeded, failed, cancelled dan partial.

Fail yang dihasilkan agent (dokumen, hamparan, slaid, carta, aplikasi web) kembali sebagai artifacts pada run. Satu run dibatasi oleh kedua-dua budget_usd dan baki workspace, jadi ia tidak akan sesekali liar.