TypeScript를 사용한 Robinhood 트레이딩 MCP 리스크 게이트웨이 구축하기

AI
 ↓
주문하기(Place Order)

AI 에이전트 (AI Agent)
   ↓
트레이딩 MCP (Trading MCP)
...

사용자:
"이 주식 $5,000어치 사줘." 

symbol = XYZ
side = buy
amount = $5,000

최대 주문액(maximum order) = $1,000

AI 에이전트 (AI Agent)
   ↓
거래 의도 (Trade Intent)
...

+----------------------+ 
| AI 에이전트 (AI Agent) | 
+----------+-----------+
...

Read
----
get_accounts
...

Write
-----
place order
...

robinhood-mcp-risk-gateway/
├── src/
│   ├── agent/
...

type TradeIntent = {
  symbol: string;
  side:

자유 형식(Free-form): 

구조화된(Structured): 

두 번째 방식은 검증하기가 쉽습니다.

예를 들어:

하지만:

이것은 테스트하기가 훨씬 쉽습니다.

## 리스크 정책 (Risk policy)

리스크 정책은 결정론적(deterministic)이어야 합니다.

기본 모델:

리스크 엔진은 다음을 평가할 수 있습니다:

정확한 규칙은 나중에 확장될 수 있습니다.

## 리스크 평가 (Risk evaluation)

핵심 API는 작을 수 있습니다:

그리고 다음 함수를 정의할 수 있습니다:

출력은 거래가 승인되거나 거부된 이유를 설명해야 합니다.

## 예시 리스크 검사 (Example risk checks)

거래는 다음과 같은 과정을 거칠 수 있습니다:

필요한 모든 검사를 통과했을 때만 거래가 계속됩니다.

## 심볼 화이트리스트 (Symbol allowlists)

간단한 제어 방법 중 하나는 에이전트가 거래할 수 있는 자산을 제한하는 것입니다.

예를 들어:

그리고 다음 로직을 사용할 수 있습니다:

이것은 의도적으로 지루합니다.

리스크 제어는 지루해야 합니다.

## 포지션 제한 (Position limits)

만약 애플리케이션에 다음과 같은 것이 있다고 가정해 봅시다:

그리고 현재 포지션이 다음과 같다고 합시다:

새로운 주문인:

은 노출도를 설정된 한도 이상으로 증가시키기 때문에 실패해야 합니다.

중요한 부분은 결정이 결정론적이라는 것입니다.

## 포트폴리오 노출도 (Portfolio exposure)

게이트웨이는 또한 포트폴리오 수준의 제약 조건을 강제할 수 있습니다.

예를 들어:

에이전트는 여전히 다른 기술 거래를 제안할 수 있습니다.

위험 엔진(risk engine)이 이를 거부합니다.

이는 포트폴리오 인지 실행 경계(portfolio-aware execution boundary)를 만듭니다:

## 일일 손실 통제 (Daily loss controls)

또 다른 유용한 안전장치는 일일 손실 한도입니다.

예를 들어:

애플리케이션이 임계값에 이미 도달했음을 감지하면:

에이전트는 정책을 무시할 수 없습니다.

## 도구 권한 (Tool permissions)

위험(risk)은 한 가지 계층일 뿐입니다.

에이전트는 또한 권한이 필요합니다.

저는 다음과 같은 기능을 모델링합니다:

그런 다음 어떤 에이전트가 어떤 기능을 가지고 있는지 정의합니다.

예를 들어:

리서치 에이전트는 다음과 같을 수 있습니다:

실행(execution) 에이전트에게는 명시적으로 필요한 쓰기 권한(write permissions)의 더 좁은 세트를 부여할 수 있습니다.

## 사용자 승인 (Human approval)

Robinhood는 현재 에이전트 기반 거래를 위한 거래 승인을 지원합니다. 승인이 활성화된 경우, 에이전트는 거래를 제안할 수 있지만 사용자가 Robinhood에서 검토하고 수동으로 체결해야 합니다. 승인이 비활성화된 경우, 적격한 거래는 각 주문에 대한 수동 확인 없이 에이전트에 의해 체결될 수 있습니다. Robinhood는 특정 거래의 경우 여전히 승인이 필요할 수 있다고 언급합니다.

이는 두 가지 애플리케이션 모드와 자연스럽게 매핑됩니다.

### 지원 모드 (Assisted mode)

### 자동화 모드 (Automated mode)

저는 지원 모드를 먼저 구축할 것입니다.

## 승인 상태 (Approval state)

애플리케이션은 승인을 명시적으로 나타낼 수 있습니다:

거래 생명주기(trade lifecycle)는 다음과 같아집니다:

또는:

이것은 실행 경로를 감사(audit)하기 쉽게 만듭니다.

## 주문 상태 (Order state)

주문이 제출되면, 애플리케이션은 여전히 이를 추적해야 합니다.

유용한 상태 기계(state machine):

id="robinhood-order-state"
PROPOSED
   ↓
...

Failure paths:

중요한 구별점은 다음과 같습니다:

대 비(versus):

후자는 실제 실행 상태를 요구합니다.

## 감사 로깅 (Audit logging)

의미 있는 모든 에이전트 액션은 감사 기록을 생성해야 합니다.

예를 들어:

목표는 다음 질문에 답하는 것입니다:

> 이 주문이 왜 발생했나요?

감사 추적(audit trail)은 우리가 다음을 재구성할 수 있도록 해야 합니다:

## AI는 게이트웨이를 우회해서는 안 됩니다 (The AI should not bypass the gateway)

아키텍처는 하나의 실행 경로를 강제해야 합니다.

다음과 같지 않게:

대신:

거래 액션으로 가는 명확하게 정의된 경로가 하나 있어야 합니다.

이렇게 하면 권한 관리, 로깅, 테스트 및 모니터링이 훨씬 쉬워집니다.

## 시장 데이터 및 계정 데이터 (Market data and account data)

Robinhood의 현재 에이전트 도구에는 계정(account), 포트폴리오(portfolio), 관심 종목(watchlist), 시장 데이터(market-data), 주식(equities), 옵션(options), 암호화폐(crypto), 스캐너(scanner), 알림(alerts) 및 고급 주문 기능이 포함됩니다.

이는 에이전트가 여러 출처로부터 잠재적으로 결정을 구축할 수 있음을 의미합니다:

중요한 엔지니어링 경계는 여전히 다음과 같습니다:

## 포트폴리오 인식 실행 (Portfolio-aware execution)

단순한 트레이딩 봇은 다음만 알 수도 있습니다:

포트폴리오 인식이 가능한 에이전트는 다음을 통합할 수 있습니다:

예를 들어:

에이전트가 한도를 기억하도록 신뢰할 필요는 없습니다. 정책 엔진이 이를 강제합니다.

## 예시 워크플로우 (Example workflow)

다음은 시작부터 끝까지의 예시입니다:

이것이 제가 GitHub 프로젝트에서 시연하고 싶은 아키텍처입니다.

## TypeScript 서비스 경계 (TypeScript service boundary)

핵심 서비스는 하나의 주요 작업을 가질 수 있습니다:

async function processTradeIntent(intent: TradeIntent): Promise<TradeDecision> {...

가장 중요한 부분은 AI 모델이 브로커에게 직접 호출하지 않는다는 것입니다.

대신, 애플리케이션의 통제된 파이프라인에 타입이 지정된 요청을 제출합니다.

## 리스크 규칙 테스트 (Testing risk rules)

리스크 로직은 높은 수준으로 테스트 가능해야 합니다.

예를 들어:

포지션 제한: 

심볼 제한: 

일일 손실액: 

테스트는 경계 값(boundary values)을 포함해야 합니다.

## 권한 테스트 (Testing permissions)

권한 테스트는 에이전트가 가지고 있지 않은 도구를 사용할 수 없음을 검증해야 합니다.

예를 들어:

하지만:

이는 권한 계층에 간단하고 결정론적인 계약(deterministic contract)을 제공합니다.

## 승인 흐름 테스트 (Testing approval flows)

두 가지 모드를 모두 테스트해야 합니다.

지원됨(Assisted):

거부됨(Rejected):

자동화됨(Automated):

이러한 테스트는 실제 AI 모델과 독립적이어야 합니다.

## 실패 경로 테스트 (Testing failure paths)

시스템은 다음 상황도 처리해야 합니다:

목표는 AI가 완벽해 보이게 만드는 것이 아닙니다.

목표는 AI 또는 외부 인프라가 불완전할 때 주변 시스템이 예측 가능하게 동작하도록 만드는 것입니다.

## 시크릿 및 계정 보안 (Secrets and account security)

게이트웨이는 비밀(secrets)을 무심코 저장하는 장소가 되어서는 안 됩니다.

다음은 하지 마세요:

환경 변수나 적절한 비밀 관리 계층(secret-management layer)을 사용하세요.

리포지토리는 다음을 포함해야 합니다:

하지만 실제 자격 증명(actual credentials)은 절대 포함해서는 안 됩니다.

## 이 아키텍처가 재사용 가능한 이유 (Why this architecture is reusable)

리스크 게이트웨이는 하나의 전략에 국한될 필요가 없습니다.

다음 아래에 위치할 수 있습니다:

에이전트만 변경됩니다.

제어 장치는 그대로 유지됩니다.

## 더 큰 아키텍처

이 프로젝트는 더 큰 트레이딩 시스템의 일부입니다:

                     사용자 (USER)
                       |
                       v

게이트웨이는 제어 지점(control point)입니다.

## 이것이 전통적인 트레이딩 봇과 다른 이유

전통적인 봇은 종종 다음과 같은 형태를 보입니다:

제어된 에이전트 기반(agentic) 트레이딩 시스템은 다음과 같은 형태에 더 가깝습니다:

## 이것은 근본적으로 다른 엔지니어링 문제입니다.

## 고객에게 증명할 수 있는 것

가치 있는 진술은 다음과 같지 않습니다:

> "저는 ChatGPT를 Robinhood에 연결할 수 있습니다." 

더 강력한 진술은 다음과 같습니다:

> **"저는 AI 트레이딩 에이전트를 둘러싼 제어된 인프라를 구축할 수 있습니다."**

여기에는 다음이 포함됩니다:

이는 실제 트레이딩 제품이 요구하는 것과 훨씬 가깝습니다.

## 최종 아키텍처