--- title: Managed Agents 배포 보안 강화하기 url: https://platform.claude.com/docs/ko/managed-agents/secure-deployment description: 에이전트가 접근하고 수행할 수 있는 범위를 제한하는 설정을 중요도 순으로 안내합니다. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 이 가이드는 Claude Managed Agents의 에이전트가 접근하고 수행할 수 있는 범위를 제한하는 설정을 중요도 순으로 나열합니다. 각 섹션은 해당 설정을 자세히 다루는 페이지로 연결됩니다. | 섹션 | 설정 또는 결정 사항 | 권장 사항 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | [에이전트 실행 위치 선택하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#choose-where-the-agent-runs) | 클라우드 또는 자체 호스팅 샌드박스 | 직접 제어하는 인프라에서 도구를 실행해야 하는 경우가 아니라면 클라우드 | | [네트워크 제한하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#limit-the-network) | 환경의 `networking.type` | 에이전트에 필요한 호스트만 포함한 `limited` | | [자격 증명을 볼트에 보관하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#keep-credentials-in-vaults) | 각 환경 변수 자격 증명의 `injection_location` 및 `networking` | 요청 헤더만 사용하고, 해당 키가 사용될 호스트만 포함한 `limited` 네트워킹 | | [웹 검색 및 웹 가져오기 제한하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#restrict-web-search-and-web-fetch) | 각 웹 도구의 `allowed_domains` | 각 도구에 허용 목록 설정. `web_fetch`에는 에이전트에 필요한 사이트만 나열. `web_search`에는 결과를 받고자 하는 사이트를 나열 | | [위험한 작업 승인하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#approve-risky-actions) | 각 도구의 `permission_policy` | `bash`, `write`, `edit`, `web_fetch` 및 데이터를 읽기만 하는 MCP 도구에는 `auto`. 샌드박스 외부에 가한 변경 사항을 되돌릴 수 없는 도구이거나, 전달된 최종 사용자 텍스트만으로 실행되어서는 안 되는 도구에는 대신 `always_ask` | | [에이전트에 최소한의 도구 세트 제공하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#give-the-agent-the-smallest-tool-set) | 에이전트 도구 세트의 `default_config.enabled` | `false`로 설정한 후 에이전트에 필요한 도구만 활성화 | | [신뢰할 수 없는 입력을 강력한 도구로부터 분리하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#keep-untrusted-input-away-from-powerful-tools) | 신뢰할 수 없는 입력을 읽을 때 에이전트가 보유하는 도구와 자격 증명 | 신뢰할 수 없는 입력을 읽는 에이전트는 파일을 쓰거나, 명령을 실행하거나, 레코드를 변경하는 도구를 `always_allow`로 보유하지 않음 | | [한도와 중지 방법 설정하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#set-limits-and-a-way-to-stop) | 각 세션 및 배포의 `budget` | 한 번의 실행에 예상되는 비용에 맞춘 상한 | | [선택 사항: 오프라인 검토자가 모든 트랜스크립트를 읽도록 하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment-monitoring#optionally-have-an-offline-reviewer-read-every-transcript) | 각 세션의 이벤트를 읽는, 직접 실행하는 오프라인 검토 작업 | 선택 사항. 유휴 상태가 되었거나 종료된 각 세션을 일정에 따라 검토 | | [세션 모니터링 및 보존 검토](https://platform.claude.com/docs/ko/managed-agents/secure-deployment-monitoring#monitor-sessions-and-review-retention) | 웹훅 및 세션 삭제 | 세션이 유휴 상태가 되거나, 예산에 도달하거나, 종료될 때 알림을 받고, 유휴 상태가 된 이유를 확인. 보관하려는 이벤트는 자체 로그에 저장하고, 더 이상 필요하지 않은 세션은 삭제 | [보안 위험과 샌드박스 경계](https://platform.claude.com/docs/ko/managed-agents/secure-deployment-risks)에서는 이러한 설정이 중요한 이유와 이 설정들이 보호하지 못하는 부분을 설명합니다. 세션을 검토하고 모니터링하려면 [에이전트 세션 검토 및 모니터링](https://platform.claude.com/docs/ko/managed-agents/secure-deployment-monitoring)을 참조하세요. ## 에이전트 실행 위치 선택하기 에이전트의 도구가 실행되는 위치에 따라 샌드박스를 보호하는 주체가 결정됩니다. 클라우드 환경에서는 Anthropic이, 자체 호스팅 샌드박스에서는 사용자가 보호합니다. 둘 중 하나를 선택하고 각각의 경우 어떤 정보가 Anthropic에 전달되는지 알아보려면 [에이전트 환경 선택하기](https://platform.claude.com/docs/ko/managed-agents/choosing-an-environment)를 참조하세요. [자체 호스팅 샌드박스](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes)를 사용하는 경우 다음 네 가지 사항에 유의하세요. * **네트워크:** [네트워크 제한하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#limit-the-network)는 클라우드 환경에 적용됩니다. 자체 호스팅 샌드박스의 경우 자체 방화벽에서 해당 트래픽에 동등한 제한을 설정하세요. 방화벽은 에이전트가 선언한 MCP 서버를 제한하지 않으므로, 해당 서버와 애플리케이션이 세션에 설정하는 서버를 검토하세요. * **웹 도구:** 웹 도구는 Anthropic의 서버에서 실행되므로 방화벽으로 제한되지 않습니다. 도메인 목록으로 제한하세요. [웹 검색 및 웹 가져오기 제한하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#restrict-web-search-and-web-fetch)를 참조하세요. * **자격 증명:** 환경 변수 자격 증명은 아직 자체 호스팅 샌드박스에서 지원되지 않습니다. * **격리 및 보안 강화:** 둘 다 사용자의 책임입니다. [보안 모델](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-security)을 참조하세요. 어느 옵션을 선택하든 Managed Agents의 규정 준수 범위나 세션 기록 보관 기간은 달라지지 않습니다. [세션 모니터링 및 보존 검토](https://platform.claude.com/docs/ko/managed-agents/secure-deployment-monitoring#monitor-sessions-and-review-retention)를 참조하세요. ## 네트워크 제한하기 `networking.type`을 `limited`로 설정하고 `allowed_hosts`에 에이전트에 필요한 호스트만 나열하세요. `networking`을 생략한 환경 생성 요청은 `unrestricted`가 될 수 있으므로, 모든 생성 요청에 `networking`을 설정하세요. [제한 없는 네트워킹의 위험](https://platform.claude.com/docs/ko/managed-agents/environments#risks-of-unrestricted-networking)을 참조하세요. 연결한 파일, 메모리 스토어, GitHub 리포지토리는 `allowed_hosts`와 관계없이 에이전트가 계속 사용할 수 있습니다. 이 페이지의 예시는 지원 에이전트를 사용합니다. 이 에이전트는 고객의 티켓을 읽고, 주문을 조회하고, 헬프 센터를 읽은 다음 답변 초안을 작성합니다. 주문 조회는 애플리케이션이 실행하며 호스트가 필요하지 않으므로, 이 환경은 `web_fetch`를 위해 헬프 센터라는 하나의 호스트만 허용합니다. ```bash cURL curl -fsS https://api.anthropic.com/v1/environments \ -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": "support-agent", "config": { "type": "cloud", "networking": { "type": "limited", "allowed_hosts": ["help.example.com"] } } }' ``` ```bash CLI ant apply environment.yaml ``` ```yaml # yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: support-agent config: type: cloud networking: type: limited allowed_hosts: - help.example.com ``` ```python Python environment = client.beta.environments.create( name="support-agent", config={ "type": "cloud", "networking": { "type": "limited", "allowed_hosts": ["help.example.com"], }, }, ) ``` ```typescript TypeScript const environment = await client.beta.environments.create({ name: "support-agent", config: { type: "cloud", networking: { type: "limited", allowed_hosts: ["help.example.com"] } } }); ``` ```csharp C# using Anthropic.Models.Beta.Environments; var environment = await client.Beta.Environments.Create(new() { Name = "support-agent", Config = new BetaCloudConfigParams { Networking = new BetaLimitedNetworkParams { AllowedHosts = ["help.example.com"], }, }, }); ``` ```go Go environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{ Name: "support-agent", Config: anthropic.BetaEnvironmentNewParamsConfigUnion{ OfCloud: &anthropic.BetaCloudConfigParams{ Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{ OfLimited: &anthropic.BetaLimitedNetworkParams{ AllowedHosts: []string{"help.example.com"}, }, }, }, }, }) if err != nil { panic(err) } _ = environment ``` ```java Java import com.anthropic.models.beta.environments.*; import java.util.List; var environment = client.beta().environments().create(EnvironmentCreateParams.builder() .name("support-agent") .config(BetaCloudConfigParams.builder() .networking(BetaLimitedNetworkParams.builder() .allowedHosts(List.of("help.example.com")) .build()) .build()) .build()); ``` ```php PHP $environment = $client->beta->environments->create( name: 'support-agent', config: [ 'type' => 'cloud', 'networking' => [ 'type' => 'limited', 'allowed_hosts' => ['help.example.com'], ], ], ); ``` ```ruby Ruby environment = client.beta.environments.create( name: "support-agent", config: { type: "cloud", networking: { type: "limited", allowed_hosts: ["help.example.com"] } } ) ``` `limited` 환경에는 세 가지 네트워킹 설정이 있습니다. | 설정 | 샌드박스의 코드에 개방되는 대상 | 권장 사항 | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `allowed_hosts` | 나열한 호스트(모든 요청에 대해) | 운영하거나 신뢰하는 각 MCP 서버의 호스트를 포함하여 에이전트에 필요한 호스트만 | | `allow_package_managers` | [패키지 관리자 호스트](https://platform.claude.com/docs/ko/managed-agents/environments#package-manager-hosts). 여기에는 누구나 콘텐츠를 게시할 수 있고 샌드박스의 코드가 파일을 업로드할 수 있는 `github.com`, `gitlab.com`, `bitbucket.org`의 모든 리포지토리와 경로가 포함됩니다 | 환경의 `packages` 설정에 패키지가 나열되어 `true`가 필요한 경우가 아니라면 `false`. 에이전트가 실행 중에 패키지를 설치하는 경우, 대신 필요한 레지스트리 호스트만 `allowed_hosts`에 나열 | | `allow_mcp_servers` | 호스트 없음. Managed Agents는 Anthropic의 서버에서 MCP 서버에 연결합니다 | `false`로 설정하고, 운영하거나 신뢰하는 각 MCP 서버의 호스트를 `allowed_hosts`에 나열 | `allow_package_managers` 및 `allow_mcp_servers` 설정은 웹 검색 및 웹 가져오기에 대한 호스트를 추가하지 않습니다. `allow_mcp_servers`는 기본값인 꺼진 상태로 두고, 운영하거나 신뢰하는 각 MCP 서버의 호스트를 `allowed_hosts`에 나열하세요. 나열한 각 호스트는 샌드박스의 코드에도 개방됩니다. `allow_mcp_servers`가 꺼져 있으면, 세션 생성 시 검사에서 MCP 서버의 호스트가 나열되지 않은 경우 요청을 거부합니다. [세션 생성 시 인증 제공하기](https://platform.claude.com/docs/ko/managed-agents/mcp-connector#provide-authentication-at-session-creation)를 참조하세요. 세션 업데이트로 `mcp_servers`가 변경될 때도 동일한 검사가 실행됩니다. 네트워크 접근은 작업 단위가 아니라 호스트 단위로 부여됩니다. 샌드박스는 허용된 호스트에 `git push`나 패키지 게시와 같은 업로드를 포함한 모든 요청을 보낼 수 있습니다. 또한 명령이 제공하는 모든 자격 증명을 사용할 수 있으며, 누군가 에이전트가 읽는 텍스트에 숨겨 둔 자격 증명도 마찬가지입니다. `allowed_hosts`에 사용할 호스트를 선택할 때는 다음 두 가지 규칙을 따르세요. * 운영하거나 신뢰하는 호스트만 나열하세요. * `*.` 와일드카드와 누구나 콘텐츠를 게시할 수 있는 공유 호스팅 도메인은 피하세요. 에이전트가 `bash`를 유지하는 경우, [위험한 작업 승인하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#approve-risky-actions)에서 설명하는 대로 `bash` 도구의 [권한 정책](https://platform.claude.com/docs/ko/managed-agents/permission-policies)을 설정하세요. 환경을 강화한 후에는 새 세션을 시작하고 이미 실행 중이던 세션은 중지하세요. 이미 실행 중인 세션은 종료될 때까지 이전 제한을 유지할 수 있습니다. [한도와 중지 방법 설정하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#set-limits-and-a-way-to-stop)를 참조하세요. 모든 네트워킹 설정은 [클라우드 환경 설정](https://platform.claude.com/docs/ko/managed-agents/environments#networking)을 참조하세요. ## 자격 증명을 볼트에 보관하기 모든 시크릿을 볼트에 저장하세요. 각 환경 변수 자격 증명에 대해 주입 위치를 요청 헤더로만 설정하고, 해당 시크릿이 사용될 호스트만 나열하세요. 샌드박스의 코드는 시크릿 대신 플레이스홀더를 보게 됩니다. Managed Agents는 자격 증명이 허용하는 호스트로 나가는 HTTPS 요청에서만 실제 시크릿으로 교체합니다. 따라서 요청 헤더를 그대로 반환하는 엔드포인트처럼 서비스가 시크릿을 되돌려 보내지 않는 한, 시크릿은 모델이 직접 접근할 수 없는 곳에 유지됩니다. 자격 증명의 `networking`이 `unrestricted`인 경우, Managed Agents는 환경이 샌드박스에 접근을 허용하는 모든 호스트로의 요청에서 실제 시크릿으로 교체합니다. 볼트를 사용하려면 세션이나 배포를 생성할 때 `vault_ids`에 해당 ID를 전달하세요. | 설정 | 설정값 | 이유 | 하지 않는 일 | | --------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | `injection_location` | 서비스가 헤더에서 키를 읽는지 확인한 후 `{"header": true, "body": false}` | 요청 본문은 에이전트가 읽는 콘텐츠로 구성되는 경우가 많으므로, 본문에 있는 키는 더 많이 노출됩니다. 두 필드를 모두 명시하세요. 객체를 생략한 생성 요청은 두 위치를 모두 활성화하며, 업데이트는 전송한 필드만 변경합니다 | 코드는 여전히 자격 증명이 허용하는 모든 호스트에서 키를 사용할 수 있습니다. 본문에서 키를 기대하는 서비스는 플레이스홀더를 받게 되어 요청을 거부합니다 | | 자격 증명의 `networking` | 키가 사용될 정확한 호스트를 포함한 `limited` | 응답은 가려지지 않은 상태로 샌드박스에 도달하므로, 와일드카드, 공유 호스팅 도메인, 요청 헤더를 그대로 반환하는 호스트는 피하세요 | 호스트를 개방하지 않습니다. 환경에서도 해당 호스트를 허용해야 합니다 | | 키를 발급한 서비스에서의 키 권한 | 에이전트에 필요한 권한만 | 에이전트는 키가 허용하는 모든 작업을 수행할 수 있습니다 | 해당 없음 | | 마운트된 리포지토리의 GitHub 토큰 | 최소 권한을 가진 [세분화된 토큰](https://platform.claude.com/docs/ko/managed-agents/github#token-permissions) | 샌드박스의 코드는 세션 전체 동안 이 토큰으로 마운트된 리포지토리에서 가져오기와 푸시를 할 수 있습니다. 에이전트가 푸시해야 하는 경우에만 쓰기 권한을 부여하세요 | 해당 없음 | 지원 에이전트는 애플리케이션이 주문 API의 API 키를 보유하므로 볼트 자격 증명이 필요하지 않습니다. 에이전트가 볼트 자격 증명을 보유하는 경우, 모든 언어로 된 요청은 [자격 증명 추가하기](https://platform.claude.com/docs/ko/managed-agents/vaults#add-a-credential)를 참조하세요. 키를 시스템 프롬프트, 에이전트 정의, 메시지에 넣지 마세요. 에이전트에 Claude API 키를 제공하지 마세요. Claude API 키가 볼트에 있더라도 샌드박스의 코드는 이를 사용하여 Claude API를 직접 호출할 수 있습니다. 세션 시작이나 삭제, 웹 검색 및 웹 가져오기 사용 등 해당 키가 허용하는 모든 작업을 수행할 수 있습니다. 에이전트의 도구 설정, 승인, 예산은 이러한 호출에 적용되지 않습니다. `limited` 환경에서는 `allowed_hosts`가 샌드박스의 `api.anthropic.com` 접근을 허용하는 경우에만 코드가 이러한 호출을 할 수 있습니다. 토큰은 직접 가져와서 볼트에 저장하세요. 샌드박스의 코드가 저장된 시크릿으로 가져온 토큰은 가려지지 않은 상태로 반환되기 때문입니다. 워크스페이스에 접근할 수 있는 모든 API 키는 해당 워크스페이스의 볼트를 참조할 수 있으므로, 신뢰 수준이 다른 워크로드의 볼트는 별도의 [워크스페이스](https://platform.claude.com/docs/ko/manage-claude/workspaces)에 보관하세요. 하나의 워크스페이스로 범위가 지정된 API 키를 사용하세요. MCP 자격 증명 및 교체에 대해서는 [볼트로 인증하기](https://platform.claude.com/docs/ko/managed-agents/vaults)를 참조하세요. ## 웹 검색 및 웹 가져오기 제한하기 `web_fetch`의 `allowed_domains`를 에이전트에 필요한 사이트로 설정하세요. 에이전트가 가져오는 모든 URL은 해당 URL이 가리키는 사이트로 데이터를 전달할 수 있으므로, 이 목록은 보안 통제 수단입니다. `web_search`에서는 `allowed_domains`를 결과를 받고자 하는 사이트로 설정하여, 정확하다고 신뢰하는 사이트에서만 결과가 나오도록 하세요. 이 목록은 검색 쿼리가 검색 제공자에게 전달되는 것을 막지 않습니다. 검색 결과에는 페이지의 텍스트가 포함되므로, 이 목록은 어떤 사이트의 텍스트가 에이전트에 도달하는지도 제한합니다. 모든 유형의 환경에서 두 도구 모두에 `allowed_domains`를 설정하세요. `blocked_domains` 목록은 나열한 호스트와 그 하위 도메인만 차단하며, 다른 호스트는 차단하지 않습니다. 동일한 콘텐츠가 웹 아카이브, 캐시, 미러 또는 나열하지 않은 관련 도메인을 통해 여전히 에이전트에 도달할 수 있습니다. 보안을 위해 `blocked_domains`에 의존하지 마세요. `allowed_domains`를 사용하고 신뢰하는 호스트를 명시하세요. `limited` 환경에서는 [네트워크 제한하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#limit-the-network)의 `allowed_hosts` 목록도 웹 도구를 제한합니다. `unrestricted` 환경이나 자체 호스팅 샌드박스는 웹 도구를 제한하지 않습니다. | `limited` 환경에서 | 결과 | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | 활성화된 웹 도구의 `allowed_domains` 항목이 `allowed_hosts` 밖에 있음 | 세션 생성이 400 오류로 실패하며, 그러한 항목을 추가하는 세션 업데이트도 마찬가지입니다. 배포가 일정에 따라 또는 수동 실행으로 시작하는 세션은 그대로 생성됩니다. 이 경우 도구는 `allowed_hosts` 밖의 호스트에서 아무것도 반환하지 않습니다 | | 웹 도구에 자체 목록이 없음 | 도구는 `allowed_hosts`에 있는 호스트의 페이지와 결과만 반환합니다. 도구에도 `allowed_domains`를 설정하세요 | | `allowed_hosts`에 항목이 없음 | 두 웹 도구 모두 페이지나 검색 결과를 반환하지 않습니다 | | 웹 도구를 위해 `allowed_hosts`에 호스트를 추가함 | 해당 호스트는 샌드박스의 코드에도 개방됩니다 | 두 목록은 호스트를 서로 다르게 매칭합니다. | 목록 | 항목 | 매칭됨 | 매칭되지 않음 | | ------------------------ | --------------- | ------------------------- | ----------------- | | `allowed_hosts` (환경) | `example.com` | `example.com` | `www.example.com` | | `allowed_hosts` (환경) | `*.example.com` | 모든 하위 도메인 | `example.com` | | `allowed_domains` (웹 도구) | `example.com` | `example.com` 및 모든 하위 도메인 | 다른 도메인 | 에이전트에 사이트와 그 모든 하위 도메인이 필요한 경우 `allowed_hosts`에 `example.com`과 `*.example.com`을 모두 나열하고, 그렇지 않으면 정확한 호스트를 나열하세요. 도구가 `example.com`을 나열하고 `allowed_hosts`가 `*.example.com`만 나열하는 경우 세션은 생성됩니다. 세션 생성 시 검사는 `example.com`을 `*.example.com`에 포함된 것으로 간주하지만, 도구는 `example.com` 자체에서는 아무것도 반환하지 않습니다. 두 목록의 매칭 방식은 [에이전트에 도메인 목록 설정](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions#set-domain-lists-on-an-agent)을 참조하세요. `web_fetch` 도구는 또한 세션에 이미 나타난 URL만 엽니다. | URL이 나타나는 위치 | `web_fetch`가 열 수 있는지 여부 | | ----------------------------------------------------- | ---------------------------------- | | 전달하는 최종 사용자 텍스트를 포함한 사용자 메시지의 텍스트 | 예 | | `user.define_outcome` 이벤트의 설명 | 예 | | 웹 검색 결과의 주소 | 예 | | 이전에 `web_fetch`가 반환한 페이지(PDF 제외)의 텍스트 중 전체 URL이 표시된 곳 | 예 | | Claude가 도구를 직접 호출한 경우 커스텀 도구 결과의 텍스트 | 예, 결과가 `is_error: true`로 표시된 경우 제외 | | 시스템 프롬프트 | 아니요 | | `allowed_domains` 항목을 포함한 에이전트 구성 | 아니요 | | Claude 자체의 출력 | 아니요 | | `bash` 및 기타 샌드박스 도구의 출력 | 아니요 | | MCP 도구 결과 | 아니요 | | 사용자 메시지에 첨부된 파일 | 아니요 | 멀티에이전트 세션에서 `web_fetch`는 다른 에이전트로부터 받은 URL이 "예"로 표시된 출처를 통해 해당 에이전트에 도달한 경우에만 엽니다. 직접 호출한 커스텀 도구의 결과는 "예"로 표시된 출처로 간주됩니다. 이는 도구가 입력을 그대로 반복하는 경우처럼 Claude가 그 텍스트를 작성한 경우에도 마찬가지입니다. URL은 `example.com/docs`처럼 `https://` 없이 작성된 경우에도 인정될 수 있습니다. `web_fetch` 도구는 "Contact support."처럼 URL 대신 단어를 표시하는 링크를 항상 열 수 있는 것은 아닙니다. 에이전트가 세션에 나타나지 않은 URL을 가져와야 하는 경우, 사용자 메시지로 보내세요. 이 규칙은 주입된 텍스트가 비공개 데이터를 전달하는 URL을 구성할 가능성을 줄여 줍니다. 최종 사용자 텍스트, 검색 결과, 가져온 페이지, 커스텀 도구 결과는 여전히 URL을 추가할 수 있으므로 `allowed_domains`를 계속 설정해 두세요. Messages API는 다른 출처 목록으로 유사한 규칙을 적용합니다. [URL 검증](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/web-fetch-tool#url-validation)을 참조하세요. `web_fetch`의 도메인 목록은 `bash` 도구를 제한하지 않습니다. [네트워크도 제한하세요](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#limit-the-network). [도메인 목록 규칙](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions#domain-list-rules)을 참조하세요. ## 위험한 작업 승인하기 `bash`, `write`, `edit`, `web_fetch` 및 데이터를 읽기만 하는 MCP 도구에는 `auto`를 설정하세요. 샌드박스 외부에 가한 변경 사항을 되돌릴 수 없는 도구에는 대신 `always_ask`를 사용하세요. 전달하는 최종 사용자 텍스트가 요청한다는 이유만으로 실행되어서는 안 되는 도구에도 이를 사용하세요. [권한 정책](https://platform.claude.com/docs/ko/managed-agents/permission-policies)은 도구 호출이 실행될지, 승인을 기다릴지, 서버가 평가할지를 결정합니다. | 도구 | 권장 정책 | 이유 | | ----------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | `read`, `glob`, `grep` | `always_allow` | 샌드박스의 파일을 읽기만 하고 아무것도 변경하지 않습니다 | | `bash`, `write`, `edit` | `auto`. 샌드박스 외부에 가한 변경 사항을 되돌릴 수 없는 도구에는 `always_ask`를 사용하세요. 최종 사용자 텍스트를 전달하는 경우 `bash`에 `always_ask`를 사용하세요 | 에이전트 도구 세트의 기본값은 `always_allow`이며, 모든 호출을 승인 없이 실행합니다 | | `web_fetch` | `auto` | 에이전트가 가져오는 URL은 해당 URL이 가리키는 사이트로 데이터를 전달할 수 있습니다 | | `web_search` | 검색 쿼리로 전송되기를 원하지 않는 데이터를 에이전트가 다루는 경우 `always_ask`. 그렇지 않으면 `always_allow` | `allowed_domains`는 결과가 나오는 사이트를 제한할 뿐, 쿼리에 포함되는 내용은 제한하지 않습니다 | | 데이터를 읽기만 하는 MCP 도구 | 도구 세트의 `configs`에서 각 도구별로 설정한 `auto` | 도구 세트 기본값은 `always_ask`로 유지되므로, MCP 서버가 나중에 추가하는 도구는 여전히 승인을 기다립니다 | | 데이터를 변경하는 MCP 도구 | `always_ask` | 이것이 MCP 도구 세트의 기본값입니다. 그대로 유지하세요 | | 커스텀 도구 | 각 호출의 실행 여부는 사용자의 코드가 결정합니다 | 권한 정책이 적용되지 않습니다 | [에이전트에 최소한의 도구 세트 제공하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#give-the-agent-the-smallest-tool-set)의 도구 세트가 이러한 정책을 적용합니다. [`auto` 정책](https://platform.claude.com/docs/ko/managed-agents/permission-policies#let-the-server-evaluate-each-call-with-auto)은 서버가 호출을 실행하거나, 거부하거나, 승인을 위해 일시 중지하도록 합니다. 긴 실행에서 사람이 모든 호출을 승인할 수는 없으므로, 대신 서버가 각 호출을 검사합니다. `auto`는 제한된 네트워킹, 좁은 권한을 가진 키, 예산, 유휴 세션에 대한 알림과 함께 사용하세요. `auto`는 사람의 검토 지점이 아니므로, 도구의 호출이 실행되기 전에 사람이 검토해야 한다면 해당 도구에 `always_ask`를 구성하세요. `auto`는 `user.message` 이벤트의 텍스트와 `user.define_outcome` 이벤트의 설명을, 전달하는 최종 사용자 텍스트를 포함하여 사용자의 지시로 취급합니다. 일시 중지된 세션은 무기한 대기하므로, 무인 세션에는 일시 중지된 호출에 응답하거나 세션을 중단하는 클라이언트가 필요합니다. 일시 중지된 각 호출을 허용하기 전에 검토하세요. 사람에게 보여 주지 않고 모든 호출을 허용하는 클라이언트는 `always_allow`와 같습니다. [확인 요청에 응답하기](https://platform.claude.com/docs/ko/managed-agents/permission-policies#respond-to-confirmation-requests) 및 [각 호출이 어떻게 평가되었는지 확인하기](https://platform.claude.com/docs/ko/managed-agents/permission-policies#see-how-each-call-was-evaluated)를 참조하세요. ## 에이전트에 최소한의 도구 세트 제공하기 `default_config.enabled`를 `false`로 설정하고 [에이전트에 필요한 도구만 활성화하세요](https://platform.claude.com/docs/ko/managed-agents/tools#enabling-only-specific-tools). 에이전트 도구 세트는 기본적으로 8개의 내장 도구를 모두 활성화합니다. | 도구 | 기능 | | ------------------------- | --------------------------------------- | | `bash` | 허용된 호스트로의 요청을 포함하여 모든 명령을 실행합니다 | | `write`, `edit` | 샌드박스의 파일을 변경합니다 | | `read`, `glob`, `grep` | 샌드박스의 파일을 읽습니다 | | `web_fetch`, `web_search` | Anthropic의 서버를 통해 웹에서 페이지와 검색 결과를 반환합니다 | 지원 에이전트에는 세 가지 내장 도구가 필요합니다. 초안 작성을 위한 `read`와 `write`, 그리고 헬프 센터를 위한 `web_fetch`입니다. 주문 조회는 애플리케이션이 실행하는 [커스텀 도구](https://platform.claude.com/docs/ko/managed-agents/tools#custom-tools)인 `lookup_order`를 통해 수행합니다. 애플리케이션이 주문 API의 API 키를 보유하므로, 에이전트에는 `bash`도 자격 증명도 필요하지 않습니다. 다음 샘플은 `allowed_domains`로 `web_fetch`를 `help.example.com`으로 제한합니다. [위험한 작업 승인하기](https://platform.claude.com/docs/ko/managed-agents/secure-deployment#approve-risky-actions)에서 권장하는 대로 `write`와 `web_fetch`에 `auto`를 설정합니다. 고객의 티켓으로 인해 에이전트가 이러한 도구를 사용하더라도, 에이전트는 샌드박스의 파일을 변경하거나 헬프 센터 페이지를 여는 것만 할 수 있습니다. 그래서 두 도구 모두 `always_ask`가 필요하지 않습니다. 샘플은 또한 `default_config`에 `always_ask`를 설정하므로, 나중에 자체 정책 없이 활성화하는 도구는 `always_ask`를 사용합니다. ```bash cURL tools='[ { "type": "agent_toolset_20260401", "default_config": { "enabled": false, "permission_policy": {"type": "always_ask"} }, "configs": [ {"name": "read", "enabled": true, "permission_policy": {"type": "always_allow"}}, {"name": "write", "enabled": true, "permission_policy": {"type": "auto"}}, { "name": "web_fetch", "enabled": true, "allowed_domains": ["help.example.com"], "permission_policy": {"type": "auto"} } ] }, { "type": "custom", "name": "lookup_order", "description": "Look up one order by its ID. Returns the status, the items, and the delivery date.", "input_schema": { "type": "object", "properties": { "order_id": {"type": "string", "description": "The order ID from the ticket"} }, "required": ["order_id"] } } ]' ``` ```bash CLI ant apply agent.md ``` ```markdown --- name: Support Agent model: claude-opus-5-5 tools: - type: agent_toolset_20260401 default_config: enabled: false permission_policy: type: always_ask configs: - name: read enabled: true permission_policy: type: always_allow - name: write enabled: true permission_policy: type: auto - name: web_fetch enabled: true allowed_domains: [help.example.com] permission_policy: type: auto - type: custom name: lookup_order description: Look up one order by its ID. Returns the status, the items, and the delivery date. input_schema: type: object properties: order_id: type: string description: The order ID from the ticket required: - order_id --- ``` ```python Python tools = [ { "type": "agent_toolset_20260401", "default_config": { "enabled": False, "permission_policy": {"type": "always_ask"}, }, "configs": [ { "name": "read", "enabled": True, "permission_policy": {"type": "always_allow"}, }, { "name": "write", "enabled": True, "permission_policy": {"type": "auto"}, }, { "name": "web_fetch", "enabled": True, "allowed_domains": ["help.example.com"], "permission_policy": {"type": "auto"}, }, ], }, { "type": "custom", "name": "lookup_order", "description": "Look up one order by its ID. Returns the status, the items, and the delivery date.", "input_schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order ID from the ticket", }, }, "required": ["order_id"], }, }, ] ``` ```typescript TypeScript const tools = [ { type: "agent_toolset_20260401", default_config: { enabled: false, permission_policy: { type: "always_ask" } }, configs: [ { name: "read", enabled: true, permission_policy: { type: "always_allow" } }, { name: "write", enabled: true, permission_policy: { type: "auto" } }, { name: "web_fetch", enabled: true, allowed_domains: ["help.example.com"], permission_policy: { type: "auto" } } ] }, { type: "custom", name: "lookup_order", description: "Look up one order by its ID. Returns the status, the items, and the delivery date.", input_schema: { type: "object", properties: { order_id: { type: "string", description: "The order ID from the ticket" } }, required: ["order_id"] } } ] satisfies Anthropic.Beta.AgentCreateParams["tools"]; ``` ```csharp C# using System.Text.Json; using Anthropic.Models.Beta.Agents; using Tool = Anthropic.Models.Beta.Agents.Tool; Tool[] tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401, DefaultConfig = new() { Enabled = false, PermissionPolicy = new BetaManagedAgentsAlwaysAskPolicy { Type = "always_ask" }, }, Configs = [ new BetaManagedAgentsReadToolConfigParams { Enabled = true, PermissionPolicy = new BetaManagedAgentsAlwaysAllowPolicy { Type = "always_allow" }, }, new BetaManagedAgentsWriteToolConfigParams { Enabled = true, PermissionPolicy = new BetaManagedAgentsAutoPolicy(), }, new BetaManagedAgentsWebFetchToolConfigParams { Enabled = true, AllowedDomains = ["help.example.com"], PermissionPolicy = new BetaManagedAgentsAutoPolicy(), }, ], }, new BetaManagedAgentsCustomToolParams { Type = "custom", Name = "lookup_order", Description = "Look up one order by its ID. Returns the status, the items, and the delivery date.", InputSchema = new() { Properties = new Dictionary { ["order_id"] = JsonSerializer.SerializeToElement( new { type = "string", description = "The order ID from the ticket" } ), }, Required = ["order_id"], }, }, ]; ``` ```go Go tools := []anthropic.BetaAgentNewParamsToolUnion{{ OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, DefaultConfig: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParams{ Enabled: anthropic.Bool(false), PermissionPolicy: anthropic.BetaManagedAgentsAgentToolsetDefaultConfigParamsPermissionPolicyUnion{ OfAlwaysAsk: &anthropic.BetaManagedAgentsAlwaysAskPolicyParam{ Type: anthropic.BetaManagedAgentsAlwaysAskPolicyTypeAlwaysAsk, }, }, }, Configs: []anthropic.BetaManagedAgentsAgentToolConfigParamsUnion{ {OfRead: &anthropic.BetaManagedAgentsReadToolConfigParams{ Enabled: anthropic.Bool(true), PermissionPolicy: anthropic.BetaManagedAgentsReadToolConfigParamsPermissionPolicyUnion{ OfAlwaysAllow: &anthropic.BetaManagedAgentsAlwaysAllowPolicyParam{ Type: anthropic.BetaManagedAgentsAlwaysAllowPolicyTypeAlwaysAllow, }, }, }}, {OfWrite: &anthropic.BetaManagedAgentsWriteToolConfigParams{ Enabled: anthropic.Bool(true), PermissionPolicy: anthropic.BetaManagedAgentsWriteToolConfigParamsPermissionPolicyUnion{ OfAuto: &anthropic.BetaManagedAgentsAutoPolicyParam{}, }, }}, {OfWebFetch: &anthropic.BetaManagedAgentsWebFetchToolConfigParams{ AllowedDomains: []string{"help.example.com"}, Enabled: anthropic.Bool(true), PermissionPolicy: anthropic.BetaManagedAgentsWebFetchToolConfigParamsPermissionPolicyUnion{ OfAuto: &anthropic.BetaManagedAgentsAutoPolicyParam{}, }, }}, }, }, }, { OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{ Type: anthropic.BetaManagedAgentsCustomToolParamsTypeCustom, Name: "lookup_order", Description: "Look up one order by its ID. Returns the status, the items, and the delivery date.", InputSchema: anthropic.BetaManagedAgentsCustomToolInputSchemaParam{ Properties: map[string]any{ "order_id": map[string]any{ "type": "string", "description": "The order ID from the ticket", }, }, Required: []string{"order_id"}, }, }, }} _ = tools ``` ```java Java import com.anthropic.core.JsonValue; import com.anthropic.models.beta.agents.*; import java.util.List; import java.util.Map; var tools = List.of( AgentCreateParams.Tool.ofAgentToolset20260401( BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .defaultConfig( BetaManagedAgentsAgentToolsetDefaultConfigParams.builder() .enabled(false) .permissionPolicy( BetaManagedAgentsAlwaysAskPolicy.builder() .type(BetaManagedAgentsAlwaysAskPolicy.Type.ALWAYS_ASK) .build() ) .build() ) .addConfig( BetaManagedAgentsReadToolConfigParams.builder() .enabled(true) .permissionPolicy( BetaManagedAgentsAlwaysAllowPolicy.builder() .type(BetaManagedAgentsAlwaysAllowPolicy.Type.ALWAYS_ALLOW) .build() ) .build() ) .addConfig( BetaManagedAgentsWriteToolConfigParams.builder() .enabled(true) .permissionPolicy(BetaManagedAgentsAutoPolicy.builder().build()) .build() ) .addConfig( BetaManagedAgentsWebFetchToolConfigParams.builder() .enabled(true) .allowedDomains(List.of("help.example.com")) .permissionPolicy(BetaManagedAgentsAutoPolicy.builder().build()) .build() ) .build() ), AgentCreateParams.Tool.ofCustom( BetaManagedAgentsCustomToolParams.builder() .type(BetaManagedAgentsCustomToolParams.Type.CUSTOM) .name("lookup_order") .description("Look up one order by its ID. Returns the status, the items, and the delivery date.") .inputSchema( BetaManagedAgentsCustomToolInputSchema.builder() .properties( BetaManagedAgentsCustomToolInputSchema.Properties.builder() .putAdditionalProperty("order_id", JsonValue.from(Map.of( "type", "string", "description", "The order ID from the ticket"))) .build() ) .addRequired("order_id") .build() ) .build() ) ); ``` ```php PHP use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolsetDefaultConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAllowPolicy; use Anthropic\Beta\Agents\BetaManagedAgentsAlwaysAskPolicy; use Anthropic\Beta\Agents\BetaManagedAgentsAutoPolicy; use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolInputSchema; use Anthropic\Beta\Agents\BetaManagedAgentsCustomToolParams; use Anthropic\Beta\Agents\BetaManagedAgentsReadToolConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsWebFetchToolConfigParams; use Anthropic\Beta\Agents\BetaManagedAgentsWriteToolConfigParams; $tools = [ BetaManagedAgentsAgentToolset20260401Params::with( type: 'agent_toolset_20260401', defaultConfig: BetaManagedAgentsAgentToolsetDefaultConfigParams::with( enabled: false, permissionPolicy: BetaManagedAgentsAlwaysAskPolicy::with(type: 'always_ask'), ), configs: [ BetaManagedAgentsReadToolConfigParams::with( enabled: true, permissionPolicy: BetaManagedAgentsAlwaysAllowPolicy::with(type: 'always_allow'), ), BetaManagedAgentsWriteToolConfigParams::with( enabled: true, permissionPolicy: BetaManagedAgentsAutoPolicy::with(), ), BetaManagedAgentsWebFetchToolConfigParams::with( allowedDomains: ['help.example.com'], enabled: true, permissionPolicy: BetaManagedAgentsAutoPolicy::with(), ), ], ), BetaManagedAgentsCustomToolParams::with( type: 'custom', name: 'lookup_order', description: 'Look up one order by its ID. Returns the status, the items, and the delivery date.', inputSchema: BetaManagedAgentsCustomToolInputSchema::with( properties: ['order_id' => ['type' => 'string', 'description' => 'The order ID from the ticket']], required: ['order_id'], ), ), ]; ``` ```ruby Ruby tools = [ { type: "agent_toolset_20260401", default_config: { enabled: false, permission_policy: {type: "always_ask"} }, configs: [ { name: "read", enabled: true, permission_policy: {type: "always_allow"} }, { name: "write", enabled: true, permission_policy: {type: "auto"} }, { name: "web_fetch", enabled: true, allowed_domains: ["help.example.com"], permission_policy: {type: "auto"} } ] }, { type: "custom", name: "lookup_order", description: "Look up one order by its ID. Returns the status, the items, and the delivery date.", input_schema: { type: "object", properties: {order_id: {type: "string", description: "The order ID from the ticket"}}, required: ["order_id"] } } ] ``` [에이전트 업데이트](https://platform.claude.com/docs/ko/managed-agents/agent-setup#update-semantics)는 `tools` 배열 전체를 교체하므로, 유지하려는 모든 항목을 보내세요. 에이전트 업데이트는 새 세션에만 적용되므로, 배포, 이 에이전트를 나열하는 에이전트, 기존 세션도 확인하세요. * 배포는 에이전트 버전을 고정하므로, 각 배포가 새 버전을 가리키도록 하세요. * [`subagents.predefined_agents`](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#list-the-subagents) 또는 `workflows.predefined_agents`에 이 에이전트를 나열하는 에이전트는 고정한 버전을 유지하므로, 해당 에이전트도 업데이트하세요. * 이미 존재하는 세션을 강화하려면 [해당 세션의 도구를 업데이트하세요](https://platform.claude.com/docs/ko/managed-agents/session-operations#updating-the-agent-configuration). 세션은 `idle` 상태여야 하며, 업데이트는 `tools` 배열 전체를 교체합니다. 멀티에이전트 세션에서는 세션이 실행하는 에이전트의 웹 도구에 대한 새 `allowed_domains` 및 `blocked_domains` 목록이 다른 모든 에이전트에도 적용됩니다. 이는 각 에이전트의 다음 턴부터 적용됩니다. 해당 에이전트들의 활성화된 도구와 권한 정책은 변경되지 않습니다. 이를 변경하려면 각 에이전트를 업데이트한 다음 새 세션을 시작하세요. MCP 서버와 커스텀 도구도 에이전트에 필요한 것으로 제한하세요. * **MCP 서버:** MCP 도구 세트는 기본적으로 서버가 노출하는 모든 도구를 활성화합니다. `default_config.enabled`를 `false`로 설정하고 이름을 지정한 도구를 활성화하여, 서버가 나중에 추가하는 도구가 꺼진 상태로 유지되도록 하세요. 에이전트가 사용하지 않는 서버는 제거하세요. [MCP 커넥터](https://platform.claude.com/docs/ko/managed-agents/mcp-connector#configure-which-mcp-tools-are-available)를 참조하세요. * **커스텀 도구:** 애플리케이션이 실행하며, 권한 정책이 적용되지 않습니다. 애플리케이션에서 각 호출의 입력을 검증하고 도구가 접근할 수 있는 범위를 제한하세요. ## 신뢰할 수 없는 입력을 강력한 도구로부터 분리하기 에이전트가 신뢰할 수 없는 입력, 즉 팀 외부의 누군가가 작성할 수 있는 텍스트를 읽을 때마다 에이전트가 보유한 도구와 자격 증명을 확인하세요. 이 섹션에서는 두 가지 용어를 사용합니다. * **신뢰할 수 없는 입력:** 웹 페이지, 검색 결과, 지원 티켓, 이메일, 리포지토리 파일, 업로드, MCP 서버 결과, 전달하는 최종 사용자 메시지. * **강력한 도구:** `bash`, `write`, `edit`, `web_fetch`, `web_search`, 데이터를 쓰거나 전송하는 MCP 도구 및 커스텀 도구, 그리고 자격 증명을 사용하는 모든 도구. 신뢰할 수 없는 입력의 텍스트는 에이전트에게 보유한 강력한 도구를 사용하도록 지시할 수 있습니다. 지원 에이전트는 티켓을 읽으므로, 커스텀 도구 `lookup_order`를 통해서만 주문 API에 접근합니다. 애플리케이션은 주문이 티켓 발신자의 것인지 확인합니다. | 에이전트가 읽는 입력 | 함께 보유한 권한 | 조치 | | ------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 티켓, 이메일 또는 업로드 | 자격 증명이 있는 `bash` | `bash`를 한 가지 작업만 하는 커스텀 도구로 교체하세요. 에이전트가 `bash`를 유지해야 하는 경우 `always_ask`로 각 호출을 승인하세요 | | 웹 페이지 또는 검색 결과 | 파일 쓰기 또는 레코드 변경 | 웹 도구를 끄거나, 운영하거나 신뢰하는 사이트로 제한하세요 | | MCP 결과 또는 리포지토리 파일 | 쓰기를 수행하는 MCP 도구 | MCP 도구 세트를 `always_ask`로 유지하고, 에이전트에 필요한 도구만 활성화하세요 | | 마운트된 GitHub 리포지토리 | 모든 도구 | 신뢰하는 리포지토리만 마운트하세요. `read`를 가진 에이전트는 검토 단계 없이 리포지토리의 `.claude/skills` 디렉터리에서 스킬을 에이전트 지침으로 로드합니다. [GitHub 리포지토리에서 스킬 로드하기](https://platform.claude.com/docs/ko/managed-agents/skills#load-skills-from-a-github-repository)를 참조하세요 | | 모든 신뢰할 수 없는 입력 | [메모리 스토어](https://platform.claude.com/docs/ko/managed-agents/memory#attach-a-memory-store-to-a-session)에 쓰기 | 에이전트가 써야 하는 경우가 아니라면 스토어를 `read_only`로 연결하세요. 기본값은 `read_write`이며, 이후 세션은 저장된 텍스트를 신뢰할 수 있는 메모리로 읽습니다 | 클라우드 환경에서는 `read`로 파일을 읽을 때 `CLAUDE.md` 및 `AGENTS.md` 파일도 지침으로 로드될 수 있습니다. 이 파일들은 해당 파일의 디렉터리와 그 상위 디렉터리에서 샌드박스의 작업 디렉터리까지 로드됩니다. `@docs/setup.md`처럼 `@`와 경로로 참조하는 파일도 최대 5단계 깊이까지 로드됩니다. 참조는 `@/etc/hosts`처럼 샌드박스의 어느 곳이든 가리킬 수 있습니다. `read`를 비활성화하는 것 외에는 이를 끄는 설정이 없으므로, 팀 외부의 누군가가 작성할 수 있는 리포지토리, 패키지 또는 아카이브는 신뢰할 수 없는 입력으로 취급하세요. 에이전트가 신뢰할 수 없는 입력을 읽으면서 동시에 작업도 수행해야 하는 경우, 이 가이드는 세 가지 설계 중 하나를 권장합니다. * **읽기와 작업 수행을 분리하세요.** 하나의 멀티에이전트 세션에서 [리드 에이전트](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#list-the-subagents)가 웹을 읽는 페처(fetcher)와 파일이나 레코드를 변경하는 라이터(writer)에게 작업을 할당합니다. * **에이전트에 좁은 범위의 커스텀 도구 하나를 제공하세요.** 애플리케이션이 도구를 실행하고, 입력을 검사하며, 자격 증명을 보유합니다. 지원 에이전트는 분리 방식이 아닌 이 설계를 사용합니다. [세션을 일시 중지시키는 도구 호출에 응답하기](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session)를 참조하세요. * **사람이 개입하도록 하세요.** 강력한 도구에 `always_ask`를 사용하여 사람이 각 호출을 승인하도록 하세요. 분리 방식은 세 개의 에이전트를 사용합니다. | 에이전트 | 읽는 것 | 보유하는 것 | 전달하는 것 | | ----------------- | --------------------------- | ----------------------------------------------------------------- | ------------------------ | | 리드(세션이 실행하는 에이전트) | 사용자의 메시지와 다른 에이전트가 돌려보내는 내용 | 내장 도구 없음. `subagents.predefined_agents` 목록에 페처와 라이터를 지정 | 각 에이전트에 대한 작업 | | 페처 | 웹 페이지 및 검색 결과 | 각각 `allowed_domains`가 설정된 `web_fetch`와 `web_search`만 | 시스템 프롬프트에서 요청한 형식의 짧은 결과 | | 라이터 | 리드로부터 받은 작업 | 파일을 쓰거나, 명령을 실행하거나, 레코드를 변경하는 도구(`auto` 또는 `always_ask`). 웹 도구 없음 | 작업 결과 | 페처의 결과는 신뢰할 수 없는 페이지로부터 구성되며, 리드는 그 텍스트를 라이터에게 전달할 수 있습니다. 라이터의 도구는 `auto` 또는 `always_ask`로 유지하세요. 페처는 여전히 읽은 내용의 일부를 `web_fetch` 목록에 있는 사이트로, 그리고 쿼리를 통해 검색 제공자에게 보낼 수 있습니다. 하나의 멀티에이전트 세션에 있는 에이전트들은 [샌드박스](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration#how-it-works), 그 파일, 볼트 자격 증명을 공유하므로, 이 분리는 도구와 대화만 분리합니다. 더 강력한 분리를 위해서는 별도의 환경과 볼트를 가진 두 개의 세션을 사용하세요. 애플리케이션이 두 세션 간에 주문 ID와 같은 고정된 필드만 전달하도록 하세요. ## 한도와 중지 방법 설정하기 각 세션을 생성할 때 예산을 설정하고, 에이전트를 중지하는 방법을 미리 정해 두세요. | 통제 수단 | 기능 | | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 세션 예산 | 공개 정가 기준의 지출 상한입니다. 상한에 도달하면 세션과 각 [스레드](https://platform.claude.com/docs/ko/managed-agents/session-threads)가 일시 중지됩니다. 진행 중인 요청은 완료될 수 있고 해당 도구 호출도 계속 실행되므로, 지출이 상한을 초과할 수 있습니다. [세션이 예산에 도달할 때](https://platform.claude.com/docs/ko/managed-agents/budgets#when-a-session-reaches-its-budget)를 참조하세요 | | 배포 예산 | 배포가 시작하는 각 세션에 적용되는 동일한 상한입니다 | | [`user.interrupt` 이벤트](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#interrupt-the-agent) | 모델 응답을 즉시 중지합니다. 실행 중인 도구 호출은 먼저 완료될 수 있습니다. 워크플로 실행이 세션을 `running` 상태로 유지하지 않는 한 세션은 `idle` 상태가 되며, 다음 메시지를 보내면 재개됩니다. 중단은 워크플로 실행을 종료하지 않습니다 | | 세션 보관 또는 삭제 | 보관하면 기록이 유지되고 새 이벤트가 차단됩니다. 삭제하면 레코드, 이벤트, 샌드박스가 제거됩니다 | | 배포 일시 중지 또는 보관 | 일시 중지하면 새로운 예약 실행은 중지되지만 수동 실행은 여전히 허용됩니다. 보관하면 일정이 영구적으로 종료됩니다. 이미 실행 중인 세션은 계속 실행됩니다 | | 볼트 또는 자격 증명 보관 또는 삭제 | 재시작 없이 실행 중인 세션에서 시크릿을 제거합니다. 지연 시간을 고려하세요. 세션은 계속 실행되므로 세션도 중단하세요. 에이전트가 시크릿으로 이미 가져온 토큰은 샌드박스에 남아 있습니다 | 실행 중인 에이전트를 중지하려면 다음 단계를 따르세요. 1. `user.interrupt`만 단독으로 보내세요. 2. 예약된 에이전트의 경우, 새로운 예약 실행이 시작되지 않도록 배포도 일시 중지하세요. 일정을 영구적으로 종료하려면 배포를 보관하세요. 3. 키가 노출되었을 가능성이 있다면, 키를 발급한 서비스에서 교체하세요. 4. 에이전트에 열려 있는 워크플로 실행이 있다면, 중단은 실행을 종료하지 않으므로 실행을 중지하도록 요청하는 `user.message`도 보내세요. 먼저 취소해야 할 도구 호출은 [실행이 열려 있는 세션 중단하기](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)를 참조하세요. 5. 세션이 `idle` 상태가 될 때까지 기다리세요. 실행 중인 세션은 보관하거나 삭제할 수 없습니다. 6. 기록을 유지하려면 세션을 보관하세요. 기록이 더 이상 필요하지 않으면 삭제하세요. 중단은 에이전트가 이미 수행했거나 보낸 것을 되돌리지 않습니다. 에이전트를 보관해도 실행 중인 세션은 중지되지 않습니다. 예산의 `max_list_cost.amount`는 문자열로 작성된 미국 센트 단위의 정수이므로, `"125"`는 $1.25를 의미합니다. [세션 생성 시 예산 설정](https://platform.claude.com/docs/ko/managed-agents/budgets#set-a-budget-at-session-creation)을 참조하세요. 예산 없이 생성된 세션에는 예산을 추가할 수 없습니다. 상한을 변경하거나 제거하려면 [예산에 도달한 세션 재개](https://platform.claude.com/docs/ko/managed-agents/budgets#resume-a-session-at-its-budget)를 참조하세요. 세션의 상한을 제거한 후에는 새 상한을 설정할 수 없습니다. 예산은 지출을 제한하지만, 상한에 도달하기 전에 에이전트가 수행하는 작업은 제한하지 않습니다. 신뢰 수준이 다른 워크로드를 분리하려면 별도의 [워크스페이스](https://platform.claude.com/docs/ko/manage-claude/workspaces)를 사용하세요. 여러 워크스페이스에 접근할 수 있는 키는 그중 어느 곳에서든 작업할 수 있으므로, 각 워크로드에 하나의 워크스페이스로 범위가 지정된 API 키를 제공하세요. [세션 예산](https://platform.claude.com/docs/ko/managed-agents/budgets), [세션 작업](https://platform.claude.com/docs/ko/managed-agents/session-operations#archiving-a-session), [예약된 배포](https://platform.claude.com/docs/ko/managed-agents/scheduled-deployments#managing-deployment-lifecycle)를 참조하세요. ## 다음 단계 네트워킹 모드, 허용된 호스트, 패키지 관리자. 승인 정책 및 확인 요청. 자격 증명 유형, 주입 위치, 교체. 상한, 예산 도달 시 재개, 배포의 예산.