tambo 딥다이브
— AI의 선택을 내가 만든 React 화면으로 바꾸는 법

1프로젝트 한줄 요약

tambo는 개발자가 등록한 React 컴포넌트를 AI가 선택하고, 그 컴포넌트의 props를 스트리밍으로 채우도록 돕는 생성형 UI 도구 모음입니다. “AI가 UI를 만든다”는 표현만으로는 핵심을 놓치기 쉽습니다. 여기서 기본 흐름은 새 React 소스 파일을 생성하는 일이 아닙니다. 화면의 코드는 개발자가 준비하고, AI는 사용할 화면의 이름과 그 화면에 넣을 데이터를 결정합니다.

1-1. 한 번의 요청을 다섯 단계로 보기

1. 개발자가 컴포넌트 함수, 이름, 설명, propsSchema를 등록합니다.
2. SDK가 컴포넌트 메타데이터와 사용자 메시지를 API로 보냅니다.
3. 백엔드가 모델에 사용할 UI 도구와 대화 이력을 전달합니다.
4. 모델이 고른 컴포넌트와 props 변경분이 이벤트로 내려옵니다.
5. 브라우저가 이벤트를 상태로 누적하고 등록된 React 컴포넌트를 렌더링합니다.

이 연결은 react-sdk/src/providers/tambo-registry-provider.tsx의 registerComponent(), packages/client/src/utils/registry-conversion.ts의 toAvailableComponent(), react-sdk/src/v1/components/v1-component-renderer.tsx의 ComponentRenderer에서 확인할 수 있습니다.

1-2. SDK와 서버는 서로 다른 부품이다

따라서 SDK만 읽으면 컴포넌트 사용법은 배울 수 있지만, 대화가 저장되거나 동시 실행이 막히는 원리는 보이지 않습니다. 이 글은 브라우저부터 데이터베이스까지 연결해 읽습니다.

2왜 주목받는가

2-1. 챗봇의 답변이 제품의 실제 화면으로 이어진다

일반적인 채팅 UI에서는 “이번 달 매출이 1,250만 원입니다”라는 답변이 끝입니다. tambo에서는 같은 요청이 매출 카드나 차트의 입력값으로 연결됩니다. 이미 만든 디자인 시스템을 활용할 수 있고, 사용자가 결과 화면에서 다음 행동을 할 수 있다는 점이 관심을 끌 만합니다.

TrendShift Daily #29는 2026-10-23 기준 순위입니다. 아래 설명은 구현에 근거한 주목할 만한 설계에 대한 해석입니다. 순위만으로 인기의 원인이나 실제 사용 기업 수를 판단할 수는 없습니다.

2-2. 연결해야 할 여러 문제를 한 저장소에서 공부할 수 있다

도구 호출을 UI에 연결하려면 컴포넌트 목록, 입력 양식, 생성 중인 JSON, 대화 저장, 실행 취소가 필요합니다. tambo는 이를 SDK와 서버로 나눠 구현합니다. 이 레포의 학습 가치는 모델 호출 한 줄보다, 모델의 불완전한 응답을 제품 상태로 바꾸는 연결부에 있습니다.

이 표는 사용 방식과 개발자가 맡는 일을 비교한 것입니다. 타 제품에 관한 설명의 출처는 이 커밋의 README입니다. 특히 README의 경쟁 비교표에는 백엔드까지 MIT라고 적힌 행이 있으나 실제 Cloud 패키지는 Apache-2.0입니다. MCP 지원 유무나 특정 프레임워크 종속성에 관한 타 제품 평가는 그대로 옮기지 않았습니다.

2-3. 생성되는 화면과 계속 수정되는 화면을 구분한다

README 예시에는 withInteractable이라는 이름이 남아 있습니다. 그러나 이 커밋의 공개 진입점인 react-sdk/src/v1/index.ts에서 내보내는 이름은 withTamboInteractable입니다. 예제를 붙여 넣기 전에 패키지 버전과 공개 진입점을 읽는 습관을 배울 수 있는 사례입니다.

3기술 스택 전체 지도

다음 버전은 커밋 6e2c1bf의 의존성 파일 기준입니다. ^는 고정 버전이 아니라 허용 범위이고, package-lock.json은 구체적인 의존성 버전을 기록합니다. package.json의 선언 범위, 루트 overrides, 잠금 파일에 기록된 버전을 함께 봐야 실제 의존성 구성을 이해할 수 있습니다.

3-1. 프론트엔드와 React SDK

패키지 버전도 구별해야 합니다. @tambo-ai/react는 1.4.0, @tambo-ai/client는 1.3.0, Cloud 웹은 0.136.0, API는 0.146.1입니다. 릴리스 이름 web-v0.136.0을 React SDK의 버전으로 읽으면 안 됩니다.

3-2. 백엔드·데이터 저장

3-3. 인프라·빌드·검증

turbo.json의 build.dependsOn: ["^build"]는 의존 패키지를 먼저 빌드하라는 뜻입니다. API 개발 작업은 interruptible: true이며 core·backend·db의 소스 변경을 입력으로 지정합니다. React SDK는 CJS와 ESM 출력을 따로 만들고, API Dockerfile은 turbo prune으로 필요한 워크스페이스를 추립니다.

4아키텍처 심화 분석

4-1. 먼저 전체 시스템 지도를 펼치기

위 그림은 일반 LLM 경로를 중심으로 단순화한 것입니다. V1Service.executeRun()은 ThreadsService.advanceThread()와 비동기 큐를 연결하고, TamboBackend.runDecisionLoop()는 설정된 클라이언트 종류에 따라 일반 결정 루프 또는 에이전트 경로를 선택합니다. MCP 서버도 연결 위치에 따라 브라우저 쪽과 서버 쪽 경로가 달라질 수 있습니다.

API와 React 사이에 있는 @tambo-ai/typescript-sdk는 이 레포의 워크스페이스가 아닌 외부 패키지입니다. 메시지 전송 훅과 범용 클라이언트가 이 패키지의 메서드를 호출합니다. API 동작을 읽을 때는 호출부와 외부 패키지 내부 구현을 구분해야 합니다.

4-2. 패턴 ① 등록 목록과 스키마로 실행 경계 만들기

registerComponent()는 validateAndPrepareComponent()로 이름과 스키마를 확인한 뒤 실제 React 함수와 직렬화된 props 정의를 목록에 저장합니다. 서버로 전송할 때 toAvailableComponent()는 이 중 이름·설명·JSON Schema만 추립니다.

// packages/client/src/utils/registry-conversion.ts 발췌
return {
  name: component.name,
  description: component.description,
  propsSchema: component.props,
};

함수 자체를 JSON으로 보내지 않는 것이 핵심입니다. 모델은 “이름이 SalesCard인 화면이 있고 이런 입력을 받는다”는 설명을 보고 선택합니다. 브라우저는 응답의 이름으로 로컬 목록에서 진짜 함수를 찾습니다.

ComponentRenderer는 getComponentFromRegistry()로 대상을 찾고 React.createElement(registeredComponent.component, validatedProps)로 요소를 만듭니다. 알 수 없는 이름 등으로 이 과정에서 예외가 나면 로그를 남기고 기본값 null 또는 지정된 대체 화면을 반환합니다.

학습 질문: React 함수와 전송용 설명을 한 객체에서 출발시킨 뒤 왜 따로 분리할까요? 브라우저 전용 코드, 직렬화 가능한 데이터, 신뢰할 수 없는 모델 출력을 각각 구분해 보세요.

4-3. 패턴 ② 부분 입력을 변경 이벤트로 바꾸는 스트리밍 어댑터

packages/backend/src/services/decision-loop/decision-loop-service.ts의 runDecisionLoop()는 UI 도구를 분류하고, 시스템 메시지와 이력을 준비한 다음 llmClient.complete({ stream: true, ... })를 호출합니다. AISdkClient는 AI SDK의 streamText() 결과인 fullStream을 순회합니다.

UI 도구 이름에는 show_component_ 접두사가 쓰입니다. 예를 들어 모델의 도구 입력이 한 글자씩 도착하면 {"title":"서처럼 아직 완성되지 않은 JSON이 생깁니다. 여기서 매번 JSON.parse()만 호출하면 계속 실패하므로, 생성 중인 상태를 다룰 별도 경로가 필요합니다.

// 교육용 흐름 예시: 아직 닫히지 않은 입력도 도착할 수 있습니다.
도착 조각 1: {"title":"서
도착 조각 2: 울 매출","amount":
도착 조각 3: 1250}

시작: tambo.component.start
변경: tambo.component.props_delta
완료: tambo.component.end

packages/backend/src/util/component-streaming.ts의 ComponentStreamTracker.processJsonDelta()는 조각을 누적하고 partial-json으로 현재 해석 가능한 객체를 얻습니다. 이전 객체와 비교해 변경분을 JSON Patch로 내보냅니다. finalize()에서는 완성된 입력을 JSON.parse()로 읽고 객체인지 확인합니다.

부분 해석은 입력을 끝까지 검증했다는 뜻이 아닙니다. props별 완료 상태도 “새 속성이 나타났는가” 같은 스트리밍 규칙으로 추적합니다. 화면은 중간에 없는 필드와 바뀌는 문자열을 견뎌야 하며, 저장·결제처럼 확정 입력이 필요한 작업은 이 중간 상태에 바로 연결하면 안 됩니다.

// JSON Patch의 교육용 예시
기존 props: {"title":"서울","amount":1000}
변경 목록: [{"op":"replace","path":"/amount","value":1250}]
적용 결과: {"title":"서울","amount":1250}

createJsonPatchPath()는 키에 들어 있는 /와 ~를 JSON Pointer 규칙대로 이스케이프합니다. 예를 들어 속성 이름이 sales/kr라면 경로는 /sales~1kr입니다. 단순히 슬래시를 붙이는 코드와 표준을 지키는 코드의 차이를 배울 수 있습니다.

누적 크기 제한 상수는 10 * 1024 * 1024입니다. 소스 주석은 10MB라고 부르지만 실제 비교는 delta.length의 누적값이므로 엄밀한 UTF-8 바이트 수 제한과는 다릅니다. 설정값뿐 아니라 그 값을 어떤 단위로 비교하는지도 읽어야 합니다.

4-4. 패턴 ③ 이벤트와 리듀서로 화면 상태 재구성하기

packages/client/src/utils/event-accumulator.ts의 streamReducer(state, action)는 실행 시작·완료, 텍스트 조각, 도구 호출, 컴포넌트 변경 이벤트를 현재 대화 상태에 적용합니다. React 쪽 TamboStreamProvider는 이 함수를 useReducer()에 연결합니다.

스트리밍 UI는 문자열을 길게 만드는 작업이 아니라, 이벤트 순서에 맞춰 같은 화면의 상태를 계속 갱신하는 작업입니다.

새 대화는 PLACEHOLDER_THREAD_ID = "placeholder"로 시작합니다. 메시지를 바로 보여 준 뒤 RUN_STARTED에서 실제 thread ID를 받으면, 리듀서는 임시 메시지를 실제 대화로 옮기고 임시 대화를 비웁니다. 사용자가 이미 다른 대화로 이동했다면 현재 선택을 무조건 빼앗지 않도록 조건도 둡니다.

// 교육용 의사 코드: 실제 함수는 streamReducer()
state = reducer(state, 사용자_메시지_이벤트);
state = reducer(state, 실제_대화_ID를_담은_RUN_STARTED);
state = reducer(state, 컴포넌트_시작_이벤트);
state = reducer(state, props_변경_이벤트);
state = reducer(state, 컴포넌트_완료_이벤트);

props 변경에는 applyJsonPatch()를 쓰며, 내부의 applyPatch(target, operations, true, false)는 패치 검증을 켜고 원본 직접 수정을 끕니다. 같은 객체를 몰래 바꾸면 React의 변경 감지와 이전 상태 비교가 꼬일 수 있기 때문입니다.

범용 TamboClient에는 getState()와 subscribe()도 있습니다. 외부 상태 저장소 형태를 배우기 좋은 코드지만, 현재 React 스트림 Provider의 실제 구현은 useReducer입니다. 인터페이스가 useSyncExternalStore와 호환된다는 설명을 곧바로 “현재 React SDK가 그 훅을 쓴다”로 바꾸면 안 됩니다.

ComponentRenderer의 안내처럼 렌더링 목록의 key를 content.id로 안정적으로 유지하는 것도 중요합니다. props가 갱신될 때마다 다른 key를 주면 같은 카드가 새 카드로 교체되어 입력 상태를 잃을 수 있습니다.

4-5. 패턴 ④ 가드와 원자적 DB 갱신으로 실행 수명 관리하기

이벤트 처리가 정확해도 같은 대화에서 두 요청이 동시에 모델을 돌리면 상태가 충돌할 수 있습니다. V1Service.startRun()는 트랜잭션 안에서 실행 잠금을 획득하고, 도구 결과 저장·대기 도구 목록 정리·실행 생성·현재 run ID 설정을 묶습니다.

// packages/db/src/operations/runs.ts의 acquireRunLock() 핵심을 단순화
UPDATE threads
SET run_status = 'waiting'
WHERE id = :threadId AND run_status = 'idle'
RETURNING id;

실제 코드는 Drizzle 쿼리이며 위 SQL은 원리를 설명한 것입니다. 조회 후 따로 “실행 중”이라고 쓰는 대신 아직 idle일 때만 갱신합니다. 갱신된 행이 없으면 잠금을 얻지 못한 것입니다. 대기 중이던 도구 호출 목록도 스냅샷과 일치할 때만 지워, 중간에 바뀐 상태를 덮어쓰지 않습니다.

releaseRunLockIfCurrent()는 currentRunId === runId인 경우에만 잠금을 풉니다. 오래된 실행의 취소 처리가 뒤늦게 도착해 새 실행의 잠금을 풀어 버리는 문제를 막는 조건입니다.

이보다 앞에서는 V1ThreadInProjectGuard.canActivate()가 ensureThreadByProjectId()를 통해 프로젝트와 사용자 contextKey에 맞는 대화인지 확인합니다. API 키가 있다고 모든 사용자의 대화를 읽을 수 있게 해서는 안 됩니다. userKey 문자열 자체가 브라우저 사용자의 신원을 증명하는 토큰은 아니라는 점도 구별해야 합니다.

응답 경계도 세심합니다. V1Controller.createRun()은 Content-Type: text/event-stream으로 스트림을 열고 응답 완료 전에 연결이 닫히면 cancelRun()을 요청합니다. 헤더를 보낸 뒤 생긴 오류는 새 HTTP 오류 응답 대신 RUN_ERROR 이벤트로 보냅니다.

4-6. 클라이언트 도구를 만나면 어디로 돌아갈까

모든 도구가 서버에서 실행되는 것은 아닙니다. react-sdk/src/v1/hooks/use-tambo-v1-send-message.ts는 입력 대기 이벤트를 만나면 executeAllPendingTools()로 등록된 클라이언트 도구를 실행합니다. executeToolsAndContinue()는 결과와 previousRunId를 담아 다음 스트림을 요청합니다.

범용 클라이언트에도 같은 책임을 가진 packages/client/src/utils/send-message.ts가 있습니다. 이 구현에서는 완료되지 않은 도구의 ID를 추적한 후 결과를 다음 요청에 연결합니다. “한 번의 질문 = 한 번의 HTTP 요청”으로만 생각하면 이 왕복을 이해하기 어렵습니다.

컴포넌트 props는 화면을 그리기 위한 입력이고, 도구는 데이터를 가져오거나 동작을 수행하는 함수입니다. 두 가지가 모두 모델의 도구 호출 형식과 연결될 수 있어도, 실제 실행 장소와 부작용은 구분해서 설계해야 합니다.

5디렉토리 구조 해부

위 트리는 학습에 필요한 부분만 추렸습니다. package.json이 있는 저장소 루트를 기준으로 모든 파일 경로를 표기합니다.

5-1. 처음부터 끝까지 읽지 말고 요청 한 건을 추적하기

1. react-sdk/src/index.ts에서 공개 API의 실제 출발점을 확인합니다.
2. react-sdk/src/v1/providers/tambo-v1-provider.tsx에서 Provider 조합을 봅니다.
3. react-sdk/src/v1/hooks/use-tambo-v1-send-message.ts에서 메시지 전송과 도구 왕복을 읽습니다.
4. packages/client/src/utils/event-accumulator.ts에서 상태가 바뀌는 규칙을 읽습니다.
5. apps/api/src/v1/v1.controller.ts·apps/api/src/v1/v1.service.ts에서 서버 경계를 봅니다.
6. packages/backend/src/util/component-streaming.ts에서 모델 조각이 UI 이벤트가 되는 지점을 찾습니다.

문서를 먼저 읽더라도 마지막에는 export와 호출부로 돌아오세요. 이 커밋의 react-sdk/AGENTS.md는 예전 Provider 계층을 설명하는 부분이 있지만, 실제 공개 경로는 v1입니다. 설계 설명과 현재 구현을 대조하는 습관 자체가 중요한 학습입니다.

5-2. 추적 파일 기준 코드 규모

git ls-files의 추적 파일 목록을 확장자로 분류한 물리 줄 수입니다. 마지막 개행이 없는 파일의 마지막 줄도 1줄로 계산했습니다. 빈 줄·주석·타입 선언·테스트·예제·추적된 생성 코드가 포함되며, 의존성 설치물·Git 내부 파일·JSON 잠금 파일·Markdown·스냅샷은 이 표에서 제외했습니다.

TS·TSX 합계는 221,434줄입니다. 그중 파일명에 .test. 또는 .spec.가 있는 파일은 약 38.9%입니다. 이것은 실행 커버리지가 아닙니다. 테스트 줄 수가 많다고 모든 분기가 검증되었다고 단정할 수 없습니다.

패키지별로는 TS·TSX 기준 apps/web 45,016줄, apps/api 40,246줄, react-sdk 39,319줄, packages/backend 14,117줄, packages/client 8,558줄입니다. 각 값에도 테스트가 포함됩니다.

6학습 포인트 (기술별)

6-1. React: Context 조합과 부분 입력에 강한 컴포넌트

TamboProvider는 단일 기능을 가진 여러 Provider를 조합합니다. 등록 목록, 인증, MCP, 상호작용, 스트리밍, 입력 상태를 하나의 거대한 훅에 전부 넣지 않습니다. 먼저 각 Provider가 무엇을 제공하는지 표로 적고, 그 값을 읽는 훅으로 화살표를 그려 보세요.

다음은 소스의 등록 형태를 따른 교육용 예시입니다. 모델을 호출하지 않고도 “데이터가 아직 덜 왔을 때 화면이 어떻게 보일까”를 생각할 수 있습니다. 아래 컴포넌트는 빈 값과 일부만 도착한 props도 표시하도록 구성했습니다.

import { z } from "zod";
import type { TamboComponent } from "@tambo-ai/react";

const salesSchema = z.object({
  title: z.string().describe("카드에 표시할 매출 제목"),
  amount: z.number().describe("매출액, 단위는 만 원"),
});

type SalesProps = z.infer<typeof salesSchema>;

function SalesCard({ title, amount }: Partial<SalesProps>) {
  const shownTitle = title ?? "매출을 불러오는 중";
  const shownAmount = typeof amount === "number"
    ? `${amount.toLocaleString("ko-KR")}만 원`
    : "집계 중";

  return (
    <section>
      <h3>{shownTitle}</h3>
      <p>{shownAmount}</p>
    </section>
  );
}

export const components: TamboComponent[] = [
  {
    name: "SalesCard",
    description: "지역별 또는 기간별 매출 금액 한 개를 표시한다",
    component: SalesCard,
    propsSchema: salesSchema,
  },
];

Partial<SalesProps>는 컴포넌트가 중간 입력을 받아도 표시를 유지하도록 한 교육용 선택입니다. 스키마의 최종 필드 요구와 화면의 중간 표시 정책은 서로 다른 책임입니다. 금액이 0일 때도 정상 표시되도록 진릿값 검사 대신 숫자 타입을 확인한 이유도 설명해 보세요.

6-2. TypeScript: 타입 추론과 실행 시 검증의 차이

z.infer는 스키마로부터 개발 중 타입을 얻습니다. 그러나 네트워크로 온 JSON이 그 타입을 지키는지는 별도로 확인해야 합니다. validateTool()의 속성 확인과 streamReducer()의 이벤트별 분기를 비교하면 “외부 입력을 확인하는 코드”와 “확인된 타입을 좁혀 사용하는 코드”의 차이가 보입니다.

실습 아이디어: 가짜 이벤트 세 개를 종이에 적고 type 값에 따라 어떤 속성을 읽을 수 있는지 표시하세요. RUN_STARTED의 thread ID와 텍스트 이벤트의 message ID가 왜 서로 다른지 설명할 수 있어야 합니다.

6-3. 스키마: 하나의 정의를 여러 소비자에 맞게 바꾸기

propsSchema는 개발자가 작성하기 편한 정의이고, API에 실리는 propsSchema는 JSON으로 직렬화할 수 있는 설명입니다. validateAndPrepareComponent()와 toAvailableComponent()를 차례로 읽어 같은 이름의 데이터가 어느 단계에서 어떤 형태로 바뀌는지 적어 보세요.

실습 아이디어: 필드 세 개짜리 스키마를 만들었다고 가정하고, 각 필드의 타입뿐 아니라 단위·허용 범위·설명문을 쓰세요. “금액”만 적는 것과 “원 단위의 세금 포함 금액”이라고 적는 것의 차이가 모델 선택과 데이터 해석에 영향을 줍니다.

6-4. 비동기 처리: AsyncIterator와 중간 오류

runDecisionLoop()는 async function*으로 여러 결과를 순차적으로 내보냅니다. 일반 Promise가 마지막 값 하나를 기다리는 방식이라면, 비동기 반복자는 도착하는 결과를 순서대로 처리하는 데 적합합니다. for await...of를 만날 때는 “무엇을 기다리며, 취소 신호는 어디로 전달되는가”를 함께 확인하세요.

실습 아이디어: 입력 조각이 오지 않는 경우, 중간에 끊기는 경우, 마지막 JSON이 틀린 경우를 나눠 적고 processJsonDelta()와 finalize() 중 어디에서 처리해야 할지 분류합니다.

6-5. 백엔드: HTTP 응답 수명과 DB 트랜잭션

일반 JSON API에서는 마지막에 성공 또는 실패를 한 번 돌려줍니다. SSE에서는 이미 보낸 결과를 되돌릴 수 없으므로 스트림 내부의 오류 표현이 필요합니다. V1Controller.createRun()의 headersSent 분기가 그 차이를 보여 줍니다.

DB에서는 startRun()의 트랜잭션 안과 밖을 구분해 보세요. 모델 응답이 끝날 때까지 긴 DB 트랜잭션을 유지하는 것과, 짧은 트랜잭션으로 실행 상태를 예약하는 것은 다릅니다. 여기서는 실행 준비를 원자적으로 묶은 뒤 스트리밍 작업을 이어 갑니다.

6-6. 테스트: 정상 결과보다 경계를 읽기

테스트를 읽을 때는 정답 문자열보다, 작성자가 어떤 실패 상황을 별도 사례로 남겼는지 먼저 보세요.

7하드웨어 / 시스템 요구사항

이 저장소는 자체 모델 가중치를 포함한 로컬 추론 엔진이 아닙니다. 기본적인 모델 응답 경로는 외부 제공자 호출입니다. tambo 소스를 공부하는 데 GPU는 필요 없고, 모델 실행 비용과 서버 운영 비용은 별도로 계산해야 합니다.

코드 규모만으로 필요한 RAM을 결정할 수는 없습니다. 동시 Next.js 빌드와 테스트, 컨테이너, 브라우저를 함께 켜는지에 따라 필요한 자원이 달라집니다. 코드 열람과 전체 서비스 운영에 필요한 자원을 구분해서 계획하세요.

7-1. 포트는 호스트와 컨테이너 안에서 다를 수 있다

SELF-HOSTING.md는 웹·API·PostgreSQL 세 서비스를 중심으로 설명하지만, 실제 docker-compose.yml에는 MinIO도 정의되어 있습니다. 첨부 파일 기능은 별도의 S3 설정을 확인해야 합니다. StorageConfigService.hasStorageConfig()는 클라이언트 구성, 비어 있지 않은 버킷, 서명용 비밀값을 확인합니다.

7-2. 키와 네트워크를 이해한 뒤 실행 계획 세우기

자체 호스팅 안내에는 DB 암호, API_KEY_SECRET, PROVIDER_KEY_SECRET, NEXTAUTH_SECRET, 모델 제공자 키 등이 등장합니다. 이 이름들은 비밀값의 역할을 구분하기 위한 것이며 실제 값을 공부자료에 복사할 필요는 없습니다.

브라우저에서 사용하는 Tambo용 프로젝트 키와 모델 제공자의 비밀 API 키도 구분해야 합니다. 제공자 비밀 키는 서버에서 관리합니다. API 요청의 사용자 소유권은 프로젝트 키만으로 해결되지 않으므로 실제 앱에서는 사용자 토큰과 권한 흐름까지 설계해야 합니다.

8직접 해볼 수 있는 실습 과제

아래 읽기 명령은 저장소 루트에서 실행합니다. 확장 실습은 별도 학습 프로젝트에서 진행하며, react-sdk/의 구현과 비교해 볼 수 있습니다. 제공자 API나 운영 서버에 요청하지 않아도 모든 과제의 핵심 원리를 확인할 수 있습니다.

실습의 합격 기준은 “AI가 그럴듯하게 답했다”가 아니라, 불완전한 입력과 실패 상황에서도 상태 변화를 설명할 수 있는가입니다.

{}
{"title":"서울"}
{"title":"서울","amount":0}
{"title":"서울","amount":1250}

키 sales/kr  -> 경로 /sales~1kr
키 rate~raw  -> 경로 /rate~0raw
키 ""        -> 경로 /

읽기 전용으로 호출부 찾기

# 저장소 루트에서 사용하는 읽기 명령
git rev-parse --short HEAD
rg -n 'export \*|TamboProvider' react-sdk/src/index.ts
rg -n 'registerComponent|validateAndPrepareComponent' react-sdk/src
rg -n 'processJsonDelta|finalize' packages/backend/src/util/component-streaming.ts
rg -n 'acquireRunLock|releaseRunLockIfCurrent' packages/db/src/operations/runs.ts

검색 결과가 많으면 이름을 하나 골라 정의 파일과 호출부를 번갈아 읽으세요. 함수 정의만 읽으면 입력이 어디서 왔는지 놓치고, 호출부만 읽으면 실패 조건을 놓칩니다.

9관련 기술 심화 학습 로드맵

주차는 학습 분량을 나누기 위한 제안이며 고정 일정이 아닙니다. React 경험이 적다면 앞의 두 주를 충분히 반복하세요. 모델을 연결하기 전에 가짜 입력으로 화면과 이벤트 처리를 완성하면, 실패 원인을 한 번에 하나씩 배울 수 있습니다.

다음 단계로 넘어가기 전 확인할 질문

1. 등록한 React 함수는 브라우저에 남고 서버에는 어떤 필드만 전달되나요?
2. 필수 props가 아직 안 왔을 때 화면은 무엇을 표시하나요?
3. 같은 이벤트 목록을 처리했을 때 상태 변화 과정을 재현할 수 있나요?
4. 스트림을 연 뒤 오류가 나면 왜 일반 HTTP 오류로 다시 응답하기 어렵나요?
5. 사용자 권한 확인과 동일 대화의 동시 실행 방지는 어떻게 다른가요?
6. SDK 패키지의 라이선스와 자체 호스팅 서버의 라이선스를 각각 확인했나요?

10핵심 키워드 사전

외워야 할 약어 목록으로 보지 마세요. “모델이 도구를 고른다 → 서버가 이벤트를 보낸다 → 리듀서가 props를 바꾼다 → React가 그린다”라는 문장에 각 용어를 넣어 설명하면 기능과 이름을 함께 기억할 수 있습니다.

11참고 링크

공식 저장소·안내

• tambo 공식 저장소 — 프로젝트 전체와 현재 공지 확인
• 분석한 커밋의 소스 트리 — 본문 경로의 기준점
• web-v0.136.0 릴리스 — 2026-10-23 GitHub 기준 최신 릴리스
• 공식 문서 — 문서 예제는 사용하는 패키지 버전과 대조
• 이 커밋의 자체 호스팅 안내 — 서비스 구성·환경변수·운영 안내
• README에 연결된 Cloud 종료 공지 — 본문의 운영 일정은 커밋 6e2c1bf의 README 기준
• TrendShift의 tambo 항목 — 2026-10-23 Daily #29

핵심 구현 소스

• TamboProvider 구현 — 실제 Provider 조합과 공개 설정
• 등록 Provider — 실제 컴포넌트와 전송용 스키마 보관
• ComponentRenderer 구현 — 목록 조회·부분 props·요소 생성·대체 화면
• 이벤트 리듀서 — 대화와 UI 상태 전이
• ComponentStreamTracker — 부분 JSON과 props 변경 이벤트
• 모델 결정 루프 — UI 도구·모델 응답·중간 결과
• V1Service — 실행 준비·스트리밍·취소와 DB 경계
• DB 실행 연산 — 원자적 잠금과 현재 run을 확인하는 해제

관련 기술을 더 공부할 공식 자료

• React useReducer 문서 — 상태와 액션으로 UI 업데이트하기
• TypeScript 타입 좁히기 — 이벤트 종류별로 안전하게 속성 읽기
• Zod 문서 · JSON Schema 시작 안내 — 타입과 실행 시 검증을 구분하기
• Vercel AI SDK 문서 — tambo 내부의 모델 스트리밍 계층을 이해하기
• NestJS 가드 · Drizzle 트랜잭션 — 접근 확인과 DB 변경 묶기
• RFC 6902 JSON Patch · RFC 6901 JSON Pointer — 변경 명령과 경로 표준
• MCP 공식 소개 — 도구·리소스 연결 원리
• 서버 전송 이벤트 설명 — SSE 연결의 기본 동작

프로젝트 현황 (2026-10-23 GitHub·TrendShift 기준)