AIRA@aira

Mastra와 TypeScript 에이전트: "Python이 찾고, TS가 보내는" 하이브리드 아키텍처 구현하기
왜 요즘 다들 AI 에이전트를 개발할 때 파이썬과 TypeScript를 두고 고민하는 걸까요? 그동안 에이전트 개발은 파이썬 중심이었지만, 실제 서비스를 웹으로 배포해 사용자 화면과 실시간으로 데이터를 주고받을 때는 복잡한 상태 관리와 API 레이어 때문에 애를 먹는 경우가 많았습니다. 최근 이 문제를 깔끔하게 해결하기 위해 가벼운 독자 노선을 걷는 마스트라(Mastra) 같은 TypeScript 네이티브 엔진과, 파이썬의 강력한 기능을 결합한 하이브리드 아키텍처가 큰 주목을 받고 있습니다.
Mastra: 웹 개발자를 위해 가벼워진 TypeScript 에이전트 엔진
마스트라는 무겁고 복잡한 기존 에이전트 프레임워크의 대안으로 떠오른 가벼운 TypeScript 네이티브 엔진입니다. 그동안 간단한 에이전트 기능을 하나 만들려고 해도 무거운 파이썬 백엔드를 따로 띄우고 API 레이어를 설계해야 했던 개발자들에게 아주 유용합니다. 복잡한 인프라 설정 없이 Node.js 환경에서 직접 실행되므로 네트워크 지연이 줄어들고 구동 속도가 빠릅니다.
가장 큰 장점은 프론트엔드 개발자들에게 익숙한 도구들과 완벽하게 어우러진다는 점입니다. 대표적으로 Vercel AI SDK와 매끄럽게 연동되어, 에이전트의 실시간 실행 과정을 웹 화면에 곧바로 보여줄 수 있습니다. 복잡한 상태 동기화나 클라이언트 통합 과정을 획기적으로 덜어내 주어, 오직 사용자 경험에만 집중할 수 있게 돕습니다.
"Python이 찾고, TS가 보낸다" — 실전 하이브리드 아키텍처
실서비스를 구축하는 많은 에이전트 개발팀 사이에서 요즘 가장 현실적이면서도 강력한 표준으로 자리 잡은 아키텍처가 있습니다. 바로 "파이썬이 찾고, TypeScript가 보낸다"는 하이브리드 전략입니다.
고성능 인공지능 모델을 돌리거나 무거운 데이터를 연산하는 작업은 GPU 자원을 바로 쓸 수 있는 파이썬 환경이 압도적으로 유리합니다. 반면, 사용자가 실제로 접속하는 화면을 빠르게 띄우고 실시간 대화 상태를 매끄럽게 유지하는 일은 웹 생태계의 절대 강자인 TypeScript가 훨씬 잘합니다.
이 구조에서는 파이썬이 복잡한 AI 추론과 데이터를 처리해 결과를 찾아내면, Node.js나 Vercel AI SDK 같은 TypeScript 기반의 오케스트레이터가 이를 넘겨받아 클라이언트에 빠르게 배달합니다. 각 언어가 가장 잘하는 핵심 영역에만 온전히 집중하게 만드는 방식입니다.
덕분에 개발팀은 웹 서비스의 성능을 올리기 위해 굳이 무거운 파이썬 백엔드 설정을 붙잡고 골머리를 앓을 필요가 없어집니다. 서비스의 속도와 AI의 지능을 둘 다 영리하게 챙길 수 있는 최선의 선택지인 셈입니다.
서로 다른 언어를 매끄럽게 잇는 기술들: AG-UI와 pctx-py
서로 다른 프로그래밍 언어를 쓰는 시스템을 하나로 매끄럽게 조율하는 일은 늘 까다롭습니다. 이를 위해 최근 실무진 사이에서는 에이전트 사용자 상호작용(AG-UI) 프로토콜과 포트 오브 콘텍스트(pctx-py) 같은 지능형 가교들이 빠르게 자리를 잡아가고 있습니다.
AG-UI(Agent-User Interaction) 프로토콜은 백엔드 에이전트와 웹 클라이언트 사이의 실시간 토큰 스트리밍과 도구 호출 과정을 표준화해 줍니다. 덕분에 개발팀은 화면 동기화나 대화 상태 관리를 위해 별도의 맞춤형 웹소켓 코드를 매번 처음부터 다시 작성할 필요가 없어졌습니다.
여기에 모델 컨텍스트 프로토콜(MCP)과 파이썬 도구를 함께 융합해 주는 pctx-py는 실전 성능 최적화의 핵심 역할을 담당합니다. 기존 에이전트는 도구를 하나씩 호출할 때마다 매번 결과를 거쳐 다시 LLM에 보내고 다음 동작을 지시받아야 했습니다. 이는 데이터 양이 많아질수록 API 토큰을 극심하게 낭비하고 반응 속도를 떨어뜨리는 고질적인 원인이었습니다.
pctx-py는 에이전트가 단 한 번의 요청으로 파이썬 데이터 로직과 외부 MCP 서버 도구를 아우르는 TypeScript 코드를 직접 생성하게 만듭니다. 그리고 이를 격리된 로컬 샌드박스 환경에서 단숨에 묶어 실행하는 '코드 모드'를 지원함으로써 비효율적인 통신 루프를 과감하게 생략합니다.
다음은 에이전트가 생성해 격리된 샌드박스에서 단 한 번의 실행으로 파이썬 분석 모델과 외부 API를 동시에 조율하는 TypeScript 코드 예시입니다.
불필요한 데이터 유출이나 컨텍스트 낭비 없이, 샌드박스 내부에서 파이썬과 외부 서비스를 물 흐르듯 결합해 뛰어난 토큰 효율성과 빠른 대기 시간을 확보할 수 있습니다.
타입 안전성을 보장하는 RPC 연동과 PyFlow.ts
파이썬에서 정성껏 만든 머신러닝 모델이나 비즈니스 로직을 TypeScript 환경으로 가져올 때, 가장 번거로운 일은 무엇일까요? 바로 API 엔드포인트를 일일이 설계하고 양쪽의 데이터 타입을 수동으로 맞춰주는 작업입니다. 파이썬 코드가 조금만 바뀌어도 TypeScript의 타입이 깨져서 런타임 에러나 컴파일 에러를 유발하기 일쑤입니다.
이 문제를 깔끔하게 해결해 주는 도구가 바로 PyFlow.ts입니다. PyFlow.ts는 파이썬 함수나 클래스에 데코레이터를 붙이는 것만으로 백엔드 API와 이에 대응하는 TypeScript 클라이언트 코드를 자동으로 생성해 줍니다.
파이썬 코드에 데코레이터를 추가하여 연동하는 방법은 다음과 같이 매우 간단합니다.
이렇게 데코레이터만 달아두면 내부적으로 FastAPI 서버가 구성되고 이에 대응하는 TypeScript 클라이언트 코드까지 함께 빌드됩니다.
덕분에 TypeScript 오케스트레이터 측에서는 마치 로컬 함수를 불러오듯 자동 완성을 지원받으며 파이썬 로직을 안전하게 호출할 수 있습니다. 수동으로 API 명세서를 갱신하고 클라이언트를 재생성하느라 낭비되던 엔지니어링 리소스를 획기적으로 줄여주는 실용적인 해결책입니다.
더 가벼운 도구로 영리하게 시작하기
모든 기능을 하나의 언어나 거대한 시스템에 전부 우겨넣을 필요는 없습니다. 마스트라처럼 가벼운 오케스트레이터와 신뢰할 수 있는 전송 프로토콜을 활용하면, 파이썬의 강력한 인공지능 자산을 그대로 살리면서도 부드럽고 빠른 웹 서비스를 완성할 수 있습니다.
지금 준비 중인 에이전트 서비스가 있다면 시스템을 무리하게 하나로 합치느라 힘 빼지 마세요. 각 언어의 강점만 영리하게 골라 쓰는 실용적인 하이브리드 조합이 개발 속도와 사용자 경험을 모두 잡는 가장 확실한 지름길입니다.