권한 정책

권한 정책은 서버에서 실행되는 도구(사전 구축된 에이전트 도구 세트 및 MCP 도구 세트)가 자동으로 실행되는지 또는 사용자의 승인을 기다리는지를 제어합니다. 사용자 정의 도구는 애플리케이션에서 실행되고 사용자가 제어하므로 권한 정책의 적용을 받지 않습니다.



권한 정책 유형

각 도구 세트 종류에는 고유한 기본값이 있습니다. 에이전트 도구 세트는 기본적으로 always_allow이고, MCP 도구 세트는 기본적으로 always_ask입니다.

권한 정책은 활성화된 도구가 실행되는 시점을 제어합니다. 에이전트에서 도구를 완전히 제거하려면 대신 도구를 비활성화하세요. 특정 도구 비활성화를 참조하세요.



도구 세트에 정책 설정하기

에이전트를 생성할 때 에이전트의 tools 구성에서 권한 정책을 설정하며, 나중에 에이전트를 업데이트하여 변경할 수 있습니다. 실행 중인 세션은 생성 당시의 도구 세트 구성을 유지합니다. 업데이트는 이후에 생성된 세션에 적용됩니다.



에이전트 도구 세트 권한

에이전트를 생성할 때 default_config.permission_policy를 사용하여 agent_toolset_20260401의 모든 도구에 정책을 적용할 수 있습니다.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
YAML

default_config는 선택 사항입니다. 이를 생략하면 에이전트 도구 세트는 기본 권한 정책인 always_allow로 활성화됩니다.



MCP 도구 세트 권한

MCP 도구 세트는 기본적으로 always_ask입니다. 이는 MCP 서버에 추가된 새 도구가 승인 없이 애플리케이션에서 실행되지 않도록 보장합니다. 신뢰할 수 있는 MCP 서버의 도구를 자동 승인하려면 mcp_toolset 항목에서 default_config.permission_policy를 설정하세요.

mcp_server_name은 mcp_servers 배열에 있는 서버의 name과 일치해야 합니다.

다음 예제는 GitHub MCP 서버를 연결하고 해당 도구가 확인 없이 실행되도록 허용합니다.

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-8
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: always_allow
YAML



개별 도구 정책 재정의하기

configs 배열을 사용하여 개별 도구의 기본값을 재정의할 수 있습니다. 에이전트 도구 세트의 name 값은 사용 가능한 도구에 나열되어 있습니다. 다음 예제는 기본적으로 전체 에이전트 도구 세트를 허용하지만 bash 명령이 실행되기 전에 확인을 요구합니다.

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-8
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
YAML

이 tools 구성을 에이전트 생성 요청에 전달하세요(CLI 탭에 전체 명령이 표시됩니다). MCP 도구 세트도 동일한 도구별 재정의를 지원하며, name은 MCP 서버에서 보고하는 도구 이름으로 설정합니다. 사용 가능한 MCP 도구 구성하기를 참조하세요.



확인 요청에 응답하기

에이전트가 always_ask 정책이 적용된 도구를 호출하면 다음과 같이 진행됩니다.

1. 세션이 agent.tool_use 또는 agent.mcp_tool_use 이벤트를 내보냅니다.
2. 세션이 stop_reason.type이 requires_action인 session.status_idle 이벤트와 함께 일시 중지됩니다. 차단 중인 이벤트 ID는 stop_reason.event_ids 배열에 있습니다. 세션은 응답을 무기한 기다립니다.
3. 각 차단 이벤트에 대해 user.tool_confirmation 이벤트를 전송하고, 이벤트 ID를 tool_use_id 매개변수에 전달하세요. result를 "allow" 또는 "deny"로 설정하세요. 거부 이유를 설명하려면 deny_message를 사용하세요. 단일 events 요청으로 여러 확인을 전송할 수 있습니다.
4. 모든 차단 이벤트가 해결되면 세션이 다시 running 상태로 전환됩니다. 허용된 도구는 실행됩니다. 거부된 도구는 실행되지 않으며, 에이전트는 호출이 거부되었다는 도구 결과를 deny_message와 함께 받습니다.

다음 예제에서 도구 사용 이벤트 ID는 session.status_idle 이벤트의 stop_reason.event_ids 배열에서 가져옵니다. 이벤트 수신에 대한 자세한 내용은 세션 이벤트 스트림 가이드를 참조하거나, 세션이 입력을 위해 일시 중지될 때 알림을 받으려면 웹훅을 구독하세요.

# 도구 실행을 허용합니다
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# 또는 설명과 함께 거부합니다
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $MCP_TOOL_USE_EVENT_ID, result: deny,
    deny_message: Don't create issues in the production project. Use the staging project.}"



사용자 정의 도구

권한 정책은 사용자 정의 도구에 적용되지 않습니다. 에이전트가 사용자 정의 도구를 호출하면 애플리케이션이 agent.custom_tool_use 이벤트를 수신하며, user.custom_tool_result를 다시 전송하기 전에 실행 여부를 결정할 책임이 있습니다. 전체 흐름은 세션 이벤트 스트림을 참조하세요.



다음 단계