Anthropic Python SDK, 메시지 스레드와 세분화된 사용량 보고 추가

대화의 다음 턴을 보내는 방식이 달라집니다

Anthropic Python SDK 2.2.0은 한국시간 2026년 10월 23일 공개됐습니다. 메시지 스레드 지원과 차원별 사용량·비용 보고가 주요 변경입니다. 공식 예제는 client.beta.messages.thread()로 대화를 만든 뒤 send()와 stream()으로 새 메시지를 보내는 흐름을 보여줍니다. 각 턴에는 새 메시지만 보내고 이전 대화는 서버가 보유한다고 설명합니다.

도구를 호출하는 턴은 메시지를 추가한 다음 스레드의 도구 실행기를 통해 이어갈 수 있습니다. 예제에는 스트리밍 응답 사이에 도구 호출을 처리하는 방식도 있습니다. 다만 전송하는 메시지가 줄었다고 전체 대화의 과금이나 모델이 읽는 문맥까지 같은 비율로 줄어든다고 결론 내릴 근거는 없습니다.

분기와 설정 변경을 구별해야 합니다

fork()는 같은 대화 이력에서 분기를 만듭니다. 분기 후 첫 턴에 새 서버 측 스레드가 시작되고 이후 원본과 독립적으로 진행된다는 것이 예제의 설명입니다. 문의 대응을 이어가는 대화와 다른 대응안을 검토하는 대화를 나누는 방식으로 이해할 수 있습니다.

반면 model, system, tools 등은 스레드 수명 동안 고정됩니다. 이를 바꾸려면 기존 메시지 이력을 사용해 새 스레드를 만드는 예제가 제시됩니다. 대화 객체의 임의 필드를 바꾸는 것만으로 서버의 실행 조건도 바뀐다고 가정하지 않는 것이 좋습니다. 분기와 새 설정 적용을 각각 확인하면 대화가 어느 조건으로 이어지는지 명확해집니다.

보고서의 집계 기준을 맞춥니다

새 사용량 API는 모델·워크스페이스 등의 기준으로 묶고, 시간 구간을 추가해 데이터를 읽을 수 있습니다. 공식 구현은 최대 다섯 집계 차원을 지원하며, 사용량이 있는 조합을 여러 페이지에 걸쳐 반환한다고 설명합니다. 집계 차원과 시간 구간을 생략하면 전체 기간을 합친 한 행으로 반환합니다. 사용량이 없는 팀이 자동으로 0인 행으로 채워진다고 가정하면 안 됩니다.

조회 시작 시각은 포함되고 종료 시각은 제외됩니다. 조회 범위는 최대 31일이며 시간 구간을 지정하면 종료 시각도 필요합니다. read:analytics 범위의 API 키 또는 Admin API 키가 요구된다는 조건도 있습니다. 사용량과 비용은 별도 보고서이므로 토큰 수를 금액처럼 합산하지 말고, 같은 기간과 필터로 대조해야 합니다.

이전 보고서와 비교할 때

릴리스는 이전 보고서를 legacy로 표시했다고 설명할 뿐, 즉시 제거했다고 발표하지는 않았습니다. 교체 전에는 페이지를 모두 읽은 합계, 날짜 경계, 삭제된 사용자 포함 여부를 같은 조건으로 맞춰 비교하는 편이 좋습니다. 이 글은 SDK 예제와 API 정의를 검토한 내용이며, 실제 조직의 비용·사용량이나 메시지 저장 정책을 측정한 결과는 아닙니다.

출처

• 공식 릴리스 원문
• 공식 메시지 스레드 예제
• 차원별 사용량 보고 API 정의
• 차원별 비용 보고 API 정의