Start a Session - 阿里云百炼 Agent Studio

Sessions

A session represents a single execution instance of an agent, supporting multi-turn conversations, tool invocations, and state changes. In the console, click New Session to create sessions for debugging; in production environments, sessions are created and driven programmatically via API—see the Session API for details.

Creating a Session

On the agent detail page, click New Session, select a runtime environment (required), and then proceed to the session page. At creation time, the server captures a snapshot of the agent’s current configuration; subsequent edits to the agent do not affect existing sessions. When creating a session via API, you must specify both the agent and the runtime environment—the server automatically snapshots the agent’s configuration at that moment. For full parameter definitions and response fields, refer to the Create Session API.

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": "/workspace/data.csv"}
    ]
  }'

Session Page Layout

Event Panel: Displays the current turn’s processing flow in real time. Use the dropdown in the top-left corner to filter events by type (All events / User / Agent / Tool / Tool_output / Error / Model / System).
Right-side Tabs: Three tabs—Agent, Environment, and Credentials—each showing the corresponding configuration snapshot for the current session.
Input Area: Enter messages in the bottom input field and click Send to submit. While processing, click Interrupt to stop the current turn.

Mounting Files

Upload new files or mount existing ones in the Resources section of the session page. The agent can read from and write to these files during tool calls using the specified mount_path. See File Upload & Mounting for details. You can also mount, list, and unmount resources dynamically at runtime via the API—see Mount Session Resource.

Archiving and Deleting Sessions

Sessions support two lifecycle operations:

Archiving: Changes the session status to terminated (a terminal state), while preserving its event history for future reference. Recommended for completed sessions.
Deletion: Permanently removes the session—including metadata, event history, and internally copied resources—with no possibility of recovery. Use archiving instead if you wish to retain event history.

Next Steps

Manage Sessions: Learn about the session state machine, tool invocation flow, and archiving/deletion behavior.
Session Event Stream (SSE): Understand all event types and how to subscribe via Server-Sent Events (SSE).
Session API: Use the API to create sessions, send messages, and subscribe to event streams.

​Sessions

​Creating a Session

​Session Page Layout

​Mounting Files