--- title: 세션 작업 url: https://platform.claude.com/docs/ko/managed-agents/session-operations description: Claude Managed Agents 세션을 조회, 나열, 업데이트, 보관 및 삭제합니다. featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 세션이 존재하면 이러한 작업을 사용하여 세션을 읽고, 업데이트하고, 보관하거나 삭제할 수 있습니다. 세션을 생성하고 작업을 보내는 방법은 [세션 시작하기](https://platform.claude.com/docs/ko/managed-agents/sessions)를 참조하세요. ## 세션 상태 세션은 다음 상태를 거쳐 진행됩니다. 세션 수명 주기에 대해서는 [세션 시작하기](https://platform.claude.com/docs/ko/managed-agents/sessions)를 참조하세요. | 상태 | 설명 | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `idle` | 에이전트가 사용자 메시지나 도구 확인을 포함한 입력을 기다리고 있습니다. `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) 없이 생성된 세션은 `idle` 상태로 시작합니다. [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#while-a-run-is-open)이 아직 열려 있는 동안에도 세션이 `idle` 상태일 수 있으므로, `idle`만으로는 작업이 완료되었다는 의미가 아닙니다. [작업이 완료되는 시점 파악하기](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#know-when-the-work-is-done)를 참조하세요. | | `running` | 에이전트가 활발히 실행 중입니다. | | `rescheduling` | 일시적인 오류가 발생하여 자동으로 재시도 중입니다. | | `terminated` | 복구할 수 없는 오류가 발생했거나 보관되었기 때문에 세션이 종료되었습니다. 작업을 완료한 세션은 `terminated`가 아니라 `idle` 상태가 됩니다. | ## 에이전트 구성 업데이트 새 에이전트 버전을 만들지 않고도 세션 도중에 세션의 `agent.tools` (csharp, go: `Agent.Tools`) 및 `agent.mcp_servers` (java, php: `agent.mcpServers`; csharp: `Agent.McpServers`; go: `Agent.MCPServers`)를 업데이트할 수 있으며, 여기에는 권한 정책과 [도메인 필터](https://platform.claude.com/docs/ko/managed-agents/tools-web-restrictions#change-the-lists-mid-session) 같은 도구별 웹 설정이 포함됩니다. 업데이트는 세션에 국한되며 기반 에이전트에 다시 전파되지 않습니다. 업데이트된 `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) 및 `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`)는 세션의 나머지 기간 동안 적용됩니다. 세션이 생성된 후에는 에이전트의 `tools` (csharp, go: `Tools`) 및 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`)만 변경할 수 있습니다. 에이전트와 다른 `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`) 또는 `skills` (csharp, go: `Skills`) 값으로 세션을 실행하려면, 세션을 생성할 때 [에이전트 구성 재정의](https://platform.claude.com/docs/ko/managed-agents/sessions#override-agent-configuration-for-a-session)를 사용하세요. [`inference_geo`](https://platform.claude.com/docs/ko/manage-claude/data-residency) 고정을 포함한 에이전트의 모델 구성도 세션 도중에 변경할 수 없습니다. 에이전트를 저장할 때 고정을 설정하거나, 세션을 생성할 때 `model` (csharp, go: `Model`) 재정의를 사용하여 단일 세션에 대해 설정하거나 해제하세요. 에이전트에 구성된 `system` (csharp, go: `System`; ruby: `system_`) 필드는 세션 수명 동안 고정됩니다. 이를 지원하는 모델에서는 [`system.message` 이벤트](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#send-system-messages)를 보내 세션 도중에도 시스템 수준 지침을 추가할 수 있습니다. `tools` (csharp, go: `Tools`) 또는 `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) 업데이트의 의미는 전체 교체입니다. 즉, 제공된 배열이 새 값이 됩니다. 기존 항목을 유지하려면 세션을 `GET`하고, 배열을 수정한 다음, 다시 `POST`하세요. 에이전트를 업데이트하려면 세션이 `idle` 상태여야 합니다. 세션이 실행 중일 때 에이전트를 업데이트하려면 [`user.interrupt` 이벤트](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#interrupt-the-agent)를 단독으로 보내고 세션이 `idle` 상태가 될 때까지 기다리세요. [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#while-a-run-is-open)이 열려 있으면, 실행 중이든 일시 중지되었든 세션이 `idle` 상태이더라도 업데이트는 400 오류를 반환합니다. 중단은 실행을 종료하지 않으므로 세션을 중단한 후에도 업데이트는 여전히 실패합니다. [에이전트에게 실행을 중지하도록 요청하는](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#interrupt-a-session-with-runs-open) `user.message`를 보내거나, 모든 실행이 종료될 때까지 기다리세요. ```bash cURL curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \ -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 '{ "agent": { "tools": [ {"type": "agent_toolset_20260401"}, {"type": "mcp_toolset", "mcp_server_name": "linear"} ], "mcp_servers": [ {"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"} ] } }' ``` ```bash CLI ant beta:sessions update --session-id "$SESSION_ID" <<'YAML' agent: tools: - type: agent_toolset_20260401 - type: mcp_toolset mcp_server_name: linear mcp_servers: - type: url name: linear url: https://mcp.linear.app/sse YAML ``` ```python Python client.beta.sessions.update( session.id, agent={ "tools": [ {"type": "agent_toolset_20260401"}, {"type": "mcp_toolset", "mcp_server_name": "linear"}, ], "mcp_servers": [ {"type": "url", "name": "linear", "url": "https://mcp.linear.app/sse"} ], }, ) ``` ```typescript TypeScript await client.beta.sessions.update(session.id, { agent: { tools: [ { type: "agent_toolset_20260401" }, { type: "mcp_toolset", mcp_server_name: "linear" } ], mcp_servers: [{ type: "url", name: "linear", url: "https://mcp.linear.app/sse" }] } }); ``` ```csharp C# await client.Beta.Sessions.Update(session.ID, new() { Agent = new() { Tools = [ new BetaManagedAgentsAgentToolset20260401Params { Type = BetaManagedAgentsAgentToolset20260401ParamsType.AgentToolset20260401, }, new BetaManagedAgentsMcpToolsetParams { Type = BetaManagedAgentsMcpToolsetParamsType.McpToolset, McpServerName = "linear", }, ], McpServers = [ new() { Type = BetaManagedAgentsUrlMcpServerParamsType.Url, Name = "linear", Url = "https://mcp.linear.app/sse", }, ], }, }); ``` ```go Go _, err = client.Beta.Sessions.Update(ctx, session.ID, anthropic.BetaSessionUpdateParams{ Agent: anthropic.BetaManagedAgentsSessionAgentUpdateParam{ Tools: []anthropic.BetaManagedAgentsSessionAgentUpdateToolUnionParam{ { OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, }, }, { OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, MCPServerName: "linear", }, }, }, MCPServers: []anthropic.BetaManagedAgentsURLMCPServerParams{ { Type: anthropic.BetaManagedAgentsURLMCPServerParamsTypeURL, Name: "linear", URL: "https://mcp.linear.app/sse", }, }, }, }) if err != nil { panic(err) } ``` ```java Java client.beta().sessions().update( session.id(), SessionUpdateParams.builder() .agent(BetaManagedAgentsSessionAgentUpdate.builder() .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) .build()) .addTool(BetaManagedAgentsMcpToolsetParams.builder() .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) .mcpServerName("linear") .build()) .addMcpServer(BetaManagedAgentsUrlMcpServerParams.builder() .type(BetaManagedAgentsUrlMcpServerParams.Type.URL) .name("linear") .url("https://mcp.linear.app/sse") .build()) .build()) .build() ); ``` ```php PHP $client->beta->sessions->update( $session->id, agent: BetaManagedAgentsSessionAgentUpdate::with( tools: [ BetaManagedAgentsAgentToolset20260401Params::with(type: 'agent_toolset_20260401'), BetaManagedAgentsMCPToolsetParams::with(mcpServerName: 'linear', type: 'mcp_toolset'), ], mcpServers: [ BetaManagedAgentsURLMCPServerParams::with( name: 'linear', type: 'url', url: 'https://mcp.linear.app/sse', ), ], ), ); ``` ```ruby Ruby client.beta.sessions.update( session.id, agent: { tools: [ {type: :agent_toolset_20260401}, {type: :mcp_toolset, mcp_server_name: "linear"} ], mcp_servers: [ {type: :url, name: "linear", url: "https://mcp.linear.app/sse"} ] } ) ``` ## 세션 예산 업데이트 [예산과 함께 생성된](https://platform.claude.com/docs/ko/managed-agents/sessions#set-a-session-budget) 세션은 두 가지 종류의 예산 업데이트를 허용합니다. 새 `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`)로 한도를 교체하는 것과, `"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`)을 전달하여 한도를 제거하는 것입니다. 두 방법 모두 세션이 한도에 도달하여 일시 중지된 작업을 자동으로 재개합니다. 교체 한도는 현재 한도보다 높거나 낮을 수 있지만, 세션이 소비한 정가 비용보다 반드시 커야 합니다. 또한 제거는 단방향입니다. null이 아닌 `budget` (csharp, go: `Budget`)은 현재 예산이 있는 세션에서만 허용되므로, 제거된 예산을 다시 추가하거나 예산 없이 생성된 세션에 예산을 추가할 수 없습니다. 요청 예시, 오류 동작, 정가 비용에 포함되는 항목에 대해서는 [세션 예산](https://platform.claude.com/docs/ko/managed-agents/budgets#resume-a-session-at-its-budget)을 참조하세요. ## 세션 조회 ```bash cURL curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_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:sessions retrieve --session-id "$SESSION_ID" ``` ```python Python retrieved = client.beta.sessions.retrieve(session.id) print(f"Status: {retrieved.status}") ``` ```typescript TypeScript const retrieved = await client.beta.sessions.retrieve(session.id); console.log(`Status: ${retrieved.status}`); ``` ```csharp C# var retrieved = await client.Beta.Sessions.Retrieve(session.ID); Console.WriteLine($"Status: {retrieved.Status.Raw()}"); ``` ```go Go retrieved, err := client.Beta.Sessions.Get(ctx, session.ID, anthropic.BetaSessionGetParams{}) if err != nil { panic(err) } fmt.Printf("Status: %s\n", retrieved.Status) ``` ```java Java var retrieved = client.beta().sessions().retrieve(session.id()); IO.println("Status: " + retrieved.status()); ``` ```php PHP $retrieved = $client->beta->sessions->retrieve($session->id); echo "Status: {$retrieved->status}\n"; ``` ```ruby Ruby retrieved = client.beta.sessions.retrieve(session.id) puts "Status: #{retrieved.status}" ``` ## 세션 나열 `GET /v1/sessions`의 결과는 페이지로 나뉩니다. `limit` 쿼리 매개변수를 사용하여 페이지 크기를 제어하세요. 각 응답에는 `next_page` 커서가 포함되며, 다음 요청에서 이를 `page` 매개변수로 전달하면 다음 페이지를 가져올 수 있습니다. 더 이상 결과가 없으면 `next_page`는 `null`입니다. 이전 페이지로 돌아가려면 `prev_page`를 `page` 매개변수로 전달하세요. 첫 페이지에 있을 때 `prev_page`는 `null`입니다. `page` 커서는 불투명하며 이를 생성한 요청의 `order`를 인코딩합니다. `order` 쿼리 매개변수는 결과의 정렬 방향을 생성 시간 기준 `asc` 또는 `desc`로 설정하며, 기본값은 `desc`(최신순)입니다. 다른 `order`로 커서를 재사용하면 400 오류가 반환되며, 커서의 위치를 제외하도록 `created_at` 필터를 변경하는 경우에도 마찬가지입니다. 나머지 필터와 `limit`을 포함한 다른 쿼리 매개변수는 페이지 요청 간에 변경할 수 있습니다. 목록 엔드포인트 전반에서 공유되는 페이지네이션 필드에 대해서는 [페이지네이션](https://platform.claude.com/docs/ko/api/overview#pagination)을 참조하세요. ```bash cURL curl -sS --fail-with-body \ "https://api.anthropic.com/v1/sessions?agent_id=$AGENT_ID&limit=1" \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" # Pass next_page back as the page query parameter to fetch the next page, # or prev_page to go back. ``` ```bash CLI # --format raw returns one page envelope with its prev_page and next_page # cursors; the default output auto-paginates and emits only the sessions. ant beta:sessions list \ --agent-id "$AGENT_ID" \ --limit 1 \ --format raw # Pass next_page back as --page to fetch the next page, or prev_page to go back. ``` ```python Python # 결과가 여러 페이지에 걸치도록 `limit`을 낮게 설정합니다. first_page = client.beta.sessions.list(limit=1, agent_id=agent.id) # 첫 페이지에서는 `prev_page`가 None이고, 마지막 페이지에서는 `next_page`가 None입니다. print(f"prev_page: {first_page.prev_page}") print(f"next_page: {first_page.next_page}") # `next_page`를 `page`로 다시 전달하여 다음 페이지를 가져옵니다. second_page = client.beta.sessions.list( limit=1, agent_id=agent.id, page=first_page.next_page ) for listed_session in second_page.data: print(f"{listed_session.id}: {listed_session.status}") # `prev_page`를 `page`로 다시 전달하여 이전 페이지로 돌아갑니다. previous_page = client.beta.sessions.list( limit=1, agent_id=agent.id, page=second_page.prev_page ) for listed_session in previous_page.data: print(f"{listed_session.id}: {listed_session.status}") # 앞으로만 순회하는 경우 페이지 객체를 직접 반복할 수도 있습니다. ``` ```typescript TypeScript const firstPage = await client.beta.sessions.list({ limit: 1, agent_id: agent.id }); // 첫 페이지에서 prev_page는 null이며, 세션이 더 있으면 next_page가 설정됩니다. console.log(`prev_page: ${firstPage.prev_page}`); console.log(`next_page: ${firstPage.next_page}`); // next_page를 `page` 커서로 전달하여 두 번째 페이지를 가져옵니다. const secondPage = await client.beta.sessions.list({ limit: 1, agent_id: agent.id, page: firstPage.next_page }); for (const listedSession of secondPage.data) { console.log(`Page 2 has ${listedSession.id}: ${listedSession.status}`); } // 두 번째 페이지의 prev_page 커서를 전달하여 첫 페이지로 돌아갑니다. const previousPage = await client.beta.sessions.list({ limit: 1, agent_id: agent.id, page: secondPage.prev_page }); for (const listedSession of previousPage.data) { console.log(`Back on page 1: ${listedSession.id} is ${listedSession.status}`); } // 정방향 반복만 필요하면 페이지 객체를 직접 순회할 수도 있습니다. ``` ```csharp C# // `List`가 반환하는 SessionListPage는 항목은 노출하지만 페이지네이션 // 커서는 노출하지 않습니다. `prev_page` / `next_page`를 읽으려면 원시 응답을 // SessionListPageResponse로 역직렬화하세요. using var page1Response = await client.Beta.Sessions.WithRawResponse.List( new SessionListParams { Limit = 1, AgentID = agent.ID } ); var page1 = await page1Response.Deserialize(); Console.WriteLine($"prev_page: {page1.PrevPage ?? "null"}"); Console.WriteLine($"next_page: {page1.NextPage ?? "null"}"); // 다음으로 이동: 1페이지의 `next_page`를 `page` 커서로 전달합니다. using var page2Response = await client.Beta.Sessions.WithRawResponse.List( new SessionListParams { Limit = 1, AgentID = agent.ID, Page = page1.NextPage } ); var page2 = await page2Response.Deserialize(); foreach (var listedSession in page2.Data ?? []) { Console.WriteLine($"Page 2: {listedSession.ID}: {listedSession.Status.Raw()}"); } // 뒤로 이동: 2페이지의 `prev_page`를 동일한 `page` 커서로 전달합니다. using var previousPageResponse = await client.Beta.Sessions.WithRawResponse.List( new SessionListParams { Limit = 1, AgentID = agent.ID, Page = page2.PrevPage } ); var previousPage = await previousPageResponse.Deserialize(); foreach (var listedSession in previousPage.Data ?? []) { Console.WriteLine($"Back to page 1: {listedSession.ID}: {listedSession.Status.Raw()}"); } // 정방향 반복만 필요하면 (await client.Beta.Sessions.List(...)).Paginate()가 next_page를 자동으로 따라가는 IAsyncEnumerable을 반환합니다. ``` ```go Go // 1페이지: 첫 페이지 앞에는 아무것도 없으므로 prev_page는 비어 있습니다. firstPage, err := client.Beta.Sessions.List(ctx, anthropic.BetaSessionListParams{ AgentID: anthropic.String(agent.ID), Limit: anthropic.Int(1), }) if err != nil { panic(err) } fmt.Printf("Page 1 prev_page: %q\n", firstPage.PrevPage) fmt.Printf("Page 1 next_page: %q\n", firstPage.NextPage) // 다음으로 이동: next_page를 Page 커서로 전달하여 2페이지를 가져옵니다. secondPage, err := client.Beta.Sessions.List(ctx, anthropic.BetaSessionListParams{ AgentID: anthropic.String(agent.ID), Limit: anthropic.Int(1), Page: anthropic.String(firstPage.NextPage), }) if err != nil { panic(err) } for _, listedSession := range secondPage.Data { fmt.Printf("Page 2: %s: %s\n", listedSession.ID, listedSession.Status) } // 뒤로 이동: 2페이지의 prev_page는 그 이전 페이지의 커서입니다. previousPage, err := client.Beta.Sessions.List(ctx, anthropic.BetaSessionListParams{ AgentID: anthropic.String(agent.ID), Limit: anthropic.Int(1), Page: anthropic.String(secondPage.PrevPage), }) if err != nil { panic(err) } for _, listedSession := range previousPage.Data { fmt.Printf("Back to page 1: %s: %s\n", listedSession.ID, listedSession.Status) } // 정방향 반복만 필요하면 ListAutoPaging을 사용하여 next_page를 자동으로 따라갑니다. ``` ```java Java var params = SessionListParams.builder() .agentId(agent.id()) .limit(1) .build(); var firstPage = client.beta().sessions().list(params); for (var listedSession : firstPage.data()) { IO.println(listedSession.id() + ": " + listedSession.status()); } // 첫 페이지에서 prev_page는 빈 Optional이고, next_page는 2페이지를 가리킵니다. IO.println("prev_page: " + firstPage.response().prevPage()); IO.println("next_page: " + firstPage.response().nextPage()); // next_page를 페이지 커서로 전달하여 다음으로 이동합니다. var nextCursor = firstPage.response().nextPage().orElseThrow(); var secondPage = client.beta().sessions().list(params.toBuilder().page(nextCursor).build()); // prev_page를 동일한 페이지 커서로 전달하여 뒤로 이동합니다. var prevCursor = secondPage.response().prevPage().orElseThrow(); var previousPage = client.beta().sessions().list(params.toBuilder().page(prevCursor).build()); // 첫 페이지로 돌아왔으므로 prev_page는 다시 비어 있습니다. IO.println("prev_page: " + previousPage.response().prevPage()); // 정방향 전용 반복의 경우 page.autoPager()는 next_page를 자동으로 따라가는 Iterable을 반환합니다. ``` ```php PHP // 1페이지: 첫 페이지 앞에는 아무것도 없으므로 prevPage는 null입니다. $firstPage = $client->beta->sessions->list(agentID: $agent->id, limit: 1); echo 'Page 1 prev_page: ' . ($firstPage->prevPage ?? 'null') . "\n"; echo 'Page 1 next_page: ' . ($firstPage->nextPage ?? 'null') . "\n"; // 다음으로 이동: nextPage를 `page` 커서로 다시 전달하여 2페이지를 가져옵니다. $secondPage = $client->beta->sessions->list( agentID: $agent->id, limit: 1, page: $firstPage->nextPage, ); foreach ($secondPage->getItems() as $listedSession) { echo "Page 2: {$listedSession->id}: {$listedSession->status}\n"; } // 뒤로 이동: 2페이지의 prevPage는 그 이전 페이지의 커서입니다. $previousPage = $client->beta->sessions->list( agentID: $agent->id, limit: 1, page: $secondPage->prevPage, ); foreach ($previousPage->getItems() as $listedSession) { echo "Back to page 1: {$listedSession->id}: {$listedSession->status}\n"; } // 정방향 반복만 필요하면 $page->pagingEachItem()이 모든 페이지의 세션을 순회합니다. ``` ```ruby Ruby first_page = client.beta.sessions.list(agent_id: agent.id, limit: 1) first_page.data.each do |listed_session| puts "#{listed_session.id}: #{listed_session.status}" end # `prev_page`는 첫 페이지에서 nil입니다. 다음 페이지 커서는 `next_page_` # (밑줄 접미사)로 노출됩니다. 일반 `next_page`는 다음 페이지 객체를 # 가져와 주는 헬퍼 메서드이기 때문입니다. puts "prev_page: #{first_page.prev_page.inspect}" puts "next_page: #{first_page.next_page_.inspect}" # 어느 커서든 `page`로 다시 전달하면 목록을 양방향으로 이동할 수 있습니다. second_page = client.beta.sessions.list( agent_id: agent.id, limit: 1, page: first_page.next_page_ ) back_to_first = client.beta.sessions.list( agent_id: agent.id, limit: 1, page: second_page.prev_page ) back_to_first.data.each do |listed_session| puts "#{listed_session.id}: #{listed_session.status}" end # 정방향 전용 반복에는 page.auto_paging_each가 next_page를 자동으로 따라갑니다. ``` ## 세션 보관 세션을 보관하면 기록은 유지하면서 새 이벤트가 전송되지 않도록 할 수 있습니다. `running` 상태의 세션은 보관할 수 없습니다. 보관하려면 [`user.interrupt` 이벤트](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#interrupt-the-agent)를 단독으로 보내고 세션이 `idle` 상태가 될 때까지 기다리세요. [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#while-a-run-is-open)이 열려 있으면, 세션이 `idle` 상태이더라도 보관 시 400 오류가 반환되거나, 보관이 성공하고 실행이 종료될 수 있습니다. 보관하기 전에 [에이전트에게 실행을 중지하도록 요청하는](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#interrupt-a-session-with-runs-open) `user.message`를 보내거나, 각 실행이 종료될 때까지 기다리세요. 그런 다음 세션이 `idle` 상태가 되면 보관하세요. ```bash cURL curl -fsSL -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/archive" \ -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:sessions archive \ --session-id "$SESSION_ID" ``` ```python Python client.beta.sessions.archive(session.id) ``` ```typescript TypeScript await client.beta.sessions.archive(session.id); ``` ```csharp C# await client.Beta.Sessions.Archive(session.ID); ``` ```go Go _, err = client.Beta.Sessions.Archive(ctx, session.ID, anthropic.BetaSessionArchiveParams{}) if err != nil { panic(err) } ``` ```java Java client.beta().sessions().archive(session.id()); ``` ```php PHP $client->beta->sessions->archive($session->id); ``` ```ruby Ruby client.beta.sessions.archive(session.id) ``` ## 세션 삭제 세션을 삭제하면 해당 레코드, 이벤트 및 연결된 샌드박스가 영구적으로 제거됩니다. `running` 상태의 세션은 삭제할 수 없습니다. 삭제하려면 [`user.interrupt` 이벤트](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#interrupt-the-agent)를 단독으로 보내고 세션이 `idle` 상태가 될 때까지 기다리세요. [워크플로 실행](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#while-a-run-is-open)이 열려 있으면, 세션이 `idle` 상태이더라도 삭제 시 400 오류가 반환되거나, 삭제가 성공할 수 있습니다. 삭제가 성공한 후에는 어떤 `workflow_run` 이벤트도 세션에 속한 워크플로 실행의 종료를 보고하지 않습니다. 삭제하기 전에 [에이전트에게 실행을 중지하도록 요청하는](https://platform.claude.com/docs/ko/managed-agents/workflow-runs#interrupt-a-session-with-runs-open) `user.message`를 보내거나, 각 실행이 종료될 때까지 기다리세요. 그런 다음 세션이 `idle` 상태가 되면 삭제하세요. 메모리 저장소, 볼트, 스킬, 환경 및 에이전트는 독립적인 리소스이며 세션 삭제의 영향을 받지 않습니다. Files API를 통해 업로드한 파일도 영향을 받지 않지만, 세션 자체가 생성한 파일은 해당 세션에 범위가 한정되어 있어 파일 시스템과 함께 영구적으로 삭제됩니다. 세션을 삭제하기 전에 보관해야 할 항목을 모두 다운로드하세요. 마지막 턴이 끝날 때 작성된 출력 파일은 세션이 idle 상태가 된 후 [세션의 파일 목록](https://platform.claude.com/docs/ko/managed-agents/files#listing-and-downloading-session-files)에 나타나기까지 몇 초가 걸릴 수 있으므로, 먼저 예상하는 파일이 목록에 있는지 확인하세요. ```bash cURL curl -fsSL -X DELETE "https://api.anthropic.com/v1/sessions/$SESSION_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:sessions delete \ --session-id "$SESSION_ID" ``` ```python Python client.beta.sessions.delete(session.id) ``` ```typescript TypeScript await client.beta.sessions.delete(session.id); ``` ```csharp C# await client.Beta.Sessions.Delete(session.ID); ``` ```go Go _, err = client.Beta.Sessions.Delete(ctx, session.ID, anthropic.BetaSessionDeleteParams{}) if err != nil { panic(err) } ``` ```java Java client.beta().sessions().delete(session.id()); ``` ```php PHP $client->beta->sessions->delete($session->id); ``` ```ruby Ruby client.beta.sessions.delete(session.id) ```