Claude Code 에이전트, 세션 간 대화 컨텍스트 유지하기 (크로스 세션 메시징 활용 경험)

Claude Code 에이전트, 세션 간 대화 컨텍스트 유지하기 (크로스 세션 메시징 활용 경험)

안녕하세요, 코딩아빠입니다. 오늘도 제 육아일기 대신 개발 경험노트를 꺼내 들었습니다. 이 글은 제가 Claude Code 환경에서 멀티 에이전트 시스템을 구축하며 겪었던 문제와 그 해결 과정을 상세히 기록한 것입니다. 처음에는 각 에이전트 세션이 독립적으로 움직이며 이전 대화나 작업 내용을 기억하지 못해 난감했습니다. 마치 매번 처음 만나는 사람처럼 대화해야 하는 상황이 반복되는 기분이었죠. 장기적인 협업이 필요한 작업을 구상하고 있었기에, 에이전트 간의 컨텍스트 공유는 필수적인 요소였습니다. 이 문제를 어떻게 접근하고 해결했는지, 제가 직접 부딪히고 정리한 내용을 공유해 봅니다.

여기서 확인할 것

• Claude Code 에이전트 세션이 기본적으로 독립적인 이유
• 에이전트 세션 간 컨텍스트 공유의 필요성과 도전 과제
• Claude Code의 크로스 세션 메시징 기능의 역할과 사용법
• 특정 에이전트 세션으로 메시지를 보내는 방법
• 모든 활성 에이전트 세션에 메시지를 브로드캐스트하는 방법
• 메시지 수신 처리 핸들러 구현을 통한 에이전트 상태 관리

처음 마주한 문제: 에이전트 세션 간 컨텍스트 단절

Claude Code를 활용하여 여러 에이전트가 협력하는 시스템을 구상하고 있었습니다. 제 아이 이름을 딴 '하준봇'과 '지훈봇'처럼, 각 에이전트가 특정 역할을 맡아 순차적으로 작업을 처리하거나, 서로 정보를 주고받으며 하나의 큰 목표를 달성하는 시나리오였죠. 하지만 막상 구현을 시작해보니, 각 에이전트 세션이 완전히 독립적으로 실행되는 것을 확인했습니다. 한 세션에서 특정 정보를 처리하고 다음 세션으로 넘어가면, 이전 세션의 내용은 전혀 기억하지 못하는 듯 보였습니다.

이것은 마치 제가 아들에게 중요한 이야기를 해주고 나서, 1시간 뒤에 그 이야기를 다시 처음부터 설명해야 하는 것과 비슷했습니다. 예를 들어, '하준봇'이 데이터 분석을 마치고 특정 결론을 도출했는데, 이 결론을 바탕으로 '지훈봇'이 다음 작업을 수행해야 할 때마다, '하준봇'의 결론을 매번 다시 주입해야 하는 상황이었습니다. 이는 장기적인 관점에서 에이전트 간의 효율적인 협업을 불가능하게 만들었고, 시스템의 확장성에도 큰 제약이 될 것이 분명했습니다. 에이전트들이 서로의 존재를 모르고 각자의 세상에서만 움직이는 듯한 느낌을 지울 수 없었습니다.

독립적인 세션 환경, 그 원인을 파악하다

문제의 본질을 파악하기 위해 Claude Code 환경의 에이전트 세션 작동 방식을 좀 더 깊이 들여다봤습니다. 일반적인 에이전트 세션은 각각 고유한 실행 컨텍스트를 가지며, 이는 격리된 환경에서 안전하고 예측 가능하게 동작하도록 설계된 결과였습니다. 즉, 한 세션에서 정의된 변수나 상태는 다른 세션에 영향을 주지 않으며, 세션이 종료되면 그 안의 모든 정보는 휘발됩니다. 이것은 보안이나 안정성 측면에서는 장점일 수 있지만, 제가 구축하려던 멀티 에이전트 협업 시스템에는 치명적인 단점으로 작용했습니다.

처음에는 단순히 특정 변수를 전역적으로 선언하거나, 파일을 이용해 상태를 공유하는 등의 방법을 고민했습니다. 하지만 이 방법들은 에이전트가 동적으로 생성되거나 사라지는 환경에서는 관리하기가 매우 복잡하고, 비동기적인 통신에서 데이터 일관성을 보장하기 어렵다는 한계가 있었습니다. 특히, 에이전트 간의 '대화'라는 개념을 구현하기 위해서는 단순한 데이터 공유 이상의, 메시징 기반의 접근 방식이 필요하다는 결론에 도달했습니다. 각 에이전트가 능동적으로 메시지를 주고받으며 컨텍스트를 이어가는 것이 제가 원하던 그림이었습니다.

크로스 세션 메시징, 해결의 실마리를 찾다

여러 문서를 찾아보고 테스트를 거듭하던 중, Claude Code가 제공하는 '크로스 세션 메시징' 기능을 발견했습니다. 이 기능은 이름 그대로 여러 에이전트 세션 간에 비동기적으로 메시지를 주고받을 수 있도록 설계된 것이었습니다. 마치 아빠가 엄마에게, 혹은 아이에게 특정 메시지를 보내는 것처럼, 에이전트가 다른 에이전트에게 명확한 의도를 담은 메시지를 전달할 수 있게 해주는 기능이었죠. 이 기능을 통해 저는 에이전트들이 서로의 존재를 인지하고, 이전 대화 내용을 이어받아 작업 상태를 공유하며, 장기적인 대화 흐름을 유지할 수 있는 기반을 마련할 수 있겠다는 확신이 들었습니다.

이 메시징 기능은 크게 두 가지 방식으로 메시지를 보낼 수 있었습니다. 하나는 특정 세션 ID를 지정하여 메시지를 보내는 방식이고, 다른 하나는 현재 활성화된 모든 세션에 메시지를 브로드캐스트하는 방식입니다. 이 두 가지 방식은 에이전트 간의 협업 모델을 설계하는 데 있어 매우 유연한 선택지를 제공해 주었습니다. 예를 들어, 특정 에이전트에게 직접 지시를 내리거나, 전체 에이전트들에게 공지사항을 전달하는 시나리오에 각각 적용할 수 있을 것 같았습니다. 단순한 정보 공유를 넘어, 에이전트의 상태를 동적으로 관리하고 제어할 수 있는 길이 열린 셈입니다.

특정 에이전트에게 직접 메시지 보내기

먼저 특정 에이전트 세션에게만 메시지를 보내는 방법을 시도했습니다. 이는 제가 '하준봇'에게 특정 작업을 지시하거나, '지훈봇'에게 '하준봇'이 처리한 결과물을 전달해야 하는 상황에 딱 맞는 기능이었습니다. 핵심은 session_id를 정확히 지정하는 것이었습니다. 각 세션은 고유한 ID를 가지고 있으므로, 이 ID를 통해 타겟 세션을 식별할 수 있었습니다.

아래 코드는 특정 세션 ID를 가진 에이전트에게 메시지를 보내는 간단한 예시입니다. `` 부분에 메시지를 받을 세션의 실제 ID를 넣으면 됩니다. 이 ID는 Claude Code 환경에서 각 세션의 정보를 확인하여 얻을 수 있습니다.

`
await send_message_to_session(session_id="<TARGET_SESSION_ID>", message="Hello from another session!")
`

이 방식을 통해 에이전트 간의 1:1 통신이 가능해졌습니다. 예를 들어, 특정 데이터 처리 에이전트가 분석을 완료한 후, 그 결과를 보고서 작성 에이전트에게 직접 전달하여 다음 단계의 작업을 트리거할 수 있게 되는 것이죠. 단순히 데이터를 던지는 것이 아니라, '이 데이터로 이런 작업을 해달라'는 명확한 의도를 담아 메시지를 보낼 수 있다는 점이 중요했습니다. 저는 이 기능을 활용하여 순차적인 작업 흐름을 가진 에이전트 파이프라인을 구축하는 데 활용했습니다.

모든 에이전트에게 공지사항 브로드캐스트하기

특정 세션에 메시지를 보내는 것 외에, 모든 활성 에이전트 세션에 일괄적으로 메시지를 보내야 하는 상황도 있었습니다. 예를 들어, 전체 시스템의 상태가 변경되었거나, 모든 에이전트가 알아야 할 전역적인 업데이트가 발생했을 때 유용할 것이라고 생각했습니다. 제가 육아를 하면서 '밥 먹자!'라고 외치면 온 가족이 듣는 것처럼 말이죠. 이럴 때는 send_message_to_all_sessions 함수를 사용하면 됩니다.

아래 코드는 모든 활성 세션에 메시지를 브로드캐스트하는 예시입니다. 이 메시지는 현재 Claude Code 환경에서 실행 중인 모든 에이전트 세션이 수신하게 됩니다.

`
await send_message_to_all_sessions(message="Global update: Task completed.")
`

이 기능은 특히 분산된 환경에서 모든 에이전트에게 동시에 특정 지시를 내리거나, 전역 설정 변경 사항을 알리는 데 매우 효과적이었습니다. 예를 들어, 시스템 유지보수 시간 공지, 새로운 설정 파일 로드 명령, 또는 특정 조건이 충족되어 모든 에이전트가 작업을 중단해야 할 때 유용하게 활용할 수 있을 것입니다. 저는 이 기능을 사용하여 특정 에이전트가 중요한 이정표(milestone)에 도달했을 때, 다른 모든 에이전트가 이를 인지하고 각자의 작업을 조정할 수 있도록 시스템을 설계했습니다. 이는 에이전트 간의 느슨한 결합을 유지하면서도, 중요한 정보는 신속하게 공유할 수 있는 좋은 방법이었습니다.

수신된 메시지 처리 로직 구현

메시지를 보내는 것만큼 중요한 것은, 보낸 메시지를 에이전트가 어떻게 수신하고 처리하느냐였습니다. 메시지를 보냈다고 해서 에이전트가 자동으로 알아서 동작하는 것은 아니기 때문이죠. 각 에이전트는 자신에게 도착한 메시지를 처리할 수 있는 핸들러를 가지고 있어야 합니다. Claude Code에서는 on_message_received와 같은 메커니즘을 통해 메시지 수신 시 특정 함수를 실행하도록 설정할 수 있었습니다.

`
on_message_received(handler_function)
`

위 코드는 메시지가 수신되었을 때 handler_function이라는 함수를 호출하도록 설정하는 기본적인 형태입니다. 이 handler_function 내에서 수신된 메시지의 내용을 파싱하고, 그 내용에 따라 에이전트가 특정 동작을 수행하도록 로직을 구현했습니다. 예를 들어, 메시지에 'task_complete'라는 키워드가 있으면 다음 작업을 시작하고, 'status_query'라는 키워드가 있으면 현재 상태를 회신하는 식으로 말이죠. 이 핸들러 함수는 메시지의 발신자, 내용, 타임스탬프 등 다양한 정보를 파라미터로 받을 수 있었고, 이를 활용해 더욱 정교한 상태 관리와 대화 흐름 제어가 가능했습니다. 이로써 에이전트는 단순히 메시지를 받는 것을 넘어, 능동적으로 상황을 인지하고 반응하는 주체로 거듭나게 되었습니다.

.ba-pc{display:none}.ba-mo{display:block}@media (min-width:768px){.ba-pc{display:block}.ba-mo{display:none}}

컨텍스트 유지의 결과와 활용 가능성

크로스 세션 메시징 기능을 활용하여 두 개 이상의 Claude Code 세션을 열고, 한 세션에서 다른 세션으로 메시지를 보내는 테스트를 진행했습니다. 특정 세션 ID를 지정하여 보낸 메시지가 의도한 대로 해당 세션에만 도착하는 것을 로그를 통해 확인했습니다. 또한, 모든 세션에 브로드캐스트한 메시지는 실행 중인 모든 세션에서 성공적으로 수신되는 것을 관찰할 수 있었습니다. 메시지 내용에 따라 에이전트가 미리 정의된 동작을 수행하는 것까지 확인하며, 컨텍스트 공유 및 지속적인 대화 흐름 유지가 성공적으로 이루어지고 있음을 검증했습니다.

이 경험을 통해 에이전트의 상태 관리와 장기 실행 작업의 일관성을 확보하는 데 매우 중요한 진전을 이루었다고 생각합니다. 단순한 정보 전달을 넘어, 에이전트 간의 복잡한 협업 모델을 설계할 수 있는 견고한 기반을 마련한 셈입니다. 앞으로는 이 기능을 활용하여 에이전트들이 서로의 작업 진행 상황을 실시간으로 공유하고, 필요에 따라 역할을 전환하며, 더욱 복잡하고 지능적인 협업 시스템을 구축해 나갈 계획입니다. 제 아들이 친구들과 협력해서 레고 블록으로 멋진 성을 만드는 것처럼, 저의 에이전트들도 서로 소통하며 더 큰 가치를 만들어낼 수 있을 것이라는 기대감이 큽니다.

남는 이야기

Claude Code의 크로스 세션 메시징 기능은 멀티 에이전트 시스템을 구축하는 개발자에게 매우 강력한 도구입니다. 단순히 독립적인 에이전트를 넘어, 서로 소통하고 협력하여 컨텍스트를 유지하는 지능적인 시스템을 만들 수 있는 핵심적인 방법론을 제공합니다. 이 기능을 이해하고 효과적으로 활용한다면, 에이전트 기반 솔루션의 잠재력을 최대한 끌어낼 수 있을 것입니다. 저처럼 에이전트 간 컨텍스트 유지 문제로 고민하셨던 분들께 이 경험이 작은 도움이 되기를 바랍니다.