권한 정책

"Permission policy"(권한 정책)는 서버에서 실행되는 도구(사전 구축된 "agent toolset"(에이전트 도구 세트)과 MCP 도구 세트)를 자동으로 실행할지, 승인을 기다릴지, 아니면 서버가 각 호출을 평가하도록 할지를 제어합니다. "Custom tool"(사용자 정의 도구)은 애플리케이션이 실행하고 사용자가 직접 제어하므로 권한 정책의 적용을 받지 않습니다.

권한 정책 유형

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

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

도구 세트에 대한 정책 설정

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

에이전트 도구 세트 권한

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

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_ask
---

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 apply agent.md

---
name: Dev Assistant
model: claude-opus-5-5
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
---

개별 도구 정책 재정의

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

ant apply agent.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: always_allow
    configs:
      - name: bash
        permission_policy:
          type: always_ask
---

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

auto로 서버가 각 호출을 평가하도록 하기

auto 권한 정책을 사용하면 서버가 각 호출을 실행하기 전에 평가합니다. 평가 시 도구, 호출의 입력, 그리고 해당 시점까지의 세션 내용을 고려하므로, 서버는 같은 도구에 대한 두 호출을 서로 다르게 처리할 수 있습니다. 각 호출의 결과는 다음 세 가지 중 하나입니다:

• 호출이 실행됩니다. 서버가 호출이 안전하다고 판단하면, 도구는 always_allow에서와 같이 실행됩니다.
• 호출이 거부됩니다. 서버가 호출을 고위험으로 평가하면 도구가 실행되지 않습니다. 에이전트는 Permission to use {tool_name} has been denied. 내용과 is_error: true가 포함된 오류 도구 결과를 받습니다. 세션은 계속 실행되며, 클라이언트는 이 거부를 재정의할 수 없습니다.
• 호출이 승인을 위해 일시 중지됩니다. 서버가 판단을 내리지 못하면, 세션은 always_ask에서와 같이 일시 중지됩니다. 확인 요청에 응답하기를 참조하세요.

auto를 활성화하려면 permission_policy를 {"type": "auto"}로 설정하세요. 다른 정책과 동일한 두 위치에 설정합니다. 전체 도구 세트에 적용하려면 도구 세트의 default_config에, 하나의 도구에 적용하려면 configs 항목에 설정합니다. 에이전트 도구 세트와 MCP 도구 세트 모두 이를 지원합니다. 기본적으로 auto를 사용하는 도구 세트는 없습니다.

다음 예시는 에이전트 도구 세트와 github MCP 도구 세트의 기본값으로 auto를 설정하고, bash를 always_ask로 재정의합니다:

ant apply agent.md

---
name: Ops Agent
model: claude-opus-5-5
mcp_servers:
  - type: url
    name: github
    url: https://mcp.example.com/github
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy:
        type: auto
    configs:
      - name: bash
        permission_policy:
          type: always_ask
  - type: mcp_toolset
    mcp_server_name: github
    default_config:
      permission_policy:
        type: auto
---

user.message 이벤트에 게시하는 내용은 사용자의 의도로 간주되며, 서버가 원래라면 거부했을 호출을 허용하게 만들 수 있습니다. 서버는 도구 결과, 가져온 웹페이지, MCP 서버의 응답, 또는 세션 스레드 간의 메시지에서는 의도를 읽지 않습니다. 서버는 해당 내용을 평가하지만 그로부터 지시를 받지는 않습니다. 일부 호출은 누가 요청하든 서버가 고위험으로 평가합니다. 신뢰할 수 없는 최종 사용자 입력을 user.message 이벤트로 전달하면, 서버는 그 입력도 사용자의 의도로 읽으며 이로 인해 호출이 허용될 수 있습니다. 해당 최종 사용자가 검토 없이 실행하도록 두고 싶지 않은 도구에는 always_ask를 구성하세요.

각 호출이 어떻게 평가되었는지 확인하기

어떤 권한 정책에서든 각 agent.tool_use 및 agent.mcp_tool_use 이벤트에는 호출의 권한 검사 결과인 evaluated_permission이 포함되며, 그 값은 "allow", "ask", 또는 "deny"입니다. 대부분의 이벤트에는 evaluation 객체도 포함되며, 이 객체의 type은 해당 결과를 만든 정책을 나타냅니다. auto에서는 이 객체에 서버의 판단도 기록되며, 결과가 ask 또는 deny인 경우 reason_code도 함께 기록됩니다.

예를 들어, bash가 auto 정책 아래에 있고 서버가 호출을 고위험으로 평가하면, 거부된 호출은 이벤트 스트림에 다음과 같이 나타납니다:

{
  "type": "agent.tool_use",
  "id": "sevt_01pqr...",
  "name": "bash",
  "input": {
    "command": "rm -rf /workspace/reports"
  },
  "evaluated_permission": "deny",
  "evaluation": {
    "type": "auto",
    "evaluated_permission": {
      "type": "deny",
      "reason_code": "high_risk"
    }
  },
  "processed_at": "2026-03-25T14:05:12Z"
}

evaluation 객체는 다음 표의 형태 중 하나를 가집니다.

evaluation.type이 "auto"인 경우, 중첩된 evaluated_permission.type은 이벤트의 최상위 evaluated_permission과 동일한 값을 가지므로 어느 필드에서든 결과를 읽을 수 있습니다. reason_code는 클라이언트가 분기 처리하고 감사 기록에 보관하기 위한 값이며, 최종 사용자에게 표시하기 위한 텍스트가 아닙니다.

evaluation은 두 가지 경우에 존재하지 않습니다. 에이전트가 세션에서 활성화되지 않은 도구를 지정하면, 서버는 정책을 평가하지 않고 호출을 거부합니다. 이때 이벤트에는 evaluated_permission: "deny"가 포함되고 evaluation은 포함되지 않습니다. evaluation이 도입되기 전에 기록된 이벤트에도 이 필드가 없습니다. 이러한 이벤트는 evaluated_permission이 "allow"이면 always_allow로, "ask"이면 always_ask로 해석하세요.

클라이언트는 인식하지 못하는 evaluation.type 또는 reason_code도 처리할 수 있도록 작성하세요. 권한 정책은 사용자 정의 도구에 적용되지 않으므로, agent.custom_tool_use 이벤트에는 두 필드 모두 포함되지 않습니다.

확인 요청에 응답하기

도구 호출은 always_ask 정책에서, 또는 auto에서 서버가 판단을 내리지 못한 경우 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 이벤트를 전송하고, tool_use_id 매개변수에 이벤트 ID를 전달하세요. result를 "allow" 또는 "deny"로 설정하세요. 거부 사유를 설명하려면 deny_message를 사용하세요. 단일 events 요청에 여러 확인을 보낼 수 있습니다.
4. 모든 차단 이벤트가 해결되면 세션은 다시 running 상태로 전환됩니다. 허용된 도구는 실행됩니다. 거부된 도구는 실행되지 않으며, 에이전트는 deny_message를 포함하여 호출이 거부되었다는 도구 결과를 받습니다.

evaluated_permission이 ask가 아닌 이벤트에 대해 user.tool_confirmation을 보내면 API가 400 오류로 이를 거부합니다. 여기에는 auto에서 서버가 거부한 호출도 포함되며, 클라이언트는 이를 재정의할 수 없습니다.

대신 대화형으로 응답하려면 ant beta:sessions connect를 사용하세요. 이 명령은 대기 중인 호출을 보여 주고, 허용하거나 거부하면 이 이벤트를 전송합니다. 터미널에서 Managed Agents 세션에 연결하기를 참조하세요.

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

# 도구 실행을 허용합니다
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# 또는 설명과 함께 거부합니다
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "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를 다시 보내기 전에 해당 도구를 실행할지 여부를 결정할 책임이 있습니다. 전체 흐름은 세션 이벤트 스트림을 참조하세요.

다음 단계