엔터프라이즈 AI 채팅 에이전트

내부용 어시스턴트: 다중 턴 채팅과 파일시스템 도구를 제공하며, 실제 MCP 서버가 파일이 실제로 관련될 때만 연결됩니다.

• 아키텍처 및 근거 → WRITEUP.md

• 규칙, 가드레일, 결정 로그 → CLAUDE.md

• 구축에 사용된 원문 프롬프트 → PROMPTS.md

설치해야 할 것과 설치 순서

프로젝트는 자체적으로 실행됩니다. 트레이스와 행동 평가는 각각 별도의 선택적 레이어이며, 각각 고유한 사전 요구사항이 있습니다. 에이전트가 작동하는 것을 보는 데는 둘 다 필요하지 않습니다. 레벨을 선택하고 거기서 멈추세요.

레벨 2와 3은 독립적입니다. 둘 중 하나, 둘 다, 또는 아무것도 하지 않아도 됩니다. Docker나 Node가 없어도 레벨 1은 아무 문제없이 작동합니다.

Related MCP server: Files MCP Server

레벨 1 — 핵심 (필수)

요구사항

정확한 버전은 requirements.txt에, 범위는 pyproject.toml에 있습니다.

mcp를 2.0.0 미만으로 유지하는 이유: MCP Python SDK v2는 FastMCP를 MCPServer로 이름을 바꾸고 mcp.server.fastmcp 모듈을 제거했습니다. langchain-mcp-adapters 0.3.2도 동일한 상한을 선언하므로, 그 이상에서는 두 패키지를 함께 설치할 수 없습니다. 이 고정은 암묵적 제약을 명시적으로 만든 것이지 다운그레이드가 아닙니다.

실행

# 0. clone
git clone https://github.com/Semmargl/enterprise-ai-chat-agent.git
cd enterprise-ai-chat-agent

# 1. environment
python3 -m venv .venv                 # or: uv venv --python 3.14
source .venv/bin/activate             # Windows: .venv\Scripts\activate
pip install -r requirements.txt       # or: uv pip install -r requirements.txt

# 2. secrets
cp .env.example .env
# then open .env and put your OpenRouter key in OPENROUTER_API_KEY

# 3. sample files to play with (the working folder starts empty)
mkdir -p workspace && cp samples/* workspace/

# 4. check the wiring before spending a token
pytest -q                             # expect: 44 passed, <1s, no network needed

# 5. start
python -m src.main

체크포인트: 에이전트가 시간대에 맞는 인사말로 응답하고 질문에 답합니다. 4단계에서 44 passed가 출력되면 샌드박스, 메모리 창, 도구 가시성이 API 호출 없이 모두 검증된 것입니다.

에이전트는 일반 대화를 유지하며, 파일을 요청하는 첫 순간에 파일 서비스에 연결됩니다.

python -m src.main --thread report   # a separate, named conversation

exit로 종료합니다. 동일한 --thread로 다시 시작하면 대화가 이어집니다. 상태는 메모리가 아닌 SQLite에 체크포인트로 저장됩니다.

MCP 서버를 실행하는 두 가지 방법

두 "기본값"에 주의하세요: 코드는 변수가 설정되지 않았을 때 0으로 폴백하는 반면, .env.example은 MCP_AUTOSTART=1을 제공하여 깨끗한 클론이 두 번째 터미널 없이 실행되도록 합니다. 템플릿을 복사하면 자동 시작을 얻고, .env 없이 배포하면 프로덕션 형태를 얻습니다.

어느 쪽이든 파일을 요청하기 전에는 아무것도 연결되지 않습니다.

시도해 볼 만한 것

로그에서 확인할 것

로그는 JSON이며, 이벤트당 한 줄씩 stderr로 출력됩니다. correlation_id(사용자 턴 하나)와 thread_id(대화 하나) 키가 이들을 연결합니다.

var/audit.jsonl은 감사 추적입니다: 도구 호출당 한 줄씩 결과와 지속 시간이 기록됩니다. 경로, 크기, 해시를 기록하며 파일 내용이나 비밀은 절대 기록하지 않습니다.

이 파일은 의도적으로 workspace/가 아닌 var/에 있습니다. 에이전트의 자체 파일 도구가 샌드박스 루트 아래의 모든 경로에 도달할 수 있으므로, 거기에 감사 추적을 두면 기록되는 프로세스가 편집할 수 있습니다. 체크포인트 데이터베이스(var/checkpoints.sqlite)도 같은 이유로 밖에 있습니다. 이는 에이전트의 메모리이지 작업 공간이 아닙니다. 시작 시 둘 중 하나를 샌드박스 안에 두는 구성은 거부됩니다.

레벨 2 — Phoenix에서의 트레이스 (선택)

사전 요구사항: Docker. Docker가 없으면 이 섹션 전체를 건너뛰세요. 에이전트는 Docker가 필요하지 않습니다. 기본값은 OTEL_EXPORTER=none이므로 깨끗한 클론은 수집기 없이 실행됩니다.

계측은 OpenInference 의미론을 사용한 OpenTelemetry이므로, 스팬은 일반적인 HTTP 작업이 아닌 LLM 및 도구 호출을 설명합니다. 익스포터는 코드 경로가 아닌 환경 변수입니다. Phoenix를 다른 OTLP 백엔드로 바꾸는 것은 리팩터링이 아니라 변수 하나만 바꾸면 됩니다.

# 1. start Phoenix (first run pulls the image, ~1-2 min)
docker run -d --name phoenix -p 6006:6006 -p 4317:4317 arizephoenix/phoenix

# 2. wait for it, then confirm it answers
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:6006    # expect: 200

# 3. run the agent pointed at it — two turns, one plain and one about a file
OTEL_EXPORTER=otlp OTEL_ENDPOINT=http://127.0.0.1:6006/v1/traces \
  python -m src.main --thread traces

체크포인트: http://localhost:6006을 엽니다. 두 턴이 두 개의 트레이스를 생성합니다. 파일 턴을 열면 도구 호출이 create_agent 루프 안에, 모델 호출 아래에 중첩되어 있습니다. 그 중첩이 핵심입니다. 에이전트의 제어 흐름이지 HTTP 요청의 평면 목록이 아닙니다.

# when finished
docker stop phoenix && docker rm phoenix

OTEL_EXPORTER=console을 로컬 디버깅 외에는 사용하지 마세요. 해당 스팬은 전체 프롬프트와 모든 도구 결과(즉, 파일 내용)를 출력하는데, 감사 추적은 의도적으로 이를 저장하지 않습니다.

레벨 3 — 행동 평가 (선택)

사전 요구사항: Node 18+. 없으면 건너뛰세요. pytest가 이미 결정적인 모든 것을 다룹니다.

pytest는 네트워크 없이 확인할 수 있는 것(경로 제한, 창 산술, 도구 가시성)을 다룹니다. 실제 모델과의 실제 9턴 대화 후에도 시스템이 여전히 작동하는지는 다룰 수 없습니다. 그 세 가지 사례는 promptfooconfig.yaml에 있으며 scripts/promptfoo_provider.py를 통해 실제 에이전트(베어 모델이 아닌)에 대해 실행됩니다.

# 1. install
npm i -g promptfoo@latest

# 2. the venv must be active and .env filled in — the provider spawns the real agent
source .venv/bin/activate

# 3. run
NODE_NO_WARNINGS=1 PROMPTFOO_DISABLE_TELEMETRY=1 PROMPTFOO_DISABLE_UPDATE=1 \
  promptfoo eval -o results.json; echo "EXIT=$?"

# 4. browse the results (optional)
promptfoo view

체크포인트: EXIT=0이고 results.json에 "successes": 3, "failures": 0, "errors": 0이 포함됩니다. 전체 실행은 40–60초가 걸립니다. 9턴 대화와 2턴 대화 두 개입니다.

실패처럼 보이지만 실패가 아닌 두 가지. 진행률 표시줄이 0% | 0/3에서 멈춘 것처럼 보일 수 있습니다. Node가 같은 터미널 줄에 경고를 쓰고 덮어쓰기 때문입니다. 표시줄이 아니라 EXIT와 JSON으로 판단하세요. 그리고 반복 실행에서 assertions.cached > 0은 채점자가 자체 호출을 캐시하는 것입니다. 에이전트 대화 자체는 절대 캐시되지 않습니다. 완전히 콜드 실행하려면 --no-cache를 추가하세요.

이것은 토큰을 소모합니다. 세 가지 사례, 총 11턴, 그리고 루브릭 어설션을 위한 LLM 채점자가 모두 .env의 동일한 OPENROUTER_API_KEY를 사용합니다.

구성

모든 설정은 .env.example에 문서화되어 있습니다. 동작을 가장 크게 바꾸는 것: MCP_AUTOSTART, SANDBOX_ROOT, MAX_FILE_BYTES, HISTORY_WINDOW_MESSAGES, SUMMARIZATION_TRIGGER_MESSAGES, OTEL_EXPORTER.

.env는 첫 커밋부터 .gitignore에 있으며 한 번도 커밋된 적이 없습니다:

git log --all --full-history -- .env    # returns nothing