에이전트 정의

권한 정책

에이전트 및 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의 모든 도구에 정책을 선택적으로 적용할 수 있습니다:

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }')

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

MCP 도구셋 권한

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

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

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

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Dev Assistant",
    "model": "claude-sonnet-4-6",
    "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 배열을 사용하여 개별 도구의 기본값을 재정의합니다. 이 예시는 전체 에이전트 도구셋을 기본적으로 허용하지만 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 이벤트를 발생시킵니다.
세션이 stop_reason: requires_action을 포함하는 session.status_idle 이벤트와 함께 일시 중지됩니다. 차단 이벤트 ID는 stop_reason.requires_action.event_ids 배열에 있습니다.
각각에 대해 user.tool_confirmation 이벤트를 전송하고, tool_use_id 파라미터에 이벤트 ID를 전달합니다. result를 "allow" 또는 "deny"로 설정합니다. 거부 시 deny_message를 사용하여 이유를 설명합니다.
모든 차단 이벤트가 해결되면 세션이 다시 running 상태로 전환됩니다.

이벤트 처리에 대한 자세한 내용은 세션 이벤트 스트림 가이드를 참조하세요.

# 도구 실행 허용
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$AGENT_TOOL_USE_EVENT_ID'",
        "result": "allow"
      }
    ]
  }'

# 또는 설명과 함께 거부
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "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의 모든 도구에 정책을 선택적으로 적용할 수 있습니다:

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "permission_policy": {"type": "always_ask"}
        }
      }
    ]
  }')

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

MCP 도구셋 권한

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

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

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Dev Assistant",
    "model": "claude-sonnet-4-6",
    "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"}
        }
      }
    ]
  }')

개별 도구 정책 재정의

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 이벤트를 발생시킵니다.
세션이 stop_reason: requires_action을 포함하는 session.status_idle 이벤트와 함께 일시 중지됩니다. 차단 이벤트 ID는 stop_reason.requires_action.event_ids 배열에 있습니다.
각각에 대해 user.tool_confirmation 이벤트를 전송하고, tool_use_id 파라미터에 이벤트 ID를 전달합니다. result를 "allow" 또는 "deny"로 설정합니다. 거부 시 deny_message를 사용하여 이유를 설명합니다.
모든 차단 이벤트가 해결되면 세션이 다시 running 상태로 전환됩니다.

이벤트 처리에 대한 자세한 내용은 세션 이벤트 스트림 가이드를 참조하세요.

# 도구 실행 허용
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "'$AGENT_TOOL_USE_EVENT_ID'",
        "result": "allow"
      }
    ]
  }'

# 또는 설명과 함께 거부
curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "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?