모든 도구를 처음부터 주지 않으려면: Flue의 턴별 도구 구성과 상태·권한 경계
고객 지원 에이전트를 만든다고 가정해 보자. 주문 조회, 상담 이관, 환불 도구를 처음부터 모두 제공하면 모델은 어느 단계에서든 그 도구들을 선택할 수 있다. 반대로 조회 단계에는 조회 도구만 주고, 애플리케이션의 검증이 끝난 뒤 다음 모델 호출에 환불 도구를 구성한다면 작업 흐름을 더 명시적으로 표현할 수 있다. 다만 도구를 늦게 보여 주는 것과 환불 권한을 안전하게 확인하는 것은 서로 다른 문제다.
Flue를 읽을 때 유용한 질문은 “React처럼 생겼나?”보다 “다음 모델 호출에 무엇을 줄지 누가 결정하나?”다. 환불 필요성은 모델이 제안할 수 있지만, 환불 가능 여부와 고객·주문 범위는 애플리케이션이 확인해야 한다. 아래 흐름과 판단표는 공식 문서를 바탕으로 만든 설계 해설이며, 실제 환불·인증·장애 주입 시험을 수행한 결과가 아니다.
1. 매 턴 다시 만든다는 것은 모델 호출 직전의 구성이다
공식 Agents 문서는 에이전트 함수를 지시문을 반환하는 JavaScript 함수로 설명한다. 이 함수는 모델이 호출되기 직전에 다시 실행된다. 따라서 여기서 턴은 사용자 메시지 한 개와 항상 같은 단위가 아니다. 도구 실행 뒤 다음 모델 호출이 이어질 때도 현재 상태를 읽어 지시문과 선언된 자원을 구성하는 관점으로 이해해야 한다.
React 비유는 이 선언적 구성 방식에 관한 것이다. 화면의 DOM을 다시 그린다거나 모델을 다시 학습한다는 뜻이 아니며, 전체 프로세스와 외부 작업을 매번 초기화한다는 뜻도 아니다. Agent Hooks 문서는 React와 달리 자원 훅을 조건부로 추가하거나 제거할 수 있다고 명시한다. 어떤 도구를 사용할지 프롬프트에 부탁하는 대신, 해당 모델 호출에 제공되는 도구 집합 자체를 코드로 구성하는 셈이다.
현재 상태로 다음 호출의 자원을 구성한다. 프로세스 초기화나 모델 재학습을 뜻하지 않는다. 출처: flueframework.com/docs/guide/building-agents.
이 차이는 조회 단계에서 특히 선명하다. “아직 환불하지 마라”는 지시는 모델이 볼 수 있는 선택지에 행동 제한을 덧붙인다. 환불 도구를 구성하지 않는 방식은 그 호출의 선택지에서 환불을 뺀다. 그러나 다른 API 경로나 다른 자원 접근까지 차단하는 서비스 전체의 보안 보증은 아니다.
2. 저장한 상태와 신뢰할 수 있는 승인은 다르다
usePersistentState는 이름으로 구분되는 상태를 대화 저장소에 기록한다. 값은 JSON 직렬화가 가능해야 하며, 문서상 턴과 재시작을 넘어 읽을 수 있다. 다음 값이 이전 값에 의존한다면 렌더 시점 스냅샷으로 계산하기보다 최신 값을 받는 updater 함수를 쓰라는 권고도 있다. 이것은 상태 갱신의 일관성에 관한 설명이지, 상태를 만든 판단의 정확성을 보증하는 설명은 아니다.
이 지점에서 공식 예시 두 종류를 구분해야 한다. 훅 가이드의 상담 이관 예시는 모델이 호출한 도구가 escalated를 바꾸고 환불 도구를 여는 구성 패턴을 보여 준다. 이를 그대로 “인증 완료”로 해석하면 모델이 만든 상태를 사용자 권한처럼 취급하게 된다. 반면 Tools 문서의 Conditional tools 예시는 승인 코드를 애플리케이션의 검증 함수로 확인한 뒤 배포 도구를 연다. 전자는 단계 전환의 예시이고, 후자는 신뢰할 수 있는 검증을 경유하는 예시다.
모델이 만든 상태를 인증으로 취급하지 않는다. 도구 노출 조건과 실행 권한 검사는 따로 필요하다. 출처: flueframework.com/docs/guide/tools.
실무 설계에서는 “환불을 원함”, “정책상 환불 가능함”, “이 호출자가 이 주문에 접근할 수 있음”을 한 불리언에 섞지 않는 편이 해석하기 쉽다. 이는 이 글의 설계 제안이다. 도구 실행 시점에도 유효한 권한과 대상 자원을 확인하도록 두면, 도구가 노출된 뒤 권한이 달라지는 상황을 따로 다룰 수 있다. Flue가 이 검증을 모두 자동으로 해 준다는 주장은 아니다.
3. 고객은 신뢰한 코드가 고정하고, 모델은 그 범위 안에서 고른다
Tools 문서의 Protect access는 도구 인자가 모델이 선택한 입력이지 권한 경계가 아니라고 명시한다. 예를 들어 customerId와 orderId를 모두 모델 입력으로 받으면 모델이 어느 고객의 주문을 조회할지도 고르게 된다. 문서의 대안은 애플리케이션이 확인한 고객 식별자를 전달 신호의 속성에 넣고, 도구가 그 값을 읽도록 묶는 패턴이다. 모델은 주문 식별자만 선택한다.
여기서도 식별자에 값을 넣었다는 사실만으로 신뢰가 생기지는 않는다. 라우트나 dispatch를 호출하는 코드가 먼저 호출자를 검증해야 한다. 이후 주문 조회 코드가 그 고객에게 속한 주문인지 확인해야 한다. 따라서 도구 미노출, 신뢰한 고객 범위, 실제 주문 접근 검사는 서로 보완하는 경계이지 대체재가 아니다.
다음 표는 지원 에이전트에 무엇을 맡길지 정할 때 쓸 수 있는 편집상 판단 도구다. 제품의 검증 결과표가 아니라 공식 설명에서 도출한 책임 분리표다.
| 상황 | 모델이 제안·선택할 부분 | 애플리케이션이 확인할 부분 | 다음 모델 호출의 도구 구성 |
|---|---|---|---|
| 고객이 배송 상태를 묻는다 | 허용된 고객 범위 안의 주문 선택 | 호출자와 고객 연결, 주문 소유 범위 | 조회 중심으로 구성 |
| 고객이 환불을 요청한다 | 요청 의도와 추가 정보 필요성 | 환불 정책과 대상 주문, 유효한 승인 | 검증 전에는 환불 실행을 제공하지 않음 |
| 검증된 승인이 들어온다 | 허용된 작업의 매개변수 선택 | 승인 대상·범위와 현재 유효성 | 검증 결과에 따라 필요한 도구 구성 |
| 환불 중 프로세스가 멈춘다 | 상황 설명과 후속 조치 제안 | 외부 처리 결과 조회, 중복 방지 식별자 | 확인 없이 새 환불을 반복하지 않음 |
고객 식별자는 호출자를 검증한 코드가 묶고, 주문 선택은 그 범위 안에 둔다. 소유권 검사는 여전히 필요하다. 출처: flueframework.com/docs/guide/tools.
이 표에서 중요한 변화는 도구 수가 줄었다는 사실 자체가 아니다. 모델이 자유롭게 고를 입력과 애플리케이션만 정할 수 있는 범위를 분리했다는 점이다. 저장된 대화 상태에 “승인됨”이 있더라도 그 승인에 어떤 고객·작업·기간이 대응하는지 설명할 수 없다면, 조건부 도구 구성만으로는 빈틈을 메우지 못한다.
4. 도구가 바뀌면 캐시 비용도 달라질 수 있다
도구를 필요할 때만 주면 무조건 저렴해질 것이라고 단정하기 쉽다. 그러나 Tools 문서는 도구 목록 변경이 제공자의 tools 배열을 바꾸고 프롬프트 캐시를 무효화할 수 있다고 경고한다. 상태가 자주 바뀌는 조건에 도구를 묶을지, 큰 작업 단계가 바뀔 때만 묶을지는 비용 측면에서도 따로 판단할 문제다.
문서에는 완료된 도구 호출로 새 도구가 열리는 경우의 캐시 예외도 있다. 이 설명은 문서가 지칭하는 Anthropic 모델 중 Haiku를 제외한 조건에 한정된다. 모든 모델·제공자가 캐시를 유지한다는 보장이나 보편적인 비용 절감률로 확장하면 안 된다. 이 글은 토큰 비용을 측정하지 않았다. 먼저 단계별 구성의 필요성을 판단하고, 실제 제공자와 작업 흐름에서 캐시 동작을 확인하는 것이 도입 순서다.
5. 상태 복구는 외부 효과의 정확히 한 번 실행과 다르다
도구 노출을 좁혔더라도 환불이나 배포가 중간에 끊기면 별도의 문제가 남는다. Tools 문서에 따르면 실행 중이던 일반 도구는 프로세스 중단 뒤 자동 재실행되지 않으며 결과 불명 오류로 끝날 수 있다. 이미 외부 효과가 일어났는지 런타임이 알 수 없기 때문이다. 결과 불명은 실패 확정과 같지 않다.
durable: true인 도구는 step.do(name, fn)으로 단계의 결과를 기록한다. 중단 복구 시 완료 기록이 있는 단계는 기록값을 재사용한다. 하지만 외부 효과가 완료된 순간과 완료 기록이 저장된 순간 사이에 충돌하면 그 단계가 다시 실행될 수 있다. 문서 표현은 “exactly-once-recorded, at-least-once-executed”다. 기록을 한 번 남기는 성질을 외부 결제·환불이 정확히 한 번만 실행된다는 보장으로 바꾸면 안 된다.
완료 기록은 재사용되지만 기록 전 중단은 재실행될 수 있다. 외부 효과에는 개별 멱등성 설계가 필요하다. 출처: flueframework.com/docs/guide/tools.
따라서 이 글의 환불 예시에 적용한다면 외부 서비스의 멱등성 기능이나 처리 결과 조회 같은 별도 설계를 검토해야 한다. 여기서는 실제 환불 API의 지원 기능을 확인하거나 테스트하지 않았으므로 구체적인 키 형식이나 구현을 제시하지 않는다. 또한 단계 기록은 한 도구 호출 범위에 속한다. 모델이 도구를 새로 호출하면 단계가 새로 실행되며, 일반적인 throw는 중단 복구가 아니어서 문서상 자동 재시도되지 않는다.
6. 도입 판단: 도구 수보다 책임의 위치를 먼저 정한다
조회와 실행의 경계가 분명하고, 단계별로 필요한 도구가 달라지는 에이전트라면 Flue의 구성 방식은 검토할 만하다. 반대로 도구 목록이 거의 고정된 작은 작업에서는 동적 구성이 반드시 이득이라고 말할 근거가 없다. 특히 승인 상태의 출처가 불명확하거나 외부 작업의 중복 방지가 해결되지 않았다면, 도구를 조건부로 숨겼다는 이유만으로 안전한 운영 준비가 끝난 것은 아니다.
이 글의 결론은 세 경계를 분리하는 것이다. 다음 모델 호출의 선택지는 훅으로 구성하고, 자원 접근 권한은 신뢰한 애플리케이션 코드로 확인하며, 외부 부작용의 중복은 별도의 멱등성·결과 확인 설계로 다룬다. 세 경계가 각각 설명될 때 “필요한 도구만 준다”는 표현이 구체적인 운영 설계가 된다.
읽은 자료와 시점
Flue 2.0의 훅 기반 구조 변경 발표일은 2026년 7월 31일이다. 이 글은 2026년 10월 27일 수집·고정한 공식 문서 본문을 해설한 것으로, 현재 최신 버전이 2.0이라고 주장하지 않으며 현재 문서의 모든 세부 동작을 최초 발표 당시 기능으로 소급하지 않는다. 제품 성능·안전성·호스팅 비용의 독립 비교 실험도 아니다.
댓글
댓글 쓰기