OpenAI Agents SDK for Python 0.24.0: MCP 도구 설명 노출, 실행 전체 오류 서식화

1. 도구의 설명 정보는 권한이 아니라 참고 자료다

2026년 10월 15일 공개된 0.24.0은 MCP 서버의 도구를 함수 도구로 변환할 때 서버가 붙인 부가 설명도 노출한다. MCP는 에이전트가 외부 도구에 연결할 때 쓰는 프로토콜이며, 이번 정보는 도구를 파악하기 위한 참고 표시에 해당한다.

개발자는 FunctionTool.mcp_annotations에서 이 정보를 읽을 수 있다. 값은 복사본으로 반환되므로 읽은 값을 고쳐도 원본에 반영되지 않는다.

MCP가 아닌 도구나 부가 설명이 없는 도구는 None을 반환한다. 서버가 생략한 힌트도 그대로 빠져 있으므로, 기본값이 필요하면 개발자가 사용 중인 MCP 버전의 기본값 규칙을 적용해야 한다.

릴리스 노트는 이 정보를 신뢰가 보장되지 않은 힌트로 다루라고 안내한다. 실행 승인을 부여하지 않으며, 모델에 전달하는 도구 정의나 직렬화된 도구 출처 정보에도 포함되지 않는다. 설명표가 출입 허가증을 대신하지 않는 것과 같다.

2. 함수 오류 문장을 실행 전체에서 정한다

RunConfig.tool_error_formatter는 실행 전체에서 도구 오류 문장을 만드는 콜백, 즉 오류가 생겼을 때 호출되는 사용자 지정 함수다. 이번에는 함수를 도구로 등록하는 표시(데코레이터)를 붙인 함수 도구의 실행 예외도 이 경로에서 처리한다.

오류 분류에 kind="tool_exception"이 추가됐다. 기존 처리기가 거절이 아닌 오류를 도구 부재로만 해석했다면, 실제로는 실행 중 실패한 함수를 찾지 못했다고 잘못 안내할 수 있다.

기존 콜백은 새 분류를 직접 처리하거나, 해당 분류에서 None을 반환해 기본 문장을 사용하도록 바꾼다. 사용자 지정 처리기가 없는 경우의 기본 동작은 달라지지 않는다.

선택 필드인 error에는 예외 정보가 전달된다. 모델에 보여 줄 문장에 상세 내용을 넣으려면 개발자가 의도적으로 정제해야 한다. 예외 정보를 받는 기능과 그 정보를 공개해도 되는지는 별개다.

도구별로 명시한 처리기가 실행 전체 설정보다 우선한다. 명시적으로 지정한 None이나 기본 처리기도 이 우선순위를 유지한다.

생성 함수로 만든 MCP 도구와 Agent.as_tool로 감싼 에이전트의 실패는 별도 동작을 유지한다. 시간 초과, 취소, 정해진 자료 구조(스키마)에 따른 프로그램 호출도 새 공통 처리 경로로 통합되지 않는다.

3. 승인 대기 중에는 기록 압축을 보류한다

자동 압축은 대화 이력을 줄여 관리하는 처리다. 이번 수정은 대기 중인 승인 요청이 있으면 이를 미루도록 한다. 승인 절차가 남아 있는 동안 기록 정리를 앞서 진행하지 않도록 처리 순서를 바꾼 것이다.

승인을 기다리며 보류한 이력도 실행을 재개한 뒤까지 보존하도록 수정됐다. 릴리스 페이지에 포함된 검토 보고서는 출력 안전성 검사 단계까지 이력 저장을 미룬다고 설명한다. 따라서 승인 이력을 보존한다는 설명을 검사 전부터 무조건 저장한다는 뜻으로 읽어서는 안 된다.

4. 도입 전에는 오류 분류와 저장된 실행을 확인한다

기존 처리기가 거절 여부만으로 도구 부재를 판단했다면, 새 버전에서는 실행 실패까지 ‘없는 도구’로 안내할 수 있다. 오류 안내를 한곳에 모으는 편의를 얻으려면 먼저 도구 부재와 실행 실패를 구분하도록 분류를 보완해야 한다.

다만 저장된 실행을 쓰는 경우에는 업데이트 시점도 따져야 한다. 릴리스 검토 보고서에 따르면, 이름이 같은 에이전트가 포함된 일부 과거 구성은 새 버전에서 읽히지 않는다. 해당 작업은 저장 당시의 SDK와 원래 에이전트 코드로 마쳐야 한다.

릴리스 노트에는 실행 가능한 코드 예시가 제시되지 않았다.

도입의 기준은 새 기능의 수보다 기존 오류 분류가 새 입력을 구분하는지, 저장된 작업을 어느 버전에서 마쳐야 하는지에 있다.