Start a Session

Create a Session

On the agent details page, click New Session, bind a runtime environment (required), and enter the session page. At creation time, the server snapshots the current agent configuration. Subsequent edits to the agent do not affect existing sessions.

When creating a session via the API, you must bind an agent and a runtime environment. The server automatically snapshots the current agent configuration. For complete parameters and response fields, see Create Session.

curl -X POST "https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sessions" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "environment_id": "env_xxx",
    "title": "Q3 Sales Data Analysis",
    "resources": [
      {"type": "file", "file_id": "file_xxx", "mount_path": "/uploads/workspace/data.csv"}
    ]
  }'

session = client.sessions.create(
    agent="agent_xxx",
    environment_id="env_xxx",
    title="Q3 Sales Data Analysis",
    resources=[
        {"type": "file", "file_id": "file_xxx", "mount_path": "/uploads/workspace/data.csv"},
    ],
)
print(session.id, session.status)

Session session = client.sessions().create(SessionCreateParam.builder()
    .agent("agent_xxx")
    .environmentId("env_xxx")
    .title("Q3 Sales Data Analysis")
    .resources(List.of(SessionResource.builder()
        .type("file")
        .fileId("file_xxx")
        .mountPath("/uploads/workspace/data.csv")
        .build()))
    .build());
System.out.println(session.getId() + " " + session.getStatus());

Session Page Layout

• Event Panel: Displays the processing steps of the current turn in real time. The dropdown in the upper-left corner filters events by type (All events / User / Agent / Tool / Tool_output / Error / Model / System).

• Right-side Tabs: The Agent, Environment, and Credentials tabs show the snapshotted configuration of the current session.

• Input Area: Enter a message in the input box at the bottom and click Send to submit. While processing, click Interrupt to stop the current turn.

Mount Files

When creating a session, you can mount uploaded files using the resources field. The agent reads and writes them by mount_path during tool calls. For details, see File Upload and Mounting.

Archive and Delete

Sessions support two operations: archive and delete.

• Archive: The status changes to terminated (terminal state). The event history is retained and queryable. Suitable for completed sessions.

• Delete: Hard delete. Session metadata, event history, and internally copied resources are all permanently removed and cannot be recovered. Use archive instead if you want to preserve the event history.