Dify가 기업 내부 API를 안전하게 호출하는 방법

Dify는 AI 워크플로우 (workflow)를 빠르게 구축하는 데 매우 훌륭합니다. 하지만 워크플로우가 기업 내부 API를 호출하기 시작하면, 리스크는 "답변이 틀릴 수 있음"에서 "시스템이 잘못된 동작을 실행할 수 있음"으로 이동합니다.

주문 환불, 계정 변경, CRM 데이터 조회, 사용자 삭제 또는 티켓 생성과 같은 작업은 에이전트 (Agent)에게 비즈니스 API 자격 증명 (credentials)에 대한 직접적인 접근 권한을 부여함으로써 처리해서는 안 됩니다.

Agent Tool Gateway (ATG)는 Dify와 기업 API 사이에 독립적인 거버넌스 게이트웨이 (governance gateway)를 배치합니다.

Dify -> ATG -> 정책 (Policy) / 승인 (Approval) / 비식별화 (Redaction) / 자격 증명 격리 (Credential Isolation) / 감사 (Audit) -> 비즈니스 API

직접적인 API 호출의 문제점

비즈니스 API가 에이전트 워크플로우 내에 직접 구성되면 다음과 같은 여러 문제점이 나타납니다:

• 실제 비즈니스 API 자격 증명이 워크플로우 도구 (workflow tools) 내부에 저장됩니다.
• 각 도구는 자체적인 권한 경계 (permission boundary)를 가집니다.
• 고위험 작업이 인간의 승인을 위해 일시 중지되지 않습니다.
• 응답에 전화번호, 이메일, ID, 주소 또는 기타 민감한 필드가 포함될 수 있습니다.
• 거부된 호출, 승인, 실패 및 감사 증거를 검토하기 어렵습니다.
• 에이전트 프레임워크 (Agent framework)가 변경될 때마다 거버넌스 로직을 다시 구축해야 합니다.

이러한 문제들은 데모 중에는 작아 보일 수 있지만, 기업 내부 배포 시에는 보안 및 인도 (delivery) 문제로 이어집니다.

ATG 경계 (The ATG Boundary)

Dify는 애플리케이션 오케스트레이션 (application orchestration)을 처리합니다. ATG는 도구 호출 거버넌스 (tool-call governance)를 처리합니다.

Dify에 노출된 HTTP 도구는 오직 ATG 호출 엔드포인트 (invoke endpoint)뿐입니다:

POST http://localhost:8080/api/v1/invoke/refund_order
Authorization: Bearer {{ATG_API_KEY}}
Content-Type: application/json

Dify는 ATG 에이전트 API 키를 저장합니다. 실제 비즈니스 API 엔드포인트, 비즈니스 자격 증명, 승인 정책, 비식별화 규칙 및 감사 기록은 ATG 내부에 유지됩니다.

최소 흐름 (Minimal Flow)

1. ATG에서 Agent를 생성하고 일회용 Agent API key를 발급받습니다.
2. ATG에 refund_order와 같은 HTTP Tool을 등록합니다.
3. Dify의 HTTP Tool이 /api/v1/invoke/{tool_name}을 호출하도록 설정합니다.
4. ATG가 Agent API key를 인증합니다.
5. ATG가 정책을 평가합니다: allow (허용), deny (거부), approve (승인 필요), 또는 redact (비식별화).
6. 승인이 필요한 경우, ATG는 승인 기록을 생성하고 아직 대상 API를 호출하지 않습니다.
7. 실행이 허용되면, ATG가 비즈니스 API를 호출합니다.
8. ATG가 응답을 비식별화(redact)하고 호출/감사(audit) 기록을 작성합니다.
9. Dify가 거버넌스가 적용된 결과를 수신합니다.

세 가지 데모 정책 (Three Demo Policies)

1. 환불 승인 (Refund Approval)

• 소액 환불은 즉시 실행됩니다.
• 고액 환불은 pending_approval을 반환합니다.
• 승인자가 ATG 웹 콘솔(Web Console)에서 요청을 검토합니다.
• ATG는 승인이 완료된 후에만 실제 환불 API를 호출합니다.

이를 통해 승인이 사후 기록이 아닌, 실행 전에 이루어짐을 확인할 수 있습니다.

2. CRM 비식별화 (CRM Redaction)

• CRM은 전화번호, 이메일, ID와 같은 값을 반환합니다.
• ATG는 Dify에 반환하기 전에 응답을 비식별화(redact)합니다.
• 감사(Audit) 기록에도 비식별화된 결과가 저장됩니다.

Agent는 보아서는 안 될 민감한 데이터를 받지 않고도 작업을 계속할 수 있습니다.

3. 위험한 작업 거부 (Dangerous Operation Denial)

• delete_user는 거부(deny) 정책에 해당합니다.
• ATG는 대상 API를 호출하지 않습니다.
• 감사 로그(Audit logs)에 거부된 작업이 기록됩니다.

로컬 검증 (Local Verification)

npm run install:local
npm run doctor:local
npm run dev:local
...

npm run dify:local은 examples/dify/http-tool.refund-order.json을 읽고, Dify가 사용하는 것과 동일한 HTTP 형태(shape)로 ATG를 호출하여 호출 및 감사 기록을 검증합니다.

이것이 단순한 Dify 플러그인이 아닌 이유

ATG를 단순한 Dify 플러그인으로 이해해서는 안 됩니다.

Dify는 하나의 진입점(entry point)일 뿐입니다. MCP 클라이언트, LangChain, Python SDK, TypeScript SDK 및 커스텀 Agent들도 동일한 게이트웨이로 진입할 수 있습니다. 중앙 집중화되어야 하는 것은 기업용 제어 평면(enterprise control plane)입니다:

• Agent 신원 (Agent identity);
• 도구 레지스트리 (Tool registry);
• 정책 (Policy);
• 승인 (Approval);
• 비식별화 (Redaction);
• 자격 증명 격리 (Credential isolation);
• 감사 (Audit).

에이전트 (Agent) 프레임워크를 변경한다고 해서 거버넌스 (Governance) 모델까지 변경할 필요는 없어야 합니다.

권장 대상

• Dify 프라이빗 배포 (Private deployment) 사용자
• Dify 통합 (Integrator) 담당자
• 기업용 AI 애플리케이션 팀
• 에이전트 (Agent)에 내부 API를 노출하는 백엔드 (Backend) 팀
• 에이전트 (Agent) 동작의 리스크를 평가하는 보안 또는 아키텍처 (Architecture) 팀

결론

Dify는 AI 워크플로 (Workflows)를 오케스트레이션 (Orchestrate)해야 합니다. ATG는 도구 호출 (Tool calls)을 거버넌스 (Govern)해야 합니다.

이러한 경계 설정을 통해 팀은 권한 (Permissions), 승인 (Approval), 비식별화 (Redaction), 자격 증명 격리 (Credential isolation), 그리고 감사 증거 (Audit evidence)를 중앙 집중화하면서도 Dify의 사용자 경험을 유지할 수 있습니다.

GitHub: https://github.com/demonzym-hash/agent-tool-gateway