AI 에이전트 SDK 새 방식 — 써보려 했더니 통째로 사라졌습니다

AI 에이전트를 코드로 붙이다 보면 여러 차례 주고받는 대화를 어떻게 짜야 하나에서 한 번 막힙니다. 검색하면 "보내기와 받기를 따로 부르는 깔끔한 방식"을 소개하는 공식 문서가 나오는데 — 그대로 짜면 안 돌아갑니다. 그 방식은 통째로 제거됐고, 그 문서는 옛 판을 쓰는 사람들을 위해 남겨둔 것이거든요. 왜 사라졌고, 지금은 어떻게 짜야 하는지 정리했습니다.

📌 30초 요약

• ★★새 방식이 아니라 없어진 방식입니다 — 문서 제목에 적혀 있습니다.
• ★판 번호가 건너뛴 자리가 제거 지점입니다.
• ★계속 쓰려면 앞자리를 고정해 설치해야 합니다.
• ⚠️ 애초에 안 되는 기능이 있었습니다 — 세션 갈라놓기 등.
• 옮기는 방법은 두 줄로 끝납니다.
• 이름에 붙은 표시가 미리 경고하고 있었습니다.

새 방식인 줄 알았는데 없어진 방식입니다

먼저 이게 뭐였는지부터. 원래 방식은 하나의 흐름에 입력과 출력이 같이 오갑니다. 한 번만 묻고 답받는 거라면 간단한데, 여러 차례 주고받으려면 입력 쪽도 흐름으로 만들어서 "언제 다음 메시지를 내보낼지"를 직접 맞춰줘야 했어요. 이게 은근히 번거롭습니다.

그래서 실험적으로 나온 게 세 조각으로 줄인 방식이었습니다 — 대화를 하나 만들고, 보내고, 받고. 보내는 동작과 받는 동작이 분리돼 있어서 차례 사이에 내 로직을 끼워 넣기가 훨씬 쉬웠죠. 답을 한 번 가공한 뒤 다음 질문을 만든다든가. 아이디어 자체는 좋았습니다.

⚠️ 그런데 지금은 없습니다

그 방식을 이루던 함수 셋과 관련 타입 둘이 모두 제거됐습니다. 문서 제목에도 "제거됨"이 붙어 있고, 맨 위에 경고 상자가 하나 놓여 있어요. 그런데 검색으로 이 페이지에 바로 들어오면 그 경고를 지나치기 쉽습니다 — 본문은 예제 코드가 가득해서 멀쩡해 보이거든요. "공식 문서대로 짰는데 함수를 못 찾는다"가 되는 전형적인 경로입니다.

판 번호가 건너뛴 자리가 경계입니다

언제부터 없어졌는지가 조금 헷갈리게 적혀 있습니다. 패키지 판 번호가 한 단계에서 다음 단계로 곧장 뛰었기 때문이에요. 중간 번호들이 아예 없습니다. 그래서 문서가 "제거된 판과 고정해야 할 판이 사실 같은 경계를 가리킨다"고 굳이 한 줄 설명을 붙여뒀습니다.

정리하면 이렇습니다 — 앞 단계의 마지막 판까지가 그 방식을 담고 있는 마지막 판이고, 다음 단계로 넘어가는 순간 사라졌습니다. 옛 코드를 당장 못 고치는 사정이라면 설치할 때 앞 두 자리를 고정하면 그 판에 머물 수 있어요. 다만 이건 시간을 버는 것이지 해결이 아닙니다 — 그 판에 머무는 동안 이후에 추가된 기능은 전부 못 씁니다. 새 모델이 나왔다는 소식을 볼 때마다 반가운데, 실은 새로 생기는 만큼 조용히 없어지기도 합니다.

옮기는 방법은 두 줄로 끝납니다

다행히 이사는 간단합니다. 문서가 제시하는 대응이 둘뿐이에요.

없어진 방식으로 하던 일	지금은
여러 차례 주고받기	사용자 메시지를 차례로 내주는 흐름을 넘깁니다
저장한 대화 이어받기	부를 때 이어받을 대화 번호를 설정으로 줍니다
한 번만 묻고 끝내기	원래 방식이 거의 그대로입니다
대화 갈라놓기	없어진 방식에선 원래 안 됐습니다

마지막 줄이 이 이야기의 힌트입니다. 없어진 그 방식은 애초에 기존 기능을 전부 담지 못했어요. 대화를 복사해 갈라놓는 것과 일부 고급 입력 방식은 처음부터 원래 방식으로만 가능했습니다. 문서에 "이건 옛 방식이 필요합니다"라는 목록이 따로 있었을 정도예요. 두 갈래를 오가야 하는 상태였다는 뜻이고, 그게 통합으로 이어진 이유이기도 합니다.

이름이 미리 경고하고 있었습니다

가장 남는 교훈은 여기입니다. 그 함수들 이름 앞에는 "불안정"이라는 표시가 붙어 있었습니다. 예쁘라고 붙인 게 아니라 "예고 없이 바뀌거나 없어질 수 있다"는 계약이었어요. 실제로 그렇게 됐고요.

그러니 이런 표시가 붙은 걸 쓸 때는 한 군데로 감싸 두세요. 내 코드 곳곳에서 직접 부르지 말고, 얇은 껍데기를 하나 만들어 그 안에서만 부르는 겁니다. 그럼 없어졌을 때 고칠 자리가 한 곳이에요. 그리고 검색으로 만난 문서는 맨 위 경고 상자부터 읽는 습관을 들이세요 — 예제 코드는 페이지가 살아 있든 죽었든 똑같이 멀쩡해 보입니다. 확장 기능들을 총정리해 세팅해 두는 흐름이라면, 어느 게 안정된 기능이고 어느 게 실험 딱지를 달고 있는지 구분해 두는 게 나중에 시간을 아껴줍니다.

✅ 정리 문법은 챙겨갈 만합니다

없어진 방식에서 하나 배워갈 게 있습니다. 대화를 블록을 벗어날 때 자동으로 닫아주는 문법을 쓸 수 있었는데, 이건 언어 자체의 기능이라 지금 방식에서도 자원 정리에 그대로 쓸 수 있어요. 다만 언어 판이 낮으면 안 되니 그때는 직접 닫아야 합니다. 에이전트에 관측을 붙여둔 상태라면, 안 닫힌 대화가 쌓이는 것도 바로 눈에 띕니다.

자주 묻는 질문 (FAQ)

Q. 제 코드가 갑자기 안 도는데 이것 때문일까요?

패키지를 올린 뒤 "그런 함수가 없다"는 오류가 났다면 가능성이 큽니다. 부르고 있는 함수 이름 앞에 "불안정" 표시가 붙어 있는지부터 보세요. 붙어 있다면 그 계열입니다.

Q. 당장 고칠 시간이 없으면요?

설치할 때 앞 두 자리를 고정하면 그 방식이 남아 있는 마지막 판에 머뭅니다. 다만 그 뒤에 추가된 기능은 하나도 못 쓰게 되니, 일정만 벌고 옮기는 걸 권합니다.

Q. 옮기면 코드가 많이 길어지나요?

한 번 묻고 끝내는 경우는 거의 그대로입니다. 여러 차례 주고받는 쪽만 메시지를 차례로 내주는 흐름을 하나 만들어 넘기는 형태로 바뀝니다. 이어받기는 설정 항목 하나면 되고요.

Q. 그럼 그 문서는 왜 아직 남아 있나요?

문서가 직접 밝힙니다 — 옛 판에 머물러 있는 코드를 유지보수하는 사람들을 위한 참고용이라고요. 새로 짜는 사람을 위한 안내가 아닙니다. 이런 "보관용" 페이지가 검색에는 똑같이 잡힌다는 게 함정이죠.

✨ 정리하면

더 편해 보이는 방식이 나왔다가 한 판 만에 통째로 사라진 사례입니다. 아이디어가 나빠서가 아니라 기능이 반쪽이라 두 갈래를 오가야 했던 게 문제였죠. 챙길 건 셋입니다 — 이름에 붙은 표시를 계약으로 읽고, 그런 건 한 군데로 감싸 두고, 검색으로 만난 문서는 맨 위 경고부터 읽기. 도구 선택과 비용을 함께 설계하는 흐름은 AI 지출 관리 허브에 단계별로 정리해 두었습니다.

출처: Claude Agent SDK 공식 문서 「타입스크립트 SDK의 옛 세션 방식(제거됨)」 (2026-09-01 열람). 해당 방식은 현재 지원되지 않으며, 문서는 옛 판 유지보수를 위한 참고용으로 남아 있습니다. 판 경계와 세부 절차는 변경될 수 있습니다.