원격 API

인증된 포그라운드 HTTP 서비스에서 q 세션과 단발 에이전트 요청을 실행합니다.

Markdown 보기

구성과 시작

리스너, 인증 스위치, Remote 전용 API 키를 구성합니다.

powershell

q remote config

그다음 포그라운드 호스트를 실행합니다.

powershell

q remote

기본 리스너는 127.0.0.1:0입니다. Remote 키는 q 프로세스가 접근할 수 있는 어떤 작업 디렉터리든 선택하고 워크스페이스 변경 도구를 실행할 수 있으므로 Gateway 키와 분리되어 있습니다.

워크스페이스 상태 조회

작업 디렉터리의 세션을 나열합니다.

powershell

curl.exe -H "Authorization: Bearer $env:Q_REMOTE_KEY" "http://127.0.0.1:8080/v1/sessions?working_directory=C%3A%5Cwork%5Cproject"

같은 워크스페이스에 적용되는 내장 및 사용자 정의 서브에이전트를 나열합니다.

powershell

curl.exe -H "Authorization: Bearer $env:Q_REMOTE_KEY" "http://127.0.0.1:8080/v1/subagents?working_directory=C%3A%5Cwork%5Cproject"

에이전트 실행

POST /v1/subagent-runs는 JSON을 받고 application/x-ndjson 이벤트를 스트리밍합니다.

powershell

curl.exe -N `
  -H "Authorization: Bearer $env:Q_REMOTE_KEY" `
  -H "Content-Type: application/json" `
  -d '{"working_directory":"C:\\work\\project","prompt":"시작 경로를 설명해줘"}' `
  http://127.0.0.1:8080/v1/subagent-runs

working_directory와 prompt는 필수입니다. session_id를 생략하면 새 세션을 만들고, 점유되지 않은 기존 세션을 재개하려면 값을 보냅니다. subagent를 생략하거나 빈 값으로 보내면 기본 메인 루프를 실행합니다. builtin/scout 같은 ID를 보내면 직접 서브에이전트 흐름을 사용합니다.

프롬프트는 UTF-8 32 KiB, 전체 JSON 요청 본문은 256 KiB로 제한됩니다. 알 수 없는 JSON 필드는 거부됩니다. 응답은 Cache-Control: no-store를 사용하며 X-Q-Session-ID 헤더에 선택된 세션을 제공합니다.

스트림 이벤트

첫 NDJSON 레코드는 항상 session입니다. working_directory, session_id, created 필드로 정규화된 워크스페이스와 새 세션 생성 여부를 알 수 있습니다.

종류	주요 필드	의미
`status`	`detail`	시작 경고 또는 간결한 런타임 상태
`activity`	`agent`, `task_id`, `parent_id`, `action`, `detail`	서브에이전트 생명주기 진행 상황
`trace`	`agent`, `kind`, `call_id`, `name`, `content`, `is_error`	상세 서브에이전트 추적 항목
`tool_call`	`call_id`, `name`, `content`	메인 에이전트 도구 요청. `content`는 인자를 포함합니다.
`message`	`role`, `name`, `call_id`, `content`, `is_error`	세션에 추가된 모델 또는 도구 메시지
`question`	`question`, `context`	대화형 질문 시도. Remote에서는 답할 수 없습니다.
`result`	`session_id`, `outcome`, `content`	성공한 종료 결과
`cancelled`	—	취소 후 종료 레코드
`error`	`error`	스트리밍 시작 후의 종료 실패

클라이언트는 필요하지 않은 필드를 무시하고 종료 레코드까지 읽어야 합니다. 연결을 끊으면 요청 컨텍스트와 활성 실행이 취소됩니다.

오류와 실행 용량

스트리밍 시작 전 실패는 JSON error 객체와 HTTP 상태로 반환됩니다.

상태	코드	의미
`400`	`invalid_request`	JSON, 디렉터리, 세션 ID, Content-Type, 요청 형식이 잘못됨
`401`	`invalid_api_key`	인증이 켜져 있고 bearer 키가 없거나 유효하지 않음
`404`	`session_not_found` 또는 `subagent_not_found`	선택한 세션이나 서브에이전트가 없음
`409`	`session_busy`	다른 프로세스가 선택한 세션을 점유 중
`413`	`request_too_large`	본문 또는 프롬프트가 제한을 초과함
`429`	`remote_capacity`	활성 실행이 `agents.max_parallel`에 도달함
`503`	`subagent_unavailable`	에이전트는 있지만 구성된 런타임을 사용할 수 없음

GET /v1/health는 서비스 버전과 새 실행 수락 가능 여부를 보고합니다. 이 엔드포인트와 /openapi.json은 bearer 키 없이 접근할 수 있으며 워크스페이스 상태를 노출하지 않습니다.

원격 경계

Remote는 도구 카탈로그에 ask_to_user를 유지하지만 스트림은 단방향입니다. q는 시도한 question을 내보낸 뒤 즉시 상호작용 불가 도구 오류를 반환합니다. 모델은 가진 정보로 계속하거나 막힌 상태로 끝낼 수 있습니다.

Remote에는 내장 TLS, 경로 허용 목록, 백그라운드 작업, 재연결, 대화형 답변이 없습니다. 인증과 신뢰할 수 있는 기밀 네트워크 또는 리버스 프록시가 없다면 루프백에서만 사용하세요.

실행 중인 서비스의 정확한 계약은 /openapi.json에서 볼 수 있습니다.