---
title: Operações de sessão
url: https://platform.claude.com/docs/pt-BR/managed-agents/session-operations
description: Recupere, liste, atualize, arquive e exclua sessões do 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
---

Depois que uma sessão existe, use estas operações para lê-la, atualizá-la, arquivá-la ou excluí-la. Consulte [Iniciar uma sessão](https://platform.claude.com/docs/pt-BR/managed-agents/sessions) para criar uma sessão e enviar trabalho a ela.

## Status de sessão

As sessões progridem por estes status. Consulte [Iniciar uma sessão](https://platform.claude.com/docs/pt-BR/managed-agents/sessions) para o ciclo de vida da sessão.

| Status         | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idle`         | O agente está aguardando entrada, incluindo mensagens do usuário ou confirmações de ferramentas. Sessões criadas sem `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) começam em `idle`. Uma sessão pode estar `idle` enquanto uma [execução de workflow](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#while-a-run-is-open) ainda está aberta, então `idle` por si só não significa que o trabalho foi concluído. Consulte [Saiba quando o trabalho está concluído](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#know-when-the-work-is-done). |
| `running`      | O agente está executando ativamente.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `rescheduling` | Ocorreu um erro transitório, tentando novamente automaticamente.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `terminated`   | A sessão terminou, seja por causa de um erro irrecuperável ou porque foi arquivada. Uma sessão que conclui seu trabalho vai para `idle`, não `terminated`.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

## Atualizando a configuração do agente

Você pode atualizar `agent.tools` (csharp, go: `Agent.Tools`) e `agent.mcp_servers` (java, php: `agent.mcpServers`; csharp: `Agent.McpServers`; go: `Agent.MCPServers`) de uma sessão, incluindo políticas de permissão e configurações web por ferramenta, como [filtros de domínio](https://platform.claude.com/docs/pt-BR/managed-agents/tools-web-restrictions#change-the-lists-mid-session), no meio da sessão sem criar uma nova versão do agente. As atualizações são locais à sessão e não se propagam de volta para o agente subjacente. Os valores atualizados de `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) e `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) se aplicam ao restante da sessão.

Somente `tools` (csharp, go: `Tools`) e `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) do agente podem mudar depois que uma sessão é criada. Para executar uma sessão com valores de `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`) ou `skills` (csharp, go: `Skills`) diferentes dos do agente, use [substituições de configuração do agente](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#override-agent-configuration-for-a-session) ao criar a sessão. A configuração de modelo do agente, incluindo sua fixação de [`inference_geo`](https://platform.claude.com/docs/pt-BR/manage-claude/data-residency), também não pode mudar no meio da sessão: defina a fixação ao salvar o agente, ou defina-a ou remova-a para uma única sessão com uma substituição de `model` (csharp, go: `Model`) ao criá-la. O campo `system` (csharp, go: `System`; ruby: `system_`) configurado do agente é fixo durante toda a vida útil da sessão. Em modelos que oferecem suporte, você ainda pode acrescentar orientações em nível de sistema no meio da sessão enviando um [evento `system.message`](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#send-system-messages).

A semântica de uma atualização de `tools` (csharp, go: `Tools`) ou `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) é de substituição completa: o array fornecido é o novo valor. Para preservar as entradas existentes, faça `GET` da sessão, modifique o array e envie-o de volta com `POST`.

A sessão deve estar `idle` para atualizar o agente. Para atualizar o agente enquanto a sessão está em execução, envie um [evento `user.interrupt`](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#interrupt-the-agent) sozinho e aguarde a sessão ficar `idle`. Se uma [execução de workflow](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#while-a-run-is-open) estiver aberta, seja em execução ou pausada, a atualização retorna um erro 400, mesmo quando a sessão está `idle`. Uma interrupção não encerra uma execução, portanto a atualização ainda falha depois que você interrompe a sessão. Envie uma `user.message` que [peça ao agente para parar suas execuções](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#interrupt-a-session-with-runs-open), ou aguarde até que todas as execuções tenham terminado.

<CodeGroup>
  ```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"}
      ]
    }
  )
  ```
</CodeGroup>

## Atualizando o orçamento da sessão

Uma sessão [criada com um orçamento](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#set-a-session-budget) aceita dois tipos de atualização de orçamento: substituir o limite por um novo `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) e removê-lo passando `"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`). Ambos retomam automaticamente o trabalho que foi pausado quando a sessão atingiu seu limite. Um limite substituto pode ser maior ou menor que o atual, mas deve ser estritamente maior que o custo de lista já consumido pela sessão, e a remoção é irreversível: um `budget` (csharp, go: `Budget`) não nulo só é aceito em uma sessão que atualmente tenha um, então você não pode adicionar novamente um orçamento removido nem adicionar um a uma sessão criada sem ele. Consulte [Orçamentos de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/budgets#resume-a-session-at-its-budget) para exemplos de requisição, os comportamentos de erro e o que conta para o custo de lista.

## Recuperando uma sessão

<CodeGroup>
  ```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}"
  ```
</CodeGroup>

## Listando sessões

Os resultados de `GET /v1/sessions` são paginados. Use o parâmetro de consulta `limit` para controlar o tamanho da página. Cada resposta inclui um cursor `next_page`; passe-o como o parâmetro `page` na próxima requisição para buscar a página seguinte. `next_page` é `null` quando não há mais resultados.

Para voltar uma página, passe `prev_page` como o parâmetro `page`. `prev_page` é `null` quando você está na primeira página.

Um cursor `page` é opaco e codifica o `order` da requisição que o produziu. O parâmetro de consulta `order` define a direção de ordenação dos resultados, `asc` ou `desc` por data de criação; o padrão é `desc` (mais recentes primeiro). Reutilizar um cursor com um `order` diferente retorna um erro 400, assim como alterar um filtro `created_at` de forma que ele exclua a posição do cursor. Outros parâmetros de consulta, incluindo os filtros restantes e `limit`, podem mudar entre requisições paginadas. Para os campos de paginação compartilhados entre endpoints de listagem, consulte [Paginação](https://platform.claude.com/docs/pt-BR/api/overview#pagination).

<CodeGroup>
  ```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
  # Defina `limit` baixo para que os resultados ocupem mais de uma página.
  first_page = client.beta.sessions.list(limit=1, agent_id=agent.id)
  # `prev_page` é None na primeira página; `next_page` é None na última.
  print(f"prev_page: {first_page.prev_page}")
  print(f"next_page: {first_page.next_page}")

  # Passe `next_page` de volta como `page` para buscar a próxima página.
  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}")

  # Passe `prev_page` de volta como `page` para voltar à página anterior.
  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}")
  # Para iteração apenas para frente, o objeto de página também é diretamente iterável.
  ```

  ```typescript TypeScript
  const firstPage = await client.beta.sessions.list({ limit: 1, agent_id: agent.id });
  // prev_page é null na primeira página; next_page é definido quando existem mais sessões.
  console.log(`prev_page: ${firstPage.prev_page}`);
  console.log(`next_page: ${firstPage.next_page}`);

  // Passe next_page como o cursor `page` para buscar a segunda página.
  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}`);
  }

  // Passe o cursor prev_page da segunda página para voltar à primeira página.
  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}`);
  }
  // Para iteração apenas para frente, o objeto de página também é diretamente iterável.
  ```

  ```csharp C#
  // O SessionListPage que `List` retorna expõe os itens, mas não os
  // cursores de paginação. Para ler `prev_page` / `next_page`, desserialize a resposta
  // bruta em SessionListPageResponse em vez disso.
  using var page1Response = await client.Beta.Sessions.WithRawResponse.List(
      new SessionListParams { Limit = 1, AgentID = agent.ID }
  );
  var page1 = await page1Response.Deserialize<SessionListPageResponse>();
  Console.WriteLine($"prev_page: {page1.PrevPage ?? "null"}");
  Console.WriteLine($"next_page: {page1.NextPage ?? "null"}");

  // Avançar: passe o `next_page` da página 1 como o cursor `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<SessionListPageResponse>();
  foreach (var listedSession in page2.Data ?? [])
  {
      Console.WriteLine($"Page 2: {listedSession.ID}: {listedSession.Status.Raw()}");
  }

  // Voltar: passe o `prev_page` da página 2 como o mesmo cursor `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<SessionListPageResponse>();
  foreach (var listedSession in previousPage.Data ?? [])
  {
      Console.WriteLine($"Back to page 1: {listedSession.ID}: {listedSession.Status.Raw()}");
  }
  // Para iteração apenas para frente, (await client.Beta.Sessions.List(...)).Paginate() retorna um IAsyncEnumerable que segue next_page automaticamente.
  ```

  ```go Go
  // Página 1: prev_page está vazio porque nada precede a primeira página.
  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)

  // Avançar: passe next_page como o cursor Page para buscar a página 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)
  }

  // Voltar: o prev_page da página 2 é o cursor da página anterior a ela.
  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)
  }
  // Para iteração apenas para frente, use ListAutoPaging para seguir next_page automaticamente.
  ```

  ```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 é um Optional vazio na primeira página; next_page aponta para a página 2.
  IO.println("prev_page: " + firstPage.response().prevPage());
  IO.println("next_page: " + firstPage.response().nextPage());

  // Avance passando next_page como o cursor de página.
  var nextCursor = firstPage.response().nextPage().orElseThrow();
  var secondPage = client.beta().sessions().list(params.toBuilder().page(nextCursor).build());

  // Volte passando prev_page como o mesmo cursor de página.
  var prevCursor = secondPage.response().prevPage().orElseThrow();
  var previousPage = client.beta().sessions().list(params.toBuilder().page(prevCursor).build());
  // De volta à primeira página, então prev_page está vazio novamente.
  IO.println("prev_page: " + previousPage.response().prevPage());
  // Para iteração apenas para frente, page.autoPager() retorna um Iterable que segue next_page automaticamente.
  ```

  ```php PHP
  // Página 1: prevPage é null porque nada precede a primeira página.
  $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";

  // Avançar: passe nextPage de volta como o cursor `page` para buscar a página 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";
  }

  // Voltar: o prevPage da página 2 é o cursor da página anterior a ela.
  $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";
  }
  // Para iteração apenas para frente, $page->pagingEachItem() produz cada sessão em todas as páginas.
  ```

  ```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 na primeira página. O cursor da próxima página é exposto como
  # `next_page_` (underscore no final) porque `next_page` puro é o método auxiliar
  # que busca o objeto da próxima página para você.
  puts "prev_page: #{first_page.prev_page.inspect}"
  puts "next_page: #{first_page.next_page_.inspect}"

  # Passe qualquer um dos cursores de volta como `page` para percorrer a lista em ambas as direções.
  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
  # Para iteração apenas para frente, page.auto_paging_each segue next_page automaticamente.
  ```
</CodeGroup>

## Arquivando uma sessão

Arquive uma sessão para impedir que novos eventos sejam enviados, preservando seu histórico. Uma sessão `running` não pode ser arquivada; para arquivá-la, envie um [evento `user.interrupt`](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#interrupt-the-agent) sozinho e aguarde a sessão ficar `idle`. Se uma [execução de workflow](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#while-a-run-is-open) estiver aberta, o arquivamento pode retornar um erro 400, mesmo quando a sessão está `idle`, ou pode ser bem-sucedido e encerrar a execução. Antes de arquivar, envie uma `user.message` que [peça ao agente para parar suas execuções](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#interrupt-a-session-with-runs-open), ou aguarde até que cada execução tenha terminado. Em seguida, arquive a sessão quando ela estiver `idle`.

<CodeGroup>
  ```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)
  ```
</CodeGroup>

## Excluindo uma sessão

Exclua uma sessão para remover permanentemente seu registro, eventos e sandbox associado. Uma sessão `running` não pode ser excluída; para excluí-la, envie um [evento `user.interrupt`](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#interrupt-the-agent) sozinho e aguarde a sessão ficar `idle`. Se uma [execução de workflow](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#while-a-run-is-open) estiver aberta, a exclusão pode retornar um erro 400, mesmo quando a sessão está `idle`, ou pode ser bem-sucedida. Após uma exclusão bem-sucedida, nenhum evento `workflow_run` informa o término das execuções da sessão. Antes de excluir, envie uma `user.message` que [peça ao agente para parar suas execuções](https://platform.claude.com/docs/pt-BR/managed-agents/workflow-runs#interrupt-a-session-with-runs-open), ou aguarde até que cada execução tenha terminado. Em seguida, exclua a sessão quando ela estiver `idle`.

Armazenamentos de memória, cofres, skills, ambientes e agentes são recursos independentes e não são afetados pela exclusão da sessão. Arquivos que você enviou por meio da Files API também não são afetados, mas arquivos que a própria sessão produziu têm escopo restrito a ela e são excluídos permanentemente junto com seu sistema de arquivos. Baixe tudo o que você precisa manter antes de excluir a sessão. Um arquivo de saída gravado no final do último turno pode levar alguns segundos após a sessão ficar idle para aparecer na [lista de arquivos da sessão](https://platform.claude.com/docs/pt-BR/managed-agents/files#listing-and-downloading-session-files), portanto verifique primeiro se os arquivos que você espera estão listados.

<CodeGroup>
  ```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)
  ```
</CodeGroup>