권한 정책

권한 정책 (Permission policies)

권한 정책은 서버에서 실행되는 도구(사전 구축된 에이전트 도구세트와 MCP 도구세트)가 자동으로 실행될지, 승인을 기다릴지, 아니면 서버가 각 호출을 평가할지를 제어해요. 커스텀 도구는 여러분의 애플리케이션이 실행하고 여러분이 제어하므로 권한 정책의 적용을 받지 않아요.

출처: 문서

본문

권한 정책 유형 (Permission policy types)

정책 (Policy)	동작 (Behavior)
`always_allow`	도구가 확인 없이 자동으로 실행돼요.
`always_ask`	세션이 멈추고 실행 전에 여러분의 승인을 기다려요. 이벤트 흐름은 확인 요청에 응답하기를 참고하세요.
`auto`	서버가 각 호출을 평가해서 실행하거나, 거부하거나, 승인을 위해 멈춰요. `auto`로 각 호출을 서버가 평가하도록 하기를 참고하세요.

각 도구세트 종류는 자체 기본값을 가져요: 에이전트 도구세트는 always_allow로, MCP 도구세트는 always_ask로 기본 설정돼요.

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

도구세트에 정책 설정하기 (Set a policy for a toolset)

에이전트를 만들 때 에이전트의 tools 구성에서 권한 정책을 설정하고, 나중에 에이전트 업데이트로 변경할 수 있어요. 실행 중인 세션은 만들어진 시점의 도구세트 구성을 유지해요. 업데이트는 이후에 만들어진 세션에 적용돼요.

에이전트 도구세트 권한 (Agent toolset permissions)

에이전트를 만들 때 agent_toolset_20260401의 모든 도구에 default_config.permission_policy로 정책을 적용할 수 있어요:

<File filename="agent.md">
  ```markdown
  ---
  name: Coding Assistant
  model: claude-opus-5-5
  tools:
    - type: agent_toolset_20260401
      default_config:
        permission_policy:
          type: always_ask
  ---
  ```
</File>

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-5-5",
    tools=[
        {
            "type": "agent_toolset_20260401",
            "default_config": {
                "permission_policy": {"type": "always_ask"},
            },
        },
    ],
)

const agent = await client.beta.agents.create({
  name: "Coding Assistant",
  model: "claude-opus-5-5",
  tools: [
    {
      type: "agent_toolset_20260401",
      default_config: {
        permission_policy: { type: "always_ask" }
      }
    }
  ]
});

using Anthropic.Models.Beta.Agents;

var agent = await client.Beta.Agents.Create(new()
{
    Name = "Coding Assistant",
    Model = BetaManagedAgentsModel.ClaudeOpus5_5,
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
            DefaultConfig = new()
            {
                PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" },
            },
        },
    ],
});

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Coding Assistant",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: "claude-opus-5-5",
	},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{{
		OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
			Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{
				PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{
					OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{
						Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk,
					},
				},
			},
		},
	}},
})
if err != nil {
	panic(err)
}
_ = agent

import com.anthropic.models.beta.agents.*;

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("Coding Assistant")
        .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
        .addTool(
            BetaManagedAgentsAgentToolset20260401Params.builder()
                .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                .defaultConfig(
                    BetaManagedAgentsAgentToolsetDefaultConfigParams.builder()
                        .permissionPolicy(
                            BetaManagedAgentsAlwaysAskPolicy.builder()
                                .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK)
                                .build()
                        )
                        .build()
                )
                .build()
        )
        .build()
);

use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy;

$agent = $client->beta->agents->create(
    name: 'Coding Assistant',
    model: 'claude-opus-5-5',
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
            defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with(
                permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'),
            ),
        ),
    ],
);

agent = client.beta.agents.create(
  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 toolset permissions)

MCP 도구세트는 always_ask로 기본 설정돼요. 이렇게 하면 MCP 서버에 새로 추가된 도구가 승인 없이 여러분의 애플리케이션에서 실행되지 않아요. 신뢰하는 MCP 서버의 도구를 자동 승인하려면 mcp_toolset 항목에 default_config.permission_policy를 설정하세요.

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

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

```bash cURL agent=$(curl -fsSL https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHR...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-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"} } } ] }') ``` ```bash CLI ant apply agent.md ```

<File filename="agent.md">
  ```markdown
  ---
  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
  ---
  ```
</File>

agent = client.beta.agents.create(
    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"},
            },
        },
    ],
)

const agent = await client.beta.agents.create({
  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" }
      }
    }
  ]
});

using Anthropic.Models.Beta.Agents;

var agent = await client.Beta.Agents.Create(new()
{
    Name = "Dev Assistant",
    Model = BetaManagedAgentsModel.ClaudeOpus5_5,
    McpServers =
    [
        new()
        {
            Type = BetaManagedAgentsUrlMcpServerParamsType.Url,
            Name = "github",
            Url = "https://mcp.example.com/github",
        },
    ],
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
        },
        new BetaManagedAgentsMcpToolsetParams
        {
            Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset,
            McpServerName = "github",
            DefaultConfig = new()
            {
                PermissionPolicy = new BetaManagedAgentsAlwaysAllowPolicy { Type = "always_allow" },
            },
        },
    ],
});

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Dev Assistant",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: "claude-opus-5-5",
	},
	MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
		Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
		Name: "github",
		URL:  "https://mcp.example.com/github",
	}},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{
		{
			OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
				Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
			},
		},
		{
			OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
				Type:          anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
				MCPServerName: "github",
				DefaultConfig: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParams{
					PermissionPolicy: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnion{
						OfAlwaysAllow: &anthropic.BetaManagedAgentsAlwaysAllowPolicyParam{
							Type: anthropic.BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow,
						},
					},
				},
			},
		},
	},
})
if err != nil {
	panic(err)
}
_ = agent

import com.anthropic.models.beta.agents.*;

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("Dev Assistant")
        .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
        .addMcpServer(
            BetaManagedAgentsUrlMcpServerParams.builder()
                .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
                .name("github")
                .url("https://mcp.example.com/github")
                .build()
        )
        .addTool(
            BetaManagedAgentsAgentToolset20260401Params.builder()
                .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                .build()
        )
        .addTool(
            BetaManagedAgentsMcpToolsetParams.builder()
                .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
                .mcpServerName("github")
                .defaultConfig(
                    BetaManagedAgentsMcpToolsetDefaultConfigParams.builder()
                        .permissionPolicy(
                            BetaManagedAgentsAlwaysAllowPolicy.builder()
                                .type(BetaManagedAgentsAlwaysAllowPolicy.Type.ALWAYS_ALLOW)
                                .build()
                        )
                        .build()
                )
                .build()
        )
        .build()
);

use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAllowPolicy;
use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetDefaultConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams;
use Anthropic\Beta\Agents\BetaManagedAgentsURLMCPServerParams;

$agent = $client->beta->agents->create(
    name: 'Dev Assistant',
    model: 'claude-opus-5-5',
    mcpServers: [
        BetaManagedAgentsURLMCPServerParams::with(
            type: 'url',
            name: 'github',
            url: 'https://mcp.example.com/github',
        ),
    ],
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
        ),
        BetaManagedAgentsMCPToolsetParams::with(
            type: 'mcp_toolset',
            mcpServerName: 'github',
            defaultConfig: BetaManagedAgentsMCPToolsetDefaultConfigParams::with(
                permissionPolicy: BetaManagedAgentsAlwaysAllowPolicy::with(type: 'always_allow'),
            ),
        ),
    ],
);

agent = client.beta.agents.create(
  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"}
      }
    }
  ]
)

개별 도구 정책 재정의하기 (Override an individual tool policy)

configs 배열을 사용해 개별 도구의 기본값을 재정의하세요. 에이전트 도구세트의 name 값은 사용 가능한 도구에 나열돼 있어요. 이 예시는 전체 에이전트 도구세트는 기본적으로 허용하지만 어떤 bash 명령이든 실행 전에 확인을 요구해요:

```bash cURL tools='[ { "type": "agent_toolset_20260401", "default_config": { "permission_policy": {"type": "always_allow"} }, "configs": [ { "name": "bash", "permission_policy": {"type": "always_ask"} } ] } ]' ``` ```bash CLI ant apply agent.md ```

<File filename="agent.md">
  ```markdown
  ---
  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
  ---
  ```
</File>

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

const tools = [
  {
    type: "agent_toolset_20260401",
    default_config: {
      permission_policy: { type: "always_allow" }
    },
    configs: [
      {
        name: "bash",
        permission_policy: { type: "always_ask" }
      }
    ]
  }
] satisfies Anthropic.Beta.AgentCreateParams["tools"];

using Anthropic.Models.Beta.Agents;
using Tool = Anthropic.Models.Beta.Agents.Tool;

Tool[] tools =
[
    new BetaManagedAgentsAgentToolset20260401Params
    {
        Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
        DefaultConfig = new()
        {
            PermissionPolicy = new BetaManagedAgentsAlwaysAllowPolicy { Type = "always_allow" },
        },
        Configs =
        [
            new BetaManagedAgentsBashToolConfigParams
            {
                PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" },
            },
        ],
    },
];

tools := []anthropic.BetaAgentNewParamsToolUnion{{
	OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
		Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
		DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{
			PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{
				OfAlwaysAllow: &anthropic.BetaManagedAgentsAlwaysAllowPolicyParam{
					Type: anthropic.BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow,
				},
			},
		},
		Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{
			OfBash: &anthropic.BetaManagedAgentsBashToolConfigParams{
				PermissionPolicy: anthropic.BetaManagedAgentsBashToolConfigParamsPermissionPolicyUnion{
					OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{
						Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk,
					},
				},
			},
		}},
	},
}}
_ = tools

import com.anthropic.models.beta.agents.*;
import java.util.List;

var tools = List.of(
    AgentCreateParams.Tool.ofAgentToolset20260401(
        BetaManagedAgentsAgentToolset20260401Params.builder()
            .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
            .defaultConfig(
                BetaManagedAgentsAgentToolsetDefaultConfigParams.builder()
                    .permissionPolicy(
                        BetaManagedAgentsAlwaysAllowPolicy.builder()
                            .type(BetaManagedAgentsAlwaysAllowPolicy.Type.ALWAYS_ALLOW)
                            .build()
                    )
                    .build()
            )
            .addConfig(
                BetaManagedAgentsBashToolConfigParams.builder()
                    .permissionPolicy(
                        BetaManagedAgentsAlwaysAskPolicy.builder()
                            .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK)
                            .build()
                    )
                    .build()
            )
            .build()
    )
);

use Anthropic\Beta\Agents\BetaManagedAgentsBashToolConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAllowPolicy;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy;

$tools = [
    BetaManagedAgentsAgentToolset20260401Params::with(
        type: 'agent_toolset_20260401',
        defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with(
            permissionPolicy: BetaManagedAgentsAlwaysAllowPolicy::with(type: 'always_allow'),
        ),
        configs: [
            BetaManagedAgentsBashToolConfigParams::with(
                permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'),
            ),
        ],
    ),
];

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`로 각 호출을 서버가 평가하도록 하기 (Let the server evaluate each call with `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로 재정의해요:

```bash cURL agent=$(curl -fsSL https://api.anthropic.com/v1/agents \ -H "x-api-key: $ANTHR...KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "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"} } } ] }') ``` ```bash CLI ant apply agent.md ```

<File filename="agent.md">
  ```markdown
  ---
  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
  ---
  ```
</File>

agent = client.beta.agents.create(
    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"},
            },
        },
    ],
)

const agent = await client.beta.agents.create({
  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" }
      }
    }
  ]
});

using Anthropic.Models.Beta.Agents;

var agent = await client.Beta.Agents.Create(new()
{
    Name = "Ops Agent",
    Model = BetaManagedAgentsModel.ClaudeOpus5_5,
    McpServers =
    [
        new()
        {
            Type = BetaManagedAgentsUrlMcpServerParamsType.Url,
            Name = "github",
            Url = "https://mcp.example.com/github",
        },
    ],
    Tools =
    [
        new BetaManagedAgentsAgentToolset20260401Params
        {
            Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401,
            DefaultConfig = new()
            {
                PermissionPolicy = new BetaManagedAgentsAutoPolicy(),
            },
            Configs =
            [
                new BetaManagedAgentsBashToolConfigParams
                {
                    PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" },
                },
            ],
        },
        new BetaManagedAgentsMcpToolsetParams
        {
            Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset,
            McpServerName = "github",
            DefaultConfig = new()
            {
                PermissionPolicy = new BetaManagedAgentsAutoPolicy(),
            },
        },
    ],
});

agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
	Name: "Ops Agent",
	Model: anthropic.BetaManagedAgentsModelConfigParams{
		ID: "claude-opus-5-5",
	},
	MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{{
		Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL,
		Name: "github",
		URL:  "https://mcp.example.com/github",
	}},
	Tools: []anthropic.BetaAgentNewParamsToolUnion{
		{
			OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
				Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
				DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{
					PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{
						OfAuto: &anthropic.BetaManagedAgentsAutoPolicyParam{},
					},
				},
				Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{{
					OfBash: &anthropic.BetaManagedAgentsBashToolConfigParams{
						PermissionPolicy: anthropic.BetaManagedAgentsBashToolConfigParamsPermissionPolicyUnion{
							OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{
								Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk,
							},
						},
					},
				}},
			},
		},
		{
			OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{
				Type:          anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset,
				MCPServerName: "github",
				DefaultConfig: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParams{
					PermissionPolicy: anthropic.BetaManagedAgentsMCPToolsetDefaultConfigParamsPermissionPolicyUnion{
						OfAuto: &anthropic.BetaManagedAgentsAutoPolicyParam{},
					},
				},
			},
		},
	},
})
if err != nil {
	panic(err)
}
_ = agent

import com.anthropic.models.beta.agents.*;

var agent = client.beta().agents().create(
    AgentCreateParams.builder()
        .name("Ops Agent")
        .model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
        .addMcpServer(
            BetaManagedAgentsUrlMcpServerParams.builder()
                .type(BetaManagedAgentsUrlMcpServerParams.Type.URL)
                .name("github")
                .url("https://mcp.example.com/github")
                .build()
        )
        .addTool(
            BetaManagedAgentsAgentToolset20260401Params.builder()
                .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
                .defaultConfig(
                    BetaManagedAgentsAgentToolsetDefaultConfigParams.builder()
                        .permissionPolicy(BetaManagedAgentsAutoPolicy.builder().build())
                        .build()
                )
                .addConfig(
                    BetaManagedAgentsBashToolConfigParams.builder()
                        .permissionPolicy(
                            BetaManagedAgentsAlwaysAskPolicy.builder()
                                .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK)
                                .build()
                        )
                        .build()
                )
                .build()
        )
        .addTool(
            BetaManagedAgentsMcpToolsetParams.builder()
                .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET)
                .mcpServerName("github")
                .defaultConfig(
                    BetaManagedAgentsMcpToolsetDefaultConfigParams.builder()
                        .permissionPolicy(BetaManagedAgentsAutoPolicy.builder().build())
                        .build()
                )
                .build()
        )
        .build()
);

use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy;
use Anthropic\Beta\Agents\BetaManagedAgentsAutoPolicy;
use Anthropic\Beta\Agents\BetaManagedAgentsBashToolConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetDefaultConfigParams;
use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams;
use Anthropic\Beta\Agents\BetaManagedAgentsURLMCPServerParams;

$agent = $client->beta->agents->create(
    name: 'Ops Agent',
    model: 'claude-opus-5-5',
    mcpServers: [
        BetaManagedAgentsURLMCPServerParams::with(
            type: 'url',
            name: 'github',
            url: 'https://mcp.example.com/github',
        ),
    ],
    tools: [
        BetaManagedAgentsAgentToolset20260401Params::with(
            type: 'agent_toolset_20260401',
            defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with(
                permissionPolicy: BetaManagedAgentsAutoPolicy::with(),
            ),
            configs: [
                BetaManagedAgentsBashToolConfigParams::with(
                    permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'),
                ),
            ],
        ),
        BetaManagedAgentsMCPToolsetParams::with(
            type: 'mcp_toolset',
            mcpServerName: 'github',
            defaultConfig: BetaManagedAgentsMCPToolsetDefaultConfigParams::with(
                permissionPolicy: BetaManagedAgentsAutoPolicy::with(),
            ),
        ),
    ],
);

agent = client.beta.agents.create(
  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를 구성하세요.

`auto`는 인간 체크포인트가 아니에요. 서버가 호출이 안전하다고 판단하면 호출은 누구도 보기 전에 실행되고, 그 효과는 되돌릴 수 없을 수 있어요. 사람이 도구의 호출을 실행 전에 검토해야 한다면, 그 도구에 `always_ask`를 구성하세요.

각 호출이 어떻게 평가됐는지 보기 (See how each call was evaluated)

어떤 권한 정책 아래에서든 각 agent.tool_use와 agent.mcp_tool_use 이벤트는 호출의 권한 검사 결과인 evaluated_permission을 실어 나르며, "allow", "ask", "deny" 값을 가져요. 대부분의 이벤트는 결과를 만든 정책의 이름을 담은 evaluation 객체도 실어요. 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`	최상위 `evaluated_permission`	의미 (Meaning)
`{"type": "always_allow"}`	`"allow"`	해결된 정책이 `always_allow`라서 호출이 실행됐어요.
`{"type": "always_ask"}`	`"ask"`	해결된 정책이 `always_ask`라서 호출이 승인을 위해 멈췄어요.
`{"type": "auto", "evaluated_permission": {"type": "allow"}}`	`"allow"`	`auto` 아래에서 서버가 호출이 안전하다고 판단해서 실행됐어요.
`{"type": "auto", "evaluated_permission": {"type": "ask", "reason_code": "indeterminate"}}`	`"ask"`	`auto` 아래에서 서버가 판단에 이르지 못해서 호출이 승인을 위해 멈췄어요.
`{"type": "auto", "evaluated_permission": {"type": "deny", "reason_code": "high_risk"}}`	`"deny"`	`auto` 아래에서 서버가 호출을 고위험으로 평가해서 거부했어요.

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 이벤트는 두 필드 모두 실어 나르지 않는데, 권한 정책이 커스텀 도구를 관장하지 않기 때문이에요.

확인 요청에 응답하기 (Respond to confirmation requests)

도구 호출은 always_ask 정책 아래에서, 또는 auto 아래에서 서버가 판단에 이르지 못했을 때 ask로 평가돼요. 그런 일이 생기면:

세션이 agent.tool_use 또는 agent.mcp_tool_use 이벤트를 발행해요.
세션이 stop_reason.type이 requires_action인 session.status_idle 이벤트로 멈춰요. 차단 이벤트 ID는 stop_reason.event_ids 배열에 있어요. 세션은 응답을 무기한 기다려요.
각 차단 이벤트에 user.tool_confirmation 이벤트를 보내고, tool_use_id 파라미터에 이벤트 ID를 전달하세요. result를 "allow" 또는 "deny"로 설정하세요. 거부를 설명하려면 deny_message를 사용하세요. 여러 확인을 단일 events 요청에 보낼 수 있어요.
모든 차단 이벤트가 해결되면 세션이 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 배열에서 옵니다. 이벤트 받기에 대해 자세히 알아보려면 세션 이벤트 스트림 가이드를 참고하거나, 웹훅 구독으로 세션이 입력을 기다리며 멈췄을 때 알림을 받으세요.

```bash cURL # Allow the tool to execute curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \ -H "x-api-key: $ANTHR...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" } ] }'

Or deny it with an explanation

curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events"
-H "x-api-key: $ANTHR...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." } ] }'


```bash CLI
# Allow the tool to execute
ant beta:sessions:events send \
  --session-id "$SESSION_ID" \
  --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"

# Or deny it with an explanation
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.}"

# Allow the tool to execute
client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.tool_confirmation",
            "tool_use_id": agent_tool_use_event.id,
            "result": "allow",
        },
    ],
)

# Or deny it with an explanation
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.",
        },
    ],
)

// Allow the tool to execute
await client.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.tool_confirmation",
      tool_use_id: agent_tool_use_event.id,
      result: "allow"
    }
  ]
});

// Or deny it with an explanation
await 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."
    }
  ]
});

// Allow the tool to execute
await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserToolConfirmationEventParams
        {
            Type = BetaManagedAgentsUserToolConfirmationEventParamsType.UserToolConfirmation,
            ToolUseID = agentToolUseEvent.ID,
            Result = "allow",
        },
    ],
});

// Or deny it with an explanation
await client.Beta.Sessions.Events.Send(session.ID, new()
{
    Events =
    [
        new BetaManagedAgentsUserToolConfirmationEventParams
        {
            Type = BetaManagedAgentsUserToolConfirmationEventParamsType.UserToolConfirmation,
            ToolUseID = mcpToolUseEvent.ID,
            Result = "deny",
            DenyMessage = "Don't create issues in the production project. Use the staging project.",
        },
    ],
});

// Allow the tool to execute
_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
		OfUserToolConfirmation: &anthropic.BetaManagedAgentsUserToolConfirmationEventParams{
			Type:      anthropic.BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation,
			ToolUseID: agentToolUseEvent.ID,
			Result:    anthropic.BetaManagedAgentsUserToolConfirmationEventParamsResultAllow,
		},
	}},
})
if err != nil {
	panic(err)
}

// Or deny it with an explanation
_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
		OfUserToolConfirmation: &anthropic.BetaManagedAgentsUserToolConfirmationEventParams{
			Type:        anthropic.BetaManagedAgentsUserToolConfirmationEventParamsTypeUserToolConfirmation,
			ToolUseID:   mcpToolUseEvent.ID,
			Result:      anthropic.BetaManagedAgentsUserToolConfirmationEventParamsResultDeny,
			DenyMessage: anthropic.String("Don't create issues in the production project. Use the staging project."),
		},
	}},
})
if err != nil {
	panic(err)
}

// Allow the tool to execute
client.beta().sessions().events().send(
    session.id(),
    EventSendParams.builder()
        .addEvent(
            BetaManagedAgentsUserToolConfirmationEventParams.builder()
                .type(BetaManagedAgentsUserToolConfirmationEventParams.Type.USER_TOOL_CONFIRMATION)
                .toolUseId(agentToolUseEvent.id())
                .result(BetaManagedAgentsUserToolConfirmationEventParams.Result.ALLOW)
                .build()
        )
        .build()
);

// Or deny it with an explanation
client.beta().sessions().events().send(
    session.id(),
    EventSendParams.builder()
        .addEvent(
            BetaManagedAgentsUserToolConfirmationEventParams.builder()
                .type(BetaManagedAgentsUserToolConfirmationEventParams.Type.USER_TOOL_CONFIRMATION)
                .toolUseId(mcpToolUseEvent.id())
                .result(BetaManagedAgentsUserToolConfirmationEventParams.Result.DENY)
                .denyMessage("Don't create issues in the production project. Use the staging project.")
                .build()
        )
        .build()
);

use Anthropic\Beta\Sessions\Events\ManagedAgentsUserToolConfirmationEventParams;

// Allow the tool to execute
$client->beta->sessions->events->send(
    $session->id,
    events: [
        ManagedAgentsUserToolConfirmationEventParams::with(
            type: 'user.tool_confirmation',
            toolUseID: $agentToolUseEvent->id,
            result: 'allow',
        ),
    ],
);

// Or deny it with an explanation
$client->beta->sessions->events->send(
    $session->id,
    events: [
        ManagedAgentsUserToolConfirmationEventParams::with(
            type: 'user.tool_confirmation',
            toolUseID: $mcpToolUseEvent->id,
            result: 'deny',
            denyMessage: "Don't create issues in the production project. Use the staging project.",
        ),
    ],
);

# Allow the tool to execute
client.beta.sessions.events.send_(
  session.id,
  events: [
    {
      type: "user.tool_confirmation",
      tool_use_id: agent_tool_use_event.id,
      result: "allow"
    }
  ]
)

# Or deny it with an explanation
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."
    }
  ]
)

커스텀 도구 (Custom tools)

권한 정책은 커스텀 도구에 적용되지 않아요. 에이전트가 커스텀 도구를 호출하면 여러분의 애플리케이션이 agent.custom_tool_use 이벤트를 받고, user.custom_tool_result를 다시 보내기 전에 실행 여부를 결정하는 책임이 있어요. 전체 흐름은 세션 이벤트 스트림을 참고하세요.

다음 단계 (Next steps)

도메인 특화 워크플로를 위해 재사용 가능한 파일시스템 기반 전문성을 에이전트에 붙이세요. 이벤트를 보내고, 응답을 스트리밍하고, 실행 중에 세션을 중단하거나 방향을 바꾸세요.

더 알아보기 (Learn more)

스킬 — 재사용 가능한 전문성을 에이전트에 붙이기
세션 이벤트 스트림 — 이벤트 보내기와 세션 방향 바꾸기
도구 — 도구세트와 개별 도구 구성