WaveSpeedAI
← 블로그

에이전틱 워크플로우 툴 연결: 패턴과 함정

에이전틱 워크플로우를 구축하고 있나요? 실패 원인은 거의 모델이 아닙니다. 실제 프로덕션 환경에서 툴 연결, 권한, 오케스트레이션이 어떻게 무너지는지 알아보세요.

9 min read
에이전틱 워크플로우 툴 연결: 패턴과 함정

지난 주에 시간을 세어봤다. 5일간의 스프린트 동안 에이전틱 파이프라인을 구성했는데 — 7개의 도구, 3개의 외부 API, 코드 샌드박스, 브라우저 자동화 레이어 — 디버깅에 약 14시간을 소비했다. 그 중 11시간이 와이어링에 쓰였다. 모델 때문이 아니었다. 프롬프트 때문도 아니었다. 모델이 도구를 호출하기로 결정한 순간과 그 도구가 실제로 올바른 동작을 수행하는 순간 사이의 공간 때문이었다.

팀 슬랙에서 누군가 내게 물었다. “Dora, 어려운 부분은 프롬프트 엔지니어링이 아니었어?” 8개월 전에는 그랬다. 이제 프롬프트는 오후 한나절이면 된다. 도구 디스패치, 인증 스코핑, 실제 부하 상황에서의 장애 복구를 올바르게 동작하게 만드는 데는 나머지 한 주가 걸린다.

당신의 에이전틱 시스템이 데모에서는 작동하지만 프로덕션에서는 망가지는 단계 — 도구가 조용히 타임아웃되고, 재시도 루프가 토큰 예산을 잡아먹고, 모델이 해석할 수 없는 권한 오류가 발생하는 — 에 있다면, 바로 그 단계가 와이어링이 실제 엔지니어링 문제가 되는 지점이다. 이 글은 해당 레이어에서 내가 겪은 패턴과 실패 모드, 그리고 시스템이 복구될지 스파이럴에 빠질지를 결정한 설계 결정들을 기록한 것이다.

도구 와이어링이 어려운 이유

모델은 거의 병목이 아니다. 내가 추적한 대부분의 프로덕션 장애는 LLM의 추론에서 시작되지 않는다. 모델이 도구를 호출하기로 결정한 이후 — 디스패치, 인증 핸드셰이크, 응답 파싱, 오류 처리 — 에서 시작된다. Anthropic의 효과적인 에이전트 구축에 관한 엔지니어링 가이드는 이 점을 명확히 한다: 증강된 LLM은 단지 하나의 빌딩 블록일 뿐이다. 힘든 작업은 그 주변의 모든 것이다.

에이전틱 시스템에서 “와이어링”이 실제로 의미하는 것. 도구 와이어링은 단순히 “API를 연결하는 것”이 아니다. 그것은 전체 표면이다: 도구가 어떻게 발견되는지, 모델에게 어떻게 설명되는지, 도구별로 권한이 어떻게 스코핑되는지, 응답이 컨텍스트 윈도우에 다시 피드백되기 전에 어떻게 검증되는지, 그리고 이러한 지점들에서의 실패가 세션을 중단시키지 않고 어떻게 처리되는지. Model Context Protocol 명세는 모든 팀이 이를 재발명하고 있었기 때문에 이 레이어 — 도구 발견, 호출, 결과 포맷팅 — 를 표준화하기 위해 특별히 설계되었다.

데모에서 프로덕션으로의 일반적인 오해. 데모에서는 세 개의 도구를 연결하고 모델이 올바르게 호출하면 마법처럼 느껴진다. 프로덕션에서는 15개의 도구가 있을 때 도구 설명들이 주의를 두고 경쟁한다는 것을 발견한다. 파라미터 스키마가 터무니없이 정확하지 않으면 모델이 인수를 환각한다는 것도. 프로토타입에서 시연한 “해피 패스”가 실제 호출의 약 40%만 커버한다는 것도. Anthropic의 에이전트를 위한 효과적인 도구 작성에 관한 최근 게시물은 도구 설명의 미묘한 변경만으로도 — Claude가 검색 쿼리에 “2025”를 추가했는지 여부처럼 — 성능이 의미 있게 저하될 수 있다는 것을 발견했다. 인터페이스 설계는 모델만큼이나 중요하다.

프로덕션 도구 오케스트레이션의 핵심 패턴

정적 vs. 동적 도구 표면. 정적 도구 표면은 모든 호출에서 모델이 동일한 도구 세트를 본다는 것을 의미한다. 단순하고, 예측 가능하며, 테스트하기 쉽다. 동적 표면은 세션 컨텍스트 — 사용자의 역할, 현재 워크플로우 단계, 이미 호출된 것 — 에 따라 도구가 로드, 필터링, 또는 생성된다는 것을 의미한다. 동적 표면은 더 유연하지만 디버깅이 훨씬 어렵다. 나는 하이브리드 방식을 사용하고 있다: 고정된 핵심 세트와 워크플로우 상태에 의해 게이팅된 조건부 도구들.

순차적 vs. 병렬 도구 디스패치. 순차적 디스패치는 간단하다 — 도구 A를 호출하고, 결과를 파싱하고, 도구 B를 호출한다. 대부분의 초기 에이전틱 시스템은 이런 방식으로 작동한다. 병렬 디스패치는 모델이 여러 도구 호출을 동시에 요청하며 지연 시간을 줄이지만 조정 복잡성을 도입한다. LangGraph의 오케스트레이션 프레임워크는 그래프 기반 상태 관리를 통해 두 패턴을 모두 지원하며, 실제 지연 시간의 차이는 상당하다 — 배치 작업에서 3-4배 속도 향상을 측정했다. 하지만 병렬 디스패치는 부분 실패도 처리해야 함을 의미한다: 도구 A는 성공하고 도구 B는 타임아웃될 때 어떻게 되는가?

도구 유형별 권한 게이팅. 모든 도구가 동일한 위험을 수반하지는 않는다. 읽기 전용 데이터베이스 쿼리는 파일을 삭제하거나 이메일을 보낼 수 있는 도구와 근본적으로 다르다. 나는 도구를 세 계층으로 분류한다: 읽기 전용(자동 승인), 롤백 가능한 쓰기(로깅됨, 감사와 함께 자동 승인), 그리고 파괴적/외부(명시적 확인 필요). NVIDIA AI Red Team이 발표한 샌드박싱을 위한 실용적인 보안 지침은 이를 잘 설명한다: 필수 제어는 네트워크 이그레스 제한과 워크스페이스 외부의 파일 쓰기 차단이다. 나머지는 부차적이다.

샌드박싱 및 격리 전략. 에이전트가 코드를 실행한다면 샌드박스가 필요하다. Docker 컨테이너가 아니라 — 컨테이너는 호스트 커널을 공유하며 신뢰할 수 없는 LLM 생성 코드에 대한 충분한 격리가 아니다. 프로덕션 옵션은 마이크로VM(Firecracker, Kata Containers), 시스콜 인터셉션을 위한 gVisor, 또는 신뢰된 코드 전용의 강화된 컨테이너다. 나는 대부분의 도구 실행에 gVisor를 사용한다. 오버헤드는 허용 가능하다. 대안 — LLM이 생성한 bash 명령이 마운트된 볼륨에서 rm -rf를 실행했다는 것을 발견하는 것 — 은 그렇지 않다.

예상해야 할 실패 모드

도구 호출 루프와 무한 위임. 가장 비용이 많이 드는 실패 패턴이다. 모델이 도구를 호출하고, 오류를 받고, 동일한 파라미터로 동일한 호출을 재시도하고, 동일한 오류를 받고, 다시 재시도한다. 제한된 재시도 예산 없이는 토큰 한도나 API 청구 임계값에 도달할 때까지 이것이 계속된다. 이것이 인증 실패에서 특히 많이 발생하는 것을 보았다 — 모델이 절대 성공하지 못할 무언가를 계속 재시도한다. 재시도 가능 vs. 재시도 불가능 오류의 분류와 함께 2-3회의 제한된 재시도 횟수가 최소 요건이다.

다운스트림 단계를 망가뜨리는 출력 잘림. 컨텍스트 윈도우를 초과하는 도구 응답은 조용히 잘린다. 그러면 모델은 불완전하다는 것을 모른 채 불완전한 데이터를 추론한다. 이것은 큰 결과 집합을 반환하는 데이터베이스 쿼리에서 특히 심각하다. 이제 나는 모든 도구 응답에 하드 토큰 제한을 적용한다 — 최대 25,000 토큰 — 결과가 잘릴 때는 명시적인 페이지네이션 신호와 함께.

세션 중 인증 만료. 장기 실행 에이전틱 세션은 OAuth 토큰 수명을 초과할 수 있다. 1분에는 도구가 잘 작동했다. 47분에는 토큰이 만료되었고, 이후의 모든 도구 호출이 실패한다. 모델은 이유를 알지 못한다. 아직 우아한 해결책이 있는지 모르겠다 — 현재 내 접근 방식은 디스패치 전에 토큰 만료를 사전에 확인하고 선제적으로 갱신하는 것이다.

가드레일 없는 파괴적 명령. 쉘 실행이나 파일 시스템 도구에 접근할 수 있는 모델은 가끔 파괴적인 명령을 생성할 수 있고 실제로 생성한다. 악의적으로가 아니라 — 단지 잘못되어서. AWS의 워크플로우 오케스트레이션 에이전트에 관한 규범적 지침은 워커 에이전트별로 실행 상태를 추적하고 프로덕션 시스템에 영향을 미치는 모든 것에 대해 승인 게이트를 구현할 것을 권장한다. 동의한다. 쓰기, 삭제, 또는 전송할 수 있는 모든 도구에는 명시적인 확인 단계가 있어야 한다.

도구 호출 전반에 걸친 속도 제한 캐스케이드. 하나의 도구가 속도 제한에 도달하면 모델은 즉시 다시 호출을 시도하는 경우가 많다. 또는 동일한 기반 API를 히트하는 다른 도구를 호출한다. 캐스케이드 효과는 몇 초 만에 모든 도구의 속도 제한을 포화시킬 수 있다. 도구 엔드포인트별 지터를 포함한 지수 백오프가 기준선이다 — 모델별이 아니라 도구별.

복구 및 복원력 패턴

지수 백오프를 사용한 재시도 로직. 1초에서 시작하여 재시도마다 두 배로 늘리고, 60초에서 상한을 두고, 무작위 지터를 추가한다. 이것은 선택 사항이 아니다. 지터 없이는 병렬 세션들이 동시에 재시도하여 천둥 무리 효과를 만든다. 먼저 오류를 분류한다: 속도 제한과 5xx 오류는 재시도된다. 인증 실패와 유효성 검사 오류는 그렇지 않다 — 잘못된 API 키는 아무리 재시도해도 수정되지 않는다. 일시적 오류에 대해 2-3회 재시도. 재시도 불가능한 오류에 대해 0회.

체크포인트 및 압축 전략. 여러 컨텍스트 윈도우에 걸쳐 작업하는 장기 실행 에이전트는 진행 상황을 지속하는 방법이 필요하다. Anthropic의 엔지니어링 팀은 장기 실행 에이전트를 위한 효과적인 하네스에 관한 작업에서 이를 문서화했다 — 핵심 통찰은 새로운 컨텍스트 윈도우가 이미 완료된 것을 빠르게 재구성할 수 있도록 git 히스토리와 함께 진행 파일을 사용하는 것이다. 비슷한 패턴을 적용했다: 압축 전에 에이전트는 완료된 단계, 보류 중인 단계, 알려진 실패를 요약하는 구조화된 체크포인트를 작성한다. 다음 컨텍스트 윈도우는 추측하는 대신 해당 파일을 읽는 것으로 시작한다.

도구를 사용할 수 없을 때의 우아한 성능 저하. 데이터베이스 커넥터가 다운되면 에이전트가 충돌해서는 안 된다. 실패를 인식하고, 해당 단계를 건너뛰고, 할 수 있는 것을 계속하거나 — 완료하지 못한 것을 사용자에게 알려야 한다. 이를 위해서는 전체 워크플로우의 하드 의존성이 되는 단일 도구가 없도록 도구 표면을 설계해야 한다. 폴백 체인이 도움이 된다: 기본 도구가 실패하면 더 저렴하거나 단순한 대안이 실행된다. 모델의 지시는 도구가 데이터를 반환하지 않을 때 수행할 작업을 명시적으로 다루어야 한다.

에이전틱 인프라 평가

직접 구축 vs. 구매: 언제 자체 하네스를 만들어야 하는가. 워크플로우가 예측 가능한 입력을 가진 3-4개의 도구로 이루어진 선형 체인이라면, 커스텀 하네스를 만드는 데 하루가 걸리며 프레임워크보다 유지 관리가 더 쉽다. 동적 라우팅, 병렬 디스패치, 세션 간 상태 지속성, 그리고 루프 내 인간 체크포인트가 필요하다면, 처음부터 구축하는 데 몇 달이 걸릴 것이다. 그때가 LangGraph나 관리형 플랫폼이 자리를 차지하는 때다. 나는 커스텀으로 시작했다. 세 번째로 상태 체크포인팅을 재구현한 후 마이그레이션했다.

프로덕션 준비성의 핵심 신호. 다음 질문들에 답할 수 있는가: 도구 호출이 타임아웃되면 어떻게 되는가? 도구 호출 로그는 어디에 저장되며 쿼리할 수 있는가? 유효한 JSON이지만 의미적으로 잘못된 도구 응답을 시스템이 어떻게 처리하는가? 체크포인트에서 실패한 세션을 재현할 수 있는가? 이러한 질문들 중 어느 것이라도 멈칫하게 만든다면, 시스템은 프로덕션 준비가 되지 않은 것이다.

스케일링 전에 벤치마킹해야 할 것. 부하 상황에서 도구 호출당 지연 시간. 도구 유형별 오류율. 세션당 토큰 소비량(도구 응답이 주요 원인). 현재 트래픽의 2배에서 속도 제한 여유. 나는 토큰 소비 지표를 몇 주 동안 무시했다가 실제로 측정했을 때 충격을 받았다 — 도구 응답이 총 토큰 지출의 60%를 차지했다.

FAQ

에이전틱 AI 시스템에서 도구 와이어링이란 무엇인가?

도구 와이어링은 LLM과 호출할 수 있는 외부 도구 사이의 전체 통합 레이어를 말한다 — 도구 발견, 스키마 정의, 권한 스코핑, 디스패치 로직, 응답 파싱, 오류 처리를 포함하여. 그것은 모델이 “함수를 호출하겠다”는 결정이 실제로 올바른 함수가 올바르게 호출되는 결과로 이어질지 결정하는 인프라다. Model Context Protocol은 다른 LLM 애플리케이션 전반에 걸쳐 이 레이어를 표준화하기 위해 만들어졌다.

에이전틱 워크플로우에서 파괴적 명령을 어떻게 방지하는가?

도구를 위험 수준별로 분류한다. 읽기 전용 작업은 자동으로 승인될 수 있다. 쓰기 작업은 롤백 기능과 함께 로깅되어야 한다. 파괴적 작업 — 데이터를 삭제하거나, 외부 통신을 보내거나, 프로덕션 상태를 수정하는 모든 것 — 은 명시적인 사람의 확인을 필요로 해야 한다. 이것을 샌드박싱(코드 실행을 위한 gVisor 또는 마이크로VM)과 기본적으로 임의의 아웃바운드 연결을 차단하는 네트워크 이그레스 제어와 결합한다.

프로덕션에서 도구 호출 실패를 처리하는 가장 좋은 방법은?

오류를 재시도 가능(속도 제한, 타임아웃, 5xx)과 재시도 불가능(인증 실패, 유효성 검사 오류, 권한 거부)으로 분류한다. 재시도 가능한 오류에는 2-3회 시도로 상한을 두고 지터를 포함한 지수 백오프를 적용한다. 재시도 불가능한 오류의 경우, 모델이 접근 방식을 조정하거나 — 사용자에게 에스컬레이션할 수 있도록 명확한 오류 메시지를 모델에 반환한다. 도구가 지속적으로 실패할 때를 감지하고 우회하는 회로 차단기를 레이어로 추가한다.

다중 도구 에이전트에서 권한 관리는 어떻게 작동하는가?

각 도구에는 정의된 권한 범위가 있어야 한다: 무엇에 접근할 수 있는지, 어떤 작업을 수행할 수 있는지, 어떤 데이터를 반환할 수 있는지. 프로덕션에서 이것은 세션별 단기 자격 증명(공유 서비스 키가 아닌), 디스패치 전 명시적 기능 확인, 그리고 모든 도구 호출에 대한 감사 로깅을 의미한다. 원칙은 최소 권한이다 — 텍스트 분석을 수행하는 에이전트는 파일 시스템에 대한 쓰기 권한이 필요하지 않다.

관리형 에이전틱 레이어 vs. 직접 구축을 언제 사용해야 하는가?

사용 사례가 예측 가능하고 순차적인 실행을 가진 다섯 개 미만의 도구를 포함한다면, 직접 구축하라 — 디버깅과 유지 관리가 더 빠르다. 동적 라우팅, 병렬 실행, 상태 지속성, 루프 내 인간 게이트, 또는 다중 에이전트 조정이 필요하게 되면, 커스텀 인프라를 구축하고 유지하는 엔지니어링 비용이 프레임워크의 학습 곡선을 능가한다. 결정 요인은 보통 상태 관리다: 세션이 프로세스 재시작에서 살아남아야 하면 스크립트가 아닌 인프라가 필요하다.

아직도 권한 게이팅 모델을 조정하고 있다. 세 계층으로는 충분히 세분화되지 않을 수 있다 — 일부 쓰기 작업은 자동 승인되어야 할 것 같고(로그 파일에 추가하기) 다른 것들은 명확히 그렇지 않다(고객 레코드 업데이트하기). 워크플로우가 더 복잡해짐에 따라 그 경계는 계속 변하고 있다. 더 많은 내용이 곧 올 것이다.

이전 게시물:

공유