Agent runs

agent run은 자율 작업입니다. 모델이 계획하고, 도구를 호출하고(web, 코드, 워크스페이스의 데이터, 파일 생성, 실제 브라우저), 검증한 뒤 결과를 전달합니다(단계별로 스트리밍). chat과 달리 작업을 시작부터 끝까지 책임집니다.

run 시작하기

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

run을 시작합니다. run은 연결과 분리되어 있습니다. 이 엔드포인트는 즉시 작은 JSON 객체를 반환하고 엔진은 분리되어 계속 작동합니다. GET …/attach(아래 참고)로 라이브 스트림을 추적하세요.

최소 통합 — 필드 하나. {"task": "…"}만 보내면 끝입니다. 플랫폼이 최적의 모델로 자동 라우팅하고, 알맞은 도구(웹 검색, 당신의 knowledge base, 코드, 브라우저 등)를 자동으로 선택 및 호출하며, 결과를 스트리밍합니다. 도구, 모델, 프롬프트를 직접 연결할 필요가 없습니다. 아래의 다른 모든 본문 필드는 더 많은 제어를 원할 때 사용하는 선택적 재정의입니다. 복사해서 쓸 수 있는 예시는 Cookbook을 참고하세요.

POST는 {"run_id", "trace_id"}를 반환합니다. run id만 있으면 run을 따라갈 수 있습니다. 클라이언트 연결이 끊겨도 run은 절대 종료되지 않으며, 결제, 영속성, 최종 답변은 항상 완료됩니다.

필수:

task — 수행할 작업을 자연어로 서술(최대 20,000자). 반드시 보내야 하는 유일한 필드입니다.

선택(모두 합리적인 기본값이 있으며, 필요할 때만 재정의):

model — 비워두면 플랫폼이 도구 호출 능력이 있는 드라이버를 선택합니다. 특정 모델을 강제하려는 경우에만 지정하세요.
max_steps — 도구/사고 반복 횟수 상한(1–50).
budget_usd — 엄격한 비용 상한(> 0, 최대 100).
pro — 더 깊고 다중 스레드인 추론을 잠금 해제합니다(복잡한 작업에서 병렬 서브 agent 실행).
project_id — project의 지시사항과 파일을 컨텍스트로 주입하여 실행합니다.
conversation_id — 이 run을 기존 chat 대화 스레드 아래에 묶습니다(결과는 해당 스레드에 다시 기록됨). 독립 작업으로 하려면 생략하세요.
skills — 사용자가 명시적으로 선택한 skills의 slug(최대 8개). 비워두면 순수 베이스라인이 실행됩니다(skill은 자동으로 첨부되지 않음).
persona_slug — agency-agents 라이브러리의 전문가 role. 이 run의 정체성 헤드로 주입됩니다. 최대 한 개.
history — 최근 턴({role, content}, role은 user 또는 assistant)으로 턴 간 연속성을 제공. conversation_id가 설정된 경우 무시됩니다(히스토리는 서버 측에서 다시 구성됨).
mode — 컴포저 레인 힌트(auto는 라우터가 chat / agent / cowork / code 중 선택). 통합 라우터가 활성화된 경우에만 참조됩니다.
approval_mode — 위험한 로컬 머신 작업에 대한 태도: ask(기본값, 사용자 승인을 위해 일시 정지) 또는 auto(정지 없이 실행).

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Compare the fee schedules of Wise and Airwallex; output a table.",
       "pro": true, "budget_usd": 0.5}'
# -> {"run_id": "…", "trace_id": "…"}

run 따라가기(Server-Sent Events)

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

run의 이벤트 스트림을 추적합니다(text/event-stream). 각 프레임은 data: 줄의 JSON 객체 하나입니다.

재연결 안전합니다. id: 줄이 스트림 엔트리 id를 전달하므로 EventSource는 네이티브로 lastEventId를 추적하고, 재연결 시 이를 Last-Event-ID로 다시 보냅니다. 새로고침, 와이파이 전환, 또는 두 번째 기기에서 run을 열어도 마지막으로 본 위치에서 정확히 재개됩니다(백로그는 마지막으로 본 id부터 재생됨). 제너레이터는 run의 종료 프레임 이후에 닫히며, 유휴 구간에는 프록시가 연결을 끊지 않도록 : ping 하트비트를 보냅니다.

이벤트 type 종류:

type	필드	발생 시점
`step_start`	`step_no`	루프 반복이 시작됨
`llm_delta`	`step_no`, `text`	스트리밍되는 모델 텍스트
`reasoning` / `reasoning_delta`	`step_no`, `text`	해당 단계의 사고 과정(턴 종료 시 전체, delta는 실시간 스트리밍)
`tool_call` / `tool_call_delta`	`step_no`, `tool_name`, `arguments`	모델이 도구를 요청(delta는 인수를 스트리밍)
`tool_progress`	`step_no`, `tool_name`, `message`, `progress?`	오래 걸리는 도구가 중간 진행 상황을 보고
`tool_result`	`step_no`, `tool_name`, `ok`, `preview`, `duration_ms`, …	도구 완료(`artifacts`, `sources`, `screenshot_url`을 포함할 수 있음)
`approval_request` / `approval_resolved`	`step_no`, `approval_id`, …	위험한 로컬 작업이 사용자 결정을 대기 중(또는 결정됨)
`step_end`	`step_no`, `cost_usd`	반복 완료
`context_compacted`	`step_no`, `summary`	이전 턴이 컨텍스트 창에 맞게 요약으로 압축됨
`run_end`	`status`, `step_count`, `cost_usd`, `final_text`, `latency_ms`	종료 — 최종 답변은 `final_text`에 있음
`error`	`message`	종료성 실패

모든 이벤트는 run_id(및 step_no)도 함께 전달하므로, 다중화된 소비자가 연결별 상태 없이 프레임을 라우팅할 수 있습니다. 스트림은 종료 프레임 run_end(또는 error)로 끝나며, [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":"…",…}

POST를 재생하기보다 GET …/attach를 선호하세요. Last-Event-ID에서 재개 가능하므로 재연결하는 클라이언트는 프레임을 잃지 않습니다. 누군가 접속해 있든 아니든 run은 계속 진행됩니다.

run 관리

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

run을 나열합니다(쿼리: limit, project_id, scheduled_only, include_archived).

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

하나를 가져옵니다: 상태, 영속화된 final_text, 전체 steps 궤적, 비용, 생성된 artifacts.

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

실행 중인 작업을 중지합니다. 협력적이며 worker 간에 작동합니다(루프가 다음 단계 경계에서 확인하는 플래그 설정). 멱등성을 가집니다. 완료된 run을 취소하면 아무 작업도 수행하지 않고 종료 상태를 반환합니다.

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

최근 항목을 편집합니다: title, archived, favorited, 또는 project_id를 이동(null인 project_id는 프로젝트 밖으로 이동).

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

기록에서 run을 삭제합니다(단계는 cascade로 삭제됨). 실행 중인 run은 먼저 취소하세요.

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

run이 생성한 모든 artifact를 단일 .zip으로 다운로드합니다.

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

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

읽기 전용 공개 재생 링크를 생성/취소합니다(본문: 선택적 expires_in_days).

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

위험한 로컬 작업 승인에 응답합니다(본문: {approved: true|false}). approval_request 이벤트가 표시하는 종류입니다.

run 상태

run_end.status(및 GET …/runs/{run_id})는 pending, running, succeeded, failed, cancelled, 또는 partial(작업이 여전히 유용한 부분 결과로 끝남) 중 하나입니다. 종료 상태는 succeeded, failed, cancelled, partial입니다.

agent가 생성한 파일(문서, 스프레드시트, 슬라이드, 차트, 웹 앱)은 run에 artifacts로 돌아옵니다. run은 budget_usd와 워크스페이스 잔액 모두로 제한되므로 결코 통제를 벗어나지 않습니다.