🌍 English | 日本語 | 简体中文 | 한국어

Agent Governance Toolkit

에이전트를 프로덕션에 안심하고 배포하세요

🚀 빠른 시작 · 📋 명세 · 📦 PyPI · 📝 변경 이력

[!IMPORTANT] 공개 프리뷰(Public Preview) — 프로덕션 품질의 Microsoft 서명 릴리즈입니다. GA 이전에 주요 변경이 발생할 수 있습니다.

자율형 AI 에이전트를 위한 정책 적용, 신원증명, 샌드박싱, SRE. pip install 하나로 어떤 프레임워크에서도 사용 가능합니다.

문제 상황

여러분의 AI 에이전트는 도구를 호출하고, 웹을 탐색하며, 데이터베이스를 조회하고, 다른 에이전트에게 작업을 위임합니다. 배포 후에는 자율적으로 의사결정을 내립니다. 세 가지 질문에 답할 수 있어야 합니다:

1. 이 동작이 허용되는가? send_email과 query_database에 접근할 수 있는 에이전트가 drop_table을 실행하지 못하도록 해야 합니다. OAuth 스코프와 IAM 역할은 에이전트가 어떤 서비스에 접근할 수 있는지를 제어하지만, 연결된 후 무엇을 하는지는 제어하지 못합니다.

2. 어떤 에이전트가 이 작업을 했는가? 다중 에이전트 시스템에서 다섯 개의 에이전트가 하나의 API 키를 공유할 수 있습니다. 문제가 발생했을 때 "어떤 에이전트가 했다"는 대응은 사고 처리 방식이 될 수 없습니다.

3. 무슨 일이 있었는지 증명할 수 있는가? 감사자와 규제 기관은 모든 의사결정에 대한 변조 불가 기록이 필요합니다: 어떤 정책이 활성화되어 있었는지, 에이전트가 무엇을 요청했는지, 허용 또는 거부된 이유가 무엇인지.

프롬프트 수준의 안전성("규칙을 따르세요")은 통제 수단이 아닙니다. 확률론적 시스템에 대한 공손한 요청일 뿐입니다. OWASP LLM01:2025는 이를 명시적으로 밝힙니다: "프롬프트 인젝션을 완벽하게 방지하는 방법이 존재하는지 불분명하다." 공개된 수치가 이를 뒷받침합니다. Andriushchenko et al. (ICLR 2025)는 logprob 접근과 suffix 최적화를 활용한 적응형 공격을 사용하여, JailbreakBench 벤치마크(Chao et al., NeurIPS 2024) 기준으로 GPT-4o, GPT-3.5, Claude 3, Llama-3에 대해 **공격 성공률 100%**를 보고했습니다. Microsoft의 AI Red Teaming Agent는 적대적 입력 하에서의 정책 위반 비율인 **공격 성공률(ASR, Attack Success Rate)**을 이 유형의 실패에 대한 표준 지표로 공식화합니다. 100개 생성형 AI 제품 레드팀 테스트에서 얻은 교훈은 이 점을 재확인합니다: "완화 조치가 위험을 완전히 제거하지는 않는다" 며 모델 레이어 방어는 본질적으로 확률론적이기 때문에 레드팀 테스트는 지속적인 프로세스여야 한다고 강조합니다.

AGT는 프롬프트 내부에서 이 싸움을 이기려 하지 않습니다. 모든 도구 호출, 메시지 전송, 위임 작업은 모델의 의도가 실행되기 전에 결정론적 애플리케이션 코드에서 가로채어집니다. AGT 커널이 거부한 동작은 "가능성이 낮은" 것이 아닙니다. 구조적으로 불가능합니다. 이것이 에이전트에게 올바르게 행동하도록 요청하는 것과 잘못된 행동 자체를 불가능하게 만드는 것의 차이입니다.

빠른 시작

사전 요구 사항: Python 3.10+

pip install agent-governance-toolkit[full]

Claude Code의 경우, AGT를 플러그인 마켓플레이스에 추가하고 거버넌스 플러그인을 설치하세요:

/plugin marketplace add microsoft/agent-governance-toolkit
/plugin install agt-governance@agent-governance-toolkit

두 줄로 어떤 도구 함수에도 거버넌스를 적용하세요:

from agentmesh.governance import govern

safe_tool = govern(my_tool, policy="policy.yaml")   # 모든 호출 검사, 기록, 적용

이것으로 끝입니다. safe_tool은 모든 호출 시 YAML 정책을 평가하고, 의사결정을 기록하며, 동작이 차단되면 GovernanceDenied를 발생시킵니다.

# policy.yaml
apiVersion: governance.toolkit/v1
name: production-policy
default_action: allow
rules:
  - name: block-destructive
    condition: "action.type in ['drop', 'delete', 'truncate']"
    action: deny
    description: "파괴적인 작업은 사람의 승인이 필요합니다"

  - name: require-approval-for-send
    condition: "action.type == 'send_email'"
    action: require_approval
    approvers: ["security-team"]

>>> safe_tool(action="read", table="users")
{'table': 'users', 'rows': 42}

>>> safe_tool(action="drop", table="users")
GovernanceDenied: Action denied by policy rule 'block-destructive':
  파괴적인 작업은 사람의 승인이 필요합니다

또는 프로그래밍 방식 제어를 위해 전체 PolicyEvaluator API를 사용하세요:

from agent_os.policies import (
    PolicyEvaluator, PolicyDocument, PolicyRule,
    PolicyCondition, PolicyAction, PolicyOperator, PolicyDefaults
)

evaluator = PolicyEvaluator(policies=[PolicyDocument(
    name="my-policy", version="1.0",
    defaults=PolicyDefaults(action=PolicyAction.ALLOW),
    rules=[PolicyRule(
        name="block-dangerous-tools",
        condition=PolicyCondition(
            field="tool_name",
            operator=PolicyOperator.IN,
            value=["execute_code", "delete_file"]
        ),
        action=PolicyAction.DENY, priority=100,
    )],
)])

result = evaluator.evaluate({"tool_name": "web_search"})    # 허용됩니다
result = evaluator.evaluate({"tool_name": "delete_file"})   # 차단됩니다

import { PolicyEngine } from "@microsoft/agent-governance-sdk";

const engine = new PolicyEngine([
  { action: "web_search", effect: "allow" },
  { action: "shell_exec", effect: "deny" },
]);
engine.evaluate("web_search"); // "허용"
engine.evaluate("shell_exec"); // "차단"

using AgentGovernance;
using AgentGovernance.Extensions.ModelContextProtocol;
using AgentGovernance.Policy;

var kernel = new GovernanceKernel(new GovernanceOptions
{
    PolicyPaths = new() { "policies/default.yaml" },
});
var result = kernel.EvaluateToolCall("did:mesh:agent-1", "web_search",
    new() { ["query"] = "latest AI news" });

// MCP 서버 연동
builder.Services.AddMcpServer()
    .WithGovernance(options => options.PolicyPaths.Add("policies/mcp.yaml"));

use agent_governance::{AgentMeshClient, ClientOptions};

let client = AgentMeshClient::new("my-agent").unwrap();
let result = client.execute_with_governance("data.read", None);
assert!(result.allowed);

import agentmesh "github.com/microsoft/agent-governance-toolkit/agent-governance-golang"

client, _ := agentmesh.NewClient("my-agent",
    agentmesh.WithPolicyRules([]agentmesh.PolicyRule{
        {Action: "data.read", Effect: agentmesh.Allow},
        {Action: "*", Effect: agentmesh.Deny},
    }),
)
result := client.ExecuteWithGovernance("data.read", nil)

CLI 도구:

agt doctor                                        # 설치 상태 확인
agt verify                                        # OWASP 컴플라이언스 확인
agt verify --evidence ./agt-evidence.json --strict # 증거 부족 시 CI 실패 처리
agt red-team scan ./prompts/ --min-grade B         # 프롬프트 인젝션 감사
agt lint-policy policies/                          # 정책 파일 검증

전체 과정: quickstart.md — 5분 만에 거버넌스가 적용된 에이전트 완성. 🌍 다음 언어로도 제공됩니다: 日本語 | 简体中文 | English

동작 원리

Agent ──► Policy Engine ──► Identity ──► Audit Log
            (YAML/OPA/Cedar)  (SPIFFE/DID/mTLS)  (변조 불가)
                 │                                      │
                 ├── Allowed ──► 도구 실행               │
                 └── Denied  ──► GovernanceDenied        │
                                                        ▼
                                                 Decision Record

모든 레이어는 선택 사항입니다. govern()으로 시작하고 리스크 프로파일에 따라 레이어를 추가하세요. 대부분의 팀은 정책 적용과 감사 로깅만으로도 충분합니다.

패키지

추가 기능

설치 방법

5개 언어 SDK 모두 핵심 거버넌스(정책, 신원, 신뢰, 감사)를 구현합니다. Python은 풀 스택을 지원합니다. Copilot CLI와 Claude Code는 TypeScript SDK 위에 구축된 1st-party 개발자 인터페이스입니다. **언어 패키지 매트릭스**에서 언어별 상세 지원 현황을 확인하세요.

사전 요구 사항

• Python: 3.10+
• Node.js: 18+ / npm 9+ (TypeScript SDK)
• .NET: 8+
• Go: 1.25+
• Rust: 1.70+
• 선택 사항: Azure 연동 기능을 위한 AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

프레임워크 지원

전체 목록: 프레임워크 연동 · Quickstart 예제

예제

명세 (Specifications)

모든 주요 컴포넌트는 적합성 테스트가 포함된 공식 RFC 2119 명세를 가지고 있습니다. 이 명세들은 구현체가 MUST, SHOULD, MAY로 무엇을 해야 하는지 정의하는 동작 계약입니다.

992개의 적합성 테스트로 코드와 명세의 일치를 보장합니다. 25개 아키텍처 결정 기록이 그 이유를 문서화합니다.

표준 컴플라이언스

보안 (Security)

AGT는 OS 커널 레벨이 아닌 애플리케이션 미들웨어 레이어에서 거버넌스를 적용합니다. 정책 엔진과 에이전트는 동일한 프로세스 경계를 공유합니다.

운영 환경 권장 사항: OS 레벨 격리를 위해 각 에이전트를 별도 컨테이너에서 실행하세요. 아키텍처: 보안 경계를 참고하세요.

정직한 설계 경계와 권장 계층 방어에 대해서는 알려진 제약 사항을 참고하세요.

문서 (Documentation)

기여하기 (Contributing)

기여 가이드 · 커뮤니티 · Discord · 보안 정책 · 변경 이력

AGT를 사용 중이신가요? ADOPTERS.md에 귀하의 조직을 추가해 주세요.

거버넌스 (Governance)

중요 고지 사항

제3자 에이전트 프레임워크 또는 서비스와 연동되는 애플리케이션을 구축하기 위해 Agent Governance Toolkit을 사용하는 경우, 그에 따른 책임은 사용자 본인에게 있습니다. 제3자 서비스와 공유되는 모든 데이터를 검토하고, 해당 서비스의 데이터 보유 및 보관 위치에 대한 정책을 숙지할 것을 권장합니다.

공식 소스

Agent Governance Toolkit의 공식 소스는 다음과 같습니다:

프로젝트 팀은 공식임을 주장하는 제3자 웹사이트, 패키지, 또는 문서 사이트를 유지 관리하거나 보증하지 않습니다. Agent Governance Toolkit 이름을 사용하는 의심스러운 사이트나 패키지를 발견하면 SECURITY.md에 설명된 채널을 통해 신고해 주세요.

라이선스 (License)

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.

상표 (Trademarks)

본 프로젝트에는 프로젝트, 제품 또는 서비스에 대한 상표 또는 로고가 포함될 수 있습니다. Microsoft 상표 또는 로고의 허용된 사용은 Microsoft의 상표 및 브랜드 가이드라인을 준수해야 합니다. 본 프로젝트의 수정된 버전에서 Microsoft 상표 또는 로고를 사용할 때 혼란을 야기하거나 Microsoft의 후원을 암시해서는 안 됩니다. 제3자 상표 또는 로고의 사용은 해당 제3자의 정책을 따릅니다.