LLM 토큰 생성 전 결정론적 Python 안전 게이트를 포함한 heym 기반 4-에이전트 혈액 검사 결과 분류 워크플로우 오픈소스 공개

저는 heym에서 가공되지 않은 혈액 검사 결과(blood panel)를 구조화된 환자 교육 보고서로 변환하는 4-에이전트 멀티 에이전트 워크플로우(multi-agent workflow)를 구축했습니다. 설계상의 핵심 통찰은 다음과 같습니다. 결정론적(deterministic) Python 도구가 어떠한 LLM 토큰이 생성되기 전(BEFORE)에 실행되며, 만약 검사 수치가 병원의 패닉 임계값(panic threshold)을 초과할 경우 고정된 응급 출력으로 단락(short-circuit)시킵니다. LLM은 자신이 보지 못한 내용을 완화(soften)할 수 없습니다. 저장소(Repo): https://github.com/ejentum/agent-teams/tree/main/blood-panel-triage

환자 대상 의료 AI가 가진 문제점
만약 일반적인 LLM에 CBC(전혈구 계산) 결과를 제시하며 "이것이 무엇을 의미하나요?"라고 묻는다면

각 에이전트의 시스템 프롬프트 (System Prompt)는 엄격한 규칙을 통해 가장 발생 가능성이 높은 실패 모드 (Failure Mode)를 억제합니다 (해석기 (Interpreter)는 절대 조언하지 않으며, 제2의 의견 (Second-opinion) 에이전트는 절대 안심시키지 않고, 감별 진단 (Differential) 에이전트는 가장 가능성 높은 항목을 선택하지 않습니다). 3. 두 개의 오류 감소 레이어 (Error-reduction layers)가 중첩되어 있습니다. 실험실 간 모델 다양성 (Anthropic + Alibaba + DeepSeek)은 실험실 전반에 걸친 상관된 실패 (Correlated failures)를 줄여줍니다. 각 하위 에이전트(Sub-agent)에 MCP를 통해 부착된 Ejentum 인지 하네스 (Cognitive harnesses)는 모델 제품군 내부 (WITHIN)의 실패를 줄여줍니다. 결정론적 안전 게이트 (Deterministic safety gate): Python 도구는 heym의 도구 샌드박스 (Tool sandbox) 내부에서 동기식으로 실행됩니다. 순수 표준 라이브러리 (stdlib)만 사용하며, 네트워크 I/O가 없고, JSON 입력 / JSON 출력을 수행합니다. 핵심이 되는 패닉 값 (Panic-value) 테이블은 다음과 같습니다:

PANIC = {
    "glucose": {"crit_low": 40, "crit_high": 600, "ref_low": 70, "ref_high": 100, "unit": "mg/dL"},
    "potassium": {"crit_low": 2.5, "crit_high": 7.0, "ref_low": 3.5, "ref_high": 5.0, "unit": "mEq/L"},
    "sodium": {"crit_low": 120, "crit_high": 160, "ref_low": 135, "ref_high": 145, "unit": "mEq/L"},
    "hemoglobin": {"crit_low": 7.0, "crit_high": 20.0, "ref_low": 12.0, "ref_high": 17.0, "unit": "g/dL"},
    "platelets": {"crit_low": 20, "crit_high": 1000, "ref_low": 150, "ref_high": 450, "unit": "x10^3/uL"},
    "wbc": {"crit_low": 1.0, "crit_high": 50.0, "ref_low": 4.0, "ref_high": 11.0, "unit": "x10^3/uL"},
    "inr": {"crit_low": None, "crit_high": 5.0, "ref_low": 0.8, "ref_high": 1.2, "unit": "ratio"},
    "troponin": {"crit_low": None, "crit_high": 0.04, "ref_low": 0.0, "ref_high": 0.04, "unit": "ng/mL"},
    "creatinine": {"crit_low": None, "crit_high": 4.0, "ref_low": 0.6, "ref_high": 1.3, "unit": "mg/dL"},
    "lactate": {"crit_low": None, "crit_high": 4.0, "ref_low": 0.5, "ref_high": 2.2, "unit": "mmol/L"},
    "calcium": {"crit_low": 6.0, "crit_high": 13.0, "ref_low": 8.5, "ref_high": 10.5, "unit": "mg/dL"},
    "magnesium": {"crit_low": 1.0, "crit_high": 4.7, "ref_low": 1.7, "ref_high": 2.4, "unit": "mg/dL"},
}

임계값 (Thresholds)은 미국의 표준 병원 실험실 콜백 정책에 따른 성인, 비임신 기본값입니다.

이 도구는 요약본인 requires_emergency_care: bool을 반환하며, 오케스트레이터(Orchestrator)는 이를 직접 읽습니다. 만약 true라면 고정된 응급 출력(fixed emergency output)을 내보내고 중단합니다. false라면 하위 에이전트(sub-agents)로 팬아웃(fan-out)합니다. 파서(Parser)는 다중 단어 별칭 매칭(multi-word alias matching, 가장 긴 단어 우선 방식)을 지원하는 좌측-우측 토크나이저(left-to-right tokenizer)를 통해 자유 형식 텍스트("Hemoglobin 8.5 g/dL, glucose 280")와 JSON 객체 문자열('{"hemoglobin": 8.5, "glucose": 280}')을 모두 처리합니다.

역할 고정 하위 에이전트 (Role-locked sub-agents)	에이전트 모델 (Agent Model)	인지 계층 (Cognitive layer)
triageOrchAgent	z-ai/glm-5.1 (없음)	안전 게이트(Safety gate) + 병렬 팬아웃(parallel fan-out) + 통합 인터프리터(integration interpreter)
interpreterAgent	qwen/qwen3-max-thinking ejentum-mcp	마커별 평이한 언어 설명(Plain-language explainer)
doctorpushAgent	anthropic/claude-opus-4 ejentum-mcp	의사에게 질문을 유도하기 위한 구체적인 질문(Specific questions to push the doctor on), 허위 안심 금지
differentialAgent	deepseek/deepseek-r1 (없음)	패턴과 일치하는 3~5가지 상태(conditions), 각 상태별 확인/배제(confirm/rule-out) 정보

오케스트레이터는 단일 어시스턴트 턴(assistant turn)에서 세 개의 call_sub_agent 도구 호출(tool calls)을 방출합니다. heym은 병렬 실행이 가능한 도구 호출을 감지하여 이를 동시에 실행합니다. 팬아웃(fan-out) 시 소요되는 실제 시간(Wall time)은 하위 에이전트들의 합계가 아니라 가장 느린 하위 에이전트에 의해 제한됩니다.

캔버스 도구(canvas tools)로 연결된 공개 의료 API (Public medical APIs wired as canvas tools)
오른쪽 하위 에이전트들에 연결된 세 개의 키리스(keyless) HTTP 엔드포인트:

• 동료 검토 문헌 근거 마련을 위한 Europe PMC (https://www.ebi.ac.uk/europepmc/webservices/rest/search). 단일 호출로 제목 + 초록 + 저자 + 저널을 반환합니다.
• 권위 있는 검사 명칭을 위한 NIH Clinical Tables LOINC (https://clinicaltables.nlm.nih.gov/api/loinc_items/v3/search).
• 검증된 질환 용어를 위한 NIH Clinical Tables conditions (https://clinicaltables.nlm.nih.gov/api/conditions/v3/search).

조작된 인용(fabricated citations)이나 임의로 만들어진 검사 명칭은 없습니다. 워크플로우가 제시하는 모든 참조는 공개된 권위 있는 출처를 추적합니다. 활용된 두 하위 에이전트는 streamable_http를 통해 에이전트별로 ejentum-mcp 서버를 연결합니다.

설정 블록: { "transport": "streamable_http", "url": "https://api.ejentum.com/mcp", "headers": "{"Authorization": "Bearer YOUR_EJENTUM_API_KEY_HERE"}", "timeout": 30, "label": "ejentum" } stdio가 아닌 streamable_http를 사용하십시오. npx -y ejentum-mcp를 사용하는 stdio 경로는 heym 컨테이너 내부에서 콜드 스타트 (cold-start) 지연이 발생하여 빈 도구 목록을 반환할 수 있습니다. streamable_http는 서브프로세스 (subprocess) 생성 없이 약 200ms 내에 4개의 harness_* 도구를 반환합니다. 각 하위 에이전트의 'HARD RULE 1'은 4개의 도구가 모두 보이더라도 에이전트를 하나의 harness에 고정합니다 (interpreter를 위한 harness_reasoning, doctorpush를 위한 harness_anti_deception). 호출당 반환되는 스캐폴드 (scaffold)에는 실패 모드 억제기 (failure-mode suppressors), 타겟 패턴 (target patterns), 반증 테스트 (falsification tests), 그리고 모델의 다음 토큰 분포 (next-token distribution)를 학습 데이터의 기본값으로부터 멀어지도록 편향시키는 Amplify: / Suppress: 신호가 포함되어 있습니다.

직접 시도해보기
레포지토리 (repo)를 클론하고, heym 인스턴스의 Workflows → Import를 통해 blood-panel-triage/heym/blood-panel-triage.json을 엽니다. 모델 자격 증명 (하나의 OpenRouter 키로 4개 모두 작동)을 구성합니다. tools/check_critical_values.py에 있는 Python 도구 소스 코드를 triageOrchAgent의 Python 도구 코드 필드에 붙여넣습니다. Parameters 필드에 파라미터 JSON 스키마 (JSON Schema)를 붙여넣습니다 (래퍼(wrapper) 없는 단일 균형 JSON 객체). 위의 streamable_http 블록을 통해 Ejentum MCP 서버를 interpreterAgent와 doctorpushAgent에 연결합니다. 3개의 HTTP 캔버스 (canvas) 도구가 각각 할당된 하위 에이전트에 연결되었는지 확인합니다. README에 있는 검증 테스트 세트 (실제적인 비정상 패널, 응급 단락, 복잡한 CRAB-minus-bone, 입력 없음 거절)를 실행합니다.

무료 Ejentum 티어: 100회 호출. 무료 heym: Docker를 통한 셀프 호스팅 (self-hosted).

알려진 제한 사항
README에 솔직하게 문서화되어 있습니다: 3개의 HTTP 노드는 에이전트의 쿼리 파라미터 (query parameter)를 등록하지만, URL 자체는 노드 설정에 하드코딩되어 있어 현재 에이전트의 쿼리는 폐기되며 노드는 쿼리와 상관없이 동일한 초기 결과를 반환합니다.

에이전트는 (정확하게) 무관한 도구 출력(tool output)을 무시하고 MCP 스캐폴드(scaffold)와 추론(reasoning)만으로 내용을 작성하므로, 출력 품질이 저하되지는 않습니다. 다만, 각 노드에 agentProvidedFields=["curl"]을 연결하기 전까지는 HTTP 도구들이 장식적인 역할에 그칩니다. 원시 세포/uL 단위의 WBC 및 혈소판 수치(예: "WBC 22" 대신 "WBC 22000")는 잘못된 위양성(false-positive) 위급 플래그를 발생시킬 수 있습니다. 환자용 입력 인터페이스에 단위 가정을 문서화하십시오. 비응급 패널의 경우 전체 실행 시간(Wall time)은 대략 60~90초이며, claude-opus-4를 통한 세컨드 오피니언(second-opinion) 음성 기능이 병목 구간입니다.

이 시스템의 정의 및 한계: 환자 교육용 소프트웨어이며, 진단 도구가 아닙니다. 면허를 소지한 임상의를 대체할 수 없습니다. 출력물은 환자가 자신의 수치를 이해하고 임상 상담을 준비하는 데 도움을 주기 위한 구조화된 정보입니다. 결정론적 응급 게이트(deterministic emergency-gate)는 어떤 공포를 유발할 수 있는 수치도 LLM에 의해 완화되어 전달되지 않도록 보장하기 위해 존재합니다. 게이트를 통과한 모든 내용은 "당신은 X입니다"가 아니라, "의사에게 물어봐야 할 질문들" 및 "이 패턴과 일치하는 상태들"로 명시적으로 프레임화됩니다.