---
title: Políticas de permisos
url: https://platform.claude.com/docs/es/managed-agents/permission-policies
description: Controla cuándo se ejecutan las herramientas del agente y de MCP.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
Las "permission policies" (políticas de permisos) controlan si las herramientas ejecutadas por el servidor (el conjunto de herramientas del agente predefinido y el conjunto de herramientas de MCP) se ejecutan automáticamente, esperan tu aprobación o hacen que el servidor evalúe cada llamada. Las herramientas personalizadas las ejecuta tu aplicación y las controlas tú, por lo que no están sujetas a las políticas de permisos.
## Tipos de políticas de permisos
| Política | Comportamiento |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `always_allow` | La herramienta se ejecuta automáticamente sin confirmación. |
| `always_ask` | La sesión se pausa y espera tu aprobación antes de ejecutarse. Consulta [Responder a solicitudes de confirmación](https://platform.claude.com/docs/es/managed-agents/permission-policies#respond-to-confirmation-requests) para ver el flujo de eventos. |
| `auto` | El servidor evalúa cada llamada y la ejecuta, la deniega o se pausa para esperar tu aprobación. Consulta [Deja que el servidor evalúe cada llamada con `auto`](https://platform.claude.com/docs/es/managed-agents/permission-policies#let-the-server-evaluate-each-call-with-auto). |
Cada tipo de conjunto de herramientas tiene su propio valor predeterminado: el conjunto de herramientas del agente usa `always_allow` de forma predeterminada, y los conjuntos de herramientas de MCP usan `always_ask` de forma predeterminada.
Una política de permisos controla cuándo se ejecuta una herramienta habilitada. Para quitar una herramienta del agente por completo, desactívala en su lugar. Consulta [Desactivar herramientas específicas](https://platform.claude.com/docs/es/managed-agents/tools#disabling-specific-tools).
## Establecer una política para un conjunto de herramientas
Estableces las políticas de permisos en la configuración `tools` (csharp, go: `Tools`) del agente cuando lo creas, y puedes cambiarlas más adelante [actualizando el agente](https://platform.claude.com/docs/es/managed-agents/agent-setup#update-an-agent). Las sesiones en ejecución conservan la configuración del conjunto de herramientas con la que se crearon. Las actualizaciones se aplican a las sesiones creadas después.
### Permisos del conjunto de herramientas del agente
Al crear un agente, puedes aplicar una política a todas las herramientas de `agent_toolset_20260401` usando `default_config.permission_policy` (java, php: `defaultConfig.permissionPolicy`; csharp, go: `DefaultConfig.PermissionPolicy`):
```bash cURL
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-opus-5-5",
"tools": [
{
"type": "agent_toolset_20260401",
"default_config": {
"permission_policy": {"type": "always_ask"}
}
}
]
}')
```
```bash CLI
ant apply agent.md
```
```markdown
---
name: Coding Assistant
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
default_config:
permission_policy:
type: always_ask
---
```
```python Python
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"},
},
},
],
)
```
```typescript TypeScript
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" }
}
}
]
});
```
```csharp C#
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" },
},
},
],
});
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Coding Assistant",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_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
```
```java Java
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()
);
```
```php PHP
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'),
),
),
],
);
```
```ruby Ruby
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` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) es opcional. Si lo omites, el conjunto de herramientas del agente se habilita con la política de permisos predeterminada, `always_allow`.
### Permisos del conjunto de herramientas de MCP
Los conjuntos de herramientas de MCP usan `always_ask` de forma predeterminada. Esto garantiza que las nuevas herramientas agregadas a un servidor MCP no se ejecuten en tu aplicación sin aprobación. Para aprobar automáticamente las herramientas de un servidor MCP de confianza, establece `default_config.permission_policy` (java, php: `defaultConfig.permissionPolicy`; csharp, go: `DefaultConfig.PermissionPolicy`) en la entrada `mcp_toolset`.
El `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) debe coincidir con el `name` (csharp, go: `Name`) de un servidor en el arreglo `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).
Este ejemplo conecta un servidor MCP de GitHub y permite que sus herramientas se ejecuten sin confirmación:
```bash cURL
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-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
```
```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
---
```
```python Python
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"},
},
},
],
)
```
```typescript TypeScript
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" }
}
}
]
});
```
```csharp C#
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" },
},
},
],
});
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Dev Assistant",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_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
```
```java Java
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()
);
```
```php PHP
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'),
),
),
],
);
```
```ruby Ruby
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"}
}
}
]
)
```
## Anular la política de una herramienta individual
Usa el arreglo `configs` (csharp, go: `Configs`) para anular el valor predeterminado de herramientas individuales. Los valores de `name` (csharp, go: `Name`) para el conjunto de herramientas del agente se enumeran en [Herramientas disponibles](https://platform.claude.com/docs/es/managed-agents/tools#available-tools). Este ejemplo permite todo el conjunto de herramientas del agente de forma predeterminada, pero requiere confirmación antes de que se ejecute cualquier comando 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
```
```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
---
```
```python Python
tools = [
{
"type": "agent_toolset_20260401",
"default_config": {
"permission_policy": {"type": "always_allow"},
},
"configs": [
{
"name": "bash",
"permission_policy": {"type": "always_ask"},
},
],
},
]
```
```typescript TypeScript
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"];
```
```csharp C#
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" },
},
],
},
];
```
```go Go
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
```
```java Java
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()
)
);
```
```php PHP
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'),
),
],
),
];
```
```ruby Ruby
tools = [
{
type: "agent_toolset_20260401",
default_config: {
permission_policy: {type: "always_allow"}
},
configs: [
{
name: "bash",
permission_policy: {type: "always_ask"}
}
]
}
]
```
Pasa esta configuración `tools` (csharp, go: `Tools`) en la solicitud de creación del agente (la pestaña CLI muestra el comando completo). Los conjuntos de herramientas de MCP admiten las mismas anulaciones por herramienta, con `name` (csharp, go: `Name`) establecido en el nombre de la herramienta que informa el servidor MCP. Consulta [Configurar qué herramientas de MCP están disponibles](https://platform.claude.com/docs/es/managed-agents/mcp-connector#configure-which-mcp-tools-are-available).
## Deja que el servidor evalúe cada llamada con `auto`
Con la política de permisos `auto`, el servidor evalúa cada llamada antes de que se ejecute. Como la evaluación considera la herramienta, la entrada de la llamada y el contenido de la sesión hasta ese momento, el servidor puede tratar de forma diferente dos llamadas a la misma herramienta. Cada llamada tiene uno de tres resultados:
* **La llamada se ejecuta.** Cuando el servidor determina que la llamada es segura, la herramienta se ejecuta como lo haría con `always_allow`.
* **La llamada se deniega.** Cuando el servidor evalúa la llamada como de alto riesgo, la herramienta no se ejecuta. El agente recibe un resultado de herramienta de error con el contenido `Permission to use {tool_name} has been denied.` e `is_error: true`. La sesión sigue ejecutándose y tu cliente no puede anular la denegación.
* **La llamada se pausa para esperar tu aprobación.** Cuando el servidor no llega a ninguna determinación, la sesión se pausa como lo hace con `always_ask`. Consulta [Responder a solicitudes de confirmación](https://platform.claude.com/docs/es/managed-agents/permission-policies#respond-to-confirmation-requests).
Para activar `auto`, establece `permission_policy` en `{"type": "auto"}`. Va en los mismos dos lugares que las demás políticas: el [`default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`)](https://platform.claude.com/docs/es/managed-agents/permission-policies#set-a-policy-for-a-toolset) de un conjunto de herramientas para todo el conjunto, o una [entrada de `configs` (csharp, go: `Configs`)](https://platform.claude.com/docs/es/managed-agents/permission-policies#override-an-individual-tool-policy) para una sola herramienta. Tanto el conjunto de herramientas del agente como los conjuntos de herramientas de MCP lo aceptan. Ningún conjunto de herramientas usa `auto` de forma predeterminada.
El siguiente ejemplo establece `auto` como valor predeterminado para el conjunto de herramientas del agente y para el conjunto de herramientas de MCP `github`, y anula `bash` a `always_ask`:
```bash cURL
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": "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
```
```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
---
```
```python Python
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"},
},
},
],
)
```
```typescript TypeScript
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" }
}
}
]
});
```
```csharp C#
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(),
},
},
],
});
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Ops Agent",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_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
```
```java Java
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()
);
```
```php PHP
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(),
),
),
],
);
```
```ruby Ruby
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"}
}
}
]
)
```
Lo que publicas en los eventos `user.message` cuenta como tu intención, y puede llevar al servidor a permitir una llamada que de otro modo denegaría. El servidor no lee la intención de un resultado de herramienta, una página web obtenida, la respuesta de un servidor MCP ni un mensaje entre [hilos de sesión](https://platform.claude.com/docs/es/managed-agents/session-threads#tool-permissions-and-custom-tools). Evalúa ese contenido, pero no toma instrucciones de él. El servidor evalúa algunas llamadas como de alto riesgo sin importar quién lo pida. Si retransmites entradas no confiables de usuarios finales en eventos `user.message`, el servidor también lee esa entrada como tu intención, y puede lograr que se permita una llamada. Configura `always_ask` en las herramientas que no dejarías que ese usuario final ejecutara sin revisión.
`auto` no es un punto de control humano. Si el servidor determina que una llamada es segura, la llamada se ejecuta antes de que alguien la vea, y sus efectos podrían no ser reversibles. Si una persona debe revisar las llamadas de una herramienta antes de que se ejecuten, configura `always_ask` en esa herramienta.
## Ver cómo se evaluó cada llamada
Con cualquier política de permisos, cada evento `agent.tool_use` y `agent.mcp_tool_use` incluye `evaluated_permission`, el resultado de la verificación de permisos de la llamada: `"allow"`, `"ask"` o `"deny"`. La mayoría de los eventos también incluyen un objeto `evaluation` cuyo `type` nombra la política que produjo ese resultado. Con `auto`, el objeto también registra la determinación del servidor, además de un `reason_code` cuando el resultado es `ask` o `deny`.
Por ejemplo, cuando `bash` está bajo `auto` y el servidor evalúa una llamada como de alto riesgo, la llamada denegada aparece en el flujo de eventos de la siguiente manera:
```json
{
"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"
}
```
El objeto `evaluation` adopta una de las formas de la siguiente tabla.
| `evaluation` | `evaluated_permission` de nivel superior | Significado |
| ------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `{"type": "always_allow"}` | `"allow"` | La política resuelta es `always_allow`, por lo que la llamada se ejecutó. |
| `{"type": "always_ask"}` | `"ask"` | La política resuelta es `always_ask`, por lo que la llamada se pausó para esperar tu aprobación. |
| `{"type": "auto", "evaluated_permission": {"type": "allow"}}` | `"allow"` | Con `auto`, el servidor determinó que la llamada era segura, y se ejecutó. |
| `{"type": "auto", "evaluated_permission": {"type": "ask", "reason_code": "indeterminate"}}` | `"ask"` | Con `auto`, el servidor no llegó a ninguna determinación, por lo que la llamada se pausó para esperar tu aprobación. |
| `{"type": "auto", "evaluated_permission": {"type": "deny", "reason_code": "high_risk"}}` | `"deny"` | Con `auto`, el servidor evaluó la llamada como de alto riesgo y la denegó. |
Cuando `evaluation.type` es `"auto"`, su `evaluated_permission.type` anidado repite el `evaluated_permission` de nivel superior del evento, por lo que puedes leer el resultado desde cualquiera de los dos campos. Un `reason_code` es un valor para que tu cliente tome decisiones de ramificación y lo conserve en registros de auditoría, no un texto para mostrar a los usuarios finales.
`evaluation` está ausente en dos casos. Cuando el agente nombra una herramienta que no está habilitada en la sesión, el servidor deniega la llamada sin evaluar una política: el evento incluye `evaluated_permission: "deny"` y ningún `evaluation`. Los eventos registrados antes de que se introdujera `evaluation` también lo omiten: interprétalos como `always_allow` cuando `evaluated_permission` es `"allow"` y como `always_ask` cuando es `"ask"`.
Escribe tu cliente para que tolere un `evaluation.type` o un `reason_code` que no reconozca. Los eventos `agent.custom_tool_use` no incluyen ninguno de los dos campos, porque las políticas de permisos no rigen las [herramientas personalizadas](https://platform.claude.com/docs/es/managed-agents/permission-policies#custom-tools).
## Responder a solicitudes de confirmación
Una llamada a herramienta se evalúa como `ask` con una política `always_ask`, o con `auto` cuando el servidor no llega a ninguna determinación. Cuando eso sucede:
1. La sesión emite un evento `agent.tool_use` o `agent.mcp_tool_use`.
2. La sesión se pausa con un evento `session.status_idle` cuyo `stop_reason.type` es `requires_action`. Los IDs de los eventos bloqueantes están en el arreglo `stop_reason.event_ids`. La sesión espera indefinidamente una respuesta. Una llamada desde un hilo de una [ejecución de flujo de trabajo](https://platform.claude.com/docs/es/managed-agents/workflow-runs#while-a-run-is-open) llega a tu cliente en el flujo principal. Mientras cualquier otra cosa en la sesión esté trabajando, la sesión puede permanecer en `running` y no enviar ningún `session.status_idle`, así que responde al propio evento de uso de herramienta. La llamada espera solo hasta que la ejecución termine con ese hilo o la ejecución finalice. Una interrupción podría dejarla en espera, así que permítela o deniégala tú mismo.
3. Envía un evento `user.tool_confirmation` por cada evento bloqueante, pasando el ID del evento en el parámetro `tool_use_id` (java: `toolUseId`; php: `toolUseID`; csharp, go: `ToolUseID`). Establece `result` (csharp, go: `Result`) en `"allow"` o `"deny"`. Usa `deny_message` (java, php: `denyMessage`; csharp, go: `DenyMessage`) para explicar una denegación. Puedes enviar varias confirmaciones en una sola solicitud `events`.
4. Una vez resueltos todos los eventos bloqueantes, la sesión vuelve a `running`. Las herramientas permitidas se ejecutan. Las herramientas denegadas no se ejecutan, y el agente recibe un resultado de herramienta que indica que la llamada fue rechazada, incluido tu `deny_message` (java, php: `denyMessage`; csharp, go: `DenyMessage`).
Por ejemplo, una llamada a `bash` pausada con una política `always_ask` aparece en el flujo de la siguiente manera:
```json
{
"type": "agent.tool_use",
"id": "sevt_01def...",
"name": "bash",
"input": {
"command": "pip install -r requirements.txt"
},
"evaluated_permission": "ask",
"evaluation": {
"type": "always_ask"
},
"processed_at": "2026-03-25T14:01:45Z"
}
```
Si envías un `user.tool_confirmation` para un evento cuyo `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) no es `ask`, la API lo rechaza con un error 400. Eso incluye las llamadas que el servidor denegó con `auto`: tu cliente no puede anularlas.
Para responder de forma interactiva, usa `ant beta:sessions connect`, que muestra la llamada en espera y envía este evento cuando la permites o la deniegas. Consulta [Conectarse a una sesión de Managed Agents desde tu terminal](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/sessions-connect#follow-and-steer-the-session).
En los siguientes ejemplos, los IDs de los eventos de uso de herramientas provienen del arreglo `stop_reason.event_ids` del evento `session.status_idle`. Obtén más información sobre cómo recibir eventos en la guía [Flujo de eventos de la sesión](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#stream-events), o [suscríbete a webhooks](https://platform.claude.com/docs/es/managed-agents/webhooks) para recibir una notificación cuando una sesión se pause en espera de una entrada.
```bash cURL
# Permite que la herramienta se ejecute
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"
}
]
}'
# O deniégala con una explicación
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."
}
]
}'
```
```bash CLI
# Permite que la herramienta se ejecute
ant beta:sessions:events send \
--session-id "$SESSION_ID" \
--event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"
# O deniégala con una explicación
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.}"
```
```python Python
# Permite que la herramienta se ejecute
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.tool_confirmation",
"tool_use_id": agent_tool_use_event.id,
"result": "allow",
},
],
)
# O deniégala con una explicación
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.",
},
],
)
```
```typescript TypeScript
// Permite que la herramienta se ejecute
await client.beta.sessions.events.send(session.id, {
events: [
{
type: "user.tool_confirmation",
tool_use_id: agent_tool_use_event.id,
result: "allow"
}
]
});
// O deniégala con una explicación
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."
}
]
});
```
```csharp C#
// Permite que la herramienta se ejecute
await client.Beta.Sessions.Events.Send(session.ID, new()
{
Events =
[
new BetaManagedAgentsUserToolConfirmationEventParams
{
Type = BetaManagedAgentsUserToolConfirmationEventParamsType.UserToolConfirmation,
ToolUseID = agentToolUseEvent.ID,
Result = "allow",
},
],
});
// O deniégala con una explicación
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.",
},
],
});
```
```go Go
// Permite que la herramienta se ejecute
_, 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)
}
// O deniégala con una explicación
_, 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)
}
```
```java Java
// Permite que la herramienta se ejecute
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()
);
// O deniégala con una explicación
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()
);
```
```php PHP
use Anthropic\Beta\Sessions\Events\ManagedAgentsUserToolConfirmationEventParams;
// Permite que la herramienta se ejecute
$client->beta->sessions->events->send(
$session->id,
events: [
ManagedAgentsUserToolConfirmationEventParams::with(
type: 'user.tool_confirmation',
toolUseID: $agentToolUseEvent->id,
result: 'allow',
),
],
);
// O deniégala con una explicación
$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.",
),
],
);
```
```ruby Ruby
# Permite que la herramienta se ejecute
client.beta.sessions.events.send_(
session.id,
events: [
{
type: "user.tool_confirmation",
tool_use_id: agent_tool_use_event.id,
result: "allow"
}
]
)
# O deniégala con una explicación
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."
}
]
)
```
## Herramientas personalizadas
Las políticas de permisos no se aplican a las herramientas personalizadas. Cuando el agente invoca una herramienta personalizada, tu aplicación recibe un evento `agent.custom_tool_use` y es responsable de decidir si ejecutarla antes de devolver un `user.custom_tool_result`. Consulta [Flujo de eventos de la sesión](https://platform.claude.com/docs/es/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session) para ver el flujo completo.
## Próximos pasos
Adjunta a tu agente conocimientos especializados reutilizables basados en el sistema de archivos para flujos de trabajo específicos de un dominio.
Envía eventos, recibe respuestas en streaming e interrumpe o redirige tu sesión en plena ejecución.