SafetySaaS Agent Server
chchun/AIAgent_Server
Backend agnóstico para agentes IA com pipeline LangGraph e ChromaDB
Ver no GitHubServidor backend de agentes IA multi-tenant construído com FastAPI, LangGraph e ChromaDB, integrado com Gemini API. Implementa um pipeline de 7 nós para processamento de intent, recuperação de SOPs, execução de ações e geração de respostas com interface A2UI renderizável.
Instalação
npx convez-ai chchun/AIAgent_Server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir backends de agentes IA multi-tenant escaláveis
- Implementar pipelines de processamento de intent com roteamento inteligente
- Integrar busca vetorial (ChromaDB) com LLMs para resposta contextualizada
- Criar interfaces A2UI dinâmicas baseadas em estado do agente
Veredito

Projeto maduro de arquitetura multi-tenant bem estruturado com componentes desacoplados (LLM, STT, vector DB). Requer expertise em FastAPI, LangGraph e orquestração de agentes; ideal para times construindo plataformas SaaS com IA conversacional e execução de ações contextualizadas.
README
A tradução para o português deste README ainda está na fila.
SafetySaaS Agent Server
FastAPI + LangGraph + ChromaDB + Gemini API 기반 멀티 테넌트 AI 에이전트 백엔드
Next.js 14 클라이언트 AIAgent_TUI와 함께 동작합니다.
전체 시스템 구조
┌─────────────────────────────────────────────────────────────────┐
│ Next.js 14 Client (github.com/chchun/AIAgent_TUI) │
│ │
│ useChat.ts ──→ POST /api/v1/chat/stream (SSE 스트리밍) │
│ A2UISurface ──→ POST /api/v1/chat/action (버튼 액션) │
│ │
│ ※ 현재 클라이언트는 mock 데이터 동작 중 (연동 예정) │
└────────────────────────┬────────────────────────────────────────┘
│ SSE (Server-Sent Events)
┌────────────────────────▼────────────────────────────────────────┐
│ FastAPI Server (이 레포) :8080 │
│ │
│ LangGraph 7-Node Pipeline │
│ input_processor → intent_router │
│ → [Query] → sop_retriever → (fallback) global_retriever │
│ → [Save] → saas_executor │
│ → final_responder → a2ui_agent → END │
│ │
│ ChromaDB (local/server) · Gemini API · Google STT │
└─────────────────────────────────────────────────────────────────┘
클라이언트 현황 (AIAgent_TUI)
| 항목 | 현재 상태 | 실서버 연동 포인트 |
|---|---|---|
| 채팅 스트리밍 | useChat.ts — mock pickAnswer() | runAgent() → SSE fetch 교체 |
| A2UI 렌더링 | A2UISurface.tsx + a2ui.ts 완전 구현 | 서버 봉투 수신 즉시 동작 |
| 버튼 액션 | onA2UIAction 훅 구현됨 | POST /api/v1/chat/action 연결 |
| 음성 입력 | Composer UI 있음 | POST /api/v1/stt/transcribe 연결 |
연동 방법은 아래 클라이언트 연동 방법 섹션을 참고하세요.
프로젝트 구조
safetysaas-server/
├── app/
│ ├── main.py # FastAPI 앱, CORS, 라우터 등록
│ ├── config.py # pydantic-settings 환경 변수 관리
│ ├── dependencies.py # Depends() 공통 의존성
│ ├── api/v1/
│ │ ├── health.py # GET /api/v1/health
│ │ ├── chat.py # POST /api/v1/chat/stream (SSE)
│ │ │ # POST /api/v1/chat/action (A2UI 버튼)
│ │ ├── stt.py # POST /api/v1/stt/transcribe
│ │ ├── documents.py # POST /api/v1/documents/ingest
│ │ └── auth.py # POST /api/v1/auth/token
│ ├── agents/
│ │ ├── graph.py # LangGraph StateGraph 조립 (7 nodes)
│ │ ├── state.py # AgentState TypedDict
│ │ └── nodes/
│ │ ├── input_processor.py # 오디오→텍스트, 입력 정규화
│ │ ├── intent_router.py # Gemini JSON 분류 (lang/intent/domain/urgency)
│ │ ├── sop_retriever.py # 테넌트 SOP 벡터 검색 (ChromaDB)
│ │ ├── global_retriever.py# 글로벌 법령 검색 (score < 0.8 fallback)
│ │ ├── saas_executor.py # Save 인텐트 SaaS API 실행
│ │ ├── final_responder.py # Gemini LLM 최종 응답 생성
│ │ └── a2ui_agent.py # A2UI 봉투 생성 (4 시나리오)
│ ├── services/
│ │ ├── llm/
│ │ │ ├── base.py # LLMProvider 추상 인터페이스
│ │ │ ├── gemini.py # Gemini API 구현체
│ │ │ └── ollama.py # Ollama stub (향후 온프레미스 전환용)
│ │ ├── stt/google_stt.py # Google Speech-to-Text v2 비동기 클라이언트
│ │ ├── vector_store/
│ │ │ ├── chroma_client.py # ChromaDB 멀티테넌트 래퍼
│ │ │ └── embeddings.py # Gemini text-embedding-004
│ │ └── saas/saas_api.py # 외부 SaaS REST API 클라이언트
│ ├── prompts/
│ │ ├── intent_router.py # intent/domain/urgency 분류 프롬프트
│ │ ├── rag_synthesis.py # SOP→법령 계층적 RAG 합성 프롬프트
│ │ └── saas_executor.py # Save 파라미터 추출 프롬프트
│ ├── utils/
│ │ ├── a2ui_builder.py # 4개 시나리오 + DataTable 봉투 빌더
│ │ └── logger.py # structlog 설정
│ └── schemas/ # Pydantic 요청/응답 스키마
├── scripts/
│ └── ingest_sample.py # 샘플 SOP/법령 문서 인덱싱 CLI
├── tests/
│ ├── conftest.py
│ └── test_chat.py
├── .env.example # 환경 변수 템플릿
├── requirements.txt
└── Dockerfile
설치 및 실행
사전 조건
- Python 3.11+
- Gemini API 키 — Google AI Studio에서 무료 발급
1. 레포 클론 및 패키지 설치
git clone https://github.com/chchun/safetysaas-server.git
cd safetysaas-server
# 가상환경 생성
python -m venv .venv
# 패키지 설치 (Windows)
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
# 패키지 설치 (Mac/Linux)
# .venv/bin/pip install -r requirements.txt
2. 환경 변수 설정
# Windows
copy .env.example .env
# Mac/Linux
# cp .env.example .env
.env 파일에서 아래 항목을 수정합니다:
# ★ 필수: Gemini API 키 입력
GEMINI_API_KEY=AIzaSy_여기에_실제_키_입력
# Docker 없으면 local 유지 (기본값, 별도 설치 불필요)
CHROMA_MODE=local
# 개발 시 true 유지 (JWT 인증 생략)
DEV_MODE=true
3. 서버 실행
# Windows
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8080
# Mac/Linux
# .venv/bin/uvicorn app.main:app --reload --port 8080
4. 동작 확인
# 헬스체크
curl http://localhost:8080/api/v1/health
# → {"status":"ok","version":"1.0.0","services":{"chromadb":"ok","gemini":"ok","google_stt":"ok"}}
Swagger UI: http://localhost:8080/docs
API 엔드포인트
| 메서드 | 경로 | 설명 |
|---|---|---|
GET | /api/v1/health | 헬스체크 + 서비스 상태 |
POST | /api/v1/chat/stream | 채팅 SSE 스트리밍 (LangGraph 실행) |
POST | /api/v1/chat/action | A2UI 버튼 액션 처리 |
POST | /api/v1/stt/transcribe | 음성 파일 → 텍스트 변환 |
POST | /api/v1/documents/ingest | 문서 ChromaDB 인덱싱 |
POST | /api/v1/auth/token | JWT 토큰 발급 |
채팅 스트림 요청
curl -X POST http://localhost:8080/api/v1/chat/stream \
-H "Content-Type: application/json" \
-H "X-Tenant-ID: dev_tenant" \
-d '{"query": "인시던트 보고서 폼 만들어줘", "input_type": "text"}'
SSE 응답 이벤트 순서:
data: {"event":"status", "data":{"text":"입력을 처리하고 있어요..."}}
data: {"event":"reasoning", "data":{"step":"의도 분류: Query / Safety_Manual / urgency:3", "index":1}}
data: {"event":"token", "data":{"text":"네, 인시던트..."}} ← LLM 스트리밍 토큰
data: {"event":"a2ui", "data":{"version":"v0.9","createSurface":{...}}}
data: {"event":"a2ui", "data":{"version":"v0.9","updateComponents":{...}}}
data: {"event":"a2ui", "data":{"version":"v0.9","updateDataModel":{...}}}
data: {"event":"done", "data":{"sources":[...]}}
LangGraph 에이전트 흐름
START
└─→ input_processor 오디오 디코딩 / 텍스트 정규화
└─→ intent_router Gemini JSON 분류 (lang / intent / domain / urgency)
├─→ [Query/Both]
│ └─→ sop_retriever 테넌트 SOP 벡터 검색
│ ├─→ [score ≥ 0.8] → final_responder
│ └─→ [score < 0.8] → global_retriever → final_responder
└─→ [Save]
└─→ saas_executor → final_responder
└─→ a2ui_agent → END
A2UI 시나리오 (4개)
에이전트가 채팅 응답과 함께 UI 컴포넌트를 JSON 봉투 3개 세트로 전달합니다.
클라이언트는 봉투를 순서대로 적용하여 동적 UI를 렌더링합니다.
| 트리거 | surfaceId | 테마 | 컴포넌트 |
|---|---|---|---|
인시던트 / incident / 장애보고 / urgency ≥ 4 + Safety_Manual | incident_form | #E5484D | ChoicePicker + TextField × 2 + CheckBox + 제출 버튼 |
배포 / deploy / 카나리 / canary / rollout | deploy_panel | #1F8A5B | Slider + 조건부 활성화 버튼 |
상태카드 / 서비스 상태 / status card / payment 상태 | status_card | #2A6FDB | 3열 메트릭 + 새로고침 버튼 |
위험성평가 / 위험성 평가 / 공종 / 위험 요인 | risk_form → risk_result_{ts} | #0E7C66 | 공종 Select + TagInput → DataTable (14열) |
A2UI 버튼 액션 테스트
# 위험성평가 결과 테이블 생성
curl -X POST http://localhost:8080/api/v1/chat/action \
-H "Content-Type: application/json" \
-H "X-Tenant-ID: dev_tenant" \
-d '{
"name": "generate_risk",
"surfaceId": "risk_form",
"context": {},
"dataModel": {"risk": {"trade": "용접", "tags": ["화기", "밀폐"]}}
}'
name | 동작 |
|---|---|
generate_risk | 공종 + 태그 기반 위험성평가 DataTable 생성 |
create_incident | 인시던트 티켓 생성 (INC-XXXX 번호 발급) |
start_deploy | 배포 시작 확인 응답 |
cancel_deploy | 배포 취소 응답 |
refresh_status | 상태 카드 메트릭 갱신 |
클라이언트 연동 방법
AIAgent_TUI의 mock 데이터를 실서버 SSE로 교체합니다.
1. 환경 변수 추가 (safetysaas/.env.local)
NEXT_PUBLIC_API_URL=http://localhost:8080
2. useChat.ts — runAgent() 교체 (src/hooks/useChat.ts:74)
현재 (mock):
const ans = pickAnswer(userText); // ← 이 줄을 교체
교체 코드:
const response = await fetch(
`${process.env.NEXT_PUBLIC_API_URL}/api/v1/chat/stream`,
{
method: "POST",
headers: { "Content-Type": "application/json", "X-Tenant-ID": "dev_tenant" },
body: JSON.stringify({ query: userText, input_type: "text" }),
}
);
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let surface: A2UISurfaceState | null = null;
while (true) {
const { done, value } = await reader.read();
if (done) break;
if (cancelled()) return;
for (const line of decoder.decode(value).split("\n")) {
if (!line.startsWith("data:")) continue;
const evt = JSON.parse(line.slice(5).trim());
if (evt.event === "status") patchMsg(botId, { phase: "status", statusText: evt.data.text });
if (evt.event === "reasoning") patchMsg(botId, { phase: "reasoning" });
if (evt.event === "token") patchMsg(botId, (m) => ({ phase: "answer", text: (m.text || "") + evt.data.text }));
if (evt.event === "a2ui") {
surface = a2ApplyEnvelope(surface, evt.data);
patchMsg(botId, { phase: "a2ui", a2uiState: surface });
}
if (evt.event === "done") patchMsg(botId, { phase: "done", streaming: false, sources: evt.data.sources ?? [] });
}
}
3. 액션 핸들러 교체 (runActionReply 내부)
const response = await fetch(
`${process.env.NEXT_PUBLIC_API_URL}/api/v1/chat/action`,
{
method: "POST",
headers: { "Content-Type": "application/json", "X-Tenant-ID": "dev_tenant" },
body: JSON.stringify(action),
}
);
const { text, envelopes } = await response.json();
// text → 응답 텍스트 스트리밍 처리
// envelopes → a2ApplyEnvelope 순서대로 적용
샘플 데이터 인덱싱
ChromaDB에 테스트용 SOP / 법령 데이터를 인덱싱합니다:
.\.venv\Scripts\python.exe scripts/ingest_sample.py
# → 3개 SOP 청크 저장 완료
# → 2개 법령 청크 저장 완료
환경 변수 전체 목록
| 변수 | 기본값 | 설명 |
|---|---|---|
GEMINI_API_KEY | — | 필수. Google AI Studio에서 발급 |
GEMINI_CHAT_MODEL | gemini-1.5-flash | 채팅용 모델 |
GEMINI_EMBEDDING_MODEL | models/text-embedding-004 | 임베딩 모델 |
LLM_PROVIDER | gemini | gemini 또는 ollama |
CHROMA_MODE | local | local (Docker 불필요) 또는 server |
CHROMA_HOST | localhost | ChromaDB 서버 호스트 (server 모드) |
CHROMA_PORT | 8000 | ChromaDB 서버 포트 (server 모드) |
JWT_SECRET_KEY | dev-secret-key | 프로덕션에서 반드시 변경 |
DEV_MODE | true | true 시 JWT 인증 생략 |
DEV_TENANT_ID | dev_tenant | 개발 모드 기본 테넌트 ID |
CORS_ORIGINS | http://localhost:3000 | 허용 오리진 (쉼표 구분 다수 가능) |
GOOGLE_APPLICATION_CREDENTIALS | — | STT용 GCP 서비스 계정 키 경로 |
GOOGLE_CLOUD_PROJECT_ID | — | STT용 GCP 프로젝트 ID |
기술 스택
| 레이어 | 기술 |
|---|---|
| API 서버 | FastAPI + Uvicorn |
| 에이전트 오케스트레이션 | LangGraph |
| LLM | Google Gemini 1.5 Flash/Pro |
| 임베딩 | Gemini text-embedding-004 |
| 벡터 DB | ChromaDB (local 모드) |
| 음성 인식 | Google Speech-to-Text v2 |
| 설정 관리 | pydantic-settings |
| 인증 | JWT (python-jose) |
| 로깅 | structlog |
로드맵
- 클라이언트 실서버 연동 —
useChat.tsmock → SSE 실제 호출 교체 - Ollama 전환 —
LLM_PROVIDER=ollama로 온프레미스 LLM 사용 - ChromaDB server 모드 — Docker 환경에서
CHROMA_MODE=server전환 - 멀티테넌트 문서 인덱싱 — 테넌트별 SOP 업로드 UI 연동
- Google STT 실연동 — 음성 입력 →
POST /api/v1/stt/transcribe - JWT 인증 활성화 —
DEV_MODE=false+ 실제 토큰 발급 흐름