LLM 시대, API와 CLI를 섞어 쓰는 도구 구성 전략 가이드
LLM(대형 언어 모델) 시대의 “도구 구성”은 이제 단순히 API를 붙이는 문제가 아닙니다. 모델이 일을 잘하게 만드는 인터페이스를 어디에 두고, 얼마나 구조화할지의 문제에 가깝죠. 2026년 산업계에서 두 가지 전략이 특히 자주 논의됩니다. 하나는 상위 수준의 전용 도구(API/SDK/에이전트 프레임워크)를 만들어 세밀한 작업을 수행하게 하는 방식이고, 다른 하나는 새 도구를 만들기보다 “유용한 CLI 조합”을 모델에게 알려 파이프라인으로 굴리는 방식입니다.
이 글은 그 두 전략을 “API vs CLI”로 단순 비교하지 않고, 실제로 함께 섞어 쓰는 설계 레시피를 정리합니다. 특히 OpenAPI, 쉘 파이프라인, 토큰 비용 최적화, OAuth·비밀 관리까지 현실적인 운영 포인트에 집중해보겠습니다.
상위 도구(API/SDK)로 ‘업무 단위’를 만든다
첫 번째 전략은 모델에게 “업무 단위”를 쥐여주는 것입니다. 예를 들어 GitHub 리포지토리에서 요청 목록을 보여주고, 거기서 특정 PR을 열어 요약하고, 라벨을 붙이고, 코멘트를 남기는 흐름을 생각해봅시다. 이걸 매번 curl과 JSON으로 처리하게 하면 모델은 매 단계마다 길을 잃기 쉽고, 호출 스펙을 설명하는 토큰도 늘어납니다.
그래서 상위 도구는 보통 두 가지를 제공합니다. 하나는 목적이 분명한 함수(“PR 목록 가져오기”, “이슈 코멘트 달기”)이고, 다른 하나는 실패/재시도/권한 오류 같은 현실을 흡수하는 실행 레이어입니다. 2026년 기준으로 이런 “에이전트 실행 환경”을 빠르게 구성하려는 팀이 늘었고, LangChain·LangGraph·AutoGen·CrewAI 같은 프레임워크가 비교군으로 자주 등장합니다. 특히 멀티스텝 자동화나 인간 승인(휴먼 인 더 루프)이 필요한 조직은 상태 관리가 명시적인 오케스트레이션 쪽을 선호하는 경향이 있습니다.
다만 단점도 명확합니다. 도구를 만들고 유지보수하는 비용이 생기고, 스키마(파라미터 정의)와 문서가 커질수록 모델 컨텍스트를 먹습니다. 그래서 요즘은 “모든 걸 상위 도구로 만들지 말고, 진짜 자주 쓰는 핵심만 올린다”로 가는 팀이 많습니다.
새 도구를 만들지 말고, CLI를 ‘모델의 손’으로 만든다
두 번째 전략은 조금 더 과감합니다. “모델이 필요한 작업을 쉘 명령으로 조립하게 하자”에 가깝습니다. 여기서 핵심은 유닉스 쉘의 진짜 강점인 명령 구성(파이프라인)을 적극 활용한다는 점입니다.
왜 이게 LLM 시대에 먹히느냐면, 모델이 작업을 단계별로 나누는 것은 잘하지만 “매 단계마다 다시 물어보는” 과정에서 토큰이 새고, 문맥이 어긋나고, 실행이 늘어지기 때문입니다. 반면 파이프라인은 한 번에 연결된 흐름을 만들 수 있습니다. 예를 들어 “목록 가져오기 → 필요한 필드만 추출 → 다음 호출에 전달”이 한 줄로 이어지면, 모델은 중간 상태를 장황하게 설명할 필요가 줄고(=토큰 절감), 사용자는 그 한 줄을 스크립트로 저장해 재사용할 수 있습니다.
그리고 명령줄은 인간과 기계 모두에게 꽤 괜찮은 공통 인터페이스입니다. 사람은 읽고 고칠 수 있고, 모델은 생성하고 실행할 수 있죠. 게다가 운영 환경(CI, cron, 로컬 자동화)으로 옮기기도 쉽습니다.
요약하면, 상위 도구는 “반복 업무를 제품화”하는 방식이라면, CLI 파이프라인은 “즉석에서 조합 가능한 레고”에 가깝습니다.
OpenAPI + 쉘 자동완성: ‘API를 CLI처럼’ 쓰는 설계
CLI 전략이 강력해지려면 전제가 하나 있습니다. 명령이 “대충 기억나는 주문”이 아니라, 스키마 기반으로 정확해야 한다는 점입니다. 여기서 OpenAPI가 등장합니다.
많은 SaaS 벤더가 API를 OpenAPI 명세로 정의하고 있고, 이 명세가 있으면 엔드포인트·파라미터·타입을 기계가 읽을 수 있습니다. 즉, 모델에게 긴 설명서를 던지는 대신 “명세를 읽어서 필요한 호출만 정확히 만들게” 할 수 있습니다.
이때 유용한 예가 OpenAPI를 해석해 CLI처럼 쓰게 해주는 도구들입니다. 예를 들어 Restish는 OpenAPI 사양을 등록해두면, API 엔드포인트와 파라미터에 맞춘 쉘 자동완성을 만들어줍니다. 사람이 칠 때도 편하고, 모델이 생성할 때도 실수가 줄어드는 구조죠.
결국 그림은 이렇습니다. “API는 그대로 두되, 사용 경험은 CLI로 바꾼다.” 새 도구를 만들지 않고도, 모델이 ‘호출 가능한 표준 인터페이스’를 갖게 됩니다.
OAuth 2.0과 토큰 보관: 자동화의 발목을 잡는 현실 포인트
여기서부터가 진짜 실전입니다. API를 CLI로 편하게 부르면, 곧바로 인증이 발목을 잡습니다. 특히 OAuth 2.0은 서비스마다 흐름이 미묘하게 다르고, 브라우저 리다이렉트나 권한 범위(scope) 같은 변수가 많습니다.
현실적인 패턴은 “Restish 같은 도구는 명세와 호출에 집중시키고, OAuth 로그인 흐름은 별도 스크립트로 분리”하는 것입니다. 스크립트가 토큰을 받아오면, CLI 호출 시 헤더에 주입하는 방식이죠.
그리고 토큰 저장은 대충 ~/.env에 넣고 끝내면 곧 사고가 납니다. macOS 환경이라면 Keychain을 이용해 비밀을 저장하고, 필요할 때 생체인식/비밀번호로 꺼내 쓰는 구성이 안전합니다. 모델이 명령을 실행할 수 있는 시대일수록 “비밀이 파일로 평문 저장되어 있지 않다”는 것 자체가 큰 방어선이 됩니다.
Google Docs/Groups 같은 SaaS를 ‘목록화→읽기→이해’ 파이프라인으로 다루기
LLM에게 문서를 “읽히는” 것과, 문서 저장소를 “다루게 하는” 것은 다릅니다. 특히 Google Docs처럼 클라우드 기반 문서가 흩어져 있으면, 모델이 잘하는 요약/분석 이전에 먼저 해야 할 일이 생깁니다.
첫 단계는 목록화입니다. HTTP API로 문서를 나열하고, 필요한 문서를 가져올 수 있어야 합니다.
두 번째는 변환입니다. 모델이 다루기 좋은 형태(예: Markdown 텍스트)로 읽어오는 과정이 필요합니다.
세 번째는 맥락 확장입니다. 본문만이 아니라 첨부된 댓글 스레드까지 함께 가져오면, “왜 이 문서가 이렇게 되었는지”를 모델이 이해하는 데 도움이 됩니다.
이 흐름은 파이프라인으로 만들기 아주 좋습니다. “문서 리스트 가져오기 → 필터링 → 본문 Markdown 변환 → 댓글 수집 → 하나로 묶기”가 가능해지면, 사용자는 그 명령을 저장해두고 반복 실행할 수 있고, 모델은 긴 대화를 하지 않아도 입력 데이터를 안정적으로 확보할 수 있습니다.
API 명세가 없는 서비스는? “수집 → 재생성”으로 우회한다
모든 서비스가 친절하게 OpenAPI를 주는 건 아닙니다. 예를 들어 어떤 커뮤니티형 서비스는 공식 명세가 없거나, 기능이 웹 UI에만 숨어 있기도 하죠.
이 경우의 우회로는 두 단계입니다. 먼저 브라우저 트래픽을 기록해(예: 하버 파일로 수집) 실제로 오가는 요청/응답을 확보합니다. 그리고 그 기록을 바탕으로 LLM을 이용해 Python 클라이언트를 생성합니다. “명세가 없으면 명세를 ‘발견’해서 만든다”에 가깝습니다.
이 방식은 완벽하진 않습니다. 서비스가 UI를 바꾸면 깨질 수 있고, 인증이 까다로울 수도 있습니다. 하지만 MCP 서버가 준비되기 전, 혹은 벤더가 공식 지원을 하기 전 단계에서 “우리 팀이 독립적으로 CLI를 유지보수한다”는 선택지를 만들어줍니다.
시사점: 2026년식 정답은 ‘API냐 CLI냐’가 아니라 ‘섞는 법’이다
정리하면, 상위 수준 도구는 반복 업무를 안정적으로 수행하게 해주고, CLI 파이프라인은 즉흥적인 조합과 토큰 절감, 재사용(스크립트화)에 강합니다. 그래서 실전에서는 둘 중 하나를 고르는 게 아니라 레이어를 나눠 섞는 쪽이 이깁니다.
제가 추천하는 실용적 기준은 이렇습니다. 팀이 매주 같은 일을 세 번 이상 반복한다면 상위 도구(API/SDK/에이전트 노드)로 올리세요. 반대로 “이번 달만 필요한 자동화”거나 “데이터를 모으고 변환하는 ETL성 작업”이라면 CLI 파이프라인이 빠르고 싸게 먹힙니다.
그리고 마지막으로, LLM 시대의 자동화는 결국 보안에서 멈춥니다. OAuth 흐름 분리, 안전한 토큰 저장(Keychain 같은), 파괴적 명령 차단(허용 도구 제한) 같은 장치가 있어야 “모델이 일을 한다”가 “모델이 사고를 친다”로 바뀌지 않습니다.
참고 (본문에 사용한 경우에만 포함)
1Top 8 LLM Frameworks for Building AI Agents in 2026 | Second Talent
이 노트는 요약·비평·학습 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.
키워드만 입력하면 나만의 학습 노트가 완성돼요.
책이나 강의 없이, AI로 위키 노트를 바로 만들어서 읽으세요.
콘텐츠를 만들 때도 사용해 보세요. AI가 리서치, 정리, 이미지까지 초안을 바로 만들어 드려요.