클로드 코드 에이전트 봇 아키텍처

구성요소

에이전트 봇은 여덟 개 구성요소로 이루어집니다.

브리지는 웹 앱 번들도 직접 제공합니다. 클라이언트가 같은 오리진의 HTTP로 앱을 열기 때문에 HTTPS 페이지에서 ws:// 를 막는 혼합 콘텐츠 제약이 생기지 않습니다.

배치와 경로

구성요소는 폰, 호스트, 저장소 세 곳에 놓입니다.

폰
  클라이언트
호스트
  브리지
  런타임
  스케줄러
  도구 계층
  하위 에이전트
  알림
저장소
  기억 저장소

요청과 응답은 아래 다섯 경로로 흐릅니다.

요청: 클라이언트 → 접근 제어 → 브리지 → 런타임 → 도구 계층
응답: 런타임 → 알림 → 클라이언트
루틴: 스케줄러 → 런타임 → 알림 → 클라이언트
위임: 런타임 → 하위 에이전트 → 결과 회수 → 런타임
기억: 런타임 → 기억 저장소

접근 제어는 호스트 앞단의 사설망 또는 터널과 접근 제어 서비스입니다. 브리지는 접근 제어를 거친 요청만 받습니다.

동작 흐름

채팅 요청

1. 클라이언트가 브리지에 요청을 보냅니다.
2. 브리지가 입력을 상주 세션에 전달합니다.
3. 런타임이 도구 계층을 호출해 일을 처리합니다.
4. 호스트가 4초마다 세션 화면을 읽어 작업 끝을 판정합니다.
5. 호스트가 마지막 응답의 앞부분을 알림 본문으로 보냅니다.

클라이언트가 같은 채팅을 6초 안에 열람했으면 알림을 보내지 않습니다. 알림 본문은 마크다운을 제거한 평문이고 180자로 자릅니다.

루틴

루틴은 세 가지 일정 형식을 가집니다.

일정 시각은 지정한 시간대의 벽시계로 계산합니다. 스케줄러는 20초마다 실행 시각을 판정합니다. 루틴은 두 방식으로 실행합니다.

호스트가 잠든 동안 지난 회차는 유예 안에서 깨어난 뒤 한 번 실행합니다. 회차 시각보다 15분 넘게 늦으면 실행 기록에 늦게 실행됨 을 붙입니다.

단독 실행은 알릴 것이 없으면 NONE 한 단어만 답하도록 지시합니다. 결과가 NONE 이면 알림과 결과 파일을 만들지 않습니다.

위임

1. 런타임이 하위 에이전트 세션을 깨우고 지시를 보냅니다. 지시 앞에는 위임 표시가 붙고, 명령은 바로 반환합니다.
2. 런타임이 세션 상태를 조회합니다.
3. 런타임이 세션이 done 이 될 때까지 대기합니다.
4. 런타임이 하위 에이전트의 대화 기록을 읽어 결과를 받습니다.

세션 상태는 네 가지입니다.

위임 규칙은 아래와 같습니다.

• 하위 에이전트에 맡기는 일: 계속 관리하거나 오래 걸리는 일
• 런타임이 직접 하는 일: 한 번에 끝나는 짧은 일, 또는 서브에이전트 호출
• 하위 에이전트의 보고: 첫 줄에 결과를 한 문장으로 요약
• 파일 결과물: 지정한 결과 폴더에 날짜와 주제가 붙은 이름으로 저장

사람 개입

로그인, 2단계 인증, 캡차, 결제 단계에서는 에이전트가 작업을 멈추고 사람에게 넘깁니다.

에이전트 → 작업 중단 → 알림(응답 대기) → 클라이언트
클라이언트 → 브라우저 화면 요청 → 브리지 → 브라우저 자동화 → 화면 프레임 → 클라이언트
클라이언트 → 탭, 입력, 스크롤 → 브리지 → 브라우저 자동화
사람 → 단계 완료 → 에이전트에 재개 지시

클라이언트는 호스트 브라우저의 화면을 보고 탭, 입력, 스크롤로 조작합니다. 브리지는 입력 길이와 좌표 범위를 검증한 뒤 브라우저 자동화에 전달합니다.

승인 선택 창도 같은 경로로 사람에게 넘깁니다. 호스트의 자동 승인 대상은 두 가지뿐입니다.

• 호스트가 만든 작업 폴더의 신뢰 확인 창
• 지침 파일 가져오기 확인 창

그 밖의 선택 창은 알림과 함께 클라이언트에 표시됩니다.

기억 큐레이션

새 사실 → 받은함 → 큐레이터(원본 보관) → 기억 파일(사실 하나, 출처 하나 이상)
출처 충돌 → 충돌 기록 → 해당 주장 작업 중단 → 소유자 결정

기억 저장소는 네 층으로 나뉩니다.

규칙은 아래와 같습니다.

• 출처: 모든 주장에 필수, 출처가 없는 주장은 적지 않음
• 사실 변경: 기존 파일 수정 금지, 새 기억 파일 추가, 새 파일의 출처에 이전 파일 기재
• 충돌: 날짜와 두 주장과 두 출처를 충돌 기록에 적은 뒤 해당 주장의 작업 중단
• 결정: 소유자가 결정, 에이전트는 승자를 고르지 않음

안전 경계

런타임은 도구 호출마다 승인을 요청하지 않는 방식으로 실행됩니다. 안전 규칙은 지침 파일과 브리지에 둡니다.

문제 해결

완료 알림은 두 방법으로 보완합니다.

• 즉시 푸시: 완료, 입력 대기, 루틴 실패, 계정 전환 때 알림을 즉시 보냄. 구현되어 있음
• 점검 루틴: 주기 루틴이 세션 목록을 읽어 완료 또는 대기 상태로 오래 남은 세션을 알림. 권장 사항이며 미구현

푸시 구독 만료는 클라이언트를 열 때마다 구독을 확인해 자동으로 다시 등록하는 방식으로 줄입니다.

제한 사항

기준값