Agent 요청 실행 방식

이 문서는 비공개 호스트 환경에 이미 접근 권한이 있는 Nexia 유지관리자를 위한 참고 자료입니다. Core는 외부 개발자에게 배포하지 않습니다. 아래 호스트 명령은 공개 CLI·클라우드 샌드박스의 선행 조건이 아닙니다. 외부 개발자는 빠른 시작을 따라주세요.

Agent는 요청의 뜻을 파악하고, 현재 권한으로 사용할 수 있는 도구를 고른 뒤 답변하거나 실행합니다. SQL·Python 계산은 필요한 요청에서만 사용합니다.

요청 경로

Intent, Router, Lane은 서로 다른 제어입니다. Core는 먼저 테넌트, 사용자, 세션, 권한을 확인하고 Primary 등급과 역할별 모델 후보 설정을 읽습니다. 이 준비 과정에서는 모델 API를 호출하지 않습니다. 등록된 /명령어는 Intent를 결정적으로 정합니다. 일반 문장은 Router 역할 모델이 해석하며 분류, 명확화 질문, 안전한 실패 중 하나가 됩니다. 같은 작업에 저장된 유효한 신호는 다시 사용합니다. 알 수 없는 /명령어는 정해진 안내문으로 끝납니다. 코드의 Lane router는 주 Lane과 필요한 보조 Lane만 선택한 뒤 권한·정책을 통과한 도구 범위를 노출합니다. 그 다음에야 Primary가 이 범위에서 도구 호출 여부를 정합니다.

Router는 권한, 승인, 코드를 고르지 않습니다. Router 실패를 Primary가 대신 처리하지 않습니다. Lane도 코드를 실행하지 않으며 현재 범위 밖의 도구를 숨깁니다. Gateway에 분석 URL과 토큰 A 중 하나라도 없으면 분석 도구는 제거됩니다.

격리된 분석

Primary는 사용자가 선택한 등급의 모델로 요청을 처리합니다. 일반 문장을 해석하려면 router 모델 배정이 필요합니다. analysis_worker와 research_worker는 필요한 보조 작업에만 사용하는 별도 역할이며, SQL·Python 계산 도구와는 다릅니다. Primary가 analysis.dataset.create를 호출하면 Core는 데이터셋의 사용 권한을 현재 테넌트·사용자·세션·작업과 요청 필드에 묶습니다. analysis.run은 Core 승인을 거쳐 SQL 또는 Python 작업을 분석 제어부에 보내고, Core는 결과를 공개하기 전에 권한을 다시 확인합니다.

로컬 분석 제어부 또는 Cloudflare 분석 Worker는 Core가 내보낸 승인된 데이터로 일회성 실행 환경을 준비합니다. 이 실행 환경은 업무 DB 접속 정보나 서비스 인증값을 받지 않습니다. Core의 초기 한도는 데이터셋당 승인된 행 10,000개, 전송 형식 전체 10 MiB, 추출 SQL 문 하나당 5초입니다. 분석 제어부는 입력·출력 크기, 실행 시간, 메모리와 동시 실행 수도 제한합니다. 한도를 넘으면 중단하며 일부 데이터만으로 전체 분석이 끝났다고 처리하지 않습니다.

뜻이 불명확하면 확인 질문을 반환합니다. 분류 실패, 분석 서비스 미설정, 권한 거부, 처리 용량 부족, 한도 초과, 실행 실패, 취소·만료, 결과 저장 실패는 해당 단계에서 처리합니다. 결과의 크기와 무결성을 확인하고, 진단 기록에는 원본 데이터·인증값·프롬프트·내부 예외 내용을 남기지 않습니다.

Central 진단

Central Admin → Agent → Analysis executions은 읽기 전용 runtime 진단이며 비용 원장이나 전체 Agent trace가 아닙니다. 안전한 status, failure·limit 분류, 수집된 측정값, tenant/session/task context를 기록합니다. Agent usage는 별도 turn/attempt 원장이므로 관련 session이나 task가 turn 전체의 model usage나 비용을 분석에 할당하지 않습니다.

Null은 0이 아니라 미수집입니다. Timing은 겹칠 수 있어 합산하면 안 됩니다. 제한 시점 row나 byte는 부분 관측값입니다. terminal telemetry가 늦거나 빠지면 prepared/running 행은 오래 남을 수 있으므로 실행 중이라는 증거가 아닙니다. 진단 보존 기간은 30일입니다.

Runtime 설정

모델 배정은 .env가 아니라 Central에서 관리합니다. Provider Keys에는 제공자 인증값을, Agent Grades에는 Primary 등급별 후보를, Agent Roles (/admin/agent-role-models)에는 router·analysis_worker·research_worker의 후보와 우선순위를 설정합니다. 배정은 모델 목록의 레코드와 관계형으로 연결됩니다. 일반 문장으로 요청하기 전에 Router를 배정해야 합니다.

기존 Agent 값	Local 수신자	Laravel Cloud	Cloudflare Agent Edge	용도
`AGENT_SERVICE_TOKEN`	루트 `.env`, Edge와 Gateway	secret	secret	Edge와 Gateway에서 Core 내부 Agent endpoint로 연결합니다.
`AGENT_EDGE_TOKEN`	루트 `.env`, Edge	secret	secret	Core에서 보호된 Edge route로 연결합니다.
`AGENT_JWT_PRIVATE_KEY_BASE64` 및 `AGENT_JWT_PUBLIC_KEY_BASE64`	생성된 key file이 기본값	secret	Edge secret 아님	Core가 delegation에 서명하고 Gateway는 인증된 bootstrap으로 public key를 받습니다.
`AGENT_CHECKPOINT_DSN_TEMPLATE`	Gateway 설정	Laravel Cloud Core에는 필요 없음	Gateway container로 전달되는 secret	업무 데이터 접근과 별개인 Agent checkpoint 저장소입니다.

로컬 루트 .env에는 AGENT_ANALYSIS_URL=http://agent-analysis:8788, AGENT_ANALYSIS_TOKEN=local-agent-analysis-token, AGENT_ANALYSIS_CORE_URL=http://app:8000, 빈 AGENT_ANALYSIS_CONTROLLER_TOKEN이 있습니다. Compose는 URL/A를 Gateway에, A/Core URL/B를 controller에 전달합니다. 분석 전에 별도 로컬 B를 생성해야 하며 쓸 수 있는 기본값은 없습니다. task agent:restart는 로컬 controller와 runner를 다시 build·restart합니다.

로컬 controller 설정

task setup 뒤 B를 만든 다음 .env에 이미 있는 분석 항목의 값을 바꾸세요. 같은 key를 추가하면 안 됩니다. 아래 값은 로컬 개발용이며 운영 credential이 아닙니다.

코드 예시

Shell

openssl rand -hex 321

출력값을 기존 dotenv 블록에 넣은 뒤 Agent profile을 시작하세요.

코드 예시

DOTENV

AGENT_ANALYSIS_URL=http://agent-analysis:8788
AGENT_ANALYSIS_TOKEN=local-agent-analysis-token
AGENT_ANALYSIS_CORE_URL=http://app:8000
AGENT_ANALYSIS_CONTROLLER_TOKEN=<생성한 토큰 B>
AGENT_ANALYSIS_CACHE_STORE=session12345

코드 예시

Shell

task dev:up:agent1

Controller·runner·analysis 환경을 바꾼 뒤에는 task agent:restart를 사용하고, 일반 Core profile로 돌아갈 때는 task dev:up:core를 사용합니다. 로컬 controller 설정의 기본값은 다음과 같습니다.

변수	기본값	적용 위치
`AGENT_ANALYSIS_EXECUTION_TIMEOUT_SECONDS`	`60`	로컬 controller sandbox deadline.
`AGENT_ANALYSIS_IDLE_TTL_SECONDS`	`300`	로컬 controller idle job lifetime.
`AGENT_ANALYSIS_MAX_LIFETIME_SECONDS`	`1800`	로컬 controller 최대 job lifetime.
`AGENT_ANALYSIS_MAX_DATASET_BYTES`	`10485760`	Core extraction과 로컬 controller dataset ceiling.
`AGENT_ANALYSIS_MAX_OUTPUT_BYTES`	`1048576`	로컬 controller result ceiling.
`AGENT_ANALYSIS_MAX_CONCURRENT`	`2`	로컬 controller admitted request ceiling.

이 값은 로컬 controller 입력입니다. Analysis Worker는 이 로컬 controller 환경 집합이 아니라 고정 Worker runtime limit을 사용합니다. 다만 Core dataset 계약은 같은 Core dataset ceiling을 계속 적용합니다.

AGENT_ANALYSIS_CACHE_STORE는 Core가 소유하며 기본값은 테넌트 prefix가 붙지 않는 공유 session store입니다. Test에서는 기본값이 array입니다. 일반 runtime에서는 tenant 초기화 전에도 Core가 실행 binding을 복원할 수 있도록 지속되는 공유 store를 유지하세요.

분석 값	Laravel Cloud Core	Cloudflare Gateway Worker	Cloudflare analysis Worker	신뢰 방향
`AGENT_ANALYSIS_URL`	받지 않음	analysis Worker URL	받지 않음	Gateway에서 controller endpoint로 연결합니다.
`AGENT_ANALYSIS_TOKEN` (A)	받지 않음	secret	secret	Gateway Worker에서 analysis Worker로 인증합니다.
`AGENT_ANALYSIS_CORE_URL`	받지 않음	받지 않음	일반 변수	Analysis Worker에서 Core HTTPS endpoint로 연결합니다.
`AGENT_ANALYSIS_CONTROLLER_TOKEN` (B)	secret	받지 않음	secret	Analysis Worker에서 Core 내부 analysis endpoint로 인증합니다.

A와 B는 방향이 다른 credential입니다. Gateway는 URL/A만 전달하며 B는 받지 않습니다. B는 제한된 Core analysis endpoint에 도달하지만 execution token과 Core lease 검사는 export와 공개를 현재 tenant, actor, session, task, 권한에 계속 묶습니다.

첫 활성화에서는 analysis route, Central migration, B가 설치된 Core를 먼저 release한 뒤 URL/A가 Gateway에 도달해야 합니다. Production Deploy는 Core release tag를 발행하고 Laravel Cloud 배포만 요청합니다. 운영자는 검토된 checkout에서 Wrangler로 Analysis와 Gateway를 배포하며 Core와 Analysis URL을 명시하고 설정된 Worker secret은 유지합니다. 둘 다 바뀌면 Analysis를 먼저 배포하고 Gateway를 배포한 뒤 Worker version, container image digest, 실행 instance를 확인합니다. Laravel Cloud의 Edge·Service·B는 별도로 같은 값으로 맞춰야 하며 JWT 키는 Core에 유지합니다. Health는 인증된 Worker liveness만 증명하며 Core B 연결이나 sandbox 실행은 증명하지 않습니다. Rollout 뒤 권한이 있는 analysis test가 그 증거를 제공합니다. Source와 workflow 설정만으로 배포 완료를 입증할 수 없습니다. A는 두 Worker에서, B는 Laravel Cloud와 analysis Worker에서 함께 회전합니다.

결과 읽기

Agent Gateway 켜기에서 Edge와 Gateway를, 환경변수에서 전체 owner별 목록을 확인하세요. Central 진단은 기록된 분석 결과를 설명하며 browser stream과 model 동작은 실제 인증 turn으로 확인해야 합니다.