---
title: Iniciar uma sessão
url: https://platform.claude.com/docs/pt-BR/managed-agents/sessions
description: Crie uma sessão para executar seu agente e começar a executar tarefas.
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

Uma sessão é uma instância de agente dentro de um ambiente. Cada sessão referencia um [agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup) e um [ambiente](https://platform.claude.com/docs/pt-BR/managed-agents/environments) (ambos criados separadamente) e mantém o histórico da conversa ao longo de múltiplas interações. As sessões seguem um ciclo de vida de duas etapas: primeiro [crie a sessão](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#creating-a-session), depois [envie um evento de usuário](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#starting-the-session) para iniciar o trabalho. Você também pode combinar as duas etapas em uma única chamada com [`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`)](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#seed-the-session-with-initial-events).

## Criando uma sessão

Uma sessão requer um ID de `agent` e um ID de `environment`. Agentes são recursos versionados; passar o ID de `agent` (csharp, go: `Agent`) como string cria a sessão com a versão mais recente do agente.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID"
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id
  )
  ```
</CodeGroup>

Para fixar uma sessão em uma versão específica do agente, passe um objeto. Isso permite controlar exatamente qual versão é executada e escalonar a implantação de novas versões de forma independente.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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": {"type": "agent", "id": "'"$AGENT_ID"'", "version": 1},
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent:
    type: agent
    id: $AGENT_ID
    version: 1
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  pinned_session = client.beta.sessions.create(
      agent={"type": "agent", "id": agent.id, "version": 1},
      environment_id=environment.id,
  )
  ```

  ```typescript TypeScript
  const pinnedSession = await client.beta.sessions.create({
    agent: { type: "agent", id: agent.id, version: 1 },
    environment_id: environment.id
  });
  ```

  ```csharp C#
  var pinnedSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentParams
      {
          Type = BetaManagedAgentsAgentParamsType.Agent,
          ID = agent.ID,
          Version = 1,
      },
      EnvironmentID = environment.ID,
  });
  ```

  ```go Go
  pinnedSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{
  			Type:    anthropic.BetaManagedAgentsAgentParamsTypeAgent,
  			ID:      agent.ID,
  			Version: anthropic.Int(1),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var pinnedSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentParams.builder()
          .type(BetaManagedAgentsAgentParams.Type.AGENT)
          .id(agent.id())
          .version(1)
          .build())
      .environmentId(environment.id())
      .build());
  ```

  ```php PHP
  $pinnedSession = $client->beta->sessions->create(
      agent: ['type' => 'agent', 'id' => $agent->id, 'version' => 1],
      environmentID: $environment->id,
  );
  ```

  ```ruby Ruby
  pinned_session = client.beta.sessions.create(
    agent: {type: :agent, id: agent.id, version: 1},
    environment_id: environment.id
  )
  ```
</CodeGroup>

### Inicializar a sessão com eventos iniciais

Você pode criar uma sessão e iniciar seu trabalho em uma única chamada. `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) é um array opcional de [eventos](https://platform.claude.com/docs/pt-BR/managed-agents/reference#event-types) iniciais a serem enviados à sessão na criação, processados em ordem. Ele suporta eventos `user.message` e [`user.define_outcome`](https://platform.claude.com/docs/pt-BR/managed-agents/define-outcomes) e aceita no máximo 50 eventos. Uma lista não vazia inicia o loop do agente na mesma chamada: a sessão é criada diretamente no status `running`, sem nenhuma requisição adicional.

O exemplo a seguir cria uma sessão com um único `user.message` em `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`):

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "initial_events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  initial_events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  seeded_session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      initial_events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  # initial_events não são ecoados na resposta de criação; leia-os de volta
  # a partir da lista de eventos da sessão.
  for event in client.beta.sessions.events.list(seeded_session.id):
      if event.type == "user.message":
          for block in event.content:
              if block.type == "text":
                  print(f"Seeded event: {block.text}")
  ```

  ```typescript TypeScript
  const seededSession = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });

  // initial_events não são ecoados na resposta de criação; liste os eventos
  // da sessão para ler de volta a mensagem semeada.
  for await (const event of client.beta.sessions.events.list(seededSession.id)) {
    if (event.type === "user.message") {
      for (const block of event.content) {
        if (block.type === "text") {
          console.log(`Seeded event: ${block.text}`);
        }
      }
    }
  }
  ```

  ```csharp C#
  var seededSession = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      InitialEvents =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  // initial_events não são ecoados na resposta de criação; leia-os de volta
  // a partir da lista de eventos da sessão.
  var seededEvents = await client.Beta.Sessions.Events.List(seededSession.ID);
  await foreach (var sessionEvent in seededEvents.Paginate())
  {
      if (sessionEvent.TryPickUserMessage(out var userMessage))
      {
          foreach (var contentBlock in userMessage.Content)
          {
              if (contentBlock.TryPickBetaManagedAgentsTextBlock(out var textBlock))
              {
                  Console.WriteLine($"Seeded event: {textBlock.Text}");
              }
          }
      }
  }
  ```

  ```go Go
  seededSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	InitialEvents: []anthropic.BetaSessionNewParamsInitialEventUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  })
  if err != nil {
  	panic(err)
  }
  // initial_events não são ecoados na resposta de criação, então liste os
  // eventos da sessão para ler de volta a user.message semeada.
  seededEvents, err := client.Beta.Sessions.Events.List(ctx, seededSession.ID, anthropic.BetaSessionEventListParams{})
  if err != nil {
  	panic(err)
  }
  for _, event := range seededEvents.Data {
  	if event.Type != "user.message" {
  		continue
  	}
  	for _, contentBlock := range event.AsUserMessage().Content {
  		if contentBlock.Type == "text" {
  			fmt.Printf("Seeded event: %s\n", contentBlock.AsText().Text)
  		}
  	}
  }
  ```

  ```java Java
  var seededSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addInitialEvent(BetaManagedAgentsUserMessageEventParams.builder()
          .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
          .addTextContent("List the files in the working directory.")
          .build())
      .build());
  // initial_events não são ecoados na resposta de criação; liste os
  // eventos da sessão para ler de volta o user.message semeado.
  for (var event : client.beta().sessions().events().list(seededSession.id()).autoPager()) {
      if (event.isUserMessage()) {
          for (var contentBlock : event.asUserMessage().content()) {
              if (contentBlock.isText()) {
                  IO.println("Seeded event: " + contentBlock.asText().text());
              }
          }
      }
  }
  ```

  ```php PHP
  $seededSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      initialEvents: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );

  // initial_events não são ecoados na resposta de criação; leia-os de volta
  // a partir da lista de eventos da sessão.
  $seededEvents = $client->beta->sessions->events->list($seededSession->id);
  foreach ($seededEvents->getItems() as $event) {
      if ($event->type === 'user.message') {
          echo "Seeded event: {$event->content[0]->text}\n";
      }
  }
  ```

  ```ruby Ruby
  seeded_session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    initial_events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )

  # initial_events não são ecoados na resposta de criação; leia-os de volta a partir
  # da lista de eventos da sessão.
  client.beta.sessions.events.list(seeded_session.id).auto_paging_each do |event|
    next unless event.type == :"user.message"
    event.content.each do |block|
      puts "Seeded event: #{block.text}" if block.type == :text
    end
  end
  ```
</CodeGroup>

Nenhum outro tipo de evento é aceito. Eventos que respondem a um turno do agente (`user.tool_confirmation`, `user.tool_result` e `user.custom_tool_result`) não são aceitos porque ainda não existe nenhum turno do agente, e `user.interrupt` não é aceito porque não há turno a ser interrompido. Diferentemente de `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) em uma implantação agendada, os `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) de uma sessão não aceitam `system.message`.

Cada evento em `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) é validado e persistido antes que a resposta de criação seja retornada, na ordem da lista, com um ID atribuído pelo servidor, exatamente como se você o tivesse enviado ao endpoint de [envio de eventos](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#send-events) imediatamente após a criação. As regras de conteúdo por evento também são as mesmas desse endpoint. Uma lista vazia equivale a omitir o campo. A validação é tudo ou nada: se qualquer evento falhar na validação, toda a requisição é rejeitada e nenhuma sessão é criada.

A requisição de criação é rejeitada nos seguintes casos:

| Condição                                                                                                                                                           | Status |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| Mais de um evento `user.define_outcome`                                                                                                                            | 400    |
| Um evento `user.define_outcome` sem `rubric`                                                                                                                       | 400    |
| Mais de 100 [blocos de conteúdo `document`](https://platform.claude.com/docs/pt-BR/build-with-claude/files#document-blocks) originados de arquivos em toda a lista | 400    |
| Um corpo de requisição acima de 32 MB                                                                                                                              | 413    |

Um evento `user.define_outcome` em `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) é aceito nas mesmas condições que o envio de um para uma sessão existente; consulte [Definir resultados](https://platform.claude.com/docs/pt-BR/managed-agents/define-outcomes).

### Substituir a configuração do agente para uma sessão

Você pode passar `agent` (csharp, go: `Agent`) de três formas: uma string de ID do agente, um objeto de versão fixada (`type: "agent"`) ou um objeto de substituições. A forma de substituições altera partes da configuração do agente para uma única sessão. Use-a para testar um modelo diferente ou conceder uma ferramenta extra em uma sessão sem versionar o agente. Para a forma de substituições, defina `type` como `agent_with_overrides` e passe o `id` (csharp, go: `ID`) do agente e, opcionalmente, uma `version` (csharp, go: `Version`) (omita `version` (csharp, go: `Version`) para usar a versão mais recente do agente). Em seguida, inclua qualquer um de `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) ou `skills` (csharp, go: `Skills`) com os valores que a sessão deve usar.

Cada campo substituível segue as mesmas três regras:

* **Omitir o campo:** A sessão herda o valor da versão do agente que ela referencia.

* **Definir o campo como `null`, ou como um array vazio para campos de lista:** A sessão é executada com esse campo limpo. Essa regra se aplica integralmente a `system` (csharp, go: `System`; ruby: `system_`) e `skills` (csharp, go: `Skills`). Há três exceções:

  * `model` nunca pode ser limpo. Uma sessão sempre precisa de um modelo, então `model: null` retorna um erro 400 `agent_model_required`.
  * Limpar `tools` retorna um erro 400 quando o `skills` (csharp, go: `Skills`) efetivo da sessão não está vazio, porque skills exigem a ferramenta `read`. Caso contrário, `tools: null` e `tools: []` limpam o campo.
  * Limpar `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) retorna um erro 400 quando o `tools` (csharp, go: `Tools`) efetivo da sessão ainda contém um `mcp_toolset` que referencia um dos servidores do agente. Substitua `tools` (csharp, go: `Tools`) na mesma requisição para remover essas entradas `mcp_toolset` e, em seguida, limpe `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).

* **Definir o campo com um valor:** O valor substitui integralmente o valor do agente. As substituições nunca são mescladas com a configuração do agente, então uma substituição de `tools` (csharp, go: `Tools`) deve listar todas as ferramentas que a sessão deve ter. Da mesma forma, uma substituição de `model` (csharp, go: `Model`) substitui integralmente o objeto `model` (csharp, go: `Model`) do agente, então o `effort` (csharp, go: `Effort`) próprio do agente não é mantido. Para executar a sessão em um nível de esforço específico, defina `effort` (csharp, go: `Effort`) dentro do objeto `model` (csharp, go: `Model`) da substituição. Um nível que o modelo não suporta retorna um erro 400, e uma substituição de `model` (csharp, go: `Model`) sem `effort` (csharp, go: `Effort`) é executada no nível de esforço padrão desse modelo.

As substituições se aplicam apenas à sessão que você cria. Elas não modificam o recurso do agente nem criam uma nova versão do agente, então outras sessões que referenciam o mesmo agente não são afetadas.

Na resposta, o objeto `agent` (csharp, go: `Agent`) reflete a configuração com a qual a sessão é executada após a aplicação das substituições. Seu `id` (csharp, go: `ID`) e sua `version` (csharp, go: `Version`) ainda identificam o agente e a versão aos quais as substituições são aplicadas. Isso permite rastrear uma sessão até seu agente base.

O exemplo a seguir inicia uma sessão que substitui o modelo e limpa o prompt do sistema:

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-sonnet-5-5"},
        "system": null
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # The response's `agent` is the resolved snapshot: each override replaces that
  # field for this session only, and the agent resource keeps its id and version.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-sonnet-5-5
    system: null
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  override_session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          "model": {"id": "claude-sonnet-5-5"},
          "system": None,  # clear the agent's system prompt for this session
      },
      environment_id=environment.id,
  )
  # O agente da resposta é o snapshot resolvido com os overrides aplicados.
  print(f"Model: {override_session.agent.model.id}")
  print(f"System: {override_session.agent.system}")
  ```

  ```typescript TypeScript
  const overrideSession = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      model: { id: "claude-sonnet-5-5" },
      system: null // clear the agent's system prompt for this session
    },
    environment_id: environment.id
  });
  // O agente da resposta é o snapshot resolvido com os overrides aplicados.
  console.log(`Model: ${overrideSession.agent.model.id}`);
  console.log(`System: ${overrideSession.agent.system}`);
  ```

  ```csharp C#
  var overrideSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeSonnet5_5,
          },
          System = null, // clear the agent's system prompt for this session
      },
      EnvironmentID = environment.ID,
  });
  // O agente da resposta é o snapshot resolvido com os overrides aplicados.
  Console.WriteLine($"Model: {overrideSession.Agent.Model.ID.Raw()}");
  Console.WriteLine($"System: {overrideSession.Agent.System ?? "null"}");
  ```

  ```go Go
  overrideSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID: anthropic.BetaManagedAgentsModelClaudeSonnet5_5,
  			},
  			// Limpa o prompt do sistema do agente para esta sessão.
  			System: param.Null[string](),
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  // O agent da resposta é o snapshot resolvido com os overrides aplicados.
  fmt.Printf("Model: %s\n", overrideSession.Agent.Model.ID)
  fmt.Printf("System: %q\n", overrideSession.Agent.System)
  ```

  ```java Java
  var overrideSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_SONNET_5_5)
              .build())
          .system((String) null) // clear the agent's system prompt for this session
          .build())
      .environmentId(environment.id())
      .build());
  // O agente da resposta é o snapshot resolvido com os overrides aplicados.
  IO.println("Model: " + overrideSession.agent().model().id());
  IO.println("System: " + overrideSession.agent().system().orElse("null"));
  ```

  ```php PHP
  $overrides = BetaManagedAgentsAgentWithOverridesParams::with(
      id: $agent->id,
      type: 'agent_with_overrides',
      model: ['id' => 'claude-sonnet-5-5'],
  );
  // Limpa o prompt do sistema desta sessão. O acesso via array é essencial aqui:
  // create() remove nulls de arrays brutos e ::with() trata args null como omitidos.
  $overrides['system'] = null;

  $overrideSession = $client->beta->sessions->create(
      agent: $overrides,
      environmentID: $environment->id,
  );
  // O agente da resposta é o snapshot resolvido com os overrides aplicados.
  echo "Model: {$overrideSession->agent->model->id}\n";
  echo 'System: ' . ($overrideSession->agent->system ?? 'null') . "\n";
  ```

  ```ruby Ruby
  # O override do prompt do sistema é `system_` (underscore no final) porque
  # `system` puro é o Kernel#system do Ruby. Defini-lo como nil limpa o prompt.
  override_session = client.beta.sessions.create(
    agent: Anthropic::Beta::BetaManagedAgentsAgentWithOverridesParams.new(
      type: :agent_with_overrides,
      id: agent.id,
      model: {id: "claude-sonnet-5-5"},
      system_: nil
    ),
    environment_id: environment.id
  )
  # O agente da resposta é o snapshot resolvido com os overrides aplicados.
  puts "Model: #{override_session.agent.model.id}"
  puts "System: #{override_session.agent.system_.inspect}"
  ```
</CodeGroup>

#### Fixar a geografia de inferência para uma sessão

Como uma substituição de `model` (csharp, go: `Model`) substitui integralmente o objeto `model` (csharp, go: `Model`) do agente, ela também define ou limpa a fixação de "inference geo" (geografia de inferência) do modelo para a sessão (consulte [geografia de inferência](https://platform.claude.com/docs/pt-BR/manage-claude/data-residency)): uma substituição que inclui `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) fixa a geografia que atende às requisições de modelo da sessão, e uma que o omite limpa a fixação do agente, de modo que a sessão segue o `default_inference_geo` do workspace. O valor substituído é validado em relação ao `allowed_inference_geos` do workspace quando a sessão é criada.

O exemplo a seguir inicia uma sessão a partir de um agente cujo modelo não tem fixação de geografia, fixa as requisições de modelo da sessão na inferência dos EUA incluindo `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) na substituição de `model` (csharp, go: `Model`) e imprime o valor retornado em `agent.model` (csharp, go: `Agent.Model`) na resposta:

<CodeGroup>
  ```bash cURL
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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": {
        "type": "agent_with_overrides",
        "id": "'"$AGENT_ID"'",
        "model": {"id": "claude-opus-5-5", "inference_geo": "us"}
      },
      "environment_id": "'"$ENVIRONMENT_ID"'"
    }'
  ```

  ```bash CLI
  # Replaces the whole model object of the agent: restate id, add inference_geo to pin.
  ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-opus-5-5
      inference_geo: us
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          # Substitui o `model` do agente por completo: reafirme `id`, adicione `inference_geo` para fixar.
          "model": {"id": "claude-opus-5-5", "inference_geo": "us"},
      },
      environment_id=environment.id,
  )
  print(f"Inference geo: {session.agent.model.inference_geo}")
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      // Substitui o `model` do agente por completo: redeclare `id`, adicione `inference_geo` para fixar.
      model: { id: "claude-opus-5-5", inference_geo: "us" }
    },
    environment_id: environment.id
  });
  console.log(`Inference geo: ${session.agent.model.inference_geo}`);
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          // Substitui o `model` do agente por completo: repita `id`, adicione `inference_geo` para fixar.
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeOpus5_5,
              InferenceGeo = "us",
          },
      },
      EnvironmentID = environment.ID,
  });
  Console.WriteLine($"Inference geo: {session.Agent.Model.InferenceGeo}");
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
  			Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
  			ID:   agent.ID,
  			// Substitui o `model` do agente por completo: repita `id`, adicione `inference_geo` para fixar.
  			Model: anthropic.BetaManagedAgentsModelConfigParams{
  				ID:           anthropic.BetaManagedAgentsModelClaudeOpus5_5,
  				InferenceGeo: anthropic.String("us"),
  			},
  		},
  	},
  	EnvironmentID: environment.ID,
  })
  if err != nil {
  	panic(err)
  }
  fmt.Printf("Inference geo: %s\n", session.Agent.Model.InferenceGeo)
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          // Substitui o `model` do agente por completo: repita `id`, adicione `inference_geo` para fixar.
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
              .inferenceGeo("us")
              .build())
          .build())
      .environmentId(environment.id())
      .build());
  IO.println("Inference geo: " + session.agent().model().inferenceGeo().orElseThrow());
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: BetaManagedAgentsAgentWithOverridesParams::with(
          id: $agent->id,
          type: 'agent_with_overrides',
          // Substitui o `model` do agente por completo: repita `id`, adicione `inference_geo` para fixar.
          model: BetaManagedAgentsModelConfigParams::with(
              id: 'claude-opus-5-5',
              inferenceGeo: 'us',
          ),
      ),
      environmentID: $environment->id,
  );
  echo "Inference geo: {$session->agent->model->inferenceGeo}\n";
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: {
      type: :agent_with_overrides,
      id: agent.id,
      # Substitui o `model` do agente por completo: repita `id`, adicione `inference_geo` para fixar.
      model: {id: "claude-opus-5-5", inference_geo: "us"}
    },
    environment_id: environment.id
  )
  puts "Inference geo: #{session.agent.model.inference_geo}"
  ```
</CodeGroup>

<Tip>
  O agente define como Claude se comporta dentro da sessão, incluindo o modelo, o prompt do sistema, as ferramentas e os servidores MCP. Consulte [Definir seu agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup) para mais detalhes.
</Tip>

### Definir um orçamento para a sessão

Para limitar quanto uma sessão pode gastar, passe o objeto opcional `budget` (csharp, go: `Budget`) ao criá-la. Um orçamento é um teto rígido sobre o custo de tabela da sessão: a plataforma precifica tudo o que a sessão consome pelas tarifas públicas de tabela, e a sessão para de emitir novas requisições de modelo assim que esse total acumulado atinge `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`). Defina `type` (csharp, go: `Type`) como `limit` e forneça a `max_list_cost` (java, php: `maxListCost`; csharp, go: `MaxListCost`) um `amount` (csharp, go: `Amount`) e uma `currency` (csharp, go: `Currency`). `amount` (csharp, go: `Amount`) é um número inteiro de centavos de dólar americano escrito como string, como `"125"` para $1,25. A API recebe uma string em vez de um número para que nenhum arredondamento de ponto flutuante seja aplicado. `USD` é a única moeda atualmente suportada. Quando a sessão atinge o limite, ela pausa e fica ociosa com o motivo de parada `budget_reached`. O limite é aplicado entre requisições de modelo, então a requisição que o ultrapassa termina primeiro e o custo de tabela final da sessão pode ficar [uma fração acima do limite](https://platform.claude.com/docs/pt-BR/managed-agents/budgets#when-a-session-reaches-its-budget). Um orçamento só pode ser anexado na criação: você pode [alterá-lo ou removê-lo](https://platform.claude.com/docs/pt-BR/managed-agents/session-operations#updating-the-session-budget) depois, mas não pode adicionar um a uma sessão criada sem ele.

O exemplo a seguir cria uma sessão com um orçamento de $1,25:

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -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": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "budget": {
        "type": "limit",
        "max_list_cost": {"amount": "125", "currency": "USD"}
      }
    }'
  ```

  ```bash CLI
  # Mantenha o valor entre aspas para que seja enviado como string, não como número.
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID" \
    --budget '{type: limit, max_list_cost: {amount: "125", currency: USD}}'
  ```

  ```python Python
  session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      budget={
          "type": "limit",
          "max_list_cost": {"amount": "125", "currency": "USD"},
      },
  )
  print(session.id, session.budget.max_list_cost.amount)  # sesn_01... 125
  ```

  ```typescript TypeScript
  const session = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: { amount: "125", currency: "USD" }
    }
  });
  console.log(session.id, session.budget?.max_list_cost.amount); // sesn_01... 125
  ```

  ```csharp C#
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      Budget = new()
      {
          Type = BetaManagedAgentsBudgetLimitType.Limit,
          MaxListCost = new() { Amount = "125", Currency = BetaCurrency.Usd },
      },
  });
  Console.WriteLine($"{session.ID} {session.Budget?.MaxListCost.Amount}");  // sesn_01... 125
  ```

  ```go Go
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
  		Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
  		MaxListCost: anthropic.BetaMonetaryAmountParam{
  			Amount:   "125",
  			Currency: anthropic.BetaCurrencyUsd,
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(session.ID, session.Budget.MaxListCost.Amount) // sesn_01... 125
  ```

  ```java Java
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .budget(BetaManagedAgentsBudgetLimit.builder()
          .type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
          .maxListCost(BetaMonetaryAmount.builder()
              .amount("125")
              .currency(BetaCurrency.USD)
              .build())
          .build())
      .build());
  IO.println(session.id() + " " + session.budget().orElseThrow().maxListCost().amount());  // sesn_01... 125
  ```

  ```php PHP
  $session = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      budget: [
          'type' => 'limit',
          'max_list_cost' => ['amount' => '125', 'currency' => 'USD'],
      ],
  );
  echo "{$session->id} {$session->budget->maxListCost->amount}\n"; // sesn_01... 125
  ```

  ```ruby Ruby
  session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    budget: {
      type: "limit",
      max_list_cost: {amount: "125", currency: "USD"}
    }
  )
  puts "#{session.id} #{session.budget.max_list_cost.amount}" # sesn_01... 125
  ```
</CodeGroup>

Consulte [Orçamentos de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/budgets) para saber como a aplicação funciona, o que conta para o custo de tabela e como os orçamentos se comportam em sessões multiagente.

## Autenticação MCP por meio de vaults

Se o seu agente usa ferramentas MCP que exigem autenticação, passe `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) na criação da sessão para referenciar um vault contendo credenciais OAuth armazenadas. A Anthropic gerencia a renovação de tokens em seu nome. Consulte [Autenticar com vaults](https://platform.claude.com/docs/pt-BR/managed-agents/vaults) para saber como criar vaults e registrar credenciais.

<CodeGroup>
  ```bash cURL
  curl -fsSL https://api.anthropic.com/v1/sessions \
    -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": "'"$AGENT_ID"'",
      "environment_id": "'"$ENVIRONMENT_ID"'",
      "vault_ids": ["'"$VAULT_ID"'"]
    }'
  ```

  ```bash CLI
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  vault_ids:
    - $VAULT_ID
  YAML
  ```

  ```python Python
  vault_session = client.beta.sessions.create(
      agent=agent.id,
      environment_id=environment.id,
      vault_ids=[vault.id],
  )
  ```

  ```typescript TypeScript
  const vaultSession = await client.beta.sessions.create({
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  });
  ```

  ```csharp C#
  var vaultSession = await client.Beta.Sessions.Create(new()
  {
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      VaultIds = [vault.ID],
  });
  ```

  ```go Go
  vaultSession, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
  	Agent: anthropic.BetaSessionNewParamsAgentUnion{
  		OfString: anthropic.String(agent.ID),
  	},
  	EnvironmentID: environment.ID,
  	VaultIDs:      []string{vault.ID},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var vaultSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addVaultId(vault.id())
      .build());
  ```

  ```php PHP
  $vaultSession = $client->beta->sessions->create(
      agent: $agent->id,
      environmentID: $environment->id,
      vaultIDs: [$vault->id],
  );
  ```

  ```ruby Ruby
  vault_session = client.beta.sessions.create(
    agent: agent.id,
    environment_id: environment.id,
    vault_ids: [vault.id]
  )
  ```
</CodeGroup>

## Iniciando a sessão

Criar uma sessão sem `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) registra a sessão, mas não inicia nenhum trabalho; o sandbox do ambiente começa a ser provisionado assim que a sessão é criada, então a primeira chamada de ferramenta não precisa esperar por ele. Para delegar uma tarefa, envie eventos para a sessão usando um [evento de usuário](https://platform.claude.com/docs/pt-BR/managed-agents/reference#event-types). Para fornecer o primeiro evento na própria requisição de criação, consulte [Inicializar a sessão com eventos iniciais](https://platform.claude.com/docs/pt-BR/managed-agents/sessions#seed-the-session-with-initial-events). A sessão atua como uma máquina de estados que acompanha o progresso, enquanto os eventos conduzem a execução propriamente dita.

<CodeGroup>
  ```bash cURL
  curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "events": [
        {
          "type": "user.message",
          "content": [{"type": "text", "text": "List the files in the working directory."}]
        }
      ]
    }'
  ```

  ```bash CLI
  ant beta:sessions:events send \
    --session-id "$SESSION_ID" <<'YAML'
  events:
    - type: user.message
      content:
        - type: text
          text: List the files in the working directory.
  YAML
  ```

  ```python Python
  client.beta.sessions.events.send(
      session.id,
      events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript
  await client.beta.sessions.events.send(session.id, {
    events: [
      {
        type: "user.message",
        content: [{ type: "text", text: "List the files in the working directory." }]
      }
    ]
  });
  ```

  ```csharp C#
  await client.Beta.Sessions.Events.Send(session.ID, new()
  {
      Events =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "List the files in the working directory.",
                  },
              ],
          },
      ],
  });
  ```

  ```go Go
  if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
  	Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "List the files in the working directory.",
  				},
  			}},
  		},
  	}},
  }); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().sessions().events().send(
      session.id(),
      EventSendParams.builder()
          .addEvent(BetaManagedAgentsUserMessageEventParams.builder()
              .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
              .addTextContent("List the files in the working directory.")
              .build())
          .build());
  ```

  ```php PHP
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );
  ```

  ```ruby Ruby
  client.beta.sessions.events.send_(
    session.id,
    events: [
      {
        type: :"user.message",
        content: [{type: :text, text: "List the files in the working directory."}]
      }
    ]
  )
  ```
</CodeGroup>

Consulte [Fluxo de eventos da sessão](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming) para saber como fazer streaming das respostas do agente e lidar com confirmações de ferramentas.

Consulte [Status da sessão](https://platform.claude.com/docs/pt-BR/managed-agents/session-operations#session-statuses) para conhecer os status pelos quais uma sessão passa.

## Próximos passos

<CardGroup cols={3}>
  <Card title="Operações de sessão" icon="settings" href="https://platform.claude.com/docs/pt-BR/managed-agents/session-operations">
    Recupere, liste, atualize, arquive e exclua sessões do Claude Managed Agents.
  </Card>

  <Card title="Fluxo de eventos da sessão" icon="lightning" href="https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming">
    Envie eventos, faça streaming de respostas e interrompa ou redirecione sua sessão durante a execução.
  </Card>

  <Card title="Implantações agendadas" icon="arrows-clockwise" href="https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-deployments">
    Crie e gerencie implantações com a Claude API: execute um agente em um agendamento cron recorrente e inspecione seu histórico de execuções.
  </Card>
</CardGroup>