Haystack 3.0: 훅·스킬·비동기 파이프라인으로 프로덕션 에이전트 프레임워크를 다시 짠 방식

왜 지금 봐야 하나

Haystack 3.0은 2026년 7월 20일에 공개됐다. 이번 릴리스가 중요한 이유는 새 모델 커넥터를 몇 개 더 붙인 정도가 아니라, 에이전트 프레임워크의 운영 경계 세 가지를 한 번에 다시 정했기 때문이다.

• 툴 실행은 더 이상 ToolInvoker 같은 별도 컴포넌트가 아니라 Agent가 직접 소유한다.
• 많은 스킬과 긴 툴 결과를 프롬프트에 그대로 싣지 않고, progressive disclosure와 tool result offload로 컨텍스트를 제어한다.
• AsyncPipeline을 없애고 Pipeline 하나로 run / run_async / stream을 정리하면서, 수명주기(warm_up / close)도 같이 통일했다.
• YAML 기반 파이프라인 로딩은 이제 trusted-module allowlist 뒤로 들어갔다. 즉, 편의보다 신뢰 경계를 먼저 보겠다는 선언이다.
• 코어는 가벼워졌지만, 그 대가로 외부 integration 패키지와 import migration을 직접 관리해야 한다.

에이전트 런타임을 직접 운영하는 팀에게 이 변화는 “새 기능이 생겼다”보다 “어디까지를 core로 믿고, 어디서부터는 명시적으로 묶을지 바뀌었다”에 가깝다.

핵심 변화 한눈에 보기

Haystack 3.0이 다시 그은 세 경계

1. ToolInvoker가 사라지면서 Agent가 진짜 제어면이 됐다

Haystack 2.x에서는 툴 호출을 별도 컴포넌트로 두고 LLM 결과를 그쪽으로 넘기는 사고방식이 남아 있었다. 3.0의 migration guide는 이 점을 명확히 끊는다. ToolInvoker는 제거됐고, tool execution은 Agent가 직접 소유한다.

이 변화가 중요한 이유는 단순한 import 변경이 아니기 때문이다.

• 툴 정의 전달
• tool call 실행
• 결과를 대화에 다시 붙이는 루프
• sync / async 실행 경로
• warm-up
• tracing
• exit condition 판단

이제 이 여섯 가지가 한 객체 안에 모인다.

run metadata가 public surface로 올라왔다

Agent 소스는 step_count, token_usage, tool_call_counts를 예약된 run metadata state로 둔다. 또 step 실행은 haystack.agent.step span 아래에서 LLM 호출과 tool 실행을 나눠 기록한다. 이건 observability에 직접적인 의미가 있다.

• 무한 tool loop 감지: tool_call_counts가 일정 임계치를 넘으면 훅에서 강제로 다른 행동을 시킬 수 있다.
• 비용 가드레일: token_usage를 보고 특정 step 이후 cheaper path로 바꾸는 로직을 훅으로 넣을 수 있다.
• 실행 감사: step span 안에 .llm / tool 실행 흐름이 분리되므로, 한 번의 agent run에서 어디가 병목인지 추적하기 쉬워진다.

즉, 3.0의 Agent는 단순 채팅 루프가 아니라 상태를 가진 workflow runtime 쪽으로 가까워졌다.

Human-in-the-Loop도 별도 특례가 아니라 훅으로 흡수됐다

기존의 confirmation 전략은 독자 표면을 가졌지만, 3.0에서는 ConfirmationHook을 before_tool에 거는 식으로 정리됐다. 이 설계가 좋은 이유는 “사람 승인”을 특례로 다루지 않고, 도구 실행 직전의 개입 지점이라는 일반 규칙으로 끌어올렸기 때문이다.

운영 측면에서 얻는 장점은 분명하다.

1. tool 승인, 수정, 거부가 다른 훅들과 같은 모델로 표현된다.
2. request-scoped resource는 hook_context로 흘려보내면 된다.
3. 승인 로직을 별도 제어면으로 취급하지 않아도 된다.

하지만 tradeoff도 있다.

• 기존 confirmation 코드를 그대로 복붙하면 안 된다. 이제 전략이 보는 값은 “모델이 요청한 tool args”이고, state에서 주입되는 값은 실행 직전에만 붙는다.
• 즉, 승인 UI가 state-injected 값을 전제로 설명 문구를 만들고 있었다면 바꿔야 한다.

2. 스킬과 긴 툴 결과를 프롬프트에 전부 싣지 않는 방향으로 갔다

Haystack 3.0의 진짜 실용 변화는 agent control plane만이 아니다. 컨텍스트 예산을 다루는 방식도 꽤 크게 바뀌었다.

SkillToolset: 이름과 설명만 먼저 노출하는 progressive disclosure

SkillToolset은 warm-up 시점에 skill store를 스캔해 스킬 이름과 한 줄 설명만 load_skill tool 설명에 baked-in 한다. 모델은 일단 어떤 스킬이 있는지만 보고, 필요할 때 load_skill로 본문을 불러온다.

이 구조는 두 가지를 동시에 노린다.

• 시스템 프롬프트에 거대한 instruction blob를 미리 넣지 않는다.
• 스킬 개수가 많아져도, 실제로 읽는 것은 현재 작업에 필요한 것만 남긴다.

이건 운영자에게 중요한 신호다. 앞으로는 “에이전트가 어떤 문서를 볼 수 있나”만이 아니라, 그 문서를 어떤 단계에서 context로 올릴지까지 설계 대상으로 봐야 한다.

ToolResultOffloadHook: 큰 결과는 store에 내리고 포인터만 남긴다

ToolResultOffloadHook은 after_tool에서 동작하면서 긴 텍스트 결과를 store에 쓰고, 대화에는 preview + reference만 남긴다. 소스를 보면 이 훅은 특히 multi-user 환경을 꽤 의식한다.

• 기본 store는 hook 생성 시 주입하지만,
• 각 run은 hook_context["tool_result_store"]로 별도 store를 덮어쓸 수 있고,
• 문서에도 세션별 store를 분리하지 않으면 사용자 간 충돌이나 result leakage가 날 수 있다고 적어 두었다.

즉, 이 기능은 단순한 token-saving trick이 아니다. tool 결과를 conversation에서 분리하는 저장 경계를 새로 만드는 기능이다.

여기서 바로 생기는 운영 규칙

3. Pipeline 하나로 sync/async를 통일했지만, 의미까지 같아진 것은 아니다

AsyncPipeline 제거는 표면만 보면 단순하다. 하지만 실무에서는 오히려 어느 경로가 concurrent이고 어느 경로가 sequential인지 더 엄격하게 구분해야 한다는 뜻이다.

바뀐 점은 명확하다

• Pipeline.run()은 동기 실행
• Pipeline.run_async() / run_async_generator() / stream()은 비동기/스트리밍 실행
• AsyncPipeline.run()이 event loop 안에서 터지던 오래된 혼선이 줄어든다

그런데 운영자는 이 차이를 의식해야 한다

migration guide는 매우 노골적으로 적어 둔다.

• Pipeline.run은 sequential이며 concurrency_limit를 받지 않는다.
• concurrent 실행은 run_async / run_async_generator 경로에서만 된다.
• Pipeline.run()은 event loop 안에서 예외를 던지지 않고, 그냥 loop를 block한다.

즉, 2.x에서 “sync처럼 보이지만 사실 async engine wrapper였던” 감각으로 코드를 쓰던 팀은 3.0에서 행동을 다시 정리해야 한다.

warm_up / close가 중요해진 이유

같은 문서에서 OpenAI/Azure OpenAI 계열 컴포넌트는 외부 리소스를 __init__이 아니라 warm_up()에서 만들도록 바뀌었다고 설명한다. 이건 사소한 변경처럼 보여도, long-running service 운영에는 꽤 중요하다.

• 생성자 단계에서 실패하던 API key 누락이 이제 warm-up/first-run으로 이동한다.
• 리소스 획득과 해제를 warm_up / close로 맞추면, 서비스 프로세스 수명주기와 component 수명주기를 맞추기 쉽다.
• connection, GPU memory, file handle 같은 자원이 어디서 잡히고 풀리는지 더 명확해진다.

이건 프레임워크가 “노트북용 utility”보다 서버에 오래 떠 있는 런타임 쪽으로 설계를 돌렸다는 신호다.

4. 3.0은 pipeline YAML을 더 이상 무해한 설정 파일로 취급하지 않는다

가장 운영자다운 변화는 deserialization allowlist다. 이제 Pipeline.load, Pipeline.loads, Pipeline.from_dict는 신뢰된 모듈 목록 밖의 클래스를 로드하지 않는다.

기본 allowlist는 제한적이다.

• haystack
• haystack_integrations
• haystack_experimental
• builtins
• typing
• collections

그리고 builtins가 allowlist에 들어 있어도 eval, exec, open, getattr, __import__ 같은 위험 builtin은 별도 denylist로 막는다.

왜 이게 중요하나

이전에는 pipeline YAML이 사실상 임의 import를 유도할 수 있는 실행 artifact였다. 3.0은 이 사실을 더 숨기지 않는다. 그래서 운영 절차도 바뀌어야 한다.

1. 커스텀 컴포넌트를 쓰는 pipeline은 배포 문서에 allowlist 등록 절차를 적는다.
2. unsafe=True는 “빨리 되게 만드는 옵션”이 아니라 신뢰 우회라는 의미로 취급한다.
3. pipeline 저장소와 코드 저장소를 분리해 관리했다면, 이제는 YAML provenance도 같이 관리해야 한다.

실제로 해야 할 선택

5. 코어는 가벼워졌지만 업그레이드 조각은 늘었다

3.0은 haystack-core-integrations 쪽으로 많은 컴포넌트를 밖으로 뺐다. 동시에 legacy generator들도 정리했다. 이건 방향 자체는 맞다. core 릴리스와 integration 릴리스를 분리하면, 작은 수정 때문에 코어 전체를 묶어서 배포하지 않아도 되기 때문이다.

하지만 업그레이드 관점에서는 귀찮은 일이 늘어난다.

가장 먼저 부딪히는 변화

• SentenceTransformers*, HuggingFaceAPI*, Whisper, Tika, OpenAPI connector, tracing connector 등은 별도 패키지 설치와 import 변경이 필요하다.
• OpenAIGenerator, AzureOpenAIGenerator, HuggingFaceAPIGenerator, HuggingFaceLocalGenerator는 제거됐다.
• ChatGenerator는 str 입력도 받아 주기 때문에 migration 자체는 쉬워졌지만, 출력은 ChatMessage가 되므로 metadata 소비 지점은 다시 봐야 한다.

그래서 upgrade PR에서는 무엇을 꼭 봐야 하나

1. requirements / pyproject.toml에 integration package가 빠지지 않았는가
2. import path만 바꾸고 실제 runtime dependency 설치는 놓치지 않았는가
3. pipeline output에서 meta를 별도 socket으로 기대하는 코드가 남아 있지 않은가
4. Document.id를 auto-generated 값으로 저장소 키처럼 쓰고 있었다면, non-empty meta가 있는 문서 재적재 계획이 있는가

여기서 중요한 건, 3.0의 core slimming이 성능 최적화가 아니라 릴리스 독립성과 의존성 경계 정리라는 점이다. 그러니 도입 검증도 benchmark보다 package graph와 import audit을 먼저 보는 편이 맞다.

도입 전에 해볼 검증 체크리스트

1) Agent 제어면 검증

• ToolInvoker 기반 코드가 남아 있지 않은지 grep
• Agent 훅에서 before_tool / after_tool / on_exit가 기대한 순서로 실행되는지 테스트
• tool_call_counts와 token_usage를 읽는 가드레일 로직이 있으면 smoke test 추가

2) 컨텍스트/스토어 검증

• SkillToolset이 실제로 스킬 본문을 lazy load하는지 확인
• ToolResultOffloadHook를 쓴다면 per-request store를 hook_context로 주입하는지 점검
• 긴 텍스트 결과가 pointer로 치환된 뒤도 agent 품질이 유지되는지 회귀 테스트

3) Pipeline 실행 검증

• sync 코드에서 정말 sequential이면 충분한지
• async 서버(FastAPI, notebook, worker)에서는 run_async로 바뀌었는지
• warm_up() 시점의 secret/credential 누락이 배포 시나리오와 맞는지

4) 신뢰/패키지 검증

• 배포에 필요한 custom component 모듈이 allowlist에 들어 있는지
• unsafe=True가 어디에 남아 있는지 코드 검색
• integration package 설치 누락이 없는지 fresh environment에서 재현

이 릴리스에서 특히 조심할 한계

• SkillToolset은 설명 품질이 낮으면 progressive disclosure가 아니라 나쁜 tool discovery가 된다.
• ToolResultOffloadHook는 text 중심이다. 이미지/파일 흐름까지 자동으로 정리해 줄 것이라고 기대하면 안 된다.
• Pipeline.run()은 event loop 안에서 조용히 block할 수 있다. “예외가 안 났으니 괜찮다”가 아니다.
• deserialization allowlist는 좋아졌지만 unsafe=True는 여전히 강력하다. 내부 도구에서 관성적으로 붙이면 3.0의 안전장치를 스스로 해제하는 셈이다.

결국 Haystack 3.0의 핵심은 agent feature를 더 얹은 것이 아니라, 에이전트를 운영하는 사람이 어디서 개입하고 어디를 신뢰해야 하는지 코어 표면에서 강제하기 시작했다는 데 있다. 그래서 이 버전의 평가는 “에이전트가 더 잘 답하나”보다, “우리 시스템이 더 예측 가능하게 동작하나”에 먼저 두는 편이 맞다.

References

• Haystack v3.0.0 release note (2026-07-20)
• Haystack Migration Guide for v3.0
• Tagged source: MIGRATION.md in v3.0.0
• Tagged source: haystack/components/agents/agent.py (step_count, token_usage, tool_call_counts, haystack.agent.step)
• Tagged source: Agent._run_step and async path
• Tagged source: haystack/tools/skills/skill_toolset.py
• Tagged source: haystack/hooks/human_in_the_loop/hooks.py
• Tagged source: haystack/hooks/tool_result_offloading/hooks.py
• Tagged source: haystack/core/serialization_security.py
• Haystack docs: Agents