convez.ai
AgenteDesenvolvimento WebAvançado
chchun

SafetySaaS Agent Server

chchun/AIAgent_Server

Backend agnóstico para agentes IA com pipeline LangGraph e ChromaDB

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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_Server

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

설치 및 실행

사전 조건

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/actionA2UI 버튼 액션 처리
POST/api/v1/stt/transcribe음성 파일 → 텍스트 변환
POST/api/v1/documents/ingest문서 ChromaDB 인덱싱
POST/api/v1/auth/tokenJWT 토큰 발급

채팅 스트림 요청

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_Manualincident_form#E5484DChoicePicker + TextField × 2 + CheckBox + 제출 버튼
배포 / deploy / 카나리 / canary / rolloutdeploy_panel#1F8A5BSlider + 조건부 활성화 버튼
상태카드 / 서비스 상태 / status card / payment 상태status_card#2A6FDB3열 메트릭 + 새로고침 버튼
위험성평가 / 위험성 평가 / 공종 / 위험 요인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_MODELgemini-1.5-flash채팅용 모델
GEMINI_EMBEDDING_MODELmodels/text-embedding-004임베딩 모델
LLM_PROVIDERgeminigemini 또는 ollama
CHROMA_MODElocallocal (Docker 불필요) 또는 server
CHROMA_HOSTlocalhostChromaDB 서버 호스트 (server 모드)
CHROMA_PORT8000ChromaDB 서버 포트 (server 모드)
JWT_SECRET_KEYdev-secret-key프로덕션에서 반드시 변경
DEV_MODEtruetrue 시 JWT 인증 생략
DEV_TENANT_IDdev_tenant개발 모드 기본 테넌트 ID
CORS_ORIGINShttp://localhost:3000허용 오리진 (쉼표 구분 다수 가능)
GOOGLE_APPLICATION_CREDENTIALS—STT용 GCP 서비스 계정 키 경로
GOOGLE_CLOUD_PROJECT_ID—STT용 GCP 프로젝트 ID

기술 스택

레이어기술
API 서버FastAPI + Uvicorn
에이전트 오케스트레이션LangGraph
LLMGoogle Gemini 1.5 Flash/Pro
임베딩Gemini text-embedding-004
벡터 DBChromaDB (local 모드)
음성 인식Google Speech-to-Text v2
설정 관리pydantic-settings
인증JWT (python-jose)
로깅structlog

로드맵

  • 클라이언트 실서버 연동 — useChat.ts mock → 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 + 실제 토큰 발급 흐름
Ver o original no GitHub

Bom para

Relacionados