> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 启动会话

> 创建会话以运行您的智能体并开始执行任务。

"会话"（会话）是环境中的一个智能体实例。每个会话都引用一个[智能体](/docs/zh/agent-setup)和一个[环境](/docs/zh/environments)（两者均需单独创建），并在多次交互中维护对话历史记录。会话遵循两步生命周期：首先[创建会话](/docs/zh/sessions#creating-a-session)，然后[发送用户事件](/docs/zh/sessions#starting-the-session)以开始工作。您也可以使用 [`initial_events`](/docs/zh/sessions#seed-the-session-with-initial-events) 将这两个步骤合并为一次调用。

<Note>
  托管智能体 API 请求需要 `managed-agents-2026-04-01` Beta 请求头，但记忆存储端点除外，它们使用 `agent-memory-2026-07-22`。SDK 会自动设置正确的 Beta 请求头。请参阅[Beta 请求头](/docs/zh/api/versioning-beta)。
</Note>

## 创建会话

会话需要一个 `agent` ID 和一个 `environment` ID。智能体是带版本的资源；以字符串形式传入 `agent` ID 会使用最新的智能体版本启动会话。

<CodeGroup defaultLanguage="CLI">
  ```bash cURL theme={null}
  session=$(curl -fsSL http://localhost:38080/v1/sessions \
    -H "x-api-key: $OMA_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
  {
    "agent": "$AGENT_ID",
    "environment_id": "$ENVIRONMENT_ID"
  }
  EOF
  )
  SESSION_ID=$(jq -r '.id' <<< "$session")
  ```

  ```bash CLI theme={null}
  ant beta:sessions create \
    --agent "$AGENT_ID" \
    --environment-id "$ENVIRONMENT_ID"
  ```

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

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

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

  ```go Go theme={null}
  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 theme={null}
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .build());
  ```

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

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

要将会话固定到特定的智能体版本，请传入一个对象。这样您可以精确控制运行的版本，并独立地分阶段推出新版本。

<CodeGroup defaultLanguage="CLI">
  ```bash cURL theme={null}
  pinned_session=$(curl -fsSL http://localhost:38080/v1/sessions \
    -H "x-api-key: $OMA_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
  {
    "agent": {"type": "agent", "id": "$AGENT_ID", "version": 1},
    "environment_id": "$ENVIRONMENT_ID"
  }
  EOF
  )
  PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")
  ```

  ```bash CLI theme={null}
  ant beta:sessions create <<YAML
  agent:
    type: agent
    id: $AGENT_ID
    version: 1
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

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

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

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

  ```go Go theme={null}
  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 theme={null}
  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 theme={null}
  $pinnedSession = $client->beta->sessions->create(
      agent: ['type' => 'agent', 'id' => $agent->id, 'version' => 1],
      environmentID: $environment->id,
  );
  ```

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

### 使用初始事件为会话提供种子

您可以在一次调用中创建会话并启动其工作。`initial_events` 是一个可选数组，包含在创建时发送给会话的初始[事件](/docs/zh/reference#event-types)，按顺序处理。它支持 `user.message` 和 [`user.define_outcome`](/docs/zh/define-outcomes) 事件，最多接受 50 个事件。非空列表会在同一次调用中启动智能体循环：会话直接以 `running` 状态创建，无需进一步请求。

以下示例创建了一个在 `initial_events` 中包含单个 `user.message` 的会话：

<CodeGroup defaultLanguage="CLI">
  ```bash cURL theme={null}
  seeded_session=$(curl -fsSL http://localhost:38080/v1/sessions \
    -H "x-api-key: $OMA_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
  {
    "agent": "$AGENT_ID",
    "environment_id": "$ENVIRONMENT_ID",
    "initial_events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "List the files in the working directory."}]
      }
    ]
  }
  EOF
  )
  SEEDED_SESSION_ID=$(jq -r '.id' <<< "$seeded_session")

  # initial_events 不会在创建响应中回显；列出会话的
  # 事件即可看到植入的消息。
  seeded_events=$(curl -fsSL \
    "http://localhost:38080/v1/sessions/$SEEDED_SESSION_ID/events" \
    -H "x-api-key: $OMA_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01")
  echo "Seeded event: $(jq -r \
    '.data[] | select(.type == "user.message") | .content[0].text' <<< "$seeded_events")"
  ```

  ```bash CLI theme={null}
  SEEDED_SESSION_ID=$(ant beta:sessions create \
    --transform id --raw-output <<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
  )

  # initial_events 不会在创建响应中回显；列出会话的
  # 事件即可看到植入的消息。
  echo "Seeded event: $(ant beta:sessions:events list \
    --session-id "$SEEDED_SESSION_ID" \
    --format raw \
    --transform 'data.#(type=="user.message").content.0.text' --raw-output)"
  ```

  ```python Python theme={null}
  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 不会在创建响应中回显；需从
  # 会话的事件列表中读回它们。
  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 theme={null}
  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 不会在创建响应中回显；需列出会话的
  // 事件才能读回预置的消息。
  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# theme={null}
  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 不会在创建响应中回显；请从
  // 会话的事件列表中读取它们。
  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 theme={null}
  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 不会在创建响应中回显，因此需列出
  // 会话的事件以读回预置的 user.message。
  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 theme={null}
  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 不会在创建响应中回显；列出
  // 会话的事件以读回预置的 user.message。
  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 theme={null}
  $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 不会在创建响应中回显；需从会话的
  // 事件列表中读取它们。
  $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 theme={null}
  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 不会在创建响应中回显；需要从
  # 会话的事件列表中读回它们。
  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>

不接受其他事件类型。响应智能体回合的事件（`user.tool_confirmation`、`user.tool_result` 和 `user.custom_tool_result`）不被接受，因为此时还不存在智能体回合；`user.interrupt` 也不被接受，因为没有可停止的回合。与计划部署上的 `initial_events` 不同，会话的 `initial_events` 不接受 `system.message`。

`initial_events` 中的每个事件都会在创建响应返回之前按列表顺序进行验证和持久化，并分配服务器生成的 ID，就像您在创建后立即将其发布到[发送事件](/docs/zh/events-and-streaming)端点一样。每个事件的内容规则也与该端点相同。空列表等同于省略该字段。验证是全有或全无的：如果任何事件验证失败，整个请求将被拒绝，且不会创建会话。

在以下情况下，创建请求会被拒绝：

| 条件                                                                 | 状态码 |
| ------------------------------------------------------------------ | --- |
| 超过一个 `user.define_outcome` 事件                                      | 400 |
| `user.define_outcome` 事件没有 `rubric`                                | 400 |
| 整个列表中来自文件的 [`document` 内容块](/docs/zh/api/files/list-files)超过 100 个 | 400 |
| 请求体超过 32 MB                                                        | 413 |

`initial_events` 中的 `user.define_outcome` 事件在与向现有会话发送该事件相同的条件下被接受；请参阅[定义结果](/docs/zh/define-outcomes)。

### 为会话覆盖智能体配置

您可以通过三种形式传递 `agent`：智能体 ID 字符串、固定版本对象（`type: "agent"`）或覆盖对象。覆盖形式可为单个会话更改智能体配置的部分内容。使用它可以在一个会话中尝试不同的模型或授予额外的工具，而无需对智能体进行版本管理。对于覆盖形式，将 `type` 设置为 `agent_with_overrides`，并传入智能体的 `id` 和可选的 `version`（省略 `version` 则使用智能体的最新版本）。然后包含 `model`、`system`、`tools`、`mcp_servers` 或 `skills` 中的任意字段，并提供会话应使用的值。

每个可覆盖的字段都遵循相同的三条规则：

* **省略该字段：** 会话从其引用的智能体版本继承该值。

* **将字段设置为 `null`，或对于列表字段设置为空数组：** 会话运行时该字段被清除。此规则完全适用于 `system` 和 `skills`。有三个例外：

  * `model` 永远不可清除。会话始终需要一个模型，因此 `model: null` 会返回 400 `agent_model_required` 错误。
  * 当会话的有效 `skills` 非空时，清除 `tools` 会返回 400 错误，因为技能需要 `read` 工具。否则，`tools: null` 和 `tools: []` 会清除该字段。
  * 当会话的有效 `tools` 仍包含引用智能体某个服务器的 `mcp_toolset` 时，清除 `mcp_servers` 会返回 400 错误。请在同一请求中覆盖 `tools` 以移除这些 `mcp_toolset` 条目，然后再清除 `mcp_servers`。

* **将字段设置为某个值：** 该值会完全替换智能体的值。覆盖永远不会与智能体的配置合并，因此 `tools` 覆盖必须列出会话应拥有的每个工具。有一个例外：
  * 会话级 `model` 覆盖中的 `effort` 不会生效。由于覆盖会完全替换智能体的 `model` 对象，智能体自身的 `effort` 也不会被保留：使用 `model` 覆盖创建的会话将以模型的默认推理强度运行。要使用特定的推理强度，请在[智能体](/docs/zh/agent-setup#agent-configuration-fields)上设置 `effort`，并且不要为该会话覆盖 `model`。

覆盖仅适用于您创建的会话。它们不会修改智能体资源或创建新的智能体版本，因此引用同一智能体的其他会话不受影响。

在响应中，`agent` 对象反映的是应用覆盖后会话运行所使用的配置。其 `id` 和 `version` 仍标识覆盖所应用到的智能体和版本。这使您可以将会话追溯到其基础智能体。

以下示例启动一个覆盖模型并清除系统提示的会话：

<CodeGroup defaultLanguage="CLI">
  ```bash cURL theme={null}
  override_session=$(curl -fsSL http://localhost:38080/v1/sessions \
    -H "x-api-key: $OMA_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
  {
    "agent": {
      "type": "agent_with_overrides",
      "id": "$AGENT_ID",
      "model": {"id": "claude-sonnet-5"},
      "system": null
    },
    "environment_id": "$ENVIRONMENT_ID"
  }
  EOF
  )
  jq '.agent | {id, version, model, system}' <<< "$override_session"
  OVERRIDE_SESSION_ID=$(jq -r '.id' <<< "$override_session")
  ```

  ```bash CLI theme={null}
  # 响应中的 `agent` 是解析后的快照：每个覆盖项仅针对此会话替换
  # 对应字段，智能体资源保留其 id 和版本。
  ant beta:sessions create \
    --transform 'agent.{id,version,model,system}' \
    --format json <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-sonnet-5
    system: null
  environment_id: $ENVIRONMENT_ID
  YAML
  ```

  ```python Python theme={null}
  override_session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          "model": {"id": "claude-sonnet-5"},
          "system": None,  # clear the agent's system prompt for this session
      },
      environment_id=environment.id,
  )
  # 响应中的 agent 是应用了覆盖后的已解析快照。
  print(f"Model: {override_session.agent.model.id}")
  print(f"System: {override_session.agent.system}")
  ```

  ```typescript TypeScript theme={null}
  const overrideSession = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      model: { id: "claude-sonnet-5" },
      system: null // clear the agent's system prompt for this session
    },
    environment_id: environment.id
  });
  // 响应中的 agent 是应用了覆盖项后解析出的快照。
  console.log(`Model: ${overrideSession.agent.model.id}`);
  console.log(`System: ${overrideSession.agent.system}`);
  ```

  ```csharp C# theme={null}
  var overrideSession = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeSonnet5,
          },
          System = null, // clear the agent's system prompt for this session
      },
      EnvironmentID = environment.ID,
  });
  // 响应中的 agent 是应用了覆盖项后解析出的快照。
  Console.WriteLine($"Model: {overrideSession.Agent.Model.ID.Raw()}");
  Console.WriteLine($"System: {overrideSession.Agent.System ?? "null"}");
  ```

  ```go Go theme={null}
  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,
              },
              // 清除此会话的智能体系统提示。
              System: param.Null[string](),
          },
      },
      EnvironmentID: environment.ID,
  })
  if err != nil {
      panic(err)
  }
  // 响应中的 agent 是应用了覆盖项后解析出的快照。
  fmt.Printf("Model: %s\n", overrideSession.Agent.Model.ID)
  fmt.Printf("System: %q\n", overrideSession.Agent.System)
  ```

  ```java Java theme={null}
  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)
              .build())
          .system((String) null) // clear the agent's system prompt for this session
          .build())
      .environmentId(environment.id())
      .build());
  // 响应中的 agent 是应用了覆盖项后解析出的快照。
  IO.println("Model: " + overrideSession.agent().model().id());
  IO.println("System: " + overrideSession.agent().system().orElse("null"));
  ```

  ```php PHP theme={null}
  $overrides = BetaManagedAgentsAgentWithOverridesParams::with(
      id: $agent->id,
      type: 'agent_with_overrides',
      model: ['id' => 'claude-sonnet-5'],
  );
  // 清除此会话的系统提示。这里数组访问方式至关重要：
  // create() 会从原始数组中剥离 null，而 ::with() 将 null 参数视为省略。
  $overrides['system'] = null;

  $overrideSession = $client->beta->sessions->create(
      agent: $overrides,
      environmentID: $environment->id,
  );
  // 响应中的 agent 是应用了覆盖后的已解析快照。
  echo "Model: {$overrideSession->agent->model->id}\n";
  echo 'System: ' . ($overrideSession->agent->system ?? 'null') . "\n";
  ```

  ```ruby Ruby theme={null}
  # 系统提示覆盖项是 `system_`（带尾部下划线），因为普通的
  # `system` 是 Ruby 的 Kernel#system。将其设为 nil 会清除该提示。
  override_session = client.beta.sessions.create(
    agent: Anthropic::Beta::BetaManagedAgentsAgentWithOverridesParams.new(
      type: :agent_with_overrides,
      id: agent.id,
      model: {id: "claude-sonnet-5"},
      system_: nil
    ),
    environment_id: environment.id
  )
  # 响应中的智能体是应用了覆盖项后解析出的快照。
  puts "Model: #{override_session.agent.model.id}"
  puts "System: #{override_session.agent.system_.inspect}"
  ```
</CodeGroup>

#### 为会话固定推理地理位置

由于 `model` 覆盖会完全替换智能体的 `model` 对象，它也会为会话设置或清除模型的 `inference_geo` 固定设置：包含 `inference_geo` 的覆盖会固定为会话的模型请求提供服务的地理位置，而省略它的覆盖会清除智能体的固定设置，使会话遵循工作区的 `default_inference_geo`。覆盖的值会在创建会话时根据工作区的 `allowed_inference_geos` 进行验证。

以下示例从一个模型没有地理位置固定的智能体启动会话，通过在 `model` 覆盖中包含 `inference_geo` 将会话的模型请求固定到美国推理，并打印响应的 `agent.model` 中回显的值：

<CodeGroup defaultLanguage="CLI">
  ```bash cURL theme={null}
  # 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
  session=$(curl -fsSL http://localhost:38080/v1/sessions \
    -H "x-api-key: $OMA_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
  {
    "agent": {
      "type": "agent_with_overrides",
      "id": "$AGENT_ID",
      "model": {"id": "claude-opus-5", "inference_geo": "us"}
    },
    "environment_id": "$ENVIRONMENT_ID"
  }
  EOF
  )
  echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"
  ```

  ```bash CLI theme={null}
  # 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
  session=$(ant beta:sessions create <<YAML
  agent:
    type: agent_with_overrides
    id: $AGENT_ID
    model:
      id: claude-opus-5
      inference_geo: us
  environment_id: $ENVIRONMENT_ID
  YAML
  )
  echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"
  ```

  ```python Python theme={null}
  session = client.beta.sessions.create(
      agent={
          "type": "agent_with_overrides",
          "id": agent.id,
          # 完整替换智能体的 `model`：重新声明 `id`，添加 `inference_geo` 以固定。
          "model": {"id": "claude-opus-5", "inference_geo": "us"},
      },
      environment_id=environment.id,
  )
  print(f"Inference geo: {session.agent.model.inference_geo}")
  ```

  ```typescript TypeScript theme={null}
  const session = await client.beta.sessions.create({
    agent: {
      type: "agent_with_overrides",
      id: agent.id,
      // 完整替换智能体的 `model`：重新声明 `id`，添加 `inference_geo` 以固定。
      model: { id: "claude-opus-5", inference_geo: "us" }
    },
    environment_id: environment.id
  });
  console.log(`Inference geo: ${session.agent.model.inference_geo}`);
  ```

  ```csharp C# theme={null}
  var session = await client.Beta.Sessions.Create(new()
  {
      Agent = new BetaManagedAgentsAgentWithOverridesParams
      {
          Type = BetaManagedAgentsAgentWithOverridesParamsType.AgentWithOverrides,
          ID = agent.ID,
          // 完整替换智能体的 `model`：重新声明 `id`，添加 `inference_geo` 以固定。
          Model = new BetaManagedAgentsModelConfigParams
          {
              ID = BetaManagedAgentsModel.ClaudeOpus5,
              InferenceGeo = "us",
          },
      },
      EnvironmentID = environment.ID,
  });
  Console.WriteLine($"Inference geo: {session.Agent.Model.InferenceGeo}");
  ```

  ```go Go theme={null}
  session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
      Agent: anthropic.BetaSessionNewParamsAgentUnion{
          OfBetaManagedAgentsAgentWithOverridess: &anthropic.BetaManagedAgentsAgentWithOverridesParams{
              Type: anthropic.BetaManagedAgentsAgentWithOverridesParamsTypeAgentWithOverrides,
              ID:   agent.ID,
              // 完整替换智能体的 `model`：重新声明 `id`，添加 `inference_geo` 以固定。
              Model: anthropic.BetaManagedAgentsModelConfigParams{
                  ID:           anthropic.BetaManagedAgentsModelClaudeOpus5,
                  InferenceGeo: anthropic.String("us"),
              },
          },
      },
      EnvironmentID: environment.ID,
  })
  if err != nil {
      panic(err)
  }
  fmt.Printf("Inference geo: %s\n", session.Agent.Model.InferenceGeo)
  ```

  ```java Java theme={null}
  var session = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(BetaManagedAgentsAgentWithOverridesParams.builder()
          .type(BetaManagedAgentsAgentWithOverridesParams.Type.AGENT_WITH_OVERRIDES)
          .id(agent.id())
          // 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
          .model(BetaManagedAgentsModelConfigParams.builder()
              .id(BetaManagedAgentsModel.CLAUDE_OPUS_5)
              .inferenceGeo("us")
              .build())
          .build())
      .environmentId(environment.id())
      .build());
  IO.println("Inference geo: " + session.agent().model().inferenceGeo().orElseThrow());
  ```

  ```php PHP theme={null}
  $session = $client->beta->sessions->create(
      agent: BetaManagedAgentsAgentWithOverridesParams::with(
          id: $agent->id,
          type: 'agent_with_overrides',
          // 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
          model: BetaManagedAgentsModelConfigParams::with(
              id: 'claude-opus-5',
              inferenceGeo: 'us',
          ),
      ),
      environmentID: $environment->id,
  );
  echo "Inference geo: {$session->agent->model->inferenceGeo}\n";
  ```

  ```ruby Ruby theme={null}
  session = client.beta.sessions.create(
    agent: {
      type: :agent_with_overrides,
      id: agent.id,
      # 完整替换智能体的 `model`：重新声明 `id`，并添加 `inference_geo` 以固定。
      model: {id: "claude-opus-5", inference_geo: "us"}
    },
    environment_id: environment.id
  )
  puts "Inference geo: #{session.agent.model.inference_geo}"
  ```
</CodeGroup>

<Tip>
  智能体定义了模型在会话中的行为方式，包括模型、系统提示、工具和 MCP 服务器。详情请参阅[定义您的智能体](/docs/zh/agent-setup)。
</Tip>

### 设置会话预算

要限制会话的支出上限，请在创建会话时传入可选的 `budget` 对象。预算是会话标价成本的硬性上限：平台按公开标价对会话消耗的所有内容进行计价，一旦累计总额达到 `max_list_cost`，会话就会停止发出新的模型请求。将 `type` 设置为 `limit`，并为 `max_list_cost` 提供 `amount` 和 `currency`。`amount` 是以字符串形式表示的美分整数，例如 `"2500"` 表示 \$25.00；API 采用字符串而非数字，以确保不会应用任何浮点舍入。`USD` 是目前唯一支持的货币。当会话达到上限时，它会暂停并进入空闲状态，停止原因为 `budget_reached`。该上限在模型请求之间强制执行，因此超过上限的那个请求会先完成，会话的最终标价成本可能会[略微超过上限](/docs/zh/budgets#when-a-session-reaches-its-budget)。预算只能在创建时附加：您可以稍后[更改或移除](/docs/zh/session-operations#updating-the-session-budget)它，但无法为创建时没有预算的会话添加预算。

以下示例创建一个预算为 \$25.00 的会话；响应会在会话资源上回显 `budget`：

```bash cURL theme={null}
curl -fsSL http://localhost:38080/v1/sessions \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2500", "currency": "USD"}
  }
}
EOF
```

请参阅[会话预算](/docs/zh/budgets)，了解强制执行的工作方式、哪些内容计入标价成本，以及预算在多智能体会话中的行为。

## 通过密钥库进行 MCP 身份验证

如果您的智能体使用需要身份验证的 MCP 工具，请在创建会话时传入 `vault_ids`，以引用包含已存储 OAuth 凭据的密钥库。OMA 会代表您管理令牌刷新。请参阅[使用密钥库进行身份验证](/docs/zh/vaults)，了解如何创建密钥库和注册凭据。

<CodeGroup defaultLanguage="CLI">
  ```bash cURL theme={null}
  vault_session=$(curl -fsSL http://localhost:38080/v1/sessions \
    -H "x-api-key: $OMA_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF
  {
    "agent": "$AGENT_ID",
    "environment_id": "$ENVIRONMENT_ID",
    "vault_ids": ["$VAULT_ID"]
  }
  EOF
  )
  VAULT_SESSION_ID=$(jq -r '.id' <<< "$vault_session")
  ```

  ```bash CLI theme={null}
  ant beta:sessions create <<YAML
  agent: $AGENT_ID
  environment_id: $ENVIRONMENT_ID
  vault_ids:
    - $VAULT_ID
  YAML
  ```

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

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

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

  ```go Go theme={null}
  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 theme={null}
  var vaultSession = client.beta().sessions().create(SessionCreateParams.builder()
      .agent(agent.id())
      .environmentId(environment.id())
      .addVaultId(vault.id())
      .build());
  ```

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

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

## 启动会话

在不使用 `initial_events` 的情况下创建会话只会注册该会话，但不会启动任何工作；环境的沙箱会在会话创建后立即开始配置，因此第一次工具调用无需等待它。要委派任务，请使用[用户事件](/docs/zh/reference#event-types)向会话发送事件。如需在创建请求中提供第一个事件，请参阅[使用初始事件为会话提供种子](/docs/zh/sessions#seed-the-session-with-initial-events)。会话充当跟踪进度的状态机，而事件驱动实际的执行。

<CodeGroup defaultLanguage="CLI">
  ```bash cURL theme={null}
  curl -fsSL "http://localhost:38080/v1/sessions/$SESSION_ID/events" \
    -H "x-api-key: $OMA_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<'EOF'
  {
    "events": [
      {
        "type": "user.message",
        "content": [{"type": "text", "text": "List the files in the working directory."}]
      }
    ]
  }
  EOF
  ```

  ```bash CLI theme={null}
  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 theme={null}
  client.beta.sessions.events.send(
      session.id,
      events=[
          {
              "type": "user.message",
              "content": [
                  {"type": "text", "text": "List the files in the working directory."}
              ],
          },
      ],
  )
  ```

  ```typescript TypeScript theme={null}
  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# theme={null}
  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 theme={null}
  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 theme={null}
  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 theme={null}
  $client->beta->sessions->events->send(
      $session->id,
      events: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'List the files in the working directory.']],
          ],
      ],
  );
  ```

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

请参阅[会话事件流](/docs/zh/events-and-streaming)，了解如何流式传输智能体的响应并处理工具确认。

请参阅[会话状态](/docs/zh/session-operations#session-statuses)，了解会话经历的各种状态。

## 后续步骤

<CardGroup cols={3}>
  <Card title="会话操作" href="/docs/zh/session-operations">
    检索、列出、更新、归档和删除 Open Managed Agents会话。
  </Card>

  <Card title="会话事件流" href="/docs/zh/events-and-streaming">
    发送事件、流式传输响应，以及在执行过程中中断或重定向您的会话。
  </Card>

  <Card title="计划部署" href="/docs/zh/scheduled-deployments">
    使用 OMA API 创建和管理部署：按定期 cron 计划运行智能体并检查其运行历史记录。
  </Card>
</CardGroup>