Update Session
Modify a session's title, metadata, environment_variables, vault_ids, session-level agent configuration, and session-level MCP request headers. Updating a session is the only operation that triggers a session.updated event.
Prerequisites
Endpoint and authentication configuration must be completed. For details, see Overview and authentication.
Endpoint
POST /sessions/{session_id}
You can modify title, metadata, environment_variables, vault_ids, session-level agent configuration (agent), and session-level MCP request headers (mcp_configs). Array and object fields are replaced as a whole; empty values clear them. Updating a session is the only operation that triggers a session.updated event.
Request body
| Field | Required | Type | Description |
|---|---|---|---|
title | No | string | Session title. Omitted keeps the current value; null performs no update |
metadata | No | object | Custom key-value pairs for business use. Replaced as a whole; omitted keeps the current value, null performs no update |
environment_variables | No | object | Environment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name. Replaced as a whole; an empty object clears them, omitted keeps the current value |
vault_ids | No | array of string | Replaces vault bindings as a whole; an empty array clears them, omitted keeps the current value |
agent | No | object | Session-level agent configuration patch. Can only carry the system / tools / mcp_servers / skills override fields; carrying other fields (such as type / id / version / model) returns invalid_parameter. See Session-level configuration patch |
mcp_configs | No | array | Replaces session-level MCP request headers as a whole; same structure as in Create Session. An empty array clears them, omitted keeps the current value, null is invalid |
Session-level configuration patch
The agent patch only modifies the configuration snapshot of the current session and never creates a new agent version. Sub-field semantics (consistent with the override semantics in Create Session):
| Value | Effect |
|---|---|
| Omitted | Keep the existing override |
null | Delete the override for that field and re-inherit the agent's source configuration |
[] (array fields) | Explicitly override to empty |
"" (only for system) | Explicitly use an empty prompt |
Request example
curl -X POST "$AGENTSTUDIO_URL/sessions/sesn_xxx" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Q3 sales review",
"metadata": {"biz_ticket_id": "1234", "status": "done"},
"environment_variables": {"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"},
"agent": {
"system": "You are a project analysis assistant dedicated to this session.",
"skills": []
},
"mcp_configs": [
{"mcp_server_name": "crm", "headers": {"X-Tenant-Id": "tenant-demo"}}
]
}'
session = client.sessions.update(
"sesn_xxx",
title="Q3 sales review",
metadata={"biz_ticket_id": "1234", "status": "done"},
environment_variables={"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"},
agent={"system": "You are a project analysis assistant dedicated to this session.", "skills": []},
mcp_configs=[{"mcp_server_name": "crm", "headers": {"X-Tenant-Id": "tenant-demo"}}],
)
Map<String, String> metadata = new HashMap<>();
metadata.put("biz_ticket_id", "1234");
metadata.put("status", "done");
Map<String, String> environmentVariables = new HashMap<>();
environmentVariables.put("API_BASE_URL", "https://api.example.com");
environmentVariables.put("LOG_LEVEL", "info");
Map<String, Object> agentPatch = Map.of(
"system", "You are a project analysis assistant dedicated to this session.",
"skills", List.of());
Map<String, String> headers = Map.of("X-Tenant-Id", "tenant-demo");
Session updated = client.sessions().update("sesn_xxx",
SessionUpdateParam.builder()
.title("Q3 sales review")
.metadata(metadata)
.environmentVariables(environmentVariables)
.agent(agentPatch)
.mcpConfigs(List.of(Map.of(
"mcp_server_name", "crm",
"headers", headers)))
.build());
Response example
Returns the updated session details: new values of title / metadata / etc. after overwrite, agent (full snapshot with overrides merged), mcp_configs, vault_ids, updated_at, and request_id.
{
"id": "sesn_xxx",
"type": "session",
"status": "idle",
"title": "Q3 sales review",
"metadata": {"biz_ticket_id": "1234", "status": "done"},
"updated_at": "2026-05-28T09:30:00Z",
"request_id": "xxx",
"environment_variables": {"API_BASE_URL": "https://api.example.com", "LOG_LEVEL": "info"},
"agent": {
"id": "agent_xxx",
"type": "agent",
"version": 1,
"name": "data-analyst",
"system": "You are a project analysis assistant dedicated to this session.",
"tools": [],
"mcp_servers": [],
"skills": []
},
"vault_ids": ["vlt_xxx"],
"mcp_configs": [{"mcp_server_name": "crm", "headers": {"X-Tenant-Id": "tenant-demo"}}]
}
Response fields
| Field | Type | Description |
|---|---|---|
id | string | Session ID |
type | string | Fixed as session |
status | string | Current session status (update does not change the status) |
title / metadata | string / object | New values after overwrite from the request body |
updated_at | string | Last update time, ISO 8601 |
request_id | string | Unique identifier for this request |
environment_variables | object | Environment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name |
agent | object | Updated agent configuration snapshot with session-level overrides merged. Fields are the same as in Get Session |
vault_ids | array of string | Updated vault bindings |
mcp_configs | array of object | Updated session-level MCP request headers; each item contains mcp_server_name and headers |