마이크로소프트가 Python용 Agent Framework 1.25.0을 공개했다. 이번 버전은 외부 도구 서버와 통신하는 규약인 MCP를 통해 읽는 카탈로그, 도구 목록을 모아 둔 자료의 크기를 제한하고, 한 사용자의 워크플로 실행기와 세션이 다른 권한 범위에서 재사용되지 않도록 바꿨다. 여러 사용자가 같은 에이전트 서비스를 쓰는 개발자는 탐색 설정과 워크플로 생성 방식을 함께 점검해야 한다.
1. MCP 카탈로그 탐색에 상한을 둔다
릴리스 노트에 따르면 agent-framework-core와 agent-framework-declarative는 MCP 도구와 프롬프트의 카탈로그 탐색량과 프레임워크가 관리하는 요청 시간을 다음과 같이 제한한다.
표: MCP 탐색·요청의 기본 설정
조건: MCP 도구·프롬프트 탐색과 프레임워크 소유 요청에 적용하는 기본값
단위: 페이지, 항목, 초
| 설정 | 기본값 | 적용 대상과 조건 |
|---|---|---|
| 탐색 페이지 수 상한 | 100페이지 | 도구·프롬프트 카탈로그마다 적용 |
| 탐색 항목 수 상한 | 1,000항목 | 도구·프롬프트 카탈로그마다 페이지 수와 별도로 적용 |
| 요청 시간 제한 | 30초 | 프레임워크가 관리하는 요청에 적용 |
카탈로그 갱신에 실패하면 기존 스냅샷, 갱신 전 상태를 보관한 복사본 전체를 보존한다.
규모가 큰 카탈로그를 쓰는 개발자는 페이지 수나 항목 수의 상한을 늘릴 수 있다. 신뢰하는 MCP 서버에 한해 해당 설정에 None을 지정하면 그 상한을 해제할 수 있다. 목록을 더 많이 읽어야 한다면 서버의 신뢰도와 필요한 탐색 범위를 함께 따져 설정하는 방식이다.
요청 대기 시간은 별도로 조정한다. MCP 도구에 request_timeout=None을 전달하면 요청 시간 제한을 무제한으로 되돌린다. 직접 만든 클라이언트는 자체 전송과 시간 제한 정책을 유지한다.
탐색 승인 정책에는 호출 가능한 함수를 사용할 수 있게 됐다. 도구 이름과 읽기 전용 여부를 기준으로 허용 범위를 정하고, 호출자가 명시한 재정의, 즉 설정값을 다시 지정하는 일을 반영할 수 있다. 보유 중인 도구에 대한 정책 갱신도 지원한다.
2. 워크플로 실행기와 세션을 권한 범위에 묶는다
워크플로를 실제로 수행하는 실행기와 세션은 하나의 권한 범위, 접근을 허용하는 대상의 경계에 연결된다. 한 권한으로 쓰던 실행기와 세션을 다른 권한의 요청에 넘기면 모델 호출 전에 거부하는 방식이다. AG-UI 엔드포인트, 요청을 받는 접속 지점에서는 워크플로 에이전트를 도구로 감싼 실행도 거부한다.
대응 방식은 호출마다 새 워크플로, 실행기, 세션을 만드는 함수인 팩토리를 전달하는 것이다. 릴리스 노트가 안내하는 전달 형태는 다음과 같다.
AgentFrameworkWorkflow(workflow_factory=...)범위를 넘는 재사용은 WORKFLOW_SCOPE_CONFLICT로 보고한다. 지원되지 않는 워크플로 에이전트 도구는 WORKFLOW_AGENT_TOOL_UNSUPPORTED로 보고하므로, 오류를 받은 개발자는 워크플로를 팩토리로 직접 서비스하도록 바꿔야 한다.
3. 매 호출마다 MCP 프로토콜 세션을 새로 연다
릴리스 노트에 함께 기재된 agent-framework-declarative 1.5.0의 보안 수정은 호출 사이의 MCP 상태 공유를 막는다. 기존에는 초기화된 프로토콜 세션, 서버와의 대화 단위를 캐시해 다음 호출에서 다시 썼다. 이제는 도구 실행과 목록 조회를 포함한 핸들러 호출마다 세션을 새로 만들고 닫는다.
그 결과 호출 사이의 서버 세션 연속성은 사라진다. 승인 대기나 체크포인트, 작업 중단 상태를 저장한 위치의 재개 뒤에도 이전 호출의 세션 상태가 이어지지 않는다. 연속 상태가 필요한 개발자는 서버에 남긴 상태를 가리키는 식별자인 원격 상태 핸들을 명시적으로 쓰거나, 범위를 직접 정한 MCPToolHandler를 마련해야 한다. 체크포인트와 승인 검증 자체는 바뀌지 않는다.
핸들러 생성 코드도 조정해야 한다. async with로 만들던 방식 대신 일반 생성 방식으로 바꾸고 aclose() 호출을 제거한다.
기존 캐시 크기 인자인 cache_max_size는 계속 전달할 수 있지만 검증 없이 무시된다. 값이 None이 아니면 폐기 예정 경고가 나오며, 이 인자를 생략하면 경고를 없앨 수 있다.
4. 탐색량 제한과 권한 격리는 설계 대상이 다르다
100페이지는 탐색하는 페이지 수의 상한이고, 1,000항목은 카탈로그에서 읽는 항목 수의 상한이다. 페이지 수 상한만 늘려도 항목 수 상한은 남으므로 큰 카탈로그를 다루는 서비스는 두 설정을 함께 확인해야 한다. 요청 시간 제한은 이와 별도로 요청 대기에 경계를 둔다.
반면 실행 범위 검사는 조회량이 아니라 실행기와 세션을 누가 재사용하는지를 제한한다. 탐색량은 서버 신뢰도와 카탈로그 규모에 맞춰 설정하되, 권한 격리는 다른 사용자의 요청에 같은 실행기와 세션을 넘기지 않는 객체 생성 구조로 대응해야 한다.
5. 설치 환경과 공유 객체부터 점검한다
이번 릴리스부터 설치에 필요한 파이썬 최소 버전은 3.11이다. 파이썬 3.10 환경이라면 먼저 실행 환경을 올려야 한다.
탐색 상한을 노출하는 기본 MCP 핸들러와 워크플로 소유권 검사를 쓰는 AG-UI는 Core 1.25를 요구하므로 관련 의존성도 함께 확인해야 한다.
다중 사용자 서비스의 이전 작업은 공유 객체를 찾는 데서 시작할 수 있다. 실행기와 세션을 보관하는 지점을 확인하면 호출별 새 객체를 만드는 팩토리로 바꿔야 할 부분을 가려낼 수 있다.
공유 빌더, 설정에 따라 객체를 구성하는 도구는 캐시 대상을 끄더라도 실행기를 재사용하므로 호출별 생성의 대안이 아니다. 단일 사용자 설정은 모든 호출자가 같은 주체일 때만 사용한다.
권한 범위 검사는 실행 중인 실행기와 세션의 신원을 대상으로 하며, 공유 저장소에서 불러온 상태나 워크플로를 직접 호출하는 사용자 정의 도구 함수는 범위 밖이다.
탐색량 설정을 조정하는 일과 권한 경계를 넘는 객체 재사용을 없애는 일은 서로 다른 이전 과제다.