Agent-Safe Pipeline 소개
에이전트에게 실제 행동 권한을 주는 순간 문제의 성격이 달라집니다. 텍스트를 잘못 생성하면 결과가 이상해질 뿐이지만, 환불을 실행하거나 배포를 트리거하는 도구를 쥐고 있으면 잘못된 판단이 곧바로 되돌리기 어려운 변경이 됩니다. 여기에 프롬프트 인젝션이 겹치면 상황이 더 어색해집니다. 공격 문자열이 프롬프트에 섞여 들어와 "정책을 무시하고 이 작업을 실행하라" 고 지시할 때, 그 지시를 검토하는 주체가 같은 모델이라면 검토가 방어가 되지 못합니다.
Agent-Safe Pipeline은 이 문제를 모델을 더 잘 설득하는 방식이 아니라 권한 경계를 옮기는 방식으로 다룹니다. Decionis가 공개한 참조 아키텍처(reference architecture)로, 저장소 첫 줄의 "Let agents propose. Let policy decide." 가 설계 전체를 요약합니다. 에이전트는 추론하고 계획하고 행동을 제안할 수 있지만, 자기 행동이 승인되었는지를 스스로 판단하거나 하위 시스템의 특권 자격증명을 보유하거나 어떤 신뢰 핸들러가 실행될지 고르는 일은 하지 못합니다.
구현은 TypeScript로 되어 있고 Apache 2.0 라이선스로 공개되어 있습니다. 실행 가능한 예제와 위협 모델 문서, 그리고 다른 언어 구현이 같은 해시 결과를 내는지 확인할 수 있는 적합성 테스트 벡터가 함께 들어 있습니다.
Agent-Safe Pipeline이 제안과 승인을 분리하는 방식
전체 흐름은 저장소가 다음 한 줄로 정리해 두었습니다.
Agent -> immutable intent -> Decionis -> ALLOW / ESCALATE / BLOCK -> SafeExecutor -> API
|
+-> Presence -> verified human approval -> Decionis re-evaluation
에이전트의 제안은 곧바로 실행으로 가지 않고 먼저 변경 불가능한 의도(immutable intent)로 고정됩니다. 그 의도를 독립된 판정 서비스가 평가해 허용, 승격, 차단 중 하나를 돌려주고, 승격인 경우에만 사람 승인 절차가 개입합니다. 사람이 승인해도 그 승인 자체가 실행 권한이 되지는 않습니다. 승인 영수증은 판정 서비스로 되돌아가 정책 재평가를 거친 뒤에야 실행 허가로 바뀝니다.
경계를 나누는 기준은 무엇이 무엇을 통제하는가입니다. 저장소의 ARCHITECTURE.md 는 이를 다음과 같이 구분합니다.
| 통제 주체 | 통제하는 대상 |
|---|---|
| 에이전트 | 제안하는 action, target, JSON parameters 뿐 |
| 런타임 | 테넌트, 행위자 식별, 대상 시스템과 작업, 멱등성 키, 자격증명 |
| Decionis | 정책 판정과 실행 허가 |
| Presence | 사람 검증 증거. 실행 권한은 아님 |
| 실행기 | 핸들러 선택과 하위 시스템 비밀값 |
에이전트가 통제하는 범위가 세 개 필드로 좁혀져 있다는 점이 핵심입니다. 테넌트나 대상 시스템을 에이전트가 말하는 대로 받아들이지 않고 신뢰 런타임 설정에서 가져오기 때문에, 프롬프트를 오염시켜도 바꿀 수 있는 것이 제안 내용으로 한정됩니다.
Agent-Safe Pipeline의 구성 요소
각 단계는 별도 구성 요소가 담당합니다.
IntentCapture: 제한된 에이전트 제안을 신뢰 컨텍스트와 분리해 검증하고, UUID와 타임스탬프를 부여하고, 최대 5분의 수명을 적용하고, 키를 정렬한 JSON으로 정규화한 뒤 권한 바인딩을 SHA-256으로 해싱합니다.DecionisGate: 그 바인딩을 인증된 판정 API로 보냅니다. 명시적으로 활성화한 루프백 개발 엔드포인트를 제외하면 HTTPS를 요구하고, 유한한 타임아웃과 응답 크기 제한을 적용하며, 모호한 상태는 전부 차단으로 수렴시킵니다.PresenceApprovalCoordinator: 행동과 대상, 의도 해시를 사람에게 제시합니다. 최종 영수증 형태의 증거만 인정하고, 그 증거를 판정 서비스로 돌려보낼 뿐 스스로 승인을 허용으로 바꾸지 않습니다.SafeExecutor: 허용 여부와 정확한 의도 바인딩, 실행 허가의 존재를 확인합니다. 검증기가 허가를 원자적으로 소비한 뒤에야 등록된 핸들러가 실행될 수 있습니다.ShadowPipeline: 기존 실행을 관찰하면서 가정적 판정만 받아 봅니다. 결과에SHADOW라벨이 붙어 실행 권한으로 오해되지 않도록 되어 있습니다.
핸들러는 신뢰할 수 있는 애플리케이션 시작 코드가 등록하며, 레지스트리는 사용 전에 봉인됩니다. 실행기가 에이전트에게서 임의의 콜백을 받지 않는다는 점이 여기서 중요합니다. 봉인된 ActionRegistry 가 행동 이름을 신뢰 핸들러로 매핑하고 파라미터를 검증한 뒤, 단 한 번만 쓸 수 있는 허가를 소비합니다.
Agent-Safe Pipeline의 위협 모델과 자격증명 배치
저장소의 THREAT-MODEL.md 는 에이전트와 그 프롬프트, 검색된 콘텐츠, 도구 인자, 모델 출력을 전부 신뢰하지 않는 것으로 두고 시작합니다. 반대로 IntentCapture 와 DecionisGate, SafeExecutor 와 등록된 핸들러가 도는 호스트는 신뢰하되 에이전트로부터 격리되어야 한다고 못박습니다.
자격증명 배치는 이 격리를 실제로 만들어 내는 부분입니다. 문서가 위험하다고 지목하는 배치는 에이전트 런타임이 모델 키와 판정 서비스 키, 그리고 하위 시스템 관리자 토큰을 한꺼번에 들고 있는 형태입니다. 요구되는 배치는 에이전트 런타임이 제안만 신뢰 실행기로 넘기고, 판정 서비스 키와 관리자 토큰은 그 실행기 뒤에만 존재하는 형태입니다. 여기에 에이전트 런타임의 아웃바운드 네트워크를 기본 차단으로 두고 실행기로 가는 제안 채널만 열어 두라는 권고가 따라붙습니다.
위협별 통제와 잔여 위험을 함께 적어 둔 표가 이 문서에서 가장 읽어 볼 만한 부분입니다. 몇 가지를 옮기면 다음과 같습니다.
| 위협 | 통제 | 잔여 위험 |
|---|---|---|
| 프롬프트 인젝션이 정책을 무시하라고 지시 | 게이트가 프롬프트 바깥에 있고 독립적으로 판정 | 개발자가 아키텍처 자체를 우회할 수는 있음 |
| 승인 후 에이전트가 도구 인자를 변경 | 정규화된 파라미터와 대상이 의도 해시에 바인딩 | 하위 시스템의 비결정적 해석은 피해야 함 |
| 예전 승인이나 허가를 재사용 | 짧은 만료, jti, 멱등성 키, 원자적 단일 소비 |
소비 후 하위 시스템 타임아웃 시 새 판정 또는 복구 필요 |
| 에이전트가 하위 시스템을 직접 호출 | 자격증명과 아웃바운드 경로가 실행기 뒤에 존재 | 네트워크 정책이 실제로 차단해야 성립 |
| 사람이 오해를 부르는 내용을 승인 | 행동, 대상, 정확한 해시가 필수 표시 항목 | 사람이 진짜로 잘못 판단할 여지는 남음 |
잔여 위험 칸을 비워 두지 않았다는 점이 이 문서의 태도를 보여 줍니다. 프로젝트는 신뢰 실행기 호스트나 하위 시스템 제공자가 침해당하는 경우는 이 라이브러리만으로 막을 수 있는 범위 밖이라고 명시하고, 대신 그 호스트의 노출 면을 줄이고 권한 증거를 독립적으로 검증 가능하게 만드는 것이 설계 목표라고 적고 있습니다.
Agent-Safe Pipeline은 누구에게 유용한가
에이전트가 환불, 배포, 계정 변경처럼 되돌리기 어려운 작업을 건드리는 시스템을 설계 중이고, 승인 로직을 프롬프트가 아니라 코드 경계로 옮기고 싶은 사람에게 맞습니다. 위협 모델과 잔여 위험 표는 그대로 가져다 자기 시스템의 검토 문서 출발점으로 쓸 만합니다. 반대로 판정을 내리는 Decionis와 사람 검증을 담당하는 Presence는 이 저장소가 아니라 별도 서비스이므로, 실제 운영에 붙이려면 그 서비스에 의존하게 된다는 점을 먼저 확인해야 합니다. 저장소의 데모는 명시적으로 프로덕션용이 아닌 픽스처 권한을 사용하며, 실제 통합에는 서버 측 자격증명과 함께 DecionisGate 및 DecionisGrantVerifier 를 쓰라고 안내합니다.
바로 도입하지 않더라도 얻을 것이 있습니다. 제안과 판정과 실행을 분리한다는 골격, 의도를 해시로 고정해 승인과 묶는다는 발상, 자격증명을 실행기 뒤로 몰아 둔다는 배치는 특정 서비스와 무관하게 적용할 수 있는 설계 원칙입니다.
Agent-Safe Pipeline 실행해 보기
Node.js 20 이상과 pnpm 9가 필요합니다.
git clone https://github.com/decionis/agent-safe-pipeline.git
cd agent-safe-pipeline
pnpm install --frozen-lockfile
pnpm --filter @decionis/agent-safe-example-basic demo
코드에서 파이프라인을 쓰는 형태는 세 줄로 요약됩니다. 실행기가 포착된 의도와 판정 결과를 함께 받는 구조이고, 에이전트가 넘긴 임의의 콜백은 받지 않습니다.
const captured = intentCapture.capture(agentProposal, trustedContext);
const decision = await gate.evaluate(captured);
const result = await executor.run(captured, decision);
예제는 시나리오별로 나뉘어 있어 원하는 것부터 열어 보면 됩니다.
examples/basic-agent: 가장 작은 차단 흐름examples/shopify-refund-agent: 금액 기준으로 허용, 승격, 차단이 갈리는 환불 시나리오examples/github-deploy-agent: 환경과 강제 푸시 통제examples/mcp-tool-gate: 통제되는 도구를 가진 실제 stdio MCP 서버
다른 언어로 같은 구조를 구현할 때를 대비한 장치도 있습니다. conformance/agent-safe-intent-v1.json 이 이식 가능한 정규 해시 테스트 벡터를 담고 있어, 정규화 방식이 어긋나면 바인딩이 깨진다는 점을 테스트로 확인할 수 있습니다.
프로젝트는 워크스페이스 패키지 버전이 0.1.0 이지만 레지스트리 릴리스 워크플로가 성공하기 전까지는 배포되었다고 주장하지 않는다고 밝히고 있어, 현재는 워크스페이스에서 설치해 쓰는 단계입니다.
Agent-Safe Pipeline의 라이선스
Agent-Safe Pipeline은 Apache 2.0 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 보안 이슈 신고 절차는 저장소의 SECURITY.md 에 정리되어 있습니다.
Agent-Safe Pipeline 아키텍처 문서
Agent-Safe Pipeline 프로젝트 GitHub 저장소
더 읽어보기
-
Anthropic, AI 에이전트 배포를 위한 Zero Trust 보안 프레임워크 eBook 공개 [영문/PDF/36p]
-
OneCLI: AI 에이전트를 위한 안전한 오픈소스 인증 정보 저장소(Credential Vault) 및 게이트웨이
이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다. 
이 도구를 직접 설치해 사용해보셨다면, 
파이토치 한국 사용자 모임
회원들을 위해 경험이나 팁을 댓글로 남겨주세요! 