---
title: 예약된 배포
url: https://platform.claude.com/docs/ko/managed-agents/scheduled-deployments
description: "Claude API로 배포를 생성하고 관리하세요: 반복되는 cron 일정에 따라 에이전트를 실행하고 실행 기록을 확인합니다."
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

**Scheduled deployment**(예약된 배포)를 사용하면 [에이전트](https://platform.claude.com/docs/ko/managed-agents/agent-setup)가 [세션](https://platform.claude.com/docs/ko/managed-agents/sessions)을 자율적으로 시작할 수 있어, 예측 가능한 주기에 따라 작업을 완료할 수 있습니다. 배포는 Claude API의 일부인 Deployments API로 생성하고 관리합니다.

출시 배경과 팀들이 일정에 따라 실행하는 작업의 예시는 블로그의 [Claude Managed Agents의 예약된 배포 및 vault](https://claude.com/blog/whats-new-in-claude-managed-agents)를 참조하세요.

## 예약된 배포 생성하기

배포를 생성할 때는 `schedule` (csharp, go: `Schedule`)과 함께 실행에 필요한 [세션 구성](https://platform.claude.com/docs/ko/managed-agents/sessions)을 전달합니다.

* 배포에는 [에이전트 구성](https://platform.claude.com/docs/ko/managed-agents/agent-setup)과 [환경 구성](https://platform.claude.com/docs/ko/managed-agents/environments)이 필요하며, 선택적으로 [파일](https://platform.claude.com/docs/ko/managed-agents/files), [GitHub](https://platform.claude.com/docs/ko/managed-agents/github), [메모리 저장소](https://platform.claude.com/docs/ko/managed-agents/memory), [vault](https://platform.claude.com/docs/ko/managed-agents/vaults)를 받을 수 있습니다. [자체 호스팅 환경](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory)을 대상으로 하는 배포는 메모리 저장소를 연결할 수 있으며, `file` 및 `github_repository` 리소스에는 클라우드 환경이 필요합니다. Claude Console 배포 양식은 현재 자체 호스팅 환경에 대한 메모리 저장소를 제공하지 않으므로, 대신 API 또는 SDK를 통해 연결하세요.
* 배포에는 각 세션의 작업을 시작하는 초기 이벤트(`user.message` 또는 `user.define_outcome`)가 최소 하나 이상 필요합니다. `ant apply`용 배포 파일에서는 frontmatter 아래의 텍스트가 해당 `user.message`가 됩니다.
* `schedule` (csharp, go: `Schedule`)에서 cron `expression` (csharp, go: `Expression`)과 `timezone` (csharp, go: `Timezone`)을 정의합니다. 지원되는 최대 세분성은 분 단위입니다.

<Note>
  [Claude Platform on AWS](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws)에서는 각 실행이 사용자의 AWS 계정에 있는 IAM 역할로 세션을 생성합니다. 배포를 생성하기 전에 에이전트의 `execution_identity`를 `{"type": "aws_role", "role_arn": "arn:aws:iam::123456789012:role/example-role"}`로 설정하세요. 이 필드가 없는 에이전트에 대해 배포를 생성하면 400 오류가 반환됩니다.

  * **신뢰 정책:** `aws-external-anthropic.amazonaws.com` 서비스 주체가 `sts:AssumeRole` 및 `sts:SetSourceIdentity`를 호출할 수 있도록 허용하세요.
  * **역할 권한:** `aws-external-anthropic:CreateSession`, `sts:GetWebIdentityToken`, `sts:TagGetWebIdentityToken`을 허용하세요.
  * **호출자 권한:** 에이전트에 역할을 설정하는 IAM 주체에는 해당 역할에 대한 `iam:PassRole`이 필요합니다. 역할은 동일한 AWS 계정에 있어야 합니다. 어떤 [관리형 정책](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#managed-policies)도 `iam:PassRole`을 부여하지 않습니다.
</Note>

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployments?beta=true" \
    -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": "Weekly compliance scan",
      "agent": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "initial_events": [
        {"type": "user.message", "content": [{"type": "text", "text": "Run the weekly compliance scan."}]}
      ],
      "schedule": {
        "type": "cron",
        "expression": "0 20 * * 5",
        "timezone": "America/New_York"
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply deployment.md
    ```

    <File filename="deployment.md">
      ```markdown
      ---
      name: Weekly compliance scan
      agent: agent_011CYm1BLqPXpQRk5khsSXrs
      environment_id: env_01595EKxaaTTGwwY3kyXdtbs
      schedule:
        type: cron
        expression: "0 20 * * 5"
        timezone: America/New_York
      ---

      Run the weekly compliance scan.
      ```
    </File>

    [`ant apply`](https://platform.claude.com/docs/ko/cli-sdks-libraries/cli/apply)는 새 배포의 ID를 출력하고 이를 `claude-lock.json`에 기록합니다. 배포 객체를 확인하려면 `ant beta:deployments retrieve`를 실행하세요.
  </CodeGroupItem>

  ```python Python
  deployment = client.beta.deployments.create(
      name="Weekly compliance scan",
      agent=agent.id,
      environment_id=environment.id,
      initial_events=[
          {
              "type": "user.message",
              "content": [{"type": "text", "text": "Run the weekly compliance scan."}],
          },
      ],
      schedule={
          "type": "cron",
          "expression": "0 20 * * 5",
          "timezone": "America/New_York",
      },
  )
  ```

  ```typescript TypeScript
  const deployment = await client.beta.deployments.create({
    name: "Weekly compliance scan",
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "Run the weekly compliance scan." }]
      }
    ],
    schedule: {
      type: "cron",
      expression: "0 20 * * 5",
      timezone: "America/New_York"
    }
  });
  ```

  ```csharp C#
  var deployment = await client.Beta.Deployments.Create(new()
  {
      Name = "Weekly compliance scan",
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      InitialEvents =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "Run the weekly compliance scan.",
                  },
              ],
          },
      ],
      Schedule = new BetaManagedAgentsScheduleParams
      {
          Type = BetaManagedAgentsScheduleParamsType.Cron,
          Expression = "0 20 * * 5",
          Timezone = "America/New_York",
      },
  });
  ```

  ```go Go
  deployment, err := client.Beta.Deployments.New(ctx, anthropic.BetaDeploymentNewParams{
  	Name:          "Weekly compliance scan",
  	Agent:         anthropic.BetaDeploymentNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
  	EnvironmentID: environment.ID,
  	InitialEvents: []anthropic.BetaManagedAgentsDeploymentInitialEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "Run the weekly compliance scan.",
  				},
  			}},
  		},
  	}},
  	Schedule: anthropic.BetaManagedAgentsScheduleParams{
  		Type:       anthropic.BetaManagedAgentsScheduleParamsTypeCron,
  		Expression: "0 20 * * 5",
  		Timezone:   "America/New_York",
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var deployment = client.beta().deployments().create(
      DeploymentCreateParams.builder()
          .name("Weekly compliance scan")
          .agent(agent.id())
          .environmentId(environment.id())
          .addInitialEvent(
              BetaManagedAgentsUserMessageEventParams.builder()
                  .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                  .addTextContent("Run the weekly compliance scan.")
                  .build()
          )
          .schedule(
              BetaManagedAgentsScheduleParams.builder()
                  .type(BetaManagedAgentsScheduleParams.Type.CRON)
                  .expression("0 20 * * 5")
                  .timezone("America/New_York")
                  .build()
          )
          .build()
  );
  ```

  ```php PHP
  $deployment = $client->beta->deployments->create(
      name: 'Weekly compliance scan',
      agent: $agent->id,
      environmentID: $environment->id,
      initialEvents: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'Run the weekly compliance scan.']],
          ],
      ],
      schedule: [
          'type' => 'cron',
          'expression' => '0 20 * * 5',
          'timezone' => 'America/New_York',
      ],
  );
  ```

  ```ruby Ruby
  deployment = client.beta.deployments.create(
    name: "Weekly compliance scan",
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: "user.message",
        content: [{type: "text", text: "Run the weekly compliance scan."}]
      }
    ],
    schedule: {
      type: "cron",
      expression: "0 20 * * 5",
      timezone: "America/New_York"
    }
  )
  ```
</CodeGroup>

응답에는 다음 예정된 실행 시각이 채워진 `schedule.upcoming_runs_at`을 포함하는 배포 객체가 들어 있어, 일정이 올바르게 설정되었는지 확인할 수 있습니다.

```json
{
  "id": "depl_01xyz",
  "status": "active",
  "paused_reason": null,
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York",
    "last_run_at": null,
    "upcoming_runs_at": [
      "2026-05-09T00:00:00Z",
      "2026-05-16T00:00:00Z",
      "2026-05-23T00:00:00Z"
    ]
  }
}
```

예정된 실행 타임스탬프는 구성된 일정을 정확히 반영합니다. 그러나 부하를 분산하기 위해 실제 실행에는 실행 간격의 최대 15%에 해당하는 "jitter"(지터)가 적용되며, 최소 5초에서 최대 9분입니다.

조직당 최대 **1,000개의 예약된 배포**가 지원됩니다. 더 필요한 경우 Anthropic 지원팀에 문의하세요.

전체 매개변수와 응답 스키마는 [Create Deployment 레퍼런스](https://platform.claude.com/docs/ko/api/beta/deployments/create)를 참조하세요.

### Cron 및 시간대 의미 체계

* **Expression:** 표준 POSIX cron(`minute hour day-of-month month day-of-week`)입니다. [Claude Console](https://platform.claude.com/workspaces/default/deployments)에서 이러한 cron 표현식을 생성하고 검증할 수 있습니다.
* **Timezone:** IANA 시간대 식별자입니다(예: `"America/Los_Angeles"`).
* **DST:** Cron 일정은 문자 그대로의 벽시계 시간 일치를 사용하므로, `America/New_York`의 `"0 20 * * *"`는 EST 또는 EDT 적용 여부와 관계없이 현지 시간 오후 8시에 실행됩니다.

<Note>
  서머타임이 시작되는 날(시계를 앞당기는 날)에 존재하지 않는 벽시계 시간(예: 오전 2시)은 트리거되지 않습니다. 서머타임이 끝나는 날(시계를 되돌리는 날)에 두 번 발생하는 벽시계 시간은 두 번 실행됩니다. 실행 누락이나 중복 실행이 허용되지 않는 경우에는 현지 시간 오전 1\~3시 구간을 피해 일정을 잡거나 UTC를 사용하세요.
</Note>

### 각 실행에 예산 설정하기

배포를 생성하거나 업데이트할 때 선택적 `budget` (csharp, go: `Budget`) 객체를 전달하세요. 이 객체는 [세션 예산](https://platform.claude.com/docs/ko/managed-agents/budgets)과 동일한 형태를 가집니다. 배포는 시작하는 각 세션에 상한을 복사하므로, 예산은 여러 실행에 걸친 누적 상한으로 작동하는 것이 아니라 각 실행을 개별적으로 제한합니다. 즉, `"2000"` 상한이 설정된 배포는 실행마다 약 $20까지 지출할 수 있습니다.

배포가 시작한 세션은 예산이 설정된 다른 세션과 정확히 동일하게 동작합니다. 자체 정가 비용이 [상한에 도달하면](https://platform.claude.com/docs/ko/managed-agents/budgets#when-a-session-reaches-its-budget) `budget_reached`와 함께 일시 중지됩니다. 배포의 예산을 변경하면 이후에 시작되는 실행에 적용되며, 이미 실행 중인 세션은 시작 시의 상한을 유지합니다. 이 상한은 [세션 자체를 통해 변경](https://platform.claude.com/docs/ko/managed-agents/session-operations#updating-the-session-budget)할 수 있습니다. 세션 예산과 달리, 배포의 예산은 `"budget": null` (python: `budget=None`; typescript: `budget: null`; ruby: `budget: nil`; go: `Budget: param.NullStruct[anthropic.BetaManagedAgentsBudgetLimitParam]()`; java: `.budget(Optional.empty())`; csharp: `Budget = null`; php: `requestOptions: ['extraBodyParams' => ['budget' => null]]`; cli: `--budget null`)로 제거했다가 나중에 다시 설정할 수 있습니다.

다음 예시는 기존 배포에 예산을 설정합니다:

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID?beta=true" \
    -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 '{
      "budget": {
        "type": "limit",
        "max_list_cost": {"amount": "2000", "currency": "USD"}
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply deployment.md
    ```

    <File filename="deployment.md">
      ```markdown
      ---
      name: Weekly compliance scan
      agent: agent_011CYm1BLqPXpQRk5khsSXrs
      environment_id: env_01595EKxaaTTGwwY3kyXdtbs
      schedule:
        type: cron
        expression: "0 20 * * 5"
        timezone: America/New_York
      budget:
        type: limit
        max_list_cost:
          amount: "2000"
          currency: USD
      ---

      Run the weekly compliance scan.
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  updated_deployment = client.beta.deployments.update(
      deployment.id,
      budget={
          "type": "limit",
          "max_list_cost": {"amount": "2000", "currency": "USD"},
      },
  )
  print(updated_deployment.budget.max_list_cost.amount)  # 2000
  ```

  ```typescript TypeScript
  const updatedDeployment = await client.beta.deployments.update(deployment.id, {
    budget: {
      type: "limit",
      max_list_cost: { amount: "2000", currency: "USD" }
    }
  });
  console.log(updatedDeployment.budget?.max_list_cost.amount); // 2000
  ```

  ```csharp C#
  var updatedDeployment = await client.Beta.Deployments.Update(deployment.ID, new()
  {
      Budget = new()
      {
          Type = BetaManagedAgentsBudgetLimitType.Limit,
          MaxListCost = new() { Amount = "2000", Currency = BetaCurrency.Usd },
      },
  });
  Console.WriteLine(updatedDeployment.Budget?.MaxListCost.Amount);  // 2000
  ```

  ```go Go
  updatedDeployment, err := client.Beta.Deployments.Update(ctx, deployment.ID, anthropic.BetaDeploymentUpdateParams{
  	Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
  		Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
  		MaxListCost: anthropic.BetaMonetaryAmountParam{
  			Amount:   "2000",
  			Currency: anthropic.BetaCurrencyUsd,
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(updatedDeployment.Budget.MaxListCost.Amount) // 2000
  ```

  ```java Java
  var updatedDeployment = client.beta().deployments().update(
      deployment.id(),
      DeploymentUpdateParams.builder()
          .budget(BetaManagedAgentsBudgetLimit.builder()
              .type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
              .maxListCost(BetaMonetaryAmount.builder()
                  .amount("2000")
                  .currency(BetaCurrency.USD)
                  .build())
              .build())
          .build()
  );
  IO.println(updatedDeployment.budget().orElseThrow().maxListCost().amount());  // 2000
  ```

  ```php PHP
  $updatedDeployment = $client->beta->deployments->update(
      $deployment->id,
      budget: [
          'type' => 'limit',
          'max_list_cost' => ['amount' => '2000', 'currency' => 'USD'],
      ],
  );
  echo "{$updatedDeployment->budget->maxListCost->amount}\n"; // 2000
  ```

  ```ruby Ruby
  updated_deployment = client.beta.deployments.update(
    deployment.id,
    budget: {
      type: "limit",
      max_list_cost: {amount: "2000", currency: "USD"}
    }
  )
  puts updated_deployment.budget.max_list_cost.amount # 2000
  ```
</CodeGroup>

## 배포 실행

배포는 다양한 이유로 트리거에 실패할 수 있습니다. 예를 들어 `environment` 리소스가 보관되었거나 세션 생성이 속도 제한에 걸린 경우입니다. 배포를 실행하려는 각 시도는 **deployment run**(배포 실행) 레코드를 생성하므로, 세션 수명 주기와 독립적으로 성공과 실패를 추적할 수 있습니다.

성공한 배포는 활성 세션을 생성하며, 성공한 배포 실행에는 연결된 `session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`)가 포함됩니다. 세션의 수명 주기를 따라가려면 [이벤트 스트림](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming) 또는 [webhook](https://platform.claude.com/docs/ko/managed-agents/webhooks)을 통해 세션 이벤트를 추적하세요. 배포 수명 주기 변경과 각 예약된 실행의 결과도 webhook 이벤트로 전달되며, 이는 [지원되는 이벤트 유형](https://platform.claude.com/docs/ko/managed-agents/webhooks#supported-event-types)의 Deployment events 및 Deployment run events 탭에 나열되어 있습니다.

다음과 같이 배포의 모든 배포 실행을 나열합니다:

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  for run in client.beta.deployment_runs.list(
      deployment_id=deployment.id,
  ):
      print(run.created_at, run.session_id or run.error.type)
  ```

  ```typescript TypeScript
  for await (const run of client.beta.deploymentRuns.list({
    deployment_id: deployment.id
  })) {
    console.log(run.created_at, run.session_id ?? run.error?.type);
  }
  ```

  ```csharp C#
  var runs = await client.Beta.DeploymentRuns.List(
      new() { DeploymentID = deployment.ID }
  );
  await foreach (var run in runs.Paginate())
  {
      // Error 유니온은 .Message를 직접 노출합니다. 공통 .Type 접근자가 추가될 때까지
      // 판별자는 .Json에서 읽습니다.
      var outcome = run.SessionID ?? run.Error!.Json.GetProperty("type").GetString();
      Console.WriteLine($"{run.CreatedAt} {outcome}");
  }
  ```

  ```go Go
  runs := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
  	DeploymentID: anthropic.String(deployment.ID),
  })
  for runs.Next() {
  	run := runs.Current()
  	if run.SessionID != "" {
  		fmt.Println(run.CreatedAt.Format(time.RFC3339), run.SessionID)
  	} else {
  		fmt.Println(run.CreatedAt.Format(time.RFC3339), run.Error.Type)
  	}
  }
  if err := runs.Err(); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  for (var run : client.beta().deploymentRuns().list(
          DeploymentRunListParams.builder()
              .deploymentId(deployment.id())
              .build()).autoPager()) {
      // Error 유니온은 아직 공통 .type()/.message() 접근자를 노출하지 않습니다.
      // .toString()은 둘 다 포함합니다.
      IO.println(run.createdAt() + " "
          + run.sessionId().orElseGet(() -> run.error().orElseThrow().toString()));
  }
  ```

  ```php PHP
  foreach ($client->beta->deploymentRuns->list(
      deploymentID: $deployment->id,
  )->pagingEachItem() as $run) {
      $outcome = $run->sessionID ?? $run->error->type;
      echo "{$run->createdAt->format(DATE_ATOM)} {$outcome}\n";
  }
  ```

  ```ruby Ruby
  client.beta.deployment_runs.list(
    deployment_id: deployment.id
  ).auto_paging_each do
    puts "#{it.created_at} #{it.session_id || it.error.type}"
  end
  ```
</CodeGroup>

추가로 오류가 있는 배포 실행만 필터링할 수 있습니다:

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID&has_error=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID" --has-error
  ```

  ```python Python
  for run in client.beta.deployment_runs.list(
      deployment_id=deployment.id,
      has_error=True,
  ):
      print(run.created_at, run.error.type, run.error.message)
  ```

  ```typescript TypeScript
  for await (const run of client.beta.deploymentRuns.list({
    deployment_id: deployment.id,
    has_error: true
  })) {
    console.log(run.created_at, run.error?.type, run.error?.message);
  }
  ```

  ```csharp C#
  var failedRuns = await client.Beta.DeploymentRuns.List(
      new() { DeploymentID = deployment.ID, HasError = true }
  );
  await foreach (var failedRun in failedRuns.Paginate())
  {
      var error = failedRun.Error!;
      var errorType = error.Json.GetProperty("type").GetString();
      Console.WriteLine($"{failedRun.CreatedAt} {errorType} {error.Message}");
  }
  ```

  ```go Go
  failedRuns := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
  	DeploymentID: anthropic.String(deployment.ID),
  	HasError:     anthropic.Bool(true),
  })
  for failedRuns.Next() {
  	failedRun := failedRuns.Current()
  	fmt.Println(failedRun.CreatedAt.Format(time.RFC3339), failedRun.Error.Type, failedRun.Error.Message)
  }
  if err := failedRuns.Err(); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  for (var run : client.beta().deploymentRuns().list(
          DeploymentRunListParams.builder()
              .deploymentId(deployment.id())
              .hasError(true)
              .build()).autoPager()) {
      IO.println(run.createdAt() + " " + run.error().orElseThrow());
  }
  ```

  ```php PHP
  foreach ($client->beta->deploymentRuns->list(
      deploymentID: $deployment->id,
      hasError: true,
  )->pagingEachItem() as $run) {
      echo "{$run->createdAt->format(DATE_ATOM)} {$run->error->type} {$run->error->message}\n";
  }
  ```

  ```ruby Ruby
  client.beta.deployment_runs.list(
    deployment_id: deployment.id,
    has_error: true
  ).auto_paging_each do
    puts "#{it.created_at} #{it.error.type} #{it.error.message}"
  end
  ```
</CodeGroup>

실패한 실행에는 세션 생성이 거부된 이유를 설명하는 `type`이 포함된 `error`가 들어 있습니다(예: `environment_archived_error`, `agent_archived_error`, `session_rate_limited_error`). 모든 필터 매개변수와 응답 스키마는 [List Deployment Runs 레퍼런스](https://platform.claude.com/docs/ko/api/beta/deployment_runs/list)를 참조하세요.

```json
{
  "type": "deployment_run",
  "id": "drun_01abc124",
  "deployment_id": "depl_01xyz",
  "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
  "session_id": null,
  "error": {
    "type": "environment_archived_error",
    "message": "environment `env_01abc` is archived"
  },
  "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
  "created_at": "2026-05-09T00:00:01Z"
}
```

ID로 단일 실행을 조회하려면 [`GET /v1/deployment_runs/{deployment_run_id}`](https://platform.claude.com/docs/ko/api/beta/deployment_runs/retrieve)를 호출하세요. [`deployment_run` webhook 이벤트](https://platform.claude.com/docs/ko/managed-agents/webhooks#supported-event-types)는 실행 ID를 `data.id`로 전달합니다.

## 배포 수명 주기 관리하기

각 수명 주기 변경은 [webhook 이벤트](https://platform.claude.com/docs/ko/managed-agents/webhooks#supported-event-types)를 발생시키므로, 폴링 없이 일시 중지, 일시 중지 해제 또는 보관된 배포에 대응할 수 있습니다. Deployment events 탭을 참조하세요.

**일시 중지(Pause)**&#xB294; 이후의 예약된 트리거를 억제합니다. 이전 배포 실행에서 시작되어 실행 중인 세션은 계속 실행됩니다. 일시 중지된 동안에도 `run` 엔드포인트를 통한 수동 실행은 여전히 허용됩니다. 일시 중지하면 `paused_reason`이 `{"type": "manual"}`로 설정되며, 일시 중지를 해제하면 이 값이 지워집니다.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/pause?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  client.beta.deployments.pause(deployment.id)
  ```

  ```typescript TypeScript
  await client.beta.deployments.pause(deployment.id);
  ```

  ```csharp C#
  await client.Beta.Deployments.Pause(deployment.ID);
  ```

  ```go Go
  if _, err := client.Beta.Deployments.Pause(ctx, deployment.ID, anthropic.BetaDeploymentPauseParams{}); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().deployments().pause(deployment.id());
  ```

  ```php PHP
  $client->beta->deployments->pause($deployment->id);
  ```

  ```ruby Ruby
  client.beta.deployments.pause(deployment.id)
  ```
</CodeGroup>

**일시 중지 해제(Unpause)**&#xB294; 다음 예약된 시점부터 일정을 재개합니다. 누락된 트리거는 소급 실행되지 않습니다.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/unpause?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments unpause --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  client.beta.deployments.unpause(deployment.id)
  ```

  ```typescript TypeScript
  await client.beta.deployments.unpause(deployment.id);
  ```

  ```csharp C#
  await client.Beta.Deployments.Unpause(deployment.ID);
  ```

  ```go Go
  if _, err := client.Beta.Deployments.Unpause(ctx, deployment.ID, anthropic.BetaDeploymentUnpauseParams{}); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().deployments().unpause(deployment.id());
  ```

  ```php PHP
  $client->beta->deployments->unpause($deployment->id);
  ```

  ```ruby Ruby
  client.beta.deployments.unpause(deployment.id)
  ```
</CodeGroup>

**보관(Archive)**&#xC740; **일시 중지**와 달리 최종적입니다. 일정이 종료되며 배포를 더 이상 수정할 수 없습니다.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/archive?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments archive --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  client.beta.deployments.archive(deployment.id)
  ```

  ```typescript TypeScript
  await client.beta.deployments.archive(deployment.id);
  ```

  ```csharp C#
  await client.Beta.Deployments.Archive(deployment.ID);
  ```

  ```go Go
  if _, err := client.Beta.Deployments.Archive(ctx, deployment.ID, anthropic.BetaDeploymentArchiveParams{}); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().deployments().archive(deployment.id());
  ```

  ```php PHP
  $client->beta->deployments->archive($deployment->id);
  ```

  ```ruby Ruby
  client.beta.deployments.archive(deployment.id)
  ```
</CodeGroup>

### 실패 시 동작

세션 생성 속도 제한 응답은 재시도 없이 즉시 `session_rate_limited_error` 실행으로 기록되며, 일정은 다음 예약된 시점에 다시 시도합니다. 세션 내의 기본 API 호출에 대한 속도 제한은 세션 자체에서 처리됩니다.

배포의 에이전트가 보관된 경우, 배포도 같은 작업에서 자동으로 보관됩니다. 에이전트가 삭제된 경우, 다음 예약된 트리거가 누락된 에이전트를 감지하고 배포를 자동으로 보관합니다. 두 경우 모두 배포 실행은 기록되지 않습니다. 에이전트가 참조하는 하위 에이전트가 보관된 경우, 다음 트리거는 `error.type: "agent_archived_error"`와 함께 실패한 실행을 기록하고 배포는 자동으로 일시 중지되므로, 에이전트를 업데이트한 후 재개할 수 있습니다. 보관된 환경이나 vault와 같은 기타 복구 불가능한 세션 생성 오류도 동일하게 동작합니다. 트리거가 실패한 실행을 기록하고 배포가 자동으로 일시 중지됩니다. 배포의 `paused_reason.error.type`은 실패한 실행의 `error.type`을 그대로 반영합니다.

## 수동 실행 트리거하기

일정과 관계없이 배포를 실행하려면 [`run` 엔드포인트](https://platform.claude.com/docs/ko/api/beta/deployments/run)를 호출하세요. 이렇게 하면 즉시 세션이 생성되고 `trigger_context.type: "manual"`이 포함된 배포 실행이 기록됩니다. 이를 통해 일정을 확정하기 전에 배포를 테스트할 수 있습니다.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/run?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  run = client.beta.deployments.run(deployment.id)
  ```

  ```typescript TypeScript
  const run = await client.beta.deployments.run(deployment.id);
  ```

  ```csharp C#
  var manualRun = await client.Beta.Deployments.Run(deployment.ID);
  ```

  ```go Go
  manualRun, err := client.Beta.Deployments.Run(ctx, deployment.ID, anthropic.BetaDeploymentRunParams{})
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var run = client.beta().deployments().run(deployment.id());
  ```

  ```php PHP
  $run = $client->beta->deployments->run($deployment->id);
  ```

  ```ruby Ruby
  run = client.beta.deployments.run(deployment.id)
  ```
</CodeGroup>