Berechtigungsrichtlinien steuern, ob serverseitig ausgeführte Tools (das vorgefertigte Agenten-Toolset und das MCP-Toolset) automatisch ausgeführt werden oder auf Ihre Genehmigung warten. Benutzerdefinierte Tools werden von Ihrer Anwendung ausgeführt und von Ihnen kontrolliert, daher unterliegen sie nicht den Berechtigungsrichtlinien.
Alle Managed Agents API-Anfragen erfordern den managed-agents-2026-04-01 Beta-Header. Das SDK setzt den Beta-Header automatisch.
| Richtlinie | Verhalten |
|---|---|
always_allow | Das Tool wird automatisch ohne Bestätigung ausgeführt. |
always_ask | Die Sitzung gibt ein session.status_idle-Ereignis aus und wartet auf ein user.tool_confirmation-Ereignis, bevor es ausgeführt wird. |
Beim Erstellen eines Agenten können Sie optional eine Richtlinie auf jedes Tool in agent_toolset_20260401 über anwenden:
Was this page helpful?
default_config.permission_policyagent=$(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 ist eine optionale Einstellung. Wenn Sie sie weglassen, wird das Agenten-Toolset mit der Standard-Berechtigungsrichtlinie always_allow aktiviert.
MCP-Toolsets verwenden standardmäßig always_ask. Dadurch wird sichergestellt, dass neue Tools, die einem MCP-Server hinzugefügt werden, nicht ohne Genehmigung in Ihrer Anwendung ausgeführt werden. Um Tools von einem vertrauenswürdigen MCP-Server automatisch zu genehmigen, setzen Sie permission_policy im mcp_toolset-Eintrag.
Der mcp_server_name muss mit dem name übereinstimmen, der im mcp_servers-Array referenziert wird.
Dieses Beispiel verbindet einen GitHub-MCP-Server und erlaubt dessen Tools, ohne Bestätigung zu laufen:
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"}
}
}
]
}')Verwenden Sie das configs-Array, um den Standard für einzelne Tools zu überschreiben. Dieses Beispiel erlaubt das vollständige Agenten-Toolset standardmäßig, erfordert jedoch eine Bestätigung, bevor ein Bash-Befehl ausgeführt wird:
tools='[
{
"type": "agent_toolset_20260401",
"default_config": {
"permission_policy": {"type": "always_allow"}
},
"configs": [
{
"name": "bash",
"permission_policy": {"type": "always_ask"}
}
]
}
]'Wenn der Agent ein Tool mit einer always_ask-Richtlinie aufruft:
agent.tool_use- oder agent.mcp_tool_use-Ereignis aus.session.status_idle-Ereignis, das stop_reason: requires_action enthält. Die blockierenden Ereignis-IDs befinden sich im stop_reason.requires_action.event_ids-Array.user.tool_confirmation-Ereignis und übergeben Sie die Ereignis-ID im tool_use_id-Parameter. Setzen Sie result auf "allow" oder "deny". Verwenden Sie deny_message, um eine Ablehnung zu erklären.running.Erfahren Sie mehr über die Ereignisverarbeitung im Leitfaden zum Sitzungs-Ereignisstrom.
# Das Tool zur Ausführung zulassen
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"
}
]
}'
# Oder ablehnen mit einer Erklärung
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."
}
]
}'Berechtigungsrichtlinien gelten nicht für benutzerdefinierte Tools. Wenn der Agent ein benutzerdefiniertes Tool aufruft, empfängt Ihre Anwendung ein agent.custom_tool_use-Ereignis und ist dafür verantwortlich zu entscheiden, ob es ausgeführt werden soll, bevor ein user.custom_tool_result zurückgesendet wird. Siehe Sitzungs-Ereignisstrom für den vollständigen Ablauf.