투자 조사를 위한 오픈소스 Claude Code: deepagents와 LangGraph 기반 아키텍처 공유

TL;DR: deepagents와 LangGraph를 기반으로 구축한 풀스택 금융 에이전트(React 19, FastAPI, PostgreSQL, Redis)를 오픈소스로 공개합니다. 두 가지 모드(전체 샌드박스 실행을 위한 PTC, 빠른 답변을 위한 Flash)를 지원합니다. 24계층 미들웨어 스택, MCP-to-Python 코드 생성, 비동기 서브 에이전트 오케스트레이션, 영구 워크스페이스를 갖추고 있습니다. 모든 LLM 제공업체에 대해 BYOK(본인 키 사용)를 지원합니다. Apache 2.0 라이선스로 github.com/ginlix-ai/langalpha에서 확인 가능합니다.

지난 3개월 동안 금융 분야의 수직적 에이전트를 구축해 왔습니다. 모든 것을 Apache 2.0 하에 오픈소스로 공개하기로 결정했습니다. 풀스택 앱으로 React 19 프론트엔드, FastAPI 백엔드, PostgreSQL, Redis를 사용합니다. 모든 LLM 제공업체에 대해 BYOK를 사용하거나 기존 Claude Code / Codex OAuth 구독을 연결할 수 있습니다.

deepagents나 Claude Code와 같은 도구들이 접근하는 방식이 마음에 들었습니다. 에이전트에게 파일 시스템과 작업 런타임을 제공하는 것입니다. 파일 시스템 도구, bash, 코드 실행이 기초가 되며 다른 모든 것은 그 위에 구축됩니다. deepagents는 플러그인 가능한 샌드박스 백엔드, 미들웨어 후크, 서브 에이전트 스캐폴딩을 제공했습니다. 우리는 이러한 추상화를 유지하면서 영구 워크스페이스, 연구 워크플로우, 멀티 에이전트 시스템, 금융 데이터 파이프라인 등 필요한 기능을 확장했습니다.

과정에서 많은 것을 배웠고 여전히 해결해야 할 부분도 있습니다. 커뮤니티의 다른 분들이 이러한 문제를 어떻게 생각하는지 듣고 싶어 이곳에 공유합니다. 이 게시물은 미들웨어, 도구/데이터, 프롬프트 관리, 서브 에이전트, 그리고 이 모든 것을 하나로 묶는 워크스페이스 시스템과 같은 주요 기능 및 설계 결정 사항을 다룹니다. 비슷한 것을 구축했거나 이러한 문제에 대해 다른 접근 방식을 취했다면, 진심으로 배우고 싶습니다.

세부 사항을 다루기 전에 배경을 조금 설명하겠습니다. 우리는 두 가지 에이전트 모드를 구축했습니다. PTC(Programmatic Tool Calling) 에이전트는 전체 에이전트로, 샌드박스에서 Python을 작성 및 실행하며 MCP 데이터 서버, 파일 도구, 서브 에이전트를 사용합니다. Flash 에이전트는 경량 모드로, 샌드박스 오버헤드나 코드 실행이 없습니다. 빠른 질문을 처리하고 워크스페이스 관리를 도우며, 적절한 워크스페이스 컨텍스트와 함께 복잡한 임무를 PTC 에이전트에 전달합니다(라우팅 레이어는 아직 개발 중).

미들웨어

LangChain v1은 미들웨어 패턴을 제공합니다. 우리는 그 위에 24개의 계층을 구축했습니다. 모든 프로덕션 문제가 미들웨어 계층이 되었습니다. 이야기할 가치가 있는 것들은 다음과 같습니다:

Steering — 실행 중인 에이전트의 방향 전환

금융 조사는 장기 실행 프로세스를 포함합니다. 에이전트가 DCF 모델을 작성하는 도중에 사용자가 동료 비교를 추가하거나, 대상 회사를 변경하거나, 더 중요하게는 에이전트가 잘못된 판단을 내리고 있음을 발견할 수 있습니다. Steering 없이는 전체 실행이 끝날 때까지 기다리거나 강제로 종료하고 처음부터 다시 시작해야 하는데, 둘 다 컴퓨팅 자원과 컨텍스트를 낭비합니다.

우리의 접근 방식: Redis 기반의 Steering 계층입니다. 사용자의 후속 요청은 스레드 ID로 키가 지정된 목록에 푸시됩니다. 모든 LLM 호출 전에 Steering 미들웨어는 원자적으로 목록을 비우고 대화 상태에 메시지를 주입합니다. 에이전트는 다음 추론 단계에서 이를 자연스럽게 확인하므로 재시작이나 컨텍스트 손실이 없습니다.

멀티모달 주입

에이전트는 Read 도구 하나만 사용합니다. 이 도구는 텍스트 파일, 이미지, PDF를 모두 처리합니다. 미들웨어는 읽기 작업을 가로채 파일 유형을 감지하고, 시각적 콘텐츠를 base64로 인코딩하여 모델이 볼 수 있는 적절한 콘텐츠 블록으로 주입합니다. 모델이 이미지나 PDF를 지원하지 않는 경우, 파일은 작업 디렉토리에 저장되고 에이전트는 샌드박스의 외부 도구를 사용하여 처리할 수 있습니다.