지난 1~2년간 LLM을 활용한 AI 에이전트에 대한 기대는 폭발적이었다. 텍스트 입력만으로 코드 리뷰, 이메일 작성, 에러 분석까지 수행해주는 자동화된 AI 동료에 대한 환상이 모든 개발자 커뮤니티를 뜨겁게 달궜다.
그러나 현실은 달랐다. 대부분의 “에이전트”라고 불리는 시스템은 단순히 GPT에게 시나리오성 지시를 내리고 응답을 받는 수준에 머물렀다. 입력값이 조금만 어긋나거나, 출력값이 기대와 다르면 디버깅은 불가능하고, 일관성은 무너졌다.
실제 프로덕션 환경에서 에이전트를 사용하고자 할 경우 필요한 것은 “프롬프트 장인 정신”이 아니라 구성 가능한 실행 구조다. 이 글에서는 Qodo Command라는 CLI 기반 도구가 제시하는 구성 가능한 AI 에이전트 설계 방식을 분석하고, 실전 투입 가능성에 대해 살펴본다.
1. 단순한 프롬프트에서 실행 단위로 – 에이전트 구성 방식의 진화
기존의 LLM 기반 자동화는 대부분 다음과 같은 구조를 따른다:
- 프롬프트에 역할, 규칙, 컨텍스트, 도구 설명까지 모두 포함시킴
- 필요할 경우 외부 툴(API, DB, 파일 등)을 호출하도록 지시
- 결과물은 chat 또는 API를 통해 사용자에게 전달
이 방식은 소규모, 단발성 태스크에선 잘 동작한다. 하지만 문제는 다음과 같다:
- 길어지는 프롬프트 유지 보수 어려움
- 툴 수 증가 시 일관된 구성 불가
- 입출력 정의 없음 → 디버깅 불가능
결국 개발자가 아닌 PM이나 마케터가 테스트용으로 써보는 정도에 그치게 된다.
2. Qodo의 제안 – “에이전트를 정의 가능한 구조로 만들자”
Qodo는 에이전트를 .toml 파일로 정의하는 구조를 제안한다. 이는 마치docker-compose.yml, workflow.yaml 같은 인프라 구성 파일을 다루는 느낌과 유사하다. 구성 요소는 다음과 같다:
trigger
- 언제 실행할 것인지 정의
- ex) on_pull_request, on_ci_failure, cron = "0 * * * *" 등
input
- 어떤 데이터를 입력으로 받을지 정의
- git diff, ci logs, api response, file content 등 다양한 소스 지정 가능
action
- 어떤 LLM을 호출하고, 어떤 툴을 사용할지 정의
- OpenAI, Anthropic, HuggingFace 모델 외 custom endpoint도 설정 가능
- API 호출, 파일 생성, 슬랙 메시지 전송 등의 tool 실행 가능
action
- 출력 형식을 명시적으로 정의
- Markdown, JSON, Text, Slack 메시지, GitHub PR 코멘트 등 다양하게 지정 가능
3. Qodo Command로 AI 에이전트 만드는 단계별 가이드
Qodo의 핵심은 .toml 파일 하나로 agent의 전 과정—입력, 실행, 출력—을 선언형으로 정의할 수 있다는 점이다.
아래는 실제로 에이전트를 만드는 단계별 가이드다.
1) Qodo CLI 설치
npm install -g @qodo/command
qodo login 로그인 후 발급되는 API 키는 로컬에 자동 저장되며, CI 환경에서는 환경변수 QODO_API_KEY를 사용하는 방식으로 인증된다.
2) 에이전트 템플릿 생성
qodo create agent --template ci_debugger3) 에이전트 구성 파일 (.toml) 예시
version = “1.0”
[[commands.ci_debugger]]
description = "CI 실패 시 로그를 요약하고 Slack으로 전송"
trigger = "on_ci_failure"
[input]
source = "ci_logs"
[action]
model = "openai:gpt-4"
tools = ["summarizer", "diagnostic_checker"]
[result]
type = "slack"
channel = "#devops-alert" > json자신의 조직 환경에 맞게 다음을 조정할 수 있다:
trigger :
실행 시점 지정 (예: PR 생성, CI 실패 등)
input :
입력 데이터 (예: git diff, 로그 파일 등)
action :
사용할 LLM 및 보조 도구
result :
출력 채널 지정 (Slack, GitHub 등)
4) 에이전트 실행
qodo run ci_debugger.toml실제로 실행해보면 에이전트가 CI 로그를 수집하고, 요약 및 진단 작업을 수행한 뒤 Slack으로 결과를 전송한다. 디버깅은 CLI 로그를 통해 trace 가능하다.
5) CI/CD 파이프라인에 통합
Steps:
- run: npm install -g @qodo/command
- run: qodo login --api-key ${{ secrets.QODO_API_KEY }}
- run: qodo run ci_debugger.toml
이렇게 하면 Pull Request가 생성될 때마다 자동으로 코드 리뷰 요약, 테스트 목록 생성 등의 작업을 수행하게 할 수 있다. * 추가 고급 기능(output schema, custom tools 등)의 경우 Qodo 공식 문서에서 확인할 수 있다.
4. 생산 환경 관점에서 본 장점
유지 보수 용이성
- 기능 단위 TOML 분리 → 책임 명확화
- prompt 수정 시에도 전체 config 구조는 유지됨
디버깅 가능성 확보
- 입력/출력이 명시되기 때문에 중간 로그 추적 가능
- 실행 실패 시 어느 단계에서 문제인지 명확히 파악 가능
보안성 및 통제 가능성
- 로컬이나 자체 서버(CLI 설치 환경)에서 실행 가능
- API 키 등 민감한 정보는 .env 또는 환경 변수로 관리
결론: 작은 단위부터 실용적인 방향으로
우리는 이미 많은 자동화 도구와 업무 스크립트를 만들어 왔다. 그 흐름은 셸 스크립트 → Jenkins 파이프라인 → GitHub Actions → Low-code 플랫폼으로 진화해왔고, 이제 그 상위 계층으로 LLM 기반 에이전트가 합류하고 있다.
하지만 LLM 기반 에이전트는 기존 자동화 시스템과 달리 불확실성과 창의성을 동시에 다루는 구조다. 그래서 더더욱 예측 가능하고 디버깅 가능한 구조가 필요하다.
Qodo가 제시한 방식은 다음과 같은 인사이트를 준다:
- 구조화된 정의 (.toml)는 prompt 실험을 넘어서 개발문화와 잘 맞는 구성 중심 접근을 가능케 한다
- CLI 기반 도입은 조직 내부 시스템에 쉽게 통합할 수 있는 장점이 있다
- “에이전트를 작게 나눠서 만든다”는 철학은 오히려 LLM의 취약한 맥락 유지 한계를 극복하는 데 효과적이다
AI 에이전트를 도입하고 싶은 팀이라면, 티어 0 자동화부터 시작해보자. CI 실패 대응, PR 설명 자동 생성, 로그 요약 등 작지만 반복적이고 명확한 영역에서 성공 경험을 만들고, 그 다음 영역으로 천천히 확장하는 것이 가장 실용적인 전략이다.
