Agent Governance Toolkit

프롬프트가 아니라 코드에서 에이전트 행동을 막는 마이크로소프트 거버넌스 툴킷

pip install "agent-governance-toolkit[full]"

자율 에이전트에 정책 집행과 신원, 샌드박스, 운영 관제를 붙이는 마이크로소프트 툴킷입니다. 도구 호출과 메시지 발송, 위임을 모델의 의도가 나가기 전에 결정적인 애플리케이션 코드에서 가로채기 때문에, 정책이 막은 동작은 일어나기 어려운 정도가 아니라 구조적으로 불가능해집니다. YAML 정책 파일 하나와 두 줄짜리 래핑으로 시작하고 프레임워크를 가리지 않습니다.

판단

이럴 때 씁니다

  • 에이전트가 닿을 수 있는 서비스가 아니라 연결된 뒤에 할 수 있는 동작을 제한해야 할 때
  • 여러 에이전트가 API 키 하나를 공유해 사고 발생 시 주체를 특정할 수 없을 때
  • 감사나 규제 대응을 위해 어떤 정책이 살아 있었고 왜 허용되거나 거부됐는지 기록이 필요할 때
  • 파괴적 작업이나 외부 발송에 사람 승인 단계를 강제해야 할 때
  • 파이썬 외에 타입스크립트나 .NET 쪽에서도 같은 정책을 걸어야 할 때

이럴 땐 쓰지 마세요

  • GA 안정성이 필요할 때. 공개 프리뷰이며 GA 전 파괴적 변경이 예고돼 있습니다
  • 프롬프트 수준 안전장치만으로 충분한 단순한 사내 실험일 때
  • 파이썬 3.11 이상을 두지 못하는 환경일 때
  • 정책을 코드가 아니라 모델 지시문으로 관리하려는 방침일 때

차별점

  • 정책 평가가 프롬프트가 아니라 결정적인 애플리케이션 코드에서 일어납니다. 모델이 설득당해도 실행 경로가 열리지 않습니다.
  • 허용 여부와 행위 주체 식별과 감사 증적을 한 제품이 함께 다룹니다. OAuth 범위나 IAM 역할이 답하지 못하는 질문을 맡습니다.
  • 정책이 YAML 이고 도구 래핑이 두 줄이라 프레임워크를 바꾸지 않고 얹을 수 있습니다.
  • PyPI 와 npm, NuGet 으로 배포되고 타입스크립트, .NET, 러스트, 고 예제를 함께 제공합니다.
  • OWASP Agentic Top 10 전 항목 대응을 문서로 매핑해 두었습니다.

워크플로

  1. 01full 엑스트라를 붙여 설치합니다. 기본 휠은 컴플라이언스 CLI 만 깔리고 거버넌스 모듈이 빠집니다.
  2. 02YAML 정책 파일을 씁니다. 기본 동작을 정하고 조건별로 거부나 승인 요구 규칙을 얹습니다.
  3. 03govern 으로 도구 함수를 감쌉니다. 호출마다 정책을 평가하고 감사 기록을 남기며 막힌 경우 예외를 던집니다.
  4. 04프로그램적 제어가 필요하면 AgentControl 로 매니페스트를 읽어 직접 평가합니다.
  5. 05Claude Code 에서 쓰려면 플러그인 마켓플레이스로 추가한 뒤 거버넌스 플러그인을 설치합니다.

주요 명령

명령설명
pip install "agent-governance-toolkit[full]"거버넌스 모듈까지 설치합니다. full 없이는 컴플라이언스 CLI 만 들어옵니다.
govern(my_tool, policy="policy.yaml")도구 함수를 감쌉니다. 호출마다 평가와 감사 기록이 붙고 차단 시 GovernanceDenied 가 발생합니다.
/plugin marketplace add microsoft/agent-governance-toolkitClaude Code 에 마켓플레이스로 등록합니다. 이어서 agt-governance 플러그인을 설치합니다.
agt-policiesv4 정책을 v5 로 옮기는 단방향 마이그레이션 명령입니다.

함정

설치 전에 확인하세요

  • 기본 휠에는 거버넌스 모듈이 없습니다. full 엑스트라나 core 배포판을 따로 받아야 예제가 그대로 돕니다.
  • agent_os 를 임포트하면 DeprecationWarning 이 납니다. 옛 agent-os-kernel 배포판이 폐기됐고 core 배포판이 대체입니다.
  • ACS 이전의 agent_os.policies 규칙 모델은 아예 사라졌습니다. 대체 항목은 BREAKING_CHANGES.md 에 정리돼 있습니다.
  • v4 에서 v5 로 가는 정책 마이그레이션은 단방향입니다. 되돌릴 계획을 세우고 실행해야 합니다.
  • 공개 프리뷰라 GA 전에 파괴적 변경이 있을 수 있다고 저장소가 명시합니다.

검토 메모

공식 문서·릴리스·공개 자료를 바탕으로 정리한 편집 메모입니다.

저는 이 툴킷이 내세우는 논거가 이 분야에서 드물게 정직하다고 봅니다. 프롬프트로 안전을 확보하려는 시도가 왜 통제 수단이 될 수 없는지를 인용과 함께 먼저 깔고, 그래서 검사 지점을 도구 호출 경계로 옮겼다고 설명합니다. 막힌 동작이 일어나기 어려운 정도가 아니라 구조적으로 불가능하다는 표현은 과장이 아니라 아키텍처를 그대로 옮긴 문장입니다.

실무에서 값이 나는 지점은 세 번째 질문이라고 생각합니다. 무엇을 허용할지는 어떻게든 짜 볼 수 있지만, 사고가 났을 때 어떤 정책이 살아 있었고 무엇이 요청됐고 왜 거부됐는지를 남기는 일은 나중에 붙이기가 특히 어렵습니다. 감사 기록을 처음부터 같은 경로에 묶어 둔 설계를 저는 높게 봅니다.

다만 지금 올리라고 권하기는 어렵습니다. 공개 프리뷰이고 GA 전 파괴적 변경이 예고돼 있으며, 이미 ACS 이전 규칙 모델이 통째로 사라진 전례가 있습니다. v4 에서 v5 로 가는 마이그레이션도 단방향입니다. 도입한다면 BREAKING_CHANGES 문서를 먼저 읽고, 정책 파일을 애플리케이션 코드와 같은 수준으로 버전 관리할 준비가 됐는지부터 확인하시기 바랍니다.

조직 단위로 검토한다면 배포 범위가 넓다는 점이 판단에 들어갈 만합니다. 파이썬만이 아니라 npm 과 NuGet 으로도 나오고 타입스크립트와 .NET, 러스트, 고 예제가 함께 있어서, 서비스마다 언어가 다른 환경에서도 같은 정책 개념을 걸 수 있습니다. OWASP 의 에이전트 위험 목록 전 항목을 문서로 매핑해 둔 것도 보안 검토를 받아야 하는 팀에는 실질적인 시간 절약입니다. 다만 그 매핑은 대응 설계를 보여 주는 문서이지 인증이 아니므로, 근거 자료로 제출할 때는 그 구분을 분명히 하시는 편이 안전합니다.

비교

가드레일 계열 도구가 모델 입출력을 검사해 위험한 내용을 걸러 낸다면, 이쪽은 검사 지점을 아예 도구 호출 경계로 옮깁니다. 프롬프트 주입이 성공하더라도 정책이 막은 함수는 실행되지 않는다는 점이 차이입니다. 대신 정책을 코드와 함께 관리해야 하는 부담이 생깁니다.

최근 변경

v5.0.0에서는 Python·TypeScript·.NET·Rust 1차 패키지를 5.0.0으로 정렬하고 Agent Control Specification 정책 계층, Nono 커널 샌드박스, 전역 명령 denylist와 감사 정보를 강화했습니다.

공식 변경 내역