AQVEN이 LLM 워크플로를 실행 전에 검사한다

AQVEN은 여러 단계의 모델·도구·사람 검토를 묶는 LLM 워크플로를 Python 파일로 구성하고, 토큰을 쓰기 전에 연결과 흐름을 검사하는 프레임워크다. 로컬 Studio에서 실행 과정을 확인할 수 있으며 코딩 에이전트는 MCP 서버를 통해 같은 프로젝트 파일을 수정하고 실험을 수행한다.

GitHub 저장소 · 문서 · 빠른 시작 · 사용 사례 · Studio · llms.txt

AQVEN은 워크플로를 저장소 안의 타입 지정 파일로 관리한다. 흐름 파일과 단계별 파일, Markdown 프롬프트, 선언된 타입·에이전트·도구가 구성 요소다. aqven check는 각 파일의 연결을 확인하고 모든 흐름을 시뮬레이션한다. Studio는 같은 설치에 포함된 로컬 브라우저 앱으로, 실행 단계를 하나씩 보여준다. Claude Code, Codex 또는 다른 MCP 클라이언트는 AQVEN의 MCP 서버를 통해 같은 파일을 다루고 실험을 실행할 수 있으며, 실험의 판정은 AQVEN이 계산한다.

AQVEN은 알파 단계여서 릴리스마다 내용이 달라질 수 있다. 오픈소스가 아니라 소스 공개(source-available) 소프트웨어다. 라이선스를 확인해야 한다.

설치와 실행 조건

AQVEN에는 uv가 필요하며 Python 3.14에서 실행된다. uv가 Python을 내려받는다.

uv tool install aqven
aqven new my_project --template minimal --provider openrouter

aqven new는 프로젝트를 만들고 uv sync로 환경을 설치한 뒤 타입이 지정된 Python 모델을 생성한다. 코딩 에이전트를 위한 AGENTS.md, CLAUDE.md, AQVEN MCP 서버를 등록하는 .mcp.json, 에이전트가 작업할 때 aqven check를 실행하는 Claude Code 훅도 준비한다.

실제 실행에는 모델 API 키가 필요하다. my_project/.env.example을 my_project/.env로 복사하고 OPENROUTER_API_KEY를 설정한다. 실제 실행은 .env 또는 셸에 내보낸 키를 사용하며 무료가 아니다. aqven check에는 API 키나 네트워크 연결이 필요하지 않다.

지원 플랫폼의 검증 수준은 서로 다르다. Linux에서는 모든 변경 때 ubuntu-latest에서 전체 CI 테스트를 실행한다. macOS는 주 개발 플랫폼이며, 빌드한 휠을 이용해 설치 과정과 오프라인 aqven check를 Platform smoke 워크플로에서 스모크 테스트하지만 전체 테스트는 아직 macOS CI에서 실행하지 않는다. Windows에서는 Platform smoke 워크플로가 Windows 러너에서 휠을 빌드·설치하고 aqven check를 실행하지만 그 이상의 검증은 하지 않았다. 문제가 생기면 GitHub 이슈에 제보를 요청한다.

AQVEN은 >=3.14,<3.15를 요구한다. 엔진이 단일 마이너 버전에서 실행되도록 해 단계 코드가 어디서나 동일하게 동작하게 한다는 정책이며, uv가 Python 3.14를 내려받는다. 원문은 Python 3.15가 2026년 10월에 출시됐다고 설명한다. 지원은 계획돼 있지만 엔진·의존성·CI가 모두 통과하는 릴리스에서 제공할 예정이며 날짜는 약속하지 않았다.

코딩 에이전트와 함께 사용하기

프로젝트에서 Claude Code를 시작하고 요청이 나오면 aqven 서버 사용을 승인한다.

cd my_project
claude

그 뒤 에이전트에게 작업을 맡길 수 있다. 에이전트는 흐름을 만들고 변경할 때마다 aqven check를 실행하며, 작업을 여러 차례에 나눠 진행한다. 저장소에는 다음과 같은 예시 과제가 제시돼 있다.

Build a flow that reads an incoming support e-mail and returns its intent (defect, delivery or question) and a one-line summary. Done means: the intent is right on more than 90% of held-out cases, and a case costs under $0.002. Work in rounds: explore on working cases, confirm once on held-out cases. Stop when every "done" criterion is confirmed, or when you have spent $5. Then report FINDINGS.md, the decisions you made and the risks that are left.

Studio를 함께 열어 각 실행을 보거나 Studio의 채팅 패널에서 Claude Code 또는 Codex를 실행할 수 있다. 채팅도 같은 프로젝트를 사용한다.

uv run aqven dev my_project

Codex, Cursor 또는 다른 MCP 클라이언트를 설정하는 방법은 Studio 밖에서 코딩 에이전트를 설정하는 안내를 참조한다. aqven new는 AQVEN 스킬을 프로젝트에 넣는다. Claude Code 전체에서 사용하려면 다음 명령으로 플러그인을 설치한다.

/plugin marketplace add lastonoga/AQVEN
/plugin install aqven@aqven

직접 확인하고 실행하기

새 프로젝트에서 다음 명령을 실행한다.

cd my_project
uv run aqven check my_project

errors: 0, warnings: 0

aqven check는 모든 파일을 검증한 다음 모델 호출을 대체하는 모의 구현으로 모든 흐름을 시뮬레이션한다. 변경할 때마다 실행하도록 안내한다. 실제 실행은 .env에 키를 넣은 뒤 할 수 있으며, 이벤트가 발생할 때마다 한 줄씩 출력한다.

echo '{"text": "How long does a light strip last?", "tone": "friendly"}' > question.json
uv run aqven run answer_question --root my_project --input question.json

저장소의 예시는 워크플로를 정의하는 파일을 중심으로 다음 구조를 보여준다.

my_project/   AGENTS.md  CLAUDE.md  .mcp.json  .claude/  pyproject.toml   my_project/     aqven.yaml     agents/assistant.yaml     tools/count_words.yaml     types/enums/tone.yaml  types/records/question.yaml  types/records/answer.yaml     flows/answer_question/       flow.yaml       nodes/prepare/  prepare.node.yaml  prepare.py       nodes/reply/    reply.node.yaml  reply.inference.yaml  reply.prompt.md

flows/answer_question/flow.yaml은 입력과 출력, 단계 순서를 선언한다.

apiVersion: "aqven/v1"
kind: "Flow"
description: "Cleans up a question and answers it in the requested tone"
input: "Question"
output: "Answer"
returns:
- name: "reply"
 from: "$reply.out.reply"
- name: "tone"
 from: "$input.tone"
order:
- "prepare"
- "reply"

flows/answer_question/nodes/reply/reply.node.yaml은 모델 단계다. prepare 단계에서 text를 가져오고 흐름 입력에서 tone을 받는다.

apiVersion: "aqven/v1"
kind: "Node"
node: "llm"
description: "Answers the prepared question with the assistant agent"
agent: "assistant"
in:
- name: "text"
 from: "$prepare.out.text"
- name: "tone"
 from: "$input.tone"

reply.prompt.md에는 프롬프트를 별도 파일로 둔다. reply.inference.yaml은 호출의 타입이 지정된 입력과 출력을 선언한다.

Answer the question in a {{ tone }} tone, in at most 120 words.
If you are not sure a draft fits, count its words with the count_words tool.
<question>{{ text }}</question>
{{ output_format }}

참조를 하나 잘못 바꿔 검사할 수도 있다. 예시에서는 $prepare.out.text를 $prepare.out.txt로 바꾼다.

$ uv run aqven check my_project
flows/answer_question/nodes/reply/reply.node.yaml:8:3: error E_REF_MISSING in[0].from: reference $prepare.out.txt: the value has no field txt
errors: 1, warnings: 0

검사 실패 시 종료 코드는 1이므로 훅이나 CI 작업이 다음 단계로 진행하지 않게 할 수 있다. AQVEN은 값의 타입이 입력 슬롯에 맞지 않는 경우(E_BINDING_TYPE), 프롬프트 변수가 추론 선언에 없는 경우(E_PROMPT_VARIABLE_UNDECLARED), switch가 일부 경우를 처리하지 않는 경우(E_SWITCH_NOT_EXHAUSTIVE)도 탐지한다. 전체 진단 목록을 제공한다.

빠른 시작 안내는 모든 노드 종류와 사람의 승인, 실험을 포함한 지원 업무 흐름 예제인 --template showcase를 다룬다.

실험 절차와 판정의 범위

한 번의 실행은 사례 하나를 보여주고 aqven check는 연결 구성을 확인하지만, 어느 쪽도 실제 입력 전반에서 워크플로가 어떻게 작동하는지는 알려주지 않는다. AQVEN은 에이전트가 여러 차례 실험을 진행하고 사람이 결정하도록 설계했다.

• 사람은 목표와 완료 기준을 수치로 정하고 예산을 설정한다.
• 에이전트는 작동하는 가장 단순한 흐름을 만들고, 기대 출력이 있는 사례를 작성한 뒤 변경할 때마다 aqven check를 실행한다.
• 사람은 에이전트가 제시한 첫 실행 추적을 읽는다. 실패한 실행을 먼저 살피고 각 사례에서 처음 문제가 생긴 지점을 기록한다.
• 에이전트는 사람의 메모를 합의된 실패 유형으로 분류하고, 데이터를 보기 전에 유형마다 실험 하나를 작성한다.
• 에이전트는 작업용 사례에서 한 실험군마다 변경 한 가지를 탐색한 뒤, 처음 보지 않았던 데이터셋 절반인 보류 사례에서 한 번 확인한다. 서버는 confirmed, refuted, inconclusive 가운데 판정을 기록하고 결과를 FINDINGS.md에 남긴다.
• 사람은 어떤 한계를 요구사항으로 볼지, 더 저렴한 단계가 품질을 얼마나 낮춰도 되는지, 프로젝트 한도를 넘는 지출을 허용할지 결정한다. 에이전트는 실험군을 시작할 수 있지만 지출을 승인할 수는 없다.

판정은 측정에 사용한 사례·검사·버전에만 해당한다. 미래의 모든 출력에 대한 보증이 아니라 의사결정을 위한 근거다. AQVEN과 함께하는 하루와 에이전트가 조사 절차를 진행하는 방법에서 더 자세히 설명한다.

구성 요소와 적용 범위

AQVEN은 열 가지 노드 종류인 llm, code, tool, human, switch, parallel, map, loop, call, narrow를 타입이 지정된 그래프로 조합한다. 레코드·열거형·유니언·ID·값·미디어 타입을 지원하고 경계마다 검사한다. 선언되지 않은 필드를 모델이 반환할 수 없도록 한다. 흐름과 노드와 타입 안내에서 설명한다.

프롬프트는 일반 텍스트, 공유 조각을 포함한 Liquid 템플릿, 또는 Python 함수로 작성할 수 있다. YAML 안에 문자열로 넣지 않고 항상 별도 파일로 둔다. 에이전트는 설정과 출력 모드를 포함한 모델을 별도 파일로 정의한다. Pydantic AI를 통한 제공자 목록에는 OpenAI, Anthropic, Google, OpenRouter, Mistral, DeepSeek, Groq, Ollama 등을 포함해 28개 항목이 있다. 자세한 내용은 프롬프트 단계와 모델 제공자 연동을 참조한다.

도구는 Python 함수나 MCP 서버로 연결하며 read, write, external 효과를 선언한다. 사람 검토 단계는 제한 시간과 기본값을 지정해 사람의 응답을 기다린다. 사례 데이터셋은 기대 출력이 있는 태그 지정 사례로 구성되며, 각 사례 이름의 해시를 기준으로 작업용과 보류용 절반으로 나뉜다. 실험은 데이터를 보기 전에 질문을 기록하고, 여러 변형과 사례에 걸쳐 실험군이 답을 찾는다. 보류 사례에서 나온 판정은 FINDINGS.md에 기록된다. 관련 문서는 도구 노드, 사람 검토 노드, 데이터셋, 실험과 결과에서 확인할 수 있다.

실행은 충돌 뒤에도 중단 지점부터 재개된다. 로컬 브라우저 앱인 Studio에서는 Flow 화면으로 워크플로 그래프·실행·사례를 보고, Research 화면으로 실험과 실험군을 확인하며 탐색 또는 확인 실험을 시작한다. Studio 채팅에서 쓰는 것과 같은 도구를 MCP 서버가 제공한다. 여기에는 여러 파일을 수정하는 flow_patch, aqven_check, prompt_preview, run_start, series_start 등이 있다. 충돌 후 실행 재개, Studio, MCP 서버 문서를 참고할 수 있다.

AQVEN이 적합하지 않은 경우도 명시돼 있다. 프롬프트 하나로 모델을 한 번 호출하는 경우에는 모델 SDK를 직접 쓰는 편이 낫다. 기존 앱을 추적하는 도구가 필요하다면 AQVEN은 자체 파일로 작성된 워크플로를 실행하므로 추적 도구가 더 적합하다. 팀을 위한 호스팅 서비스가 필요할 때도 AQVEN은 사용자 기기에서 로컬로 실행되므로 맞지 않는다. Python 3.14를 실행할 수 없거나 OSI 승인 오픈소스 라이선스가 필요한 경우에도 적합하지 않다.

저장소는 추적 도구와 시각적 빌더, AQVEN의 차이를 다음 기준으로 비교한다.

추적 도구의 예로 Langfuse, LangSmith, Arize Phoenix를, 시각적 빌더의 예로 n8n, Dify, Flowise를 든다.

기반 기술과 라이선스

모델 호출에는 Pydantic AI, SQLite를 이용한 실행별 체크포인트에는 DBOS, MCP 제공과 사용에는 공식 MCP Python SDK를 사용한다. FastAPI는 Studio와 API를 제공하고 python-liquid은 프롬프트 템플릿을 렌더링한다. AQVEN의 기반 기술 안내도 제공한다.

AQVEN은 AQVEN License 1.0.0에 따라 소스를 공개하지만 오픈소스는 아니다. 이 라이선스는 PolyForm Shield License 1.0.0을 바탕으로 한다. 상업 제품과 프로덕션을 포함해 어떤 목적으로든 사용할 수 있고, AQVEN으로 만든 워크플로는 사용자의 소유이며 판매도 허용된다. 반면 원본이나 수정본을 AQVEN과 경쟁하는 제품 제공에 사용할 수 없다. AQVEN 자체를 재배포할 때는 무료·비상업적 목적이어야 하며, AQVEN 자체를 판매할 권리는 라이선스 제공자에게 남는다. 저작권자는 Kirill Burkhanov다. 전체 조건은 LICENSE에서 확인할 수 있다.

FAQ에 따르면 계정이나 호스팅 서비스는 필요하지 않다. AQVEN은 로컬에서 실행되며 aqven check에는 모델 키와 네트워크가 필요 없지만 실제 실행에는 선택한 제공자의 키가 필요하다. Claude Code와 Codex는 Studio 채팅이나 터미널에서 사용할 수 있고, Cursor를 비롯한 다른 MCP 클라이언트도 MCP 서버를 통해 연결할 수 있다. 모델 제공자는 Pydantic AI를 거쳐 28개 항목을 제공한다.

AQVEN은 평가 라이브러리와도 차이가 있다고 설명한다. 평가 라이브러리는 보통 이미 있는 앱의 출력을 점수화한다. AQVEN은 실행 전 검사하는 타입 지정 파일로 워크플로 자체를 관리하고, 데이터를 보기 전에 실험 질문을 기록하며, 보류 사례에서 inconclusive 판정도 가능한 결과를 낸다. 기존 앱의 점수만 매기려는 경우에는 평가 라이브러리가 더 가벼운 선택이라고 안내한다. 버그와 제안은 GitHub Issues, 문서는 aqvenstudio.com에서 확인할 수 있다.