권한 정책

에이전트 및 MCP 도구 실행 시기를 제어합니다.

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

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

권한 정책 유형

정책	동작
`always_allow`	도구가 확인 없이 자동으로 실행됩니다.
`always_ask`	세션이 `session.status_idle` 이벤트를 내보내고 실행하기 전에 `user.tool_confirmation` 이벤트를 기다립니다.

도구 세트에 대한 정책 설정

에이전트 도구 세트 권한

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

ant beta:agents create <<'YAML'
name: Coding Assistant
model: claude-opus-4-7
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 항목에서 permission_policy를 설정하세요.

mcp_server_name은 mcp_servers 배열에서 참조되는 name과 일치해야 합니다.

이 예제는 GitHub MCP 서버를 연결하고 확인 없이 도구를 실행할 수 있도록 허용합니다:

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-7
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 배열을 사용하여 개별 도구의 기본값을 재정의합니다. 이 예제는 전체 에이전트 도구 세트를 기본적으로 허용하지만 bash 명령이 실행되기 전에 확인을 요구합니다:

tools = [
    {
        "type": "agent_toolset_20260401",
        "default_config": {
            "permission_policy": {"type": "always_allow"},
        },
        "configs": [
            {
                "name": "bash",
                "permission_policy": {"type": "always_ask"},
            },
        ],
    },
]

확인 요청에 응답

에이전트가 always_ask 정책으로 도구를 호출할 때:

세션이 agent.tool_use 또는 agent.mcp_tool_use 이벤트를 내보냅니다.
세션이 session.status_idle 이벤트와 함께 일시 중지되며 stop_reason: requires_action을 포함합니다. 차단 이벤트 ID는 stop_reason.requires_action.event_ids 배열에 있습니다.
각각에 대해 user.tool_confirmation 이벤트를 보내고 tool_use_id 매개변수에 이벤트 ID를 전달합니다. result를 "allow" 또는 "deny"로 설정합니다. deny_message를 사용하여 거부 이유를 설명합니다.
모든 차단 이벤트가 해결되면 세션이 running으로 전환됩니다.

세션 이벤트 스트림 가이드에서 이벤트 처리에 대해 자세히 알아보세요.

# 도구 실행 허용
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를 다시 보내기 전에 실행 여부를 결정할 책임이 있습니다. 전체 흐름은 세션 이벤트 스트림을 참조하세요.

Was this page helpful?

빌드에이전트 정의

권한 정책

에이전트 및 MCP 도구 실행 시기를 제어합니다.

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

권한 정책 유형

정책	동작
`always_allow`	도구가 확인 없이 자동으로 실행됩니다.
`always_ask`	세션이 `session.status_idle` 이벤트를 내보내고 실행하기 전에 `user.tool_confirmation` 이벤트를 기다립니다.

도구 세트에 대한 정책 설정

에이전트 도구 세트 권한

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

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

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

MCP 도구 세트 권한

mcp_server_name은 mcp_servers 배열에서 참조되는 name과 일치해야 합니다.

이 예제는 GitHub MCP 서버를 연결하고 확인 없이 도구를 실행할 수 있도록 허용합니다:

ant beta:agents create <<'YAML'
name: Dev Assistant
model: claude-opus-4-7
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

개별 도구 정책 재정의

tools = [
    {
        "type": "agent_toolset_20260401",
        "default_config": {
            "permission_policy": {"type": "always_allow"},
        },
        "configs": [
            {
                "name": "bash",
                "permission_policy": {"type": "always_ask"},
            },
        ],
    },
]

확인 요청에 응답

에이전트가 always_ask 정책으로 도구를 호출할 때:

세션이 agent.tool_use 또는 agent.mcp_tool_use 이벤트를 내보냅니다.
세션이 session.status_idle 이벤트와 함께 일시 중지되며 stop_reason: requires_action을 포함합니다. 차단 이벤트 ID는 stop_reason.requires_action.event_ids 배열에 있습니다.
각각에 대해 user.tool_confirmation 이벤트를 보내고 tool_use_id 매개변수에 이벤트 ID를 전달합니다. result를 "allow" 또는 "deny"로 설정합니다. deny_message를 사용하여 거부 이유를 설명합니다.
모든 차단 이벤트가 해결되면 세션이 running으로 전환됩니다.

세션 이벤트 스트림 가이드에서 이벤트 처리에 대해 자세히 알아보세요.

# 도구 실행 허용
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.",
        },
    ],
)

사용자 정의 도구

Was this page helpful?