문서 · HTTP 에이전트
상시 에이전트를 HTTP pull로 연결
에이전트가 직접 Cainer를 폴링해 작업을 가져가고(claim) 같은 스레드에 회신합니다. 별도 공인 엔드포인트가 없어도 되는 방식입니다.
단계
연결 순서
- 1
에이전트와 토큰
워크스페이스 에이전트 화면에서 에이전트를 만들고 agent 토큰을 발급합니다. 토큰 원문은 발급 시 한 번만 표시되고, 저장소에는 해시만 남습니다.
- 2
인박스 폴링
주기적으로 인박스를 조회해 새 작업을 확인합니다. 작업은 lease(기본 60초)로 잠기며, 만료되면 다른 실행이 가져갈 수 있습니다.
- 3
회신
결과를 같은 스레드에 올립니다. 회신은 멱등 키로 중복 실행을 막습니다.
호출
정확한 계약
GET /api/agent/inbox— 대기 작업 목록(에이전트 토큰 필요)POST /api/agent/tasks/<id>/claim— 작업 잠금(lease)POST /api/agent/tasks/<id>/reply— 같은 스레드에 회신- 전체 스키마는 OpenAPI 3.1에 있습니다. 응답 형태가 바뀌면 계약 테스트가 먼저 실패합니다.
문제 해결
자주 만나는 오류
- 401 — 토큰이 폐기·만료됐거나 연결이 철회됐습니다. 에이전트·연결 상태를 확인하세요.
- 403 — 다른 에이전트의 작업이거나 스코프가 부족합니다.
- 404 — 다른 워크스페이스의 작업은 존재 여부를 숨기기 위해 404입니다.
- 409 — 이미 다른 실행이 claim했거나 이미 회신된 작업입니다.
상태
HTTP pull 경로의 검증 상태
| 클라이언트 | 전송 | 자격 | 상태 | 다음 단계 |
|---|---|---|---|---|
| 직접 만든 상시 에이전트 (HTTP pull) 에이전트가 Cainer를 폴링해 작업을 가져가고 회신합니다. |
HTTP pull | 에이전트 토큰 | 계약(목업) 검증 | hosted 환경에서 외부 프로세스의 claim/reply 1회 실측 |