LLM 에이전트가 호출하는 CLI 도구 설계 OnTech Insight

TECH INSIGHT / EXPLAINED

에이전트용 CLI는 예측 가능한 데이터, 실행 한도, 명시적인 권한을 제공해야 합니다. 모델이 결정을 제안하더라도 실제 실행 파일은 입력과 한도를 검사한 뒤에만 외부 상태를 바꿉니다.

동료 세 명이 에이전트 CLI의 계약과 실행권한 주제를 그림으로 설명하는 모습 — 이해를 돕기 위한 AI 생성 설명 일러스트. 실제 운영 화면이나 실적 자료가 아닙니다.

실제 프로젝트의 로컬 실행 화면

기존 프로젝트의 화면 또는 함수를 로컬에서 실행해 촬영했습니다. 개인정보 없는 샘플 입력을 사용했으며, 실행한 범위는 각 이미지 아래에 설명했습니다.

LLMStockTrading/lib/output.py의 print_json()·print_error()가 실제 출력한 내용을 브라우저 실행 리포트로 캡처했습니다. SAMPLE은 임의 값이며 계좌·키·실제 오류가 아닙니다. 원본의 단순한 ok/data/error 형식만 보여 주며, 본문에서 권장한 버전·요청 ID·타입 검증이 구현돼 있다는 뜻은 아닙니다.

표준 출력에는 JSON 문서 하나

버전, 요청 ID, 성공/실패가 있는 형식과 일치하는 종료 코드를 사용합니다. 진단 로그는 stderr로 보냅니다. 모든 값을 default=str로 문자열화하면 잘못된 객체가 숨어 계약 오류를 놓칩니다. 타입별 직렬화를 정하고 유한하지 않은 숫자는 거절하세요. Windows 출력과 이를 읽는 소비자 모두 UTF-8을 지정합니다.

비밀을 노출하지 않는 실패 응답

STALE_INPUT, LIMIT_EXCEEDED처럼 안정적인 오류 코드와 짧고 안전한 설명을 반환합니다. traceback은 자격증명과 민감한 응답 본문을 제거한 제한된 로그에 남기세요. 예외와 traceback 전체를 에이전트 문맥에 보내면 토큰·계좌 정보·로컬 경로가 노출될 수 있습니다. 거절된 요청과 전송 후 결과를 모르는 타임아웃도 구분합니다.

스냅샷에도 트랜잭션이 필요하다

작은 상태 스냅샷과 추가 전용 이벤트 원장을 함께 둡니다. 같은 디렉터리의 임시 파일에 쓰고 flush한 뒤 지원되는 원자적 교체를 하며, 여러 작성자는 조율하거나 트랜잭션 DB를 사용하세요. 스키마 버전·관측 시각·출처를 기록합니다. 외부 잔고·주문으로 대사하되 로컬 의도 ID도 내구성 있게 보존해야 앱이 왜 주문했는지 추적할 수 있습니다.

두 단계 실행 계약 예시

견적 도구가 제안 행동, 입력 시각, 최대 크기, 만료되는 plan ID를 반환합니다. 실행 도구는 만료·종목 허용 목록·가용 잔고·고정 한도를 재검사하고 제출 전에 중복 방지 키를 기록합니다. 한도가 100이면 모델이 101을 요청할 때 설명이 그럴듯해도 코드가 거절해야 합니다. 타임아웃은 새 주문을 자동 생성하는 대신 대사 상태로 전환합니다.

조회 틱과 실행을 분리한다

tick은 계좌·포지션·신호를 모으되 매매하지 않을 수 있습니다. 출처별 시각과 부분 실패를 표시하세요. 모델의 제안은 결정론적인 위험 관문이 검증할 입력입니다. 전략 일부를 프롬프트로 옮겨도 안전 한도를 코드에서 지우면 안 됩니다. 하위 프로세스는 인자 배열·시간 제한·출력 한도로 실행하고 모델 문자열을 셸에 전달하지 않습니다.

메시지 예시

가상의 견적 응답, 실행 요청, 거절 응답 순서입니다. plan은 서버 측에 저장하고 실행 시 만료를 검사합니다. 클라이언트가 보낸 max_quantity를 권한의 근거로 믿으면 안 됩니다.

{"ok":true,"schema_version":1,"request_id":"r-42","data":{"plan_id":"p-7","expires_at":"2026-09-29T01:01:00Z","symbol":"EXAMPLE","max_quantity":100,"observed_at":"2026-09-29T01:00:00Z"}}

{"request_id":"r-43","plan_id":"p-7","quantity":101,"idempotency_key":"intent-7"}

{"ok":false,"schema_version":1,"request_id":"r-43","error":{"code":"LIMIT_EXCEEDED","message":"quantity exceeds plan limit"}}

공식 문서와 이어 읽기

내용·예제 검토: 2026-09-29

LLM 에이전트가 호출하는 CLI 도구 설계