282 282
283Each session has its own conversation and work. See the [Agents API reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents) to list, retrieve, update, or delete saved agents. Credentials stay in [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults), separate from the saved configuration.283Each session has its own conversation and work. See the [Agents API reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents) to list, retrieve, update, or delete saved agents. Credentials stay in [vaults](https://developers.openai.com/api/docs/guides/agents-api/tools/vaults), separate from the saved configuration.
284 284
285## Update a saved agent
286
287Saved-agent updates apply only to new sessions. Each session copies the saved configuration when you create it and keeps those settings for later turns. To change an existing session, [update its settings](#update-settings-for-an-existing-session).
288
289When updating a saved agent:
290
291- Omitted fields keep their saved values. Changing only `model` preserves `reasoning`, `service_tier`, and `text`.
292- Supplied objects replace the whole field. Supplying `reasoning` with only `effort` also clears the saved `summary`.
293- `null` resets fields that accept it. For example, `reasoning: null` restores the model's default effort.
294
295Change or reset any settings the new model does not support in the same request.
296
285## Override settings for one session297## Override settings for one session
286 298
287299Include both `agent_id` and `agent` to customize a session that uses a saved agent. The session inherits omitted settings, including the model.Include both `agent_id` and `agent` when creating a session to customize a saved agent's configuration. The session copies omitted settings, including the model, from the saved agent at creation time.
288 300
289Replace the illustrative `agent_123` value with the saved agent's ID before running this example:301Replace the illustrative `agent_123` value with the saved agent's ID before running this example:
290 302
434 446
435See the [Create session reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions/methods/create) for request fields.447See the [Create session reference](https://developers.openai.com/api/reference/resources/beta/subresources/agents/subresources/sessions/methods/create) for request fields.
436 448
449## Update settings for an existing session
450
451Send `POST /v1/agents/sessions/{session_id}` with an `agent` object to change `model`, `reasoning.effort`, or `service_tier` for one session. These settings are available in the beta and GA API contracts. You can update `metadata` in the same request.
452
453Changes apply to new turns started by messages sent after the update completes. Messages already in flight can use the previous settings. An active turn keeps its settings, including when you send a steering message. The session keeps its conversation history. The selected model must support the resulting settings, or the update fails.
454
455- The `agent` and `reasoning` objects merge supplied fields into the current settings. Omitted fields stay unchanged, including reasoning summary. Changing only `model` preserves the session's reasoning effort and service tier.
456- `reasoning.effort: null` resets effort to the selected model's default.
457- `service_tier: null` restores automatic tier selection.
458- A model must remain set, so you cannot supply `model: null`. The `agent` and `reasoning` objects also reject `null`.
459- `metadata` replaces the full map. Omit it to preserve metadata, or pass `null` or `{}` to clear it.
460
461For example, this request changes reasoning effort and lets the API select the service tier automatically:
462
463```json
464{
465 "agent": {
466 "reasoning": { "effort": "low" },
467 "service_tier": null
468 }
469}
470```
471
472Updating a session does not change the saved agent or other sessions. Later saved-agent updates do not change the session.
473
474You cannot update `reasoning.summary`, `text`, `tools`, `instructions`, or `multi_agent` through this endpoint. Create a new session to change those settings.
475
437## Environment settings476## Environment settings
438 477
439Set `environment` alongside `agent` when creating a session. It determines where the agent runs commands and works with files.478Set `environment` alongside `agent` when creating a session. It determines where the agent runs commands and works with files.