도구 호출 뒤 문장이 깨진 이유: Pydantic AI 2.43의 스트림 경계 수정

정상 응답인데 프런트엔드가 멈췄다

LLM이 텍스트를 보내다가 도구를 호출하고, 같은 응답에서 다시 텍스트를 이어 보내는 흐름은 이상하지 않다. 문제는 화면으로 전달되는 이벤트의 수명주기가 어긋날 때 생긴다. Pydantic AI 이슈 #8208의 재현 순서는 text → tool call → text였다. 모델과 도구는 정상 동작했지만 Vercel AI SDK v6 어댑터는 두 번째 텍스트를 이미 끝난 텍스트 조각의 delta로 내보냈다. 프런트엔드는 열린 적이 없거나 이미 닫힌 ID에 delta가 왔다며 오류를 냈다.

이 결함은 2026년 9월 12일 00:54 UTC에 공개된 Pydantic AI 2.43.0에서 수정됐다. 릴리스 노트에는 OpenAIChatModel이 도구 호출 뒤 텍스트 경계를 보존한다고 적혀 있다. 짧은 한 줄이지만, 에이전트 스트리밍을 운영하는 쪽에서는 꽤 구체적인 계약 변경이다. 토큰 문자열만 순서대로 전달하면 되는 것이 아니라, 각 조각의 시작과 delta, 끝이 올바른 ID로 닫혀야 한다.

텍스트 조각 0이 끝난 뒤 도구 조각 1이 시작됐지만 후속 delta가 닫힌 index 0을 다시 가리켜 UI 오류가 나는 이벤트 순서

그림 1. 문자열 순서가 맞아도 닫힌 text part ID에 delta가 오면 UI stream protocol은 실패한다. 출처: github.com/pydantic/pydantic-ai/issues/8208.

고정된 content ID가 오래 살아남았다

2.42 이전 코드의 핵심 문제는 단순했다. OpenAIStreamedResponse._map_text_delta가 모든 텍스트 delta에 같은 vendor part ID인 content를 썼다. 첫 텍스트가 시작될 때는 맞는 선택이다. 하지만 도구 조각이 시작되면 상위 스트림은 앞선 텍스트 조각을 끝낸다. 그 뒤 도착한 텍스트까지 다시 content로 찾으면 parts manager는 이미 닫힌 첫 조각을 가리킨다.

이슈의 최소 재현에서는 이벤트가 PartStart(0) → PartEnd(0) → PartStart(1, tool) → PartDelta(0) 순으로 나왔다. 마지막 delta의 index 0은 앞에서 끝난 상태다. Vercel 어댑터가 이를 text-delta로 바꾸면서 화면 쪽 검사가 실패했다. 보고자는 OpenAI 호환 Qwen endpoint에서 현상을 봤지만, 공개 재현은 실제 provider cassette가 아니라 제어된 SSE 응답을 사용했다. 따라서 "모든 OpenAI 응답이 이 순서를 낸다"고 확대할 근거는 없다.

같은 text tool text SSE 입력에서 Pydantic AI 2.36은 닫힌 ID 0에 delta를 보냈고 2.43은 새 text 2를 시작한 대조

그림 2. 제어된 재실행에서 invalid delta index는 Pydantic AI 2.36.0의 0 한 건에서 2.43.0의 0건으로 바뀌었다. 출처: github.com/pydantic/pydantic-ai/pull/8235.

2.43은 ID를 무조건 바꾸지 않는다

PR #8235는 현재 텍스트용 _vendor_part_id 상태를 추가했다. 도구의 PartStartEvent가 들어오고, 그 ID가 지금 TextPart를 가리킬 때만 ID를 새 값으로 회전한다. 다음 텍스트는 새 ID로 시작하므로 닫힌 조각에 붙지 않는다. 반대로 도구가 없는 연속 텍스트는 한 조각으로 유지된다.

여기서 조건문이 중요하다. 생각 과정을 <think>...</think> 태그로 표현하는 OpenAI 호환 모델도 같은 텍스트 경로를 쓴다. 도구 호출이 왔다고 ID를 무조건 회전하면, 도구 뒤의 </think>가 앞선 ThinkingPart를 닫지 못하고 사용자에게 보이는 일반 텍스트로 샐 수 있다. 수정 코드는 현재 조각이 TextPart일 때만 회전한다. 새 회귀 테스트도 이 경우를 따로 확인한다.

Chat Completions의 과거 메시지는 assistant 메시지 하나에 content 문자열 하나를 둔다. Pydantic AI 내부에서 여러 TextPart로 나뉜 응답을 다시 과거 메시지로 보낼 때는 두 줄바꿈으로 합친다. 화면 스트림의 조각 경계와 다음 모델 요청의 문자열 표현은 같은 문제가 아니다. 이번 수정은 전자를 고치면서 후자의 기존 변환을 유지한다.

도구 PartStart가 들어왔을 때 현재 조각이 TextPart인 경우에만 새 text ID로 회전하고 ThinkingPart는 유지하는 조건 흐름

그림 3. 2.43.0은 현재 조각이 TextPart일 때만 ID를 회전해 닫힌 텍스트 재사용과 think 닫기 태그 노출을 함께 피한다. 출처: github.com/pydantic/pydantic-ai/blob/86b250f3d5e26f4cb25617a82904c720f690193d/pydantic_ai_slim/pydantic_ai/models/openai.py.

두 버전을 같은 입력으로 다시 돌려봤다

공개 이슈의 제어된 SSE 모양을 별도 임시 환경에서 재실행했다. Python 코드는 실제 자격 증명 없이 httpx2.MockTransport와 정규 도구 하나를 사용했다. Pydantic AI 2.36.0에서는 닫힌 index 0에 PartDeltaEvent가 다시 왔고, 검사 결과 invalid_delta_indices=[0]이었다. 같은 입력을 2.43.0에 넣자 텍스트 뒤 도구, 그 뒤 새 텍스트가 index 0, 1, 2로 각각 시작하고 끝났다. 닫힌 조각에 대한 delta는 0건이었다.

이 대조는 공개 이슈의 스트림 수명주기 결함과 2.43.0 수정 결과를 재현한다. 실제 Qwen 서비스나 브라우저 UI를 돌린 시험은 아니며, 네트워크 지연과 provider별 chunk 병합도 측정하지 않았다. 또 2.43.0 릴리스에는 다른 변경도 함께 들어갔다. 이 글의 결과를 릴리스 전체 안정성 평가로 읽으면 안 된다.

어댑터를 고칠 때 확인할 네 가지

첫째, 문자열 내용만 snapshot으로 비교하지 말고 조각별 상태 전이를 검사해야 한다. Vercel의 현재 AI SDK UI stream protocol 예시도 같은 ID에 대해 text-start, text-delta, text-end 순서를 명시한다. text-start 이전 delta, text-end 이후 delta, 중복 start를 모두 실패로 잡는 작은 상태 기계가 유용하다. 둘째, text → tool → text를 별도 fixture로 둔다. 보통의 text → tool 테스트는 후속 텍스트가 없어서 이 결함을 놓친다.

셋째, thinking 태그와 도구 호출을 같은 fixture에 넣어야 한다. 일반 텍스트 결함을 고친 패치가 생각 과정 닫기 태그를 화면에 노출할 수 있기 때문이다. 넷째, 내부 조각 경계와 대화 기록 직렬화를 나눠 검증해야 한다. UI에는 두 텍스트 조각이 필요해도 Chat Completions history에는 하나의 문자열로 합쳐질 수 있다.

버전 업그레이드가 당장 어렵다면 provider가 같은 응답에서 도구 뒤 텍스트를 보내는지 로그의 이벤트 종류와 ID만으로 먼저 확인할 수 있다. 원문이나 도구 인자를 통째로 남길 필요는 없다. 다만 애플리케이션에서 임의로 두 번째 텍스트를 버리는 우회는 결과 손실을 만들 수 있고, 닫힌 ID를 다시 여는 우회는 다른 SDK 계약을 깨뜨릴 수 있다. 가능한 해결은 2.43.0 이상으로 올린 뒤 해당 provider의 실제 chunk fixture를 추가하는 쪽이다.

작은 경계 하나가 에이전트 전체를 멈춘다

이번 결함은 모델 답변의 사실성이나 도구 실행 결과와 무관했다. 데이터 자체는 도착했는데, 스트림 조각의 ID가 잘못 재사용됐다. 에이전트 UI를 연결할 때는 토큰과 tool call만 세지 말고, 각 part의 시작과 종료도 외부 계약으로 다뤄야 한다.

Pydantic AI 2.43.0의 수정은 새 공개 API를 추가하지 않는다. 대신 이미 종료된 텍스트를 다시 쓰지 않는 규칙을 구현에 반영했다. 실무에서 챙길 결론도 소박하다. provider SDK, 에이전트 프레임워크, UI 어댑터 사이에는 문자열보다 긴 수명주기 계약이 있다. 그 계약은 도구 호출 앞뒤를 모두 넣은 테스트로만 보인다.

참고 자료

댓글

댓글 쓰기

이 블로그의 인기 게시물

체크아웃은 분리됐는데 Git 상태는 공유된다: Codex 0.154 worktree의 세 경계

이미지
1. --worktree 가 해결하는 충돌은 무엇인가 에이전트 두 개가 같은 저장소에서 동시에 파일을 고치면 가장 먼저 부딪히는 것은 모델이 아니다. 한쪽이 바꾼 작업 트리와 인덱스를 다른 쪽이 읽고, 테스트 산출물이 섞이고, 아직 정리하지 않은 변경을 다음 작업이 자기 입력으로 오해한다. OpenAI는 GitHub 기준 2026년 9월 9일 22:35 UTC, 한국 시각 10일 07:35에 공개한 Codex 0.154.0에 실험적 managed worktree 기능을 넣었다. 새 실행이나 기존 세션의 fork를 --worktree 로 시작할 수 있고, TUI에서는 /worktree 로 새 대화 또는 현재 대화의 fork를 별도 체크아웃에 둘 수 있다. 공식 릴리스 설명은 이를 "isolated checkouts"라고 부른다. 다만 이 표현을 저장소 전체와 외부 환경까지 격리한다는 뜻으로 읽으면 곤란하다. Git worktree가 분리하는 것은 체크아웃의 파일과 작업별 관리 상태다. Git 공식 문서에 따르면 연결된 worktree는 HEAD , index 같은 파일을 따로 갖지만 나머지 저장소 데이터는 공유한다. 따라서 같은 소스 파일을 동시에 편집하는 충돌은 줄일 수 있어도, 같은 원격 브랜치에 push하거나 같은 배포·테스트 데이터베이스를 건드리는 충돌까지 사라지지는 않는다. 그림 1. Codex 0.154 managed worktree는 체크아웃 생성과 thread 소유권을 연결한다. binding 전 실패 시 체크아웃을 보존한다. 출처: github.com/openai/codex/releases/tag/rust-v0.154.0 . 2. Codex는 새 체크아웃을 어떻게 만든다 0.154.0 태그가 가리키는 커밋의 codex-rs/worktree/src/lib.rs 를 보면 생성 순서가 꽤 보수적이다. 먼저 현재 HEAD 를 commit SHA로 확정한다. 그 SHA에서 git worktree add --detach --...
자세한 내용 보기

잠근 작업이 커밋 뒤 다시 나온다: PostgreSQL 에이전트 큐의 소유권 설계

이미지
1. 잠금은 작업을 소비했다는 기록이 아니다 에이전트 작업자를 여러 개 띄웠다. 각 작업자는 PostgreSQL에서 FOR UPDATE SKIP LOCKED 로 작업 하나를 가져온다. 다른 작업자가 잡은 행을 기다리지 않으니 병렬 처리도 잘되는 것처럼 보인다. 그런데 커밋한 뒤 같은 작업이 다시 나온다면 무엇이 빠진 걸까? 핵심은 행을 잠갔다는 사실과 작업을 맡았다는 상태가 서로 다르다 는 점이다. PostgreSQL 공식 문서는 행 잠금이 트랜잭션 종료 때 풀린다고 설명한다. SKIP LOCKED 는 지금 즉시 잠글 수 없는 행을 건너뛰는 옵션이지, 그 작업을 영구히 큐에서 제거하는 명령이 아니다. 공식 PostgreSQL 18.0 소스의 회귀 테스트에도 이 차이가 드러난다. 상태를 바꾸지 않고 조회만 하는 순서에서 세션 A가 작업 1을 잠그면 B는 작업 2를 받는다. A가 커밋한 뒤 B가 다시 조회하면 작업 1이 나온다. 프로젝트가 저장한 기대 출력과 별도로, 이번 글에서는 PostgreSQL 16.2의 격리된 로컬 DB 에서도 이 순서를 실제 확인했다. 문서와 고정 소스는 18 계열, 직접 실행한 엔진은 16.2다. 두 버전을 같은 실험으로 섞거나 최신 버전의 성능 측정이라고 부르지 않는다. 그림 1. 잠금이 해제돼도 작업 상태가 그대로면 같은 작업이 다시 선택된다. 공식 18.0 기대 출력과 별도 16.2 로컬 확인에 근거한 자체 도식. 출처: www.postgresql.org/docs/18/sql-select.html . 조회 결과가 0행일 때도 해석에 주의해야 한다. 모든 후보가 다른 작업자에게 잠겨 있으면 SKIP LOCKED 는 아무것도 반환하지 않을 수 있다. 로컬 확인에서는 일반 조회로 보이는 행이 2개인데 잠금 건너뛰기 조회는 0행이었다. 따라서 “지금 가져올 작업이 없다”와 “큐 자체가 비었다”는 같은 말이 아니다. 공식 문서 역시 이 옵션이 일반적인 일관된 조회에는 적합하지 않고, 큐와 비슷한 테이블의 여러 소비자 사이 경합을...
자세한 내용 보기

코딩 에이전트는 API 문서보다 AGENTS.md를 먼저 읽었다

이미지
코딩 에이전트를 위한 문서를 만든다고 하면 보통 API 레퍼런스나 상세한 개발 가이드부터 떠올린다. 그런데 실제 에이전트의 작업 기록을 분석한 연구에서는 다른 문서가 훨씬 자주 등장했다. AGENTS.md , CLAUDE.md 같은 지시 파일과 계획·작업 노트였다. 2026년 8월 공개된 논문 From Agent Behaviour to Agent-Friendly Documentation 은 공개된 코딩 에이전트 세션과 풀 리퀘스트를 이용해 에이전트가 어떤 문서를 읽고 쓰는지 조사했다. 연구진이 분석한 데이터는 다음과 같다. SWE-chat의 파싱 가능한 세션 557개 개발 이벤트 94,813개 문서 관련 이벤트 3,033개 AIDev의 에이전트 풀 리퀘스트 33,097개 파일·커밋 단위 변경 기록 690,260개 에이전트가 가장 자주 만진 문서 문서 상호작용에서 가장 큰 비중을 차지한 것은 에이전트 지시 파일이었다. 문서 유형 이벤트 수 비중 에이전트 지시 파일 1,074 35.4% 계획·작업 노트 760 25.1% 작업 및 요구사항 문서 301 9.9% 설정 문서 205 6.8% README 197 6.5% API 레퍼런스 40 1.3% 지시 파일과 작업 노트를 합하면 전체 문서 상호작용의 60.5%다. API 레퍼런스는 1.3%에 그쳤다. 지시 파일이 API 레퍼런스보다 약 27배 많이 관찰된 셈이다. 코딩 에이전트의 문서 관련 이벤트 분포. 지시 파일과 계획·작업 노트가 전체의 60.5%를 차지했다. 출처: Gao & Chen, arXiv:2608.20195v1 . 이 수치를 "API 문서는 필요 없다"고 해석하면 곤란하다. 연구가 추적한 것은 저장소 안에서 명시적으로 열린 파일이다. 웹 문서, 모델이 이미 학습한 지식, 코드 주석, 런타임이 자동으로 주입한 문맥은 잡히지 않는다. 정확한 결론은 코딩 에이전트가 저장소 안에서 작업할 ...
자세한 내용 보기