Middleware Configurations
이 가이드는 NPO Studio에서 AI 에이전트를 생성하거나 편집할 때 사용할 수 있는 Middleware 설정을 설명합니다. Middleware 탭은 3가지 주요 기능을 제공합니다: Human in the loop, PII (Personally Identifiable Information) protection 및 Summarization (LangChain 기반).
Middleware 설정 접근하기
- 에이전트 디자인 캔버스에서 AI 에이전트를 엽니다.
- AI 에이전트 노드(예: "Agent 1 - Main Agent")를 클릭합니다.
- 오른쪽 구성 패널에서 Middleware 탭을 선택합니다.
Human in the loop
Human in the loop 미들웨어는 에이전트가 자율적으로 실행할 수 있는 도구와 명시적인 인간 승인이 필요한 도구를 제어할 수 있게 해줍니다. 활성화되면, 구성된 규칙에 맞는 도구 호출은 실행을 일시 중지하고, 진행하기 전에 인간이 승인, 편집 또는 거부할 때까지 기다립니다.
Human in the loop 활성화하기
미들웨어 패널 상단에서 Human in the loop 스위치를 ON으로 전환합니다. 이 기능은 메인 에이전트와 서브 에이전트 노드 모두에서 사용할 수 있습니다.
MCP 서버별 도구 권한 구성하기
Human in the loop을 활성화한 후, 각 연결된 MCP 서버는 접을 수 있는 섹션으로 표시됩니다. 각 MCP 서버 내에서 도구별 승인 규칙을 구성합니다.
도구 권한 규칙 추가하기
- MCP 서버 섹션을 확장합니다(예: "ddg-search").
- Select a tool 드롭다운을 클릭하여 해당 MCP 서버에서 특정 도구를 선택합니다.
- Select one or more permission 드롭다운을 클릭하여 해당 도구에 대한 허용된 권한을 할당합니다.
- checkmark 버튼을 클릭하여 확인하거나, X 버튼을 클릭하여 취소합니다.
- 도구가 이제 할당된 권한 작업과 함께 목록에 나타납니다.
Note: MCP 서버에 Human in the Loop에 대한 도구가 구성되어 있지 않으면 "이 MCP에 대해 구성된 도구가 없습니다."라고 표시됩니다.
도구 권한 작업
구성된 각 도구는 에이전트가 도구 실행 요청을 처리하는 방법을 정의하는 하나 이상의 작업 버튼을 표시합니다. 도구는 동시에 승인, 편집, 거부의 여러 권한으로 구성될 수 있습니다.
| 작업 | 설명 |
|---|---|
| 승인 | 도구 실행이 진행될 수 있도록 허용합니다. 인간 검토자가 도구 호출 및 그 인수가 수용 가능한지 확인합니다. |
| 편집 | 인간 검토자가 실행 전에 도구 호출 인수를 수정할 수 있도록 허용합니다. 편집 가능한 권한이 구성된 경우에 사용할 수 있습니다. |
| 거부 | 도구 실행을 완전히 차단합니다. 에이전트는 도구 호출이 거부되었음을 통보받고 이를 없이 진행해야 합니다. |
도구 규칙 관리
- 도구 옆의 더보기 메뉴 (⋮)를 클릭하여 추가 옵션에 접근합니다 (예: 규칙 제거).
- MCP 서버 헤더의 추가 아이콘을 클릭하여 새로운 도구 권한 규칙을 추가합니다.
- 동일한 MCP 서버의 여러 도구는 각각 다른 권한 구성을 가질 수 있습니다.
런타임에서 Human in the Loop 작동 방식
Human in the Loop가 활성화된 에이전트가 NPO Workspace 채팅에서 사용될 때:
- 에이전트는 사용자의 메시지를 처리하고 도구를 호출해야 함을 결정합니다.
- 도구를 자동으로 실행하는 대신, 에이전트는 채팅에 "Tool execution pending approval" 메시지를 표시합니다.
- 메시지는 다음을 보여줍니다.
- 호출되는 도구 이름 (예: fetch_content, search, get_alerts_api_alert_v1...).
- 에이전트가 전달하려는 인자
- 인간 검토자는 사용 가능한 작업 버튼 중 하나를 클릭합니다.
- Approve: 도구가 표시된 인수로 실행됩니다.
- Edit: 검토자가 인수를 수정한 후, 도구가 업데이트된 값으로 실행됩니다.
- Reject: 도구 호출이 차단됩니다; 에이전트는 도구 결과 없이 계속 진행합니다.
- 작업 후, 에이전트는 도구 결과(승인된 경우) 또는 결과 없이(거부된 경우) 처리를 재개합니다.
Note: 여러 도구 호출이 단일 보류 승인 메시지에 나타날 수 있습니다. 메시지 내의 각 도구 호출은 검토되어야 합니다. 에이전트는 모든 보류 중인 도구가 처리될 때까지 진행하지 않습니다. 메인 에이전트와 서브 에이전트에 대해 선택된 모든 MCP 서버는 'Human in the Loop' 섹션 아래에 표시되어야 합니다. 선택할 수 있도록 도구가 구성된 MCP를 확인해야 합니다.
구성 예제
| MCP 서버 | 도구 | 사용 가능한 작업 | 사용 사례 |
|---|---|---|---|
| ZCP Alert Backend | get_alerts_api_alert_v1... | 승인, 편집, 거부 | 실행 전에 경고 쿼리 검토 |
| ddg-search | fetch_content | 승인, 거부 | 에이전트가 가져올 수 있는 URL 제어 |
| ddg-search | search | 승인, 편집, 거부 | 검색 쿼리 검토 및 수정 |
인간이 개입하는 루프를 위한 모범 사례
- 쓰기 (생성, 업데이트, 삭제) 작업을 수행하거나 민감 데이터에 접근하는 도구에 대해 인간이 개입하는 루프를 활성화해야 합니다.
- 인수 조정이 정확성을 향상시키는 도구에 대해 수정 권한을 사용하면 됩니다(예: 검색 쿼리, API 필터).
- 읽기 전용 도구의 위험이 낮은 경우, 대화 속도를 유지하기 위해 Human in the Loop 없이 두는 것을 고려하면 됩니다.
- MCP 서버별로 도구 규칙을 구성하여 세부적인 제어를 적용합니다. - 모든 도구가 동일한 수준의 감독이 필요하지는 않습니다.
- 사용자 경험이 원활한지 확인하기 위해 Playground에서 승인 흐름을 테스트하면 됩니다.
- Human in the Loop는 Main Agent와 Sub-Agent 노드 모두에 독립적으로 적용됩니다 - 각 에이전트 노드를 특정 도구 사용에 따라 구성합니다.
PII 개인 식별 정보
PII 미들웨어는 AI 에이전트를 통해 흐르는 민감한 데이터를 자동으로 감지하고 보호합니다. 활성화되면, 특정 데이터 유형에 대해 메시지를 스캔하고 보호 조치를 적용합니다.
PII 활성화
PII 스위치를 ON으로 전환하여 에이전트에 대한 PII 보호를 활성화합니다.
지원되는 PII 유형
각 PII 유형은 개별적으로 ON 또는 OFF로 전환할 수 있습니다.
| PII 유형 | 설명 |
|---|---|
| 이메일 주소 (예: user@example.com) | |
| Credit card | 신용/직불 카드 번호 |
| IP | IP 주소 (IPv4/IPv6) |
| MAC address | 네트워크 MAC 주소 |
| URL | 웹 URL 및 링크 |
각 PII 유형에는 감지된 데이터가 처리되는 방식을 결정하는 작업 드롭다운이 있습니다.
- Redact: 감지된 PII를 자리 표시자(예: [REDACTED])로 대체하여 민감한 값을 메시지에서 완전히 제거합니다.
각 PII 유형에 대해 보호가 적용되는 위치를 선택할 수 있습니다. 체크박스를 사용하여 하나 이상 선택합니다.
- Input: 에이전트에 전송된 사용자 메시지에서 PII를 스캔하고 보호합니다.
- Output: 사용자에게 돌아가는 에이전트의 응답에서 PII를 스캔하고 보호합니다.
- Tool results: 도구/API 호출에서 반환된 데이터의 PII를 스캔하고 보호합니다.
| PII 유형 | 작업 | 입력 | 출력 | 도구 결과 | 사용 사례 |
|---|---|---|---|---|---|
| 이메일 | 삭제 | 선택 해제 | 선택 | 선택 | 응답에서 이메일 유출 방지 |
| 신용 카드 | 삭제 | 선택 해제 | 선택 | 선택 해제 | 출력에서 카드 번호 차단 |
| IP | 삭제 | 선택 해제 | 선택 | 선택 해제 | 응답에서 IP 주소 숨기기 |
| MAC 주소 | 삭제 | 선택 해제 | 선택 | 선택 해제 | 응답에서 MAC 주소 숨기기 |
| URL | 삭제 | 선택 | 선택 해제 | 선택 해제 | 처리 전에 사용자 입력에서 URL 제거 |
- 민감한 유형(이메일, 신용 카드)에 대한 Output 보호를 활성화하여 우발적인 데이터 유출을 방지합니다.
- 노출되어서는 안 되는 사용자 데이터를 반환하는 백엔드 API가 있을 때 Tool results를 활성화합니다.
- LLM에 도달하기 전에 사용자 제공 데이터를 익명화하려는 경우 Input를 활성화합니다.
- 민감한 정보를 반환할 수 있는 새로운 MCP 도구를 연결할 때 PII 설정을 검토합니다.
요약
요약 미들웨어(LangChain 기반)는 대화 기록을 자동으로 압축하여 컨텍스트 창 한계를 관리합니다. 대화가 구성된 임계값을 초과하면 요약을 트리거하여 중요한 정보를 보존하면서 컨텍스트를 범위 내로 유지합니다.
요약 활성화
Summarization 스위치를 ON으로 전환하여 대화 요약을 활성화합니다.
LLM 구성
요약에는 요약을 생성하기 위한 자체 LLM이 필요합니다. 다음 필수 필드를 구성합니다.
Provider(필수)
- 요약 생성을 위해 사용되는 LLM 제공자입니다.
- 예: OpenAI
- 구성된 제공자 목록에서 선택합니다.
Default model(필수)
- 요약에 사용되는 특정 모델입니다.
- 예: GPT 4o
- 요약 작업을 위해 품질과 비용의 균형을 맞춘 모델을 선택합니다.
API Key(필수)
- LLM 공급자와 인증하는 데 사용되는 API 키입니다.
- 시스템에 미리 구성된 API 키 중에서 선택합니다.
Trigger
Trigger 섹션은 요약을 시작하는 조건을 정의합니다. 활성화된 조건이 충족되면 요약 프로세스가 실행됩니다. 여러 트리거를 동시에 활성화할 수 있으며, 어떤 조건이 충족되면 요약이 활성화됩니다.
Messages- 대화가 지정된 메시지 수에 도달하면 요약을 트리거합니다.
- 예: 50 - 대화에서 50개의 메시지 후에 요약이 실행됩니다.
- 값을 지우려면 x를 클릭합니다.
- 대화가 지정된 토큰 수에 도달하면 요약을 트리거합니다.
- 요약이 활성화되기 전에 최대 토큰 수를 입력합니다.
- LLM 컨텍스트 창 한도를 유지하는 데 유용합니다.
- 대화가 컨텍스트 창의 지정된 비율을 사용할 때 요약을 트리거합니다.
- 슬라이더(0-100%)를 통해 조정 가능합니다.
- 모델 용량에 따라 동적 컨텍스트 관리를 위해 유용합니다.
Keep
Keep 섹션은 요약이 실행된 후 얼마나 많은 대화 기록이 유지되는지를 결정합니다. 세 가지 전략 중 하나를 선택합니다.
Messages (메시지 수 기준으로 유지)- 요약 후 가장 최근 메시지의 고정 수를 유지합니다.
- Messages limit: 보존할 최근 메시지의 수입니다.
- 예: 30 - 요약 후 가장 최근의 30개 메시지가 그대로 유지되며, 이전 메시지는 요약으로 대체됩니다.
- 지정된 토큰 예산까지 최근 메시지를 유지합니다.
- Tokens limit: 최근 기록에서 보존할 최대 토큰 수입니다.
- 컨텍스트 창 사용에 대한 정밀한 제어가 필요할 때 유용합니다.
- 전체 대화의 일부를 최근 메시지로 유지합니다.
- Fraction limit: 슬라이더를 통해 조정 가능 (예: 12%).
- 나머지 부분은 요약됩니다.
- 대화 길이에 관계없이 비례적 맥락 관리를 위해 유용합니다.
Summarization 작동 방식 (LangChain 기반)
- 에이전트는 구성된 Trigger 조건에 따라 대화를 모니터링합니다.
- 트리거 임계값에 도달하면, 요약 LLM이 이전 메시지의 간결한 요약을 생성합니다.
- 시스템은 Keep 전략에 따라 최근 메시지를 유지합니다.
- 요약은 이전 대화 기록을 대체하여 맥락 크기를 줄입니다.
- 향후 상호작용은 요약 + 최근 메시지를 맥락으로 사용합니다.
| 시나리오 | 트리거 | 유지 전략 | 추천 사항 |
|---|---|---|---|
| 짧은 대화, 비용 민감 | 메시지: 30 | 메시지: 10 | 간단하고 예측 가능 |
| 긴 대화, 품질 중심 | 토큰: 모델 한계 근처 | 비율: 20% | 맥락 사용 극대화 |
| 가변 길이 대화 | 비율: 80% | 메시지: 20 | 대화 길이에 적응 |
| 엄격한 토큰 예산 | 토큰: 4000 | 토큰: 1000 | 정밀한 토큰 제어 |
- 자주 실행되므로 요약을 위해 빠르고 비용 효율적인 모델(예: GPT 4o)을 사용합니다.
- 요약 자체를 위한 여유 공간을 허용하기 위해 Trigger 임계값을 모델의 실제 맥락 한계 아래로 설정합니다.
- 안전을 위해 여러 트리거 유형을 활성화하세요—하나의 조건이 잘못 구성되면 다른 조건이 이를 포착합니다.
- 실제 대화로 테스트하여 요약 후 중요한 맥락이 보존되는지 확인합니다.
- 다중 턴 작업 에이전트의 경우, 최근 지침이 intact하도록 Messages 유지 전략을 선호합니다.
- 지식이 많은 대화의 경우, 더 많은 세부 정보를 유지하기 위해 Tokens 또는 Fraction를 선호합니다.