LangSmith와 Vite로 배포하기

LangChain 딥 에이전트를 LangSmith Deployment에 배포하고 Vercel, Netlify 또는 Cloudflare Pages의 Vite React 채팅 UI에서 스트리밍해요.

이 예시는 로컬 체크아웃에서 작동하는 채팅 UI가 있는 배포된 LangChain 딥 에이전트까지 안내해요. 백엔드는 LangSmith Deployment로 실행되고, 프론트엔드는 그로부터 스트리밍하는 Vite + React 앱이에요.

에이전트를 로컬에서 실행하고 LangSmith에 배포한 다음 UI를 배포된 Agent Server에 연결하고 싶을 때 이 가이드를 사용하세요.

소스: 배포 쿡북의 js-langsmith.

출처: 문서

본문

배포하는 것

LangSmith Deployment는 LangGraph 그래프를 LangSmith의 호스팅된 Agent Server에서 실행해요. 이 예시에서:

agent/는 딥 에이전트 그래프, 하위 에이전트, 미들웨어, 도구를 포함해요.
langgraph.json은 LangGraph CLI에 어떤 그래프를 서빙하고 배포할지 알려줘요.
src/는 React 채팅 UI를 포함해요.
UI는 LangGraph SDK와 @langchain/react를 통해 Agent Server API와 통신해요.

배포된 에이전트는 두 하위 에이전트가 있는 코디네이터예요:

researcher는 로컬 search_web 도구를 사용해요.
math-whiz는 로컬 calculator 도구를 사용해요.

조각이 어떻게 맞물리는가

%%{init: {"themeVariables": {"lineColor": "#40668D", "primaryColor": "#E5F4FF", "primaryTextColor": "#030710", "primaryBorderColor": "#006DDD"}}}%%
flowchart LR
  A["agent/<br/>createDeepAgent graph"] -->|"pnpm run deploy"| B["LangSmith Deployment<br/>Agent Server"]
  C["React chat UI<br/>src/"] -->|"LangGraph SDK<br/>threads + streaming"| B

  classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
  classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33
  class A,C process
  class B output

로컬 개발 중에는 pnpm run dev가 LangGraph 개발 서버와 Vite 앱을 모두 시작해요. 프로덕션에서는 LangSmith가 에이전트를 호스팅하고 정적 호스트가 Vite 빌드 UI를 서빙해요.

사전 요구 사항

배포 접근 권한이 있는 LangSmith API 키.
에이전트 모델용 OpenAI API 키.
pnpm.

로컬에서 실행

의존성 설치:
```
cd js-langsmith
pnpm install
```
환경 파일 만들기:
```
cp .env.example .env
```
.env를 열고 설정하세요:
```
OPENAI_API_KEY=<your OpenAI API key>
```
로컬 개발을 위해 LANGSMITH_API_KEY와 VITE_AGENT_API_URL은 비워 두세요. 원격 LangSmith 배포에 대해 UI를 배포하거나 테스트할 때만 LANGSMITH_API_KEY가 필요해요.
에이전트와 UI 시작:
```
pnpm run dev
```
이 명령이 두 프로세스를 모두 시작해요:
- http://localhost:2024의 LangGraph 개발 서버.
- http://localhost:5173의 Vite 개발 서버.
채팅 열기:

http://localhost:5173을 여세요. 두 하위 에이전트를 모두 사용하는 프롬프트를 시도해 보세요:
```
Research LangGraph streaming, and separately calculate 42 * 17.
```
VITE_AGENT_API_URL이 비어 있으면 Vite 앱은 /api/langgraph의 로컬 프록시를 사용하고, 이 프록시는 요청을 LangGraph 개발 서버로 전달해 CORS 문제를 피해요.

에이전트를 LangSmith에 배포

환경 확인: .env에 다음이 포함되어야 해요:
```
OPENAI_API_KEY=<your OpenAI API key>
LANGSMITH_API_KEY=<your LangSmith API key>
```
선택적으로 배포 이름을 설정하세요:
```
LANGSMITH_DEPLOYMENT_NAME=deployment-cookbook-agent
```
LANGSMITH_DEPLOYMENT_NAME이 설정되지 않으면 배포 이름은 디렉터리 이름으로 기본 설정돼요.
에이전트를 LangSmith에 배포:
```
pnpm run deploy
```
이 명령은 langgraphjs deploy를 실행해요. CLI는 langgraph.json을 사용해 agent/index.ts에서 agent 그래프를 배포해요.
배포 API URL 복사: 배포 후 LangSmith에서 배포를 열고 API URL을 복사하세요. 다음과 비슷해야 해요:
```
https://your-app.us.langgraph.app/
```
루트 URL만 사용하세요. API 경로 접미사를 추가하지 마세요.
원격 배포에 대해 UI 테스트: .env에서 VITE_AGENT_API_URL을 설정하세요:
```
VITE_AGENT_API_URL=https://your-app.us.langgraph.app
```
그런 다음 UI를 실행하세요:
```
pnpm run dev
```
브라우저 클라이언트는 원격 배포와 통신할 때 LANGSMITH_API_KEY를 재사용해요.

이 데모는 UI가 LangSmith 배포를 직접 호출할 수 있도록 LANGSMITH_API_KEY를 브라우저 번들에 노출해요. 로컬 테스트에는 편리하지만 프로덕션에서는 안전하지 않아요. 실제 앱에서는 자체 백엔드를 통해 요청을 프록시하고 키를 서버 측에 보관하세요.

프론트엔드 배포

에이전트와 UI는 별도로 배포돼요. pnpm run deploy가 성공한 후 Vite 빌드(dist/)를 어떤 정적 플랫폼에서든 호스팅하고 LangSmith 배포 URL을 가리키세요.

Vercel

저장소 가져오기: 아래의 Deploy with Vercel을 클릭하거나, langchain-ai/deployment-cookbook을 수동으로 가져오세요.
프로젝트 구성:
1. Root Directory를 js-langsmith로 설정하세요.
2. 기본 Vite 빌드를 사용하세요. 빌드 출력은 dist/예요.
3. 환경 변수를 설정하세요:
  - VITE_AGENT_API_URL: LangSmith 배포 루트 URL.
  - LANGSMITH_API_KEY: 데모 클라이언트가 사용하는 LangSmith API 키.

Netlify

저장소 가져오기: 아래의 Deploy to Netlify를 클릭하거나, langchain-ai/deployment-cookbook을 수동으로 가져오세요.
프로젝트 구성: Base directory를 js-langsmith로 설정하세요. 기본 빌드 명령(pnpm build 또는 npm run build)과 퍼블리시 디렉터리 dist/를 사용하세요.
환경 변수 설정: 배포 전에 Netlify에 다음 변수를 추가하세요:
- VITE_AGENT_API_URL: LangSmith 배포 루트 URL.
- LANGSMITH_API_KEY: 데모 클라이언트가 사용하는 LangSmith API 키.

Cloudflare Pages

저장소 연결: Cloudflare 대시보드에서 langchain-ai/deployment-cookbook에서 Workers & Pages 프로젝트를 만드세요.
빌드 구성:
- Root directory: js-langsmith
- Build command: pnpm install && pnpm build
- Build output directory: dist
환경 변수 설정: Pages 프로젝트 설정에 다음 변수를 추가하세요:
- VITE_AGENT_API_URL: LangSmith 배포 루트 URL.
- LANGSMITH_API_KEY: 데모 클라이언트가 사용하는 LangSmith API 키.

문제 해결

pnpm run dev가 시작되는데 UI가 연결되지 않음: 로컬 개발에서는 VITE_AGENT_API_URL을 비워 두고 pnpm run dev를 다시 시작하세요.
에이전트가 로컬에서 응답하지 못함: .env에 OPENAI_API_KEY가 설정돼 있는지 확인하세요.
pnpm run deploy가 인증 오류로 실패: LANGSMITH_API_KEY에 배포 접근 권한이 있는지 확인하세요.
원격 UI가 연결 실패: VITE_AGENT_API_URL이 경로 접미사가 없는 배포 루트 URL인지 확인하세요.
로컬 개발을 다시 시작한 후 스레드가 사라짐: 로컬 langgraph dev는 인메모리 MemorySaver를 사용해요. LangSmith Deployment는 프로덕션에서 내구성 있는 저장소를 제공해요.
agent/에서 파일을 변경했지만 프로덕션이 바뀌지 않음: pnpm run deploy를 다시 실행하세요.

프로젝트에 대해 알아보기

에이전트 파일

LangSmith 백엔드는 agent/에 있어요:

agent/
├── index.ts       # createDeepAgent graph
├── middleware.ts  # response middleware
└── tools.ts       # custom code tools

agent/index.ts는 LangGraph가 로컬에서 서빙하고 LangSmith가 배포하는 그래프를 내보내요. 로컬 MemorySaver 체크포인터는 langgraph dev에서만 사용돼요. LangSmith Deployment는 코드 변경 없이 프로덕션에서 내구성 있는 Postgres 기반 저장소로 교체해요.

LangGraph 구성

langgraph.json은 CLI를 그래프로 안내해요:

{
  "graphs": {
    "agent": "./agent/index.ts:agent"
  },
  "env": ".env"
}

그래프 id는 agent예요. 프론트엔드는 스트리밍할 때 그 id를 어시스턴트 id로 사용해요.

채팅 UI

src/의 React 앱은 스트리밍 채팅, 스레드 기록, 하위 에이전트 렌더링, 도구 호출 렌더링을 제공해요.

프론트엔드는 다음을 사용해요:

스레드 사이드바용 client.threads.search().
대화 관리용 client.threads.create()와 client.threads.delete().
스트리밍 채팅용 assistantId: "agent"가 있는 StreamProvider.

기본 스레드 및 스트리밍 API는 Agent Server API 참조를 참고하세요.

로컬 명령

두 로컬 프로세스를 모두 실행:

pnpm run dev

별도로 실행:

pnpm run dev:agent
pnpm run dev:web

프론트엔드 빌드 및 미리보기:

pnpm build
pnpm preview

CI/CD

js-langsmith/agent/ 아래의 파일이나 공유 구성 파일이 변경되면 에이전트가 GitHub Actions를 통해 배포돼요:

워크플로: .github/workflows/deploy-langsmith-agent.yml
액션: langgraphjs deploy를 LangSmith로.
필요한 시크릿: LANGSMITH_API_KEY.
선택 변수: LANGSMITH_DEPLOYMENT_NAME.

프론트엔드는 정적 호스트의 Git 통합(예: Vercel, Netlify 또는 Cloudflare Pages)을 통해 배포돼요.

LangSmith와 Vite로 배포하기