MCP를 쓰지 않았는데 mcp extra가 필요했다: Pydantic AI 2.43의 연산 식별 수정

1. 평범한 함수 도구가 선택 패키지 하나 때문에 멈췄다

Pydantic AI에서 Temporal durable execution을 쓰되 특정 도구만 activity 밖에서 실행하고 싶다면 도구 메타데이터에 temporal: False를 줄 수 있다. 비동기 함수 도구처럼 workflow 안에서 안전하게 실행할 수 있는 작업은 이 경로를 사용할 수 있다. 그런데 2.42.0에서는 MCP를 전혀 쓰지 않은 평범한 함수 도구도 선택 패키지인 mcp extra가 없으면 ImportError로 멈추는 사례가 나왔다.

이슈 #8249의 재현 환경은 Python 3.11.15와 pydantic-ai-slim[temporal] 2.42.0이다. 내장 TestModel과 함수 도구만 사용하므로 외부 모델 SDK도 필요 없다. 문제는 도구가 실행된 뒤가 아니라, activity opt-out 설정을 해석하는 도중 발생했다. 사용자가 선택하지 않은 기능의 import가 공통 분기 안에 숨어 있었던 셈이다.

이 버그는 단순한 의존성 누락으로만 보면 놓치는 부분이 있다. mcp extra를 추가하면 첫 증상은 사라지지만, 실행 경계의 종류를 Python 객체 타입으로 판정하는 설계는 그대로 남는다. Pydantic AI 2.43.0은 import를 조건부로 감싸는 대신, durable operation을 만들 때 이미 기록한 toolset_kind를 사용하도록 바꿨다.

일반 함수 도구가 Pydantic AI 2.42.0의 공통 Temporal opt-out 분기를 지나 MCP import 때문에 extra 미설치 시 실패하는 흐름

그림 1. 현재 도구가 MCP인지 확인하기 전에 선택 기능 import가 먼저 실행돼 일반 함수 경로까지 막았다. 출처: github.com/pydantic/pydantic-ai/blob/v2.42.0/pydantic_ai_slim/pydantic_ai/durable_exec/temporal/_durability.py.

2. 2.42.0은 왜 모든 opt-out 도구에서 MCP를 불러왔나

2.42.0의 _resolve_temporal_tool_config()는 먼저 도구별 activity 설정을 계산한다. 결과가 False이면 activity를 사용하지 않겠다는 뜻이다. 바로 이 분기 첫 줄에 from pydantic_ai.mcp import MCPToolset이 있었다. 뒤에서 현재 도구가 MCP인지 검사하려고 불러온 타입이지만, Python import는 검사보다 먼저 실행된다.

따라서 현재 도구가 일반 FunctionToolset에 속하더라도 mcp extra가 없으면 분기 초입에서 실패한다. 코드가 알고 싶었던 것은 "이 연산이 MCP 도구 호출인가"였지만, 확인 방식 때문에 "MCP 모듈을 지금 import할 수 있는가"가 선행 조건이 됐다. 기능 판정과 설치 상태가 뜻하지 않게 묶였다.

단순한 try/except ImportError는 첫 사례를 막을 수 있다. 실제로 PR 설명에는 이전 시도 #8255가 이런 접근을 썼다고 적혀 있다. 하지만 그러면 두 번째 문제가 남는다. 도구를 감싸는 wrapper가 있으면 현재 보이는 객체 타입과 실제 durable operation의 종류가 달라질 수 있다.

3. wrapper는 객체의 겉모양을 바꾸지만 연산의 기원은 바꾸지 않는다

PrefixedToolset은 도구 이름 앞에 접두사를 붙이는 wrapper다. 이 wrapper를 통과한 MCP 도구의 tool.toolset은 원래 MCPToolset이 아니라 wrapper를 가리킬 수 있다. 2.42.0의 isinstance(tool.toolset, MCPToolset) 검사는 이런 도구를 MCP로 알아보지 못한다. 이어지는 함수 도구 전용 가정에서 AssertionError가 날 수 있었다.

반면 durable operation ID에는 도구 경로를 만들 때 toolset_kind가 기록된다. 일반 함수 도구는 function, MCP 도구는 mcp, 동적 도구 집합은 dynamic으로 식별된다. wrapper가 표시용 이름이나 노출 객체를 바꿔도 이 연산 종류는 남는다.

PR #8257은 opt-out 분기에서 먼저 현재 ID가 tool operation인지 확인한 뒤 operation_id.toolset_kind를 읽는다. dynamic은 workflow 안에서 도구 해석이나 호출 중 I/O가 생길 수 있어 거부하고, mcp 역시 I/O가 필요하므로 거부한다. 일반 함수 도구 경로에서는 MCP 모듈을 import하지 않는다.

wrapper가 tool 객체의 겉 타입을 바꿔도 DurableOperationId의 toolset_kind가 MCP 연산을 식별해 I O 경계를 유지하는 비교

그림 2. 2.43.0은 wrapper 뒤의 객체 타입 대신 생성 시 기록한 operation kind로 실행 정책을 판정한다. 출처: github.com/pydantic/pydantic-ai/pull/8257.

4. 이 수정이 지키는 Temporal의 경계

Temporal workflow는 같은 입력과 기록된 이력으로 다시 실행할 때 같은 결정을 내야 한다. 네트워크 요청처럼 반복할 때 결과가 달라질 수 있는 작업은 activity로 분리하는 것이 기본 구조다. Pydantic AI의 Temporal 문서도 workflow를 결정적 부분, activity를 I/O와 비결정적 작업을 맡는 부분으로 설명한다.

그래서 모든 도구에 temporal: False를 허용하는 것이 수정의 목적은 아니다. MCP와 dynamic toolset은 여전히 workflow 내부 실행이 금지된다. 달라진 것은 금지 대상을 찾는 기준이다. 선택 패키지의 타입을 import해 현재 객체를 검사하지 않고, durable layer가 이미 알고 있는 operation kind로 경계를 판정한다.

이 구분은 오류 메시지에도 영향을 준다. 평범한 비동기 함수 도구는 불필요한 ImportError 없이 opt-out을 해석할 수 있다. 반대로 MCP 도구는 wrapper 안에 있어도 toolset_kind == 'mcp'로 잡혀, I/O 도구는 workflow 밖에서 실행할 수 없다는 UserError를 받는다. 잘못된 설치 오류나 내부 assertion보다 운영자가 고칠 수 있는 실패에 가깝다.

5. 두 회귀 테스트가 각각 다른 실패를 막는다

2.43.0 태그의 테스트에는 두 사례가 추가됐다. 첫 테스트는 sys.modules['pydantic_ai.mcp'] = None으로 MCP 모듈을 불러올 수 없는 설치를 흉내 낸다. 일반 비동기 함수 도구에 temporal: False를 주고 설정 해석 결과가 False인지 확인한다. 핵심은 MCP 없이도 MCP와 무관한 경로가 작동한다는 점이다.

두 번째 테스트는 MCP 도구를 PrefixedToolset으로 감싼다. 외부에서 보이는 tool.toolset이 wrapper로 바뀌어도 operation ID에는 mcp가 남는다. 테스트는 이 경로가 AssertionError로 빠지지 않고 "MCP tools require the use of IO"라는 UserError를 내는지 확인한다.

이번 검토에서는 2.42.0과 2.43.0 태그의 _durability.py를 직접 비교했다. 2.42.0에는 opt-out 분기 안의 MCP import와 객체 타입 검사가 있고, 2.43.0에는 그 import가 없으며 is_tool_operation과 두 toolset_kind 비교가 들어 있다. 또한 2.43.0 태그에서 위 두 테스트를 대상으로 실행해 통과 여부를 별도 확인했다. 이는 해당 회귀 경로를 확인한 것이지 Temporal 전체 동작이나 모든 wrapper 조합을 검증한 것은 아니다.

MCP extra가 없는 일반 비동기 함수 도구는 통과하고 PrefixedToolset 안의 MCP 도구는 UserError로 거부하는 두 회귀 테스트

그림 3. 회귀 테스트는 허용해야 할 함수 도구와 계속 거부해야 할 wrapped MCP를 각각 고정한다. 출처: github.com/pydantic/pydantic-ai/blob/v2.43.0/tests/durable_exec/temporal/test_durability.py.

6. durable agent 통합에서 바로 확인할 것

선택 의존성이 공통 실행 경로에 섞였는지 먼저 본다. foo extra를 쓰지 않는 사용자가 관련 모듈을 설치하지 않은 상태에서도 기본 도구, 검증, 오류 처리 경로가 돌아가야 한다. 테스트 환경에 모든 extra를 한꺼번에 설치하면 이런 결함이 숨어 버린다. 최소 설치 조합을 별도 CI 축으로 두는 편이 낫다.

실행 종류는 wrapper 바깥의 현재 객체보다 생성 시점의 명시적 식별자로 판정한다. 이름 접두사, 캐시, 권한 wrapper가 겹치면 객체 그래프는 바뀐다. 반면 function, mcp, dynamic처럼 operation에 붙인 종류는 실행 정책이 참고할 안정적인 값이 된다. 다만 이 값도 생성 단계에서 잘못 붙이면 안전하지 않으므로 operation 생성과 정책 판정을 함께 테스트해야 한다.

마지막으로 거부 경로를 성공 경로만큼 구체적으로 검증한다. I/O가 필요한 MCP 도구를 workflow 안에서 실행하도록 풀어 버리면 안 된다. 이번 수정은 제한을 완화하지 않고, 일반 함수 도구의 불필요한 실패와 wrapped MCP의 누락을 동시에 고쳤다. 의존성 오류를 없앴다는 한 문장보다, 어떤 연산은 통과하고 어떤 연산은 계속 거부되는지를 보는 편이 정확하다.

참고 자료

댓글

댓글 쓰기

이 블로그의 인기 게시물

체크아웃은 분리됐는데 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 문서는 필요 없다"고 해석하면 곤란하다. 연구가 추적한 것은 저장소 안에서 명시적으로 열린 파일이다. 웹 문서, 모델이 이미 학습한 지식, 코드 주석, 런타임이 자동으로 주입한 문맥은 잡히지 않는다. 정확한 결론은 코딩 에이전트가 저장소 안에서 작업할 ...
자세한 내용 보기