CLI-based Tool Calling

• CLI-based Tool Calling은 단일 run(command="...") 도구로 Unix 명령어를 실행해 agent의 외부 작업을 수행하는 패턴
• 함수 카탈로그(function calling) 대신 LLM이 이미 학습한 Bash 문법을 그대로 활용하는 도구 인터페이스
• LLM의 본질이 “텍스트 환경의 운영자(터미널 오퍼레이터)“라는 관찰에서 출발한 agent 아키텍처 철학
• 컨텍스트 절감·조합성·자기 기술 능력을 동시에 달성하는 단순화된 도구 모델

해당 개념이 필요한 이유

• 함수 카탈로그 방식은 매 호출마다 N개 도구 중 선택을 요구하여 토큰·주의력 낭비 발생
• 단순 작업(“로그에서 ERROR 개수”)도 3호출(read_file → search → count)이 필요한 비효율 구조
• LLM 훈련 데이터(GitHub/StackOverflow)에 Bash·CLI 패턴이 압도적으로 많아 별도 학습 없이도 능숙
• 새 명령어 추가 시 스키마 등록 없이 --help로 자기 기술 가능 → 확장 비용 최소화

AS-IS — Function Calling 카탈로그

sequenceDiagram
    autonumber
    participant A as Agent(LLM)
    participant T as Tool Catalog
    A->>T: read_file("/var/log/app.log")
    T-->>A: 로그 전체 텍스트
    A->>T: search_text("ERROR")
    T-->>A: 매칭 라인들
    A->>T: count_lines()
    T-->>A: 247
    Note over A,T: 3호출, 매번 도구 선택 추론

TO-BE — CLI 기반 단일 도구

sequenceDiagram
    autonumber
    participant A as Agent(LLM)
    participant R as run() Tool
    A->>R: run("cat /var/log/app.log | grep ERROR | wc -l")
    R-->>A: "247\n[exit:0 | 12ms]"
    Note over A,R: 1호출, Unix 파이프로 조합

LLM의 본질 — “터미널 오퍼레이터”

LLM과 Unix가 50년의 시차를 두고 같은 설계 결정에 수렴했다.

영역	Unix (1970s)	LLM (현재)
데이터 형식	모든 것은 텍스트 스트림	모든 것은 토큰(텍스트)
조합 방식	| 파이프	텍스트 입출력 chaining
자기 기술	--help, exit code	도구 설명 + 출력 메타
LLM의 학습 환경	—	GitHub/StackOverflow 데이터

LLM 훈련 코퍼스의 막대한 Bash 명령어·에러 메시지·exit code 노출 덕분에, CLI 사용은 사실상 “기본기”에 해당한다. 새로운 함수 시그니처를 학습시키는 비용 없이 그 능력을 그대로 끌어 쓰는 것이 CLI tool calling의 출발점.

Function Calling vs CLI — 호출 비용 비교

항목	Function Calling	CLI
도구 노출 방식	카탈로그 (15+ 함수 사전 노출)	단일 run() + 명령어 목록
조합 가능성	호출 결과를 LLM이 다시 받아 다음 함수 결정	| 파이프로 단일 호출 내 조합
컨텍스트 비용	매 호출마다 도구 선택 토큰 소모	명령어 자체가 의도 표현
새 기능 추가	JSON Schema 정의 + 프롬프트 등록	명령어 추가, --help로 자동 발견
LLM 사전지식	학습 데이터 부족	풍부 (Bash, Unix 문서)
실패 복구	함수 시그니처 에러	exit code + stderr 표준

4가지 Unix 연산자 (Chain Parser)

CLI tool은 단일 명령어가 아니라 연산자로 조합된 표현식을 받아들여야 LLM의 작업 압축이 의미를 가진다.

연산자	의미	예시
|	이전 stdout → 다음 stdin	cat log | grep ERROR | wc -l
&&	이전 성공 시만 실행	curl $URL -o data.csv && head data.csv
||	이전 실패 시만 실행	cat config.yaml || echo "default"
;	결과 무관 순차 실행	cd /tmp ; ls ; date

2계층 아키텍처 (개요)

LLM의 인지 제약(컨텍스트 유한, 텍스트 전용)과 Unix의 순수 의미론이 충돌하지 않도록 두 계층으로 분리한다.

• Layer 1 (Execution): 순수 Unix 의미론. 메타데이터·가공 없이 명령어 실행과 파이프 처리만 수행.
• Layer 2 (Presentation): LLM에 전달하기 직전, 바이너리 가드·오버플로우 처리·메타 푸터·stderr 첨부 적용.

분리 이유: Layer 1에서 [exit:0] 같은 메타데이터를 추가하면 다음 파이프(grep)의 검색 대상에 섞여 의미론이 깨진다.

상세 내용은 Two-Layer Architecture에서 다룬다.

휴리스틱 3기법 (개요)

Agent가 도구를 효율적으로 발견·사용·복구하도록 만드는 3가지 설계 원칙.

1. Progressive --help discovery — 필요할 때만 정보를 점진적으로 노출
2. Error as navigation — 에러 메시지 자체가 다음 행동을 안내
3. Consistent output format — [exit:0 | 12ms] 같은 메타데이터로 LLM에 비용·성패를 학습시킴

상세 내용은 Agent Heuristic Design에서 다룬다.

한계와 제약

• 강타입 상호작용: DB 쿼리·GraphQL은 스키마 검증된 typed 인터페이스가 안정적
• 보안: CLI 문자열 연결은 주입 위험 → 샌드박스 격리 필수
• 멀티모달 네이티브: 순수 오디오·비디오 처리에는 텍스트 파이프가 병목

CLI 기반 접근은 “agent를 위한 일반 작업 환경”으로는 강력하지만, 모든 도구 인터페이스를 대체하는 은탄환은 아니다.

관련 개념

• Two-Layer Architecture — Layer 1(Execution)과 Layer 2(Presentation) 분리, 바이너리 가드·오버플로우·메타 푸터·stderr 첨부 4가지 메커니즘
• Agent Heuristic Design — Progressive --help, Error as Navigation, Consistent Output Format 3가지 휴리스틱
• AG-UI Tools — Frontend-defined tool 패턴 (CLI tool과 대비되는 다른 각도의 도구 인터페이스)
• AbstractAgent — agent loop 진입점과 RunAgentInput 자동 조립
• delta — 스트리밍 메타데이터 일반 개념

참고 문서

• I was backend lead at Manus — 원문 Gist
• Context Engineering for AI Agents (Manus 공식 블로그)
• agent-clip 소스 (Go)